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/ and use the configuration defined in /etc/rstudio-connect/rstudio-connect.gcfg unless you specify an alternate configuration file with the --config flag.

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.

Posit Connect Administrative Tool

This utility can be used to manage your configuration information. This includes the ability to encrypt the values of sensitive settings to be used within the configuration file or configuration environment variables, as well as resetting the secret key in the event of a mismatch between the key within the database and the key on disk.

Flags

Configuration for rscadmin:

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

Note

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

Commands

The rscadmin utility supports the following commands:

• encrypt-config-value: Read a value from standard input and write it encrypted to the standard output. Must be used alone. Encryption uses the NaCl library, which in turn uses the Salsa20 cipher and Poly1305 MAC.
• reset-secret-key: Reset the secret key signature in the database allowing the use of a new encryption key file created on disk.

Examples

Encrypt a configuration value:

Note

The rscadmin tool will prompt you for the value to encrypt. Your plain-text input is encrypted before it is printed as a Base64-encoded string. You can use these encrypted, Base64-encoded values for any configuration setting that has an encrypted-string type.

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 Posit Connect is started will cause a different key to be used leading to the value being considered as if it were plain text.

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

Pipe a value to rscadmin for encryption:

echo <my_sensitive_setting> | /opt/rstudio-connect/bin/rscadmin encrypt-config-value

Reset the secret key signature:

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

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

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

Specify a custom configuration file:

sudo /opt/rstudio-connect/bin/rscadmin --config /etc/connect/mycustomconfig.gcfg reset-secret-key 

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 Posit 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 CLI can be used to transfer ownership of the entire set of one user’s content items to another user. To transfer singular content items between users, use the Posit Connect Server API.

If you are using the SQLite database provider, you must stop Connect before using the usermanager utility. The usermanager interacts directly with the SQLite database, which is not possible while Connect is running. See the Stopping and Starting section for information on stopping and restarting Connect.

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
• align-ldap-groups: Align LDAP groups to match the Remote or Local configuration specified in the config file.

Flags

Configuration for usermanager:

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

• --sort: Sorts users or groups by provided attribute, e.g. dn, uniqueid, guid, ownerguid, etc.

• --csv: Outputs listed users or groups in CSV format with no header.

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

• --normalize-ids: Update all groups’ Unique IDs to follow the provider’s setting for GroupsByUniqueId (only with --groups, all providers except LDAP).

• --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 Logging.AuditLogFormat as JSON), oldest entry first.

• --csvlog: Output entries as comma-separated values, 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.

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, sort them by their Unique ID, and output the data to a CSV file:

sudo /opt/rstudio-connect/bin/usermanager list \
    --sort uniqueid \
    --csv

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 groups’ Unique IDs to follow the GroupsByUniqueId setting:

sudo /opt/rstudio-connect/bin/usermanager alter \
    --groups \
    --normalize-ids

Note

If SAML.GroupsByUniqueId, OAuth2.GroupsByUniqueId or ProxyAuth.UniqueId are enabled this setting will cause the groups’ Unique IDs to be set to their names. Otherwise, new internal Unique IDs will be assigned randomly to all groups.

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

To prevent unexpected privilege escalation, transferred keys are demoted as needed to the least-privileged role of the source user, target user, and key. This demotion will be noted in the logs if --verbose mode is used.

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:

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

Dump audit logs (JSON) to a file similar to Logging.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.

Running align-ldap-groups

The align-ldap-groups command can be used to resolve cases where local groups and remote groups exist simultaneously in Posit Connect. A mix of local and remote LDAP groups is not supported and can cause unexpected behavior.

This tool can be used after performing a group management mode configuration change from local to remote, or remote to local.

You may have seen a warning message that looks like this:

Found 2 remote group(s) but server is configured for local groups. Learn how to transfer these groups in
the CLI Appendix to the Admin Guide.

Or this:

Found 5 local group(s) but server is configured for remote groups. Learn how to transfer these groups in
the CLI Appendix to the Admin Guide.

Posit Connect will identify the target LDAP group management mode (remote or local) based on your configuration file. If the settings for groups are correctly configured, the target mode will be remotely managed groups. If the settings for groups are omitted from the configuration, the target mode will be locally managed groups.

Note

To learn more about LDAP group settings and see configuration examples, see the Group Settings Section of the Advanced LDAP/AD Appendix.

When the group management mode is changed, Posit Connect does not automatically purge all the groups that were created prior to the update.

Use the align-ldap-groups tool to review each group that does not conform to the current target mode. For each group:

• Understand the relationships the group has to existing content items (applications, dashboards, APIs, pins, etc.) on the server.

• Evaluate the potential effect that removing or transferring the group would have on user access permissions.

To get started, enter the following command and follow the interactive prompts. To exit at any point, use Control + C:

/opt/rstudio-connect/bin/usermanager align-ldap-groups

Local to remote

Upon using the align-ldap-groups command, you will see the following options:

These local group(s) collectively have access to 2 piece(s) of content.
  [S] Show affected groups,
  [Q] Quit
# _

Selecting [S] Show affected groups the alignment process will continue to the next screen:

What do you want to do with the affected groups?
  [R] Remove all,
  [N] Remove groups with no access to content,
  [I] Decide individually,
  [Q] Quit
# _

Selecting [R] Remove all will prompt you to confirm the removal of all local groups from Posit Connect.

Selecting [N] Remove groups with no access to content will prompt you to confirm the removal of only the local groups with no access to content.

Selecting [I] Decide individually will cycle through each group with the following screen:

What do you want to do with the group "My Local Group"?
  [T] Transfer content permissions to a remote group and remove the local group from Posit Connect,
  [R] Remove the local group and all of its content permissions from Posit Connect,
  [S] Skip for now
