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:

  • --users: List users (default).
  • --groups: List groups.
  • --include-locked: Includes locked user accounts in the list.
  • --detect-unreachable: Detect LDAP objects (users or groups) 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.
  • --user-guid: Specifies the user guid of the user to alter.
  • --groupname: Specifies the group name of the group to alter.
  • --group-id: Specifies the group id of the group to alter.
  • --group-guid: Specifies the group guid of the group to alter.
  • --group-owner: Specifies a new owner will be set on the group (except LDAP). Requires specifying both a user to alter and group to alter.
  • --new-groupname: Specifies the new name for the group (except LDAP).
  • --new-username: Specifies the new username for the user (only Password, OAuth2).
  • --new-last-name: Specifies the new last name for the user (except LDAP, OAuth2).
  • --new-first-name: Specifies the new first name for the user (except LDAP, OAuth2).
  • --new-email: Specifies the new email address for the user (except LDAP, OAuth2).
  • --update-ids-using: Update all Unique IDs for users or groups matching the specified attribute (only LDAP).
  • --new-unique-id: Specifies a new Unique ID (base64 value or Distinguished Name) for a user or group.
  • --new-role: Specifies the role to set for the user. Allowed roles are viewer, publisher, and administrator.
  • --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:

/opt/rstudio-connect/bin/usermanager help

Specify a custom configuration file

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

List unlocked users:

sudo /opt/rstudio-connect/bin/usermanager list

Or:

sudo /opt/rstudio-connect/bin/usermanager list --users

Note: This distinguished name field (DN) is included in the results only when LDAP is used.

List all users (locked and unlocked):

sudo /opt/rstudio-connect/bin/usermanager list --include-locked

Or:

sudo /opt/rstudio-connect/bin/usermanager list --users --include-locked

Note: The distinguished name field (DN) is included in the results only when LDAP is used.

List all groups:

sudo /opt/rstudio-connect/bin/usermanager list --groups

Note: The distinguished name field (DN) is included in the results only when LDAP is used.

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

sudo /opt/rstudio-connect/bin/usermanager list --detect-unreachable

Or:

sudo /opt/rstudio-connect/bin/usermanager list --users --detect-unreachable

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

sudo /opt/rstudio-connect/bin/usermanager list --groups --detect-unreachable

Promote the user john to an administrator role

sudo /opt/rstudio-connect/bin/usermanager alter --username john --new-role administrator

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

sudo /opt/rstudio-connect/bin/usermanager alter --user-id 1 --new-role administrator

Or with --user-guid to specify the GUID of the desired user. GUIDs can be discovered via usermanager list.

sudo /opt/rstudio-connect/bin/usermanager alter \
  --user-guid 00000000-0000-4000-a000-000000000000 --new-role administrator

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

Change the owner of the group Administrators to be the user administrator (not supported with LDAP groups):

sudo /opt/rstudio-connect/bin/usermanager alter --groupname Administrators \
  --new-owner --username admin

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

sudo /opt/rstudio-connect/bin/usermanager alter --group-id 1 --new-owner --username admin

Or with --group-guid to specify the GUID of the desired groups. GUIDs can be discovered via usermanager list --groups.

sudo /opt/rstudio-connect/bin/usermanager alter \
  --group-guid 00000000-0000-4000-a000-000000000000 --new-owner --username admin

Note: --groupname, --group-id and --group-guid can be used interchangeably but not at the same time the same applies to --username, --user-id and --user-guid while specifying the new owner.

Demote the last remaining administrator to a non-administrative role

sudo /opt/rstudio-connect/bin/usermanager alter --username admin --new-role publisher --force-demoting

Update all users’ Unique IDs currently using DN:

sudo /opt/rstudio-connect/bin/usermanager alter --update-ids-using DN

Or:

sudo /opt/rstudio-connect/bin/usermanager alter --users --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.

Update all groups’ Unique IDs currently using DN:

sudo /opt/rstudio-connect/bin/usermanager alter --groups --update-ids-using DN

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

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

Updating all users’ Unique IDs to use another attribute:

sudo /opt/rstudio-connect/bin/usermanager alter --update-ids-using < attribute >

Or:

sudo /opt/rstudio-connect/bin/usermanager alter --users --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.

Updating all groups’ Unique IDs to use another attribute:

sudo /opt/rstudio-connect/bin/usermanager alter --groups --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 groups such as objectGUID (Microsoft AD) or entryUUID (OpenLDAP).

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

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

Change a user’s or a group’s Unique ID (DN) individually:

sudo /opt/rstudio-connect/bin/usermanager alter --username john \
     --new-unique-id="CN=John Johnson,OU=Users,DC=example,DC=com"
sudo /opt/rstudio-connect/bin/usermanager alter --groupname Admins \
     --new-unique-id="CN=Admins,OU=Groups,DC=example,DC=com"

Use this command when the user’s or group’s DN has changed on the LDAP server and usermanager --update-ids-using was not able to reach and recover them.

Change a user’s or a group’s Unique ID (base64) individually:

sudo /opt/rstudio-connect/bin/usermanager alter --username john \
     --new-unique-id="+4FR9WW0+0ecjM20sf3OZA=="
sudo /opt/rstudio-connect/bin/usermanager alter --groupname Admins \
     --new-unique-id="hYGFGBI987ud+hg7H8dndd=="

Use this command when the value for the attribute used as the user’s or group’s Unique ID has changed on the LDAP server and usermanager --update-ids-using was not able to reach and recover them.

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.

Dump audit logs to screen

sudo /opt/rstudio-connect/bin/usermanager audit

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

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

B.2 Migration Utility

The migrate 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