B Command-Line Interface
Connect includes tools with a command-line interface (CLI). These tools are typically targeted towards actions that might be performed when the web server is offline or is otherwise inaccessible. Other CLI commands are useful for performing actions against the server in a batch or scripted fashion.
These utilities are installed in /opt/rstudio-connect/bin/
. They use the configuration defined in /etc/rstudio-connect/rstudio-connect.gcfg
unless you specify an alternate configuration file with the --config
flag.
B.1 User Management
This utility helps you list users and modify user roles. This can be used to recover if you are unable to access an RStudio Connect administrative account.
Connect’s usermanager
CLI also includes the ability to dump audit logs. By default, the logs are displayed in a formatted table, but you can also choose to output comma-separated values for easy analysis in other tools.
The usermanager
utility can only be run when Connect is stopped if you use the SQLite database provider. See Section 5.1 for information on stopping and restarting Connect. See Section 9 for information on database providers.
B.1.1 Commands
The usermanager
utility supports the following commands:
list
: Lists usersalter
: Changes a user’s roletokens
: Lists tokensdeactivate
: Deactivates tokensaudit
: Dumps audit logs
B.1.2 Flags
Configuration for usermanager
:
--config
: The full or relative path to a Connect configuration file (.gcfg
). Defaults to/etc/rstudio-connect/rstudio-connect.gcfg
.
Flags for the list
command:
--include-locked
: Includes locked user accounts in the list.
Flags for the alter
command:
--username
: Specifies the user name of the user to alter.--new-role
: Specifies the role to set for the user. Allowed roles areviewer
,publisher
, andadministrator
.--new-username
: Specifies the new username for the user.--new-last-name
: Specifies the new last name for the user.--new-first-name
: Specifies the new first name for the user.--new-email
: Specifies the new email address for the user.--new-dn
: Specifies the new DN for the LDAP user.--force
: Force demotion of the last remaining administrator.
Flags for the token
command:
--active
: Show only active tokens.
Flags for the deactivate
command:
--all
: Deactivate all tokens.
Flags for the audit
command:
--csv
: Output comma-separated values.
B.1.3 Examples:
Display help:
./bin/usermanager help
List unlocked users:
sudo ./bin/usermanager list
List all users (locked and unlocked):
sudo ./bin/usermanager list --include-locked
Specify a custom configuration file
sudo ./bin/usermanager --config /etc/connect/mycustomconfig.gcfg list
Promote the user john
to an administrator role
sudo ./bin/usermanager alter --username john --new-role administrator
Demote the last remaining administrator to a non-administrative role
sudo ./bin/usermanager alter --username admin --new-role publisher --force
Change a user’s DN:
sudo ./bin/usermanager alter --username john \
--new-dn="CN=John Johnson,OU=Users,DC=example,DC=com"
Dump audit logs to screen
sudo ./bin/usermanager audit
Dump audit logs (comma-separated) to a file:
sudo ./bin/usermanager audit --csv > ~/audits.txt
B.2 Migration Utility
The migration
utility assists system administrators in migrating from one database to another or in transitioning RStudio Connect to a new server. For a high-level overview of the steps necessary to migrate from SQLite to Postgres, see the section on changing database providers. For the high-level steps involved in completing a server migration, see 4.8.
B.2.1 Commands
The migrate
utility supports four commands
db
: Migrate data between databasesrebuild-packrat
: Rebuilds the Packrat cache for all content on the server. This command can be used WHILE RStudio Connect is running.repair-content-permissions
: Checks and corrects permissions and ownership for the working directories of each deployed piece of content.help
: Displays help
B.2.2 Flags
Configuration for migrate
:
--config
: The full or relative path to a Connect configuration file (.gcfg
). Defaults to/etc/rstudio-connect/rstudio-connect.gcfg
.
Flags for the migrate db
command:
--verify
: Verify migration only.--drop-all
: Drop all existing data in the target before migrating.
By default, the migrate db
command will copy the data from the SQLite database into PostgreSQL, and verify the migration. We assume that the PostgreSQL destination does not contain any data unless the --drop-all
flag is included.
Data migration copies data from the SQLite database to the PostgreSQL database. Data in the SQLite database remains after the migration; it is not removed. A verification step runs after the data copy completes and confirms the integrity of the migration:
- Row counts for all tables are verified.
- Each record is checked for the correct values.
Data verification will fail if Connect is started prior to the completion of data verification. Please ensure that Connect remains down until the data migration and verification are complete.
Flags for the rebuild-packrat
command:
-force
: Delete the Packrat cache before rebuilding-fast-fail
: Stop when the packages for a single application cannot be installed.
Proactively rebuilds the Packrat cache for all applications on the server. When the -force
flag is used, the entire existing Packrat cache directory will be deleted first. This command can be used for instances in which the Packrat cache may be incomplete for the current environment. For example, if the system only has one version of R installed and it has been upgraded, the cache will not include packages built on the appropriate version of R. Similarly, if you migrate your RStudio Connect installation to a different server which might have different versions of system libraries, you should delete the cache and rebuild it as discussed in 4.8.
When the -fast-fail
flag is used, rebuilding the Packrat package cache is halted when the packages for any application cannot be installed or verified as installed.
Flags for the repair-content-permissions
command:
No flags supported.
Scans for issues with the permissions and ownership of application directories on the server. This command can be used if you have moved some data on disk and need to confirm that the attributes were transferred properly.
B.2.3 Examples
Display help:
/opt/rstudio-connect/bin/migrate help
Migrate SQLite data to an empty PostgreSQL database:
sudo /opt/rstudio-connect/bin/migrate db
Migrate SQLite data to a PostgreSQL database, first dropping all data in the PostgreSQL database:
sudo /opt/rstudio-connect/bin/migrate db --drop-all
Perform data verification only:
sudo /opt/rstudio-connect/bin/migrate db --verify
Specify a custom configuration file:
sudo /opt/rstudio-connect/bin/migrate --config /etc/connect/mycustomconfig.gcfg db
Delete the existing Packrat cache and rebuild it by pro-actively rebuilding each application’s library.
sudo /opt/rstudio-connect/bin/migrate rebuild-packrat --force
Check and fix any disk permission errors for applications’ working directories.
sudo /opt/rstudio-connect/bin/migrate repair-content-permissions