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 and in /etc/rstudio-connect/rstudio-connect-migration.gcfg unless you specify an alternate configuration file with the --config flag. In that case, RStudio Connect will attempt to load a second file with the suffix migration.

Note: All command flags accept both double (--) dashes as indicated here or single (-) dashes as indicated in the command built-in help and error messages.

B.1 Connect

The executable connect is responsible for all services provided by RStudio Connect. In general, there’s no need for connect to be used directly.

B.1.1 Flags

WARNING: Using the flags below implies a custom installation. Do not attempt to use these flags unless strictly necessary.

The connect supports the following flags:

  • --config: The path of your configuration file. The path to the migration file is derived from this.
  • --migration-config: Overrides the derived path with a different location for the migration file.

Note: The derived migration file name is the name of the file passed to the --config flag suffixed with -migration. By default /etc/rstudio-connect/rstudio-connect.gcfg is the main configuration and /etc/rstudio-connect/rstudio-connect-migration.gcfg is the migration file.

B.1.2 Examples

Set an alternate location for the configuration file:

/opt/rstudio-connect/bin/connect --config /etc/rstudio-connect/rstudio-connect.gcfg

Set an alternate location for the migration file:

/opt/rstudio-connect/bin/connect --config /etc/rstudio-connect/rstudio-connect.gcfg \
    --migration-config /etc/rstudio-connect/rstudio-connect-migration.gcfg

Note: You should use this setting if the default path /etc/rstudio-connect is not writable.

B.2 RSC Administrative Tool

This utility may be used to help you manage your configuration information. This includes the ability to encrypt configuration values such as passwords to be used in the configuration for added security and to manage the configuration migration, moving settings from the migration file (which is managed by RStudio Connect) to your main configuration file.

B.2.1 Commands

The rscadmin utility supports the following commands:

  • configure: Initial setup and configuration utilities

B.2.2 Flags

Configuration for rscadmin:

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

Note: The configuration path must be the first flag in a custom installation.

Flags for the configure command:

  • --append-migration: Write the migrated settings directly to the main configuration file. Must be used alone.
  • --encrypt-config-value: Read a value from the standard input and write it encrypted to the standard output. Must be used alone.
  • --reset-secret-key: Reset the secret key signature in the database allowing the use of a new encryption key file created on disk.

B.2.3 Examples

Encrypt a configuration value:

/opt/rstudio-connect/bin/rscadmin configure --encrypt-config-value

Note: You will be prompted to enter the value and the output is printed in the base64 format. The encrypted value should then be transferred to the configuration file for the appropriate setting.

WARNING: The settings Server.DataDir or Database.Dir determine the location of the key used for encryption. Any changes to these values between the time the value has been encrypted and the next time RStudio Connect is started will cause a different key to be used leading to the value being considered as if it were plain text.

Append migrated settings to the main configuration file:

/opt/rstudio-connect/bin/rscadmin configure --append-migration

Note: After the transfer, rstudio-connect-migration.gcfg (or the file derived from --config or pointed by --migration-config) will be left empty.

Reset the secret key signature:

/opt/rstudio-connect/bin/rscadmin configure --reset-secret-key

WARNING: Use this option only if the encryption key file has been lost due to a human error or a disk failure and you’re receiving the following message in the RStudio Connect log: Secret key mismatch between database and file; the database was previously used with a different secret key that began with: <signature>

Note: This command only allows RStudio Connect to proceed past this error by resetting the encryption key signature stored in the database. However, at this point it means the following has been lost and it’s unrecoverable: - All encrypted data in the database, such as environment variable values; and - All encrypted settings in the configuration, such as security credentials.

RStudio Connect will run after this command but configuration settings need to be re-encrypted and each piece of content relying on environment variable values need to have these manually re-entered.

If the original encryption key is found and restored to its configured location after this command is run once, the error above will be reported in the log and the command will have to be executed again. It’s possible some data not yet replaced may be recoverable in this case.

Specify a custom configuration file:

sudo /opt/rstudio-connect/bin/rscadmin --config /etc/connect/mycustomconfig.gcfg configure

Specify a custom migration file:

sudo /opt/rstudio-connect/bin/rscadmin --migration-config /etc/connect/mycustommigration.gcfg configure

B.3 User Management

This utility helps you list users and modify user attributes such as role, username, name, email, and Unique ID. This can be used to recover if you are unable to access an RStudio Connect administrative account. Similar operations can be done for groups, such as listing and changing the group name, Unique ID or even owner.

Modifications done to users and groups made via usermanager are recorded in the audit logs.

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 10 for information on database providers.

