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 attributes such as role, username, name, email, and DN. 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: Alter a user
  • 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.
  • --detect-unreachable: Detect LDAP users no longer visible to Connect.

Flags for the alter command:

  • --username: Specifies the user name of the user to alter.
  • --user-id: Specifies the user id 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-unique-id: Specifies a new Unique ID (base64 value or Distinguished Name).
  • --update-ids-using: Update all Unique IDs matching the specified LDAP attribute.
  • --lock: Locks the user. Fails if --unlock is also present.
  • --unlock: Unlocks the user. Fails if --lock is also present.
  • --force-demoting: Force demotion of the last remaining administrator.
  • --yes: Alter without asking for confirmation. Use with caution!

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

List all users no longer seen by Connect (LDAP):

sudo ./bin/usermanager list --detect-unreachable

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

To do the same as above to a user without a username, use the --user-id flag to specify the ID of the desired user. IDs can be discovered via usermanager list.

sudo ./bin/usermanager alter --user-id 1 --new-role administrator

Note: --username and --user-id can be used interchangeably but not at the same time. Some users may not have names defined in which case only --user-id will work.

Demote the last remaining administrator to a non-administrative role

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

Change a user’s Unique ID (DN):

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

Use this command when the user’s DN has changed on the LDAP server and you have received a warning about it on RStudio Connect start up.

Change a user’s Unique ID (base64):

sudo ./bin/usermanager alter --username john \

Use this command when the value for the attribute used as the user’s Unique ID has changed on the LDAP server.

Note: An LDIF (LDAP Data Interchange Format) representation of the user object may contain values in the base64 format. This is true for binary values (such as objectGUID from Active Directory). On the other hand, string values (such as entryUUID from OpenLDAP) must be encoded as base64 before use. Please refer to your LDAP documentation how to obtain an LDIF for a user.

Update all users’ Unique IDs currently using DN:

sudo ./bin/usermanager alter --update-ids-using DN

Use this command after you have configured LDAP.UniqueIdAttribute for the first time.

Note: If the current value for the LDAP.UniqueIdAttribute setting is "DN" or not present this command does nothing.

Updating all users’ Unique IDs to use another attribute:

sudo ./bin/usermanager alter --update-ids-using < attribute >

Where <attribute> is the case-sensitive name of the LDAP attribute used previously in the RStudio Connect configuration for identifying LDAP users such as objectGUID (Microsoft AD) or entryUUID (OpenLDAP).

Use this command after you have re-configured LDAP.UniqueIdAttribute with a different attribute. This command can also be used to revert back to "DN" after removing LDAP.UniqueIdAttribute.

Note: If the current value for the UniqueIdAttribute setting is the same as <attribute> this command does nothing.

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