Skip to main content
Loading

Configure Aerospike to Run as Non-root User

Here are details about how to configure Aerospike to run as a non-root user.

note

Even if you configure Aerospike to run as a non-root user, the server must be started by a user with root permissions. See Aerospike Daemon Management.

Thereafter, the running process is owned by the user defined in the Aerospike configuration, as described here.

Notational conventions

In this discussion, we call the non-root user and group aerospikeUser and aerospikeGroup.

Configure a Newly Installed Aerospike Node​

Here's how to configure a new installation of Aerospike to run as a non-root user.

Install Aerospike​

We assume that you have already installed Aerospike, as described in the install documentation.

The default user/group and owner of the Aerospike files is aerospike/aerospike. You can either use this user/group or create an alternative.

Configure User and Group​

Edit the Aerospike configuration file /etc/aerospike/aerospike.conf. In the service stanza of the file, change the value of user to the desired aerospikeUser and group to the desired aerospikeGroup.

service {
    user aerospikeUser
    group aerospikeGroup
}

Changing 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 aerospikeUser and aerospikeGroup.

note

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

Here we 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=aerospikeUser
Group=aerospikeGroup
EOF

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

Configure PID File​

note

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

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

Make sure that your aerospikeUser and aerospikeGroup have write access to this file and its directory. There are several alternatives for accomplishing this, including chowning the directory's user and group or chgrping only the group and making sure aerospikeUser is a member of that group.

note

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

Configure Logging​

In the logging stanza of /etc/aerospike/aerospike.conf, ensure the file specified is a file that aerospikeUser can write to and that aerospikeUser has creation permission for the directory. 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
    }
}

Configure File Resources used by Namespaces​

If your namespace data is configured for persistence to a file, ensure that aerospikeUser can write that file and that aerospikeUser has creation permission for the directory:

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

Configure SSD Resources used by Namespaces​

If you are using SSDs as raw devices, you need to either add aerospikeUser 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 aerospikeUser

Add udev rule

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

KERNEL=="sd[bc]", OWNER="aerospikeUser"

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

$ udevadm control --reload-rules
$ udevadm trigger

SSDs that are as filesystems, for example, a flash index, need the same directory ownership and permissions detailed in Configure User and Group.

SSD Scheduler Must Be No-op​

You can configure Aerospike for an automatic SSD device scheduler setting. Automatic SSD scheduling does not work with a non-root user.

You need to explicitly set the devices' scheduler mechanism to be "noop". For more detail, see SSD Initialization.

Change Ownership of Additional Directories​

The ownership and permissions of the following directories also require changes to allow writing by the aerospikeUser:

 # Used for persisting System Meta Data
$ chown -R aerospikeUser:aerospikeGroup /opt/aerospike/smd
 # Used for persisting User-Defined Functions (UDFs)
$ chown -R aerospikeUser:aerospikeGroup /opt/aerospike/usr

Configure pre-version 5.0 XDR​

These details apply only to versions of Aerospike Server prior to 5.0. The latest XDR configuration does not require specific file ownership.

If you are using XDR, make sure the relevant files and parent directories have the proper write permission, as shown below from the Aerospike configuration file:

 # XDR
xdr {
    enable-xdr                   true
    namedpipe-path               /tmp/xdr_pipe
    digestlog-path               /etc/aerospike/digestlog 10000000000
    errorlog-path                /var/log/aerospike/asxdr.log
    xdr-pidfile                  /var/run/aerospike/asxdr.pid 
    ...
}

Change an Existing Installation​

Here are the general steps for switching from running as root to running as non-root user. You need to:

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

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 aerospikeUser:aerospikeGroup:

  • 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/.

Change Service User and Group​

For details, see Changing Ownership in user.conf.

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 cannot use the "scheduler-mode" configuration file option. Instead you must make sure to set the device scheduler mode. For more information, see SSD Initialization.

Checking for Success​

After you have made these changes, start the node.

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

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 correction.

Last updated on