B.3.1 Commands

The usermanager utility supports the following commands:

  • list: Lists users or groups
  • alter: Alter a user or group
  • transfer: Transfer user owned items to another user or group relationships to another group
  • delete: Delete a user or a group
  • tokens: Lists tokens
  • deactivate: Deactivates tokens
  • audit: Dumps audit logs

B.3.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.
  • --migration-config: The full or relative path to a Connect migration file. Defaults to /etc/rstudio-connect/rstudio-connect-migration.gcfg.

Note: The configuration path must be the first flag in a custom installation.

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.
  • --base64-unique-id: Detect, decode and attempt to interpret UniqueId values encoded as base64.
  • --force-hex: When used with --base64-unique-id do not attempt to interpret values showing them as hex.
  • --force-ms-guid: When used with --base64-unique-id will attempt to convert GUID/UUID values to the Microsoft format.

Flags for the alter command:

  • --users: Specify operations over users (default).
  • --groups: Specify operations over groups.
  • --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.
  • --new-owner: Specifies a new owner to be set on the group (except groups managed by an auth provider). Requires specifying both a user to alter and group to alter.
  • --drop-owner: Specifies the removal of the group owner (except groups managed by users).
  • --new-groupname: Specifies the new name for the group (except groups managed by an auth provider).
  • --new-username: Specifies the new username for the user (only Password, OAuth2, Proxied auth with UniqueID).
  • --new-last-name: Specifies the new last name for the user (except OAuth2 or managed by Proxied, LDAP, SAML).
  • --new-first-name: Specifies the new first name for the user (except OAuth2 or managed by Proxied, LDAP, SAML).
  • --new-email: Specifies the new email address for the user (except OAuth2 or managed by Proxied, LDAP, SAML).
  • --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.
  • --base64-unique-id: When used with --new-unique-id will encode the input as base64.
  • --force-hex: When used with --base64-unique-id will handle the input as a hex-encoded binary value.
  • --force-ms-guid: When used with --force-hex will first convert GUID/UUID values to the Microsoft format.

Flags for the transfer command:

  • --users: Specify operations over users (optional).
  • --groups: Specify operations over groups (optional).
  • --source-username: Specifies the user name of the source user to transfer from.
  • --source-user-id: Specifies the user id of the source user to transfer from.
  • --source-user-guid: Specifies the user guid of the source user to transfer from.
  • --target-username: Specifies the user name of the target user to transfer to.
  • --target-user-id: Specifies the user id of the target user to transfer to.
  • --target-user-guid: Specifies the user guid of the target user to transfer to.
  • --source-groupname: Specifies the group name of the source group to transfer from.
  • --source-group-id: Specifies the group id of the source group to transfer from.
  • --source-group-guid: Specifies the group guid of the source group to transfer from.
  • --target-groupname: Specifies the group name of the target group to transfer to.
  • --target-group-id: Specifies the group id of the target group to transfer to.
  • --target-group-guid: Specifies the group guid of the target group to transfer to.
  • --memberships: Additionally transfer group memberships (except LDAP).
  • --permissions: Additionally transfer permissions and email subscriptions to content. This is implied for groups.
  • --api-keys: Additionally transfer API keys.
  • --delete: Delete the user or group and references to it after the transfer.
  • --yes: Skip confirmation for both transfer and deletion.
  • --verbose: Show a detailed list of items affected by the operation before the confirmation.

Flags for the delete command:

  • --users: Specify operations over users (optional).
  • --groups: Specify operations over groups (optional).
  • --username: Specifies the user name of the user to delete.
  • --user-id: Specifies the user id of the user to delete.
  • --user-guid: Specifies the user guid of the user to delete.
  • --groupname: Specifies the group name of the group to delete.
  • --group-id: Specifies the group id of the group to delete.
  • --group-guid: Specifies the group guid of the group to delete.
  • --yes: Skip confirmation for deletion.
  • --verbose: Show a detailed list of items affected by the operation before the confirmation.

Flags for the token command:

  • --active: Show only active tokens.

Flags for the deactivate command:

  • --all: Deactivate all tokens.

Flags for the audit command:

  • --table: Output entries as a formatted table, newest entry first (default).
  • --jsonlog: Output entries as JSON objects (as produced by Server.AuditLogFormat as JSON), oldest entry first.
  • --csvlog: Output entries as comma-separated values (as produced by Server.AuditLogFormat as CSV), oldest entry first.
  • --csv: Deprecated: Output entries as comma-separated values with header (use timestamps in the format YYYY-MM-DD HH:MI:SS -ZZZZ MST for backwards compatibility, event before user), newest entry first as in the default format.
  • --since: Output the entries on or after this timestamp.
  • --until: Output the entries up to and before this timestamp.

