5 R Sessions
5.1 R Executable and Libraries
5.1.1 Locating R
RStudio uses the version of R pointed to by the output of the following command:
$ which RThe which command performs a search for the R executable using the system PATH. RStudio will therefore by default bind to the same version that is run when R is executed from a terminal.
For versions of R installed by system package managers this will be /usr/lib/R. For versions of R installed from source this will typically (but not always) be /usr/local/lib/R.
If you want to override which version of R is used then you can use the rsession-which-r setting. For example:
/etc/rstudio/rserver.conf
rsession-which-r=/usr/local/bin/RNote that this change will not take effect until the server is restarted.
5.1.1.1 Using Multiple Versions of R
The section above describes how RStudio locates the global default version of R. It’s also possible to specify alternate versions of R either by user or by group. The R Versions section describes this in more detail.
5.1.3 Customizing Session Launches
5.1.3.1 Profile Script Execution
RStudio launches R sessions under a bash login shell. This means that prior to the execution of the R session the bash shell will read and execute commands from this file if it exists:
/etc/profileAfter reading that file, it looks for the following files and reads and executes commands from the first one that exists and is readable (it’s important to note that only one of these files will be read and executed):
~/.bash_profile
~/.bash_login
~/.profileIf you have further RStudio specific initialization logic (exporting environment variables, etc.) you can optionally create an R session specific profile script at:
/etc/rstudio/rsession-profileIf it exists this script will be executed prior to the bash shell that launches the R session. This script must be executable by all RStudio users, so it is recommended that you set its file permissions to 755 via the following command:
chmod 755 /etc/rstudio/rsession-profileIn some situations, you will not want to run user shell profile scripts. This is also a good way to troubleshoot the inability for sessions to launch, as it could indicate a conflict is occurring due to environment variables being set in the shell profiles. To disable execution of the shell profiles, set the rsession-no-profile option to 1 in /etc/rstudio/rserver.conf. For example:
/etc/rstudio/rserver.conf
rsession-no-profile=15.1.3.2 Environment Variables
R sessions inherit environment variables that are explicitly exported from the profile scripts described above. It’s also possible to append paths to the LD_LIBRARY_PATH environment variable using the rsession-ld-library-path option (see previous section for details).
Another source of environment variables are PAM sessions. On Debian/Ubuntu systems, the default PAM profile run by RStudio includes the environment variables defined in /etc/security/pam_env.conf and /etc/environment. To learn more about setting environment variables with PAM you should consult the PAM Sessions section as well as the documentation on the pam_env module here: http://linux.die.net/man/8/pam_env.
5.1.3.3 Program Supervisors
You may also wish to run R sessions under a program supervisor that modifies their environment or available resources. You can specify a supervisor (and the arguments which control it’s behavior) using the rsession-exec-command setting. For example:
/etc/rstudio/rserver.conf
rsession-exec-command=nice -n 10This example uses the nice command to run all R sessions with a lower scheduling priority. See http://linux.die.net/man/1/nice for more details on nice. Note that for nice in particular it’s possible to accomplish the same thing using user and group profiles (and even specify a custom priority level per user or group). See the User and Group Profiles section for more details.
5.1.4 Diagnosing Session Launch Failures
RStudio Workbench allows you to launch sessions in a diagnostics mode to capture extended session launch information in the event that you run into problems when starting sessions. This mode captures the environment variables that are set by all of the profile scripts, loading of any modules, arguments passed to the session, and the exit code of the session and any stack trace information if the session crashes. To enable collection of this diagnostic data, set the rsession-diagnostics-enabled flag in /etc/rstudio/rserver.conf like below:
/etc/rstudio/rserver.conf
rsession-diagnostics-enabled=1When this setting is enabled, all sessions that are started will create a diagnostics file that contains extended launch diagnostics under the /tmp directory by default. To change the location, use the rsession-diagnostics-dir to point to the desired directory, like so:
/etc/rstudio/rserver.conf
rsession-diagnostics-dir=/tmp/diagnosticsBe aware that this directory should be accessible by all users of the system. If it does not exist, RStudio will attempt to create it and set its permissions to Read/Write/Execute for everyone (file permissions of 777).
To diagnose containerized sessions (e.g. Kubernetes) launched via the Job Launcher, set rsession-diagnostics-dir to a shared folder mounted in the container via /etc/rstudio/launcher-mounts. Otherwise sessions may fail to launch due to the default location under /tmp not being available in the containers.
Strace information can be included in the diagnostics file by adding the rsession-diagnostics-strace-enabled flag as shown below. Before using this setting, ensure that strace is installed and is available on your users’ path.
/etc/rstudio/rserver.conf
rsession-diagnostics-enabled=1
rsession-diagnostics-strace-enabled=1We recommend that you send these files to RStudio support to aid in troubleshooting any session launch issues should they arise.
5.1.4.1 Safe Mode
Two of the most common session startup problems are (1) oversized global R environments, which take a long time to load into memory when the session is resumed, and (2) problematic code in .Rprofile which takes too long to run or throws errors during startup.
In order to help eliminate these variables as the cause of session startup issues, RStudio can start sessions in Safe Mode. This mode starts the session without running .Rprofile or restoring the global environment. If a session takes too long to start, the user will be given the option to restart a session in Safe Mode.
It is also possible to control these features independently, which can be helpful when troubleshooting issues.
5.1.4.1.1 Skipping Workspace Restoration
To skip workspace restoration (i.e. reloading the contents of the global environment), append ?restore_workspace=0 to the R session’s full URL. For example:
https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?restore_workspace=0Note that this will work only if the session is not already running. If you are currently waiting for the session to start, it is too late to try to skip workspace restoration, since it is already in progress. Kill or force-kill the session before restarting the attempt with the restore_workspace flag.
5.1.4.1.2 Omitting .Rprofile
To skip executing .Rprofile, append run_rprofile=0 to the R session’s full URL. For example:
https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?run_rprofile=0Just like restore_workspace, this can only be used prior to the session starting.
Note that Safe Mode is only available when RStudio itself is starting sessions, so it is not a useful troubleshooting technique when sessions are being run using the Job Launcher.
5.2 Session Startup Scripts
When an R session starts up, the following scripts are run:
- Any PAM session modules Pro
- The
/etc/rstudio/rsession-profilescript Pro - The environment module for the R version in use, if any; see Extended R Version Definitions Pro
- The prelaunch script for the R version in use, if any; see Extended R Version Definitions Pro
- System and user shell profile scripts, such as
.bash_profilePro - The R session itself, inside any supervisor specified by
rsession-exec-commandPro .Rprofileand other R initialization scripts; see Initialization at the Start of a Session for details- RStudio-internal session startup scripts
- The
rstudio.sessionInithook
The very last of these provides a way to run code after the R session is fully booted and ready to use; since it only runs in RStudio it can be used to finalize R sessions in RStudio-specific ways, using for example methods in the rstudioapi package. Here is an example that prints the RStudio version in new R sessions:
/opt/R/version/lib64/r/etc/Rprofile.site
setHook("rstudio.sessionInit", function(newSession) {
if (newSession)
message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")5.3 User and Group Profiles
User and Group Profiles enable you to tailor the behavior of sessions on a per-user or per-group basis. The following attributes of a session can be configured within a profile:
- Version of R used
- CPU affinity (i.e. which set of cores the session should be bound to)
- Scheduling priority (i.e. nice value)
- Resource limits (maximum memory, processes, open files, etc.)
- R session timeouts (amount of idle time which triggers session suspend)
- R session kill timeouts (amount of idle time which triggers a session to be destroyed and cleaned up)
Note that if launching sessions via the Job Launcher, scheduling priority and resource limits are not ignored, but these should generally be configured via the Job Launcher itself where applicable. For example, when running Kubernetes sessions, memory limits can be specified each time a session is launched, so memory limits should be configured by the Job Launcher in that case.
5.3.1 Creating Profiles
Profiles are defined within the file /etc/rstudio/profiles. Note that this file is not created by default so you’ll need to create it if doesn’t already exist. Profiles are divided into sections of three different type:
Global (
[*])Per-group (
[@groupname])Per-user (
[username])
Here’s an example profiles file that illustrates each of these types:
/etc/rstudio/profiles
[*]
cpu-affinity = 1-4
max-processes = 800
max-memory-mb = 2048
session-limit=5
session-timeout-minutes=60
session-timeout-kill-hours=24
[@powerusers]
cpu-affinity = 5-16
nice = -10
max-memory-mb = 4096
session-limit=10
[jsmith]
r-version = /opt/R/3.1.0
session-timeout-minutes=360This configuration specifies that by default users will run on cores 1 to 4 with a limit of 800 processes and 2GB of virtual memory. It also specifies that members of the powerusers group will run on cores 5 to 16 with an elevated nice priority and a limit of 4GB of memory. Finally, the user jsmith is configured to use a different version of R from the system default.
Note that the /etc/rstudio/profiles file is processed from top to bottom (i.e. settings matching the current user that occur later in the file always override ones that appeared prior). Additionally, some settings do not apply to certain editor types (like Jupyter or VS Code). The settings available within /etc/rstudio/profiles are described in more depth below.
5.3.2 Session Limit
To configure the maximum allowed number of sessions you can use the session-limit option. This is a more flexible choice than disabling multiple sessions entirely with server-multiple-sessions.
For example to limit user to 5 sessions:
session-limit=5By default there is no limit to the number of sessions other than the one specified by the license. This limit has no effect if greater than the number of sessions allowed by your license.
This setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.3 Session Timeout
To configure the amount of idle time to wait before suspending sessions you can use the session-timeout-minutes option. Idle time is the amount of time since a session has run any R commands, including commands typed by the user in the console and the execution of any R scripts.
For example:
session-timeout-minutes=360The default value if none is explicitly specified is 120 minutes.
There are some conditions where an R session will not be suspended, these include:
- When a top-level R computation is running
- When the R prompt is not in it’s default state (e.g. during a debugging session)
You can also specify that R sessions should never be suspended by setting the session-timeout-minutes to zero. For example:
session-timeout-minutes=0This setting only applies to the RStudio IDE, and does not apply to Jupyter or VS Code. Session timeout can be configured for Jupyter sessions via the session-cull setting - see Jupyter configuration for more details. There is currently no mechanism for timing out VS Code sessions.
5.3.4 Session Timeout Kill
To configure the amount of time to wait before forcefully killing and destroying sessions you can use the session-timeout-kill-hours option in the /etc/rstudio/rsession.conf file. This allows you to specify how much time should pass before a session is automatically cleaned up. This is the length of time during which a session exists without user input (regardless of computation status) allowing you to automatically reclaim temporary disk space used by the session, and to stop its processes and children.
This setting should only be used to ensure that any sessions that users have forgotten about are destroyed, reclaiming valuable disk space. Note that this setting does not work if the server-shared-storage-path is located on a root squash mount.
Sessions can be destroyed while important computations are executing. The user whose session is cleaned will also lose all unsaved code and data.
This setting can also be used in conjunction with session-timeout-minutes, allowing already suspended sessions to be cleaned up.
For example:
session-timeout-kill-hours=48The default value if none is explicitly specified is 0 hours, meaning sessions will never be killed and destroyed automatically. The supplied value should be an integer representing the amount of hours a session can go without user interaction before being killed.
This setting only applies to the RStudio IDE, and does not apply to Jupyter or VS Code. Session timeout can be configured for Jupyter sessions via the session-cull setting - see Jupyter configuration for more details. There is currently no mechanism for timing out VS Code sessions.
5.3.4.1 Interaction with session-timeout-minutes
It is recommended that the session-timeout-kill-hours be set to a much higher span of time than that specified by session-timeout-minutes. This will allow sessions to be suspended (and not destroyed) before they are forcefully killed and cleaned up, allowing for a better user experience. Note however, that if a session is running a long-running computation, it may not be suspended but it will still be killed.
If session-timeout-kill-hours is set to an amount of time less than session-timeout-minutes (which has a default of 2 hours), then sessions will never be suspended and they will be forcefully killed and cleaned up.
The two settings may be set to the same amount of time, but this is not recommended. In this case, it is undefined whether or not the session will be suspended, but the session will be killed and cleaned up regardless.
5.3.5 CPU Affinity and Scheduling Priority
If you have users or groups that consistently require more compute resources than others you can use profile settings to reserve CPUs (cpu-affinity) as well as raise overall scheduling priority (nice).
5.3.5.1 CPU Affinity
The cpu-affinity setting specifies which cores on a multi-core system should be used to schedule work for a session. This is specified as a comma-separated list of core numbers (1-based) where both individual cores and ranges of cores can be specified. For example:
cpu-affinity = 1,2,3,4
cpu-affinity = 1-4
cpu-affinity = 1,2,15-16To determine the number of addressable cores on your system you can use the nproc command:
$ nprocThis setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.5.2 Scheduling Priority
The nice setting specifies a relative priority for scheduling session CPU time. Negative 20 is the highest nice priority and positive 20 is the lowest priority. The system default niceness for processes is typically 0. The following are all valid nice values:
nice = -10
nice = 0
nice = 15Scheduler behavior around nice priorities varies by system. For more details see nice use and effect.
This setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.6 Resource Limits
Profiles can also be used to specify limits on available memory as well as the maximum number of processes and open files.
5.3.6.1 Available Memory
The max-memory-mb setting controls the maximum amount of addressable memory for R sessions (by default memory is unlimited). This example specifies a limit of 2GB:
max-memory-mb = 2048Note that this value sets the amount of virtual memory that can be used by a process. Virtual memory includes code (i.e. shared libraries) loaded by the process as well as things like memory mapped files, so can often consume several hundred megabytes even for a vanilla R session. Therefore, you want to be sure not to set this threshold too low (in no case should you set it below 1024).
This setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.6.2 Number of Processes
The max-processes setting controls the maximum number of system processes createable by a user. This setting is useful to prevent either inadvertent or malicious fork bombs. The following example sets a limit of 800 processes:
max-processes = 800Note that max-processes refers to system processes, not R processes. Users may need to create many system processes in order to use RStudio, so we recommend setting this value high and testing the outcome before deploying in production.
This setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.6.3 Number of Open Files
In most Linux environments there is a maximum of 1024 open files per process. This is typically more than enough, but if you have a particular applications that requires more open files the max-open-files setting can be used to increase the limit. For example:
max-open-files = 2048This setting applies to all session types (RStudio, Jupyter, and VS Code).
5.3.7 Using Multiple Versions of R
As illustrated above, you can bind users or groups to distinct versions of R installed on your server. This is controlled by the r-version option. Here are several examples of it’s use:
r-version = /usr/lib/R
r-version = /usr/local/lib/R
r-version = /opt/R/3.1.0
r-version = /opt/R/3.2.0Note that r-version specifies the full path to the directory where R is installed.
See the R Versions chapter for additional details on running multiple versions of R on a single server.
This setting only applies to the RStudio IDE, and does not apply to Jupyter or VS Code.
5.4 Multiple R Sessions
RStudio Workbench enables users to have multiple concurrent R sessions on a single server or load balanced cluster of servers (the open-source version of RStudio Server supports only a single session at a time).
5.4.1 Creating New Sessions
You can start a new R Session using the New Session command from the Session menu (or the corresponding toolbar button near the top-right of the IDE).
You can also open an existing RStudio project in a new R session by using the Open Project in New Session command. When switching projects there is also a button on the right side of the projects menu that lets you specify that the project should be opened in a new session rather than within the current one.
You can review all currently running sessions and switch between them using the Sessions toolbar near the top-right of the IDE.
5.4.2 Session Lifetimes
R Sessions are long-running tasks that continue to be available until you explicitly quit them (you can think of them as you’d think of multiple top-level RStudio windows running on the desktop). This means that you can kickoff a long running job in one session and then switch to another session, revisiting the original session later to check on it’s progress. As is also possible on the desktop, you can navigate between different projects and working directories within a session.
Sessions will suspend automatically when they are idle and then be automatically resumed next time they are accessed. To permanently quit a session you can use the Quit Session command located on the File menu or the corresponding toolbar button at the top right of the IDE.
5.4.3 Disabling Multiple Sessions
If you wish disable support for multiple sessions you can use the server-multiple-sessions option. For example:
/etc/rstudio/rserver.conf
server-multiple-sessions=05.5 PAM Sessions
RStudio Workbench uses PAM (Pluggable Authentication Modules) for both user authentication as well to establish the environment and resources available for R sessions. This is accomplished using the PAM session API. PAM sessions are used for a variety of purposes:
- To initialize environment variables
- To automatically create local users after authentication or authorization against a directory server.
- To mount remote drives
- To initialize and destroy Kerberos tickets
This section explains how to configure and customize PAM sessions with RStudio Workbench.
5.5.1 Session PAM Profile
For PAM authentication RStudio Workbench uses the either the /etc/pam.d/other profile (Debian/Ubuntu) or /etc/pam.d/rstudio profile (RedHat/CentOS). However, for launching R sessions a different PAM profile is used. This is because the launching of R sessions may not coincide with authentication (e.g. returning to the site with login credentials cached in a cookie or resuming a suspended session). Therefore, the PAM directive that enables authentication with root privilege only (auth sufficient pam_rootok.so) needs to be present in the PAM profile.
Note: Some
sssdconfiguration additionally require PAM account verification asrootto present on both theauthandaccountdirectives in the PAM profile (auth sufficient pam_rootok.soandaccount sufficient pam_rootok.so). Be sure to include this if you see errors when starting new R sessions.
The behavior that RStudio Workbench requires is essentially the same as that of the su command (impersonation of a user without a password). Therefore by default RStudio Workbench uses the /etc/pam.d/su profile for running R sessions.
The session PAM profile itself is also run whenever the user accesses the home page. Regardless of where the session actually runs (such as on another machine if using Job Launcher sessions), the PAM profile is executed on the RStudio Workbench instance itself when opened via the home page.
5.5.1.1 Creating a Custom Profile
The /etc/pam.d/su profile has different default behavior depending upon your version of Linux and local configuration. Depending upon what type of behavior you want associated with R sessions (e.g. mounting of disks, setting of environment variables, enforcing of resource limits, etc.) you’ll likely want to create a custom profile for R sessions. For example, if you wanted to use a profile named rstudio-session you would add this to the configuration file:
/etc/rstudio/rserver.conf
auth-pam-sessions-profile=rstudio-sessionHere is in turn what the custom profile might contain in order to enable a few common features of PAM sessions (this is based on a modified version of the default su profile on Ubuntu):
/etc/pam.d/rstudio-session
# This allows root to su without passwords (this is required)
auth sufficient pam_rootok.so
# This module parses environment configuration file(s)
# and also allows you to use an extended config
# file /etc/security/pam_env.conf.
# parsing /etc/environment needs "readenv=1"
session required pam_env.so readenv=1
# Locale variables are also kept into /etc/default/locale in etch
# reading this file *in addition to /etc/environment* does not hurt
session required pam_env.so readenv=1 envfile=/etc/default/locale
# Enforces user limits defined in /etc/security/limits.conf
session required pam_limits.so
# The standard Unix authentication modules
@include common-auth
@include common-account
@include common-session5.5.1.2 Custom Profile with Passwords
Note that in the above configuration we rely on pam_rootok.so to enable authentication without a password. This is necessary because RStudio doesn’t retain the passwords used during the authentication phase.
In some situations however passwords are important for more than just authentication. PAM profiles support a use_first_pass directive to forward passwords used during authentication into other modules (for example, to request a Kerberos ticket with pam_krb5.so or to mount an encrypted or remote drive with pam_mount.so). For these scenarios RStudio Workbench supports an optional mode to retain passwords after login and then forward them into the PAM session profile. This is enabled via the auth-pam-sessions-use-password setting:
/etc/rstudio/rserver.conf
auth-pam-sessions-use-password=1Note: This setting is only available when using PAM authentication.
In this scenario you should remove the auth sufficient pam_rootok.so directive and replace it with whatever authentication directives apply in your environment. You can then employ the use_first_pass directive to forward the password as necessary to other modules.
For example, here’s a very simple RedHat/CentOS PAM configuration file that uses system default authentication and forwards the password into the pam_mount.so module. Note that we are no longer using pam_rootok.so because the password is now available when the session is created.
/etc/pam.d/rstudio-session
# Auth/account (use system auth and forward password to pam_mount)
auth include system-auth
auth optional pam_mount.so use_first_pass
account required pam_unix.so
# Session (read environment variables and enforce limits)
session required pam_env.so readenv=1
session required pam_env.so readenv=1 envfile=/etc/default/locale
session required pam_limits.soNote that this configuration requires that RStudio Workbench retain user passwords in memory. This retention is done using industry best-practices for securing sensitive in-memory data including disabling ptrace and core dumps, using mlock to prevent paging into the swap area, and overwriting the contents of memory prior to freeing it. When using Job Launcher, the passwords are securely transmitted in encrypted form to different nodes or containers running the R sessions.
Note: Launcher will require TLS/SSL to be configured in order to allow PAM profiles with passwords to be used.
5.5.1.3 More Resources
If you want to learn more about PAM profile configuration the following are good resources:
5.5.2 PAM Session Cleanup
By default, RStudio Workbench does not close PAM sessions when their associated R process exits. This is because PAM sessions often initialize and maintain resources that require more persistence that the lifetime of a single R session (e.g. mounted drives, Kerberos tickets, etc.). If a user has multiple active R sessions then closing the PAM session associated with one of them might unmount a drive or revoke a ticket that is still required by another R session.
It is however possible to manually close the PAM session associated with an R session by force suspending it. This can be accomplished in one of two ways:
By pressing the Suspend button on the Sessions page of the Administrative Dashboard.
By executing a
force-suspendorforce-suspend-allcommand as described in Suspending Sessions.
If you prefer that PAM sessions be closed whenever their associated R session exits you can use the auth-pam-sessions-close setting. For example:
/etc/rstudio/rserver.conf
auth-pam-sessions-close=1Note that if you specify this setting be aware that depending upon what resources are managed by your PAM sessions it may be incompatible with users running multiple concurrent R sessions (because for example a drive might be unmounted from underneath a running session). In this case you may wish to disable support for multiple R sessions (see the section on Multiple R Sessions for details on how to do this).
5.5.3 PAM Sessions with the Job Launcher
When launching sessions via the Job Launcher, you must also configure PAM on any Launcher nodes (for Local or Slurm plugins) and within any containers used (if using Kubernetes). That’s because PAM sessions are needed at the point where the R session is run, which for Launcher means some machine/container other than the one where RStudio Workbench is running. The PAM configuration is still required at the RStudio Workbench machine for authentication purposes.
Launcher session PAM profiles run with different permissions at different stages of the session launch pipeline. When a user visits the RStudio home page for the first time, their PAM session is initiated with root privilege, allowing the session to rely on pam_rootok.so, as discussed in the previous sections, and it is opened on the RStudio Workbench instance itself. However, Job Launcher sessions themselves never have true root privilege (unlike traditional session launches which have root privileges during early initialization), and thus cannot rely on pam_rootok.so. Their PAM sessions are opened on the actual instance where the session is running (e.g. a Kubernetes or Slurm node).
It is generally sufficient to simply do all your necessary setup, such as user directory creation, whenever the user accesses the home page for the first time. This means that you can rely on pam_rootok.so and do not need password forwarding. However, if you need to also ensure that PAM sessions are created when actual sessions are started (e.g., for Kerberos or pam_mount), you will need to enable auth-pam-sessions-use-password to forward the user’s PAM credentials to the session.
Note: When Kerberos or LDAP/Active Diretory are required for PAM sessions, individual Launcher nodes or Kubernetes containers will have to either join the Kerberos domain or be configured to use
sssdfor obtaining LDAP/AD users and groups.
When forwarding credentials over a TCP connection, we require that Job Launcher connections be secured with SSL to prevent leaking of the credentials. Therefore, if auth-pam-sessions-use-password is set for Launcher sessions, you will also need to set launcher-use-ssl and configure the Job Launcher to use SSL (see the Job Launcher SSL Considerations section for more info).
The following sample configuration demonstrates forwarding of PAM user credentials to Job Launcher sessions. This is only recommended if it is absolutely necessary to start PAM sessions whenever Launcher sessions are started, and it is not sufficient to simply start a PAM session whenever the user accesses the homepage for the first time:
/etc/rstudio/rserver.conf
launcher-sessions-enabled=1
launcher-use-ssl=1
auth-pam-sessions-enabled=1
auth-pam-sessions-profile=rstudio
auth-pam-sessions-use-password=1The following sample configuration demonstrates a basic PAM setup where it is sufficient to only start PAM sessions when users visit the homepage, and thus no PAM sessions are started when Launcher sessions are started:
/etc/rstudio/rserver.conf
launcher-sessions-enabled=1
auth-pam-sessions-enabled=1
auth-pam-sessions-profile=rstudio5.5.4 Disabling PAM Sessions
If you don’t want RStudio Workbench to utilize PAM sessions you can disable this feature using the auth-pam-sessions-enabled setting. For example:
/etc/rstudio/rserver.conf
auth-pam-sessions-enabled=0Warning: When using
sssdto automatically provision local system accounts using LDAP or Active Directory, RStudio relies on PAM sessions configured withpam_mkhomedir(or equivalent) to create the home directories of a user that has never logged into the server. Disabling PAM sessions in this scenario may cause permission errors when starting session unless other methods for creating users’ home directories are used.
Important: PAM sessions are initially disabled by default when using RStudio Launcher to simplify its initial setup in a multi-node environment. However, many environments still require PAM sesssions and in those cases that needs to be explicitly enabled with Launcher.
5.6 Kerberos
You can use PAM sessions to arrange for Kerberos tickets to be made available for use by R sessions. This is accomplished using the pam_sss PAM module. Note that you may need to install this module separately depending on which Linux distribution/version you are running.
5.6.1 Configuration
Note: You should be sure to understand the previous section on PAM Sessions before attempting to modify your configuration to support Kerberos.
The following are simple examples of the pam_sss and sssd.conf configuration directives you would need to add to use Kerberos with RStudio. Note that the sssd Kerberos backend supports a large number of options, some of which may be required to get Kerberos working correctly in your environment. You should consult the documentation before proceeding to ensure you’ve specified all options correctly.
Important: If you are migrating your Kerberos settings from the now deprecated
pam_krb5topam_sss, consult the pam_krb5 migration documentation for additional information.
The main PAM profile for RStudio should be modified to include the following pam_sss directives:
/etc/pam.d/rstudio
auth sufficient pam_sss.so
account required pam_sss.so
session requisite pam_sss.soIn addition to modifying the main PAM profile, you will also need to create a custom PAM session profile for RStudio (as described in Creating a Custom Profile). This needs to include the appropriate pam_sss directives. For example:
/etc/pam.d/rstudio-session
auth required pam_sss.so
account [default=bad success=ok user_unknown=ignore] pam_sss.so
password sufficient pam_sss.so use_authtok
session requisite pam_sss.soNote that typically when you create a custom PAM session profile you include the auth sufficient pam_rootok.so directive. However, in the case of configuring for Kerberos authentication you do not want this directive, rather you need to specify that authentication is done by Kerberos using an explicit password as illustrated in the above example.
To ensure that the custom PAM session profile is used by RStudio Workbench and that PAM passwords are correctly forwarded to pam_sss you’ll also need to add the following entries to the rserver.conf config file:
/etc/rstudio/rserver.conf
auth-pam-sessions-profile=rstudio-session
auth-pam-sessions-use-password=1Finally, you will need to specify Kerberos settings in sssd.conf (usually located at /etc/sssd/sssd.conf). For more information on SSSD configuration, see the sssd.conf documentation and the sssd-krb5 documentation.
/etc/sssd/sssd.conf
[sssd]
services = nss, pam
# replace this with a comma-separated list of your configured SSSD domains
domains = TEST.EXAMPLE.COM
[domain/TEST.EXAMPLE.COM]
# can also be set to ad or local depending on your authentication setup
id_provider = ldap
auth_provider = krb5
# replace with the name of your Kerberos realm
krb5_realm = TEST.EXAMPLE.COM
# we recommend setting the debug level high to make troubleshooting easier
debug_level = 5
krb5_validate = true
# note that RHEL-7 default to KERNEL ccaches, which are preferred in most cases to FILE
krb5_ccachedir = /var/tmp
krb5_keytab = /etc/krb5.keytabSome additional notes regarding configuration:
The
debugsetting insssd.confis not required however we recommend adding it as it makes troubleshooting much more straightforward.The examples above are not complete examples but rather illustrations of the
pam_sssandsssd.confentries that need to be present. Your local environment may have many additional entries which you should ensure are also included as necessary.
You should be sure to suspend active R sessions and to restart RStudio after making configuration changes to ensure that the new settings are being used. You can do this as follows:
sudo rstudio-server force-suspend-all
sudo rstudio-server restart5.6.2 Testing and Troubleshooting
After making the required configuration changes you should test your updated PAM configuration in isolation from RStudio using the pamtester utility as described in Diagnosing PAM Authentication Problems. The following command will test both authentication as well as issuing of Kerberos tickets:
sudo /usr/lib/rstudio-server/bin/pamtester --verbose \
rstudio-session <user> authenticate setcred open_sessionNote that you should substitute an actual local username for the <user> part of the command line.
The specifics of both PAM configuration and Kerberos configuration can vary substantially by environment. As a result correct configuration likely requires additional entries and options which this guide isn’t able to cover. Please refer to the documentation linked to in More Resources as well as the pam_krb5 for additional details.
5.7 Directory Management
5.7.1 Working Directories
The default working directory for both new R sessions and new R projects is the user’s home directory (~). You can change this behavior via the session-default-working-dir and session-default-new-project-dir configuration parameters within the rsession.conf config file.
For example, the set the default values to “~/working” and “~/projects” you’d use the following configuration:
/etc/rstudio/rsession.conf
session-default-working-dir=~/working
session-default-new-project-dir=~/projectsYou should ensure that users have the permissions required to write to the specified default directories. The specified directories will be automatically created if they don’t already exist.
Note that these settings control only the default working and new project directories (users can still override these settings locally if they choose to).
5.7.2 Restricted Directories
Like most IDEs, RStudio allows users to open and edit any file to which they have read or write permission (respectively) at the filesystem level. However, in some environments it’s important to restrict access to system files from web front ends. RStudio can optionally enforce a restrictive mode for most directories, which will prevent users from using the IDE to open files in the directories. This is enabled by the restrict-directory-view option as follows:
/etc/rstudio/rsession.conf
restrict-directory-view=1When enabled, RStudio users will only have access to open files from the following in the IDE:
- Home directories
- R and R library directories
- RStudio-specific directories
- User/session specific temporary directories
If you wish to allow users to open and view files in a directory that RStudio would ordinarily forbid access to, you can change the directory-view-whitelist setting. This setting accepts a list of directories to enable access to, separated by :. For example, if you wish to allow users to open files from /var/run and /usr/share/examples:
/etc/rstudio/rsession.conf
directory-view-whitelist=/var/run:/usr/share/examplesNote that this setting only applies to RStudio’s IDE web interface. Users will still have access to other files on the system using R itself and/or the Terminal interface. Follow security best practices by relying on operating system-level file permissions, not front end restrictions, to guard access to sensitive content and files.
5.8 Workspace Management
5.8.1 Default Save Action
When a user exits an R session they need to choose whether to save their R workspace (i.e. .RData file). RStudio has global and per-project settings that control what happens when a workspace has unsaved changes. Possible values are:
ask– Ask whether to save the workspace fileyes– Always save the workspace fileno– Never save the workspace file
The default global setting is ask and the default project-level setting is derived from the current global setting (these options can be modified by end users via the Global Options and Project Options dialogs respectively).
The default global setting can also be changed via the session-save-action-default configuration parameter in the rsession.conf config file. For example, to change the default value to no you would use this:
/etc/rstudio/rsession.conf
session-save-action-default=noNote that this setting is specified in the rsession.conf config file and takes effect the next time a user launches an R session (rather than requiring a full restart of the server).
5.8.2 Suspend and Resume
When R sessions have been idle (no processing or user interaction) for a specified period of time (2 hours by default) RStudio suspends them to disk to free up server resources. When the user next interacts with their session it is restored from disk and the user resumes right back where they left off. This is all done seamlessly such that users aren’t typically aware that a suspend and resume has occurred.
5.8.2.1 Session Timeout
To configure the amount of idle time to wait before suspending sessions you can use the session-timeout-minutes setting in the /etc/rstudio/rsession.conf file. For example:
/etc/rstudio/rsession.conf
session-timeout-minutes=360The default value if none is explicitly specified is 120 minutes.
Important: this setting and a few others discussed in this section are specified in the
/etc/rstudio/rsession.conffile (rather than therserver.conffile previously referenced).
There are some conditions where an R session will not be suspended, these include:
- When a top-level R computation is running
- When the R prompt is not in it’s default state (e.g. during a debugging session)
You can also specify that R sessions should never be suspended by setting the session-timeout-minutes to zero. For example:
/etc/rstudio/rsession.conf
session-timeout-minutes=0You can also set session timeouts on a per-user or per-group basis, see the User and Group Profiles section for details.
If you simply want the session process to quit (and lose all unsaved work in the process) instead of suspending to disk, you can turn the session-timeout-suspend option off, like so:
session-timeout-minutes=90
session-timeout-suspend=0The above example will quit idle sessions after 90 minutes, discarding any unsaved data.
5.8.2.2 Forcing Suspends
You can force the suspend of individual sessions or even all sessions on the server. You can do this directly from the main page of the Administrative Dashboard or from the system shell as follows:
$ sudo rstudio-server force-suspend-session <pid>
$ sudo rstudio-server force-suspend-all5.8.2.3 Resume and .Rprofile
By default the Rprofile.site and .Rprofile files are not re-run when a session is resumed (it’s presumed that all of their side-effects are accounted for by simply restoring loaded packages, options, environment variables, etc.).
In some configurations it might be desirable to force the re-execution of profile files. There is an end user option that controls this on the General options pane which defaults to false. However, server administrators may wish to ensure that this option defaults to true. To do this you use the session-rprofile-on-resume-default option. For example:
/etc/rstudio/rsession.conf
session-rprofile-on-resume-default=1Note that this setting is specified in the rsession.conf config file and takes effect the next time a user launches an R session (rather than requiring a full restart of the server).
5.8.2.4 Child Processes
By default, when sessions are quit or suspended, child processes created in the session will continue to run. You can specify whether or not that should occur by specifying the session-quit-child-processes-on-exit setting in /etc/rstudio/rsession.conf. The allowed values are 1 or 0 to quit child processes or leave them running, respectively.
For example, to quit child processes when the session exits:
/etc/rstudio/rsession.conf
session-quit-child-processes-on-exit=1Note that this setting is specified in the rsession.conf config file and takes effect the next time a user launches an R session (rather than requiring a full restart of the server). Also, users can specifically override this setting in their project settings.
5.8.2.5 Session Timeout Kill
To configure the amount of time to wait before forcefully killing and destroying sessions you can use the session-timeout-kill-hours option in the /etc/rstudio/rsession.conf file. This allows you to specify how much time should pass before a session is automatically cleaned up. This is the length of time during which a session exists without user input (regardless of computation status) allowing you to automatically reclaim temporary disk space used by the session, and to stop its processes and children.
This setting should only be used to ensure that any sessions that users have forgotten about are destroyed, reclaiming valuable disk space.
Sessions can be destroyed while important computations are executing. The user whose session is cleaned will also lose all unsaved code and data.
This setting can also be used in conjunction with session-timeout-minutes, allowing already suspended sessions to be cleaned up.
For example:
/etc/rstudio/rsession.conf
session-timeout-kill-hours=48The default value if none is explicitly specified is 0 hours, meaning sessions will never be killed and destroyed automatically. The supplied value should be an integer representing the amount of hours a session can be idle before being killed.
5.8.3 Workspace Storage
Storage of workspaces (.RData files) in RStudio does not use compression by default. This differs from the behavior of base R. Compression is disabled because we’ve observed that for larger workspaces (> 50MB) compression can result in much lower performance for session startup and suspend/resume (on the order of 3 or 4 times slower).
The default workspace save options under RStudio are as follows:
options(save.defaults=list(ascii=FALSE, compress=FALSE))
options(save.image.defaults=list(ascii=FALSE, safe=TRUE, compress=FALSE))If you wish to use different defaults you can define the save.defaults and/or save.image.defaults options in your Rprofile.site or per-user .Rprofile and RStudio will respect the settings you specify rather than using it’s own defaults.
See https://stat.ethz.ch/R-manual/R-devel/library/base/html/save.html for additional details on how R saves objects and the storage and performance implications of using compression.
5.8.4 User State Storage
By default, RStudio stores each user’s state in their home directory, in the following folder:
~/.local/share/rstudioThis folder contains information on all of a user’s active RStudio sessions, including all of the session data when the session is suspended. It also includes various internal RStudio state. Deleting it will result in a factory-fresh RStudio experience for the user, with the exception of their per-user settings (which are described in Customizing Session Settings).
Because this folder can include arbitrary amounts of suspended session data, it can become very large. We recommend ensuring that each user has sufficient disk space quota to store suspended sessions along with the data for their R projects, and using other controls to clean up old data (such as session-timeout-kill-hours)
Note: RStudio 1.3 and earlier stored user state in the folder
~/.rstudio(non-configurable). If you are upgrading to RStudio 1.4 from an earlier release, RStudio will automatically move user state to the new location when the user starts their first IDE session after the upgrade. If there’s a possibility you may downgrade to a prior RStudio release, we recommend configuring RStudio to use the old location temporarily; see below for instructions.
5.8.4.1 Storage Location Customization
If it is necessary to store user state in another folder to relieve disk quota pressure or comply with other requirements, you can customize it using the XDG_DATA_HOME environment variable. XDG_DATA_HOME must be set for the entire RStudio process tree, since RStudio needs to write and read user state both inside and outside R sessions (so attempting to set it in session startup scripts like Rprofile.site or rsession-profile is inadequate and may result in inconsistent behavior).
If your Linux distribution uses the systemd init system, run sudo systemctl edit rstudio-server. In the editor, add the following section to the file (replacing /mnt/storage with your choice of root, of course). Note that the rstudio folder is not included in this path; this is a configuration root directory that will be respected by other applications that use the XDG standard.
[Service]
Environment="XDG_DATA_HOME=/mnt/storage/$USER"If your Linux distribution does not use the systemd init system, consult the documentation for your Linux distribution to learn which init system it uses and the appropriate method for setting environment variables for the rstudio-server service.
In the example above, the state for the user bob would be stored in /mnt/storage/bob/rstudio. The following special variables are expanded in the value:
| Variable | Expands To |
|---|---|
$USER
$HOME
$HOSTNAME |
User’s Unix username User’s home directory Name of current host |
The $HOSTNAME value can be useful to avoid conflicts between hosts running distinct RStudio installations that share a file system, but note that $HOSTNAME should only be used in installations wherein the RStudio services and R session are on the same host. It’s important that all the machines in an installation agree on the path to the user state.
5.8.4.2 Permissions Considerations
You must ensure that the folder that hosts user state data is writable by all RStudio users, since the R session (running as the user) will create the state folder if it does not exist. In the example above, bob would need write access to /mnt/storage to create /mnt/storage/bob/rstudio.
Note that the user’s default umask will be used to set permissions on this folder (i.e. RStudio does not attempt to set them). We recommend ensuring that user umasks are configured such that the folder, when created, will not be readable by other users. If you want the folder to be created with permissions other than those it would receive via umask, you can create it via some other means prior to a user’s first interaction with RStudio; RStudio will not attempt to re-create the folder or change permissions if it already exists.
5.8.4.3 Compatibility, Sharing, and Exact Locations
XDG_DATA_HOME affects many different XDG-compliant applications, and it sets a base (root) directory, to which /rstudio is appended to form the final path. If you wish to set the exact path, or want to avoid side effects in other applications, use the environment variable RSTUDIO_DATA_HOME instead of XDG_DATA_HOME.
For example, RStudio 1.3 and prior stored user state in the folder ~/.rstudio. If you wish to continue using this folder in RStudio 1.4 and later, you could use the following setting (again, in sysctl edit rstudio-server):
[Service]
Environment="RSTUDIO_DATA_HOME=$HOME/.rstudio"Note however that having two different RStudio installations with different versions of RStudio sharing a user state folder is unsupported and can lead to runtime errors or data corruption, as RStudio’s internal state structure changes between versions. If you have multiple RStudio installations with different versions that are run by concurrently by users, we recommend using RSTUDIO_DATA_HOME to create distinct user state folders, ensuring that these installations don’t corrupt each others’ state.
If RSTUDIO_DATA_HOME and XDG_DATA_HOME are both set, RSTUDIO_DATA_HOME takes precedence.
5.8.4.4 Job Launcher Mounts
Finally, if you are using containerized sessions with the Job Launcher, and you mount RStudio’s user state data to a folder outside their home directory, you must ensure that directory is mounted into the containers in addition to the home directory itself. See Launcher Mounts for more information about mounting folders into containerized sessions.
5.9 First Project Template
5.9.1 Overview
RStudio allows you to specify a first project to automatically open for first time users of the system. To do this, set the session-first-project-template-path parameter in rsession.conf to an RStudio project directory. This directory will be copied into the user’s home directory upon first running the IDE, and will automatically open the project contained within. For example:
/etc/rstudio/rsession.conf
session-first-project-template-path=/etc/rstudio/welcome-projectIn the example above, the project located within /etc/rstudio/welcome-project would be copied to users’ home directories when first starting RStudio, and the project file welcome-project.Rproj would be run.
The project file must be named the same as the directory it is contained in. For the above example, the project file must be named welcome-project.Rproj. In addition, you must ensure that the project directory is fully readable and executable by your users, as they will be copying the contents of the directory into their home directory.
If you copy an existing project to be used as a project template, ensure that you delete the RStudio metadata folders and files contained within the project directory. You will want to ensure you delete the following:
.Rproj.user
.Rhistory
.RData
If you are creating the project template for the first time, the project (.Rproj) file must contain the version specifier at a minimum. For example:
welcome-project.Rproj
Version: 1.05.9.2 Project DefaultOpenDocs
Project files allow you to specify default documents that should be opened when a project is opened for the very first time. For example, you could have your welcome project bring up explanatory documents to help guide your users. To do this, add the DefaultOpenDocs line to the .Rproj file. For example:
welcome-project.Rproj
Version: 1.0
DefaultOpenDocs: welcome.txt:firstMarkdown.RmdThe DefaultOpenDocs parameters specifies a list of files to automatically be opened when the project is opened for the first time, separated by a : character. These files are relative paths to the project directory. Only files contained within the project directory can be opened.
5.10 Project Sharing
5.10.1 Overview
Project Sharing is a feature of RStudio Workbench that enables users to work together on RStudio projects. When enabled, a project owner may select any number of other RStudio Workbench users as project collaborators. RStudio Workbench manages the permissions of files in the project to ensure that all collaborators can access them, enables multiple collaborators to edit a file simultaneously, and lets collaborators see who else is working inside a project with them.
5.10.2 Prerequisites
Due to high latencies, use of EFS (Elastic File System) for project sharing directories within AWS is strongly discouraged. If EFS is used, RStudio will experience highly degraded performance. We recommend using a traditional NFSv3 or NFSv4 mount instead.
The following sections outline additional prerequisites that your file system must meet.
5.10.2.1 Access Control Lists
To use Project Sharing, the directories hosting the projects to be shared must be on a volume that supports Access Control Lists (ACLs). RStudio uses ACLs to grant collaborators access to shared projects; ordinary file permissions are not modified.
Instructions for enabling ACLs vary by Linux distribution and filesystem type (see the Guide to enabling ACLs on Ubuntu or RedHat, for example). RStudio supports both NFSv3 (POSIX compatible) and NFSv4 ACLs.
5.10.2.3 Project Sharing and NFS
If you plan to use Project Sharing with NFS-mounted volumes, there are several caveats you should be aware of.
We recommend mounting NFS with the
noacmount option. Without this option, NFS caches file attributes, so it may not be possible for users working simultaneously in a project to know whether they’re seeing each others’ latest changes. Thenoacoption does reduce performance, however, so we recommend testing to choose the right trade off for your environment.Some features which automatically update when directory contents change will not update on NFS. For instance, users may need to manually refresh the Files pane to see new files added by collaborators.
ACL support on NFS is more complicated than ACL support on local file systems. Read ACLs on Linux NFS for a discussion of the issues; guidance for configuring specific NFS versions is provided below.
5.10.2.3.1 Determining NFS Version
Project Sharing works with versions 3 and 4 of the NFS protocol. However, some additional configuration may be necessary depending on the NFS version and underlying filesystem. To determine your NFS client version, run the following command on your RStudio Workbench instance:
$ nfsstat -mYou should see vers=3.0 in the output if you’re using NFSv3, and vers=4.0 if you’re using NFSv4. Extra RStudio configuration is required for NFSv4 clients (see below).
5.10.2.3.2 NFSv3
To use NFSv3 access control lists, you will need to ensure that the filesystem is mounted with the acl attribute, and modify /etc/fstab if necessary to persist the attributes.
Note that many Linux distributions now have ACLs enabled by default in which case no special configuration is required. You can use the tune2fs command to inspect the attributes with which your filesystem is mounted (user_xattr and acl are required for project sharing).
On most systems this is the default, so you need only ensure that noacl is not present. It’s also necessary for the file system on the NFS server to itself be appropriately configured for ACL support; see the section above on Access Control Lists for guidance. Not all file servers that support the NFSv3 protocol also support POSIX compatible ACLs.
To test for POSIX compatible ACLs, you can use the setfacl command as follows:
setfacl -m u:user2:x /home/user1/projectwhere /home/user1/project is the full path to a directory owned by user1, and user2 is another valid user on the system.
Because many Linux systems support POSIX compatible ACLs on the native filesystem, RStudio uses them by default. You can also specify them explicitly as follows:
/etc/rstudio/rsession.conf
nfs-acl-version=nfsv35.10.2.3.3 NFSv4
Version 4 of the NFS protocol uses a very different permissions and ACL model from Version 3. Not all NFSv4 servers support or expose the NFSv4 ACL model, so check with the server administrator to determine whether the capability exists and/or can be enabled.
Testing for support
To test NFSv4 ACL support, you can use the nfs4_setfacl command as follows:
nfs4_setfacl -a A::user2@domain:rax /home/user1/projectwhere /home/user1/project is the full path to a directory owned by user1, user2 is another valid user on the system, and domain is your system’s user domain. Verify that this command succeeds, and that the new ACL entry for user2@domain is visible when you retrieve it:
nfs4_getfacl /home/user1/projectThis presumes that your environment supports using user/domain pairs as security principals. While most environments do, there are two different ways to specify security principals in NFSv4 ACLs: by user name and domain (preferred) or user ID. RStudio can use either, but you’ll need to choose one appropriate for your network environment. If unsure, examine the output of the nfs4_getfacl operation described above. The security principal (the part after e.g., A:: on each line) will be displayed as either a large integer (UID) or in username@domain format.
Using user name and domain security principals
NFSv4 ACLs differ from NFSv3 ACLs in that they can associate a domain with each user named in the access control list. This is typically the same as the domain part of the machine’s host name, but can be any string that the NFSv4 client and server agree on. On Linux systems, the domain can be set in /etc/idmapd.conf.
Tell RStudio the NFSv4 domain you want to use as follows:
/etc/rstudio/rsession.conf
nfs-acl-version=nfsv4
nfs4-principal-type=username
nfs4-domain=mydomain.comUsing user ID security principals
In some environments, it may not be possible to resolve fully qualified user@domain security principals on all of the nodes running RStudio Workbench. This is common on e.g., Kubernetes nodes which are not domain-joined. In this case, it’s possible to use raw User ID (UID) values as security principals in the access control list. You can tell RStudio to write raw UIDs as security principals in NFSv4 access control lists as follows:
nfs-acl-version=nfsv4
nfs4-principal-type=uid5.10.2.4 User Visibility
Projects can only be shared with users with provisioned local system accounts unless LDAP is used for local account provisioning.
The RStudio user database is scanned to list Project Sharing users. This method of user scanning avoids making calls to the system to determine the available users, and prevents making queries to the system password database (such as LDAP). However, it only lists users who have previously logged in to RStudio. To instead show all users on the server, set the following configuration to scan the system password database:
/etc/rstudio/rsession.conf
project-sharing-enumerate-server-users=1When scanning via the system password database, if you’re using sssd with LDAP, you may need to enable user enumeration so that RStudio Workbench can search the directory to create a list of users you can share a project with. To do this, set the following in your sssd.conf file:
[domain/<domainname>]
enumerate = trueAlternatively, the auth-required-user-group setting can be used. This setting allows RStudio Workbench to enumerate only the members of the named groups rather than the entire user directory. Therefore, if you cannot enable user enumeration on your LDAP provider, you can instead create a group containing all RStudio users and supply it as the auth-required-user-group.
You can read more about user enumeration in the sssd FAQ.
5.10.2.6 Proxy Settings
If you are running RStudio Workbench with a proxy, you’ll need to make sure that your proxy is correctly configured to pass websocket connections through in order for all Project Sharing features to work. See the Running with a Proxy section for more on this.
5.10.3 Disabling Project Sharing
Project Sharing is enabled by default however you can disable it using the server-project-sharing option, for example:
/etc/rstudio/rserver.conf
server-project-sharing=05.11 Package Installation
You can customize the location of user packages installed from CRAN as well as the default CRAN repository. You can also configure the user-interface of the RStudio IDE to discourage end-user package installation in the case where packages are deployed centrally to a site library.
Important: The settings discussed in this section are specified in the
/etc/rstudio/rsession.conffile (rather than therserver.conffile previously referenced).
5.11.1 User Library
By default R packages are installed into a user-specific library based on the contents of the R_LIBS_USER environment variable (more details on this mechanism are here: http://stat.ethz.ch/R-manual/R-devel/library/base/html/libPaths.html).
It’s also possible to configure an alternative default for user package installation using the r-libs-user setting. For example:
/etc/rstudio/rsession.conf
r-libs-user=~/R/library/%vR interprets %v to be the major.minor version of R; for example the above would cause R 3.6 to use a package library located at ~/R/library/3.6.
5.11.1.1 Unversioned R Library
R doesn’t guarantee ABI compatibility between minor versions, so when you use packages that include compiled code, you will want to ensure that each version of R has its own library. Otherwise, compiled code may cause crashes or other unexpected behavior when R is upgraded.
However, if you do not use any compiled packages, you can share a library between R versions (e.g. just ~/R/library). This makes it possible to upgrade the major version of R on the server and have user’s packages continue to work.
5.11.1.2 Upgrading R
You can read more about package library considerations when upgrading R in the following article:
5.11.2 Discouraging User Installations
It may be that you’ve configured RStudio Workbench with a site package library that is shared by all users. In this case you might wish to discourage users from installing their own packages by removing the package installation UI from the RStudio IDE. To do this you use the allow-package-installation setting. For example:
/etc/rstudio/rsession.conf
allow-package-installation=0Note that this setting merely discourages package installation by removing user-interface elements. It’s still possible for users to install packages directly using the utils::install.packages function.
5.11.3 CRAN Repositories
RStudio uses the RStudio CRAN mirror (https://cran.rstudio.com) by default. This mirror is globally distributed using Amazon S3 storage so should provide good performance for all locales. You may however wish to override the default CRAN mirror. This can be done with the r-cran-repos settings. For example:
/etc/rstudio/rsession.conf
r-cran-repos=http://cran.at.r-project.org/Whatever the default CRAN mirror is, individual users are still able to set their own default. To discourage this, you can set the allow-r-cran-repos-edit settings. For example:
/etc/rstudio/rsession.conf
allow-r-cran-repos-edit=0Note that even with user editing turned off it’s still possible for users to install packages from alternative repositories by directly specifying the repos parameter in a call to install.packages.
To specify a list of CRAN repos, define a /etc/rstudio/repos.conf file containing the primary CRAN repo and named secondary repos. For example:
/etc/rstudio/repos.conf
CRAN=https://cran.rstudio.com
Australia=https://cran.ms.unimelb.edu.au/
Austria=https://lib.ugent.be/CRAN/To change the location of repos.conf, use the r-cran-repos-file setting. For example, by adding to rsession.conf:
r-cran-repos-file=/etc/rstudio/mirrors.confOptional CRAN repos can be made available for users in RStudio with the r-cran-repos-url setting, this setting expects a URL to retrieve a configuration file containing named secondary repos. These secondary repos won’t be set by default, but rather, RStudio will list them to users to be manually added to their repo selection. For example:
http://custom-domain/repos.conf
Australia=https://cran.ms.unimelb.edu.au/
Austria=https://lib.ugent.be/CRAN/Notice that the allow-r-cran-repos-edit option can also be used to disallow secondary repos and that repos.conf overrides the r-cran-repos setting, if specified.
5.12 Feature Limits
RStudio Workbench has a number of other limits that can be configured. This section describes these limits. Note that these settings are specified in the /etc/rstudio/rsession.conf file (rather than the rserver.conf file previously referenced).
5.12.1 Disabling Access to Features
Besides the limits on package installation and CRAN repository editing described in the previous section there are a number of other limits that can be specified. The following describes all of the options that can be used to limit features.
/etc/rstudio/rsession.conf
allow-vcsAllow access to Git and SVN version control features.
allow-vcs-executable-editAllow editing of the underlying Git or SVN executable.
allow-package-installationAllow installation of packages using the Packages Pane (note that even if this is set to 0 it’s still possible to install packages using
utils::install.packagesfrom the command line).allow-r-cran-repos-editAllow editing of the CRAN repository used for package downloads (note that it’s still possible to specify an alternate repository using the
reposparameter ofutils::install.packages).allow-shellEnable integrated terminal feature (note that it’s still possible to execute shell commands using the
systemfunction).allow-terminal-websocketsAllow integrated terminal feature to use WebSockets for better responsiveness.
allow-file-downloadsAllow downloading files using the Export command in the Files Pane.
allow-file-uploadsAllow uploading files using the Upload command in the Files pane.
allow-external-publishAllow content to be published to external (cloud) services. This includes publishing HTML documents created with R Markdown or R Presentations to RPubs (http://rpubs.com), and publishing Shiny applications and documents to ShinyApps.io (http://shinyapps.io). Note that this just removes the relevant user interface elements in the IDE, and that it may still be possible for users to publish content using the R console.
allow-publishAllow content to be published. If specified, this option removes all user interface elements related to publishing content from the IDE, and overrides
allow-external-publish.allow-launcher-jobsAllow running standalone adhoc Job Launcher jobs from the Jobs pane.
All of these features are enabled by default. Specify 0 to disable access to the feature.
Note that these options should be specified in the /etc/rstudio/rsession.conf configuration file (rather than the main rserver.conf configuration file).
5.12.2 Maximum File Upload Size
You can limit the maximum size of a file upload by using the limit-file-upload-size-mb setting. For example, the following limits file uploads to 100MB:
/etc/rstudio/rsession.conf
limit-file-upload-size-mb=100The default behavior is no limit on the size of file uploads.
5.12.3 CPU Time per Computation
If you want to prevent runaway computations that consume 100% of the CPU you can set the maximum number of minutes to allow top-level R computations to run for using the limit-cpu-time-minutes setting. For example:
/etc/rstudio/rsession.conf
limit-cpu-time-minutes=30This specifies that no top level computation entered at the R console should run for more than 30 minutes. This constraint is implemented by calling the R setTimeLimit function immediately prior to handing off console commands to R. As a result it is possible for a particular script to override this behavior if it knows that it may exceed the threshold. This would be done as follows:
setTimeLimit(cpu = Inf)
# Long running R code here...5.12.4 XFS Disk Quotas
If your system uses the XFS file system (http://en.wikipedia.org/wiki/XFS) then RStudio Workbench can be configured to notify users when they come close to or exceed their disk quota. You can enable this using the limit-xfs-disk-quota setting. For example:
/etc/rstudio/rsession.conf
limit-xfs-disk-quota=1The user’s XFS disk quota will be checked when the RStudio IDE loads and a warning message will be displayed if they are near to or over their quota.
5.13 Notifications
Administrators can broadcast notifications to user sessions in real-time using the notifications.conf file located at /etc/rstudio/notifications.conf. This file comes by default with commented out entries that you can uncomment and use, and helps show you the available time and message formats.
Each session monitors for changes in the notifications.conf file, and if a new notification is detected, it will be shown to the user at the appropriate time (as defined in the next section). All open sessions for a user will receive the notification, and they will continue to see the notification in any new sessions they open until the notification is acknowledged.
Modifying a notification will cause it to count as a new notification, so make sure to only save changes to the file when you’ve confirmed what you want the message to be and what time it should be displayed. Otherwise, the same message could be shown multiple times.
5.13.1 notifications.conf format
The notifications.conf file is a file consisting of multiple notification entries separated by a blank line. The following table lists the fields that are available for each notification entry in the file.
| StartTime | The start time at which the notification can start to be delivered. This must be a time-formatted field. This field is not required. |
| EndTime | The end time at which the notification will no longer be delivered. This must be a time-formatted field. This field is required. |
| Message | The message content to show to the users. The message cannot have empty lines in it. This field is required. |
An example notifications.conf file is shown below. For more information on the formatting of each field, see the subsequent sections.
/etc/rstudio/notifications.conf
StartTime: 2017-08-30 09:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Please remember to shut down your computers at the end of the day.
StartTime: 2017-05-30 05:55
EndTime: 2017-06-13
Message: This is a test notification. Notifications can span
multiple lines by indenting the next line's message text.
Empty lines are not supported!It is important that each entry consists of 2-3 fields as specified above (StartTime, EndTime, and Message). Each field must go on its own line. There should be no empty lines between field definitions.
For example, this is okay:
/etc/rstudio/notifications.conf
StartTime: 2017-08-30 12:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Please remember to shut down your computers at the end of the day.But this is not:
/etc/rstudio/notifications.conf
StartTime: 2017-08-30 12:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Please remember to shut down your computers at the end of the day.There must be one empty line (2 new line characters) in between separate notification entries.
For example, this is okay:
/etc/rstudio/notifications.conf
StartTime: 2017-08-30 08:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Please remember to shut down your computers at the end of the day.
StartTime: 2017-08-30 08:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Remember to drop off any borrowed equipment at Grace's office today only.But this is not:
StartTime: 2017-08-30 12:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Please remember to shut down your computers at the end of the day.
StartTime: 2017-08-30 12:00:00 -5:00
EndTime: 2017-08-30 20:00:00 -05:00
Message: Remember to drop off any borrowed equipment at Grace's office today only.5.13.1.1 Time format
The time format fields, StartTime and EndTime, must be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DD hh:mm
YYYY-MM-DD hh:mm:ss zh:zm
The following table shows the meaning of the format sections.
| YYYY | 4 digit year (example: 2017) |
| MM | 2 digit month (example: 06) |
| DD | 2 digit day (example: 28) |
| hh | 2 digit hours (24 hour clock. example: 19) |
| mm | 2 digit minutes (example: 15) |
| ss | 2 digit seconds (example: 59) |
| zh | Time zone hours offset (example: -06 for CST or -08 for PST) |
| zm | Time zone minutes offset (usually just 00, different for only a few timezones) |
If no time is specified, the time will be set to 00:00:00 in the current server time zone for start times and 23:59:59 in the current server time zone for end times.
If no seconds are specified, they will be set to 00 and the time is interpreted in the current server time zone.
Note that if you have sessions spanning multiple servers in different time zones and you want your notifications to display at a uniform time, you MUST manually set the timezone to what is appropriate. Otherwise, sessions in different time zones will see notifications in their local time.
The following table shows some example dates and how they would be formatted.
| January 1st, 2020 at 6:00 PM in the server’s time zone | 2020-01-01 18:00 |
| July 31st, 2018 at midnight in the server’s time zone (for a start time) | 2018-07-31 |
| September 23rd, 2019 at 23:59:59 in the server’s time zone (for an end time) | 2019-09-23 |
| November 30th, 2020 at 9:14:12 in Pacific Standard Time | 2020-11-30 09:14:12 -08:00 |
5.13.1.2 Message format
The message to deliver must be plain text and cannot have any empty lines. To start text on another line, simply indent the line as in the multiline example in the previous section.
5.14 RStudio Connect Server
Users of RStudio can publish content to RStudio Connect. To do so, they must first specify the RStudio Connect server they wish to use. You can set the default RStudio Connect server URL to use when users are connecting to an account. To do so, use the default-rsconnect-server option:
/etc/rstudio/rsession.conf
default-rsconnect-server=http://connectserver/5.15 Terminal WebSockets
The RStudio terminal pane uses WebSockets to communicate between the web browser and the session. If the attempt to connect with WebSockets fails, the terminal switches to a less responsive but generally more forgiving HTTP-based protocol.
Slow typing response in the terminal is a symptom of this slower protocol. You can check by starting a terminal, then going to Tools / Terminal / Terminal Diagnostics. Scroll down to Connection Information and look for “WebSocket connect error, switching to RPC”. This indicates that the terminal was unable to use WebSockets and has fallen back on the slower protocol.
Several settings are available for tuning the terminal’s use of WebSockets.
5.15.1 IDE Settings
In the IDE under Tools / Global Options / Terminal, there is a checkbox “Connect with WebSockets”. Unchecking this will cause terminals to always connect with the HTTP-based protocol.
5.15.2 Feature Limit
As mentioned earlier, the feature limit allow-terminal-websockets completely disables the use of WebSockets.
5.15.3 Advanced Settings
The following settings may be modified by adding them to the /etc/rstudio/rsession.conf file.
| Setting | Default | Purpose |
|---|---|---|
| websocket-ping-seconds | 10 | How often a keep-alive is sent over the WebSocket, in seconds. Set to 0 to disable keep-alives. Many proxies will close inactive WebSockets so keeping enabled is recommended. |
| websocket-connect-timeout | 3 | How long terminal waits (in seconds) for WebSocket to connect before switching to the HTTP protocol. If set to 0 then the timeout of the web browser’s WebSocket implementation will be used; this is often quite lengthy (minutes). |
| websocket-log-level | 0 | Controls logging of WebSocket diagnostics. These are for troubleshooting only, and will appear in the RStudio R Console pane while enabled.
|
| websocket-handshake-timeout | 5000 | How long the server waits (in milliseconds) for WebSocket handshake to complete when connecting and disconnecting. Set to 0 to disable. |
For example, this would double the number of keep-alive packets sent, wait longer before switching to HTTP, log information on WebSocket errors, and increase the handshake timeout to 15 seconds.
websocket-ping-seconds=5
websocket-connect-timeout=10
websocket-log-level=1
websocket-handshake-timeout=15000For more background on the terminal feature, see this support article.
5.16 Customizing Session Settings
All of the session settings file locations described in this section conform to the XDG Base Directory Specification. They are configurable using environment variables:
| Scope | Default | Environment |
|---|---|---|
| User | ~/.config/rstudio |
XDG_CONFIG_HOME |
| System | /etc/rstudio |
XDG_CONFIG_DIRS |
In accordance with the Base Directory Specification, the environment variables specify the location of the rstudio folder. For example, to store system-wide preference configuration in /var/config/rstudio/rstudio-prefs.json, you would set the XDG_CONFIG_DIRS variable to the value /var/config.
If specified, the RStudio variables take precedence over the XDG variables. These variables specify a specific directory (not a base directory). For example, to store system-wide preferences in /var/config/settings/rstudio-prefs.json, you would set the RSTUDIO_CONFIG_DIR variable to the value /var/config/settings.
The examples in this section presume you’re setting system-wide settings in /etc/rstudio; in each case it’s also possible to use a different folder by changing environment variables as described above, or to apply the settings to individual user accounts by changing files in ~/.config/rstudio.
5.16.1 User Preferences
User preferences set in the RStudio IDE’s Global Options dialog can also be set in the JSON file rstudio-prefs.json, located in the settings directory described above.
5.16.1.1 Schema
The schema for the JSON file can be found at:
/usr/lib/rstudio-server/resources/schema/user-prefs-schema.jsonIt documents all of the preferences, shows data types and allowable values, and briefly explains the usage of each. You can see a summary of this information in the Session User Settings appendix.
5.16.1.2 Example
By default, RStudio Workbench only shows the home page (session overview) to users who have multiple sessions running. If you’d like it to be shown to all users regardless of the number of running sessions, set it in the global user preferences file as follows:
/etc/rstudio/rstudio-prefs.json
{
"show_user_home_page": "always"
}5.16.2 Snippets
You can install global snippets files for all users in the /etc/rstudio/snippets folder. For example, if you’d like to create a snippet lib for an R library call:
/etc/rstudio/snippets/r.snippets
snippet lib
library(${1:package})You can also define snippets for CSS files in the file css.snippets, and so on. You can find documentation on the snippet file format in the Cloud 9 IDE snippet documentation.
Note that RStudio will not merge snippet files, which implies the following:
- If you define your own snippets (for a given file type), they will replace those that ship with RStudio (for that same file type).
- If users define their own snippets (for a given file type), changes to the system snippet file (for that same file type) won’t have any effect on those users.
5.16.3 Default Document Templates
RStudio typically opens new documents with completely blank contents. You can, however, define the contents of the blank document by creating a file named default.X in /etc/rstudio/templates, where X is the file extension you wish to customize. For example, to start all R scripts with a standard comment header users can fill out, you could use the following:
/etc/rstudio/templates/default.R
# -------------------------------------
# Script:
# Author:
# Purpose:
# Notes:
#
# Copyright(c) Corporation Name
# -------------------------------------There are also some special template files which ship with RStudio; these, too, are customizable. In /etc/rstudio/templates, you can customize the following:
| File | Description |
|---|---|
document.Rmd |
The default R Markdown document file content (without YAML header) |
notebook.Rmd |
The default R Notebook file content (without YAML header) |
presentation.Rmd |
The default R Markdown presentation file content (without YAML header) |
shiny.Rmd |
The default Shiny R Markdown file content (without YAML header) |
query.sql |
The default SQL query |
5.16.4 Color Themes
You can define additional custom themes for RStudio by placing .rstheme files in the following directory:
/etc/rstudio/themesThe .rstheme file contains plain-text CSS with some special metadata. You can create one by importing an existing TextMate theme file, or by starting from scratch (using an existing theme file as a template). Run the R command ?rstudioapi::addTheme for more help.
5.16.5 Fonts
RStudio’s code editor and R console use a fixed-width font. By default, only fonts that end users have installed locally can be selected. If you wish to make additional fixed-width fonts available to your users, you can place them here:
/etc/rstudio/fontsFonts placed here will be automatically made available for selection in RStudio’s Appearances settings (Tools -> Global Options -> Appearance) for all users. It’s helpful to place the fonts preferred by your users here because it allows the font to be used in RStudio regardless of what fonts they have installed locally.
The following font formats are supported:
- Web Open Font Format (.woff, .woff2)
- OpenType (.otf)
- Embedded OpenType (.eot)
- TrueType (.ttf)
Only fixed-width fonts are supported by the RStudio IDE. Proportional fonts will still be installed, but if users select a proportional font, they will experience cursor positioning problems.
5.16.5.1 Naming and Directory Structure
The name of the file is presumed to be the name of the font. If you wish to give the font a custom name, you can place it in a directory with your name of choice. For example:
+ fonts/
|
+-- Coding-Font.ttf
|
+-- Coding Font Two/
|
+-- CodingFont2-Regular.woffThis directory structure would make two fonts available, Coding-Font and Coding Font Two.
Some fonts come in many different weights and styles. If you want these weights and styles to be treated as single font, you can place them underneath a single folder. This is useful when a theme uses bold or italic variants of a font to decorate code (e.g., to set comments in italics).
To do this, create subfolders with the font’s weight or style as the folder’s name. For example, this creates a single font, “Coding Font 3”, which has two weights (400 and 700 for regular and bold, respectively) and an italic style for each weight.
+ fonts/
|
+-- Coding Font Three/
|
+-- 400/
| |
| +-- CodingFont3-Regular.woff
| |
| +-- italic/
| |
| +-- CodingFont3-Italic.woff
|
+-- 700/
|
+-- CodingFont3-Bold.woff
|
+-- italic/
|
+-- CodingFont3-BoldItalic.woff5.16.5.2 Autodetection
In addition to displaying a list of fonts installed on the server, RStudio attempts to automatically detect available fixed-width fonts that are installed on a user’s browser. For security reasons, it is not possible for RStudio to enumerate all the fonts on the user’s machine, so a known list of popular programming fixed-width fonts are checked for compatibility. This list is stored in the option browser_fixed_width_fonts.
If your users have a font they prefer but it can’t be installed on the server, you can cause RStudio to start scanning for it locally by including it in the set of browser_fixed_width_fonts in the global RStudio preferences file, /etc/rstudio/rstudio-prefs.json. See User Preferences for more information on setting global options.
5.16.6 Keybindings
RStudio keybindings can be globally defined using the following two files:
/etc/rstudio/keybindings/editor_commands.json
/etc/rstudio/keybindings/rstudio_commands.jsonIt isn’t necessary to hand-author these files; RStudio can generate them for you:
- Remove the
~/.config/rstudio/keybindings/folder - Start a new R session and customize the keyboard shortcuts as desired
- Copy the new
.jsonfiles from~/.config/rstudio/keybindingsto/etc/rstudio/keybindingsto make them active for all users on the server
5.16.7 Spelling
You can define additional spelling dictionaries for RStudio by placing dictionary files in the following folders:
5.16.7.1 Languages
Define additional system languages by placing Hunspell .aff files in:
/etc/rstudio/dictionaries/languages-system5.16.7.2 Dictionaries
Define additional custom dictionaries by placing Hunspell.dic files in:
/etc/rstudio/dictionaries/custom