Run API Gateway as non-root on UNIX/Linux


In a typical deployment on UNIX/Linux, the process for the API Gateway instance runs as root. This is typically used to enable the process to listen on Internet domain privileged ports (port numbers less than 1024). However, this is a potential security issue because the root user has read/write access to all files on the system.

Therefore, if the API Gateway process ever becomes compromised, it could be used to return the contents of, or overwrite sensitive files, and the operating system would not prevent this. A solution to this problem is to run the API Gateway as a non-root user, but still allow the API Gateway process to bind to privileged ports.

Note   The steps in this topic apply to the following API Gateway processes:
  • API Gateway instance
  • Admin Node Manager
  • API Gateway Analytics

Linux capabilities

Traditional UNIX implementations distinguish between the following categories of processes:

  • privileged processes whose effective user ID is 0 (superuser or root)
  • unprivileged processes whose effective user ID is non-zero

Privileged processes bypass all kernel permission checks where unprivileged processes are subject to full permissions checking based on the processes credentials, usually from the effective user ID and effective group ID. More recent versions of the kernel divide up the privileges traditionally associated with the superuser into a set of capabilities that can be independently enabled or disabled. This allows a more fine-grained control of permissions for a process.

The capability to use with the API Gateway is CAP_NET_BIND, which specifically allows binding to privileged ports. The method by which this capability is set on the API Gateway is supported from kernel 2.6.24 onwards. If the kernel version is before 2.6.33, you must enable CONFIG_SECURITY_FILE_CAPABILITIES.

Before you begin

The sections that follow describe the steps that you must perform to run the API Gateway as an unprivileged user. This topic assumes that the new unprivileged user is named admin, and that the location of your API Gateway installation is /home/admin/apigateway.

Modify API Gateway file ownership

The unprivileged user must have ownership of the API Gateway files. If there is a pre-existing API Gateway installation, you must change the ownership of the API Gateway files to the new user that you intend to run the API Gateway with.

You can use the following command to change the user and group ownership of all files under the installation directory:

For example:


SSL accelerators for HSM

When using a Hardware Security Module (HSM), the unprivileged user must have access to the device corresponding to the cryptographic accelerator or HSM card. For HSMs such as Cavium and Ultimaco, this means that you must have access to the following directories:

  • Cavium: /dev/pkp_nle_drv
  • Utimaco: /dev/cs2a

For example, when using Cavium, an admin user using /dev/pkp_nle_drv should have the following permissions:

If the unprivileged user is different from admin , run the following command:

Set the CAP_NET_BIND capability on vshell

You must add the Linux capability to allow the API Gateway to listen on ports less than 1024 to the vshell file.

You can use the following command:

For example:

To verify that the permission has been set, run the following command:

For example, the output of this command should be as follows:

Note   For API Gateway versions prior to 6.3.0 (for example, 6.1.2), this path should be platform/libexec/vshell instead of platform/bin/vshell.

Install the libcap2 package if required

Depending on your Linux distribution, this may involve installing an additional software package. If the setcap command cannot be found, try installing the libcap2 package.

For yum-based systems (for example, Redhat Enterprise Linux, CentOS, Oracle Enterprise Linux), you can use the following command:

For Debian or Ubuntu, you can use the following command:

API Gateway appliance version 7.1.0 or later

You must set an additional privilege for API Gateway appliance version 7.1.0 or later. This step applies if you have an appliance and wish to run the vshell processes as a user other than the default admin user.

Run the following command (all on one line):

For example:

To verify that the permissions have been set, run the following command:

For example, the output of this command should be as follows:

Add API Gateway library locations

When executing a file with elevated permissions, certain environment variables are disabled as a security precaution. For this reason, you must make the locations of the API Gateway library files available to the operating system. You can do this using the steps described in this section:

  1. Create an file with the API Gateway shared object locations.
  2. Run ldconfig to reload the file.

Create the file

Create the following file:

And add the following lines:

Note   You should replace /home/admin/gateway with the root of your API Gateway installation.

Run ldconfig

After creating the /etc/ file, run the following command to reload the library cache file:

Modify the jvm.xml file

To modify your jvm.xml file, perform the following steps:

  1. Open the system/conf/jvm.xml file in your API Gateway installation.
  2. Near the top of the file, add an extra line after the following line:
  3. Add the following:

Restart the API Gateway

When you have completed the steps described in this topic, start the API Gateway with the unprivileged user.

Further information

For more details, see Start and stop the API Gateway.

Related Links