Audit trail

This page describes how to set up an audit trail, a feature available in Aerospike Enterprise Edition (EE), and Federal Edition (FE).

Audit logging system

Audit logs are specialized log files that receive only security- or compliance-related events specified in the log stream. They are designed for security, compliance, and accountability. They track specific, user-centric activities that are critical to an organization’s security posture and regulatory requirements. These logs provide a detailed, chronological record of who did what, where, and when, making them a crucial tool for forensic analysis and legal defense.

An audit trail is the complete chronological sequence of records that shows how a system, process, or resource was accessed and changed over time. It is the end-to-end history of activities, pieced together from audit logs. Audit logs are raw entries, individual events. The audit trail is the organized timeline that lets you reconstruct what actually happened.

For example:

• Audit logs might record individual entries like userX logged in, userX deleted file A, userX logged out.
• The audit trail is the storyline built from these logs: On Sept 9 at 10:12, userX logged in from IP 1.2.3.4, deleted file A at 10:13, and logged out at 10:15.

The following diagram shows the entire audit logging process in the Aerospike logging framework:

Figure 1: Aerospike logging pipeline

1. The system generates a logged event.
2. Events are aggregated into a log stream, which is the live, in-memory sequence of logs.
3. From the stream, events are dispatched to one or more log sinks. Audit trail messages can be logged to a file, a console, or syslog.
4. The audit log is available for analysis.

Best practice configuration setup

The following configuration illustrates best practices for setting up an audit log. Audit trail messages can be sent to any type of supported log sink such as file, console or syslog. Key configuration features include:

• Security enabled: audit logging is enabled when security is in use. See Enable access control.
• File sink: Writes to /var/log/aerospike/audit.log for local inspection.
• Syslog sink: Forwards to your syslog daemon for aggregation/monitoring (SIEM-friendly).
• Console sink (optional): Helpful if running Aerospike in Docker/Kubernetes where stdout is aggregated.
• Logging context: Specifies the server module where the log messages originated, such as tls, drv_ssd, or fabric.
• Severity level: Determines how much information is logged.

# =============================
# Aerospike audit logging setup
# =============================

service {
    # Other service-level settings...
}

security {
   # Other security-level settings...
}

logging {
    # Local file sink for audit logs
    file /var/log/aerospike/audit.log {
        context audit info           # Capture audit events at info+ level
    }

    # Syslog sink for centralized monitoring
    syslog {
        facility local0
        tag aerospike-audit
        context audit info           # Send only audit events
    }

    # Console sink (optional, useful in containers)
    console {
        context audit info
    }
}

Required roles and permissions

To configure or view audit logs, you must have the appropriate roles and permissions.

Role and permission to dynamically configure audit logging

To set up or change which events are logged to the audit trail, you need a high-level administrative role on the Aerospike cluster.

Required role or privilege: sys-admin (or a custom role with equivalent global configuration privileges). This privilege is required to:

• Configure which events are logged to the audit trail.

• Configure a syslog log sink in the logging section to ship the audit data.

Roles and permission to view or read audit logs

Once the audit log is configured, the logs are written as files on the server or shipped via the syslog protocol to an external system. Viewing these logs is a matter of Operating System (OS) permissions or Log Management System access, not Aerospike database access control.

• For instructions about how to add and configure Aerospike filtering and parsing rules for supported 3rd-party log ingestion tools, see 3rd-party log analysis tools.

Set up audit logging

The following steps demonstrate how to set up a logging pipeline to create files you can use for an audit trail.

Before editing the configuration file, aerospike.conf, decide the following:

• What do you need to audit?
  • Do you care about all security-related events, like user creation, role grants, and authentication attempts?
  • Do you want to limit logging to specific event types, like failed logins or privilege changes?
• Which log sinks do you need?
  • Local file (default: /var/log/aerospike/audit.log)
  • Syslog (centralized logging, often used in production for security monitoring)
  • Console (useful for containers or testing environments)
• What are your retention and compliance requirements?
  • How long do you need to keep audit logs?
  • Do you need to rotate logs or prepare for secure archival?
• Do you need to consider performance implications?
  • Audit logging adds overhead. Audit logging by default is less verbose, using configurations like report-data-op logs more information but can impact performance.
  • Do audit logs need to be stored locally, shipped off-cluster, or both?

