Process Management#

Advanced

Posit Package Manager executes R and Python to build packages for Git sources. Package Manager can automatically scan for R and Python in some well-known locations. Use the Server.RVersion setting to explicitly specify the R installation, or use Server.PythonVersion to specify the Python installation. Review the section on Building Git Packages for details on installing and configuring R and Python.

Since R and Python processes can execute arbitrary code and commands, Package Manager prefers to run them 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 and Python 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
...
Attempting to detect Python version in a user namespace sandbox.
Detected Python version <version> at /path/to/python

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 for R will be disabled.
...
Warning: Unable to use Python on this system. Building Git packages for Python 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 and Python 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
...
Attempting to detect Python version in a user namespace sandbox.
Detected Python version <version> at /path/to/python

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
...
Attempting to detect Python version in a call to rsandbox
Detected Python version <version> at /path/to/python

Sandboxing#

Package Manager prefers to run R and Python in a sandbox. Package Manager can run these processes in two 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 and Python in a user namespace. See About User Namespaces for more information.
2. No Sandbox - If user namespace sandboxing is unavailable or if Package Manager is running as root, you can configure Git.AllowUnsandboxedGitBuilds = true to allow R and Python processes to run without a sandbox. This is insecure, should only be used when you implicitly trust the sources of all R and Python 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 and Python securely in a new user namespace. When using a user namespace, parts of the file system are hidden from the 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 and Python processes from the rest of the system. However, you can configure the Git.AllowUnsandboxedGitBuilds = true setting to allow these 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 and Python packages that will be tracked from Git. The setting does not impact other sources such as CRAN or PyPI packages.

Bind Mounts#

When sandboxing is supported, the following locations are masked during R or Python 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.
• 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 or Python execution:

• The Git repository source directory when building an R or Python package from a Git source.
• The package build destination directory when building an R and Python 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 and Python processes have write access to the directory containing the unpackaged code. Data written here will be visible to all processes running under the Package Manager service account, but are not visible to other R and Python processes started by Package Manager when these processes run in a sandbox.

Temporary Directory#

Each R and Python 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 and Python processes that build packages. This provides better security, especially when packages include pre- or post-build scripts.

Calculating User Namespace Requirements#

While building R or Python 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.

Ubuntu 24.04 and later versions restrict services by using unprivileged user namespaces, which isolate processes and limit their capabilities. Package Manager includes a default AppArmor profile starting from Ubuntu 24.04 and newer versions. This profile is located at /etc/apparmor.d/rstudio-pm.

CentOS, Red Hat#

CentOS/Red Hat supports user namespaces, but they must be enabled. To determine 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 or Python 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, set Git.AllowUnsandboxedGitBuilds = true. Or, 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 and Python processes. If you reconfigure Package Manager to run under a different unprivileged account, then R and Python processes will automatically run under that account, as well.