Configure Aerospike to Run as Non-root User

Overview

This page describes how to configure Aerospike to run as a non-root user.

Configure a newly installed Aerospike node

Use the following steps to configure a new installation of Aerospike to run as a non-root user.

1. If you haven't already, install Aerospike as described in the install documentation.

2. Configure user and group The default is whichever user or group that started the asd process. The /lib/systemd/system/aerospike.service file sets both the user and group to root.

To change the defaults, edit the Aerospike configuration file /etc/aerospike/aerospike.conf. By default, we do not provide any value for these configs in the configuration file, so you may have to add these config lines to your file.

In the service stanza of the file, enter the new AEROSPIKE-USER. In group enter the new AEROSPIKE-GROUP.

service {
    user AEROSPIKE-USER
    group AEROSPIKE-GROUP
}

3. Change ownership in user.conf On Linux operating systems that rely on systemd, for Aerospike server versions prior to 4.5.3.2, change /etc/systemd/system/aerospike.service.d/user.conf to add your desired AEROSPIKE-USER and AEROSPIKE-GROUP.

note

If upgrading to Aerospike Database 4.5.3.2 or newer, do not follow this step.

Use the cat command to create the user.conf file and add the lines to it.

cat > /etc/systemd/system/aerospike.service.d/user.conf <<EOF
[Service]
User=AEROSPIKE-USER
Group=AEROSPIKE-GROUP
EOF

For more details, see Changing Usergroup of asd process under systemd.

4. Configure PID file

note

If you use systemd you do not need to configure a process ID (PID) file.

The default process ID (PID) file for Aerospike is /var/run/aerospike/asd.pid.

Use chown in the directory's user and group to configure the PID file. AEROSPIKE-USER and AEROSPIKE-GROUP must have write access to this file and its directory.

note

Ubuntu mounts /var/run as tmpfs. This causes the /var/run/aerospike folder to be deleted after a reboot. The folder is recreated by init script and the permissions are fixed for the Aerospike user. If you run your server as some other user, you should update the ASD_USER in the init script (/etc/init.d/aerospike) to reflect your new user.

5. Configure logging In the logging stanza of /etc/aerospike/aerospike.conf, AEROSPIKE-USER must have write permissions, and AEROSPIKE-USER must have creation permission for the directory with the specified file. By default, the file is /var/log/aerospike/aerospike.log.

logging {
    # Log file must be an absolute path.
    file /var/log/aerospike/aerospike.log {
        context any info
    }
}

6. Configure file resources used by namespaces If your namespace data is configured for persistence to a file, AEROSPIKE-USER must have write permissions, and AEROSPIKE-USER must have creation permission for the directory with the specified file.:

namespace bar {
    ...
    storage-engine device {
        file /opt/aerospike/data/bar.data
        ...
    }
}

7. Configure SSD resources used by namespaces If you are using SSDs as raw devices, you must either add AEROSPIKE-USER to the disk group or add a udev rule to the AEROSPIKE-USER, giving it ownership of the devices.

Add user to disk group

sudo usermod -a -G nameOfDiskGroup AEROSPIKE-USER

Add udev rule

Add a rule similar to the following to the file /etc/udev/rules.d/99-aerospike.rules. This rule sets AEROSPIKE-USER as the owner of the devices /dev/sdb and /dev/sdc.

KERNEL=="sd[bc]", OWNER="AEROSPIKE-USER"

Save this file, then reload and trigger the udev rules.

udevadm control --reload-rules
udevadm trigger

SSDs used as filesystems, such as a flash index, need the same directory ownership and permissions detailed in Configure User and Group.

8. Configure SSD Scheduler to no-op Aerospike supports automatic SSD scheduling, but this feature does not work for a non-root user. You must explicitly set the devices' scheduler mechanism to "noop". For more details, see SSD Initialization.

9. Change Ownership of additional directories The ownership and permissions of the following directories also require changes to allow writing by the AEROSPIKE-USER:

 # Used for persisting system metadata
chown -R AEROSPIKE-USER:AEROSPIKE-GROUP /opt/aerospike/smd
 # Used for persisting User-Defined Functions (UDFs)
chown -R AEROSPIKE-USER:AEROSPIKE-GROUP /opt/aerospike/usr

Change an existing installation to non-root

1. Stop the Aerospike asd process. See Aerospike Daemon Management.
2. Tune the Linux kernel to the following required parameters:

/proc/sys/vm/dirty_bytes = 16777216
/proc/sys/vm/dirty_background_bytes = 1
/proc/sys/vm/dirty_expire_centisecs = 1
/proc/sys/vm/dirty_writeback_centisecs = 10

note

In an All-Flash deployment, the following Linux kernel parameters are required. enforce-best-practices verifies that these kernel parameters have the expected values.

• When running as non-root, you must prepare these values before running the Aerospike server.
• When running as root, the server configures them automatically.

Either way, if these parameters can't be correctly set (manually or automatically by the server), the node will not start.

3. Change the user and group in the Aerospike configuration file, as detailed in Configure User and Group.
4. Change ownership and permissions for all relevant Aerospike resources so they can be written by the new user and group.
5. Restart asd.

For the following directories, permissions need to be changed to allow file creation and writing. The simplest way is to change ownership of the directories to AEROSPIKE-USER:AEROSPIKE-GROUP:

• System metadata: /opt/aerospike/smd/.
• User-Defined Functions: /opt/aerospike/usr/ and all subdirectories.
• Log file and PID file: /var/log/aerospike/ and /var/run/aerospike/.
• If you are using file storage: /opt/aerospike/data/.

Additional necessary changes

The following additional changes are needed.

Shared memory Remove the existing shared memory blocks owned by Aerospike. If you use fast restart, removing these blocks forces a cold restart. New shared memory blocks are created by the new user and group.

To avoid a cold restart, uou can use a special script to change ownership of shared memory. For more information, see Fast Restart.

Raw devices If you are using raw device storage, see Configure SSD Resources used by Namespaces, except as noted below.

SSD Auto Scheduling

If you are using raw devices and running without root privileges, you must set the device scheduler mode. You cannot use the "scheduler-mode" configuration file option. Refer to Initializing Solid State Drives (SSDs) for more information.

Checking for success

After you make changes, start the node.

The Aerospike server can be started only by a root user or by a user with sudo permissions. The running process, however, is owned by the user defined in the user.conf configuration file.

For options on starting the server, see Aerospike Daemon Management.

If there are errors, the asd process does not start. Examine the logs for messages about which resources require attention.