Configure Aerospike Database

This page describes how to configure a Database cluster node using the configuration file, aerospike.conf.

The configuration file is divided into different contexts, some of which are optional. These contexts can be in any order in the configuration file. A context can be further divided into sub-contexts. The maximum length of a line in the configuration file is 1,024 characters. The default location of the configuration file is /etc/aerospike/aerospike.conf.

Sample configuration file

The following sample file shows the structure of aerospike.conf with the most common contexts and sub-contexts. The contexts in this example are empty and do not have actual parameters, indicated by empty braces {}. Sub-contexts are indented.

Caution

This is not a working configuration example. Do not copy and try to use it as-is. It will not work without adding your parameters.

service {}               # Tuning parameters, process owner, feature
                         # key file

network {                # Used to configure intracluster and
                         # application-node communications
    service {}           # Tools/Application communications protocol
    fabric {}            # Intracluster communications protocol
    admin {}             # Dedicated administration protocol
    heartbeat {}         # Cluster formation protocol
}

security {               # (Optional, Enterprise Edition only) to enable
                         # access control on the cluster
}

logging {}               # Logging configuration

xdr {                    # (Optional, Enterprise Edition only) Configure
                         # Cross-Datacenter Replication
}

namespace {              # Define namespace record policies and storage
                         # engine
    storage-engine {}    # Configure data storage for the namespace
    set {}               # (Optional) Set specific record policies
}

mod-lua {                # location of UDF modules
}

Configuration file changes

The following examples show how aerospike.conf changed in recent Database releases.

Database 8.1.0 and later

# Aerospike database developer configuration file.

service {
  run-as-daemon false # To work with gdb, and make console logging visible.

  # The number of concurrent connections to the database is limited by
  # proto-fd-max, and by the system's maximum number of open file descriptors.
  # See "man limits.conf" for how to set the system's "nofile" limit.
  proto-fd-max 1024

  work-directory run/work
  pidfile run/asd.pid
  cluster-name cakery
}

mod-lua {
  user-path run/work/usr/udf/lua
}

logging {
  # Log file must be an absolute path.
  file run/log/aerospike.log {
    context any info
  }

  console {
    context any info
  }
}

network {
  service {
    address any
    port 3000
  }

  heartbeat {
    mode multicast
    multicast-group 239.1.99.222
    port 9918

    # To use unicast-mesh heartbeats, remove the 3 lines above, and see
    # aerospike_mesh.conf for alternative.

    interval 150
    timeout 10
  }

  fabric {
    port 3001
  }

  admin {
    port 3003
    address any
  }
}

namespace test {
  replication-factor 2

  storage-engine memory {
    data-size 4G
  }
}

Prior to Database 7.0.0

 # Aerospike database configuration file.

service {
  user root
  group root
  pidfile /var/run/aerospike/asd.pid
  proto-fd-max 15000
}

logging {
  # Log file must be an absolute path.
  file /var/log/aerospike/aerospike.log {
    context any info
  }
}

network {
  service {
    address any
    port 3000
  }

  heartbeat {
    mode multicast
    multicast-group 239.1.99.222
    port 9918

    # To use unicast-mesh heartbeats, remove the 3 lines above, and see
    # aerospike_mesh.conf for alternative.

    interval 150
    timeout 10
  }

  fabric {
    port 3001
  }

  info {
    port 3003
  }
}

namespace test {
  replication-factor 2
  memory-size 4G

  storage-engine memory
}

Note

You can use any port between 1024 and 65335 for Aerospike, as long as the port is not in use by an existing process.

YAML configuration

Starting with Database 8.1.1, Aerospike supports YAML format configuration files as a preview feature. This format is similar to that used by the asconfig tool and the Aerospike Kubernetes Operator.

Note

This preview feature requires a startup flag when starting the server. Functionality may change in future releases.

Configuration steps

1. (If necessary) Obtain a feature-key file.
2. Configure network service and heartbeat sub-contexts.
3. Configure namespaces.
4. Configuring Log Files and Manually Rotating the Aerospike Log File.
5. (Optional) Configure security.
6. (Optional) Configure rack-awareness.
7. (Optional) Configure cross-datacenter replication.

Enable YAML configuration

To use a YAML configuration file, start the server with the --preview yaml-config flag.

Caution

Prior to Database 8.2.0, the --experimental flag enabled preview features. Database 8.2.0 and later reject --experimental. If you are running Database 8.1.1 or 8.1.2, use --experimental in place of --preview yaml-config in the following commands. For more information, see Aerospike Daemon CLI options.

asd --preview yaml-config --config-file /etc/aerospike/aerospike.yaml

Without the --preview yaml-config flag, the server reads the file with the traditional .conf parser.

The server validates the YAML configuration against the default JSON schema packaged at /opt/aerospike/schema/aerospike_config_schema.json. To use a custom schema, specify it with the --schema-file flag:

asd --preview yaml-config --config-file /etc/aerospike/aerospike.yaml --schema-file SCHEMA_FILE_PATH

Replace SCHEMA_FILE_PATH with the absolute path to your custom JSON schema file.

Convert existing configurations

Use the asconfig tool to convert an existing Aerospike configuration file to YAML format:

asconfig convert --aerospike-version "8.1.0" --output aerospike.yaml aerospike.conf

Required updates after running asconfig

While asconfig generates a standard YAML format, you must make minor updates to align the YAML configuration file with the server’s validation requirements. After converting your configuration, apply the following adjustments:

1. Convert arrays to maps (keyed objects):
   • namespaces, namespaces[].sets
   • network.tls
   • xdr.dcs, xdr.dcs[].namespaces
2. Remove name fields that were used inside array entries; the name now becomes the map key.
3. Update logging sinks to typed entries with contexts (see schema for valid types/contexts):
   • type: console uses only contexts
   • type: file requires path plus contexts
   • type: syslog supports facility, path, tag, and contexts
4. (Optional) Use unit-aware values for size/time settings. Optionally use { value, unit } objects where supported. Plain numeric values are still valid. Refer to the schema for the authoritative list of unit-capable fields and allowed units.

For the authoritative format, reference /opt/aerospike/schema/aerospike_config_schema.json.

Example config changes

YAML configuration as output by asconfig.

# asconfig output (not valid for the server's YAML parser)
service:
  cluster-name: my-cluster
  pidfile: /var/run/aerospike/asd.pid

logging:
  - name: console
    any: info

network:
  service:
    addresses:
      - any
    port: 3000
  admin:
    addresses:
      - any
    port: 3003
  fabric:
    port: 3001
  heartbeat:
    mode: mesh
    port: 3002
    addresses:
      - local
    interval: 150
    timeout: 10

namespaces:
  - name: test
    replication-factor: 2
    storage-engine:
      type: memory
      data-size: 4294967296

The configuration after aligning it with the database schema.

# server YAML format
service:
  cluster-name: my-cluster
  pidfile: /var/run/aerospike/asd.pid

logging:
  - type: console
    contexts:
      any: info

network:
  service:
    addresses:
      - any
    port: 3000
  admin:
    addresses:
      - any
    port: 3003
  fabric:
    port: 3001
  heartbeat:
    mode: mesh
    port: 3002
    addresses:
      - local
    interval: 150
    timeout: 10

namespaces:
  test:
    replication-factor: 2
    storage-engine:
      type: memory
      data-size:
        value: 4
        unit: g

Related content

• Troubleshooting guide
• Knowledge base
• Reference manuals:
  • Configuration parameters
  • Info commands
  • Metrics
  • Server log messages