Command Line Interface

NAME

rstudio-server - a command-line interface for administering an RStudio server.

SYNOPSIS

rstudio-server COMMAND [ARGS…]

DESCRIPTION

rstudio-server is a utility script containing a collection of subcommands for performing administrative actions on an Posit Workbench instance.

COMMANDS

SERVER MANAGEMENT

offline
Takes the server offline. Users who attempt to access the server while it is offline will see a friendly message indicating that the server is currently offline, rather than the generic HTTP error they would see if the server is fully stopped.
online
Brings the server back online after the offline command was used.
reload
Reloads the server’s configuration without starting or stopping it. Only some configuration values are affected; others cannot be reloaded in place and require a full restart. Consult the administration guide for information on specific values.
restart
Restarts the server, similar to a stop followed by a start. Useful for applying configuration changes.
start
Start the server, if it is currently stopped.
status
Report the status of the server according to the service manager, for instance whether it is stopped, starting, or running
stop
Stop the server. Also stops all R sessions running locally on the server.

USER MANAGEMENT

add-user NAME [0|1]
Adds the user NAME to the list of licensed users. This is useful for allocating license seats; note however that it does not create Linux users or other system resources. The second argument, which is optional, indicates whether to create an ordinary user (0) or administrator (1).
list-users
Lists all the users, their license status (active or locked), and whether or not they are administrators.
lock-user NAME
Locks a user. Locked users cannot log in and don’t count against the licensing seat limit.
set-admin NAME 0|1
Sets the user NAME to either be an administrator (as in set-admin johndoe 1) or an ordinary user (0).
unlock-user NAME
Unlocks a previously locked user.

USER SERVICE

Tokens for authenticating with Workbench’s SCIM API can be managed using the user-service command.

user-service generate-token [–duration] NAME
Generates a token for the user service with the given name. This token can be used to authenticate with the user service SCIM API. The --duration option can be used to specify the duration of the token in days. If not specified, the token will be valid for 365 days.
user-service list-tokens
Lists all tokens for the user service.
user-service revoke-token [--all] TOKEN
Revokes the token with the given name. If --all is specified, revokes all tokens.

LOAD BALANCING

list-nodes
Lists all active nodes in the load balancing cluster, along with the status of each.
node-status
Load balancing status (enabled/disabled), and lists all cluster nodes and corresponding sessions
reset-cluster
Clears the internal load balancing state. This is used to reset the secure cookie key hash and transfer protocol used by the load balancing cluster.
delete-node ID
Permanently deletes the node with ID from the database and stops all nodes from messaging that node.

SESSION MANAGEMENT

active-sessions
Lists all currently active sessions. Only lists local R sessions; sessions running on other nodes or via the Job Launcher are not included.
force-suspend-all
Forcefully suspends all R sessions at once; doesn’t give users an opportunity to save their work. For a gentler alternative, use suspend-all.
force-suspend-session ID|PID
Forcefully suspends one specific session. If using a session controlled by the Job Launcher, its ID should be supplied (the eight characters at the end of its URL). Otherwise, supply the ID of session’s process ID (PID), which you can obtain via Sys.getpid() inside the session or by inspecting the process ID of the rsession process with ps.
kill-all ID|PID
Kills all sessions. This uses SIGKILL or the equivalent, so the session will not shut down gracefully and work can be lost. When the user next attempts to use the session, R will report it as having crashed.
kill-session ID|PID
Kills one specific session. If using a session controlled by the Job Launcher, its ID should be supplied (the eight characters at the end of its URL). Otherwise, supply the ID of session’s process ID (PID), which you can obtain via Sys.getpid() inside the session or by inspecting the process ID of the rsession process with ps.
suspend-all
Suspends all R sessions at once.
suspend-session ID|PID
Suspends one specific session. If using a session controlled by the Job Launcher, its ID should be supplied (the eight characters at the end of its URL). Otherwise, supply the ID of session’s process ID (PID), which you can obtain via Sys.getpid() inside the session or by inspecting the process ID of the rsession process with ps.

LICENSE MANAGEMENT

The server’s license can be managed through the license-manager command, which has an extensive set of subcommands. Most of these subcommands accept the --output option, which can be used to set the output format to either text (the default when connected to a terminal) or json, which is useful for scripting or machine readability.

