Oracle® Fusion Middleware
Part 3. Manage the API Gateway

In a typical deployment on Linux or Solaris, 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.

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

Traditional UNIX implementations distinguish between the following categories of processes:

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.

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.

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:

# chown -R user:usergroup /path/to/apigateway/installation

For example:

# chown -R admin:admin /home/admin/apigateway

crw-rw-r-- 1 root admin 126, 0 /dev/pkp_nle_dev

# sed -i /admin/d /lib/udev/load_{cavium,utimaco}

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:

# setcap 'cap_net_bind_service=+ep' /path/to/apigateway/installation//platform/bin/vshell

For example:

# setcap 'cap_net_bind_service=+ep' /home/admin/apigateway/platform/bin/vshell

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

# getcap /home/admin/apigateway/platform/bin/vshell

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

/home/admin/apigateway/platform/bin/vshell = cap_net_bind_service+ep

	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.

# yum install libcap2

# apt-get install libcap2-bin

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):

# setcap 'cap_net_bind_service=+ep cap_sys_rawio=+ep' 
   /path/to/apigateway/installation/platform/bin/vshell

For example:

# setcap 'cap_net_bind_service=+ep cap_sys_rawio=+ep' 
   /home/admin/apigateway/platform/bin/vshell

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

# getcap /home/admin/apigateway/platform/bin/vshell

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

/home/admin/apigateway/platform/bin/vshell = cap_net_bind_service,cap_sys_rawio+ep

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:

Create the ld.so.conf file

For a 64-bit API Gateway installation, create the following file:

/etc/ld.so.conf.d/gateway-libs.conf

And add the following lines:

/home/admin//apigateway/platform/jre/lib/amd64/server
/home/admin/apigateway/platform/jre/lib/amd64
/home/admin/apigateway/platform/lib/engines
/home/admin/apigateway/platform/lib
/home/admin/apigateway/ext/lib

For a 32-bit API Gateway installation, create the following file:

/etc/ld.so.conf.d/gateway-libs.conf

And add the following lines:

/home/admin/gateway/platform/jre/lib/i386/server
/home/admin/gateway/platform/jre/lib/i386
/home/admin/gateway/platform/lib/engines
/home/admin/gateway/platform/lib
/home/admin/gateway/ext/lib

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

# ldconfig

If there is an init.d script that runs the API Gateway as a service, you must change this to execute as the unprivileged user. The easiest way is by using sudo -u admin in the start command of the script.

For API Gateway version 6.1, this means changing the following line in the /etc/init.d/vordelgateway script:

daemon --pidfile $PIDFILE $DAEMON $DAEMON_ARGS >> $LOGFILE 2>&1

to the following:

daemon --pidfile $PIDFILE --user=admin $DAEMON $DAEMON_ARGS >> $LOGFILE 2>&1

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

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

On Solaris 10, a similar system is provided by adding the net_privaddr privilege to a user.

	Note
	On Solaris, you must modify the user instead of the API Gateway process (as already described for Linux in this topic).

In this case, you can modify an existing user (for example, gwadmin) as follows:

# usermod -K defaultpriv=basic,net_privaddr gwadmin