Note: The timestamp filters --since, --until are in the RFC-3339 format (i.e. 2006-01-02T15:04:05) and they can be partial, for example 2001, 2001-02, 2001-02-03, 2001-02-03T23:22.

B.3.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

Specify a custom migration file

sudo /opt/rstudio-connect/bin/usermanager --migration-config /etc/connect/mycustommigration.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

List users or groups attempting to decode and interpret base64 UniqueIDs:

sudo /opt/rstudio-connect/bin/usermanager list --users --base64-unique-id
sudo /opt/rstudio-connect/bin/usermanager list --groups --base64-unique-id

Note: The --base64-unique-id option works with --detect-unreachable and --include-locked.

List users or groups just decoding base64 UniqueIDs and showing values as hex:

sudo /opt/rstudio-connect/bin/usermanager list --users --base64-unique-id --force-hex
sudo /opt/rstudio-connect/bin/usermanager list --groups --base64-unique-id --force-hex

List users or groups giving a hint that GUIDs may be in the Microsoft format:

sudo /opt/rstudio-connect/bin/usermanager list --users --base64-unique-id --force-ms-guid
sudo /opt/rstudio-connect/bin/usermanager list --groups --base64-unique-id --force-ms-guid

Note: Use this option if the UniqueID is represented by a binary Microsoft GUID (such as objectGUID).

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 or automatic group provisioning in Proxied authentication):

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.

Remove the owner of the existing group Administrator so it can be used with LDAP or with automatic group provisioning in Proxied authentication:

sudo /opt/rstudio-connect/bin/usermanager alter --groupname Administrators \
  --drop-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 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 individually, encoding the result as base64:

sudo /opt/rstudio-connect/bin/usermanager alter --username john \
     --new-unique-id="f04db6b3-5bab-437b-b46d-18b46d1fd16f" --base64-unique-id
sudo /opt/rstudio-connect/bin/usermanager alter --groupname Admins \
     --new-unique-id="f04db6b3-5bab-437b-b46d-18b46d1fd16f" --base64-unique-id

Note: Use this option if the UniqueID is represented by a textual value in LDAP (such as entryUUID).

Change a user’s or a group’s Unique ID individually, interpreting hex values as binary then encoding the result as base64:

sudo /opt/rstudio-connect/bin/usermanager alter --username john \
     --new-unique-id="010500000000000515000000bed626e0d5fbb2934fb4ee9557040000" \
     --base64-unique-id --force-hex
sudo /opt/rstudio-connect/bin/usermanager alter --groupname Admins \
     --new-unique-id="010500000000000515000000bed626e0d5fbb2934fb4ee9557040000" \
     --base64-unique-id --force-hex

Note: Use this option if the UniqueID is represented by a binary value in LDAP (such as objectSID).

Change a user’s or a group’s Unique ID individually, interpreting hex values as binary, forcing the Microsoft representation for GUIDs and then encoding the result as base64:

sudo /opt/rstudio-connect/bin/usermanager alter --username john \
     --new-unique-id="f04db6b3-5bab-437b-b46d-18b46d1fd16f" \
     --base64-unique-id --force-hex --force-ms-guid
sudo /opt/rstudio-connect/bin/usermanager alter --groupname Admins \
     --new-unique-id="f04db6b3-5bab-437b-b46d-18b46d1fd16f" \
     --base64-unique-id --force-hex --force-ms-guid

Note: Use this option if the UniqueID is represented by a binary Microsoft GUID (such as objectGUID).

Change a user’s or a group’s Unique ID individually with base64 values encoded externally:

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.

Transfer user-owned groups and content to another user

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane

Transfer using ID or GUID to identity source and/or target users

sudo /opt/rstudio-connect/bin/usermanager transfer --source-user-id 1 --target-user-guid 00000000-0000-4000-a000-000000000000
sudo /opt/rstudio-connect/bin/usermanager transfer --source-user-guid 00000000-0000-4000-a000-000000000001 --target-user-id 2

Transfer user-owned items and group memberships to another user

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane \
     --memberships

Transfer user-owned items, API keys, group memberships, content permissions and subscriptions to another user

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane \
     --memberships --permissions --api-keys

Note: Transferring API keys is not a recommended practice and it should be used only when it’s extremely difficult to replace the API key on the application consuming the Connect Server API. This is a convenience tool with security implications that should be considered. carefully. After this operation the audit logs will record that the target user, not the source user, is now the one responsible for the operations done using the transferred key.

