Configure Aerospike Database to run as non-root

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This page describes how to configure Aerospike Database to run as a non-root user on Linux systems that use systemd.

Running asd as a dedicated non-root user follows least-privilege security practices and makes ownership of Aerospike Database files, devices, and logs explicit. On nodes that run asd as root, Linux assigns root ownership to logs, namespace directories, shared memory segments, and raw block devices, so other users need elevated privileges to access them (for example, collectlogs).

Migrating an existing node from root to non-root is not a single configuration change. Choose the target user and group, stop asd, then grant that user access to each resource the node uses: service identity, file and directory ownership, raw devices, shared memory, and any required kernel parameters. Verify each change before you start the service again.

The sections on this page follow this order. For a new installation, skip Prepare shared memory for an existing installation and begin at Configure the node.

Applies to

Aerospike Database on Linux nodes managed by systemd
New installations and migrations from root
All supported Database versions unless a step calls out a version-specific constraint (for example, scheduler-mode removed in 6.4.0)

Prerequisites

This task is for Linux cluster operators who manage Aerospike Database nodes with systemd and privileged OS access.

Confirm that the following conditions are true for the node:

Aerospike Database is installed. See Install Aerospike on Linux.
The node uses systemd to manage the Aerospike Database service.
You can run privileged operating system commands from a root shell, or from an account with equivalent sudo permissions. The examples on this page assume those permissions.

For production clusters, convert one node at a time. Verify that the cluster is stable before you convert the next node.

Outcome

After this procedure, asd runs as AEROSPIKE_USER / AEROSPIKE_GROUP, can access namespace storage and logs, and the node returns OK from asinfo -v status and rejoins a stable cluster.

Prepare shared memory for an existing installation

Complete this section only when asd is running as root on the node. For a new installation, skip to Configure the node.

When asd runs as root, it creates shared memory segments for indexes and in-memory namespace data. Before the service starts as AEROSPIKE_USER, stop asd and either preserve those segments or remove index segments so asd can recreate them under the new user.

Stop the Aerospike daemon (asd) on the node.
Terminal window
```
systemctl stop aerospike
```
See Aerospike daemon management for more details.
List shared memory segments and identify Aerospike Database resources.
Terminal window
```
ipcs -m
```
The command prints a table of shared memory segments—chunks of RAM the kernel keeps around after asd stops, so a later asd process can reconnect to indexes and in-memory data without rebuilding everything from disk.

Aerospike labels each segment in the key column. Match the start of that value to see what the segment holds:

If the key starts with… The segment holds…
0xae Primary index
0xa2 Secondary indexes
0xad In-memory namespace data (not just indexes)

These keyed segments apply to Enterprise Edition deployments that use shared-memory indexes (index-type or sindex-type shmem) and, for 0xad, storage-engine memory on Database 7.0 and later.

Other columns matter for non-root migration:
- owner — Linux user that created the segment. After asd ran as root, this is often root even after you switch the service to AEROSPIKE_USER.
- perms — Access mode. Aerospike often shows 666, meaning any user on the host can read and write the segment. That is why a non-root asd can still use segments left behind by root.
Choose how to handle index segments before you configure the node.
- Preserve shared memory
- Cold start indexes
Choose this path when the node must reuse existing primary and secondary index segments without a cold restart. Do not remove 0xae or 0xa2 segments in this procedure.
Reuse segments in place
ASMT backup and restore
Use this path when you stop asd for non-root migration on the same host without rebooting. Do not run ipcrm on index segments.
After you configure the node and start asd, Aerospike reattaches to existing segments when fast restart conditions are met.
In ipcs -m output, owner may still show root and perms may show 666. That is expected and does not block a non-root asd from reusing the segments. On hosts shared by untrusted users, treat 666 segments as a local exposure and prefer cold start or ASMT on those nodes.
Use this path when shared memory will be lost, such as after a host reboot, and you must persist indexes to disk first.
Note
ASMT applies only to Aerospike Database Enterprise Edition (EE). Do not use ASMT for namespaces where the primary index is on flash or Persistent Memory. See When not to use ASMT.

Back up indexes with ASMT before maintenance that clears shared memory.

After maintenance (for example, a host reboot), restore indexes with ASMT before you start asd. Restored segments may again show owner root and perms 666 in ipcs -m; this is expected.
Use this path only if the node can restart without reusing the existing primary and secondary index shared memory segments. The next startup can take longer because asd must recreate those index segments under AEROSPIKE_USER. Remove only the existing primary and secondary index shared memory segments:
Terminal window
ipcs -m | awk '$1 ~ /^0xa[2e][0-9a-f]*/ {print $1}' | while read -r key; do ipcrm -M "$key"; done
Caution
Do not remove 0xad shared memory segments unless you have planned for a cold start or verified that the data is persisted and recoverable. Removing 0xad segments can discard in-memory namespace data.