license-manager activate [--proxy=PROXY] PRODUCT-KEY
Attempts to activate the server with the given product key. If successful, the server uses one “activation” of the product key and becomes fully licensed. It is not necessary to restart the server after activating it; the license will take effect immediately. Requires an Internet connection; use the --proxy option to specify a proxy URL.
license-manager activate-file LICENSE-FILE
Attempts to activate the server with the given license file. License files take precedence over other types of licensing.
license-manager activate-offline ACTIVATION-FILE
Applies an activation file from Posit Support to the server.
license-manager activate-offline-request
Starts the process of requesting a offline activation and generates a file you can send to Posit to complete the activation.
license-manager acquire-lease-verbose
Attempts to acquire a lease on a floating license, printing diagnostic information while doing so. Not useful except as a troubleshooting tool; Posit automatically acquires and releases leases during the normal course of operation, and also acquires a temporary lease while executing the status command.
license-manager begin-evaluation-offline EVALUATION-FILE
Begins the evaluation period, using an evaluation file supplied by Posit Support.
license-manager begin-evaluation-request
Starts the process of requesting an evaluation period and generates a file you can send to Posit. This typically isn’t necessary except on air-gapped machines which can’t automatically connect to the Internet to start an evaluation.
license-manager deactivate [--proxy=PROXY]
Deactivates the current license, making it available so that it can be used on another server. If successful, removes one “activation” of the product key. Requires an Internet connection; use the --proxy option to specify a proxy URL.
license-manager clear-license-server
Clears a license server previously set with the license-server command. Used to switch from floating licensing to traditional key-based licensing.
license-manager deactivate-offline
Deactivates the current license and prints an offline deactivation request; the license won’t be fully deactivated until you send the request to Posit for processing.
license-manager initialize [--userspace]
Initializes the licensing system. This is normally done during installation, so only needs to be performed manually when using alternative installation methods or switching to userspace licensing with the --userspace flag (see administration guide).
license-manager license-server HOSTNAME|URL
Sets the host (e.g. license.corp.com:8989) or URL (e.g. https://license.corp.com/) to use for floating licensing. Note that this has no effect unless Posit Workbench is configured to use floating licensing; see documentation for server-license-type.
license-manager verify
Verifies that the current license is valid; prints basic information about the license and exits. Typically status will give you richer information.
license-manager status
Prints detailed information about the current status of the licensing system: whether the license is currently valid, what licensing mode is in use (trial, key, floating), etc.

DIAGNOSTICS

run-diagnostics [--output-file=PATH]
Prepares an extensive diagnostics report containing configuration files, logs, system information, and other output useful to help troubleshoot errors and problems. The report is placed in /tmp/rstudio-diagnostics by default, but you can specify any other path using the --output-file option.
test-config
Tests the server’s configuration for validity.
upload-minidump MINIDUMP
Uploads a previously collected crash dump file (.dmp) to Workbench’s crash reporting service. Requires an active Internet connection. Crash dump files can be found in the crash-db-path path set in your crash-handler.conf file.
verify-installation
Performs a variety of tests to ensure that the server is installed and working correctly, including starting an R session, launching a trial job (if the Job Launcher is configured), etc.
Note that the server must be stopped in order for these tests to run, so use the stop command first if your server is running.
version
Reports the current version of the server and exits.

VS CODE

configure-vs-code
Creates the default configuration in /etc/rstudio/vscode.conf for using VS Code sessions. Pass -h to see additional options.
install-vs-code-ext [-l] [-v VERSION]
Installs Posit’s VS Code extension, which enables integration between VS Code and Posit Workbench. You may specify -l to install locally (only for the current user) and -v to download a specific version of the extension (advanced usage only).

DATABASE

encrypt-password
Encrypts a password. Doesn’t take any arguments; will prompt you for the password to encrypt and then emit the encrypted password. Use this utility to encrypt the database password in database.conf. When load balancing, ensure the same secure-cookie-key and database.conf are distributed across the cluster.
migrate-db
Migrates the internal database from a SQLite database to a PostgreSQL database. Useful when transitioning from a single-server to a multiple-server configuration.
Back to top