B Command-Line Interface

Connect includes tools with a command-line interface (CLI). These tools are typically targeted towards actions that might be performed when the web server is offline or is otherwise inaccessible. Other CLI commands are useful for performing actions against the server in a batch or scripted fashion.

These utilities are installed in /opt/rstudio-connect/bin/. They use the configuration defined in /etc/rstudio-connect/rstudio-connect.gcfg unless you specify an alternate configuration file with the --config flag.

B.1 User Management

This utility helps you list users and modify user roles. This can be used to recover if you are unable to access an RStudio Connect administrative account.

Connect’s usermanager CLI also includes the ability to dump audit logs. By default, the logs are displayed in a formatted table, but you can also choose to output comma-separated values for easy analysis in other tools.

The usermanager utility can only be run when Connect is stopped if you use the SQLite database provider. See Section 5.1 for information on stopping and restarting Connect. See Section 9 for information on database providers.

B.1.1 Commands

The usermanager utility supports the following commands:

  • list: Lists users
  • alter: Changes a user’s role
  • tokens: Lists tokens
  • deactivate: Deactivates tokens
  • audit: Dumps audit logs

B.1.2 Flags

Configuration for usermanager:

  • --config: The full or relative path to a Connect configuration file (.gcfg). Defaults to /etc/rstudio-connect/rstudio-connect.gcfg.

Flags for the list command:

  • --include-locked: Includes locked user accounts in the list.

Flags for the alter command:

  • --username: Specifies the user name of the user to alter.
  • --new-role: Specifies the role to set for the user. Allowed roles are viewer, publisher, and administrator.
  • --new-username: Specifies the new username for the user.
  • --new-last-name: Specifies the new last name for the user.
  • --new-first-name: Specifies the new first name for the user.
  • --new-email: Specifies the new email address for the user.
  • --new-dn: Specifies the new DN for the LDAP user.
  • --force: Force demotion of the last remaining administrator.

Flags for the token command:

  • --active: Show only active tokens.

Flags for the deactivate command:

  • --all: Deactivate all tokens.

Flags for the audit command:

  • --csv: Output comma-separated values.

B.1.3 Examples:

Display help:

./bin/usermanager help

List unlocked users:

sudo ./bin/usermanager list

List all users (locked and unlocked):

sudo ./bin/usermanager list --include-locked

Specify a custom configuration file

sudo ./bin/usermanager --config /etc/connect/mycustomconfig.gcfg list

Promote the user john to an administrator role

sudo ./bin/usermanager alter --username john --new-role administrator

Demote the last remaining administrator to a non-administrative role

sudo ./bin/usermanager alter --username admin --new-role publisher --force

Change a user’s DN:

sudo ./bin/usermanager alter --username john \
     --new-dn="CN=John Johnson,OU=Users,DC=example,DC=com"

Dump audit logs to screen

sudo ./bin/usermanager audit

Dump audit logs (comma-separated) to a file:

sudo ./bin/usermanager audit --csv > ~/audits.txt

B.2 Migration Utility

The migration utility assists system administrators in migrating from one database to another or in transitioning RStudio Connect to a new server. For a high-level overview of the steps necessary to migrate from SQLite to Postgres, see the section on changing database providers. For the high-level steps involved in completing a server migration, see 4.8.

B.2.1 Commands

The migrate utility supports four commands

  • db: Migrate data between databases
  • rebuild-packrat: Rebuilds the Packrat cache for all content on the server. This command can be used WHILE RStudio Connect is running.
  • repair-content-permissions: Checks and corrects permissions and ownership for the working directories of each deployed piece of content.
  • help: Displays help

B.2.2 Flags

Configuration for migrate:

  • --config: The full or relative path to a Connect configuration file (.gcfg). Defaults to /etc/rstudio-connect/rstudio-connect.gcfg.

Flags for the migrate db command:

  • --verify: Verify migration only.
  • --drop-all: Drop all existing data in the target before migrating.

By default, the migrate db command will copy the data from the SQLite database into PostgreSQL, and verify the migration. We assume that the PostgreSQL destination does not contain any data unless the --drop-all flag is included.

Data migration copies data from the SQLite database to the PostgreSQL database. Data in the SQLite database remains after the migration; it is not removed. A verification step runs after the data copy completes and confirms the integrity of the migration:

  • Row counts for all tables are verified.
  • Each record is checked for the correct values.

Data verification will fail if Connect is started prior to the completion of data verification. Please ensure that Connect remains down until the data migration and verification are complete.

Flags for the rebuild-packrat command:

  • -force: Delete the Packrat cache before rebuilding
  • -fast-fail: Stop when the packages for a single application cannot be installed.

Proactively rebuilds the Packrat cache for all applications on the server. When the -force flag is used, the entire existing Packrat cache directory will be deleted first. This command can be used for instances in which the Packrat cache may be incomplete for the current environment. For example, if the system only has one version of R installed and it has been upgraded, the cache will not include packages built on the appropriate version of R. Similarly, if you migrate your RStudio Connect installation to a different server which might have different versions of system libraries, you should delete the cache and rebuild it as discussed in 4.8.

When the -fast-fail flag is used, rebuilding the Packrat package cache is halted when the packages for any application cannot be installed or verified as installed.

Flags for the repair-content-permissions command:

No flags supported.

Scans for issues with the permissions and ownership of application directories on the server. This command can be used if you have moved some data on disk and need to confirm that the attributes were transferred properly.

B.2.3 Examples

Display help:

/opt/rstudio-connect/bin/migrate help

Migrate SQLite data to an empty PostgreSQL database:

sudo /opt/rstudio-connect/bin/migrate db

Migrate SQLite data to a PostgreSQL database, first dropping all data in the PostgreSQL database:

sudo /opt/rstudio-connect/bin/migrate db --drop-all

Perform data verification only:

sudo /opt/rstudio-connect/bin/migrate db --verify

Specify a custom configuration file:

sudo /opt/rstudio-connect/bin/migrate --config /etc/connect/mycustomconfig.gcfg db

Delete the existing Packrat cache and rebuild it by pro-actively rebuilding each application’s library.

sudo /opt/rstudio-connect/bin/migrate rebuild-packrat --force

Check and fix any disk permission errors for applications’ working directories.

sudo /opt/rstudio-connect/bin/migrate repair-content-permissions