If the key starts with…	The segment holds…
`0xae`	Primary index
`0xa2`	Secondary indexes
`0xad`	In-memory namespace data (not just indexes)

Configure the node

Use the following steps for new and existing installations. If you prepared shared memory on an existing node, asd should remain stopped until you finish these steps.

Choose the service user and group.

Pick the Linux user and group for asd to use after this migration. The same names appear in every chown, udev rule, and permission check in the steps that follow, so choose them before you change ownership elsewhere on the node.

Use an existing non-root user and group, or create them now. Throughout this page, replace AEROSPIKE_USER and AEROSPIKE_GROUP with those names.

Verify that both accounts exist:
Terminal window
```
id AEROSPIKE_USER
getent group AEROSPIKE_GROUP
```
Configure systemd to start asd as that user and group.

systemd starts and supervises asd on boot and on systemctl start. A drop-in file adds User= and Group= to the existing aerospike.service unit without editing the package file directly.

After this step, systemd launches the asd process as AEROSPIKE_USER and AEROSPIKE_GROUP. The remaining steps grant that identity access to logs, data, devices, and shared memory.

If a configuration management tool manages systemd unit files in your environment, use that tool to set the same User and Group values.
Terminal window
```
install -d -m 0755 /etc/systemd/system/aerospike.service.d
cat > /etc/systemd/system/aerospike.service.d/non-root.conf <<'EOF'
[Service]
User=AEROSPIKE_USER
Group=AEROSPIKE_GROUP
EOF
systemctl daemon-reload
```
Terminal window
```
systemctl show aerospike.service -p User -p Group
```
Run systemctl cat aerospike.service to inspect the full unit and drop-in configuration.

Set the process identity with User= and Group= in the systemd drop-in. If aerospike.conf defines service.user or service.group, those values must match the drop-in exactly. Mismatches cause asd to fail at startup with an “insufficient privileges to switch user” error. Remove or align any existing keys before you start the service.
Configure Aerospike Database logging.

Choose one of the following options. Console logging is recommended for systemd because logs are available through journalctl without extra directory permissions. For more information, see Access Aerospike logs with systemd.
- Console logging (recommended)
- File logging
Add or update the logging stanza in aerospike.conf to send logs to the service manager:
logging { console { context any info } }
If aerospike.conf still defines a file sink for the main log, remove that sink or change it so asd does not write to a path the non-root user cannot access.
If your environment requires a log file (for example, for log rotation or collectlogs), keep or add a file sink and grant the service user write access to the log directory:
logging { file /var/log/aerospike/aerospike.log { context any info } }
Terminal window
chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /var/log/aerospike/
Configure log rotation for the file path you use.
Configure namespace storage permissions.

Aerospike Database must be able to read from and write to every namespace storage resource after asd stops running as root. Complete every subsection that applies to this node. These storage types are not mutually exclusive.

File-backed namespace

If namespace data is configured for persistence to a file, AEROSPIKE_USER must have write permission for the directory that contains the file.
Terminal window
```
chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/data/
```
Filesystem-mounted SSD

SSDs mounted as filesystems, such as SSDs used for a flash index, need the same directory ownership and permissions as file-backed namespace storage.
Terminal window
```
chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/data/
```
Raw SSD

Raw SSD namespaces need persistent device paths in aerospike.conf and operating system permissions on the underlying block devices.
1. Configure persistent /dev/disk/by-id/ paths in aerospike.conf.
  
  Use persistent /dev/disk/by-id/ paths because kernel-assigned names like /dev/sdb or /dev/sdc can change across reboots. Replace DEVICE_PATH with the configured persistent device path, such as /dev/disk/by-id/DISK_BY_ID_PATH.
```
namespace aerospike-example {
    ...
    storage-engine device {
        device DEVICE_PATH
        ...
    }
}
```
2. Add targeted udev rules for Aerospike Database namespace devices.
  
  Use targeted udev rules that match only Aerospike Database namespace devices. This limits raw block-device access to the devices Aerospike uses.
  
  Use udevadm info --query=property --name=DEVICE_PATH to find a persistent identifier such as ID_SERIAL_SHORT (NVMe) or ID_WWN. On cloud VMs, match on the property present for that device (for example ID_PATH or ID_SERIAL for Google disks). Match on that identifier without a DEVTYPE filter—partitions and whole disks share the same ID_SERIAL_SHORT and ID_WWN values, so the rule applies whether DEVICE_PATH is a partition or a whole disk. Add the rules to /etc/udev/rules.d/99-aerospike-non-root.rules.
