Aerospike Tools Configuration File

Aerospike tools read their startup options from TOML configuration files. Use configuration files to specify commonly used options or to manage multiple options in groups.

Invoke any tool with the --help option to see if it has the capability to read a configuration file.

A tool that supports a configuration file has a help message indicating the allowable options and the group that it belongs to.

Example:

 --no-config-file
                      Do not read any config file. Default: disabled
 --instance <name>
                      Section with this instance is read. For example, if instance `a` is specified, 
                      then sections `cluster_a` and `aql_a` are read.
 --config-file <path>
                      Read this file after default configuration file.
 --only-config-file <path>
                      Read only this configuration file.

Defaults

Aerospike tools read configurations from four possible sources.

File Name and Path (Linux)	Purpose	Read Order
/etc/aerospike/astools.conf	Global options	Read first.
~/.aerospike/astools.conf	User-specific options	Read second. If any configurations conflict with the global options, this file takes precedence.
--config-file	A file specified with the optional runtime flag --config-file	Read third. If any configurations conflict with global or user-specific options, this file takes precedence.
Individual runtime configuration parameters	Parameters passed individually, outside of a file	Read fourth. If any parameters conflict with previously read options, the runtime-specified values take precedence.

info

asadm and asinfo require additional dependencies: toml and jsonschema. To work around those dependencies, use the --no-config-file option.

The following describes how to specify options while invoking tools.

Command line syntax

option type	Usage	constraints
Long options	Use "equals": --option=value.	No spaces. No concat.
Short option -P	Use "concat": -Pvalue.	No spaces. No equals.
Short option for all others	Only support "space" or "concat": -O value.	No equals.

There are some special cases.

• Provide an empty string for password to trigger a prompt.
• If the value in the options has a preceding - (hyphen), an extra space must appear before the hyphen: --tls-protocol=" -all +TLSv1.2"

Configuration file format

The Aerospike tools configuration file is a plain text file in TOML format that can be created using any text editor.

Any long option supported on the command line when running any Aerospike tool can be provided in a configuration file as well. To get the list of available options for a tool, run it with the --help option. For example: asadm --help.

The syntax for specifying options in a configuration file is similar to command-line syntax. In a configuration file, however, omit the leading two dashes from the option name and specify only one option per line. For example, --port=3000 and --host=localhost on the command line are specified as port=3000 and host="localhost" on separate lines in a configuration file.

Empty lines in the configuration files are ignored. Non-empty lines can take any of the following forms:

# comment

Comment lines start with # or ;. A # comment can start in the middle of a line as well.

[group]

group is the name of the program or group for which you want to set options.
After a group line, any option-setting lines apply to the named group until
the end of the configuration file or another group line is given.
Option group names are not case-sensitive.

opt_name

This is equivalent to --opt_name on the command line.

opt_name=value

This is equivalent to --opt_name=value on the command line.
In a configuration file, you can have spaces around the = character,
something that is not true on the command line. The value optionally
can be enclosed within single quotation marks or double quotation
marks, which is useful if the value contains a # comment character.

Leading and trailing spaces are automatically deleted from option names and values.

The following rules apply to the options and values in the configuration file:

1. Option values are of string, integer and boolean type. String are to be specified in quotes. Any other value type would fail with an error message.

Some examples:

host="localhost:tls-name:3000"
port=3000
tls-enable=true

2. Multiple instances of the same option or group in the same file is not allowed.

3. In case of multiple instances of a given option or group in different file, the last instance takes precedence.

If an option group name is the same as a program name, options in the group apply specifically to that program. For example, the [asadm] and [aql] groups apply to the asadm and the aql program, respectively.

The [cluster] group is read by all tools, under which the connection end point, security and encryption options are specified.

Here is a typical global configuration file:

[cluster]
host="localhost:3000"
port=3000
tls-enable=false
user="" # Empty string is for no user.

[asadm]
service-alumni=false

[aql]
outputmode="table"

Includes

You can use an [include] group in configuration files to specify other configuration files by file path or directory. For example, to include a file at /home/mydir/astools.conf and to read any configuration files found in the /home/mydir directory, include these lines:

[include]
file="/home/mydir/astools.conf"
directory="/home/mydir"

danger

The asconfig and UDA tools do not support include functionality in their configuration files.

Aerospike makes no guarantee about the order in which configuration files in the directory will be read.

Aerospike reads the options in the following order. Files that are read later overwrite files that are read earlier in case of conflicts.

1. A configuration file that has an [include] group.
2. Files specified by [include] and a file path.
3. Files in an [include] directory.

The contents of an included configuration file should contain groups of options, each preceded by a [group] line that indicates the program to which the options apply.

  [cluster]
  host="localhost"

  [cluster_red]
  host="redhost"

  [asadm]
  timeout=5

  [asadm_red]
  timeout=1000

Instances

You can append the instance name to a group in the configuration file, which lets you manage groups using the name.

A group name without an instance suffix is considered a global group, and global groups are loaded by default. While invoking tools, you can use the command line option --instance to load a specific instance of a group.

For example:

asadm --instance red

If multiple copies of the same instance are found, the copy that is read last takes precedence.

If the user invokes a tool with asadm --instance red:

1. Any specific instance overrides a global instance. If both [cluster] and [cluster_red] are specified, then the values in [cluster] are ignored.

2. In the case where [cluster_red] is not specified, startup fails with an error. To start a program with a certain instance, [cluster_INSTANCE] is compulsory.

3. In the case of a program specific group, the default is global (that is, if [asadm_red] is not found, options are read from the [asadm] group).

4. The [include] group does not allow for a suffix, it is only global.