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:
- 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. - No Sandbox - If user namespace sandboxing is unavailable or if Package Manager is running as
root
, you can configureGit.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 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.
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.
No Sandbox#
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.
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 therspm
CLI to communicate with the Package Manager service. This directory defaults to/var/run/rstudio-pm
. - Any persistent storage directories that are defined outside of the
Server.DataDir
directory. These locations are configured withFileStorage.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 underServer.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.
Note
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 1777
.
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
Example Calculation
- Four git builders are configured with tag polling (tagBuilders = 4)
Git.BuildConcurrency
is 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.
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.
You can temporarily enable user namespace support by simply echoing a new value to /proc/sys/user/max_user_namespaces
. For example:
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 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.