```
# Example: match each raw device by a persistent identifier.
SUBSYSTEM=="block", ENV{ID_SERIAL_SHORT}=="DEVICE_SERIAL_1", OWNER="AEROSPIKE_USER", GROUP="AEROSPIKE_GROUP"
SUBSYSTEM=="block", ENV{ID_WWN}=="DEVICE_WWID_2", OWNER="AEROSPIKE_USER", GROUP="AEROSPIKE_GROUP"
```
  Confirm that the chosen ENV{…} key matches the output of udevadm info for each DEVICE_PATH before you reload the rules.
3. Reload and trigger the udev rules.
  
  Run the trigger command for each DEVICE_PATH configured for Aerospike Database.
  Terminal window
```
udevadm control --reload-rules
udevadm trigger --type=devices --subsystem-match=block --action=change --name-match="$(readlink -f DEVICE_PATH)" --settle
```
4. Configure the disk scheduler at the operating system level.
  
  The scheduler-mode parameter was removed in Aerospike Database 6.4.0. Set the disk scheduler at the operating system level for each raw namespace device. Follow Configure disk scheduler at the operating system level, including persistent scheduler rules in /etc/udev/rules.d/60-aerospike-scheduler.rules when that procedure applies.
5. Verify device ownership.
  
  Replace DEVICE_PATH with the configured persistent device path. The resolved block device should be owned by AEROSPIKE_USER and AEROSPIKE_GROUP.
  Terminal window
```
ls -l "$(readlink -f DEVICE_PATH)"
```
If your operating system policy requires group-based device access, add AEROSPIKE_USER to the required disk group. Assess the scope of the disk group before using this option because it can grant broad raw block-device access.
Terminal window
```
usermod -a -G DISK_GROUP_NAME AEROSPIKE_USER
```
Restart the Aerospike service (or reboot the node) after changing group membership so asd picks up the new group.
Change ownership of additional Aerospike Database directories.

The system metadata and user-defined function directories store runtime state that asd updates after startup. Give the non-root service identity ownership of those directories.
Terminal window
```
chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/smd
chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/usr
```
Set required Linux kernel parameters.

This step applies when the node uses an all-flash deployment or primary index on flash. Those configurations require the values below for the node to start. Set them in sysctl before you start asd as AEROSPIKE_USER.

For secondary index on flash without index-type flash, these values are recommended but not enforced at startup by the server.

Caution
These vm.dirty_* settings apply to the entire kernel, not only Aerospike Database. Validate them on shared hosts before rollout.

Persist the values in a sysctl configuration file under /etc/sysctl.d/. Record the original values before changing them so you can restore them if you roll back this migration.
Terminal window
```
sysctl vm.dirty_bytes vm.dirty_background_bytes vm.dirty_expire_centisecs vm.dirty_writeback_centisecs
```
Terminal window
```
cat > /etc/sysctl.d/99-aerospike-non-root.conf <<'EOF'
vm.dirty_bytes = 16777216
vm.dirty_background_bytes = 1
vm.dirty_expire_centisecs = 1
vm.dirty_writeback_centisecs = 10
EOF
sysctl --system
```
Verify the active values:
Terminal window
```
sysctl vm.dirty_bytes vm.dirty_background_bytes vm.dirty_expire_centisecs vm.dirty_writeback_centisecs
```

Outcomes and constraints

After migration:

systemd runs asd as AEROSPIKE_USER / AEROSPIKE_GROUP.
Shared-memory segments may retain owner root and perms 666 when you preserve indexes in place or restore with ASMT.
Raw namespace devices use persistent /dev/disk/by-id/ paths, targeted udev ownership rules, and OS-level disk scheduler rules.
Optional enforce-best-practices fails startup when any best-practices check fails.
In production clusters, convert one node at a time and verify cluster stability before the next node.

Verify

After you configure the node, verify that the service starts, runs under the configured non-root user, and rejoins the cluster.

Start the Aerospike Database service and verify that it is active.

Starting the service is a service management action, so a root user or a user with sudo permissions must do it. After systemd starts the service, the running asd process is owned by the configured non-root user.

For options on starting the server, see Aerospike daemon management.
Command
Terminal window
```
systemctl start aerospike.service
systemctl is-active aerospike.service
```
Expected output
active
Verify that asd is running as the non-root user and group.
Terminal window
```
ps -o user,group,comm -C asd
```
Expected output includes AEROSPIKE_USER, AEROSPIKE_GROUP, and asd.
Verify that the service port is ready.
Command
Terminal window
```
asinfo -v status
```
Expected output
OK
Verify Aerospike Database shared memory segments.
Terminal window
```
ipcs -m
```
After a cold start or when asd creates new segments, the owner column in ipcs -m should show AEROSPIKE_USER. If you preserved segments in place or restored them with ASMT, owner may still show root and perms may show 666; verify that the expected index and in-memory segments (keys starting with 0xae, 0xa2, and if applicable 0xad) are present. These keyed segments apply to Enterprise Edition deployments that use shared-memory indexes.
For production clusters, verify that the cluster is stable before converting the next node.

