Skip to main content

Configuring AVS

AVS uses a single configuration file. The file's default location is /etc/aerospike-proximus/aerospike-proximus.yml.

The configuration file is divided into different contexts, some of which are optional. These contexts can be in any order in the configuration file.

The maximum length of a line in the configuration file is 1,024 characters. (Prior to Aerospike Server 5.0, the line length limit was 256 characters.)

The following example shows the structure of aerospike-proximus.yml. Some of the configuration options shown below are empty and do not have actual parameters, indicated by empty braces { }.


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

# Custom node-id. It will be auto-generated if not specified.
# node-id: a1

# Unique identifier for this cluster.
cluster-name: aerospike-proximus

# Aerospike vector-service enabled license file
feature-key-file: /etc/aerospike-proximus/features.conf

# The Proximus service listening ports, TLS and network interface.
# Required when running behind NAT
# default:
# # List of externally accessible addresses and ports for this Proximus instance.
# - address:
# port: 5000

# Management API listening ports, TLS and network interface.
5040: { }

# Intra cluster interconnect listening ports, TLS and network interface.

- address:
port: 5001

# Target Aerospike cluster
- localhost:
port: 3000

# Indexing configuration
max-entries: 5000000

# The logging properties.
#format: json
#file: /var/log/aerospike-proximus/aerospike-proximus.log
enable-console-logging: true
# metrics-ticker: info
# root: debug

The configuration has the following sections

  • cluster - configures the AVS cluster
  • feature-key-file - AVS license file
  • service - configures the AVS listening ports
  • manage - configures the management API listening ports
  • interconnect - configures intra-cluster listening ports
  • heartbeat - configures heartbeat-based AVS cluster discovery
  • aerospike - configures connectivity and performance options to the target Aerospike Server
  • logging - configures AVS logging


The cluster section configures the AVS cluster.

node-idnoUnique-id derived from the node’s service IP address and port.A unique node-id for this node as a hexadecimal formatted long number. E.g. 7f0000011388
cluster-nameyesUnique name for the Proximus cluster E.g. proximus-db-1

Feature Key file

An Aerospike feature key file which has the vector-service key enabled. Contact your Vector Search point of contact or Aerospike account manager if you need assistance.


The service section primarily configures the networking between Proximus and Proximus clients.

portsyesThe map of ports the Proximus listens on, to each port specific configuration. See Ports for details .
advertised-listenersnoA map of advertised-listener names to advertised endpoint. See Advertised Listener for details.
io-threadsnoNumber of available processorsThe number of IO threads to read, parse incoming requests.
worker-threadsnoNumber of available processorsThe number of threads that will invoke the connector to dispatch a record.
cluster-namenoproduct-nameGroup or cluster this connector instance belongs to. Used for grouping instances in Prometheus.
max-inbound-message-sizeno8388608Maximum uncompressed size (in bytes) for inbound messages.


You can use the Management and Metrics API to query and manage the outbound server metrics and logs via a REST endpoint. These settings are for using the manage subsection of the service section to specify the endpoint and (optionally) TLS settings for securing connections.

portsyesThe map of ports the Proximus management API listens on, to each port specific configuration. See Ports for details


The service section primarily configures the networking between Proximus clusters.

portsyesThe map of ports the Proximus interconnect listens on, to each port specific configuration. See Ports for details


This section configures heartbeat communication over interconnect ports between Proximus cluster instances for discovery, cluster formation and maintenance.

intervalno500Heartbeat message interval in milliseconds.
timeoutno5000Peer node timeout interval in milliseconds. If no heartbeat is received from the peer in this interval,it is considered unreachable.
seedsnoA seed list of Advertised Listeners for Proximus peer instances.


This describes the configuration for each listening port

addressesno0.0.0.0The list of interface IP addresses the connector binds to. Use for all interfaces.

Advertised Listener

An advertised listener is external (NATed) address,port combination that can be used by clients to access the Proximus service on a node that differs from the actual address,port Proximus listens on. This describes the configuration for each advertised listener.

addressyesAdvertised IP address or hostname
portyesAdvertised port

Flow Control

This configures Proximus behavior under heavy load.

Flow control is enabled when the heap or direct memory usage breaches the high water mark percentage. When flow control is enabled, a response is sent on the gRPC stream only when the stream is ready. If the stream is not ready after stream-ready-timeout milliseconds, the stream is closed.

Flow control is disabled when the heap and direct memory usage comes back below low water mark percentage.

memory-high-water-mark-percentageno80The percentage of heap or direct memory at which flow control is enabled.
memory-low-water-mark-percentageno60The percentage of heap and direct memory at which flow control is disabled.
periodno10The period in milliseconds at which flow control detection is run.
stream-ready-timeoutno10000 (10 seconds)The time in milliseconds to wait for a gRPC stream to be ready when flow control is enabled.
minimum-enable-timeno10000 (10 seconds)The minimum time in milliseconds to enable flow control before it can be disabled again.


Configure the connection properties that the Proximus must use when connecting to the target (destination) Aerospike database.

The configuration options are

seedsyesList of Aerospike seeds. See seeds
client-policynoSee Aerospike client policy properties.

Client Policy

cluster-namenoCluster name of the destination Aerospike cluster
unary-event-loopsnoNumber of available processors.Number of event loops to process unary requests like get, put, exists, etc from the client.
batch-event-loopsno2Number of event loops to process batch requests from the client.
query-event-loopsno4Number of event loops to process query and scan requests from the client.
auth-modenoINTERNALAerospike auth mode can be INTERNAL or EXTERNAL
timeoutno1000Cluster tend info call timeout in milliseconds. The timeout when opening a connection to the server node for the first time and when polling each node for cluster status.
login-timeoutno5000Login timeout in milliseconds. The timeout is used when user authentication is enabled and a node login is being performed.
close-timeoutno0Cluster close timeout in milliseconds. Time to wait for pending async commands to complete. Use 0 for no timeout.
min-conns-per-nodeno0Minimum number of synchronous connections allowed per server node. Preallocate min connections on client node creation. The client will periodically allocate new connections if count falls below min connections.
max-conns-per-nodeno100Maximum number of synchronous connections allowed per server node. Transactions will go through retry logic and potentially fail with "ResultCode.NO_MORE_CONNECTIONS" if the maximum number of connections would be exceeded.
conn-pools-per-nodeno1Number of synchronous connection pools used for each node. Machines with 8 cpu cores or less usually need just one connection pool per node. Machines with a large number of cpu cores may have their synchronous performance limited by contention for pooled connections. Contention for pooled connections can be reduced by creating multiple mini connection pools per node.
max-socket-idleno0Maximum socket idle in seconds. Socket connection pools will discard sockets that have been idle longer than the maximum. Maximum socket idle in seconds. Socket connection pools will discard sockets that have been idle longer than the maximum.
max-error-rateno0Maximum number of errors allowed per node per before backoff algorithm throws exception on database commands to that node. If maxErrorRate is zero, there is no error limit and the exception will never be thrown.
error-rate-windowno1The number of cluster tend iterations that defines the window for maxErrorRate. One tend iteration is defined as `tendInterval` plus the time to tend all nodes. At the end of the window, the error count is reset to zero and backoff state is removed on all nodes.
tend-intervalno1000Interval in milliseconds between cluster tends by maintenance thread.
keep-alivenoSee keepAlive.
ip-mapnoSee ipMap.
use-services-alternatenofalseShould use "services-alternate" instead of "services" in info request during cluster tending. "services-alternate" returns server configured external IP addresses that client uses to talk to nodes. "services-alternate" can be used in place of providing a client "ipMap".
rack-awarenoSee rackAware.
rack-idnoSee rackId.
rack-idsnoSee rackIds.


This section configures index usage and maintenance operations.

cachenoSee Cache


max-entriesno2000000The maximum number of vector graph vertices to cache
expiry-millisnono expiryCache expiry in milliseconds. Entries in cache will expire after this interval when written to cache.


Use the required seeds stanza to list the nodes in the Aerospike database cluster that you want the connector to connect to. By connecting to a seed node, the connector can discover all of the nodes in the cluster. The connector iterates through the list of nodes until it successfully connects to one of them, then it discovers the other nodes in the cluster. The connector is an Aerospike Smart Client, and stores in memory the partition maps of each node in the cluster, so that it can send updates directly to the appropriate nodes. For more information about Aerospike Smart Clients, see Smart Client.

portno3000The port to use when making connections to the Aerospike database.
tls-namenoThe TLS name of the Aerospike database.


Here is an example with the seeds stanza at the top of the file:

port: 3000
tls-name: red


filenoSpecifies the path to the log file. Rotated log files are placed in the same folder as the current log file.
formatnoSimpleLogging format: simple (space delimited) or json (JSON formatted)
enable-console-loggingnofalseWhen set to true and a log file is also specified, log messages are sent to both the console and the log file. Although enable-console-logging is false by default, it is forced to true if you do not specify a log file.
max-historyno30Specifies the maximum number of log files to retain.
levelsnoSpecify the types of messages to include in the log file. Valid log levels are error, warn, info, debug, trace. Each successive level includes the messages from the previous levels. For example, trace, being the highest level, includes messages from error, warn, info, and debug.
ticker-intervalno10Specifies how frequently messages are written to the log file, if there are any messages to write. The interval in measured in seconds.


format: json
file: /var/log/aerospike-proximus/aerospike-proximus.log