Configuration reference
This page is a complete list of Aerospike Database configuration options. A carefully planned and optimized database configuration is essential to running a successful Aerospike deployment. To learn more, see the main database configuration documentation. The Aerospike configuration file is located by default at /etc/aerospike/aerospike.conf.
Be sure to review the dynamic runtime configuration examples.
Logging
A Linux console log sink. A systemd Linux OS captures the log stream from STDERR to journald. In SysV Linux the default console sink is /tmp/aerospike-console.<pid>.
A console log sink subcontext can have one or more context configuration parameters.
The logging contexts and the severity levels associated with a specified log sink can be obtained with an info command:
asinfo -v log/0Returns the values associated with the first log sink defined in logging:
misc:CRITICAL;alloc:CRITICAL;arenax:CRITICAL;hardware:CRITICAL;jem:CRITICAL;msg:CRITICAL;...To list the log sinks:
asinfo -v log/0Prior to Aerospike Database 4.9, the default value was any info, for an INFO severity level.
Consult the list of logging contexts. For common log messages, organized by logging context, see Server Log Message Reference.
Example:
logging { console { context any info }}Specifies the context and severity level with which to filter a log stream. You can use a combination of contexts and logging levels. See Dynamically changing the severity level.
The logging contexts and the severity levels associated with a specified log sink can be obtained with an info command:
asinfo -v log/0Returns the values associated with the first log sink defined in logging:
misc:CRITICAL;alloc:CRITICAL;arenax:CRITICAL;hardware:CRITICAL;jem:CRITICAL;msg:CRITICAL;...To list the log sinks:
asinfo -v log/0Prior to Aerospike Database 4.9, the default value was any info, for an INFO severity level.
Consult the list of logging contexts. For common log messages, organized by logging context, see Server Log Message Reference.
Specifies the standard syslog facility name to be used when logging to a syslog socket.
Defines a file log sink (not to be confused with
file from the namespace configuration context.) You can define multiple log sinks for various contexts.
A file log sink subcontext can have one or more context configuration parameters.
Context specifies the logging context and severity level used to filter messages in the log stream. You can use a combination of contexts and
severity levels.
Example:
logging { file /var/log/aerospike/aerospike.log { context any critical }
file /var/log/aerospike/udf_debug.log { context any critical context udf debug }}Specifies a valid path to a syslog compatible Unix domain socket.
Defines a pre-existing syslog-compatible Unix domain socket as a log sink.
A syslog log sink subcontext can have the following configuration parameters: facility, tag, path, and one or more context.
Context specifies the logging context and severity level used to filter messages in the log stream. You can use a combination of contexts and
severity levels.
Example:
logging { syslog { facility local0 tag asd-query context any critical context query info }}Specifies a syslog tag to be used for labeling messages going to the socket log sink.
Mod lua
Whether to enable caching of Lua states for each registered Lua module, to benefit performance.
Namespace
Enables operator to dynamically designate a particular rack-id to hold all master partition copies. For active-rack to take effect, all nodes must agree on the same active rack, and the number of racks must be less than or equal to the configured replication-factor. Also, active-rack = 0 (default) disables the feature. This means that you can’t designate rack_id 0 as the active rack. Changing the rack_id on all nodes with rack_id 0 to a new value that is distinct from any other racks, does not cause any migrations.
Example:
Enable using aerospike.conf
namespace ns-name {...rack-id Xactive-rack Y #Y may be the same as X"...In Aerospike 5.0, this parameter was replaced by reject-non-xdr-writes.
Parameter to control the writes done by a non-XDR client. Setting it to false will disallow all
the writes from a non-XDR client (any regular client library). This parameter is useful to control accidental writes by a
non-XDR client to a namespace when it is not expected, and can be used for namespaces taking writes exclusively from XDR client(s). When
set to false, error code 10 will be returned and will tick the fail_xdr_forbidden
statistic.
Example: Set allow-nonxdr-writes to false:
asinfo -v "set-config:context=namespace;id=namespaceName;allow-nonxdr-writes=false"Aerospike strongly recommends that you do not change this setting. See the Warning in “Additional Information” below.
If data expiration and eviction are disabled (nsup-period set to 0, the default), setting
allow-ttl-without-nsup to true allows writes of records with a non-zero TTL (which would otherwise will not be allowed).
Example:
Set allow-ttl-without-nsup to true:
asinfo -v "set-config:context=namespace;namespace=namespaceName;allow-ttl-without-nsup=true"In Aerospike 5.0, this parameter was replaced by reject-xdr-writes.
Parameter to control whether to accept write transactions originating from an XDR client. Setting it to false will disallow all
the writes from an XDR client (at a destination cluster) and will only allow non XDR clients to write transactions.
This parameter is useful to control accidental writes by an XDR client. When
set to false, error code 10 will be returned, disallowed writes will not be relogged by XDR and will tick the fail_xdr_forbidden
statistic on the remote (destination) cluster.
Example: Set allow-xdr-writes to true:
asinfo -v "set-config:context=namespace;id=namespaceName;allow-xdr-writes=true"Selectively revives partitions in SC namespaces at startup. The revive command forces a partition to go “live” and start accepting transactions providing the operations team an opportunity to take remediation actions when a series of events may have caused data loss.
The auto-revive feature is for deployments that don’t have any remediation options available and/or want to minimize downtime due to potential data loss. The auto-revive feature is selective; it will only revive partitions that have data, whereas the revive command will also revive partitions that have been totally lost (such as wiped disks on multiple nodes).
In a case where two nodes in a strong-consistency replication-factor 2 namespace were shut down uncleanly, using SIGKILL for instance, the cluster detects possible lost data resulting in dead partitions. Without auto-revive, the operator follows remediation steps, including issuing the revive command to the cluster.
With the auto-revive feature enabled, the cluster ignores this potential data loss event and continues to allow client traffic. However, if the two nodes in this scenario had their data wiped, then the auto-revive feature would not restore the affected partitions and would still require that the operator take remediation steps, including issuing the revive command.
Example configuration:
namespace test {
...
auto-revive true
...Maximum records per second (RPS) allowed for a background query such as a UDF or ops query. If necessary, the query is throttled so as to not exceed this RPS value. Value range: 1-1000000. If the query must read the records from device to do any filtering (bin level filters), or if it reads them from device with no filtering, the throttle is applied to the rate at which records are read. If the records are stored in memory, or can be filtered based on index metadata, the throttle is applied to the rate at which the records are returned to the client.
Example: Set background-query-max-rps to 6000:
asinfo -v "set-config:context=namespace;id=namespaceName;background-query-max-rps=6000"Maximum records per second (RPS) allowed for a background scan such as UDF or ops scan. If necessary, the scan is throttled so as to not exceed this RPS value. Value range: 1-1000000. If the scan must read the records from device to do any fbin level filters, or if it reads them from device with no filtering, the throttle is applied to the rate at which records are read. If the records are stored in memory,or can be filtered based on index metadata, the throttle is applied to the rate at which the records are returned to the client.
Example: Set background-scan-max-rps to 6000:
asinfo -v "set-config:context=namespace;id=namespaceName;background-scan-max-rps=6000"Controls whether replica writes are placed into the post-write queue.
Setting this true could improve performance in certain situations.
It cannot be set true for data-in-memory namespaces.
Setting this to true will cause cold start to ignore existing data on drives and start as if empty. Does not affect fast restart.
Minimum size, in bytes, of a disk flush when
commit-to-device
is enabled.
Has to be a power of 2. Can be set as 4K. The default value of 0 will auto-detect the smallest size possible for the device.
It is usually recommended to keep the default for this configuration.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB).
Wait for write to flush to disk or pmem before acknowledging the client. Only
available for
strong-consistency
enabled namespaces. If using storage-engine device file storage with commit-to-device set
true, it may be useful to set
read-page-cache
true.
This parameter sets an acceleration level for LZ4 storage compression. Lower values specify lower acceleration, resulting in higher compression levels and greater CPU usage. The allowable range is 1 - 65537, with a default value of 1, indicating no acceleration and maximum compression. In practice, values greater than 400 result in no compression.
Only applicable when compression is set to lz4.
Example:
Set compression-acceleration dynamically to 50:
asinfo -v 'set-config:context=namespace;namespace=nameSpaceName;compression-acceleration=50'Note: This is compression-level for storage-engine.
For XDR compression-level for dc namespace, scroll down to compression-level in the XDR context.
Allowable range: 1-9
The compression level to use with ZSTD compression. Controls the trade-off between compression speed and compression ratio.
A higher level value, for example 9, means more efficient but slower compression.
A lower level value, for example 1, means less efficient but faster compression.
This item should only be specified when using compression zstd.
In Aerospike Database prior to 4.6.x, if this setting has never been specified when using compression zstd,
a default flag of 0 is displayed and the compression-level of 9 is used.
In Aerospike Database 4.6.x or later, if this setting has never been specified when using compression zstd,
a default flag of 9 is displayed and the compression-level of 9 is used.
The compression configuration directives
belong to a namespace’s storage-engine section.
Example: Set the namespace’s compression-level to 1:
asinfo -v 'set-config:context=namespace;namespace=namespaceName;compression-level=1'Options: none, lz4, snappy, zstd.
Use of compression requires the asdb-compression feature-key to be enabled in the feature-key-file, and specifies
the algorithm used to compress records on SSD or pmem storage files.
For zstd the compression-level can be specified.
As of Database 4.5.3.2, the flat storage format is also used as wire format for replication, migration and duplicate resolution,
providing potential significant network bandwidth and CPU usage when using compression.
Example: Set the namespace’s compression algorithm to zstd:
asinfo -v 'set-config:context=namespace;namespace=namespaceName;compression=zstd'Set to either last-update-time or generation
generation - Resolve records conflict based on the record’s generation number.
last-update-time - Resolve records conflict based on the record’s last update time.
This parameter does not impact the cold restart conflict resolution policy. Cold restart conflict resolution always uses the last-update-time.
For records created prior to Database 3.8.3, the cold start resolution falls back to generation.
Also, in case of equal last-update-time, the tie is broken by generation.
Generation value could wrap back to 1 on a record with a high update rate (Max of 65K generations per record).
In AP mode (strong-consistency set to false) network partitions
could cause updates to be lost when the cluster re-forms itself. Where it is more important to preserve
the history of a record (such as lists or maps with items appended on each update) generation may be more
suitable. Where the last update is more important to preserve, last-update-time would be more
suitable.
Example:
Set conflict-resolution-policy to last-update-time:
asinfo -v "set-config:context=namespace;id=namespaceName;conflict-resolution-policy=last-update-time"Not configurable when strong-consistency is enabled (neither
generation nor only last-update-time is in such case but a combination of last-update-time and regime).
conflict-resolve-writes is required for the XDR bin convergence feature. If this is enabled, the bin-level LUT is
stored and determines the winner. If this is disabled, the bin-level LUT is discarded and
the latest write cannot be determined. conflict-resolve-writes cannot be enabled if single-bin is enabled for the namespace.
See bin convergence for more information.
Example: Set conflict-resolve-writes dynamically:
asinfo -v "set-config:context=namespace;namespace=namespaceName;conflict-resolve-writes=true"Optimization in single bin case, will only allow integer or float stored in index
space. Can only be used when storage-engine is device
and single-bin is true.
Keep a copy of all data in memory always.
Specifies the total amount of memory allocated for the namespace’s eight virtual devices. This size is split into 8 stripes. The stripes appear individually in the logs.
Minimum: 128 MiB. Maximum: 2 TiB. data-size is required, and only allowed, with storage-engine set to memory with no persistence to device or file.
Stop the asd service before modifying the data-size value. Clear the shared memory segments before starting asd again. For more information, see How to change data-size configuration in a running cluster.
Supports the following suffixes:
- K Kibibyte (KiB)
- M Mebibyte (MiB)
- G Gibibyte (GiB)
- T Tebibyte (TiB)
- P Pebibyte (PiB)
Example:
data-size 500GFor the namespace configuration, 0 means reads never have a read touch a record to extend its TTL. Values 1-100 specify a percentage of the most recent record expiration time, so that a read within this interval of the record’s end of life will generate a touch. The touch uses the previous record TTL to extend the record’s life.
For the set configuration, 0 means use the namespace value. A set-level configuration can explicitly override the default namespace value: -1 means reads never touch a record. Values 1-100 are the same as the namespace configuration.
Clients may also send a read-touch TTL percent: 0 instructs the server to use its configuration. Other values override the server configuration. -1 means reads never touch a record, values 1-100 are the same as the server configurations.
Queries, UDFs and writes which do not change records do not behave like reads for this feature.
Default time-to-live (in seconds) for a record from the time of creation
or last update. The record will expire in the system beyond this time. default-ttl has an upper limit
of ten years (3650D).
A default-ttl specified at the set level overrides a default-ttl specified at the namespace level.
Supports the following suffixes:
- S Second
- M Minute
- H Hour
- D Day
Example:
set test-set { ... default-ttl 60D}Set default-ttl to 30 days dynamically:
asinfo -v "set-config:context=namespace;namespace=namespaceName;set=test-set;default-ttl=30D"Can be overridden using API. 0 means lives forever.
Blocks that are less filled in percentage than the specified limit will be marked as eligible to be defragmented.
Also, wblocks that are in the post-write-queue (before Database 7.1) or post-write-cache (Database 7.1 and later) are not eligible
to be defragmented. Therefore the post-write-queue should be kept small compared to the overall
device size as the size allocated to the post-write-queue will not be defragmented.
Example:
Set defrag-lwm-pct to 55:
asinfo -v "set-config:context=namespace;id=namespaceName;defrag-lwm-pct=55"Don’t defrag unless the queue has this many eligible wblocks.
Example: Set defrag-queue-min to 10:
asinfo -v "set-config:context=namespace;id=namespaceName;defrag-queue-min=10"Number of microseconds to sleep after each wblock is defragmented. In Database 7.1 and later, this configuration controls the time to sleep between reading segments of size flush-size.
Example: Set defrag-sleep to 500:
asinfo -v "set-config:context=namespace;id=namespaceName;defrag-sleep=500"Server needs at least specified amount (in percentage) of free space at startup.
The value must be an integer and the allowable range is 0 to 99.
Prior to Database 5.7, the default value is 10 and the allowable range is 1 to 99.
Raw device used to store the namespace.
Example: Persist to two devices
device /dev/sdbdevice /dev/sdcPersist to device and shadow device
device /dev/nvme0n1 /dev/sdbRelevant only for file storage. If using storage-engine pmem, relevant only for shadow file storage.
If direct-files is set true, then
the odirect and odsync flags are enabled for file IO. This means
write-buffers are synchronously written all the way through to the
devices under the file system.
If using storage-engine device with
data-in-memory
set false, then it may be useful
to set
read-page-cache
true. See the Buffering and Caching in Aerospike
article for further details.
If true, disables eviction that may occur at cold start for this namespace only.
true protects the set from evictions. Setting this parameter does not affect the TTL of records within the set.
Records can have a TTL and will expire as normal.
This parameter is unanimous but not validated for unanimity across all nodes by the server. You must ensure that if you change it dynamically, all node configuration files are edited to ensure future restarts of any node stay unanimous for this parameter. If adding new nodes to the cluster, the configuration file must be correctly configured before the node joins the cluster to maintain unanimous configuration of this parameter.
Example: Set disable-eviction on the set dynamically:
Admin+> manage config namespace test set testset param disable-eviction to true"Set disable-eviction under the namespace definition in aerospike.conf:
set set1 { disable-eviction true } set set2 { disable-eviction true } set test { disable-eviction true }Controls whether transactions can be used by applications. Blocks new transactions with writes by blocking monitor creates. Can be used dynamically to let an XDR destination settle to a transaction-consistent state.
If disable-odsync is set true, then
the Linux O_DSYNC I/O flag is set false (even if, for files,
direct-files is
set true). Disabling O_DSYNC would likely improve performance
at a cost of relaxed durability guarantees.
See the Buffering and Caching in Aerospike
article for further details.
Note: disable-odsync and
commit-to-device
cannot be both set to true. Setting both to true will prevent the server from starting
given their opposition in the durability/performance trade off.
Disables write duplicate resolution for the namespace. Only applicable for AP namespaces (non strong-consistency enabled). Write duplicate resolution is needed when recovering from node maintenance/failure or a partition. In such situations, a node will chase different versions of a record prior to applying the update. This only applies during migrations when multiple versions of a given partition may exist.
For use with available and partition-tolerant (AP) namespaces only. When set to true, attempted non-durable deletes return error code 22 (forbidden).
Enabling this configuration will error out a record write attempt if done without a set name.
By default, Aerospike allows writes with and without a set name. If a record is sent without a setname, it gets assigned a ‘null’ set.
If this configuration is enabled, any record without a setname will not be allowed to be written to the namespace. An ‘Error Code 4 AEROSPIKE_ERR_REQUEST_INVALID’ will be sent back to the client.
Additionally, a warning will be logged to the server with the message null/empty set name not allowed for namespace.
Note: Ensure that the configuration is set uniformly on all nodes. If that is not done, it would lead to situations when one node would allow such null-set records and others would not.
Example: Dynamically enabling this configuration:
asinfo -v "set-config:context=namespace;id=namespaceName;disallow-null-setname=true"Earth’s radius in meters, since the workspace here is the complete earth.
Enable histograms for batch sub transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-batch-sub to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-batch-sub=true'Enable histograms for ops sub transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-ops-sub to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-ops-sub=true'Enable histograms for read transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-read to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-read=true'Enable histograms for storage access. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-storage to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-storage=true'Enable histograms for udf sub transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-udf-sub to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-udf-sub=true'Enable histograms for udf transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-udf to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-udf=true'Enable histograms for write transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-write to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-benchmarks-write=true'Enable histograms for proxy transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-hist-proxy to true:
asinfo -v 'set-config:context=namespace;id=<namespaceName>;enable-hist-proxy=true'Setting this to true maintains an index specific to the set, which is used for scans of the set. Using such an index improves performance of scans of the set if the set is very small compared to the size of its namespace. See Set Indexes for further details.
Example: Enable a set-specific index within the namespace definition in the configuration file:
set setName { enable-index true }Dynamically enable a set-specific index:
asadm -e "enable; manage config namespace namespaceName set setName param enable-index to true"To check the enable-index configuration for a specific set (example run against the sandbox):
Admin> show stat sets like enable~~~~~~~~~~sandbox ufodata Set Statistics (2024-10-15 22:15:38 UTC)~~~~~~~~~~Node |jupyter-aerospike-2dexamp-2dctive-2dnotebooks-2duh4zco0l:3000enable-index|falseNumber of rows: 2This controls, at the namespace level, whether digest log entries are being written to the digest log.
This therefore practically controls whether records are being shipped through XDR globally, assuming
DCs are configured and available, xdr-shipping-enabled
is kept at its default value (true) and the enable-xdr configuration is set to true at the
XDR stanza level.
Configured DCs that are linked to namespaces will be connected to independently of the value of this setting. To
prevent the connections from being made, you will need to either a) remove all seed
nodes from the datacenter definition, or b) remove the
datacenter from all namespace definitions, or do so
dynamically to break existing connections.
Example: Enable XDR dynamically on the namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;enable-xdr=true"Specifies a user-supplied encryption key and activates storage encryption. For more information see Configuring Encryption at Rest.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/encryption-key-file- Read from the filesystem (thefile:prefix is optional).env-b64:ENCKEY- Read from the named environment variable (Database 5.3+).vault:encryption-key- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:EncryptionKey- fetched using Aerospike Secret Agent (Database 6.4+).
Example: Enable encryption at rest for namespace test:
namespace test { ... storage-engine device { device /dev/sda1 ... encryption-key-file /etc/aerospike/key.dat } ...}Enable encryption at rest for namespace test, with the encryption key secret fetched from HashiCorp Vault:
namespace test { ... storage-engine device { device /dev/sda1 ... encryption-key-file vault:encryption-key } ...}Works together with the encryption-key-file when rotating the storage encryption key. For more information see Configuring Encryption at Rest.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/old-encryption-key-file- Read from the filesystem (thefile:prefix is optional).env-b64:OLDENCKEY- Read from the named environment variable (Database 5.3+).vault:old-encryption-key- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:OldEncryptionKey- fetched using Aerospike Secret Agent (Database 6.4+).
Example: Rotate the encryption keys for namespace test:
namespace test { ...
storage-engine device { device /dev/sda1 ... encryption-key-file key.dat encryption-old-key-file /etc/aerospike/old-key.dat } ...}Fetch the encryption keys for namespace test from HashiCorp Vault and rotate them:
namespace test { ... storage-engine device { device /dev/sda1 ... encryption-key-file vault:encryption-key encryption-old-key-file vault:old-encryption-key } ...}Specifies the algorithm used to generate the data encryption key - aes-128 or aes-256.
For more information see Configuring Encryption at Rest.
Number of histogram buckets used for evictions. Must be between 100 and 10,000,000. Takes effect on the next eviction round.
Example: Set evict-hist-buckets to 200000:
asinfo -v "set-config:context=namespace;id=namespaceName;evict-hist-buckets=200000"Aerospike monitors the total amount of index memory in use. If configured nonzero, and indexes-memory-budget is also configured nonzero, and the combined size of the RAM indexes exceeds the configured percentage of the budget, this begins evicting records from the namespace. Default is 0, which means no budget. Range is 0-100.
Data is evicted if the mount’s utilization is greater than this specified percentage
(of mounts-budget).
Setting this parameter to zero (which is the default) disables this threshold.
Aerospike monitors the total amount of system memory in use, including non-Aerospike memory usage. If the amount of system memory in use out of the total system memory becomes greater than the specified percentage, Aerospike begins evicting records from the namespace. Default is 0 which mean no eviction will be done.
When using evict-sys-memory-pct, as opposed to other eviction thresholds where data storage and index allocation grow gradually to reach the threshold, an external process can rapidly exceed the eviction threshold and cause records to be deleted unexpectedly.
Example:
Designate a evict-sys-memory-pct value within a namespace definition in the configuration file:
evict-sys-memory-pct 75Dynamically enable a evict-sys-memory-pct value:
asinfo -v "set-config:context=namespace;id=namespaceName;evict-sys-memory-pct=75"Maximum 1/10th percentage of objects to be deleted during each iteration of eviction.
Example: Set evict-tenths-pct to 10:
asinfo -v "set-config:context=namespace;id=namespaceName;evict-tenths-pct=10"Data is evicted if the storage utilization is greater than this specified percentage.
Setting this parameter to zero disables this threshold.
Example:
Set evict-used-pct to 60 using asadm:
Admin+> manage config namespace NAMESPACE_NAME storage-engine param evict-used-pct to 60Data file path on rotational disk (using a file system) or pmem (starting with Database 4.8). As of 4.3.0.2, the file may include an optional ‘shadow file’ as a second argument.
Example: Persist to two files:
file /mnt/disk1/myfile1.datfile /mnt/disk2/myfile2.datPersist to two files (pmem):
file /mnt/pmem/myfile1.datfile /mnt/pmem/myfile2.datPersist file with a shadow file:
file /mnt/pmem1/rw_file.dat /mnt/sdb1/shadow_file.datfile /mnt/nvme0n1/rw_file.dat /mnt/sdb1/shadow_file.datMaximum size for each file storage defined in this namespace. File header is 8M. Filesize must be a multiple of 8M and greater than 8M or server will not start.
filesize is required to be set explicitly when the namespace is configured to use files.
Supports the following suffixes:
- K Kibibyte (KiB)
- M Mebibyte (MiB)
- G Gibibyte (GiB)
- T Tebibyte (TiB)
- P Pebibyte (PiB)
Example:
filesize 500GConfigures the maximum amount of time that a Streaming Write Buffer (SWB) can go without being written to device or pmem storage file. This only becomes relevant for very low or intermittent write rates, since write buffers do get written to device (or pmem) when full. In general, changing this should not be necessary. Minimum 0: Don’t do partial flush. Maximum: No limit. See the Buffering and Caching in Aerospike article for further details.
Example: Set flush-max-ms to 500:
asinfo -v "set-config:context=namespace;id=namespaceName;flush-max-ms=500"Specifies the size of write units for streaming write buffer (SWB) flushes. Must be a power of 2, from 4KiB to 8MiB (The configuration accepts the following values: 4K, 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M). The flush-size can be configured to match the write-block-size used prior to Database 7.1. For most SSDs the ideal value may be 128KiB. Can be modified dynamically up or down.
Governs both partial writes and full writes, and can completely solve the problem of excess device I/O in workloads dominated by partial writes. For such workloads, configure flush-size to be relatively small, 128KiB or even less.
Data is evicted if the disk utilization is greater than this specified percentage.
Setting this parameter to zero (which is the default) disables this threshold.
Example:
Set high-water-disk-pct to 60:
asinfo -v "set-config:context=namespace;id=namespaceName;high-water-disk-pct=60"Data will be evicted if the memory utilization is greater than this
specified percentage.
Setting this parameter to zero (which is the default) disables this threshold.
Example: Set high-water-memory-pct to 60:
asinfo -v "set-config:context=namespace;id=namespaceName;high-water-memory-pct=60"For namespaces in
storage-engine memory,
set the ignore-migrate-fill-delay parameter to true effectively sets it to 0 and overrides migrate-fill-delay,
. migrate-fill-delay imposes a time lag
before the “fill” migration to the cluster nodes that do not normally function as replicas.
A time lag is useful for a cluster where some of the namespaces use storage-engine memory and are not persisted. This situation requires migrations to immediately repopulate a node that won’t have any other source for such repopulation when it restarts.
ignore-migrate-fill-delay is not useful for strong-consistency-enabled
namespaces, even with non-persisted namespaces because the roster dictates which node would normally hold a given partition,
.
For more information, see Delaying “Fill” Migrations.
Example:
To disregard the migrate-fill-delay setting and cause nameSpaceName to begin “fill” migration:
asinfo -v "set-config:context=namespace;id=nameSpaceName;ignore-migrate-fill-delay=true".
Configuration used to size the primary index arena(s).
Configuration has to be a power of 2. Lower limit is 128M and upper limit of 1G prior to Database 4.2.0.2, 16G for Database 4.2.0.2 and later. This setting will change the size of each of the 2048 (EE or SE) or 256 (CE) possible arena stages and require a coldstart.
Supported size notation is no-suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB), P for Pebibyte (PiB).
Options: pmem, shmem, flash
If pmem, the primary index is stored in persistent memory (e.g., Intel Optane DC Persistent Memory). If shmem, the primary index is stored in Linux shared memory. If flash, the primary index is stored in a block storage device (typically NVMe SSD). For information about shmem and flash, see Configuring the primary index.
In all three options, the node is able to fast-restart.
If pmem or flash the primary index is also preserved across reboots of the node’s OS, allowing for fast-restart after the host machine reboots.
Setting to flash requires the asdb-flash-index feature-key, pmem requires the asdb-pmem feature-key to be enabled in the feature-key-file.
In Database 7.0, flash does not work with storage-engine pmem or storage-engine memory.
Maximum amount of total memory for the indexes on this namespace. If configured nonzero, and in conjunction with evict-indexes-memory-pct, it will trigger stop-writes if the combined size of the RAM indexes (primary, secondary, and set indexes) exceeds the budget.
In Database 6.3 and later, you have the option to run short queries inline, which means that one service thread executes the query, bypassing the query monitor. Ensure that queries designated as short queries return a small number of records, otherwise they might time out. This configuration is useful in cases where short query latency is a priority, and you are willing to potentially sacrifice some single-record transaction latency, as the service threads will be used for both.
See Query features and short and long queries for more information.
If specified, then only cells where (level - min-level) is a multiple of “level-mod” will be used (default 1). This effectively allows the branching factor of the S2 Cell Id hierarchy to be increased. Currently the only parameter values allowed are 1, 2, or 3, corresponding to branching factors of 4, 16, and 64 respectively.
Sets the maximum desired number of cells in the approximation. The maximum number of cells allowed is 256.
Example: Changing max-cells dynamically:
asinfo -v "set-config:context=namespace;id=namespacename;geo2dsphere-within-max-cells=24"Maximum depth (number of subdivisions) to use for a single cell. This defines the minimum cell size to be used.
The allowable range for this parameter is 0 to 30. At level 20 the cell size varies from 46.4 to 97.3 square meters.
Example: Changing max-level dynamically:
asinfo -v "set-config:context=namespace;id=namespacename;geo2dsphere-within-max-level=25"Specifies the maximum allowed record size in bytes up to 8MiB. The default is 1MiB. Any write attempt that breaches max-record-size fails with a code 13 error,
fail_record_too_big.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB).
Example: Changing max-record-size dynamically:
asinfo -v "set-config:context=namespace;id=ns1;max-record-size=256K"In asadm the equivalent is:
Admin> enableAdmin+> manage config namespace ns1 param max-record-size to 256K- Prior to 7.1, the default is 0.
Disallow writes except deletes, replica writes and migration writes, when
the ratio of device_used_bytes to device_total_bytes (with storage-engine device) or the ratio of pmem_used_bytes to pmem_total_bytes (with storage-engine pmem) for the namespace is greater than this specified percentage.
Writes are disallowed when the memory utilization for the namespace reached the
configured stop-writes-pct or when the node’s system memory utilization reached the configured stop-writes-sys-memory-pct.
Example:
Designate a max-used-pct value within a namespace definition in the configuration file:
max-used-pct 90Dynamically enable a max-used-pct value:
asinfo -v "set-config:context=namespace;id=namespaceName;max-used-pct=90"Number of bytes of pending write blocks that the system is allowed to keep before failing writes. The write cache implements a circuit-breaker to throttle excessive writes. Should be multiple of write-block-size.
While max-write-cache has no maximum permitted value, Aerospike recommends a maximum value of 2047M. Click ‘Show Additional Information’ for more details.
Example - How write cache is calculated
The write cache size is the number of devices for the namespace on the node, multiplied by the value of max-write-cache. The cache for each device
must be accounted for in the total sizing calculation.
Each device has its own write queue (write-q). Assume the following:
- a 3-node cluster with 1 namespace and 4 devices for that namespace on each node (12 total across the cluster)
max-write-cacheis set at the default 64MiB and the write-blocks are always 8MiB. When the sum of all pending blocks across the 4 write queues breaches 256MiB (64MiB x 4), thewrite fail: queue too deep:error and Error Code 18: Device overload are thrown.
The write cache does not have to be the same size on each of the 4 devices in this example. Each could have 64MiB (or 8 blocks) or 1 of could have 256MiB (or 32 blocks) and the other three are keeping up and are at 0.
If you configure max-write-cache to 128MiB and have 10 devices on the namespace on each node, you need to account for potentially
using up 128MiB x 10 = 1280MiB of RAM in case you go all the way to that value.
Tip:
When the queue grows beyond the configured limit and device overload errors appear you can dynamically increase the max-write-cache
limit with the following example command.
asinfo -v 'set-config:context=namespace;id=namespaceName;max-write-cache=128M'For more details, see the Log Reference and Resilience.
Starting with Database 7.0, a namespace that stores its data in memory, pre-allocates the memory used for data storage, so the indexes are the main consumers of unallocated memory. In this case, replace memory-size with indexes-memory-budget, which declares the maximum amount of memory that the namespace can use for all indexes combined (primary, secondary and set indexes).
In versions prior to Database 7.0, memory-size controls the amount of memory used by the namespace, including the indexes and any data in stored memory.
Cannot be reduced by more than 50% of previously set value.
See Capacity Planning for namespace sizing details.
Prior to 4.3.0.2, the default value was 4GiB. As of 4.3.0.2, memory-size is required to be explicitly configured, with a minimum of 1MiB.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB).
Example:
memory-size 10GSet memory-size to 12G dynamically:
asinfo -v "set-config:context=namespace;id=namespaceName;memory-size=12G"Number between 1 and 10 which determines the order namespaces are to be processed when migrating. Namespaces are processed in ascending order (lowest to highest) according to this configuration.
Example: Set migrate-order to 1:
asinfo -v "set-config:context=namespace;id=namespaceName;migrate-order=1"How long to wait for success, in milliseconds, before retrying a
migration related transaction. In Database 3.10.1,
even though migrate-retransmit-ms is honored and set to 5000ms,
it cannot be retrieved through the info protocol and cannot be set.
Example: Set migrate-retransmit-ms to 2500:
asinfo -v "set-config:context=namespace;id=namespaceName;migrate-retransmit-ms=2500"If true, skips writing a record locally during a migration if the record fails validation.
Use this setting only in consultation with Aerospike Support, and only if you are experiencing persistent issues with drive firmware or hardware. Work with your firmware or drive manufacturer to resolve any data integrity issues.
Skipped record count available in migrate_records_unreadable.
Number of microseconds to sleep after each record migration. This parameter can be decreased to 0 in order to speed up migrations. See manage migrations for further details.
Example: Set migrate-sleep to 0:
asinfo -v "set-config:context=namespace;id=namespaceName;migrate-sleep=0"Disallow writes except deletes, replica writes and migration writes when
device_available_pct on one of
the devices or pmem files configured for the namespace is below this specified percentage.
Minimum depth (number of subdivisions) to use for a single cell. This defines the maximum cell size to be used.
The allowable range for this parameter is 0 to 30. At level 1 the cell size is 21,252,753 square kilometers.
Example: Changing min-level dynamically:
asinfo -v "set-config:context=namespace;id=namespacename;geo2dsphere-within-min-level=5"Path to the mount directory, typically on NVMe SSD. There may be more than one mount per namespace: in Database 7.0 maximum is 32, pre-7.0 maximum is 16.
Although not recommended, a mount may be shared with other namespaces.
For sizing details when using index-type flash,
see the Capacity Planning page.
When using index-type pmem or sindex-type pmem with
auto-pin numa, configured mounts that are not
on the local NUMA node are ignored. Therefore, different instances of Aerospike server running on different NUMA
nodes may share the same configured mounts without the operator needing to determine which mounts are on which
NUMA nodes.
Maximum amount of total device space for the mount(s) on this namespace. For example, if there are two mount points of 100GiB each,
then mounts-budget should be set to 200GiB. The minimum size is 4GiB and maximum is to not exceed to the total capacity of all
the mount point[s]. This does not prevent sprigs to be allocated beyond the limit,
but rather enforces the eviction of records based on the evict-mounts-pct
configuration which is measured against the index usage (based on the number of records rather than the number of sprigs).
See All Flash capacity sizing for further details.
Required to be explicitly set when using index-type flash
or index-type pmem.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB), P for Pebibyte (PiB).
Data is evicted if the mount’s utilization is greater than this specified percentage
(of mounts-size-limit).
Setting this parameter to zero (the default) disables this threshold.
Maximum amount of total device space for the mount(s) on this namespace. For example, if there are two mount points of 100GiB each,
then mounts-size-limit should be set to 200GiB. The minimum size is 4GiB and maximum is to not exceed to the total capacity of all
mount point[s]. This does not prevent sprigs from being allocated beyond the limit,
but rather enforces the eviction of records based on the mounts-high-water-pct
configuration which is measured against the index usage (based on the number of records rather than the number of sprigs).
See All Flash capacity sizing for further details.
Required to be explicitly set when using index-type flash
or index-type pmem.
Example: Dynamically change mount size limit:
asinfo -v "set-config:context=namespace;id=bar;mounts-size-limit=5368709180"Changing this parameter dynamically does not require a sub-context to be included. Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB), P for Pebibyte (PiB).
The default duration of a transaction, in seconds, if a value isn’t specified by the client. Determines the deadline after which commands are no longer permitted as part of a transaction. Minimum 1, maximum 120, default 10 (in seconds).
Note: this is namespace in the namespace context, not namespace in the XDR context. Search for namespace, and look at the Context heading to make sure you are working with the correct parameter.
Defines a namespace. For more information, see Namespace Configuration.
Example: To define namespace someNameSpaceName:
...namespace someNameSpaceName { ... memory-size 256G replication-factor 2 storage-engine device { ... ... }
}...In Aerospike 5.0, this parameter was replaced by forward.
This parameter provides fine grained control at namespace level to forward writes that
originated from another XDR to the specified destination datacenters (in xdr section).
This parameter is effective when the forward-xdr-writes
in the xdr section is set to false. If the forward-xdr-writes in xdr section is set to true,
all the namespaces will be forwarded irrespective of the namespace-level setting (ns-forward-xdr-writes).
Example: Enable ns-forward-xdr-writes on the namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;ns-forward-xdr-writes=true"The interval (secs) at which the object size histograms, as well as the time-to-live (ttl) histogram, are updated.
Setting nsup-hist-period to a value of 0 will disable these histogram updates.
See the histogram info command for further details
on the object size and ttl histograms.
The interval at which the main expiration/eviction thread (called NSUP, the namespace supervisor) wakes up to process the namespace.
The default value of nsup-period 0 disables the namespace supervisor for the namespace.
By default, the value is in seconds. You can also set this value in minutes, hours, or days, with notation like 1m or 1h or 1d.
For additional discussion, see Namespace Data Retention Configuration.
Example:
Set nsup-period to 600 seconds dynamically for a namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;nsup-period=600"The number of dedicated expiration/eviction threads for NSUP to use when processing the namespace. Must be at least 1, and at most 128.
Example: Set nsup-threads to 3 dynamically for a namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;nsup-threads=3"Configuration to alter the number of secondary index trees that are used for query lookups.
Increasing this configuration reduces depth of sindex trees, and may help secondary index lookups perform better. However, increasing these will also result in memory overheads, so it is recommended to monitor the memory utilization and benchmark when tuning this configuration.
Number of tree sprigs per partition to use. Default value is 256 for Database 4.2 and later. Must be an exact power of 2. Common workloads and use cases would benefit from 4096 or 8192 sprigs. For workloads potentially requiring more (values higher than 32K), Enterprise Edition licensees should contact Aerospike support for guidance. Even if the memory overhead seems acceptable, configuring too many sprigs may not only provide no benefits, but could actually adversely affect a cluster:
-
A sub-cluster would have to accommodate for all the sprigs that were in the larger cluster (except if min-cluster-size has been configured to prevent the formation of such sub-cluster).
-
The memory required would also have to be contiguous (fragmented memory may prevent the allocation of memory).
-
Having too many sprigs on a node could delay shut down and cause an unnecessary cold restart upon the subsequent restart.
Changing this configuration parameter will force a cold start. Providing more trees (sprigs) reduces the number of levels and speeds up the search. It also causes the reduce lock blockage to be broken up (the reduce lock is unlocked between each sprig, and a sprig takes much less time to traverse than a single partition tree).
Example:
A 4-node cluster, replication-factor 2, 2048 partition-tree-sprigs.
For Database 4.2 and later, the per-node namespace memory overhead for sprigs is:
Community Edition: 64K + (8M x 2 + 8B x 2048 x 4096 x 2) / 4 = 64K + 4M + 32M = 36.06MEnterprise Edition: 64K + (8M x 2 + (8B + 5B) x 2048 x 4096 x 2) / 4 = 64K + 4M + 32M + 20M = 56.06MFor releases prior to 4.2, the per-node namespace memory overhead for sprigs is:
Community Edition: 64K + 2.5M + 128M = 130.56MEnterprise Edition: 64K + 2.5M + 128M + 40M = 170.56MThe amount of bytes per-device used to cache the recently written write-blocks of this namespace. Should be a multiple of 8MiB, and has a default value of 256MiB.
The post-write-cache benefits XDR, as all writes are quasi-immediately read to be shipped to the destination cluster(s). The read-page-cache configuration parameter can also help to leverage page cache, and help with latency for read intensive workloads. The namespace cache-hit is reflected in its cache_read_pct statistic.
Also, wblocks in the post-write-cache are not eligible
to be defragmented. Therefore the post-write-cache should be kept small compared to the overall
device size as the size allocated to the post-write-cache will not be defragmented.
Supported size notation is no suffix for bytes, K for KiB, M for MiB, G for GiB.
Example: Set post-write-cache per-device to 512MiB:
asinfo -v 'set-config:context=namespace;id=ns1;post-write-cache=512M'In asadm the equivalent is:
Admin> enableAdmin+> manage config namespace ns1 param post-write-cache to 512MNumber of write-block buffers to keep as cache (per device). Only available for non data-in-memory storage configurations.
Maximum allowed value for Database 4.7 and later is 8192.
See the cache_read_pct value for how much of the read workload
is being served by the post-write queue. XDR use cases should leverage the post-write-queue as writes would
be quasi-immediately read to be shipped to the destination cluster(s). The
read-page-cache configuration parameter can also be considered
to leverage page cache and help with latency for read-intensive workloads.
Also, wblocks in the post-write queue are not eligible
to be defragmented. Therefore the post-write-queue should be kept small compared to the overall
device size as the size allocated to the post-write-queue will not be defragmented.
Example:
Set post-write-queue to 512:
asinfo -v "set-config:context=namespace;id=namespaceName;post-write-queue=512"If true, this namespace will make an effort to distribute partitions evenly to all nodes. Starting with Database 4.7 the default value is true. To achieve uniform-balance, Aerospike must give up some migration performance for this namespace. Time required to complete migrations is only impacted when a node is either permanently added or removed; i.e., the time to complete migrations when a restarted node rejoins the cluster is not impacted.
Has to be followed by a recluster command to be effective.
For strong-consistency enabled namespaces,
uniform-balance is computed for all nodes in the roster - if a
node is offline, the balance will be less uniform (but likely better than without uniform-balance enabled). If
the node is permanently down, or down for an extended duration, the administrator may choose to remove the
offline node from the roster and issue a recluster command to readjust
the partition distribution back to a uniform-balance.
Example:
Enable prefer-uniform-balance on the namespace:
Admin+> asinfo -v "set-config:context=namespace;id=namespaceName;prefer-uniform-balance=true"aero-node1:3000 (10.0.3.41) returned:ok
aero-node2:3000 (10.0.3.224) returned:ok
aero-node4:3000 (10.0.3.196) returned:ok
aero-node3:3000 (10.0.3.149) returned:ok
Admin+> asinfo -v "recluster:"aero-node1:3000 (10.0.3.41) returned:ok
aero-node2:3000 (10.0.3.224) returned:ignored-by-non-principal
aero-node4:3000 (10.0.3.196) returned:ignored-by-non-principal
aero-node3:3000 (10.0.3.149) returned:ignored-by-non-principalDesignates which rack this node should be a part of. rack-id must be an integer between 0 and 1000000. For strong-consistency namespaces, the rack-id configuration is set through the roster itself. See Configure rack awareness in strong consistency mode for more information.
Example:
rack-id 1Set rack-id to 2 dynamically:
asinfo -v "set-config:context=namespace;id=namespaceName;rack-id=2"Set rack-id for multiple nodes at once:
Admin+> asinfo -v "set-config:context=namespace;id=test;rack-id=101" with 192.168.10.2 192.168.10.4 192.168.10.5node2.aerospike.com:3000 (192.168.10.2) returned:oknode4.aerospike.com:3000 (192.168.10.4) returned:oknode5.aerospike.com:3000 (192.168.10.5) returned:okSet rack-id for strong consistency:
Admin+> asinfo -v "roster-set:namespace=test;nodes=BB9070016AE4202@102,BB9060016AE4202@101,BB9050016AE4202@101,BB9040016AE4202@101,BB9020016AE4202@102node2.aerospike.com:3000 (192.168.10.2) returned:ok...Admin+> asinfo -v "recluster:"...When set to a non-default value, overrides the client-specified per-transaction read consistency level for
this namespace. This configuration specifies whether the server is to consult internally the different
versions of a record to determine the most-recent record value when duplicate resolving in an ongoing
migration.
Values: off, one, all.
See the discussion of SC guarantee in
Strong Consistency Mode.
Example: Set read consistency level override to one in the configuration file (skip duplicate resolution):
read-consistency-level-override oneDynamically override clients and set read consistency to one:
asinfo -v "set-config:context=namespace;id=namespaceName;read-consistency-level-override=one"If true, disables the odirect and odsync flags during read
transactions. This allows the OS to leverage page cache and can help
with latencies for some workload types. Should be tested or deployed
on a single node prior to full production roll out. This configuration
should not be set true for namespaces with
data-in-memory
set true. It may be useful to set read-page-cache to true if
using raw devices, or if using file storage with data-in-memory set
false and
direct-files or
commit-to-device
set true. See the Buffering and Caching in Aerospike
article for further details.
Example: Set read-page-cache to true dynamically:
asinfo -v "set-config:context=namespace;id=namespaceName;read-page-cache=true"Parameter to control the writes done by a non-XDR client. Setting it to true disallows writes from a non-XDR client (any regular client library).
This parameter is on the destination or target node in the namespace stanza, not the xdr stanza’s dc’s namespace sub-stanza.
This parameter is useful to control accidental writes
by a non-XDR client to a namespace when it is not expected,
and can be used for namespaces taking writes exclusively from XDR clients.
When set to true, error code 10 will be returned
and will tick the fail_xdr_forbidden statistic.
Example: Namespace stanza on XDR destination:
namespace someNameSpaceName { reject-non-xdr-writes true ...}Set reject-non-xdr-writes to true:
asinfo -v "set-config:context=namespace;id=namespaceName;reject-non-xdr-writes=true"Parameter to control whether to accept write transactions
originating from an XDR client. Setting it to true disallows all
the writes from an XDR client (at a destination cluster)
and allow only non-XDR clients to write transactions.
This parameter is on the destination or target node
in the namespace stanza, not the xdr stanza’s dc’s namespace sub-stanza.
This parameter is useful to control accidental writes by an XDR client.
When set to true, error code 10 will be returned,
disallowed writes will not be relogged by XDR
and will tick the fail_xdr_forbidden
statistic on the remote (destination) cluster.
Example: Namespace stanza on XDR destination:
namespace someNameSpaceName { reject-xdr-writes true ...}Set reject-xdr-writes to true:
asinfo -v "set-config:context=namespace;id=namespaceName;reject-xdr-writes=true"Unanimous configuration, specifies the number of copies of a record (including the master copy) maintained in the entire cluster.
AP namespaces can be dynamically modified, followed by a recluster info command to make the changes take effect. The effective_replication_factor drops automatically if the number of nodes in the cluster is less than the RF. Prior to Database 7.2, the RF factor drops when a node shuts down or crashes, and the remaining nodes are fewer than the RF. In Database 7.2 this will happen as soon as a node is quiesced and there are fewer nodes in the cluster than the RF.
The effective replication factor is 0 for an orphaned node. For example, if a node tries to join a cluster but that node is unable to communicate with every other node in the cluster, the principal node rejects the request and the node marks itself as an orphan.
For SC namespaces, which are configured with strong-consistency set to true, the RF can only be modified statically and unanimously, essentially through a cluster wide shutdown and restart. If the cluster has fewer nodes than the RF, the effective replication factor drops to 0, and the namespace partitions become unavailable.
Example: In Database 6.0 and later, you can set the replication factor dynamically in AP namespaces:
Admin+> manage config namespace test param replication-factor to 3Admin+> manage reclusterThis example uses asadm to change the entire cluster’s replication factor. The asinfo CLI tool only sends commands to one node at a time.
Optional I/O scheduler for non-NVMe drives (SSD or HDD).
Prevent different namespaces’ tomb raids from running concurrently.
Replaced by info command truncate starting with Database 3.12. See the truncate info command for details.
Setting it to true will delete the specified set in the namespace. Resets to false after deletion occurs.
For more information on deleting sets, see Managing Sets
Example: Enable set-delete on the set:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setname;set-delete=true"Setting it to true will protect the set from evictions. Setting this parameter does not affect the TTL of records within the set. Records can have a TTL and will expire as normal.
Example: Enable set-disable-eviction on the set:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setname;set-disable-eviction=true"
/* Setting parameter under namespace definition in a static manner.
set set1 { set-disable-eviction true } set set2 { set-disable-eviction true } set test { set-disable-eviction true }Replaced in Aerospike 5.0 by ship-only-specified-sets
and ignore-set.
Set-specific parameter to enable/disable shipping through XDR.
If set to ‘use-default’, it inherits the behavior from sets-enable-xdr. If set to ‘true’, XDR will ship this set (overriding sets-enable-xdr). If set to ‘false’, XDR will not ship this set (overriding sets-enable-xdr).
Example: Changing set-enable-xdr dynamically:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setname;set-enable-xdr=true"asinfo -v "set-config:context=namespace;id=namespaceName;set=setname;set-enable-xdr=false"How many records may be in this set before the server begins rejecting writes to this set.
This parameter was renamed to stop-writes-count
in Database 5.6.
The set-stop-writes-count parameter will only take effect when the number
of records reaches the threshold configured. Once the threshold is reached,
clients will get Error Code 22 (AEROSPIKE_ERR_FAIL_FORBIDDEN) back.
Example: Dynamically set the count to two thousands:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setname;set-stop-writes-count=2000"Begins a set context, set must be followed by the set name.
Replaced in Aerospike 5.0 by ship-only-specified-sets.
Specifies whether XDR should ship all sets in a namespace or not.
This setting can be overridden at set level by the set-enable-xdr parameter.
Example: Set sets-enable-xdr dynamically to false:
asinfo -v "set-config:context=namespace;id=namespaceName;sets-enable-xdr=true"Configuration used to size the secondary index arena(s).
Configuration has to be a power of 2. Lower limit is 128M and maximum value is 4G. This setting changes the size of each of the 2048 possible arena stages, for all editions (CE/EE/SE).
Supported size notation is no-suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB), P for Pebibyte (PiB).
At startup, build secondary indexes by scanning devices.
If most records in the namespace are in sets with secondary indexes, setting this configuration true
will very likely speed up the secondary index rebuild. Whether this will be faster also depends on
other factors, such as average record size, and number of configured devices. Ultimately, experimentation
is the best way to determine whether to set this configuration or not.
Options: shmem, pmem, flash
If shmem, secondary indexes are stored in Linux shared memory.
If pmem, the secondary indexes are stored in persistent memory (e.g., Intel Optane DC Persistent Memory).
If flash, the secondary indexes are stored in a block storage device (typically NVMe SSD).
In all options, the node is able to fast-restart. If pmem or flash, the secondary indexes are also preserved across reboots of the node’s OS, allowing for fast-restart after the host machine reboots.
Setting to pmem needs the asdb-pmem feature-key, setting to flash requires the asdb-flash-index feature-key to be enabled in the feature-key-file.
For information about shmem, pmem, and flash, see Configuring the secondary index.
Setting it true will disallow multiple bin (columns) for a record.
Maximum number of threads allowed for a single query. Value range: 1-128.
Example: Set single-query-threads to 12:
asinfo -v "set-config:context=namespace;id=namespaceName;single-query-threads=12"Maximum number of threads allowed for a single query. Value range: 1-128.
Example: Set single-scan-threads to 12:
asinfo -v "set-config:context=namespace;id=namespaceName;single-scan-threads=12"Disallow writes except deletes, replica writes and migration writes when
data_avail_pct on one of
the devices or pmem files or memory storage configured for the namespace is below this specified percentage.
How many records may be in this set before the server begins rejecting writes to this set.
The stop-writes-count parameter will only take effect when the number
of records reaches the threshold configured. Once the threshold is reached,
clients will get Error Code 22 (AEROSPIKE_ERR_FAIL_FORBIDDEN) back.
Example:
Configure a set-specific stop-writes-count value within the namespace configuration context:
set setname { stop-writes-count 1000 }Dynamically set the count to two thousand:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setName;stop-writes-count=2000"Disallow writes when memory utilization
(tracked under
memory_used_bytes) is greater than this specified percentage:
- This threshold is checked every 10 seconds.
- Deletes, replica writes, and migration writes are still allowed.
Example: Set stop-writes-pct to 95:
asinfo -v "set-config:context=namespace;id=namespaceName;stop-writes-pct=95"Specifies a maximum limit in bytes for the size of a set. For data-in-memory namespaces, this limit is for memory_data_bytes. For other types of storage, the limit is for device_data_bytes.
After the limit is reached, the server does not allow any additional writes, even those that would decrease the size of a record. There are two ways to get under the stop-writes-size limit: increase or remove the limit, or delete records.
The sets info command outputs the stop-writes-size configuration in bytes, as well as the device_data_bytes or memory_data_bytes set metrics. By comparing those values, a monitoring/management tool can determine if the set is currently unable to accept writes due to a quota violation.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB), G for Gibibyte (GiB), T for Tebibyte (TiB), P for Pebibyte (PiB).
Example:
Configure a set-specific stop-writes-size value within the namespace configuration context:
set setname { stop-writes-size 500M }Dynamically enable a set-specific stop-writes-size value:
asinfo -v "set-config:context=namespace;id=namespaceName;set=setName;stop-writes-size=550M"Aerospike monitors the total amount of system memory in use, including non-Aerospike memory usage. If the amount of system memory in use out of the total system memory becomes greater than the specified percentage, new writes are disallowed.
Example:
Designate a stop-writes-sys-memory-pct value within a namespace definition in the configuration file:
stop-writes-sys-memory-pct 75Dynamically enable a stop-writes-sys-memory-pct value:
asinfo -v "set-config:context=namespace;id=namespaceName;stop-writes-sys-memory-pct=75"Disallow writes except deletes, replica writes and migration writes when
the ratio of data_used_bytes to data_total_bytes for the namespace is greater than this specified percentage.
Example:
Designate a stop-writes-used-pct value within a namespace storage-engine definition in the configuration file:
stop-writes-used-pct 90Dynamically enable a stop-writes-used-pct value:
asinfo -v "set-config:context=namespace;id=namespaceName;stop-writes-used-pct=90"Determines whether or not writes are persisted. Required in Database 7.0 and later. Accepted values are:
device- Data written to this node is persisted to either a raw device or a file.memory- Data written to this node is written to DRAM. You can also specify one or morefileordeviceparameters to store a copy of the data.memorywas the default value for this parameter prior to Database 7.0.pmem- Data written to this node is written to persistent memory. This requires an EE license and theasdb-pmemfeature-key to be enabled in thefeature-key-file.
In Database 7.0, index-type flash does not work with storage-engine pmem or storage-engine memory.
For more information about defining an in-memory only namespace, see Configure Namespace Storage.
Additional sanity check from Aerospike to validate whether the points returned by S2 falls under the user’s query region. When set to false, Aerospike does not do this additional check and send the results as it is.
When set to true, allows non-durable deletes to be used with
strong-consistency.
Expunges are not ‘consistent’.
Example:
Admin+> asinfo -v "set-config:context=namespace;id=bar;strong-consistency-allow-expunge=true"172.17.0.10:3000 (172.17.0.10) returned:ok
0e0d1a1651ae:3000 (172.17.0.9) returned:okSet the namespace to Strong Consistency mode to favor consistency over
availability. Allows linearized reads to be enabled.
See the Configuring strong consistency and
Consistency Management pages for further details.
Requires the asdb-strong-consistency feature-key to be enabled in the feature-key-file.
Number of seconds to retain a tombstone, even though it’s discovered to be safe to remove. This is to protect
a cluster from older records to be re-introduced after a node that was out of the cluster for some time joins the cluster back.
If a node was out of a cluster for longer than the tomb-raider-eligible-age, it should have all of its data removed before
being brought back in the cluster. Default is 1 day.
Example: Set tomb-raider-eligible-age to 43200 (1/2 day):
asinfo -v "set-config:context=namespace;id=namespaceName;tomb-raider-eligible-age=43200"Minimum amount of time, in seconds, between tomb-raider runs. Default is 1 day.
Starting with Database 4.3.0, setting tomb-raider-period to a value of 0 will deactivate tomb raider.
Example: Set tomb-raider-period to 43200 (1/2 day):
asinfo -v "set-config:context=namespace;id=namespaceName;tomb-raider-period=43200"Number of microseconds to sleep in between large block reads on disk or pmem storage files. Default is 1 ms (1000µs), max 4,294,967,296 µs.
Example: Set tomb-raider-sleep to 2000:
asinfo -v "set-config:context=namespace;id=namespaceName;tomb-raider-sleep=2000"Maximum pending transactions that can be queued up to work on the same key. A value of 0 removes the limit (unlimited), and a value of 1 will allow a maximum of 1 transaction to be queued up in the rw-hash behind a transaction that is already in progress.
Excessive transactions may result in a KEY_BUSY error (14). See “key-busy” in the Server Log Reference.
This parameter context was moved from service to namespace in Database 4.3.1.3.
Example: Set transaction-pending-limit to 3 dynamically:
asinfo -v "set-config:context=namespace;id=namespaceName;transaction-pending-limit=3"Prior to Database 4.3.1.3, run this instead:
asinfo -v "set-config:context=service;transaction-pending-limit=3"The number of dedicated threads each truncate job will create in the namespace. Minimum is 1, maximum is 128. If a truncated set has a set index, this will be used and should speed up the job significantly. However, if the set contains any tombstones at the beginning of the job, the set index cannot be used because set indexes do not include tombstones.
Example:
Set truncate-threads dynamically to 6 for a namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;truncate-threads=6"Size in bytes of each I/O block that is written to the disk. This
effectively sets the maximum object size, which can also be controlled by max-record-size. Acceptable values are 128K, 256K, 512K, 1M. Starting with Database 4.2, 2M, 4M or 8M. Large write-block-size may adversely impact
performance. See “How do I change the write-block-size configuration?” for more information.
Supported size notation is no suffix for bytes, K for Kibibyte (KiB), M for Mebibyte (MiB).
When set to all or master (AKA “fire and forget”), overrides the client-specified commit-level policy for write transactions to this
namespace.
Values: off, all, master.
Only applies to high availability (AP) namespaces.
Not available for strong-consistency enabled (CP)
namespaces because they write (or attempt to write) to all replicas prior to returning to the client.
Example: Set write commit level override to master in the configuration file (return upon master side completion without waiting for replica side):
write-commit-level-override masterDynamically override clients and set commit level to master for every write transaction in this namespace:
asinfo -v "set-config:context=namespace;id=namespaceName;write-commit-level-override=master"If bin-policy
is set to ship changed bins (policies other than the default all),
bin deletions will create bin tombstones. This parameter specifies the
time-to-live (in seconds) for those bin tombstones. 0 means never
expire. Bin tombstones whose TTL expired will be removed only on a
subsequent write operation on the record. The default value in Database
5.2.x used to be 0 and it changed to 86400 (1 day) as of 5.3.
Example: Set xdr-bin-tombstone-ttl to 600 seconds:
asinfo -v "set-config:context=namespace;id=namespaceName;xdr-bin-tombstone-ttl=600"As of Aerospike 5.0, replaced by the dc parameter.
Name of the datacenter to forward this namespace to.
The xdr-remote-datacenter parameter should be defined for each
remote datacenter XDR is to ship to. This can be set dynamically starting with Database 3.8.1.
The Datacenter names are defined in the XDR stanza.
Example: Dynamically associating and disassociating a namespace to a remote datacenter:
asinfo -v "set-config:context=namespace;id=namespaceName;xdr-remote-datacenter=DC1;action=add"asinfo -v "set-config:context=namespace;id=namespaceName;xdr-remote-datacenter=DC1;action=remove"Minimum amount of time, in seconds, between xdr-tomb-raider runs. Default is 120 seconds.
This only applies to xdr_tombstones
and not regular tombstones from durable deletes.
Setting xdr-tomb-raider-period to a value of 0 will deactivate the xdr-tomb-raider.
Example: Set xdr-tomb-raider-period to 500:
asinfo -v "set-config:context=namespace;id=namespaceName;xdr-tomb-raider-period=500"The number of dedicated threads used by the xdr-tomb-raider to clear
xdr_tombstones.
Example: Set xdr-tomb-raider-threads to 4:
asinfo -v "set-config:context=namespace;id=namespaceName;xdr-tomb-raider-threads=4"Network
An access address is an IP address that is announced to clients and used by clients for connecting to the cluster.
If access-address is not specified, the bind address (through the address config) is published to clients.
If access-address is not specified and the service address is set to any, then access-address lists all available IP addresses. Use access-address to specify one or more of the available IP addresses.
Multiple access addresses can be specified. IPv4, IPv6 and DNS names can be used to specify access addresses. DNS names are expanded to all IP addresses they resolve to, IPv4 (A DNS resource records) as well as IPv6 (AAAA DNS resource records). Set advertise-ipv6 to true if using IPv6, otherwise, specifying an IPv6 address is ignored and reverts to the default described earlier.
The IP addresses that are specified under access-address must be available locally. See alternate-access-address and tls-alternate-access-address for more information.
TLS equivalent are exposed through tls-access-address and tls-alternate-access-address.
The info service-clear-std command will return a node’s access address(es) and the
peers-clear-std command will return a node’s peers access address(es) in a cluster.
Multiple access addresses can be specified.
Example:
service { ---- access-address 10.0.0.104 access-address 10.0.0.103 --- }Port number associated with access-address. If not specified, it defaults to the port value in the service stanza.
IP address at which the server listens (binds) for fabric traffic (inter node communication, for replica writes, migrations, duplicate resolution and more).
Can be used to choose a specific IP address or DNS name that will be published as an alternate list for clients to connect (other than the one based on address and access-address). Prior to Database 5.0, XDR can make use of this by specifying dc-use-alternate-services true. Starting with Database 5.0.0, use use-alternate-access-address.
Isolates clients based on public/private address or NATted environments like cloud deployments. Ability to specify a DNS name gives extra benefits.
Unlike its standard counterpart access-address, the IP address or DNS specified does not have to be local to the node.
Port number associated with alternate-access-address. If not specified, it defaults to the access-port value.
Path to the CA file needed for mutual authentication. Only one of ca-file
or ca-path is required.
For XDR TLS connections, one of the 2 is mandatory. Defaults to the system’s default (/etc/ssl/certs/cacert.pem on Ubuntu)
except for XDR where it should be set if needed.
Example:
ca-file <path to file>Path to the directory of the CA file for mutual authentication. Requires openssl rehash <path to directory> command be ran on the ca-path directory containing the CA certs. Only one of
ca-file or ca-path configuration is required.
For XDR TLS connections, one of the 2 is mandatory. Defaults to the system’s default (/etc/ssl/certs on Ubuntu)
except for XDR where it should be set if needed.
Example:
ca-path <path to directory>Path to the file containing rogue certificates serial numbers. Use this to revoke or blacklist rogue certificates. The file should contain the serial numbers of the certificates to be blacklisted, one per line.
Since Database 7.1, blacklist file is periodically refreshed based on tls-refresh-period configuration value.
Prior to Database 7.1, only file-based cert-blacklist is supported. Since Database 7.1, file-based as well as external Secret Manager-based cert-blacklist is also supported.
Example:
File-based cert-blacklist
cert-blacklist PATH TO FILEexternal Secret Manager-based cert-blacklist
cert-blacklist secrets:AerospikeSecrets:CertBlacklistPath to the TLS certificate when TLS is enabled. Starting with Database 7.1, file-based as well as external Secret Manager-based TLS certificates are refreshed periodically using tls-refresh-period configuration. Prior to Database 7.1, only file-based certificates automatically reload
on subsequent connections if the file itself changes.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/cert- Read from the filesystem (thefile:prefix is optional).env:CERT- Read from the named environment variable (Database 5.3+).vault:cert- the named secret is read from Vault (Database 5.1+).secrets:AerospikeSecrets:CertFile- fetched using Aerospike Secret Agent (Database 6.4+).
.
Prior to Database 7.1, cert-file specified using Vault, environment variable, or Secret Agent is read when the server starts
and is not re-read thereafter.
Example:
File based cert-file
cert-file <path to file>External Secret Manager-based cert-file
cert-file secrets:AerospikeSecrets:CertFileNumber of bulk channel sockets to open to each neighbor node. Twice this number of sockets per neighbor will be opened since the neighbor nodes will open the same number of sockets back to this node.
Number of threads processing intra-cluster messages arriving through the bulk channel. This channel is used for record migrations during rebalance.
Example: Set channel-bulk-recv-threads to 6 dynamically:
asinfo -v "set-config:context=network;fabric.channel-bulk-recv-threads=6"Number of control channel sockets to open to each neighbor node. Twice this number of sockets per neighbor will be opened since the neighbor nodes will open the same number of sockets back to this node.
Number of threads processing intra-cluster messages arriving through the control channel. This channel distributes cluster membership change events as well as partition migration control messages.
Example: Set channel-ctrl-recv-threads dynamically to 6:
asinfo -v "set-config:context=network;fabric.channel-ctrl-recv-threads=6"Number of meta channel sockets to open to each neighbor node. Twice this number of sockets per neighbor will be opened since the neighbor nodes will open the same number of sockets back to this node.
Number of threads processing intra-cluster messages arriving through the meta channel. This channel distributes System Meta Data (SMD) after cluster change events.
Example: Set channel-meta-recv-threads dynamically to 6:
asinfo -v "set-config:context=network;fabric.channel-meta-recv-threads=6"Number of read/write channel sockets to open to each neighbor node. Twice this number of sockets per neighbor will be opened since the neighbor nodes will open the same number of sockets back to this node.
Number of thread pools for the fabric rw (read/write) receive channel. Each thread pool has one epoll instance (Linux system call for scalable I/O event notification).
The configuration parameter channel-rw-recv-threads
must be a multiple of this setting (channel-rw-recv-pools).
For high throughput write workloads, increasing the number of channel-rw-recv-threads can help, but you would also have to increase the number of thread pools (channel-rw-recv-pools) to prevent having all the fabric rw receive threads contend on a single epoll instance. A ratio of 16:1 (channel-rw-recv-threads : channel-rw-recv-pools) is a good starting point.
It may also be beneficial to adjust the channel-rw-fds and the send-threads to keep an 8:1 ratio with the channel-rw-recv-pools.
Proper benchmark testing is required for the best values for a given workload (as defined by throughput, objects type and size as well as general configuration such as compression and encryption — at rest as well as over the fabric channel). The send and receive buffer sizes (tcp_rmem and tcp_wmem) could also be tuned for extreme workloads.
Number of threads processing intra-cluster messages arriving through the rw (read/write) channel. This channel is used for replica writes, proxies, duplicate resolution, and various other intra-cluster single-record commands.
Minimum: 1.
Maximum: 128. Exceeding this maximum will prevent the server from starting.
Starting with Database 5.1,
configuration parameter channel-rw-recv-threads
must be a multiple of
channel-rw-recv-pools.
Example: Set channel-rw-recv-threads to 24 dynamically:
asinfo -v "set-config:context=network;fabric.channel-rw-recv-threads=24"Ciphers to includes. This is not set by default on Aerospike and would revert to what the system uses,
usually ALL:!aNULL:!eNULL.
Example:
cipher-suite ALL:!COMPLEMENTOFDEFAULT:!eNULLNode connection timeout within the cluster, in milliseconds. This timeout also applies to establishing and accepting TLS connections.
This value must be at least 50, and cannot be larger than one-third the product of
heartbeat.interval and heartbeat.timeout
Example:
Set heartbeat.connect-timeout-ms to 1200:
asinfo -v 'set-config:context=network;heartbeat.connect-timeout-ms=1200'When set true, the service will not listen on localhost.
Interval in milliseconds between which heartbeats are sent. interval
can be set to a minimum value of 50 and a maximum of 600000 (10 minutes).
Example:
Set heartbeat.interval to 250:
asinfo -v 'set-config:context=network;heartbeat.interval=250'Enables the nodes to send keep-alive messages to each other.
Interval in seconds between successive keep-alive packets.
Maximum number of keep-alive packets the node sends succession before declaring the socket dead.
Time in seconds from the last user data packet sent on the socket before sending the first keep-alive packet.
Password for the key-file.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/key-file-password- Read from the filesystem (thefile:prefix is optional).env:KEYPASS- Read from the named environment variable (Database 5.3+).vault:key-file- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:KeyFile- fetched using Aerospike Secret Agent (Database 6.4+).
.
This parameter is read when the server starts and is not re-read thereafter.
Example:
key-file-password file:<path to keyfile pwd>Path to the TLS key file when TLS is enabled. Starting with Database 7.1, file-based as well as external Secret Manager-based TLS certificates are refreshed periodically using tls-refresh-period. Prior to Database 7.1, only file-based TLS certificates automatically reload
on subsequent connections if the file itself changes.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/key-file- Read from the filesystem (thefile:prefix is optional).env:KEYFILE- Read from the named environment variable (Database 5.3+).vault:key-file- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:KeyFile- fetched using Aerospike Secret Agent (Database 6.4+).
.
Prior to Database 7.1, key-file specified using Vault, environment variable, or Secret Agent is read when the server starts
and is not re-read thereafter.
Example:
File based key-file
key-file <path to key file>External Secret manager based key-file
key-file secrets:AerospikeSecrets:KeyFileMaximum latency in milliseconds between nodes that the clustering system will tolerate.
Used to derive the quantum interval, which helps to determine cluster reformation time after cluster event. Increasing this value can increase the amount
of time it takes for a new cluster to form.
This value is also used in the HLC (Hybrid Logical Clock)
when determining if an event happened before or after another event. If two events occur less than this value
apart, the ordering is indeterminate.
The impact of this parameter on cluster reformation after cluster
events is discussed in detail in the What is the Quantum Interval
article. Changing this value may be appropriate in certain scenarios whereby intra-node network latency is
necessarily high. Enterprise Licensees should consult with Aerospike Support before changing this configuration.
Mesh address (host-name or IP) and port info for seed server(s). These are other addresses from the cluster that Aerospike will bootstrap from. A new line is required for each additional boot strap. Applies only when mode is mesh.
Example:
mesh-seed-address-port 10.10.0.116 3002mesh-seed-address-port aerospike_a_0 3002May be either multicast or mesh. In case of multicast, all
cluster nodes must be in the same subnet.
Example:
mode multicastFor the underlying network, returns the maximum transmission unit (MTU) detected by the heartbeat system.
IP address for cluster-state heartbeat communication over multicast.
TTL for multicast packets.
Port for inter-node communication within a cluster.
Heartbeat protocol version to be used by cluster. Use v3 or none.
Protocol can only be changed on all nodes at once.
-
v3= Improved cluster management and flexible cluster size, removespaxos-max-cluster-sizedependency. Introduced in version 3.10.0.3. -
none= Used only for dynamically changing protocolExample: Set
heartbeat.protocolto v3.asinfo -v 'set-config:context=network;heartbeat.protocol=v3'
TLS protocol versions to include. The default is to only allow TLS protocol version 1.2.
Example:
protocols -all,+TLSv1.2Number of intra-node send threads to be used. The send-threads
operate across all fabric channels.
Number of missing heartbeats after which the remote node will be declared dead. Values lower than 3 are not allowed as this would potentially lead to very frequent timeout which could destabilize a cluster.
Example:
Set heartbeat.timeout to 20:
asinfo -v 'set-config:context=network;heartbeat.timeout=20'TLS equivalent of access-address.
Transport Layer Security (TLS) equivalent of access-port.
Bind address for TLS, the IP address at which the server listens for client connections, heartbeat connections or fabric connections (based on the subcontext this is set at). Similar to address when not using TLS. Will default to any if not set.
TLS equivalent of alternate-access-address.
Unlike its standard counterpart tls-access-address, does not have to be local to the node.
The TLS authentication mode you want to run the server with in regards to the service (Client connections).
See the TLS Configuration Manual for further details.
Multiple tls-authenticate-client directives can be specified.
Options:
There are three modes you can have TLS configured, standard authentication (server only), mutual authentication
(TLS client and TLS server), mutual authentication with subject validation.
If not specified will default to any (mutual authentication without subject validation).
false: Use this for only client authenticating the server.any: Use this is for a two way (mutual) authentication, both client and server need to be authenticated. Also check configsca-fileandca-pathwhen set to this mode.- user-defined: Use this for two way (mutual) authentication along with subject validation. This would be the
TLS name a cluster node would expect clients to present on incoming connections.
Note: false and any are incompatible with each other and incompatible with a subject name, so if false or any is used, then there can only be onetls-authenticate-clientdirective.
Note: There isn’t anytls-authenticate-clientfor heartbeat and fabric. They always validate the subject name in their peer’s certificate and expect it to match the TLS name.
Example:
service { <...> tls-authenticate-client remote-xdr-dc.aerospike.com tls-authenticate-client local-clients.aerospike.com <...>}TLS mesh address (host-name or IP) and port info for seed server(s). These are other addresses from the cluster that Aerospike will bootstrap from. A new line is required for each additional boot strap. Applies only when mode is mesh.
Example:
tls-mesh-seed-address-port 10.10.0.116 3012tls-mesh-seed-address-port aerospike_a_0 3022Specifies which TLS parameters to use for the given context TLS connections. The TLS parameters are configured under the matching tls sub-stanza. This also implicitly specifies the TLS name the node will present on incoming client connections. See TLS Name Clarification for details.
Port that is TLS enabled at which the server listens for client connections, heartbeat connections or fabric connections based on the subcontext this is set to.
Definition of TLS parameters for a given tls-name.
Can be <cluster-name> (literally), <hostname> (literally) or user defined. See the
TLS Configuration Manual for further details.
Example:
tls <cluster-name> { cert-file path-to-cert-file key-file path-to-key-file}Security
A path or an optional prefix, such as env: or secrets: to specify where to fetch the initial password for the default admin user. If not configured, the old default password “admin” is used.
Whether or not to disable the use of TLS for LDAP server connections
Enables LDAP. See the LDAP Configuration
documentation for further details.
Requires the asdb-ldap feature-key to be enabled in the feature-key-file.
As of Database 5.7, this item is removed, and LDAP is enabled by the presence of an ldap section
within the security section of the configuration file.
Enables read and write rate quotas to limit transaction rates. Quotas can be added to roles,
and users assigned such roles are restricted according to the associated quotas.
When enable-quotas is true, read and write transaction per second (TPS) rates
and scan record per second (RPS) rates are tracked for all users,
even users with no quotas, and can be displayed with the “show users statistics” command in asadm which was added in tools package 8.4.0.
Enables Access Control (ACL). See Configuring Access Control in EE and FE for further details.
Database 4.6.0.4 and later, 4.5.3.6, 4.5.2.6, 4.5.1.11 and 4.5.0.15 support enabling ACL
through a rolling restart, allowing environments running on the latest Client Libraries (supporting mixed security
modes) to turn on ACL without downtime. The AER-6099 improvement was made to allow the System Metadata (SMD)
sub-system to support mixed security modes on the server side.
Starting with Database 5.7, this item is removed, and ACL is enabled by the presence of a security section in the configuration file.
Number of threads to use for LDAP logins.
Write to “local0” facility as well as to default syslog file. You can define local0 in /etc/rsyslog.conf.
Number of threads to use for LDAP logins.
How frequently (in seconds) to query the LDAP server for user group membership information. Allowable range is 0 to 86400 (24 hours). A value of 0 means do not poll.
Frequency in seconds with which the node verifies permissions for active client connections.
Example: Set privilege-refresh-period to 200 dynamically:
asinfo -v "set-config:context=security;privilege-refresh-period=200"Distinguished name of the LDAP directory entry at which to begin the search when querying for a user’s group membership information.
Distinguished name of the user designated for user group membership queries.
Clear text password of the user specified for user group
membership queries.
This parameter’s value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/ldap-query-password- Read from the filesystem (thefile:prefix is optional).env:LDAPQPASS- Read from the named environment variable (Database 5.3+).vault:ldap-query-password- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:LDAPQueryPass- fetched using Aerospike Secret Agent (Database 6.4+).
.
Set to true to report successful authentications in aerospike.log.
This parameter is dynamic starting with Database 5.6.
Example: Set the parameter dynamically:
asinfo -v "set-config:context=security;log.report-authentication=true"Set this to report on data transactions for all users having a given role. Report transactions in aerospike.log.
Example: Enable reporting of data operations by all users having the ‘billing’ role:
report-data-op-role billingDynamically disable reporting of data operations to aerospike.log by all users having the ‘billing’ role:
asinfo -v "set-config:context=security;log.report-data-op=false;role=billing"Set this to report on data transactions for a given user. Report transactions in aerospike.log.
Example: Enable reporting of data operations by user ‘charlie’:
report-data-op-user charlieDynamically enable reporting of data operations by user ‘fred’:
asinfo -v "set-config:context=security;log.report-data-op=true;user=fred"Set this to report on data transactions for a namespace (and optionally a set). Report transactions in aerospike.log.
This parameter is dynamic starting with Database 5.6.
Example:
report-data-op {namespace} {set}Dynamically enable reporting of data operations to aerospike.log for set ‘setA’ in namespace ‘test’:
asinfo -v "set-config:context=security;log.report-data-op=true;namespace=test;set=setA"Set to true to report systems administration operations in aerospike.log.
This parameter is dynamic starting with Database 5.6.
Example: Set the parameter dynamically:
asinfo -v "set-config:context=security;log.report-sys-admin=true"Set to true to report successful user administration operations in aerospike.log.
This parameter is dynamic starting with Database 5.6.
Example: Set the parameter dynamically:
asinfo -v "set-config:context=security;log.report-user-admin=true"Set to true to report security violations in aerospike.log.
This parameter is dynamic starting with Database 5.6.
Example: Set the parameter dynamically:
asinfo -v "set-config:context=security;log.report-violation=true"If specified uses this value as the base dn when performing the role queries.
Format for the search filter to use when querying for a user’s group membership
information. The substitutions for username, ${un}, and distinguished name, ${dn} will be replaced by the actual
username and the actual user’s full distinguished name when constructing the search filter. If needed, multiple role-query-pattern
strings can be specified separately and each will be tried in order when querying for a user’s information
Whether to look for a user’s group membership information in the organizational unit entries of the user’s LDAP distinguished name
Name of the LDAP server to use. Multiple servers can be specified using a comma-delimited string without white-space.
Lifetime (in seconds) of an access token. A TCP connection attempt with an expired token will fail, and the client must log in again to get a fresh token. Allowable range is 120 (2 minutes) to 864000 (10 days). The server sends a time stamp one minute shorter for the clients to refresh to avoid getting too close to the time it expires.
This parameter was moved out of the ldap subcontext into the main security context in database 5.7.
Local syslog file to log to.
Path to the CA certificate file used for validating TLS connections to the LDAP server. Includes filename, e.g. /path/to/CA/cert/filename.
Hash algorithm to use when generating the HMAC for access tokens. Currently supported algorithms are sha-256 and sha-512.
A number indicating how much smoothing to do when maintaining transactions per second (tps) values for enforcing quotas. Smoothing makes the system less responsive to brief spikes in transaction rates, so that the more smoothing is used, the less likely it is that a brief spike in transactions greater than a user’s quota will result in a violation. The allowable range is 2 (least smoothing) to 20 (most smoothing).
The tps rates are computed every second as exponential moving averages, and a tps-weight of N
means that the previous tps value is given (N-1) times the weight of the observed tps over the
most recent second when performing the computation. The computation looks like:
tps = (((tps-weight - 1) * tps) + transactions_during_last_second) / tps-weight
So for example, with a tps-weight of 5, the computation would be:
tps = ((4 * tps) + transactions_during_last_second) / 5
Example: Set tps-weight to 8 dynamically:
asinfo -v "set-config:context=security;tps-weight=8"Format for the distinguished name of the LDAP directory entry to use when binding to the LDAP
server for user authentication. ${un} should be placed in this string to specify where the user ID is inserted when
constructing the distinguished name.
Format for the search filter to use when querying for a user’s distinguished name.${un} should be placed in this string to specify where the user ID is inserted when
constructing the distinguished name.
Service
Requires heartbeat v3. Set to true in order enable IPv6.
This configuration controls the different options for CPU pinning. When using this configuration prior to
Database 4.7, neither service-threads, nor
transaction-queues may be configured in the configuration file; both
will default to the number of CPUs. With Aerospike 4.7+,
service-threads can be configured, but must be a multiple of the number of
CPUs, if this configuration is in effect. Possible values are:
none- relying on Linux’s irqbalance.cpu- CPU pinning - Aerospike controls the interrupt affinity of all NIC queue interrupts.numa- CPU and NUMA pinning - restrict memory and CPU usage ofasdto a single NUMA node.adq- Application Device Queue pinning - Aerospike dispatches a client request to a CPU based on the NIC queue associated with the corresponding client network connection. Requires an ADQ-enabled NIC and manual configuration of the NIC. Introduced in 4.7.
cpu and numa require Linux kernel 3.19+. This is the default for Ubuntu18.04+ and Debian 9+, but not CentOS 7
(3.10). If necessary, the Linux kernel can be upgraded. adq requires Linux kernel 4.12+. When moving away from any auto-pinning,
a reboot is required to restore the system defaults for interrupts. When setting auto-pin to cpu, prior to Database 4.7
don’t allow transaction-queues and service-threads to be set in the configuration file; both will be forced to the number of
CPUs - which is also the default in Aerospike versions 3.12+. Database 4.7 and later allows setting service-threads, but require
the configured number to be a multiple of the number of CPUs. Contact Aerospike Support for recommendations and benchmark details
prior to using these configurations.
Number of batch index response worker threads. This is set by default to the number of CPU cores available. Each thread has its own queue. These threads only handle sending back batch response buffers to the client using sockets. Setting this parameter to 0 disables batch commands. Config file value range: 1-256 (a value of 0 can be set dynamically).
Example: Set batch-index-threads to 16 dynamically:
asinfo -v "set-config:context=service;batch-index-threads=16"Number of 128 KiB response buffers allowed in each batch index queue before it is marked as full. A batch index queue (one per
batch-index-threads) can have more than batch-max-buffers-per-queue buffers
but it will not receive any new batch until it gets less than that number. When all queues are greater than the batch-max-buffers-per-queue
new batch requests are rejected and an error will be logged on the server: Failed to find active batch queue that is not full.
Example: Set batch-max-buffers-per-queue to 512 dynamically:
asinfo -v "set-config:context=service;batch-max-buffers-per-queue=512"Max number of keys allowed per node. Limits the number of sub-requests per batch transaction. The default value of 0 means there is no limit.
Example: Set batch-max-requests to 6000 dynamically:
asinfo -v "set-config:context=service;batch-max-requests=6000"Max number of 128 KiB response buffers allowed in the unused buffer pool for reuse by any response thread. If the limit is reached, completed buffers will be destroyed at the end of the batch request. For large batch workloads, it may be advisable to increase this configuration parameter to avoid unnecessary destruction and recreation of buffers, which would impact CPU load.
Example: Set batch-max-unused-buffers to 512 dynamically:
asinfo -v "set-config:context=service;batch-max-unused-buffers=512"If set to true, digests are not included in batch responses.
Starting with Database 5.7, the default value is true. In earlier versions the default value is false.
Example: Dynamically set batch-without-digests to false:
asinfo -v "set-config:context=service;batch-without-digests=false"Mandatory in Database 7.0 and later. Maximum 63 characters. Node can only join a cluster with a matching cluster-name. Clients must provide matching cluster name. Configuration file of a new node must specify a non-null cluster name or node will not start.
An application or client must provide the IP address of the seed node to connect. IP addresses in the cloud are assigned dynamically when instances are created. Customers running multiple, separate Aerospike clusters in the cloud can ensure secondary validation that their application is connecting to the intended cluster by optionally using cluster name in their client policy.
Use asinfo to dynamically change the cluster name on a specific node, or asadm to dynamically change the cluster name on all nodes simultaneously.
Examples:
- Dynamically set
cluster-nameto payments on the current node:
asinfo -v "set-config:context=service;cluster-name=payments"- Dynamically set
cluster-nameto payments on all nodes simultaneously:
Admin+> manage config service param cluster-name to paymentsOptions for debugging memory allocations on the server.
Starting with Database 7.0, the options are false (default) or true.
Prior to Database 7.0
none- Feature not enabled (default).transient- Feature enabled only for transient allocations - ‘overhead’ memory that is not record data or metadata.persistent- Feature enabled only for persistent allocations - memory that is record data or metadata.all- Feature enabled for all allocations.
Completely disallow the execution of User-Defined Functions (UDFs).
Example: Disable UDF execution:
service { ... disable-udf-execution true ...}Used in conjunction with downgrades from Database 5.2 or later (where XDR bin shipping has been used) to pre-5.2, or from Database 5.4 (where XDR bin convergence has been used) to 5.3 or 5.2, or from Database 5.5 or later (where XDR bin convergence has been used) to 5.4 or 5.3 or 5.2.
When set true before downgrading, ensures record compatibility when sending records from nodes with the later server version to nodes with the older version.
This parameter can only be set dynamically.
Example:
Set to true:
asinfo -v "set-config:context=service;downgrading=true"Enable histograms for fabric. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-benchmarks-fabric to true:
asinfo -v 'set-config:context=service;enable-benchmarks-fabric=true'Monitors the health of a cluster and attempts to identity potential outlier nodes.
Helpful if there is a suspicion of a node under performing and impacting the overall cluster.
This does not replace regular monitoring and alerting for a cluster but rather augments it.
This has to be explicitly enabled on all the nodes for best results.
See the health-stats and
health-outliers commands.
Example: Set the enable-health-check to true dynamically:
asinfo -v "set-config:context=service;enable-health-check=true"Enable histograms for info protocol transactions. See the Histograms from Aerospike Logs page for details.
Here is the list of configuration enabled histograms:
enable-benchmarks-batch-subenable-benchmarks-fabricenable-benchmarks-ops-subenable-benchmarks-readenable-benchmarks-storageenable-benchmarks-udfenable-benchmarks-udf-subenable-benchmarks-writeenable-hist-infoenable-hist-proxysindex-histogram
Example:
Set enable-hist-info to true:
asinfo -v 'set-config:context=service;enable-hist-info=true'If enforce-best-practices is set to true then Aerospike will fail to startup if any of the checked
best-practices are violated. When set to false,
Aerospike will continue to startup and also log a warning for each failed best-practice as well as set the
failed_best_practices metric to true and add the name
of the failed best-practices to the output of the best-practices info
command.
Specifies the feature-key file needed to start up Enterprise Edition and Standard Edition server nodes.
Value must follow one of these formats: Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path/to/feature-key-file- Reads from the filesystem (thefile:prefix is optional). Starting with Database 5.5, up to 32feature-key-filedirectives can be specified, with the server merging feature-keys from multiple sources. Path can also specify a directory, in which case all files within the directory must be feature-key files.env-b64:FEATUREKEY- read from a named, base64-encoded environment variable (Database 5.4+).vault:feature-key- the named secret will be read from Vault (Database 5.4+).secrets:AerospikeSecrets:FeatureKey- fetched using Aerospike Secret Agent (Database 6.4+).
Group to run as.
Total time span in seconds over which to cache data. This serves as a flag to enable/disable histograms. The reported track-back value can change at the generated namespace hist-track-back due to rounding based on the slice size. When the histogram is started, its number of rows is computed based on integer division of ‘back’ / ‘slice’. And while the number of rows and the slice size are stored with the histogram, the back size is not – it is recomputed from (# rows) * (slice size) when being reported. So when the histogram is started, ‘back’ is effectively rounded down to the nearest multiple of ‘slice’, and corresponds to the actual time window tracked by the histogram.
Period in seconds at which to cache histogram data.
Comma-separated bucket (ms) values to track, must be powers of 2. For example : 1,4,16,64.
Example:
hist-track-thresholds 1,2,4,8,16,32,64,128,256,512Extra option for debug-allocations which enables detection of all double frees.
info-max-ms checks info transactions for timeout after they are popped from the info transaction queue. The default value is 10000 milliseconds. The minimum is 500 ms, maximum 10000 ms.
Related to the info_timeout metric, which tracks total timed-out info transactions.
Number of threads to create to process info requests. This configuration is static in releases prior to 4.5.2. Maximum allowed value is 256 for Database 4.5.2 and later. Value range: 1-256.
Example: Set info-threads to 8 dynamically:
asinfo -v "set-config:context=service;info-threads=8"If true, enables non-root Aerospike users to keep permissions necessary to report (NVMe) device health. Currently, only ‘age’ is returned.
By default, Aerospike server logs have a time stamp in GMT. Set this configuration to true to set logs to have local
time stamp (also displays an offset to GMT).
Example:
Dec 12 2015 18:52:39 GMT-0800: INFO (as): (as.c::494) service ready: soon there will be cake!
Set this to true in order to get millisecond timestamps in the log file.
Set the granularity of histograms to microseconds instead of the default milliseconds. For the auto enabled histograms, this configuration is static and nodes have to be restarted.
Example: Set microsecond histograms to true:
asinfo -v "set-config:context=service;microsecond-histograms=true"Number of seconds to delay before starting ‘fill’ migrations. For Available mode (AP),
fill migrations are migrations that are going to a node that didn’t own
a partition to be migrated. For
strong-consistency,
these are migrations that are going to a non-roster-replica. These
migrations aren’t necessary if the cluster state is transient (normal
case) — when the cluster state is restored this migrated data would
eventually be dropped. This setting doesn’t affect ‘lead migrations’
indicated by
migrate_tx_partitions_lead_remaining.
See the Delaying “Fill” Migrations page for
further details.
Example:
To enable a one hour fill delay across the cluster (to be changed in the configuration file as well since a restart will revert such dynamic change):
asadm -e "enable; asinfo -v 'set-config:context=service;migrate-fill-delay=3600'"
Maximum number of partitions a node can be receiving records from at any given time. The default value of 4 limits potential congestion on a given node, especially in situations where a node is added in a cluster. Can be increased cautiously to speed up migrations. See manage migrations for further details. Maximum value is 256.
Example: Set migrate-max-num-incoming to 8 dynamically:
asinfo -v "set-config:context=service;migrate-max-num-incoming=8"Number of threads per server allocated for data migration. Each thread will migrate one partition at a time. Increasing this parameter should be done with caution. See manage migrations for further details. Value range: 0-100.
Example: Set migrate-threads to 2 dynamically:
asinfo -v "set-config:context=service;migrate-threads=2"The minimum number of nodes required for a cluster to form. Necessary when configured with
index-type flash
to avoid running out of resources in case of cluster splits.
Example: Set min-cluster-size dynamically to 6
asinfo -v "set-config:context=service;min-cluster-size=6"Name of the interface from which to generate the ‘Node ID’. The ‘Node ID’ determines the succession list for partition assignments across nodes in a cluster.
Allows specifying the node-id of the node as a 1 to 16 character (in hexadecimal), in order to make it friendlier or to
influence the partition distribution which is based off the cluster’s node ids. By
default, Aerospike derives the node-id from the configured fabric port and one of the server’s network interface
mac address (or, if configured, the mac address of the node-id-interface).
Example:
service { <...> node-id a1 <...> }When set true, group read/write permissions are added to files created by the service.
Examples of affected files include storage files, system metadata (SMD) files, and log files.
If the cluster size is less than or equal to this value, only one copy
of the data (no replicas) will be kept in the cluster. Only in Available mode (AP). Will be
ignored for strong-consistency configured
namespaces. Should typically be configured
to a few nodes under the expected cluster size for clusters that would be used
at near capacity (per the usual capacity sizing guidelines) but will depend on the total
size of the cluster and how full the nodes are within the cluster.
File to store the PID of the daemon.
Time in milliseconds to wait before reaping connections. The default means that idle connections are never reaped. The Aerospike server uses keep-alive for client sockets starting with Database 4.8.
Example: Set proto-fd-idle-ms to 70000 dynamically:
asinfo -v "set-config:context=service;proto-fd-idle-ms=70000"Maximum number of open file descriptors opened on behalf of client connections.
Can be increased for higher throughput use cases or for absorbing temporary spikes in traffic.
Minimum: 1024.
Maximum: 2097152.
At Aerospike server start, this value must not exceed the system’s file descriptor limit for the asd process.
To avoid a startup problem, there are two alternatives:
- Decrease the value of
proto-fd-maxin your Aerospike configuration file. - Increase the system’s file descriptor limit for the asd process.
Example: Set proto-fd-max to 30000 dynamically. Prior to Database 4.9, for a dynamic change, this limit was enforced only if the new value was lower than the system setting.
asinfo -v "set-config:context=service;proto-fd-max=30000"This configuration specifies how long to sleep between repeated attempts when sending the response buffer for “slow” queries. Can be used as a throttling parameter during unexpected network congestion when response get re-queued.
Example:
asinfo -v "set-config:context=service;proto-slow-netio-sleep-ms=100"
Amount of disk I/O a query performs per I/O request. See the Managing Queries page for further details on tuning and configuring limits for secondary queries.
Example: Set query-batch-size to 75 dynamically:
asinfo -v "set-config:context=service;query-batch-size=75"The unit of buffer size at which network IO is performed for secondary index queries. Used to avoid too many network calls. Decreasing this would mean more frequent network IO and hence improved response at the socket level.
Example: Set the query-buf-size to 500KiB dynamically:
asinfo -v "set-config:context=service;query-buf-size=512000"This configuration specifies how many buffers to keep in a pool. This can be configured between the range of 1 to UINT32_MAX.
The unit of buffer size at which network IO is performed can be configured with query-buf-size.
Example:
asinfo -v "set-config:context=service;query-bufpool-size=512"
Run queries in transaction threads (Database 4.7 adn earlier) or service threads (Database 4.7 and later) instead of using query threads. Set it to ‘true’ when you expect queries to run for a short period of time or when the namespace is in-memory. Leave it set to ‘false’ if you expect longer running queries or if the namespace uses disk storage. See the Managing Queries page for further details on tuning and configuring limits for secondary queries.
Example: Set query-in-transaction-thread to true dynamically:
asinfo -v "set-config:context=service;query-in-transaction-thread=true"Number of queries in the long running query queue. A long running query is one that returns more records than the query-threshold.
See the Managing Queries page for further details on tuning
and configuring limits for secondary queries.
Example: Set query-long-q-max-size to 600 dynamically:
asinfo -v "set-config:context=service;query-long-q-max-size=600"Max number of finished query kept for monitoring. Value range: 0-1000.
Example: Set query-max-done to 500 dynamically:
asinfo -v "set-config:context=service;query-max-done=500"Enable microbenchmarks of queries.
This configuration can be used to pre-reserve all queryable partitions before processing a query. Enabling this to true might help reduce the potential inconsistency windows during ongoing migration for some use-cases, but can also have an adverse effect. Enterprise licensees can discuss specific use cases that could benefit from this parameter with Aerospike Support.
Example:
asinfo -v "set-config:context=service;query-pre-reserve-partitions=true"
Time in microseconds that the server pauses after reading query-priority sequential query elements.
See the Managing Queries page for further details on tuning
and configuring limits for secondary queries.
Example: Set query-priority-sleep-us to 2 dynamically:
asinfo -v "set-config:context=service;query-priority-sleep-us=2"Priority for query threads. Number of sequential query elements to read before yielding (for query-sleep-us micro seconds).
A higher value is a higher priority. See the Managing Queries page for further details on tuning
and configuring limits for secondary queries.
Example: Set query-priority to 20 dynamically:
asinfo -v "set-config:context=service;query-priority=20"This is the maximum number of records a query is allowed to return. A query returning beyond this limit is aborted. This can be configured between the range of 1 to UINT64_MAX.
Example:
asinfo -v "set-config:context=service;query-rec-count-bound=512"
This configuration set to true will cause queries to always be processed in the main query thread and would not be queued to be processed
by the query-worker-threads.
Example:
asinfo -v "set-config:context=service;query-req-in-query-thread=true"
Number of query I/O threads used per query at one time. See the Managing Queries page for further details on tuning and configuring limits for secondary queries.
Example: Set query-req-max-inflight to 150 dynamically:
asinfo -v "set-config:context=service;query-req-max-inflight=150"Number of queries in the short running query queue. A short running query is one that returns fewer records than the query-threshold.
See the Managing Queries page for further details on tuning
and configuring limits for secondary queries.
Example: Set query-short-q-max-size to 600 dynamically:
asinfo -v "set-config:context=service;query-short-q-max-size=600"Maximum number of threads allowed for all queries. Can be dynamically increased or decreased. Value range: 1-1024.
Example: Set query-threads-limit to 64 dynamically:
asinfo -v "set-config:context=service;query-threads-limit=64"Number of dedicated query threads on the node. Value range: 1-32. See the Managing Queries page for further details on tuning and configuring limits for secondary queries. Only even values are allowed from Database 5.7 and later. Odd values are rounded up to the next even number prior to Database 5.7.
Example: Set query-threads to 12 dynamically:
asinfo -v "set-config:context=service;query-threads=12"Dividing line between short running and long running queries. A query that returns fewer records than the query threshold is a short running query. All others are long running queries.
See the Managing Queries page for further details on tuning
and configuring limits for secondary queries.
Example: Set query-threshold to 20 dynamically:
asinfo -v "set-config:context=service;query-long-q-max-size=600"Queries that run longer than this configured time are tracked by default. See the Managing Queries page for further details on tuning and configuring limits for secondary queries.
Example: Set query-untracked-time-ms to 5 sec dynamically:
asinfo -v "set-config:context=service;query-untracked-time-ms=5000"Number of dedicated I/O threads on the node. See the Managing Queries page for further details on tuning and configuring limits for secondary queries.
Example: Set query-worker-threads to 20 dynamically:
asinfo -v "set-config:context=service;query-worker-threads=20"If true, initial process forks into a new process (which runs in background) and exits.
Maximum number of threads allowed for all queries. Can be dynamically increased or decreased. Value range: 1-1024.
Example: Set scan-threads-limit to 64 dynamically:
asinfo -v "set-config:context=service;scan-threads-limit=64"Specifies an IP address and port of the Secret Agent and TLS name specified in the TLS certificate.
For a plain TCP connection between Aerospike Database and Secret Agent, only the IP address and port of Secret Agent need to be specified.
For a TLS over TCP connection between the Aerospike database and Secret Agent, specify only the IP address, port of the Secret Agent, and TLS name mentioned in the TLS certificate, along with secrets-tls-context. The TLS name should be either a common name or one of the Subject Alternate Names (SAN) in TLS certificate.
User must specify either secrets-address-port or secrets-uds-path but not both, to configure access to Secret Agent.
Example:
Sample configuration file for a plain TCP connection between Aerospike server and Secret Agent:
service { ... secrets-address-port 127.0.0.1 3005 ...}Sample configuration file for a TLS over TCP connection between Aerospike server and Secret Agent:
service { ... secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name. secrets-tls-context secrets-tls ...}
network { ... tls secrets-tls { ca-file /path/to/ca-file.pem } ...}To establish a TLS connection over TCP between Aerospike server and Secret Agent, specify an IP address, port, and TLS name in secrets-address-port along with a secrets-tls-context. TLS name should be either a common name or one of the Subject Alternate Name (SAN) in TLS certificate.
Example:
Sample configuration file for a TLS over TCP connection between Aerospike server and secret agent:
service { ... secrets-address-port 127.0.0.1 3005 secretagent #'secretagent' is a TLS name. secrets-tls-context secrets-tls ...}
network { ... tls secrets-tls { ca-file /path/to/ca-file.pem } ...}This parameter specifies a Unix Domain Socket (UDS) path. To access a Secret Agent, you must set either secrets-uds-path or secrets-address-port but not both. Use secrets-uds-path to communicate with a secret agent only if the Aerospike server and secret agent are running on the same host.
Example: Sample configuration file to configure UDS:
service { ... secrets-uds-path /path/to/uds.sock ...}Number of threads receiving client requests and executing transactions. On multi-socketed systems, if Non-Uniform Memory Access (NUMA) pinning is enabled, each Aerospike instance only counts the CPU cores on the socket it is servicing.
- Recommended and default value is five times the number of CPUs unless there are no SSD, memory, persistent memory (PMEM) namespaces with
commit-to-deviceenabled, in which case the recommended and default value is the number of CPUs. The value range is 1-4096.
- Prior to Database 5.1, all persistent memory (PMEM) namespaces also default to 5 per CPU.
- Prior to 5.1, all persistent storage.
- Prior to Database 4.7, this configuration item is static and defaults to the number of CPUs.
Number of threads for building secondary indexes. Can be set dynamically for secondary indexes created when a server is already running. When updating dynamically, the change goes into effect on a subsequent sindex build. The number of builder threads remains unchanged on a sindex build in progress. You should set this value in the configuration file for secondary indexes that are built or rebuilt during start up.
The maximum value is 32. Refer to this knowledge base article for further details.
Example:
asinfo -v 'set-config:context=service;sindex-builder-threads=5'
The maximum processing rate (entries per second) for secondary index entries garbage collector.
This refers to the number of records that have been indexed by a secondary
index (entries).
Example:
asinfo -v "set-config:context=service;sindex-gc-max-rate=10000"
The interval (seconds) at which secondary index garbage collection thread runs.
Starting with Database 4.3.0, setting sindex-gc-period to a value of 0 will disable secondary index garbage collection.
Example:
asinfo -v "set-config:context=service;sindex-gc-period=100"
If set true, the node will start up quiesced and will remain quiesced.
It will also ignore the quiesce-undo command.
For details on when to leverage this feature, see the Quiescing a node page.
Global configuration for how often to print ‘ticker’ info to the log in seconds.
Example: Set ticker-interval to 20 dynamically:
asinfo -v "set-config:context=service;ticker-interval=20"Sets the time interval for refreshing the cert-file, key-file and cert-blacklist. Set to 0 to disable periodic refresh of TLS certificates.
Example:
Set tls-refresh-period to 100 seconds dynamically:
asinfo -v "set-config:context=service;tls-refresh-period=100s"How long to wait for success, in milliseconds before timing out a
transaction on the server (typically, but not necessarily, during replica write or
duplicate resolution). This would be overwritten by the client transaction timeout
(if set). Transactions taking longer than this time (or the time specified in the client policy) will return a
timeout and tick the client_write_timeout metric.
Example: Set transaction-max-ms to 2000 dynamically:
asinfo -v "set-config:context=service;transaction-max-ms=2000"How long to wait for success, in milliseconds, before retrying a
transaction.
migrate-retransmit-ms is
used for the migration related retransmits. The default of 1002 is meant to avoid retransmission by default based on the default
transaction-max-ms.
Example: Set transaction-retry-ms to 500 dynamically:
asinfo -v "set-config:context=service;transaction-retry-ms=500"User to run as.
Path on Aerospike node to TLS certificate for authentication with Vault server. See the Vault integration documentation for further details.
A string specifying the Vault namespace name. Only for use with Vault Enterprise. See the Vault integration documentation for further details.
The path on the Vault system to the stored secret. See the Vault integration documentation for further details.
Path on an Aerospike node to a file that contains a token that identifies the Aerospike server to the Vault server. This token is either from your orchestration system or a manual definition on the Vault system. As of Database 6.3, you can dynamically update the vault-token-file value.
If the configuration parameter is dynamically set to the same value, it forces a re-reading of the file and updates the token.
Prior to Database 6.3, vault-token-file is not dynamically settable.
See the Vault integration
documentation for further details.
Example: Update the path to a Vault token:
asinfo -v "set-config:context=service;vault-token-file=/path/to/file"Set a path to a Vault token in the configuration file:
service { ... vault-token-file /path/to/file ...}Protocol, domain name or IP address, and port of Vault service. See the Vault integration documentation for further details.
Xdr
Specifies the authentication mode to be used by XDR when security is enabled in the destination cluster. Allowed values are:
none- Authentication will not be attempted.internal- user credentials are validated internally by the destination cluster, using a hashed password.external- user credentials are validated externally, using LDAP by the destination cluster for example. TLS is required between the clusters for this mode, as the user password is sent in clear text.external-insecure- user credentials are validated externally using LDAP by the destination cluster for example. TLS is not required for this mode, but since the user password is sent in clear text, this mode is not recommended for production systems.pki- use the common-name (CN) in the TLS certificate as the user name (valid for Database 5.7 and later).tls-namemust be configured for this mode. No need to specifyauth-userorauth-password-filein this mode.
Specifies the password of the XDR auth-user. This user must have read/write permissions on a destination node that has security-enabled true.
Value must follow one of these formats. Prefixes file:, env:, env-b64:, vault:, and secrets: are literal strings.
file:/path_to/xaupwd- Read from the filesystem (thefile:prefix is optional).env:XAUPWD- Read from the named environment variable (Database 5.3+).vault:auth-password- the named secret will be read from Vault (Database 5.1+).secrets:AerospikeSecrets:AuthPassword- fetched using Aerospike Secret Agent (Database 6.4+).
Content of the file is the password of the user:
passwordOnDestinationExample:
dc dataCenter1 { node-address-port someIpAddress1 somePort1 ... auth-user someUser auth-password-file /private/security-credentials_DC1.txt ... } }Set auth-password-file dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;auth-password-file=/private/security-credentials_DC1.txt"For XDR, specifies the name of a user who has read/write permissions on a destination node that has security-enabled true.
For background, see Securing XDR with access control, LDAP, and TLS.
Example:
xdr { dc dataCenter1 { node-address-port someIpAddress1 somePort1 ... auth-user someUser auth-password-file /private/security-credentials_DC1.txt ... } }Set auth-user dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;auth-user=someUser"Determines which bins are shipped to the target datacenter. Allowable values:
all(default)no-binsonly-changedonly-specified(removed as of Database 5.3)changed-and-specifiedchanged-or-specified
Some restrictions apply based on the configuredwrite-policy. See the bin policy documentation page.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { bin-policy only-changed ... } }}Set bin-policy dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=nameSpaceName;bin-policy=only-changed"Note: This is
XDR compression-level for dc namespace,not compression-level for storage-engine.
Compression level of data-in-transit to remote destinations.
Allowable range: 1 to 9. A higher value, for example 9, means more efficient but slower compression. A lower value, for example 1, means less efficient but faster compression.
Requires enable-compression true; otherwise, no compression is applied.
See also the metric compression_ratio.
Example:
Set compression-level to 6 (the compression level of XDR 4.X) in the configuration file.
xdr { dc dataCenter1 { node-address-port someIpAddress1 somePort1 namespace someNameSpaceName { ... enable-compression true compression-level 6 ... } }}Set compression-level dynamically to 6 (the compression level of XDR 4.X):
asinfo -v 'set-config:context=xdr;dc=DataCenter1;namespace=someNameSpace;enable-compression=true;'
asinfo -v 'set-config:context=xdr;dc=DataCenter1;namespace=someNameSpace;compression-level=6Record size threshold, in bytes. When at or greater than this threshold, a record will be compressed for transit to remote destinations.
Only applicable when enable-compression is true.
Allowable range is 128 to UINT32_MAX.
Example:
Set compression-threshold to 512.
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { enable-compression true compression-threshold 512 } }}Set compression-threshold dynamically to 512:
asinfo -v 'set-config:context=xdr;dc=DataCenter1;namespace=someNameSpace;compression-threshold=512'Allowed values are:
true- Indicates that the destination is a server running an Aerospike connector capable of receiving change notification messages.false- Indicates that the destination is also an Aerospike cluster.
Specifies the name of a remote datacenter for XDR. Name of the remote datacenter is user-defined.
In Aerospike Database 5.0 and later, this parameter is replaced by dc.
Example:
Below is an example of the datacenter parameter:
xdr { enable-xdr true datacenter DC1 { dc-node-address-port xx.xx.xx.xx 3000 dc-node-address-port yy.yy.yy.yy 3000 dc-node-address-port zz.zz.zz.zz 3000 }}This idle time before a connection is closed on the XDR client. This should always be set to a few seconds lower than the
corresponding destination(s) proto-fd-idle-ms to avoid race conditions
where the destination closes a connection right when the XDR client is sending a new record on it.
XDR is very sensitive to connection errors and will throttle when encountering such errors, potentially resulting in lag and
outstanding digest increases.
Example: Dynamically increasing the connections idle time to 85 seconds:
asinfo -v "set-config:context=xdr;dc=DC1;dc-connections-idle-ms=85000"The number of connections to open per destination node. This typically should not be changed, but for specific low throughput workloads, decreasing the number of connections avoids running into idle connections being terminated by the destination node which is based on the proto-fd-idle-ms setting.
XDR is very sensitive to connection errors and will throttle when encountering such errors, potentially resulting in lag and outstanding digest increases.
Example: Dynamically reducing the number of connections for DC1 to 8:
asinfo -v "set-config:context=xdr;dc=DC1;dc-connections=8"Use dc-use-alternate-services and
alternate-access-address at the destination nodes instead of dc-int-ext-ipmap.
Mapping of the internal
IPs of nodes of the remote cluster to their corresponding external IPs.
Example: Mapping of Internal to External IP
dc-int-ext-ipmap 192.168.1.1 204.153.101.101dc-int-ext-ipmap 192.168.1.2 204.153.101.102...Dynamic changes
asinfo -p <XDRPORT> -v 'config-set:context=xdr;dc=<DATACENTER>;dc-int-ext-ipmap=<INTERNAL_IP>/<EXTERNAL_IP>;action=add' asinfo -p <XDRPORT> -v 'config-set:context=xdr;dc=<DATACENTER>;dc-int-ext-ipmap=<INTERNAL_IP>/<EXTERNAL_IP>;action=remove'Replaced in Aerospike 5.0 with node-address-port.
The address & port of a node in the remote datacenter. Can be set dynamically.
Example: Dynamically adding and removing of a node for DC1:
asinfo -v "set-config:context=xdr;dc=DC1;dc-node-address-port=192.168.55.210:3000;action=add"asinfo -v "set-config:context=xdr;dc=DC1;dc-node-address-port=192.168.55.210:3000;action=remove"Ipv6 example
asinfo -v "set-config:context=xdr;dc=DC1;dc-node-address-port=[fe80::20c:29ff:fea9:df10]:3000;action=add"asinfo -v "set-config:context=xdr;dc=DC1;dc-node-address-port=[fe80::20c:29ff:fea9:df10]:3000;action=remove"Replaced in Aerospike 5.0 with auth-password-file and auth-user.
Specifies the credentials file to be used by XDR to ship to the DC. User must have write or read-write permissions.
File syntax:
credentials{ username xdr_user password xdr_pass}To dynamically specify this use the following command:
asinfo -v "set-config:context=xdr;dc=DC1;dc-security-config-file=/private/aerospike/security_credentials_DC1.txt"This command would trigger a reconnection to the cluster to avoid having a mix of connections using different credentials.
To dynamically unset the security config file:
asinfo -v "set-config:context=xdr;dc=DC1;dc-security-config-file=none"``` See [XDR Advanced Configuration](/database/manage/xdr/static-xdr/#example-configuration-parameters-for-xdr-topologies) for further details.
**Example:**XDR stanza```asciidoc...xdr { enable-xdr true
xdr-digestlog-path /opt/aerospike/xdr/digestlog 100G
datacenter DC1 { dc-node-address-port xx.xx.xx.xx 3000 dc-node-address-port yy.yy.yy.yy 3000 dc-node-address-port zz.zz.zz.zz 3000
dc-use-alternate-services true dc-security-config-file /private/aerospike/security_credentials_DC1.txt } ...
$ more /private/aerospike/security-credentials_DC1.txt credentials { username xdr_user password xdr_pass }If false, bin shipping optimization is disabled at DC level.
Refer xdr-ship-bins
to know about bin shipping optimization.
To dynamically specify this use the following command:
asinfo -v "set-config:context=xdr;dc=DC1;dc-ship-bins=false"Allowed values are:
aerospike- Indicates that the destination is also an aerospike cluster.http- Indicates that the destination is a webserver capable of receiving change notification messages.
Though this config option is dynamic, only the type of skeleton DCs can be changed tohttp(from the defaultaerospike). Once the type is set ashttp, its type cannot be changed toaerospike. If the type is changed dynamically by mistake, the node should be restarted with the correct configuration. Changes to this configuration should be planned accordingly. See Configuring change notification for further details.
Replaced in Aerospike 5.0 with use-alternate-access-address.
If alternate-access-address is set on the destination nodes, specify dc-use-alternate-services true at the source nodes
in order to use the services-alternate IP addresses to connect to the destination nodes (instead of services). To
be used when the remote cluster’s nodes publish IP addresses through access-address which are not accessible over WAN
and alternate IP addresses accessible over WAN through alternate-access-address.
Example: Set dc-use-alternate-services to true post 3.14.1.1:
asinfo -v "set-config:context=xdr;dc=<dc-name>;dc-use-alternate-services=true"Specifies the name of a remote datacenter for XDR. Name of the remote datacenter is user-defined.
The maximum number of dc definitions is 64. The maximum length of a single definition is 31 bytes. Stay within the ASCII character set to avoid using a double-byte character and exceeding the size limit.
Note: Prior to Aerospike Database 5.7, at least one DC needs to be configured statically to enable XDR.
Prior to Database 5.0, this parameter was named datacenter.
Example:
xdr { dc DC1 { node-address-port xx.xx.xx.xx 3000 node-address-port yy.yy.yy.yy 3000 node-address-port zz.zz.zz.zz 3000 namespace someNameSpaceName { ... } }}Set the dc parameter dynamically:
asinfo -h localhost -v "set-config:context=xdr;dc=aerospike_b;action=create"Set the XDR namespace parameter dynamically:
asinfo -h localhost -v "set-config:context=xdr;dc=aerospike_b;namespace=test;action=add"Value in milliseconds as an artificial delay on shipment of all records, including hotkeys and records that are not hot. Minimum value is 0 and maximum value is 5000.
- Must be less than or equal to the value of
hot-key-ms. - Must be 0 if
ship-versions-policyisall. - Cannot exceed the time window specified by
ship-versions-interval.
Example:
In Aerospike 5.0, this parameter is no longer needed.
This configuration initializes the change notification framework in the server (XDR).
Unless this configuration is set to true, HTTP destination types cannot be configured.
See change notification for further details.
Requires a feature the asdb-change-notification feature-key be enabled in the feature-key-file.
For Aerospike 5.0 and later, by default, compression is disabled.
For Aerospike 5.0 through 5.7, the compression threshold is internally set at record sizes of 128 bytes or more. For Aerospike 6.0 and later, the compression threshold is specified by the compression-threshold parameter.
If set to true, the lowest level of compression is applied by default (1).
To set a compression level other than the default,
see related parameter compression-level for XDR dc namespace.
The compression algorithm is zlib.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { enable-compression true } }}Set enable-compression dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;enable-compression=true"In Aerospike 5.0, this parameter is no longer needed.
Enable record entries to be written to the XDR digest log for the node globally, letting
the enable-xdr namespace level setting take effect at the namespace level. This controls whether
digest log entries are being written to the digest log. This therefore practically controls whether
records are being shipped through XDR globally, assuming DCs are configured and available,
xdr-shipping-enabled
is kept at its default value (true) and the enable-xdr configuration is set to true at the
respective namespaces.
Configured DCs that are linked to namespaces will be connected to independently of the value of this setting. To
prevent the connections from being made, you will need to either a) remove all seed
nodes from the datacenter definition, or b) remove the
datacenter from all namespace definitions, or do so
dynamically to break existing connections.
Example:
Set enable-xdr to true dynamically:
asinfo -v "set-config:context=xdr;enable-xdr=true"Replaced in Aerospike 5.0 by forward.
By default XDR writes that originated from another XDR are not forwarded to the specified
destination datacenters. Setting this parameter to true will forward writes that originated
from another XDR to the specified destination datacenters.
Example: Set forward-xdr-writes to true dynamically:
asinfo -v "set-config:context=xdr;forward-xdr-writes=true"By default XDR writes that originated from another XDR are not forwarded to the specified destination datacenters. Setting this parameter to true sends writes that originated from another XDR to the specified destination datacenters. See simple topology example in Linear chain.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { forward true } }}Set forward dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;forward=true"Time (in milliseconds) to wait in between shipping hotkeys, which are records that change frequently. See also delay-ms.
Minimum: 0.
Maximum: 5000.
Replaces xdr-hotkey-time-ms.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { hot-key-ms 1000 } }}Set hot-key-ms dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;hot-key-ms=1000"This specifies the URL to which the change notification will publish the events. A webserver should be listening here to acknowledge the notification and process them. Multiple lines of this configuration can be used to specify multiple URLs. When multiple URLs are specified, XDR will load balance between them.
If the URL starts with https, secure communication will be used.
Else, if it starts with http, plain text communication will be used.
If a directory/file other than the system default should be used for certificate validation
during https communication, it can be done with tls-name config option of the datacenter.
The corresponding tls spec’s ca-cert/ca-path will be used for certificate validation.
Example:
Dynamically adding or removing URLs is similar to that of regular aerospike nodes. By default, asinfo -v displays details only about the node you are connecting to:
asinfo -v "set-config:context=xdr;dc=DC1;http-url=https://ws1.aerospike.com:2111/index.html;action=add"asinfo -v "set-config:context=xdr;dc=DC1;http-url=https://ws1.aerospike.com:2111/index.html;action=remove"For the Aerospike Kafka Connector, to display the configured URLs for any node, use the following syntax:
asinfo -v "get-dc-config"For details about all nodes, use asadm:
asadm -e "enable; asinfo -v get-dc-config"This configuration determines the HTTP protocol that talks to the http destination. See change notification for further details. Allowed values are:
v1- Only HTTP v1.1 protocol is used.
Specifies the name of a bin to exclude from shipping over XDR. You can have multiple ignore-bin entries. By default, all bins are shipped. The value of the bin-policy parameter
determines if this configuration is honored or not.
For examples, see the bin policy documentation.
Example:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { ignore-bin someBinName1 ignore-bin someBinName2 } }}Set ignore-bin dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ignore-bin=binName1"If more than one bin name is passed in asinfo separated by a comma, such as ignore-bin=binName1,binName2, it is considered a single bin named binName1,binName2.
By default, XDR ships user-initiated record deletes.
To not ship records deleted by clients, set this parameter true.
This parameter only affects non-durable deletes.
Durable deletes are always shipped.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { ignore-expunges true } }}Set ignore-expunges dynamically:
asinfo -v "expunges-config:context=xdr;dc=DC1;namespace=namespaceName;ignore-expunges=true"Set-specific parameter to exclude a set from shipping through XDR. You can have multiple ignore-set entries.
For examples, See the set policy documentation.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { ignore-set someSetName1 ignore-set someSetName2 } }}Set ignore-set dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ignore-set=setName1"If more than one set name is passed in asinfo separated by a comma, such as ignore-set=setName1,setName2, it is considered a single set named setName1,setName2.
This parameter specifies the maximum number of partitions that will be recovered at any given point in time. By default, all the partitions pending recovery completion will be recovered partially in each round in round robin fashion. This will be good in cases where the recovery can finish quickly and go back to transaction-q mode. However, if the recovery needs to ship a lot of records for each partition and there are a lot of partitions to recover, the transaction-q of a partitions may overflow by the time its recovery is complete. This will make the partition go into recovery again and this vicious cycle may continue. In these kind of situations, its better to focus on fewer partitions and finish their recovery as soon as possible.
Example: Change the parameter dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;max-recoveries-interleaved=10"Number of records per second to ship using XDR. That is, number of records written per second to the remote datacenters. Setting to 0 will stop throughput. The lowest value for max-throughput is 100. The value for max-throughput can only be in increments of 100. e.g. 100, 200, 1000, etc.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { max-throughput 50000 } }}Set max-throughput dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;max-throughput=50000"This parameter specifies the number of service threads used by XDR to read records and ship to the
destination DC. By default XDR uses all the service threads. Each service thread opens one connection
to each destination node. This can lead to lot of connections, especially if the number of service
threads are high. This configuration can be used to limit the number of connections made to the
destination by limiting the number of service threads used.
Service threads are also used by XDR to read records locally. If this
configuration is too low, XDR throughput could be impacted as it may not be able to read enough records
in parallel.
Removed in Database 6.4. In that version, a partition to service thread affinity is introduced. The number of service threads used by XDR is as follows:
- For a given partition a service thread is randomly/deterministically assigned (affinity).
- A given partition will always have one and only one service thread.
- There cannot be more than one service thread assigned to a partition.
- There can be more than one partition assigned to a service thread.
- This also means that it is possible to end up, in some cases, with some service threads having to handle two partitions, some with one and some having none, for the same namespace.
When clusters change, open connections may become idle. Such idle connections will be reaped after 5 minutes.
Example: Change the parameter dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;max-used-service-threads=32"asinfo -v "set-config:context=xdr;dc=DC1;max-used-service-threads=0"Note: this is namespace in the XDR context, not namespace in the namespace context.
Search for namespace, and look at the Context
heading to make sure you are working with the correct parameter.
Defines a namespace to be shipped to a remote datacenter over XDR.
- The parameter must be nested in the
dcsection of thexdrstanza. - The parameter must be followed by a variable name of your choice to refer to the namespace.
For more details, see Configure XDR.
Example: Define a namespace to be shipped to a remote datacenter over XDR:
xdr { dc DataCenter1 { namespace someNameSpaceName1 { ... } namespace someNameSpaceName2 { ... } }}Add a namespace to a datacenter dynamically:
asinfo -v "set-config:context=xdr;dc=DataCenter1;namespace=someNameSpaceName1;action=add"Remove a namespace from a datacenter dynamically:
asinfo -v "set-config:context=xdr;dc=DataCenter1;namespace=someNameSpaceName1;action=remove"The address and port of a node in the remote datacenter or of a connector. See the Change Notification Configuration page for details on how to configure outbound connectors.
Multiple nodes can be specified.
For TLS, an optional tlsname is specified after the port. For details on setting up TLS and someTlsName,
see TLS Configuration.
Example: Basic XDR stanza in configuration file:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 someTlsName1 node-address-port 10.2.0.1 3000 someTlsName2 namespace someNameSpace { ... } }}Add and remove nodes for DC1 dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;node-address-port=192.168.55.210:3000;action=add"asinfo -v "set-config:context=xdr;dc=DC1;node-address-port=192.168.55.211:3000;action=remove"IPv6 example:
asinfo -v "set-config:context=xdr;dc=DC1;node-address-port=[fe80::20c:29ff:fea9:df10]:3000;action=add"asinfo -v "set-config:context=xdr;dc=DC1;node-address-port=[fe80::20c:29ff:fea9:df10]:3000;action=remove"The period in milliseconds at which the DC-thread processes partitions for XDR shipment.
Decreasing period-ms decreases the latency of replication but at the cost of increase in CPU.
For a discussion of the DC and other XDR threads, see Lifecycle of XDR record shipment with metrics.
Minimum: 5.
Maximum: 1000.
Example:
Set period-ms to 50 milliseconds in configuration file
xdr { dc DC1 { period-ms 50 namespace someNameSpace { ... } }}Set period-ms to 50 dynamically
asinfo -v "set-config:context=xdr;dc=DC1;period-ms=50"Create a mapping between a local namespace and a remote namespace with a different name.
- This configuration can be set only when the remote DC is not connected.
- To unset dynamically, use the
nullspecial keyword. - The value of
remote-namespacecannot be the name of a local namespace. - The local namespace should not exist on the remote destination (if it does, only shipping to that namespace is supported, which is done without the use of this configuration parameter).
- The value of
remote-namespacemust be unique across namespaces in the local DC (two or more namespaces in a cluster cannot map to the same remote namespace, but two different clusters can each map to the same namespace in a third cluster).
Example:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace A { remote-namespace B } }}Set remote-namespace dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=A;remote-namespace=B"Use the reserved word null to unset remote-namespace dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=A;remote-namespace=null"Number of milliseconds that XDR waits before dequeuing a record from the in-memory transaction queue of a namespace configured for Strong Consistency (SC).
This gives time for the client-write replicate to finish.
With SC, XDR does not ship a record unless the record is successfully replicated.
Setting sc-replication-wait too low might cause XDR redundant reads and retries.
Minimum: 5.
Maximum: 1000.
Example:
Set sc-replication-wait-ms to 50 in configuration file:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace someNameSpace { sc-replication-wait-ms 50 ... } }}Set sc-replication-wait-ms to 50 dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=someNameSpace;sc-replication-wait-ms=50"ship-bin-luts is necessary for the XDR bin convergence feature. When this is enabled, XDR ships bin-level last-update-time (LUT). Bin-level LUTs are necessary to determine the winner when trying resolve conflicts in mesh/active-active topologies. Prior to Database 6.3, ship-bin-luts is not allowed for connectors. See bin convergence for more information.
Example:
xdr { src-id 1 dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { bin-policy only-changed ship-bin-luts true } }}Set ship-bin-luts dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ship-bin-luts=true"Specifies the name of a bin to ship over XDR. You can have multiple ship-bin entries.
By default, all bins are shipped.
The value of the bin-policy configuration parameter
determines if this configuration is honored or not.
For examples, see the bin policy documentation.
Example:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { bin-policy changed-and-specified ship-bin someBinName1 ship-bin someBinName2 } }}Set ship-bin dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ship-bin=binName1"Specifies if XDR ships record deletes from evictions and expirations that are the result of the Namespace Supervisor (nsup). Truncates are not shipped. For more information, see Namespace Data Retention.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { ship-nsup-deletes true } }}Set ship-nsup-deletes dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ship-nsup-deletes=true"Replaced with the bin-policy configuration parameter in Database 5.2 and later.
Specifies that XDR should ship only specific sets in a namespace.
For examples, see the set policy documentation.
This setting should be accompanied at the namespace level
with the ship-set parameter.
Example:
asciidocxdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { ship-only-specified-sets true ship-set someSetName1 ship-set someSetName2 } }}Set ship-only-specified-sets dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ship-only-specified-sets=true"Specifies the name of a set to ship over XDR. You can have multiple ship-set entries.
By default, all sets are shipped.
To ship only specific sets,
use the ship-only-specified-sets parameter
accompanied by multiple ship-set entries for the desired sets to ship.
For examples, see the set policy documentation.
Example:
xdr { dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { ship-only-specified-sets true ship-set someSetName1 ship-set someSetName2 } }}Set ship-set dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=namespaceName;ship-set=setName1"A nonzero value that specifies a time window in seconds within which XDR is allowed to skip versions. It is guaranteed that at least one (written) version per time window will be shipped. Allowable range is 1 to 3600 in seconds. Also supports the S,M,H,D suffixes (20M = 20 minutes = 1200 seconds).
Relevant only if ship-versions-policy is true. If set to 0, every version is shipped.
This policy controls how XDR ships versions of modified records when facing lag between the source cluster and a destination.
-
latestcontinues to ship the most recent version of the record, same as versions earlier than 7.2. -
intervalattempts to ship at least one version pership-versions-intervalin seconds, otherwise it applies back-pressure by refusing further writes until the record’s current version has shipped. -
allconfirms that every version of the record reaches the remote destination, and blocks further writes to the record until confirmation.
If ship-versions-policy is all, delay-ms must be 0. delay-ms cannot exceed the time window specified by ship-versions-interval.
Allowed values are 0-255. Necessary for the XDR bin convergence feature. Each DC involved in the XDR topology must pick a unique value. Breaks ties that may happen with the bin-level last-update-time. See bin convergence feature.
Example:
xdr { src-id 1 dc DC1 { node-address-port 10.0.0.1 3000 namespace nameSpaceName { bin-policy only-changed ship-bin-luts true } }}Set src-id dynamically:
asinfo -v "set-config:context=xdr;src-namespace=3\n```
:::note `id=` is deprecated in `set-config` Database 7.2 replaced with `namespace=`.:::This parameter specifies which TLS parameters to use for the specific XDR datacenter TLS connections.
The TLS parameters used are configured under the matching tls
sub-stanza. This also implicitly specifies the TLS name the node will present on outgoing XDR client
connections. The remote cluster should have a tls-authenticate-client
directive specifying the same TLS name, or false, or any.
See TLS name clarification for further details.
This can either be set to:
-
CLUSTER_NAME(literally) which will then pick the cluster-name defined in the Aerospike config file. -
HOST_NAME(literally) which will then pick up the hostname from the system. -
User specific where any string can be picked, for example,
my-tls-name.
This should match the certificate as well as what the client will be sending. See the TLS Guide for more information.
Example:
tls-name CLUSTER_NAMEtls-name <hostname>tls-name my-tls-nameThe remote cluster’s IP address, tls-name and tls-port number. The TLS name provided through this configuration parameter is the TLS name the cluster node expects the remote DC to present on XDR connections the local node would initiate. See TLS Name Clarification for details.
In Aerospike 5.0, superseded by node-address-port
Example:
tls-node 192.168.55.210 tls-node1 4000Maximum number of elements allowed
in XDR’s in-memory transaction queue
per partition, per namespace, per datacenter.
Each element is 25 bytes.
Value must be a power of 2
and must be expressed as an integer, not an exponent.
Default: 16*1024 = 16384.
Minimum: 1024.
Maximum: 1048576.
Example:
Set transaction-queue-limit to twice its default value in the configuration file.
xdr { dc dataCenter1 { node-address-port someIpAddress1 somePort1 namespace someNameSpaceName { ... transaction-queue-limit 32768 ... } }}Set transaction-queue-limit dynamically to twice its default value:
asinfo -v 'set-config:context=xdr;dc=DataCenter1;namespace=someNameSpace;transaction-queue-limit=32768'If alternate-access-address is set on the destination nodes, specify use-alternate-access-address true at the source nodes
in order to use the services-alternate IP addresses to connect to the destination nodes (instead of services). To
be used when the remote cluster’s nodes publish IP addresses through access-address which are not accessible over WAN
and alternate IP addresses accessible over WAN through alternate-access-address.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 use-alternate-access-address true namespace nameSpaceName { ... } }}Set use-alternate-access-address dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;use-alternate-access-address=true"Determines the behavior of XDR writes on the target datacenter. Allowable values:
auto(default)updatereplace
Some restrictions apply based on the configuredbin-policy. See the write policy documentation.
Example:
xdr { dc DC1 { node-address-port 10.1.0.1 3000 namespace nameSpaceName { write-policy replace ... } }}Set write-policy dynamically:
asinfo -v "set-config:context=xdr;dc=DC1;namespace=nameSpaceName;write-policy=replace"Number of threads processing the responses from the destination cluster(s). Replaces xdr-threads.
In Aerospike 5.0, replaced by enable-compression.
Packet size threshold in bytes beyond which the packets will be compressed. 0 means
compression disabled. The compression happens on the XDR read threads, and happens once
per DC (the same record will be compressed twice when shipped to 2 different DCs). If
CPU seems constrained when compression is enabled, increasing the number of xdr-read-threads
may help.
Example:
asinfo -v 'set-config:context=xdr;xdr-compression-threshold=<VALUE>'In Aerospike 5.0, replaced by ignore-expunges.
This option determines if XDR will ship the deletes of records.
Example:
Set xdr-delete-shipping-enabled dynamically to false :
asinfo -v "set-config:context=xdr;xdr-delete-shipping-enabled=false"This configuration controls the time, in milliseconds, of 2 different batch/throttling mechanisms around the digestlog io:
-
Time to wait for the queue to be written into the digestlog if the limit of 100 entries has not been reached.
-
Time to wait before reading digest log entries from the digest log if the limit of 100 entries has not been reached.
Path where the digestlog is located.
By convention, it is located in /opt/aerospike/digestlog. When the XDR process is initially started, it
will create a digestlog file of the size specified in the configuration. For example, xdr-digestlog-path /opt/aerospike/digestlog 100G will
create a digestlog of 100G. Each digestlog entry takes up 80 bytes. Master and prole records end up having entries in the digestlog, but
proles will be used only when a node at the source cluster goes down. It is usually fine to have the digestlog on rotational drives as
reads from and writes to the digestlog are done in batches of 100.
Changing this size or location requires a restart of the XDR process. In order to modify the digestlog size in a running XDR process, update the configuration, backup or delete the existing digestlog and restart XDR to recreate the digestlog file with the new size.
Controls how much time (in milliseconds) to wait in between shipping of hot-keys.
In Aerospike Database EE 5.0, replaced by hot-key-ms.
Example:
asinfo -v 'set-config:context=xdr;xdr-hotkey-time-ms=<VALUE>'Timeout in millisecond when xdr does info calls. Also used as a time out for remote cluster tending as well.
Example:
asinfo -v 'set-config:context=xdr;xdr-info-timeout=<VALUE>'Maximum bandwidth to be used by XDR to ship records to destination clusters.
Example:
asinfo -v 'set-config:context=xdr;xdr-max-ship-bandwidth=<VALUE>'In Aerospike 5.0, replaced by max-throughput.
Maximum throughput of records that are sent to the remote datacenters (number of records written per second to the remote datacenters). This is on a per node basis.
0 means unlimited. In case of shipping to multiple destination clusters, this control the maximum throughput per destination,
so the total throughput will be at most the maximum throughput times the number of destination. For example,
an xdr-max-ship-throughput limit of 1000 when shipping to 3 destination will give a maximum
total throughput of 3 x 1000 = 3000.
XDR actually turns this into a maximum number of objects that can be inflight, based on the link latency for a given DC. For example,
if a link between 2 DCs has a round trip latency of 10ms, putting 1 record at a time on the link (1 record in flight) would allow for
100 records to be written every second (throughput of 100). In default configuration (no xdr-max-ship-throughput set) the derived
value for the maximum number of objects that can be in flight at one time is 50000. If the records in flight exceed this value,
XDR will start to throttle.
Example:
asinfo -v 'set-config:context=xdr;xdr-max-ship-throughput=<VALUE>'Digest log free percentage (dlog_free_pct) under which to trigger stop_writes
and reject application writes. Default value 0 will not disallow writes and will cause older entries in the digest log to be overwritten when the digest log is full.
A recommended value to avoid overwriting older entries in the digest log and miss shipping some records would be 5 percent.
Example:
Set xdr-min-digestlog-free-pct dynamically to 5%:
asinfo -v "set-config:context=xdr;xdr-min-digestlog-free-pct=5"Replaced in Aerospike 5.0 with ship-nsup-deletes.
This option will determine if XDR will ship deletes which are generated as
effect of evictions, expirations or set-delete. Truncates will not be shipped
in any case.
Example: Set xdr-nsup-deletes-enabled to true dynamically:
asinfo -v "set-config:context=xdr;xdr-nsup-deletes-enabled=true"Number of threads that are used to read from ASD.
Example:
asinfo -v 'set-config:context=xdr;xdr-read-threads=<VALUE>'By default, XDR will ship the complete record and will replace at destination. Turning xdr-ship-bins to true will only ship the modified or new bins in most cases.
Example: Set xdr-ship-bins to true dynamically:
asinfo -v "set-config:context=xdr;xdr-ship-bins=true"Enable shipping to remote node while accepting digest logs. Used for
suspending shipping.
Configured DCs that are linked to namespaces will be connected to independently of the value of this setting. To
prevent the connections from being made, you will need to either a) remove all seed
nodes from the datacenter definition, or b) remove the
datacenter from all namespace definitions, or do so
dynamically to break existing connections.
Example:
asinfo -v 'set-config:context=xdr;xdr-shipping-enabled=<true | false>'Timeout in millisecond when shipping to destination cluster(s). In case of timeout, digest of the records will be relogged and shipping will be throttled until the destination is marked as down or connectivity is recovered.
Example:
asinfo -v 'set-config:context=xdr;xdr-write-timeout=<VALUE>'