Replace CLUSTER_SIZE with the expected number of nodes:
Terminal window
```
asinfo -v 'cluster-stable:size=CLUSTER_SIZE;ignore-migrations=false'
```
The command returns ERROR while migrations are in progress. When migrations complete, all nodes return the same cluster key. For more information, see Wait for migrations.
(Recommended) Enable enforce-best-practices.

Complete the verification steps in Verify before you enable this setting. With enforce-best-practices enabled, startup fails when any best-practices check fails. Review logs from the successful start and resolve violations such as min_free_kbytes or RAM reservation settings before you add the flag.

Add the setting to aerospike.conf:
```
service {
    enforce-best-practices true
}
```
Restart the service and confirm that the node starts and returns OK from asinfo -v status:
Terminal window
```
systemctl restart aerospike.service
asinfo -v status
```

Troubleshoot startup errors

If asd does not start, examine the logs for resources that still require attention:

journalctl -u aerospike.service -b

Common causes include missing user or group accounts, stale systemd unit definitions, incorrect file or device ownership, missing kernel parameter values, and enforce-best-practices failures.

Roll back changes

If the node does not start after the change, roll back the service identity and local operating system changes before you start the node again.

Remove the systemd drop-in override and reload the systemd manager configuration.
Terminal window
```
rm -f /etc/systemd/system/aerospike.service.d/non-root.conf
systemctl daemon-reload
```
Recover shared memory if you removed index segments during migration.

If you removed 0xae or 0xa2 segments in the cold-start path, expect index rebuild on the next start or restore indexes from ASMT before you start asd. Rolling back systemd alone does not restore removed segments.
Disable or remove the udev rules added for Aerospike Database devices, if you added them.

If you used the dedicated rules file from this procedure, remove that file. If you added rules to another file, remove only the rules that you added for this migration. Run the trigger command for each DEVICE_PATH that used those rules.
Terminal window
```
rm -f /etc/udev/rules.d/99-aerospike-non-root.rules
udevadm control --reload-rules
udevadm trigger --type=devices --subsystem-match=block --action=change --name-match="$(readlink -f DEVICE_PATH)" --settle
```
If you used disk-group access, remove AEROSPIKE_USER from that group according to your operating system policy.
Restore the previous sysctl configuration, if you changed kernel parameters only for this migration.

Skip this step if these sysctl values are part of the required baseline for the node. Replace the PREVIOUS_DIRTY_BYTES, PREVIOUS_DIRTY_BACKGROUND_BYTES, PREVIOUS_DIRTY_EXPIRE_CENTISECS, and PREVIOUS_DIRTY_WRITEBACK_CENTISECS placeholders with the values you recorded before changing the sysctl configuration.
Terminal window
```
rm -f /etc/sysctl.d/99-aerospike-non-root.conf
sysctl -w vm.dirty_bytes=PREVIOUS_DIRTY_BYTES
sysctl -w vm.dirty_background_bytes=PREVIOUS_DIRTY_BACKGROUND_BYTES
sysctl -w vm.dirty_expire_centisecs=PREVIOUS_DIRTY_EXPIRE_CENTISECS
sysctl -w vm.dirty_writeback_centisecs=PREVIOUS_DIRTY_WRITEBACK_CENTISECS
sysctl --system
```
Revert aerospike.conf changes made for this migration.

Remove or restore settings you added in this procedure, such as console or file logging changes and enforce-best-practices. Removing the systemd drop-in in the first rollback step restores root for the service. Remove any service.user or service.group keys from aerospike.conf if they were present before migration—Aerospike Database validates these deprecated keys against the process identity at startup, and a mismatched value causes asd to fail to start.
Restore directory ownership if you changed it for the non-root user.
Terminal window
```
chown -R root:root /opt/aerospike/data
chown -R root:root /opt/aerospike/smd
chown -R root:root /opt/aerospike/usr
```
If you changed ownership for file logging, restore the log directory as well (for example, /var/log/aerospike/).

Adjust paths and owners to match your environment’s pre-migration ownership.
Remove scheduler udev rules, if you added them while following Configure disk scheduler at the operating system level (for example, /etc/udev/rules.d/60-aerospike-scheduler.rules).
Start the service and verify that the node returns to the cluster.
Terminal window
```
systemctl start aerospike.service
asinfo -v status
```

Next steps

Review best practices for remaining kernel and RAM settings.
For raw devices, confirm disk scheduler configuration on every node.
Convert additional cluster nodes one at a time; see Wait for migrations.