2 Server Management
2.1 Core Administrative Tasks
2.1.1 Configuration Files
RStudio uses several configuration files all located within the
/etc/rstudio directory. Configuration files and folders include:
|rserver.conf||Core server settings|
|rsession.conf||Settings related to individual R sessions|
|notifications.conf||Notifications to be delivered to user sessions Pro|
|logging.conf||Configuration of the logging system including logger type, location, and level|
|crash-handler.conf||Configuration of the crash handling system (see Automated Crash Reporting)|
|database.conf||Configuration of the database that RStudio will store data in (see Database)|
|ngnix.http.conf||Extra HTTP configuration for nginx Pro|
|ngnix.server.conf||Extra server configuration for nginx Pro|
|ngnix.site||Extra site configuration for nginx Pro|
|profiles||User and group resource limits Pro|
|r-versions||Manual specification of additional versions of R Pro|
|ip-rules||IP access rules (allow or deny groups of IP addresses) Pro|
|load-balancer||Load balancing configuration Pro|
|health-check||Template for content to return for server health checks Pro|
|google-accounts||Mappings from Google accounts to local accounts Pro|
|file-locks||Configuration for file locking|
|env-vars||Additional environment variables to set during server startup|
|login.html||Custom HTML for login page|
|themes/||Custom editor color schemes|
|fonts/||Fonts for RStudio’s R console and code editor|
|keybindings/||Custom IDE keybindings|
|snippets/||Editor snippet files|
|templates/||Default templates for new files created in the IDE|
|dictionaries/||Custom spelling languages and dictionaries|
rsession.conf files are created by default during installation however the other config files are optional so need to be created explicitly. It should be noted that the
rsession.conf file must be readable by each RStudio user, so it should be given appropriate permissions (e.g. 644).
r-versions files are created, but their entries are commented out as an example.
Whenever making changes to configuration files you need to restart the server for them to take effect. You can do this using the
restart command of the server management utility:
$ sudo rstudio-server restart
2.1.2 Alternate Configuration File Location
RStudio can be instructed to use a directory other than
/etc/rstudio for hosting configuration files using the XDG standard environment variable
XDG_CONFIG_DIRS. This can be useful when running RStudio in a container and mounting configuration at runtime. It can also be helpful for setting up alternate configurations for testing or troubleshooting purposes without running the risk of corrupting a known-good production configuration.
For the example below, presume that you’d like RStudio’s configuration to live in
220.127.116.11 Create the Directory
First, create the directory that needs to host configuration (this can of course be skipped when mounting). Make sure that the rstudio-server service account can read content in this directory.
$ mkdir -p /mnt/config/rstudio $ chmod 755 /mnt/config/rstudio
18.104.22.168 Copy Configuration
Presuming that you’d like to start with your existing configuration, copy all of the configuration files and folders from your existing configuration set to your new configuration. You can do this as follows:
$ cp -r /etc/rstudio/* /mnt/config/rstudio/
22.214.171.124 Configure Service
Because RStudio runs as a system service, you must use your system’s service manager to change its environment. 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/config with your choice of root). 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.
If you wish to set RStudio’s configuration folder directly, use the
RSTUDIO_CONFIG_DIR environment variable instead. For example, to use
/mnt/config/rstudio as the configuration folder:
RSTUDIO_CONFIG_DIR is also useful if you do not wish other XDG-compliant applications to be affected by the environment variable. If set, it takes precedence over
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
126.96.36.199 Change and Restart
Finally, make any configuration changes you’d like in your new configuration folder, and then restart the server to use the new configuration files.
$ sudo rstudio-server restart
To return to the configuration in
/etc/rstudio, just remove the
Environment directive added above and restart the service.
2.1.3 Configuring the Run-Time Data Directory
RStudio needs to write several temporary files while running to function properly. The directory at which these files is written can be set by the
server-data-dir configuration option by modifying
/etc/rstudio/rserver.conf like so:
The data directory defaults to
/var/run/rstudio-server but you can change it to any directory. The specified location must be readable by any users of RStudio.
2.1.4 Setting Environment Variables
You can set environment variables for RStudio’s server process using the
env-vars configuration file. This is an alternative to setting the environment variables using your system’s service manager. For example, to set the
XDG_DATA_HOME environment variables for the server process:
# Set proxy for outbound HTTP requests HTTP_PROXY=http://192.168.1.1 # Store user data on mounted external storage XDG_DATA_HOME=/mnt/storage/$USER
env-vars file is reloaded, and the environment variables set again, when the server process receives a
SIGHUP signal. See Reloading Configuration for an example.
Note: This technique cannot be used to set the specific environment variables
RSTUDIO_CONFIG_DIR, because those variables control where configuration files are loaded from, and
env-varsis itself a configuration file. Use your system’s service manage to set those variables as described in Alternate Configuration File Location.
Note: With the exception of XDG variables, environment variables set for the server process are not generally forwarded to individual R sessions. To set environment variables such as
HTTP_PROXYfor all R sessions on the server, use Renviron.site or set them in one of the scripts executed when R sessions are initialized (see Profile Script Execution).
2.1.5 Stopping and Starting
During installation RStudio is automatically registered as a daemon which starts along with the rest of the system. The exact nature of this will depend on the init system in use on your system:
- On systems using systemd (such as Debian 7, Ubuntu 15, and RedHat/CentOS 7), this registration is performed as a systemd script at
- On systems using Upstart (such as older versions of Debian and Ubuntu, and RedHat/CentOS 6), this registration is performed using an Upstart script at
- On systems using init.d, including RedHat/CentOS 5, an init.d script is installed at
To manually stop, start, and restart the server you use the following commands:
$ sudo rstudio-server stop $ sudo rstudio-server start $ sudo rstudio-server restart
To check the current stopped/started status of the server:
$ sudo rstudio-server status
2.1.6 Reloading Configuration Values
To reload the server’s configuration without restarting it, use the
$ sudo rstudio-server reload
Alternately, you can send a
SIGHUP to the
rserver process, using a command like
kill -s SIGHUP $PID, where
$PID is the process ID of the
Note that most configuration values cannot be applied without a full restart. The following are the values and settings that will be reloaded when you send
SIGHUP or execute the
- Logging configuration (
logging.conf), as described in Logging.
- Environment variables (
env-vars), as described in Setting Environment Variables.
- Load balancing settings (
load-balancer), as described in Load Balancing.
- nginx configuration (
nginx.*.conf), as described in Customizing Default Proxy.
- Custom R version settings (
r-versions), as described in Extended R Version Definitions.
- Product license data, as described in License Management.
2.1.7 Managing Active Sessions
There are a number of administrative commands which allow you to see what sessions are active and request suspension of running sessions.
To list all currently active sessions:
$ sudo rstudio-server active-sessions
188.8.131.52 Suspending Sessions
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.
To manually suspend an individual session:
$ sudo rstudio-server suspend-session <pid>
To manually suspend all running sessions:
$ sudo rstudio-server suspend-all
The suspend commands also have a “force” variation which will send an interrupt to the session to request the termination of any running R command:
$ sudo rstudio-server force-suspend-session <pid> $ sudo rstudio-server force-suspend-all
force-suspend-all command should be issued immediately prior to any reboot so as to preserve the data and state of active R sessions across the restart.
184.108.40.206 Killing Sessions
If you are for any reason unable to cooperatively suspend an R session using the commands described above you may need to force kill the session. Force killing a session results in SIGKILL being sent to the process, causing an immediate termination.
To force kill an individual session:
$ sudo rstudio-server kill-session <pid>
To force kill all running sessions:
$ sudo rstudio-server kill-all
Note that these commands should be exclusively reserved for situations where suspending doesn’t work as force killing a session can cause user data loss (e.g. unsaved source files or R workspace content).
2.1.8 Listing users
You can list all of the users that have signed in to RStudio Workbench by running the following command:
sudo rstudio-server list-users
2.1.9 Adding users to the user database
Normally, when users sign in to RStudio Workbench for the first time, they are automatically added to the RStudio user database. However, you can manually add them via script if you need to. This is useful for designating specific users as administrators to allow them access to the administration panel without requiring them to belong to the administration group. This can be done by running the following command:
$ sudo rstudio-server add-user <username> <0 or 1>
Specifying a 0 in the above command will add the user without admin privilege; specify a 1 to grant admin privilege.
Note: Users set as administrators in this way will be
Admin Superusers. See Administrator Superusers.
2.1.10 Changing the admin status of a user
You can also change the admin status of a particular existing user:
$ sudo rstudio-server set-admin <username> <0 or 1>
2.1.11 Locking and unlocking users
If you are using RStudio Workbench under a named user license, you can lock and unlock specific users to disallow or reallow access to the server. Locking a user will prevent them from signing in to RStudio, but will preserve their files. Locked users do not count against the named user limit on your license.
This feature may be used when a user leaves the organization or otherwise no longer needs access to RStudio Workbench on a permanent basis.
To lock a user, click on the user on the Users admin page, and then click the Lock button in the upper right-hand corner of the screen.
You can also lock users via the server management utility:
$ sudo rstudio-server lock-user <username> $ sudo rstudio-server unlock-user <username>
Note that RStudio’s Software License Descriptions only allow this feature to be used to permanently terminate a named user’s access.
2.1.12 Taking the Server Offline
If you need to perform system maintenance and want users to receive a friendly message indicating the server is offline you can issue the following command:
$ sudo rstudio-server offline
When the server is once again available you should issue this command:
$ sudo rstudio-server online
When the server is taken offline all R sessions will be suspended and no new sessions can be started. Session data will be saved but any running computations will be terminated.
2.1.13 Upgrading to a New Version
If you perform an upgrade of RStudio and an existing version of the service is currently running, then the upgrade process will also ensure that active sessions are immediately migrated to the new version. This includes the following behavior:
- Running R sessions are suspended so that future interactions with the server automatically launch the updated R session binary
- Currently connected browser clients are notified that a new version is available and automatically refresh themselves.
- The core server binary is restarted
When load balancing is configured upgrading multiple nodes may cause brief glitches if you upgrade each server one at a time. This is due to the possibility of two servers with different versions trying to coordinate. If some downtime is acceptable, we recommend taking all nodes offline before upgrading.
To upgrade to a new version of RStudio you simply install the new version. For example on Debian/Ubuntu:
$ sudo gdebi <rstudio-package.deb>
$ sudo yum install <rstudio-package.rpm>
For openSUSE / SLES:
$ sudo zypper install <rstudio-package.rpm>
RStudio provides the ability to change various facets of its logging functionality, such as changing the logger type (syslog vs file) on a per-binary or per-section basis. In most configurations, it is recommended that you do not change the logging configuration, but in some circumstances it is desirable to turn on debug logging to help troubleshoot issues.
2.2.1 Configuration File
The logging configuration file is located at
/etc/rstudio/logging.conf. It allows you to specify logging options in a hierarchy of three different types:
- Global (
- Per-binary (
- Per log section (
[log section name])
[*] log-level=info logger-type=syslog [@rserver] log-level=debug logger-type=file max-size-mb=10 [file-locking] log-dir=/var/log/file-locking log-file-mode=600
This configuration specifies that by default, all logging should be sent to
info level or higher. Debug logging is enabled for the
rserver binary specifically, where logs are written to file with a maximum log file size of 10MB, in the default
/var/log/rstudio-server directory. File locking logging is also specifically redirected to a different logging directory,
/var/log/file-locking, with a specific file creation mode of
600. All logging sections named
file-locking which occur in the
rserver process will be logged to file, whereas the same logging sections in other binaries will continue to be logged to
The following settings may be specified:
|Config Option||Description||Default Value|
|log-level||The minimum log level to capture. Can be one of
|logger-type||The type of logger to use. Can be one of
When using the file logger, the following can also be specified:
|Config Option||Description||Default Value|
|log-dir||The log directory to store log files in. The resulting log file name is based on the binary name (and optionally the process ID).||
|log-file-mode||The filemode to use when creating the log file. Must be a valid POSIX octal file mode.||
|log-file-include-pid||Whether to include the process id in the filename. Useful for differentiating between multiple processes of the same name. Can be
|rotate||Whether or not to rotate the log file as it reaches maximum size. Can be
|max-size-mb||Maximum allowable size of the file before it is rotated. Only applicable if rotate is enabled.||
220.127.116.11 List of Logging Sections
The following is a list of logging sections that may be used within the logging configuration file.
|file-locking||Logging of file locking operations, such as processes acquiring and releasing locks.|
18.104.22.168 Reloading Configuration
In order to reload the logging settings during run-time of a process, simply send the
SIGHUP signal to the desired process, and the logging configuration will be reloaded for that binary.
For example, to send the
SIGHUP signal to the
rserver process after changing the configuration file:
pidof rserver | sudo xargs kill -s SIGHUP
2.3 Administrative Dashboard
RStudio Workbench includes an administrative dashboard with the following features:
- Monitoring of active sessions and their CPU and memory utilization;
- The ability to suspend, forcibly terminate, or assume control of any active session;
- Historical usage data for individual server users (session time, memory, CPU, logs);
- Historical server statistics (CPU, memory, active sessions, system load); and
- Searchable server log (view all messages or just those for individual users)
- The ability to lock users, preventing them from signing in to RStudio
The dashboard can be an invaluable tool in understanding server usage and capacity as well as to diagnose and resolve problems.
Note that at this time, historical monitoring is not available for sessions spawned via the Job Launcher.
2.3.1 Enabling the Dashboard
The administrative dashboard is accessed at the following URL:
The administrative dashboard is disabled by default. To enable it you set the
admin-enabled option. You can also specify that only users of certain group have access to the dashboard using the
admin-group option. For example:
You can specify a single group as the above example does or a comma-delimited list of groups. For example:
Note that changes to the configuration will not take effect until the server is restarted.
2.3.2 Administrator Superusers
You can further designate a certain user or group of users as administrative “superusers”. Superusers have the following additional privileges:
- Suspend or terminate active sessions
- Assume control of active sessions (e.g. for troubleshooting)
- Login to RStudio as any other server user
Administrative superusers do not have root privilege on the system, but rather have a narrow set of delegated privileges that are useful in managing and supporting the server. You can define the users with this privilege using the
admin-superuser-group setting. For example:
Note that as with the admin groups above, you can specify a single group as the above example does or a comma-delimited list of groups. For example:
Changes to the configuration will not take effect until the server is restarted. Admin superusers can also be added via the command line. See Adding users to the user database.
22.214.171.124 User Impersonation Restrictions
Note that the ability to login as other users and assume control of existing sessions is not available if you are authenticating with [SAML SSO], [Google Accounts] or proxied authentication. This is because these authentication mechanisms use a different user-identity mechanism which isn’t compatible with the way that user session impersonation is implemented.
2.3.3 Server Log Time Zone
You can control the time zone in which the server logs are displayed in the admin dashboard by the use of the
admin-monitor-log-use-server-time-zone option. For example:
Setting this option to
1 will display the server logs in the server’s time zone. The default value of
0 will display the log times in UTC.
2.3.4 Licensing Considerations
If you have been granted a license which has a limit on the total number of users that may use RStudio (i.e. named user licensing), you will need to control user access to the server. Each unique user that signs in to RStudio will count against your available user limit. If too many users sign in and attempt to use the system, new users will be denied, as the license limit will be reached.
If this occurs, please contact email@example.com to purchase additional users.
For more information on licensing, see License Management.
2.4 Automated Crash Reporting
RStudio allows you to automatically capture crash dumps for all RStudio processes and upload them to our crash database for easy reporting, allowing us to more easily determine the exact cause of crashes without adding administrative overhead to your team by requiring you to manually collect crash dumps. As user privacy is of utmost concern, these crash dumps only contain stack information, such as the names of the functions that were on the callstack at the time of the crash. No heap information is stored within the dumps, so no sensitive user data is captured in the crash dumps. The IP address of the machine uploading the reports is captured and used only to determine the unique amount of users experiencing a crash.
2.4.1 Crash Handler Configuration
A separate RStudio process is responsible for handling crashes, and may be configured similar to other RStudio processes by modifying the config file
/etc/rstudio/crash-handler.conf. Automated crash handling is disabled by default, though we recommend that you enable it. The following shows a table of available configuration options.
|Config Option||Description||Required (Y/N)||Default Value|
|crash-handling-enabled||Enables/disables automatic capturing of crash dumps for all RStudio processes.||N||0 (disabled)|
|crash-db-path||Location of the path where crash dumps should be stored on disk. This path must be readable and writeable by all RStudio users.||N||/tmp/crashpad_database|
|uploads-enabled||Enables/disables automatic uploading of crash dumps to our crash reporting service. If this is disabled, you will have to manually upload crash dumps.||N||1 (enabled)|
|upload-url||Web URL where crash reports are uploaded. You should likely not change this setting unless RStudio Support instructs you to do so.||N|
|upload-proxy||Proxy server to connect to when submitting the minidump. Only applicable on Linux - uses the default system-wide setting on OSX. If left blank, any system-wide setting specified will be used. This should be in the form of [scheme]://[host]:[port], where scheme may be one of the following:
For most RStudio installations, it is sufficient to merely set
crash-handling-enabled=1 in the config file, like so:
2.4.2 Manually Uploading Crash Dumps
In some cases, you may be unable to automatically upload crash dumps to the crash reporting service because of lack of internet connectivity or simply because you want to manually upload crash dumps. RStudio allows you to manually upload crash dumps at any time by invoking the following command:
rstudio-server upload-minidump /path/to/minidump