1. Enable audit logging.

   Audit logging is enabled automatically when the security configuration section is used.

   security {
   
   }

2. Add the event types you want to audit.

   You can filter audit events by type. In the following example, the log subsection defines the events you want to audit.

   security {
       log {
           report-authentication true # report successful authentication and login attempts.
           report-user-admin true # report successful user admin operations.
           report-sys-admin true # report operations made with the sys-admin permission.
           report-violation true # report operations failed due to violating security checks e.g. permissions, quotas, authentication, etc.
           report-data-op test demoset # report successful data transactions on set "demoset" in namespace "test"
       }
   }

3. Integrate with logging system.

   You can send Aerospike audit logs to one or more destinations, according to your specific requirements. The following example sends audit logs to both a file and syslog.

   • context audit info ensures only audit events at info severity level and above are captured.
   • The audit context log messages are sent to the local0 syslog facility and tagged with “aerospike-audit.”

   logging {
      file /var/log/aerospike/audit.log {
          context audit info
      }
      syslog {
          facility local0
          tag aerospike-audit
          context audit info
      }
   }

4. Secure the audit logs.

   • Set restrictive permissions (chmod 600) so only Aerospike or security admins can read audit logs.
   • If using syslog, verify that TLS or secure forwarding is in place.
   • Consider rotating logs daily with logrotate.

5. Activate your changes with a rolling restart, and verify audit logging.

   1. Run a simple admin action, such as creating a test user and role with the following command.

      aql -c "create user audit_test password pass roles read"

   2. Check your audit log (/var/log/aerospike/audit.log) or syslog for the event.

   3. Confirm the format (JSON-like structured events) matches what your SIEM or monitoring system expects.

Note

Prior to Database 6.3.0, you log to syslog with the following configuration:

security {
    syslog {
        local 0 # write to "local0" facility
        # write audit trail messages to the default syslog facility
        report-authentication true
        report-user-admin true
        report-sys-admin true
        report-violation true
        report-data-op test demoset # report successful data transactions on set "demoset" in namespace "test"
    }
}

Log lines

Aerospike log lines contain default information followed by detailed audit trail entries when those entries are present.

Default log line

Each Aerospike log line starts with the following elements:

DATE-TIME: LOG-LEVEL (LOGGING-CONTEXT): (FILE:LINE) MESSAGE

The date-time substring has the strftime format %b %d %Y %T %Z.

• Aerospike sends regular log lines when an event occurs.
• Ticker log lines are printed at regular intervals defined by ticker-interval, which is 10 seconds by default. Ticker log lines contain everything that occurred during the previous interval, and they can be identified by the ticker.c entry that follows the logging context.

For example:

Jul 25 2025 01:11:31 GMT: INFO (info): (ticker.c:577) {test} data-usage: used-bytes 0 avail-pct 99 cache-read-pct 0.00
Jul 25 2025 01:11:36 GMT: INFO (drv_ssd): (drv_ssd.c:2128) {test} /opt/aerospike/data/test.dat: used-bytes 0 free-wblocks 511 write-q 0 write (0,0.0) defrag-q 0 defrag-read (0,0.0) defrag-write (0,0.0)

The Database log reference describes many log lines in detail.

Detailed audit log entries

Audit log messages have the following format:

RESULT_TAG | client: CLIENT_IP:PORT: | authenticated user: USERNAME | action: ACTION_TAG | detail: DETAIL_STRING

Each placeholder contains specific information about the event, as described in the following tables. It is important to understand these components so you can interpret audit logs effectively.

RESULT_TAG placeholder descriptions

