Core Administrative Tasks
Configuration files
Posit Workbench uses several configuration files, which are all located within the /etc/rstudio directory by default.
Unless otherwise noted in the Takes Effect column in the table below, you must restart both Workbench and the Launcher to apply configuration changes.
Terminal
sudo rstudio-server restart
sudo rstudio-launcher restartThe Launcher only needs to be restarted when Launcher configuration files (e.g., launcher.conf, launcher.slurm.conf, launcher.kubernetes.conf) have changed. However, restarting both services is recommended as a safe default.
Settings marked with reload can be updated without restarting the server using a reload command:
Terminal
sudo rstudio-server reloadSettings marked with Launcher reload can be updated without restarting the Launcher by sending a SIGHUP signal to the rstudio-launcher process:
Terminal
sudo killall -HUP rstudio-launcherSettings marked with session take effect for all new sessions. Sessions that are already running will continue to use the previous setting.
Settings marked with immediate take effect immediately.
| Filename | Description | Takes Effect | |
|---|---|---|---|
| rserver.conf | Core Workbench server settings | ||
| rsession.conf | Settings related to individual RStudio or RStudio Pro sessions | reload | |
| logging.conf | Configuration of the logging system including logger type, location, and level | reload | |
| database.conf | Configuration of the internal database that Posit Workbench will store data in (see Internal Database) | ||
| repos.conf | Customize the location of user packages installed from CRAN as well as the default CRAN repo | session | |
| rstudio-prefs.json | System-wide RStudio IDE preferences | session | |
| file-locks | Configuration for file locking | ||
| env-vars | Additional environment variables to set during the Workbench server process startup | reload | |
| secure-cookie-key | Private key used to sign authentication cookies | ||
| login.html | Custom HTML for login page | ||
| themes/ | Custom editor color schemes | session | |
| fonts/ | Fonts for the R console and code editor in RStudio Desktop and RStudio Pro | session | |
| keybindings/ | Custom IDE keybindings | session | |
| snippets/ | Editor snippet files | session | |
| templates/ | Default templates for new files created in the IDE | session | |
| dictionaries/ | Custom spelling languages and dictionaries | session | |
| connections/ | Database connection snippet files | immediate | |
| audit-database.conf | Configuration of the database that Posit Workbench will store auditing records data in (see Audit Database) | ||
| databricks.conf | Configurations for the Databricks integration | reload | |
| health-check | Template for content to return for Workbench server process health checks | ||
| ip-rules | IP access rules (allow or deny groups of IP addresses) | reload | |
| load-balancer | Load balancing configuration | reload | |
| launcher.conf | Configuration of the Launcher | ||
| launcher.local.conf | Configuration of the Local Launcher Plugin | ||
| launcher.local.profiles.conf | Configuration of resource limits by user and group when using the Local Launcher Plugin | Launcher reload | |
| launcher.local.resources.conf | Configuration of user-selectable resource profiles when using the Local Launcher Plugin | Launcher reload | |
| launcher.kubernetes.conf | Configuration of the Kubernetes Launcher Plugin | ||
| launcher.kubernetes.profiles.conf | Configuration of resource limits by user and group when using the Kubernetes Launcher Plugin | Launcher reload | |
| launcher.kubernetes.resources.conf | Configuration of user-selectable resource profiles when using the Kubernetes Launcher Plugin | Launcher reload | |
| launcher.slurm.conf | Configuration of the Slurm Launcher Plugin | ||
| launcher.slurm.profiles.conf | Configuration of resource limits by user and group when using the Slurm Launcher Plugin | Launcher reload | |
| launcher.slurm.resources.conf | Configuration of user-selectable resource profiles when using the Slurm Launcher Plugin | Launcher reload | |
| launcher-env | Environment variables used in Launcher sessions | ||
| launcher-ports | Port mappings exposed by containerized sessions | ||
| launcher-mounts | Configuration for mount points used by containerized sessions | ||
| jupyter.conf | Configuration of JupyterLab and Jupyter Notebook sessions | ||
| notifications.conf | Notifications to be delivered to user sessions | session | |
| nginx.http.conf | Extra HTTP configuration for nginx | reload | |
| nginx.metrics-directives.conf | Extra directives for nginx when serving metrics | reload | |
| nginx.metrics-server.conf | Extra server configuration for nginx when serving metrics | reload | |
| nginx.server.conf | Extra server configuration for nginx | reload | |
| nginx.site.conf | Extra site configuration for nginx | reload | |
| nginx.worker.conf | Extra worker process configuration for nginx | reload | |
| openid-client-secret | OpenID Connect client ID and secret | ||
| positron.conf | Configuration of Positron Pro sessions | ||
| positron.extensions.conf | Extensions to automatically install in Positron Pro sessions | session1 | |
| positron-user-settings.conf | System-wide default Positron Pro user settings | session | |
| profiles | User and group resource limits | ||
| r-versions | Manual specification of additional versions of R | reload | |
| snowflake.conf | Configurations for the Snowflake integration | reload | |
| vscode.conf | Configuration of VS Code sessions | ||
| vscode.extensions.conf | Extensions to automatically install in VS Code sessions | session2 | |
| vscode-user-settings.conf | System-wide default VS Code user settings | session | |
| workbench-nss.conf | NSS module configuration used for user provisioning | ||
| positron-custom-bootstrap/ | Custom Positron bootstrap extensions | session | |
| profiles_positron/ | Profile-based configuration overrides for Positron Pro sessions | ||
| profiles_vscode/ | Profile-based configuration overrides for VS Code sessions |
Default rserver.conf and rsession.conf files are created during installation. Files containing commented examples are also created for notifications.conf and r-versions. The other files are optional. Create them to configure settings contained in them.
Ensure that rsession.conf can be read by all Workbench users by setting appropriate filesystem permissions (e.g., 644).
Alternate configuration file location
Posit Workbench 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 Posit Workbench 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 Posit Workbench’s configuration to live in /mnt/config/rstudio.
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/rstudioCopy 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/Configure service
Because Posit Workbench 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.
[Service]
Environment="XDG_CONFIG_DIRS=/mnt/config"If you wish to set Posit Workbench’s configuration folder directly, use the RSTUDIO_CONFIG_DIR environment variable instead. For example, to use /mnt/config/rstudio as the configuration folder:
[Service]
Environment="RSTUDIO_CONFIG_DIR=/mnt/config/rstudio"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 XDG_CONFIG_DIRS.
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 Workbench’s rstudio-server service.
Change and restart
Finally, make any configuration changes you’d like in your new configuration folder, and then restart the Workbench server process to use the new configuration files.
sudo rstudio-server restartTo return to the configuration in /etc/rstudio, just remove the Environment directive added above and restart the service.
Configuring the run-time data directory
Posit Workbench 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:
server-data-dir=/var/run/rstudio-serverThe 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 Posit Workbench.
Setting environment variables
You can set environment variables for Posit Workbench’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 HTTP_PROXY and XDG_DATA_HOME environment variables for the Workbench server process:
/etc/rstudio/env-vars
# 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/$USERThe env-vars file is reloaded, and the environment variables set again, when you restart Posit Workbench or reload the configuration. See Reloading configuration values for more information.
This technique cannot be used to set the specific environment variables XDG_CONFIG_DIRS or RSTUDIO_CONFIG_DIR, because those variables control where configuration files are loaded from, and env-vars is itself a configuration file. Use your system’s service manager to set those variables as described in Alternate Configuration File Location.
With the exception of XDG variables, environment variables set for the Workbench server process are not generally forwarded to individual RStudio Pro Sessions. To set environment variables such as HTTP_PROXY for all RStudio Pro Sessions running in Workbench, use Renviron.site or set them in one of the scripts executed when RStudio Pro Sessions are initialized (see Profile script execution).
Stopping and starting
During installation, Posit Workbench registers as a daemon with the operating system’s init system. Refer to the documentation for your Linux distribution to learn which init system it uses.
To stop, start, or restart the Workbench and Launcher services, use the following commands:
sudo rstudio-server stop
sudo rstudio-server start
sudo rstudio-server restart
sudo rstudio-launcher stop
sudo rstudio-launcher start
sudo rstudio-launcher restartTo check the current stopped/started status of the Workbench server service:
sudo rstudio-server statusReloading configuration values
To reload the Workbench server’s configuration without restarting it, use the reload command:
sudo rstudio-server reloadAlternately, you can send a SIGHUP to the Workbench rserver process, using a command like kill -s SIGHUP $PID, where $PID is the process ID of the rserver process.
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 reload command:
- 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.
Session Lifecycle
When using the Job Launcher, Workbench sessions are launched as child processes of the respective Job Launcher Plugin. This means that restarting Posit Workbench will not necessarily cause sessions to suspend or be terminated.
When not using the Job Launcher, Workbench sessions are started as children of the Workbench server process. As a result, in this configuration, restarting Workbench will cause the termination of sessions.
If you want to more actively manage sessions and trigger suspension or termination then you can make use of the Managing active sessions section below.
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-sessionsSuspending sessions
When RStudio Pro Sessions have been idle (no processing or user interaction) for a specified period of time (2 hours by default) Posit Workbench suspends them to disk to free up system 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-allThe 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-allThe force-suspend-all command should be issued immediately prior to any reboot so as to preserve the data and state of active RStudio Pro Sessions across the restart.
Killing sessions
If you are for any reason unable to cooperatively suspend an RStudio Pro 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-allNote 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).
Listing Users
You can list all of the users that have signed in to Posit Workbench by running the following command:
sudo rstudio-server list-usersAdding users to the user database
Normally, when users sign in to Posit Workbench for the first time, they are automatically added to the Posit Workbench 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.
Users set as administrators in this way will be Admin Superusers. See Administrator superusers.
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>Locking and unlocking users
If you are using Posit Workbench under a named user license, you can lock and unlock specific users to disallow or re-allow access to Workbench. Locking a user will prevent them from signing in to Workbench, 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 Posit 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 Workbench server management utility:
sudo rstudio-server lock-user <username>
sudo rstudio-server unlock-user <username>Note that Posit Workbench’s Software License Descriptions only allow this feature to be used to permanently terminate a named user’s access.
To permanently terminate a user’s access to allow re-assignment of their seat per the Posit Workbench Software License Descriptions, simply lock that specific user’s account.
User management commands can also be run as the Workbench service account (default: rstudio-server) without root, which is useful in automated or containerized environments.
Taking the Workbench server offline
If you need to perform system maintenance and want users to receive a friendly message indicating the Workbench server is offline you can issue the following command:
sudo rstudio-server offlineWhen the Workbench server is once again available you should issue this command:
sudo rstudio-server onlineWhen the Workbench server is taken offline all RStudio Pro Sessions will be suspended and no new sessions can be started. Session data will be saved but any running computations will be terminated.
Upgrading to a new version
If you upgrade Workbench and an existing version of the server is currently running, then the upgrade process also ensures 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.
- Connected browser clients are notified that a new version is available and automatically refreshes themselves.
- The core server binary restarts.
When load balancing is configured upgrading multiple nodes may cause brief glitches if you upgrade each Workbench node one at a time. This is due to the possibility of two Workbench nodes 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 Posit Workbench, please use our Upgrade documentation.
Footnotes
Use
sudo rstudio-server install-positron-extto install extensions listed inpositron.extensions.conf. See Positron Extension Configuration for more information.↩︎Use
sudo rstudio-server install-vs-code-extto install extensions listed invscode.extensions.conf. See VS Code Extension Configuration for more information.↩︎