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, Posit Connect will attempt to load a second file with the suffix migration
.
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.
In older versions of Posit Connect, the rscadmin
utility was able to automatically append contents from the migration configuration file to the main configuration file. This functionality was removed as the migration file is now read-only. It is recommended that Administrators move any settings within the migration configuration file to the main configuration file at their earliest convenience. In a later release Posit Connect will fail to start if settings are present within the migration configuration file.
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
.
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:
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.
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/rscadmin encrypt-config-value
Reset the secret key signature:
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>
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.
The usermanager
utility can only be run when Connect is stopped if you use the SQLite database provider. See Stopping and Starting for information on stopping and restarting Connect. See the Database section for information on database providers.
Commands
The usermanager
utility supports the following commands:
list
: Lists users or groupsalter
: Alter a user or grouptransfer
: Transfer user owned items to another user or group relationships to another groupdelete
: Delete a user or a grouptokens
: Lists tokensdeactivate
: Deactivates tokensaudit
: Dumps audit logsalign-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
.--migration-config
: The full or relative path to a Connect migration file. Defaults to/etc/rstudio-connect/rstudio-connect-migration.gcfg
.
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 forGroupsByUniqueId
(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 areviewer
,publisher
, andadministrator
.--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 byLogging.AuditLogFormat
asJSON
), 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 formatYYYY-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.
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
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
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
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
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
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
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
--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
--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
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.
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.
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
.
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
.
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
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
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
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.
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
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:
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
--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.
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) # _
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.
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 database 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.
By default, the migrate db
command copies the data from the SQLite database into PostgreSQL, and verifies 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.
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
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.
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