# _

Selecting the [R] Remove ... option will prompt you to confirm the removal of this specific local group from Posit Connect.

Selecting the [T] Transfer ... option will show the next screen:

If the group you would like to transfer content memberships to has been used in Posit Connect
before, you can find its "entryUUID" attribute using the 'usermanager list -groups -base64-unique-id'. Do not include quotes.
What is the "entryUUID" attribute of the group you would like to transfer content memberships to?
(Empty entry returns to the previous screen)
(Ctrl-C aborts)
# _

Note

There could be other options other than entryUUID depending on your configuration.

After you enter a valid remote group identifier, usermanager will prompt you to confirm the staged changes:

Staged changes:

The remote group "My Remote Group" will have access to the following:
Content Relationship:
        - Local-managed App (viewer) https://localhost/connect/#/apps/149369af-d8be-4ae4-b4ee-9998f393bff2
        - Remote-managed App (viewer) https://localhost/connect/#/apps/40066041-9bf3-4c89-872e-6fdfab5e7b0e

The local group "My Local Group" will be removed afterwards.
Confirm changes?
  [Y] Yes,
  [N] No
# _

Selecting [Y] Yes will execute the changes, while selecting [N] No will return you to the initial prompt.

Remote to local

Upon using the align-ldap-groups command, you will see the following options:

These remote group(s) collectively have access to 2 piece(s) of content.
  [S] Show affected groups,
  [Q] Quit
# _

Selecting [S] Show affected groups the alignment process will continue to the next screen:

What do you want to do with the affected groups?
  [R] Remove all,
  [N] Remove groups with no access to content,
  [I] Decide individually,
  [Q] Quit
# _

Selecting [R] Remove all will prompt you to confirm the removal of all remote groups from Posit Connect.

Selecting [N] Remove groups with no access to content will prompt you to confirm the removal of only the remote groups with no access to content from Posit Connect.

Selecting [I] Decide individually will cycle through each group with the following screen:

What do you want to do with the group "My Remote Group"?
  [T] Transfer content permissions and members to a local group and remove the remote group from Posit Connect,
  [R] Remove the remote group and all of its content permissions from Posit Connect,
  [S] Skip for now
# _

Selecting the [R] Remove ... option will prompt you to confirm the removal of this specific remote group from Posit Connect.

Selecting the [T] Transfer ... option will show the next screen:

You can list available groups to transfer content and users to by using the 'usermanager list -groups' command. Only groups created locally are supported.
What is the name of the group you would like to transfer content memberships to?
(Ctrl-C aborts)
# _

After you enter a valid local group name, usermanager will prompt you to confirm the staged changes:

Staged changes:

The local group "My Local Group" will have access to the following:
Content Relationship:
        - Remote-managed App (viewer) https://localhost/connect/#/apps/40066041-9bf3-4c89-872e-6fdfab5e7b0e
        - Local-managed App (viewer) https://localhost/connect/#/apps/149369af-d8be-4ae4-b4ee-9998f393bff2

The remote group "My Remote Group" will be removed afterwards.
Confirm changes?
  [Y] Yes,
  [N] No
# _

Selecting [Y] Yes executes the changes, while selecting [N] No will return you to the initial prompt.

Database Migration

The migrate db utility transfers Connect information from SQLite to PostgreSQL. Use the database migration workflow for this transition.

Tip

The Server Migrations section contains related workflows.

The migrate db command requires root or sudo privileges to read the Connect configuration and connect to the SQLite database.

In most environments, you can run migrate db without any additional arguments:

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

This command copies data from the SQLite core and instrumentation databases into PostgreSQL, and verifies the migration. PostgreSQL connection settings must be added to your Connect configuration before performing the migration. Details about the migration are written into a migration-*.log file created in your working directory.

Connect must be stopped while the data transfer and verification is occurring.

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.

Alternate configuration

Use the -config option when your Posit Connect configuration is not at the default /etc/rstudio-connect/rstudio-connect.gcfg location.

sudo /opt/rstudio-connect/bin/migrate \
    -config /custom/location/rstudio-connect.gcfg \
    db

Only migrate one SQLite database

Use the -data argument to the migrate db command in order to specify which database you would like to migrate. By default the data argument is set to all and will migrate both the core and instrumentation databases.

To migrate only the core database:

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

To migrate only the instrumentation database:

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

Drop previous migration

Use the -drop-all option when you want to remove existing information in the target PostgreSQL database. Unless some previous migration attempts was unsuccessful, your PostgreSQL database should always start empty.

Warning

Double-check that your Connect configuration references the correct target PostgreSQL database before using -drop-all. This option is destructive, and will delete all the Connect data in the target database.

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

Suppress confirmation

By default, the migrate db asks for confirmation before making any changes. Use the -yes option to suppress this confirmation prompt.

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

Content permissions check

The migrate repair command scans the Connect-managed directories containing deployed content and adjusts their ownership and permissions according to the Applications.RunAs, Applications.SharedRunAsUnixGroup, and content-specific overrides.

Use this command if the location of the Connect variable data has changed. Connect performs the same permissions checks at startup.

When Connect is using SQLite as its database provider, the Connect service must be stopped when using migrate repair.

The migrate repair command requires root or sudo privileges to read the Connect configuration and adjust file ownership and permissions.

In most environments, you can run migrate repair without any additional arguments:

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

Alternate configuration

Use the -config option when your Posit Connect configuration is not at the default /etc/rstudio-connect/rstudio-connect.gcfg location.

sudo /opt/rstudio-connect/bin/migrate \
    -config /custom/location/rstudio-connect.gcfg \
    repair