--- title: "Configure Aerospike Database to run as non-root" description: "Configure Aerospike Database 8.0.0 to run as a non-root user with the required systemd, storage, and kernel settings." --- # Configure Aerospike Database to run as non-root > 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 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 a node that still runs `asd` as root, Linux assigns root ownership to logs, namespace directories, shared memory segments, and raw block devices—so other host users need elevated privileges to access them (for example, [`collectlogs`](https://aerospike.com/docs/database/tools/asadm/live-mode#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 identity 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](#prepare-shared-memory-for-an-existing-installation) and begin at [Configure the node](#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 is already true for the node: - Aerospike Database is installed. See [Install Aerospike on Linux](https://aerospike.com/docs/database/8.0.0/install/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` has already been running as root on the node. For a new installation, skip to [Configure the node](#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. 1. Stop the Aerospike daemon (`asd`) on the node. Terminal window ```bash systemctl stop aerospike ``` See [Aerospike daemon management](https://aerospike.com/docs/database/8.0.0/manage/database/daemon) for more details. 2. List shared memory segments and identify Aerospike Database resources. Terminal window ```bash 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. 3. Choose how to handle index segments before you configure the node. - [Preserve shared memory](#tab-panel-3701) - [Cold start indexes](#tab-panel-3702) 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](#tab-panel-3699) - [ASMT backup and restore](#tab-panel-3700) 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](https://aerospike.com/docs/database/8.0.0/manage/database/fast-start) 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](https://aerospike.com/docs/database/tools/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](https://aerospike.com/docs/database/tools/asmt#when-not-to-use-asmt). ::: 1. [Back up indexes](https://aerospike.com/docs/database/tools/asmt/backup) with ASMT before maintenance that clears shared memory. 2. After maintenance (for example, a host reboot), [restore indexes](https://aerospike.com/docs/database/tools/asmt/restore) 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 ```bash 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. ::: ## 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. 1. 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 ```bash id AEROSPIKE_USER getent group AEROSPIKE_GROUP ``` 2. 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 ```bash 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 ```bash 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`](https://aerospike.com/docs/database/reference/config#service__user) or [`service.group`](https://aerospike.com/docs/database/reference/config#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. 3. 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](https://aerospike.com/docs/database/8.0.0/manage/logging/systemd). - [Console logging (recommended)](#tab-panel-3697) - [File logging](#tab-panel-3698) Add or update the `logging` stanza in `aerospike.conf` to send logs to the service manager: ```ruby 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`](https://aerospike.com/docs/database/tools/asadm/live-mode#collectlogs)), keep or add a `file` sink and grant the service user write access to the log directory: ```ruby logging { file /var/log/aerospike/aerospike.log { context any info } } ``` Terminal window ```bash chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /var/log/aerospike/ ``` Configure [log rotation](https://aerospike.com/docs/database/8.0.0/manage/logging/rotation) for the file path you use. 4. 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 ```bash chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/data/ ``` #### Filesystem-mounted SSD SSDs mounted as filesystems, such as SSDs used for a [flash index](https://aerospike.com/docs/database/8.0.0/manage/namespace/primary-index/#primary-index-on-flash), need the same directory ownership and permissions as file-backed namespace storage. Terminal window ```bash 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`. ```text 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`. ```text # 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 ```bash 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`](https://aerospike.com/docs/database/reference/config#namespace__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](https://aerospike.com/docs/database/8.0.0/manage/planning/ssd/manage#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 ```bash 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 ```bash 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. 5. 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 ```bash chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/smd chown -R AEROSPIKE_USER:AEROSPIKE_GROUP /opt/aerospike/usr ``` 6. Set required Linux kernel parameters. This step applies when the node uses an [all-flash](https://aerospike.com/docs/database/8.0.0/learn/best-practices#all-flash-deployment) deployment or [primary index on flash](https://aerospike.com/docs/database/8.0.0/manage/namespace/primary-index#set-kernel-parameters). 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](https://aerospike.com/docs/database/8.0.0/manage/namespace/secondary-index#set-kernel-parameters) 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 ```bash sysctl vm.dirty_bytes vm.dirty_background_bytes vm.dirty_expire_centisecs vm.dirty_writeback_centisecs ``` Terminal window ```bash 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 ```bash 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`](https://aerospike.com/docs/database/reference/config#service__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. 1. 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](https://aerospike.com/docs/database/8.0.0/manage/database/daemon). Command Terminal window ```bash systemctl start aerospike.service systemctl is-active aerospike.service ``` Expected output ```text active ``` 2. Verify that `asd` is running as the non-root user and group. Terminal window ```bash ps -o user,group,comm -C asd ``` Expected output includes _`AEROSPIKE_USER`_, _`AEROSPIKE_GROUP`_, and `asd`. 3. Verify that the service port is ready. Command Terminal window ```bash asinfo -v status ``` Expected output ```text OK ``` 4. Verify Aerospike Database shared memory segments. Terminal window ```bash 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](https://aerospike.com/docs/database/tools/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. 5. 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 ```bash 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 [`cluster-stable`](https://aerospike.com/docs/database/reference/info#cluster-stable) and [Quiesce a node](https://aerospike.com/docs/database/8.0.0/manage/cluster/quiesce-node). 6. (Recommended) Enable [`enforce-best-practices`](https://aerospike.com/docs/database/reference/config#service__enforce-best-practices). Complete the verification steps in [Verify](#verify) before you enable this setting. With `enforce-best-practices` enabled, startup fails when any [best-practices check](https://aerospike.com/docs/database/8.0.0/learn/best-practices) 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`: ```ruby service { enforce-best-practices true } ``` Restart the service and confirm that the node starts and returns `OK` from `asinfo -v status`: Terminal window ```bash systemctl restart aerospike.service asinfo -v status ``` ## Troubleshoot startup errors If `asd` does not start, examine the logs for resources that still require attention: Terminal window ```bash 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. 1. Remove the systemd drop-in override and reload the systemd manager configuration. Terminal window ```bash rm -f /etc/systemd/system/aerospike.service.d/non-root.conf systemctl daemon-reload ``` 2. 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](https://aerospike.com/docs/database/tools/asmt) before you start `asd`. Rolling back systemd alone does not restore removed segments. 3. 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 ```bash 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. 4. 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 ```bash 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 ``` 5. 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`](https://aerospike.com/docs/database/reference/config#service__user) or [`service.group`](https://aerospike.com/docs/database/reference/config#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. 6. Restore directory ownership if you changed it for the non-root user. Terminal window ```bash 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. 7. Remove scheduler udev rules, if you added them while following [Configure disk scheduler at the operating system level](https://aerospike.com/docs/database/8.0.0/manage/planning/ssd/manage#configure-disk-scheduler-at-the-operating-system-level) (for example, `/etc/udev/rules.d/60-aerospike-scheduler.rules`). 8. Start the service and verify that the node returns to the cluster. Terminal window ```bash systemctl start aerospike.service asinfo -v status ``` ## Next steps - Review [best practices](https://aerospike.com/docs/database/8.0.0/learn/best-practices) for remaining kernel and RAM settings. - For raw devices, confirm [disk scheduler configuration](https://aerospike.com/docs/database/8.0.0/manage/planning/ssd/manage#configure-disk-scheduler-at-the-operating-system-level) on every node. - Convert additional cluster nodes one at a time; see [`cluster-stable`](https://aerospike.com/docs/database/reference/info#cluster-stable) and [Quiesce a node](https://aerospike.com/docs/database/8.0.0/manage/cluster/quiesce-node).