Process Management#

Package Manager executes R to build packages for Git sources. Use the Server.RVersion setting to specify the R installation. See the section on Building R Packages for details on installing and configuring R.

Since R processes can execute arbitrary code and commands, Package Manager prefers to run R in a sandbox.

Quick Start#

This section walks you through the scenarios you are likely to encounter and helps you quickly decide how to configure Package Manager for building R packages from Git sources.

No Git Sources#

If you are not using Git sources, you do not need to worry about sandboxing.

For Git Sources#

If you are using Git sources, then:

Built-in OS Support#

If your operating system is configured for user namespace sandboxing, you will see a message like this in /var/log/rstudio/rstudio-pm/rstudio-pm.log at startup:

Attempting to detect R version in a user namespace sandbox.
Detected R version <version> at /path/to/R

If you see the above messages, no further action is required.

No built-in OS Support#

If your operating system does not support user namespaces, you will see a message like this in /var/log/rstudio/rstudio-pm/rstudio-pm.log at startup:

Warning: Unable to use R on this system. Building Git packages will be disabled.

If you see the above message, choose one of the following:

• If you are using CentOS / Red Hat, enable user namespaces by following the instructions in the Enable User Namespaces section,
• Change Package Manager to run as root by following the instructions in the Changing RunAs User section, or
• Use the configuration setting Git.AllowUnsandboxedGitBuilds = true to run R processes without a sandbox.

If you choose to enable user namespaces on CentOS / Red Hat, you should see this message in the server log at startup:

Attempting to detect R version in a user namespace sandbox.
Detected R version <version> at /path/to/R

If you choose to run Package Manager as root or use the Git.AllowUnsandboxedGitBuilds configuration setting, then you should see this message in the server log at startup:

Attempting to detect R version in a call to rsandbox
Detected R version <version> at /path/to/R

Sandboxing#

Package Manager prefers to run R in a sandbox. Package Manager can run R processes in three different environments:

1. User Namespace Sandbox - When Package Manager is running under an unprivileged service account (by default, the rstudio-pm user), it attempts to run R in a user namespace. See About User Namespaces for more information.
2. Unshare Sandbox - When Package Manager is running as the root user, it runs R processes as an unprivileged user and uses unshare to create sandboxes for the R processes.
3. No Sandbox - If neither user namespace or unshare sandboxing is available, you can configure Git.AllowUnsandboxedGitBuilds = true to allow R processes to run without a sandbox. This is insecure, should only be used when you implicitly trust the sources of all R packages that will be built.

The three environments above are described in more detail below.

User Namespace Sandbox (the default)#

User namespaces are supported as follows.

• Fully Supported on Ubuntu, openSUSE/SLES
• Supported with System Configuration on CentOS/Red Hat
• Varies by Kernel in Docker containers

For more information about user namespaces see About User Namepaces.

For details about operating system support for user namespaces, see User Namespace Support.

The Package Manager process runs as the rstudio-pm user and runs R securely in a new user namespace. When using a user namespace, parts of the file system are hidden from the R process, and certain OS features are isolated in new namespaces. For details on the file system isolation, see the Bind Mounts section.

You can learn more about cloning namespaces here, and you can learn about the Linux user namespace here. Your local man pages will document their behavior specific to your system.

See the Bind Mounts section for information on the bind mounts that are used.

Unshare Sandbox#

When the Package Manager process runs as the root user, R processes are securely invoked as an unprivileged user, rstudio-pm by default.

The "unshare" environment created for R execution involves first establishing a number of bind mounts and then switching to the target unprivileged user. The Posit Job Launcher uses unshare to alter the execution context available to R processes. Within this newly established environment, a number of mount calls are made in order to hide or isolate parts of the filesystem.

To configure the Package Manager process to run as root - see see the Changing RunAs User section.

See the Bind Mounts section for information on the bind mounts that are used.

You can learn more about unshare here. The mount call is detailed here. Your local man pages will document their behavior specific to your system.

No Sandbox#

If your operating system does not support user namespaces (see the User Namespace Support section) and you cannot run the Package Manager service as root, then you cannot isolate R processes from the rest of the system. However, you can configure the Git.AllowUnsandboxedGitBuilds = true setting to allow R processes to run without a sandbox. This can be a security risk, and you should only use the Git.AllowUnsandboxedGitBuilds = true setting if you trust the sources of the R packages that will be tracked from Git. The setting does not impact other sources such as CRAN packages.

Bind Mounts#

When sandboxing is supported, the following locations are masked during R execution:

