R Executable and Libraries

Locating R

RStudio Pro uses the version of R pointed to by the output of the following command:

$ which R

The which command performs a search for the R executable using the system PATH. RStudio Pro 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/bin/R. For versions of R installed from source this will typically (but not always) be /usr/local/bin/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/R

Note that this change will not take effect until the server is restarted.

Using multiple versions of R

Workbench

The section above describes how RStudio Pro 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.

Locating shared libraries

You can add elements to the default LD_LIBRARY_PATH for RStudio Pro Sessions (as determined by the R ldpaths script) by adding an rsession-ld-library-path entry to the server config file. This might be useful for ensuring that packages can locate external library dependencies that aren’t installed in the system standard library paths. For example:

/etc/rstudio/rserver.conf

rsession-ld-library-path=/opt/someapp/lib:/opt/anotherapp/lib

Note that this change will not take effect until the server is restarted.

Customizing session launches

Workbench

Profile script execution

RStudio Pro launches RStudio Pro Sessions under a bash login shell. This means that prior to the execution of the RStudio Pro Session the bash shell will read and execute commands from this file if it exists:

/etc/profile

After 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
~/.profile

If you have further RStudio-Pro-specific initialization logic (exporting environment variables, etc.) you can optionally create an RStudio Pro Session specific profile script at:

/etc/rstudio/rsession-profile

If it exists this script will be executed prior to the bash shell that launches the RStudio Pro Session. This script must be executable by all Post Workbench users, so it is recommended that you set its file permissions to 755 via the following command:

chmod 755 /etc/rstudio/rsession-profile

In 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=1

Environment variables

RStudio Pro 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 Posit Workbench 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.

Program supervisors

You may also wish to run RStudio Pro 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 10

This example uses the nice command to run all RStudio Pro 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.

Diagnosing session problems

Posit Workbench allows you to launch sessions in a diagnostics mode to capture extended session trace information in the event that you run into problems. 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.

We recommend that you send these files to Posit support to aid in troubleshooting any session launch issues should they arise.

Either enable diagnostics for an individual user session, or system-wide for all sessions.

Enabling session diagnostics for individual sessions

To enable diagnostics for an individual user’s sessions, create a text file in the user’s home directory: ~/.config/rstudio/rsession-diagnostics that contains the type of diagnostics desired: debug (for debug logging only), or strace for debug logging and a system call strace. For example, run these commands to enable strace logging for the current user:

mkdir -p ~/.config/rstudio
echo "strace" > ~/.config/rstudio/rsession-diagnostics

When the next RStudio Pro session is started, logs are created in the user’s rstudio log directory, by default: ~/.local/share/rstudio/log. The file: rsession-diagnostics.log contains startup info including environment variables. The file rsession-username.log has debug log messages.

When using strace mode, an additional file is created called rsession-diagnostics.log.strace that contains the output of the linux strace command for the session.

To disable diagnostic collection, either remove the file ~/.config/rstudio/rsession-diagnostics or change its contents to the word off.

Session Protocol Debug

Debug logging may also be enabled for an RStudio Pro session by enabling the Session Protocol Debug option in the Tools -> Show Command Palette option menu in RStudio. Enabling this option adds detail to the standard debug logs including trace messages for operations relayed between browser and rsession. Enabling this option will automatically enable debug logging, but after the session has started. Use rsession-diagnostics to capture the complete debug log for the session, including startup messages.

Enabling session diagnostics system wide

To enable collection of diagnostic data for all RStudio Pro sessions, set the rsession-diagnostics-enabled flag in /etc/rstudio/rserver.conf like below:

/etc/rstudio/rserver.conf

rsession-diagnostics-enabled=1

When 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/diagnostics

Be aware that this directory should be accessible by all users of the system. If it does not exist, Posit Workbench will attempt to create it and set its permissions to Read/Write/Execute for everyone (file permissions of 777).

Remember to turn the option off when you are done to prevent diagnostic information from accumulating in this directory.

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.

When running Slurm sessions with Singularity, it should be noted that the rsession-diagnostics-dir must still have accessible permissions so that the Slurm sessions can write to it.

For other types of remote sessions, such as running non-containerized sessions, configuring launcher-mounts is not necessary. For load-balanced configurations, we recommend that each load-balanced node running Workbench should be configured independently with rsession-diagnostics-dir when needed.

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. These files will grow very large in a short amount of time so remember to turn off this option and do not use it to capture extended session runs.

/etc/rstudio/rserver.conf

rsession-diagnostics-enabled=1
rsession-diagnostics-strace-enabled=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, Posit Workbench 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.

Skipping workspace restoration

To skip workspace restoration (i.e., reloading the contents of the global environment), append ?restore_workspace=0 to the RStudio Pro Session’s full URL. For example:

https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?restore_workspace=0

Note 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.

Omitting .Rprofile

To skip executing .Rprofile, append run_rprofile=0 to the RStudio Pro Session’s full URL. For example:

https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?run_rprofile=0

Just like restore_workspace, this can only be used prior to the session starting.

Note that Safe Mode is only available when Posit Workbench itself is starting sessions, so it is not a useful troubleshooting technique when sessions are being run using the Job Launcher.

RedHat Toolsets

When using RedHat based OSes, a common issue is the GCC version available is not as modern as required for R package compilation.

To install more up to date development libraries, you can install and enable GCC toolsets, prepared by RedHat as an Application Stream.

With RedHat 7 there was a single package to install called devtoolset-N, where N was the version number. Since RedHat 8, this has changed to a default package called GCC Toolset, and they provide a list of other, non-default, packages.

To make these tools available to all users of Workbench, please follow this process:

Install GCC Toolset version 13 - the most recent version available:

yum install gcc-toolset-13

Install individual packages from GCC Toolset:
1. List the available packages
```
yum list available gcc-toolset-13-\*
```
1. Install the required packages.
```
yum install package_name
```
Make the GCC Toolset available to all R Sessions by editing /etc/rstudio/rsession-profile:

/etc/rstudio/rsession-profile

source /opt/rh/gcc-toolset-13/enable

Allow access to the file

chmod 755 /etc/rstudio/rsession-profile

Test in a new shell:

# which gcc
/usr/bin/gcc
# gcc --version
gcc (GCC) 8.5.0 20210514 (Red Hat 8.5.0-22)
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
Warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# source /opt/rh/gcc-toolset-13/enable
# which gcc
/opt/rh/gcc-toolset-13/root/usr/bin/gcc
# gcc --version
gcc (GCC) 13.2.1 20231205 (Red Hat 13.2.1-6)
Copyright (C) 2023 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

References: