1 Getting Started

1.1 Overview

The RStudio Job Launcher provides an extensible and reusable mechanism for RStudio applications, such as RStudio Workbench, to start processes within various batch processing systems (e.g. Slurm) and container orchestration platforms (e.g. Kubernetes). RStudio products integrate with the Job Launcher to allow you to utilize your existing cluster hardware for maximum process isolation and operations efficiency.

1.2 Configuration Options

To configure the Job Launcher, create and modify the /etc/rstudio/launcher.conf file. Configuration options are listed below.

Server Options

There should be one [server] section in the configuration file (see sample config below).

Config Option Description Required (Y/N) Default Value
address IPv4 or IPv6 address, or path to Unix domain socket Y
port Port number (0-65535) Y (when using IP Address)
enable-ssl Toggle usage of SSL encryption for connections N 0
certificate-file Certificate chain file of public certificates to present to incoming connections. Must be readable by the server-user user. Y (Only required when SSL is enabled)
certificate-key-file Certificate private key file used for encryption. Must be readable by the server-user user. Y (Only required when SSL is enabled)
server-user Service user. The Launcher should be started as root, and will lower its privilege to this user for normal execution. N rstudio-server
authorization-enabled Enables/disables authorization - this is required for all but test systems. Can be 1 (enabled) or 0 (disabled) N 1
admin-group Group name of users that are able to see/control all jobs in the system, including jobs belonging to other users. If using with RStudio Workbench, this must match the rserver.conf’s server-user’s group value. N Empty
thread-pool-size Size of the thread pools used by the launcher N Number of CPUs * 2
request-timeout-seconds Number of seconds a plugin has to process a request before it is considered timed out N 120
bootstrap-timeout-seconds Number of seconds a plugin has to bootstrap before it is considered a failure N 120
max-message-size Maximum allowed message size (in bytes) of messages sent by plugins. It is strongly recommended you do not change this, but it may be increased if you exceed the limit. N 5242880
enable-debug-logging Enables/disables verbose debug logging. Can be 1 (enabled) or 0 (disabled) N 0
scratch-path Scratch directory where the launcher and its plugins write temporary state N /var/lib/rstudio-launcher
logging-dir Specifies the path where debug logs should be written. N /var/log/rstudio/launcher
secure-cookie-key-file Location of the secure cookie key, which is used to perform authorization/authentication. It is strongly recommended you do not change this. N /etc/rstudio/secure-cookie-key

Cluster Options

There should be one [cluster] section in the configuration file per cluster to connect to / plugin to load (see sample config below).

Config Option Description Required (Y/N) Default Value
name Friendly name of the cluster Y
type Type of the cluster (for human consumption, display purposes) Y The plugin type. Can be one of Local, Kubernetes, or Slurm
exe Path to the plugin executable for this cluster N If using an RStudio plugin like Local, Kubernetes, or Slurm, this will be inferred from the value of type. If using a custom plugin, you must provide the executable path by configuring this option.
config-file Path to the configuration file for the plugin N Each plugin will have its own default config location
allowed-groups Comma-separated list of user groups that may access this cluster N Empty (all groups may access)

1.2.1 Sample Configuration

/etc/rstudio/launcher.conf

[server]
address=127.0.0.1
port=5559
server-user=rstudio-server
admin-group=rstudio-server
authorization-enabled=1
thread-pool-size=4
enable-debug-logging=1

[cluster]
name=Local
type=Local
exe=/usr/lib/rstudio-server/bin/rstudio-local-launcher
allowed-groups=devs,admins

1.2.2 SSL Considerations

The Job Launcher can be configured to use SSL via the use of the certificate-file and certificate-key-file options above. When the Launcher is configured to use SSL, any node(s) connecting to the Launcher must ensure that the hostname configured in their address field matches the FQDN of the Common Name or Subject Alternate Name of the certificate that is presented by the Launcher. If the hostnames do not match exactly, SSL verification will fail, preventing connections to the Job Launcher.

The certificate files must be readable by the server-user user account, and it is recommended that the permissions be very restrictive to prevent leaking of the private key. This can be accomplished by setting the permissions to 600 and changing the owner to the server-user account. For example, if the server-user is set to the default rstudio-server account:

/etc/rstudio/launcher.conf

certificate-file=/etc/rstudio/launcher.crt
certificate-key-file=/etc/rstudio/launcher.key
sudo chmod 0600 /etc/rstudio/launcher.crt
sudo chmod 0600 /etc/rstudio/launcher.key
sudo chown rstudio-server /etc/rstudio/launcher.crt
sudo chown rstudio-server /etc/rstudio/launcher.key

Additionally, both the Job Launcher root certificates need to be imported into the trusted root certificate store on the systems that are accessing those addresses. For example, RSP server nodes connecting to the Launcher need to have the Job Launcher root certificate installed in their trusted certificate store to ensure that certificate verification works correctly. The exact steps for importing a certificate into the trusted root store are operating system specific and outside of the scope of this document.

1.2.3 Job Launcher Plugin Configuration

Each specific cluster plugin can be additionally configured via its own configuration file, and some plugins (such as the Kubernetes plugin) require additional configuration. Documentation for all plugins created by RStudio can be found in the following sections.