RESULT_TAG (log string)	Description
permitted	Requested operation or access was allowed by the security policies.
not authenticated	Session or connection has not been authenticated, or authentication is missing or invalid.
role violation]	Authenticated user does not have the necessary roles or permissions for the requested operation.
not whitelisted	Client’s IP address is not on the allowlist for the user’s roles.
quota exceeded	User or role has exceeded their allocated transaction (read/write) quota.
forbidden password	User tried to set a password to one that was recently used, or tried to set a password on a nopassword PKI user.
authentication failed (user)	Authentication failed, typically because the specified user was not found or is invalid.
authentication failed (credential)	Authentication failed due to an invalid or incorrect credential, such as a password or token.
authentication failed (password)	Authentication failed, specifically due to an incorrect password.
authentication failed (session expired)	Authentication failed because the provided session token has expired.
LDAP not configured	LDAP authentication failed because LDAP is not configured on the server.
LDAP setup failed	LDAP authentication failed due to an issue during the LDAP setup or initialization.
LDAP TLS setup failed	LDAP authentication failed due to an error in setting up the TLS connection for LDAP.
LDAP authentication failed	LDAP authentication failed because of incorrect LDAP credentials, or user not found in LDAP.
LDAP role query failed	After successful LDAP authentication, the query to retrieve the user’s roles from LDAP failed.
UNEXPECTED RESULT	Undefined or unexpected result code was encountered.

client placeholder descriptions

client is normally the IP address and port of the client attempting the operation that generated the log statement.

client	Description
CLIENT_IP:PORT	This is the most common event information, used when the connecting client is known.
UNKNOWN	The literal value UNKNOWN may be used if the client is unknown.
N/A	The literal value N/A may be used when the client is unknown.

authenticated user placeholder descriptions

authenticated user is usually the username that attempted the operation triggering the log.

authenticated user	Description
USERNAME	Username of the user that triggered the log.
NONE	The literal value NONE is used if the user is not known or unauthenticated.

action placeholder descriptions

action describes the event, such as a command or operation, that triggered the log.

action	Description	Associated command
authentication	Used when authentication fails or succeeds
info request	Logs failed authentication events for info requests	Any info command that fails authentication
login	Used when a login fails or succeeds
INFO_COMMAND_NAME	Name of the info command triggering the log. Can be any entry in the Info command reference	Any info command
write	Used for write operations	writes
read	Used for read operations	read
create user	Used when a user is created	create-user
drop user	Used when a user is deleted	drop-user
set password	Used when setting a password	set-password
change password	Used when changing a password	change-password
grant roles	Used when granting roles	grant-roles
revoke roles	Used when roles are revoked	revoke-roles
query users	Used when there is an attempt to get the list of users	query-users
create role	Used when a role is created	create-role
delete role	Used when a role is deleted	delete-role
add privs	Used when privileges are added to a role	add-privs
delete privs	Used when privileges are removed from a role	delete-privs
set whitelist	Used when setting the whitelist	set-whitelist
set quotas	Used when setting role, read, and write quotas	set-quota
query roles	Used when listing roles	query-roles
NONE	The literal value NONE used when the action is unknown
UNEXPECTED ACTION	The literal value UNEXPECTED ACTION. Used when an unexpected/invalid action is encountered internally

detail placeholder description

detail varies according to the type of operation that generated the log. The following sections describe the possible formats of detail.

Data operations

Used with read, write, and query operations.

{NAMESPACE|SET_NAME} [I|INTEGER_KEY_VAL]
{NAMESPACE|SET_NAME} [S|STRING_KEY_VAL]
{NAMESPACE|SET_NAME} [B|HEX_KEY_VAL]
{NAMESPACE|SET_NAME} [?|HEX_KEY_VAL]
{NAMESPACE|SET_NAME} [D|HEX_DIGEST_VAL]
{NAMESPACE|SET_NAME} (if no key/digest string can be formed)

example: {ns1|set1} [S|key1]

Quotas

When the audit trail logs an exceeded quota, the detail string hold throughput information for the job that exceeded that quota. Example: rps=800,read-quota=400

Format	Description
NONE	Literal value NONE used when called from as_security_check_rps and the user is not authenticated.
rps=RPS_OF_THE_JOB,write-quota=WRITE_QUOTA	Used when a write quota is exceeded by a query, both values are unsigned integers in decimal format
rps=RPS_OF_THE_JOB,read-quota=read_quota_QUOTA	Used when a read quota is exceeded by a query, both values are unsigned integers in decimal format
quota=RPS	Used when a quota is violated by an operation. rps is an unsigned integer

Info requests and commands

When an info command fails to authenticate, the detail string is the literal value NONE. Otherwise the detail string is the info command as it was received by the server. For example: bins/test for the bins command in the Info command reference