Transfer user-owned items and content permissions and subscriptions to another user and then delete the source user

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane \
     --permissions --delete

Transfer without confirmation

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane \
     --yes

Transfer and delete source user without confirmation

sudo /opt/rstudio-connect/bin/usermanager transfer --source-username john --target-username jane \
     --delete --yes

Delete user

sudo /opt/rstudio-connect/bin/usermanager delete --username john

Delete user by ID

sudo /opt/rstudio-connect/bin/usermanager delete --user-id 1

Delete user by GUID

sudo /opt/rstudio-connect/bin/usermanager delete --user-guid 00000000-0000-4000-a000-000000000000

Delete user without confirmation

sudo /opt/rstudio-connect/bin/usermanager delete --username john --yes

Transfer group content permissions to another group

sudo /opt/rstudio-connect/bin/usermanager transfer --source-groupname john --target-groupname jane

Transfer using ID or GUID to identity source and/or target group

sudo /opt/rstudio-connect/bin/usermanager transfer --source-group-id 1 --target-group-guid 00000000-0000-4000-a000-000000000000
sudo /opt/rstudio-connect/bin/usermanager transfer --source-group-guid 00000000-0000-4000-a000-000000000001 --target-group-id 2

Transfer group content permissions and members to another group

sudo /opt/rstudio-connect/bin/usermanager transfer --source-groupname viewers --target-groupname admins \
     --memberships

Transfer group content permissions and members to another group and then delete the source group

sudo /opt/rstudio-connect/bin/usermanager transfer --source-groupname viewers --target-groupname admins \
     --memberships --delete

Transfer without confirmation

sudo /opt/rstudio-connect/bin/usermanager transfer --source-groupname viewers --target-groupname admins \
     --yes

Transfer and delete source group without confirmation

sudo /opt/rstudio-connect/bin/usermanager transfer --source-groupname viewers --target-groupname admins \
     --delete --yes

Delete group

sudo /opt/rstudio-connect/bin/usermanager delete --groupname viewers

Delete group by ID

sudo /opt/rstudio-connect/bin/usermanager delete --group-id 1

Delete group by GUID

sudo /opt/rstudio-connect/bin/usermanager delete --group-guid 00000000-0000-4000-a000-000000000000

Delete group without confirmation

sudo /opt/rstudio-connect/bin/usermanager delete --groupname viewers --yes

Dump audit logs to screen

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

Or:

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

Dump audit logs (comma-separated) to a file intended to be imported by other application:

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

Dump audit logs (comma-separated) to a file similar to Server.AuditLogFormat = CSV:

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

Dump audit logs (JSON) to a file similar to Server.AuditLogFormat = JSON:

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

Dump audit logs to screen since May 2018 (includes all entries since midnight):

sudo /opt/rstudio-connect/bin/usermanager audit --since 2018-05

Dump audit logs to screen until May 2018 (excludes all entries after midnight):

sudo /opt/rstudio-connect/bin/usermanager audit --until 2018-05

Dump audit logs to screen until Midnight, May 1st 2018:

sudo /opt/rstudio-connect/bin/usermanager audit --until 2018-05-01T00:00:00

Dump audit logs to screen since Midnight, May 1st 2018:

sudo /opt/rstudio-connect/bin/usermanager audit --since 2018-05-01T00:00:00

Dump audit logs to CSV for the entire month of May 2018:

sudo /opt/rstudio-connect/bin/usermanager audit --csvlog \
     --since 2018-05 \
     --until 2018-06

Note: --since and --until can be used for any output formats.

B.4 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.9.

B.4.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.
  • rebuild: alias for rebuild-packrat.
  • repair-content-permissions: Checks and corrects permissions and ownership for the working directories of each deployed piece of content.
  • help: Displays help

B.4.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.
  • --migration-config: The full or relative path to a Connect migration file. Defaults to /etc/rstudio-connect/rstudio-connect-migration.gcfg.

Note: The configuration path must be the first flag in a custom installation.

Flags for the migrate db command:

  • --verify: Verify migration only.
  • --drop-all: Drop all existing data in the target before migrating.
  • --yes: Migrate without asking for confirmation. Use with caution.

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.9.

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.4.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

Skipping confirmation prompt:

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

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

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

Or without confirmation prompt:

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

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

Specify a custom migration file

sudo /opt/rstudio-connect/bin/migrate --migration-config /etc/connect/mycustommigration.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