Local Plugin

Workbench

The Local Job Launcher Plugin provides the capability to launch executables on the local machine (same machine that the Launcher is running on). It also provides the capability of running arbitrary PAM profiles. All of the sandboxing capability is provided via rsandbox.

Configuration

The local plugin does not require configuration, and it is recommended you do not change any of the defaults.

/etc/rstudio/launcher.local.conf

Config Option Description Required (Y/N) Default Value
server-user User to run the executable as. The plugin should be started as root, and will lower its privilege to this user for normal execution. It is recommended not to change the default value, as this is populated by the Launcher service itself. N rstudio-server
thread-pool-size Size of the thread pool used by the plugin. It is recommended not to change the default value, as this is populated by the Launcher service itself. N Number of CPUs * 2
enable-debug-logging Enables/disables verbose debug logging. Can be 1 (enabled) or 0. (disabled) N 0
scratch-path Scratch directory where the plugin writes temporary state N /var/lib/rstudio-launcher/{name of plugin}
logging-dir Specifies the path where debug logs should be written. N /var/log/rstudio/launcher
job-expiry-hours Number of hours before completed jobs are removed from the system N 24
save-unspecified-output Enables/disables saving of stdout/stderr that was not specified in submitted jobs. This will allow users to view their output even if they do not explicitly save it, at the cost of disk space. N 1
rsandbox-path Location of rsandbox executable. N /usr/lib/rstudio-server/bin/rsandbox
verify-ssl-certs Whether or not to verify SSL certificates when connecting to other Launcher instances. Only applicable if connecting over HTTPS and load balancing is in use. For production use, you should always leave the default or have this set to true, but it can be disabled for testing purposes. N 1
unprivileged Runs the Launcher in unprivileged mode. Child processes will not require root permissions. If the plugin cannot acquire root permissions it will run without root and will not change users or perform any impersonation. N 0
node-connection-timeout-seconds The amount of seconds to allow for the process to connect to load balanced nodes before giving up on the connection. N 3
stream-idle-timeout-seconds The amount of seconds to allow a stream to a load balanced node to be idle before it is timed out and reconnected. This is important to keep somewhat low, as network middleware and node crashes can cause these streams to become stale. N 300 (5 minutes)
load-balancer-hostname The hostname to use for load balancing. It is recommended to set this if using external load balancing and the hosts for a particular node are mismatched. N Defaults to system hostname
load-balancer-preference Specifies the preference for which load balancing mode to use. Once the mode has switched to the preference, the other load balancing type will no longer be used. Can be either external or nfs. N nfs

Session Lifecycle

RStudio, Jupyter, and VS Code sessions are launched as child processes of the Local Job Launcher Plugin. This means that restarting Posit Workbench will not necessarily cause sessions to suspend or be terminated. However, restarting the Job Launcher will cause sessions to exit.

Load balancing considerations

In order to effectively load balance the local plugin, the following must be true across each instance of the plugin that you intend to balance:

  • Each hostname of the systems running the local plugin must be unique.
  • Each local plugin must be configured the same - the name of the local plugin must also match across all instances in the load balancer pool.
  • When using nfs load balancing, the scratch-path directory above must be located on shared storage so that all instances of the plugin may see the presence of other nodes. It is recommended that you create the directory on NFS first and change the owner to the server-user above so that the directory will be correctly writable by the plugin. These steps can be performed as follows (assuming default values for configuration are used):
sudo mkdir -p /var/lib/rstudio-launcher/Local
sudo chown rstudio-server /var/lib/rstudio-launcher/Local

# now, mount the path created above into all hosts that you will be load balancing
  • If using external load balancing, the load-balancer-hostname must match what is detected by the external load balancer (such as Workbench).
  • Each local plugin node must be able to directly connect to the launcher service located on other nodes in the load balance pool.
  • When each node comes online, it downloads all jobs from the other nodes in the load balance pool, so if you frequently have a large amount of jobs in memory you may need to raise the max-message-size /etc/rstudio/launcher.conf parameter described above. The default of 5 MiB should be sufficient for a working load of approximately 1000 jobs (though this will vary based on average job size).

Once these steps have been accomplished, simply start each instance of the launcher/local-plugin that you wish to load balance.