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.
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:
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:
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
rootby following the instructions in the Changing RunAs User section, or
- Use the configuration setting
Git.AllowUnsandboxedGitBuilds = trueto 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:
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:
Package Manager prefers to run R in a sandbox. Package Manager can run R processes in three different environments:
- User Namespace Sandbox - When Package Manager is running under an unprivileged service account (by default, the
rstudio-pmuser), it attempts to run R in a user namespace. See About User Namespaces for more information.
- No Sandbox - If user namespace sandboxing is unavailable or if Package Manager is running as
root, you can configure
Git.AllowUnsandboxedGitBuilds = trueto 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 two 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.
See the Bind Mounts section for information on the bind mounts that are used.
If your operating system does not support user namespaces (see the User Namespace Support section), or if the Package Manager service is running 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.
When sandboxing is supported, the following locations are masked during R execution:
Server.DataDirdirectory containing all variable data used by Package Manager.
SQLite.Dirdirectory, which can optionally be placed outside the data directory.
Git.BuilderDirdirectory, which can optionally be placed outside the data directory
- Configuration directories, including
Server.SockFileDir, which contains the domain socket used by the
rspmCLI to communicate with the Package Manager service. This directory defaults to
- Any persistent storage directories that are defined outside of the
Server.DataDirdirectory. These locations are configured with
FileStorage.Locationconfiguration settings, and are not used by default.
Server.TempDir/rspm-workspacesdirectory, 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
TMPDIRenvironment variable of the process. This temporary directory is created under
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.
Each R process started by Package Manager is given its own unique temporary directory. These directories are created under
Server.TempDir's default value is obtained by first checking the
TMPDIR environment variable for a path and falls back to
You may wish to override
Server.TempDir if the default temporary directory has too little space or is mounted with the
If you do override
Server.TempDir please ensure the location can be reached by, read from, and written to by any user on the system. On most systems, temporary directories typically have permissions of
You can learn more about the
noexec option here.
About User Namespaces#
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.BuildConcurrencysetting (defaults to 25) = buildConcurrency
- Number of git builders using commit polling = commitBuilders
User Namespaces Required = ((tagBuilders * buildConcurrency) + commitBuilders) * 2
- Four git builders are configured with tag polling (tagBuilders = 4)
Git.BuildConcurrencyis set to the default of 25 (buildConcurrency = 25)
- Five git builders are configured with commit polling (commitBuilders=5)
Max User Namespaces = ((4 * 25) + 5) * 2 = 210 namespaces
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.
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#
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.
You can temporarily enable user namespace support by simply echoing a new value to
/proc/sys/user/max_user_namespaces. For example:
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
(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 Package Manager and all R processes. If you reconfigure Package Manager to run under a different unprivileged account, then R processes will automatically run under that account, as well.