• The Server.DataDir directory containing all variable data used by Package Manager.
• The SQLite.Dir directory, which can optionally be placed outside the data directory.
• The Git.BuilderDir directory, which can optionally be placed outside the data directory
• Configuration directories, including /etc/rstudio-pm.
• The Server.SockFileDir, which contains the domain socket used by the rspm CLI to communicate with the Package Manager service. This directory defaults to /var/run/rstudio-pm.
• The bin directory (usually /opt/rstudio-pm/bin) that contains the Package Manager binaries.
• Any persistent storage directories that are defined outside of the Server.DataDir directory. These locations are configured with FileStorage.Location configuration settings, and are not used by default.
• The Server.TempDir/rspm-workspaces directory, which contains temporary directories, one per process.

The following information is exposed during R execution:

• The Git repository source directory when building an R package from a Git source.
• The R package build destination directory when building an R package for a Git source.
• A per-process temporary directory specified in the TMPDIR environment variable of the process. This temporary directory is created under Server.TempDir/rspm-workspaces.

Running R processes have write access to the directory containing the unpackaged R code. Data written here will be visible to all processes running under the Package Manager service account, but are not visible to other R processes started by Package Manager when these processes run in a sandbox.

Temporary Directory#

Each R process started by Package Manager is given its own unique temporary directory. These directories are created under Server.TempDir/rspm-workspaces.

Server.TempDir's default value is obtained by first checking the TMPDIR environment variable for a path and falls back to /tmp otherwise.

You may wish to override Server.TempDir if the default temporary directory has too little space or is mounted with the noexec option.

You can learn more about the noexec option here.

About User Namespaces#

Introduction#

A user namespace is essentially a mapping of a user ID within a container to another user ID outside the container. Package Manager git builders utilize user namespaces, along with other container technologies, to isolate the R processes that build R packages. This provides better security, especially when R packages include pre- or post-build scripts.

Calculating User Namespace Requirements#

While building R packages, Package Manager uses two user namespaces. The Git.BuildConcurrency setting controls the number of concurrent Git builds in Package Manager per git builder. To determine the maximum number of user namespaces you need, you can perform a calculation like this:

• Number of git builders using tag polling = tagBuilders
• Git.BuildConcurrency setting (defaults to 25) = buildConcurrency
• Number of git builders using commit polling = commitBuilders

User Namespaces Required = ((tagBuilders * buildConcurrency) + commitBuilders) * 2

There is no harm in enabling a larger number of user namespaces; this is why the Admin Guide examples include large values like 15,000.

Security#

Red Hat Enterprise Linux has been slow to enable user namespaces by default to give the technology more time to incubate. If you are concerned about any security issues involving user namespaces, we recommend running Package Manager on a server or VM that is dedicated to Package Manager so that no other users, applications, or services can take advantage of the user namespace support.

User Namespace Support#

Ubuntu, openSUSE/SLES#

User namespace sandboxing is fully supported by Ubuntu and openSUSE/SLES.

CentOS, Red Hat#

CentOS/Red Hat supports user namespaces, but they must be enabled. To see if user namespace support is enabled, run cat /proc/sys/user/max_user_namespaces. If a value greater than 0 (zero) is returned, user namespace support is enabled.

To enable user namespace support permanently on CentOS/Red Hat, edit /etc/sysctl.d/files.conf with a change similar to the following. This change will be effective when the server is rebooted.

user.max_user_namespaces=15000

You can temporarily enable user namespace support by simply echoing a new value to /proc/sys/user/max_user_namespaces. For example:

echo 1000 > /proc/sys/user/max_user_namespaces

Docker#

User namespace support is a feature of Linux kernel version 3.8 and greater. If you are running Package Manager in a Docker environment, user namespace support will depend upon the kernel of the host operating system.

Creating a sandbox requires system calls not permitted by Docker's default seccomp profile. You must start the container with --security-opt 'seccomp=unconfined' to disable seccomp or provide another seccomp profile that includes the clone() system call if you wish to use R process sandboxing in a Docker environment.

Similarly, the use of bind mounts may cause issues if your container runtime has AppArmor enabled, because the default AppArmor profile does not allow mounts. You must start the container with --security-opt 'apparmor=unconfined' to disable AppArmor or provide an alternative profile that permits the use of mount.

(You can also run Docker with the --privileged flag instead of setting these security options, but this has much greater consequences than disabling seccomp or AppArmor.)

If you prefer to run under Docker without a modified seccomp or AppArmor profile, you can set Git.AllowUnsandboxedGitBuilds = true. Or, you can simply run Package Manager without any changes, in which case Git sources and sandboxed builds will be disabled but other functionality will continue to work as expected.

User Account for Processes#

The Package Manager installation creates a local rstudio-pm user account. This account runs all R processes even if you have reconfigured Package Manager to run as root. If you would like a different user to run R processes, customize the Launcher.ServerUser property. If you reconfigure Package Manager to run under a different unprivileged account, then R processes will automatically run under that account, as well.