--- title: "Configure access control" description: "Configure role-based access control (RBAC), manage users, roles, and audit trails in Aerospike Database EE/FE." --- # Configure access control > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. This page describes how to enable authentication and assign roles and permissions in Aerospike Database. Aerospike Database uses role-based access control (RBAC) to manage internal and external users. It is available in Aerospike Database Enterprise Edition (EE), and the [FIPS 140-2](https://csrc.nist.gov/publications/detail/fips/140/2/final)\-compliant Aerospike Database Enterprise Edition for United States Federal (FE). ## Requirements - Aerospike Database Enterprise Edition (EE), or Aerospike Database Enterprise Edition for United States Federal (FE). - Client version that supports the features necessary to do a rolling restart. See the [Minimum client version matrix](#minimum-client-version-matrix) for details. ::: note During a rolling restart activation of RBAC, some nodes in the cluster authenticate the clients and some don’t. Verify that your client versions support this mixed environment prior to initiating the rolling restart. ::: ## Enable access control You can enable RBAC in Aerospike EE with a [rolling restart](https://aerospike.com/docs/database/8.0.0/manage/cluster/quiesce-node/#rolling-upgrade-procedure). In a running cluster, execute the following steps node-by-node. If the node isn’t running, skip to step 3: 1. [Quiesce the node](https://aerospike.com/docs/database/8.0.0/manage/cluster/quiesce-node). 2. [Stop the Aerospike server](https://aerospike.com/docs/database/8.0.0/manage/database/daemon#controlling-the-aerospike-daemon). 3. Verify that a `security` stanza is present in the [configuration file](https://aerospike.com/docs/database/8.0.0/manage/database/as-config#sample-configuration-file)(`aerospike.conf`). a. In Database 5.7.0 and later, the presence of a `security` stanza enables security and access control. The server does not recognize [`enable-security`](https://aerospike.com/docs/database/reference/config#security__enable-security) and will not start if it is present. b. Prior to Database 5.7.0, set `enable-security` to `true` in the `security` stanza. 4. (Optional) Set [`enable-quotas`](https://aerospike.com/docs/database/reference/config#security__enable-quotas) to `true` in the `security` stanza to enable [rate quotas](https://aerospike.com/docs/database/8.0.0/learn/security/rate-quotas). Terminal window ```bash security { # enable-security true # versions 5.6.x and earlier only enable-quotas true # Other security-related configuration... } ``` ::: note To change the default password for the admin user, edit the [`default-password-file`](https://aerospike.com/docs/database/reference/config#security__default-password-file) configuration that was introduced in Database 7.1.0. ::: 5. [Start the Aerospike server](https://aerospike.com/docs/database/8.0.0/manage/database/daemon/#controlling-the-aerospike-daemon). 6. Verify that access control is enabled on the cluster. 7. Use `asadm -U admin` to connect to the server as the admin user. - Aerospike EE: Log in with the default username _admin_ and password _admin_. - Federal Edition: An admin user must [create and sign the certificate](https://aerospike.com/docs/database/8.0.0/manage/network/tls#generate-tls-certificate-requests). 8. Change the admin user’s password with `manage acl set-password user admin password NEW-PASSWORD`. 9. Grant the sys-admin role to the admin user with `manage acl grant user admin roles sys-admin`. ## Secure SMD files The `/opt/aerospike/smd/security.smd` file stores sensitive information about users and roles. The default permission on all SMD files grants read access to everyone. When a new node is added to an existing cluster, it is a [best practice](https://aerospike.com/docs/database/8.0.0/learn/best-practices/#initialize-new-cluster-nodes-with-smd) to initialize it by copying [SMD](https://aerospike.com/docs/database/8.0.0/manage/database/directory-structure/#run-time-directories) files from an active cluster node. This best practice is not checked at startup. To secure the file, change the permissions of the `/opt/aerospike/smd` directory and its contents. 1. Set permissions on the `/opt/aerospike/smd` directory. Terminal window ```bash chmod 700 /opt/aerospike/smd ``` 2. Set permissions on the `/opt/aerospike/smd/security.smd` file. Terminal window ```bash chmod 600 /opt/aerospike/smd/security.smd ``` 3. Optional: Use `chmod 600` to restrict permissions on other SMD files you want to protect in the `/opt/aerospike` directory. Terminal window ```bash chmod 600 /opt/aerospike/smd/FILENAME ``` 4. List the contents of the `/opt/aerospike` directory to verify permissions: Terminal window ```bash ls -la /opt/aerospike/ ``` Expected output after permissions are set: ```text drwxr-xr-x 1 aerospike aerospike 4096 Apr 24 13:17 . drwxr-xr-x 1 root root 4096 Apr 24 13:17 .. drwxr-xr-x 2 aerospike aerospike 4096 Apr 24 13:17 bin drwxr-xr-x 2 aerospike aerospike 4096 Nov 10 2020 data drwxr-xr-x 2 aerospike aerospike 4096 Apr 24 13:17 doc drwxr-xr-x 4 aerospike aerospike 4096 Apr 24 13:17 lib drwx------ 1 aerospike aerospike 4096 Jun 22 12:26 smd <<<< drwxr-xr-x 3 aerospike aerospike 4096 Apr 24 13:17 usr ``` 5. To verify permissions in the `/opt/aerospike/smd` directory, list its contents: Terminal window ```bash ls -la /opt/aerospike/smd ``` Expected output after permissions are set: ```text drwx------ 1 aerospike aerospike 4096 Jun 22 12:26 . drwxr-xr-x 1 aerospike aerospike 4096 Apr 24 13:17 .. -rw-r--r-- 1 root root 292 Jun 22 10:12 sindex.smd -rw-r--r-- 1 root root 289 Jun 22 12:26 truncate.smd -rwx------ 1 root root 289 Jun 22 12:26 security.smd ``` ## Audit trail You can configure Aerospike EE to log security events to an audit log. Each cluster node has a separate audit trail. See [Configuring Log Streams](https://aerospike.com/docs/database/8.0.0/manage/logging/logs) for more information. Aerospike supports an audit trail with granular control over the type of security events being logged: - Security violations (including authentication or role violations). - Successful authentications. - Successful or attempted data commands including various write/read commands. - User administration operations, including: - Creating/removing users. - Granting/revoking user roles. - Creating/removing roles. - Granting/revoking role privileges. - System administration operation including: - Creating/removing secondary indexes. - Registering/removing UDFs. - Changing dynamic server configurations. In general, auditing security violations and other rare events have minimal performance impact. However, logging every attempted or successful data commands on numerous data sets can slow runtime performance in systems under heavy load. This level of logging also increases storage requirements for the logs. If you plan to maintain extensive audit records, we suggest that you first review the potential performance impact and storage needs in a test environment. ### General - Security violations, see [report-violation](https://aerospike.com/docs/database/reference/config#security__report-violation). ### Authentication - Authentication failure, see [report-violation](https://aerospike.com/docs/database/reference/config#security__report-violation). - Successful authentications, see [report-authentication](https://aerospike.com/docs/database/reference/config#security__report-authentication). - Successful data transactions, see [report data transactions](https://aerospike.com/docs/database/reference/config#security__report-data-op). ### Users - Role violation, [report violation](https://aerospike.com/docs/database/reference/config#security__report-violation). - User administration operations, see [report user admin](https://aerospike.com/docs/database/reference/config#security__report-user-admin): - Create or drop user. - Change user password. - Grant roles to user. - Revoke roles from user. - Create or drop role. - Grant privileges to role. - Revoke privileges from role. - Set allowlist for role. - Set read/write rate quotas for role. - Query users and their roles. - Query roles and their privileges. ### System administration - System administration operations: - Create or drop index. - Register or remove UDFs. - Set dynamic server configuration variables. - Enable specialized logging. - Get server configuration, server statistics, and other information. ## Configuring the audit trail in Database 6.3.0 and later Starting with Database 6.3.0, the `syslog` subcontext of the `security` configuration context was removed because any log message, including the audit logging context, can be sent to any log sink, including syslog-compatible `socket` log sinks. The following example shows how to configure an audit trail starting with Database 6.3.0. ```plaintext security { log { 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" } } ``` The `logging` configuration context defines log sinks, with each having the ability to filter log messages by context and level. ### Logging audit trail messages to a syslog-compatible socket Combined with the configuration above, `audit` context log messages will be sent to the local0 syslog facility. ```plaintext logging { syslog { facility local0 tag aerospike-audit context any critical context audit info } } ``` ## Configuring the audit trail in versions prior to Database 6.3.0 You can enable the audit trail in the `security` configuration context. For details about these configuration parameters, see the [Configuration Reference](https://aerospike.com/docs/database/reference/config). ### Logging audit trail messages to file sinks The following configuration sends audit trail messages to the `file` log sinks defined in the `logging` configuration context, where log messages can be filtered by message context and log level. ```plaintext security { log { 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" } } ``` ### Logging audit trail messages to syslog Prior to Database 6.3.0, only audit trail log messages could be sent to syslog, through a special configuration of the `security` config context. Destinations included: - Local syslog facility (local file) - Syslog daemon default sink ```plaintext 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" } } ``` The following example configures `rsyslog` to send locally written audit information to syslog, with the following line added to `/etc/rsyslog.conf`: ```text local0. /var/log/aerospike_security_audit.log ``` Restart `rsyslogd` to activate any changes. ### Parsing audit trail 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' ```text 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] ``` ### Security features by Database version Support for various features and security modes has changed with new versions of Aerospike server and clients. - Database 6.3.0: Removed the `syslog` subcontext of the `security` config context. Audit trail messages can be sent to any log sink type (`file`, `console` or `syslog`) that is defined in the `logging` config context. - Database 6.0.0: The FIPS 140-2 compliant “Federal Edition” variant of Aerospike EE restricts access to PKI or LDAP authentication modes. - Aerospike Admin, `asadm`, added support for mixed security modes in tools package 7.0.0 (`asadm` 2.7.0) which was packaged with Aerospike Database 6.0.0. - Database 5.7.0: Added PKI auth as an alternative authentication mode for users created in Aerospike. You can restrict an internal user to PKI authentication by generating a strong random password for the user and not communicating it to the user. Create a user normally with `asadm`, then generate an SSL cert for the user, signed by the server’s root CA. The server must be configured for Mutual TLS (mTLS). ::: caution When access control is enabled with Cross-Datacenter Replication (XDR), a cluster with Aerospike EE releases 4.1.0.1 to 4.3.0.6 cannot ship to an Aerospike EE Database 4.6.0 or later. The simplest workaround is to avoid using incompatible Aerospike EE releases (4.1.0.1 to 4.3.0.6). See [this support article](https://support.aerospike.com/s/article/Internal-user-warning-returned-when-using-an-Access-Control-List-ACL-with-Cross-Datacenter-Replication-XDR-non-compatible-Aerospike-Server-versions-sending-both-internal-and-external-authentication-mode) for more information. ::: ## Privileges Privileges are a fundamental component of RBAC, and cannot be modified. - A privilege consists of permissions and a scope. - The scope is global, per namespace, or per set within a specified namespace. - A role is a collection of scoped privileges, and roles are granted to users. The following table describes permissions and the scope corresponding with each privilege. | Privilege | Permission | Scope | | --- | --- | --- | | `read` | \- Get record \- Scan \- Query \- Get server configuration and statistics \- Change user password | Global, per namespace, or per set in a namespace. | | `write` | \- Record-level write commands such as put, touch, delete \-Bin-level write commands such as List or Map write commands \- Truncate or undo a truncation of namespaces or sets permissions (Only in 5.7.0 and earlier. Permissions moved to `truncate` in 6.0) | Global, per namespace, or per set in a namespace. | | `read-write` | \- All read user role privileges \- All write user role privileges | Global, per namespace, or per set in a namespace. | | `read-write-udf` | \- All read-write user role privileges \- Execute User-Defined Functions (UDFs) \- Execute queries using UDFs | Global, per namespace, or per set in a namespace. | | `truncate` (Database 6.0.0+) | \- Truncate or undo a truncation of namespaces or sets | Global, per namespace, or per set in a namespace. | | `data-admin` | \- Create and drop secondary indexes \- Register and remove UDFs \- Use the scan-query job monitoring system \- Abort scans and queries \- Change user password \- Truncate or undo a truncation of namespaces or sets | Global | | `sindex-admin` (Database 6.0.0+) | \- Create and drop secondary indexes | Global | | `sys-admin` | \- All data-admin role privileges \- Set dynamic server configuration variables \- Enable specialized logging \- Get server configuration and statistics | Global | | `udf-admin` (Database 6.0.0+) | \- Register and remove UDFs | Global | | `user-admin` | \- Create and drop users \- Change any user password \- Grant roles to users \- Revoke user roles \- Create and drop user roles \- Grant user role privileges \- Revoke role privileges \- Set allowlists for roles \- Set read/write rate quotas for roles \- Query all users and their roles \- Query all roles and their privileges \- Get server configuration and statistics | Global | ## Commands for managing roles Aerospike provides pre-defined roles corresponding with each privilege. Each has a name matching the single privilege, such as `read-write`. Pre-defined roles have a global scope. They cannot be modified. They can only be assigned as-is to users. For instructions on how to manage roles and users with the Admin tool, `asadm`, see [Create and manage users](#create-and-manage-users). ### Create a role The `asadm` command to create a new role is: ```plaintext manage acl create role ROLE NAME priv PRIVILEGE [ns NAMESPACE [set SET]] [allow ADDR1 ADDR2 [...]]] [read READ-QUOTA] [write WRITE-QUOTA] ``` Example ```text manage acl create role superusers priv read-write-udf ``` ### Add a privilege to a role The `asadm` command to add a privilege to a role is: ```plaintext manage acl grant role ROLE-NAME priv PRIVILEGE [ns NAMESPACE [set SET]]> ``` Example ```text manage acl grant role demo-users priv read-write-udf ns test set demoset ``` ### Remove a privilege from a role The `asadm` command to remove a privilege from a role is: ```plaintext manage acl revoke role ROLE-NAME priv PRIVILEGE [ns NAMESPACE [set SET]]> ``` Example ```text acl revoke role demo-users priv read-write-udf ``` ### Add an IP address to a role’s allowlist The `asadm` command to add an IP address or range to a role’s allowlist is: ```plaintext manage acl allowlist role ROLE-NAME allow ADDR1 [ADDR2 [...]] ``` Example ```text manage acl allowlist role superusers allow 10.0.0.1 manage acl allowlist role demo-users allow 127.0.0.0/8 ``` ### Clear a role’s allowlist The `asadm` command to clear an allowlist from a role is: ```plaintext manage acl allowlist role ROLE-NAME clear ``` Example ```text manage acl allowlist role demo-users clear ``` ### Delete a role The `asadm` command to delete a role is: ```plaintext manage acl delete user USERNAME ``` Example ```text manage acl delete role demo-users ``` ## Create and manage users When RBAC is first enabled in an Aerospike EE cluster, it comes with a default admin user that has the permissions to create new users. - In Aerospike EE the default credentials are username:`admin`, password: `admin`. To change the default password for the admin user, edit the [`default-password-file`](https://aerospike.com/docs/database/reference/config#security__default-password-file) configuration parameter which was introduced in Aerospike Database 7.1.0. - In Aerospike Federal Edition password authentication is disabled. You must create and sign a TLS certificate for the admin user, in order to use PKI authentication. See [Generate TLS certificate requests](https://aerospike.com/docs/database/8.0.0/manage/network/tls#generate-tls-certificate-requests). ### Set a new password The `asadm` command to set a password for an existing user is: ```plaintext manage acl set-password user USERNAME [password PASSWORD] ``` ::: caution In [tools package 7.1.1 (asadm 2.8.1)](https://aerospike.com/docs/database/tools/release-notes/#tools-711) and earlier, `asadm` (formerly performed in `aql`) limits the characters you can use when setting a password. Valid passwords can contain alphanumeric characters and the symbols `.*-:/_{}@`. White space is not supported. When setting a user password with a hidden prompt these restrictions do not apply. ::: Example ### Create a user The `asadm` command to create a user is: ```plaintext manage acl create user USERNAME [password PASSWORD] [roles ROLE1 ROLE2 ...] ``` Example ```text acl create user alice password alicepass roles superusers manage acl create user bob password bobpass roles user-admin demo-users aaargh-users ``` ### Grant a role to a user The `asadm` command to add one or more roles to a user is: ```plaintext manage acl grant user USERNAME roles ROLE1 [ROLE2 [...]] ``` Example ```text manage acl grant user alice roles superusers manage acl grant user bob roles user-admin demo-users aaargh-users ``` ### Revoke a user’s role The `asadm` command to revoke one or more roles previously granted to a user is: ```plaintext manage acl revoke user USERNAME roles ROLE1 [ROLE2 [...]] ``` Example ```text manage acl revoke user bob roles user-admin demo-users ``` ### Delete a user The `asadm` command to delete a user is: ```plaintext manage acl delete user USERNAME ``` Example ```text manage acl delete user jdoe ``` ## PKI authentication For PKI authentication: - Verify that the server is using Mutual TLS (mTLS). If it is not, see [TLS Configuration](https://aerospike.com/docs/database/8.0.0/manage/network/tls) for configuration instructions. - Create a user and grant them privileges and roles. - Generate an SSL certificate for the user, with the username as the Common Name `CN`. - Sign the certificate using the server `root` certificate authority (CA). For instructions, see [Generate TLS certificate requests](https://aerospike.com/docs/database/8.0.0/manage/network/tls#generate-tls-certificate-requests). ::: note If you are using Aerospike Federal Edition (FE) you _cannot use_ password authentication. Use PKI authentication or LDAP, which are available for both EE and FE. ::: Example ```text asadm -p 4333 --tls-enable --tls-name server \ --tls-certfile=/root/rootca/output/admin.pem --tls-keyfile=/root/rootca/output/admin.key \ --tls-cafile=/etc/aerospike/tls/server/rootCA.pem --auth=pki ``` ## Minimum client version matrix The following table shows the minimum client version for the following security features: | Client | RBAC support | LDAP support | Rolling restart to enable RBAC | PKI auth support (Database 5.7.0 or later) | | --- | --- | --- | --- | --- | | Java | 3.1.2 | 4.1.6 | 4.4.4 | 5.1.8 | | C | 3.1.16 | 4.3.11 | 4.6.5 | 5.2.3 | | C# | 3.1.2 | 3.6.4 | 3.8.2 | 4.2.3 | | Go | 1.3.0 | 1.35.1 | 2.3.0 | 5.6.0 | | Python | 1.0.44 | 3.2.0 | 3.7.3 | 6.1.0 | | Node.js | 1.0.35 | 3.3.0 | 3.12.0 | 4.0.5, 5.0.3 | | Ruby | 1.0.0 | \- | \- | \- | | Rust | 1.1.0 | \- | \- | \- | ## Related information Aerospike supports LDAP, PKI, and password-based authentication modes that are described in detail in [Access Control with LDAP and PKI](https://aerospike.com/docs/database/8.0.0/learn/security/access-control).