Login logging

When the audit trail logs a login, detail displays the username that logged in.

Format: user=USERNAME[;roles=ROLE,...] Example: user=bobby;roles=user-admin,data-admin

Auth and user admin commands

In the case of auth failure (log_auth_failure), auth success (log_auth_success), and user-admin commands (log_user_admin), detail displays information about the user affected.

General format: [user=USERNAME;][roles=ROLE,...;][role=ROLE;][privs=PERM_CODE_TAG[{NAMESPACE[|SET_NAME]}],...;][whitelist=VALUE;][read-quota=UINT32_VALUE;][write-quota=UINT32_VALUE]

Component	Format/Description	Notes
Overall	Concatenation of following components, semicolon-separated	Each […] part is optional and only appears if the corresponding field is present in the request. Trailing semicolon is removed.
user	user=USERNAME	Username from the request.
roles	roles=ROLE1,ROLE2,...	Comma-separated list of roles.
	roles=NONE	If no roles are specified or applicable. NONE is a literal value, not replaced.
	roles=PARSE ERROR	If parsing of roles fails. PARSE ERROR is a literal value, not replaced.
role	role=ROLE_NAME	Single role name.
privs	privs=PRIV_STR1,PRIV_STR2,...	Comma-separated list of privileges.
priv_str	PERM_CODE_TAG[{NAMESPACE[|SET_NAME]}]	Format for an individual privilege string.
PERM_CODE_TAG	Short string such as u, r, w	Represents the permission code from perm_code_tag(). Possible perm codes are defined in the definition of the perm_code_tag function in the reference information section.
Scope	{NAMESPACE[|SET_NAME]}	Optional scope: namespace, and possibly set name
whitelist	whitelist=WHITELIST_STR	Whitelist string
read-quota	read-quota=QUOTA_VAL	Read quota value (unsigned integer)
write-quota	write-quota=QUOTA_VAL	Write quota value (unsigned integer)

Example detail string:

user=bob;privs=u{NAMESPACE1\|SET1},w{NAMESPACE2\|SET2};read-quota=300

Parsing audit log messages

Log messages are plain text descriptions of attempted security actions, whether or not the action succeeded, and any user that was involved.

Namespaces and sets are in braces: {NAMESPACE|SET} or just {NAMESPACE}

Custom role privileges are letter codes that correspond to Aerospike pre-defined privileges, and are followed by {NAMESPACE|SET} scoping if applicable.

The letter codes are:

• r = read
• rw = read-write
• rwf = read-write-udf
• t = truncate
• w = write
• d = data-admin (a global privilege, scoping not applicable).
• fa = udf-admin (a global privilege, scoping not applicable).
• ia = sindex-admin (a global privilege, scoping not applicable).
• s = sys-admin (a global privilege, scoping not applicable).
• u = user-admin (a global privilege, scoping not applicable).

For example:

• rw{} indicates read-write privileges across all namespaces.
• r{test},rw{ns2} indicates read privileges for the test namespace and read-write privileges for the ns2 namespace.
• u,rwf{test|demoset} indicates user-admin privileges as well as read-write-udf privileges for demoset in the test namespace.

If the key is stored, key data is logged with successfully-authenticated data transactions and data transactions that fail due to role violations. If the key is not stored, the digest is logged. The eventual success or failure of the transaction does not affect this behavior, since logging happens at the point at which authentication is checked.

Stored key data appears as follows:

• [S|mykey] if the key is a string.
• [I|78654] if the key is an integer.
• [B|AA C5 48] if the key is a blob of bytes.

If the key is not stored, the digest is logged as a string:

• [D|567895f996dd7dd3832222b57cd4a3031ecc6e24]

Example audit trail output, logging context is 'audit'

Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51378 | authenticated user: user2 | action: login | detail: user=user2
Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51380 | authenticated user: user2 | action: authentication | detail: user=user2
Sep 01 2021 18:37:56 GMT: INFO (audit): (security.c:7608) permitted | client: 127.0.0.1:51380 | authenticated user: user2 | action: read | detail: {test|eg-set} [D|1142f0217ababf9fda5b1a4de66e6e8d4e51765e]