Skip to content

Configuration#

This appendix documents the RStudio Connect configuration file format and enumerates the user-configurable options.

Configuration Basics#

The RStudio Connect configuration file is located at /etc/rstudio-connect/rstudio-connect.gcfg. This configuration is read at startup and controls the operation of the service.

File Format#

The RStudio Connect configuration file uses the gcfg (Go Config) format, which is derived from the Git Config format.

Here is an example of that format showing the different property types:

; Comment
[BooleanExamples]
property1 = true
property2 = false

[IntegerExamples]
Property1 = 42
Property2 = -123

[DecimalExamples]
Property1 = 3.14
Property2 = 0.217

[StringExamples]
Property1 = "simple"
Property2 = "a string with spaces"
Property3 = "escape \"quotes\" in a string like this"

[MultiStringExamples]
ListProperty = "black"
ListProperty = "blue"
ListProperty = "green"

[DurationExamples]
Property1 = 1000000000
Property2 = 500ms
Property3 = 3m

Start comments with a semi-colon (;) at the beginning of a line.

Configuration sections always begin with the name of the section bounded by square brackets. A section may appear multiple times and are additive with the last value for any property being retained. The following two configuration examples are equivalent.

[Example]
A = "alligator"
B = 2

[Example]
A = "aardvark"
C = "shining"

[Example]
A = "aardvark"
B = 2
C = "shining"

Each configuration property must be included in its appropriate section. Property and section names are interpreted case-insensitively.

Property definitions always have the form: 

Name = value
The equals sign (=) is mandatory.

Multi-value Properties#

If a property happens to to be given more than once, only the last value is retained. The "multi" properties are an exception to this rule; multiple entries are aggregated into a list.

[MultiExample]
Color = "black"
Color = "blue"

[NonMulti]
Animal = "cat"
Animal = "dog"

If Color is a multi-string property, both the "black" and "blue" values are used. If Animal is a normal string property, only the value "dog" is retained.

Property Types#

Configuration properties all have one of the following types:

string

A sequence of characters. The value is taken as all characters from the first non-whitespace character after equal sign to the last non-whitespace character before the end-of-line or start of a comment. Double-quotes (") are supported, but usually unnecessary. A literal double-quote MUST be escaped and quoted itself like QuotedValue = "J.R. \"Bob\" Dobbs". Strings containing the comment characters ; and # also need to be quoted.

encrypted-string

A potentially encrypted sequence of characters. The rules on how the value is taken from the file are the same as for the regular string type. But to generate an encrypted string one needs to enter the plain text value as-is (no quotes or escaping) in the command rscadmin configure --encrypt-config-value which will output the encrypted version of the entered value. Encrypted values are tied to the RStudio Connect installation that generated them in most cases. For convenience and backwards compatibility, plain text values are accepted. However, in this case RStudio Connect will log a message on startup saying that the value should have been encrypted. Please refer to the RSC Administrative Tool appendix for more information on using the rscadmin CLI tool.

multi-string

A property that takes multiple string values. The property name is listed with each individual input value. For example, providing Color = "black" and Color = "blue" results in two separate values. Defaults for multi-string configuration properties are not overridden when additional values are configured.

boolean

A truth value. true or false.

integer

A number.

decimal

A number with optional decimals.

duration

A value specifying a length of time. When provided as a raw number, the value is interpreted as nanoseconds. Duration values can also be specified as a sequence of decimal numbers, each with optional fraction and unit suffix, such as 300ms, 1.5h, or 1m30s.

Valid time units are ns (nanoseconds), us (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), and d (days).

Each configuration property documented in this appendix includes its description, data type, and default value.

Reloadable Properties#

Some properties are marked as "reloadable". Sending a HUP signal to the Connect process causes the on-disk configuration to be reread. The server is reconfigured with the latest values of these reloadable properties. See Stopping and Starting for details about sending a HUP signal to your Connect process.

Use a HUP signal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of RStudio Connect when changing other properties.

Configuration Migration#

Configuration migration allows RStudio Connect to proceed with updated settings after an upgrade. That's done automatically and without a need for any immediate intervention. Though it still requires your attention.

If a new version of RStudio Connect requires modifications to the configuration, a separate /etc/rstudio-connect/rstudio-connect-migration.gcfg file will be created automatically during the upgrade to a new release containing adjusted or new settings and it will have the same permissions on disk as the main configuration file.

This file will be loaded first if the service were to be restarted. It means that settings in your main configuration file will override any settings defined in the migration file but settings that only exist in the migration file will continue to be effective.

Having a separate file for migration avoids modifications to your main configuration file during an upgrade. However, the contents generated in the migration file should be moved to the main configuration file.

Note: The migration file should not be modified manually.

Moving the settings can be easily done by using the option --append-migration of the rscadmin CLI tool. Since the operation above requires some downtime (RStudio Connect has to be stopped during the process) that should be done in a time convenient for your organization.

Note: Migrated settings must be moved to the main configuration before you make any modifications to your configuration file. Ideally, all RStudio Connect settings should be in the main configuration file. If you ever need to restart RStudio Connect, take this opportunity to do this operation. Postponing the operation above over the course of multiple releases is not recommended.

Once the settings are moved to the bottom of main configuration file, they can be reorganized if desired or left alone.

Alternate paths and migration failures#

If RStudio Connect is using an alternate configuration file or path, the configuration migration will take place in a file with the same name of the one currently in use with the suffix migration. For example, if the service is started with connect --config /path/to/rsc.gcfg an attempt to migrate the settings will take place for the file /path/to/rsc-migration.gcfg.

If RStudio Connect cannot create or write to the path where the migrated configuration would be placed then the migration will happen in memory only and a warning will be issued in the logs.

A different path for the migration file can be specified by using the --migration-config option for the connect command. Multiple occurrences of this option will be ignored and the last one will be used. Again, the migration file is always loaded first.

Please refer to the CLI appendix for more information on using the connect CLI.

Server#

The Server section contains configuration properties which apply across the whole of RStudio Connect and are not appropriate for the other sections, which are generally narrower.

The properties which follow all must appear after [Server] in the configuration file.

Server Settings#

DataDir#

The directory where RStudio Connect will store its variable data.

Type: string
Default: /var/lib/rstudio-connect

TempDir#

The directory that will contain all temporary directories needed by R processes. If TMPDIR environment variable is not defined then /tmp.

Type: string
Default: $TMPDIR

LandingDir#

Specifies an optional path from which a customized landing page is served to logged-out users. See examples/landing-page for a directory containing a sample landing page.

Type: string
Default: <empty-string>

EnableSitemap#

Specifies if RStudio Connect should provide a /sitemap.xml file enumerating the publicly available apps.

Type: boolean
Default: false

JumpStartEnabled#

Enable the jump start examples for onboarding.

Type: boolean
Default: true

RVersionMatching#

Specifies how RStudio Connect attempts to match R version associated with uploaded content with the R versions available on the system. Allowed values are nearest, major-minor or exact.

Type: string (case-insensitive)
Default: nearest

RVersion#

Path to an R installation root. Multiple definitions can be used to provide multiple locations with R.

Type: multi-string
Default: unspecified

RVersionScanning#

Scan for R installations in well-known locations.

Type: boolean
Default: true

CompilationConcurrency#

The number of processes allowed by make during R and Python package installation. This setting is passed to make as the -j value. The DEFAULT_CONCURRENCY value is derived from the number of available CPUs by the following calculation: max(1, min(8, (numCPU-1)/2)).

Type: integer
Default: #DEFAULT_CONCURRENCY

SourcePackageDir#

A directory containing source bundles for packages that are unavailable on either CRAN or a public GitHub repository. Must be readable by the Applications.RunAs user.

Type: string
Default: <empty-string>

Address#

A public URL for this RStudio Connect server such as https://connect.company.com/. Must be configured to enable features such as including links to your content in emails. If you are running RStudio Connect behind a proxy, this should be set to the canonical address of the proxy. If a port number is not provided- for example, https://connect.company.com:3443/ - the standard ports of 80 for HTTP and/or 443 for HTTPS will be assumed.

Type: string
Default: <empty-string>

SenderEmail#

An email address used by RStudio Connect to send outbound email. The system will not be able to send administrative email until this setting is configured.

Type: string
Default: <empty-string>

SenderEmailDisplayName#

The display name to use when sending outbound email. This setting can be used to set a name alias for the email address defined by Server.SenderEmail

Type: string
Default: RStudio Connect

EmailFromUserAddresses#

Controls the From and Sender email message fields. When enabled, user email addresses are used as the From message field and Server.SenderEmail is the Sender field. Some mail servers may not allow your Server.SenderEmail to send messages on behalf of other addresses. When disabled, the From address of outbound messages uses the name of the sending user but the email address from Server.SenderEmail.

Type: boolean
Default: false

EmailTo#

The email address used in the To: field of emailed reports. All other recipients will be blind-carbon-copied (Bcc). Use this setting with some no-reply email address if emails sent by RStudio Connect are being flagged as spam.

Type: string
Default: <empty-string>

EmailProvider#

The type of mail delivery to be used. With SMTP mail delivery, use the [SMTP] configuration section to specify your SMTP connection settings. When none is used, if legacy email settings were previously configured in the RStudio Connect administrator interface, they will be used instead. Otherwise, all the email features will be disabled. Allowed values are none, SMTP or Sendmail.

Type: string (case-insensitive)
Default: none

EmailSubjectPrefix#

A leading subject prefix for all mail sent by RStudio Connect.

Type: string
Default: [RStudio Connect]

ViewerKiosk#

When enabled, RStudio Connect does not prompt view-only users to request elevated privileges when attempting to access restricted resources.

Type: boolean
Default: false

HideEmailAddresses#

When enabled, RStudio Connect will not expose email addresses to non-administrators in API requests or its dashboard.

Type: boolean
Default: false

MailAll#

When enabled, RStudio Connect will allow scheduled and on-demand documents to send email to all users of the system.

Type: boolean
Default: false

PublicWarning#

An HTML snippet used to inject a message into the RStudio Connect dashboard welcome pages.

Type: string
Default: <empty-string>
Reloadable: true

LoggedInWarning#

An HTML snippet used to inject a message into the RStudio Connect recent views.

Type: string
Default: <empty-string>
Reloadable: true

ContentTypeSniffing#

If disabled, sets the X-Content-Type-Options HTTP header to nosniff. When enabled, removes that header, allowing browsers to mime-sniff responses.

Type: boolean
Default: false

ServerName#

By default, RStudio Connect sets the Server HTTP header to something like RStudio Connect v1.2.3. This setting allows you to override that value.

Type: string
Default: RStudio Connect vX.Y.Z-NNNN

AccessLog#

Path to the file that RStudio Connect will use for its access logs. Disabled when empty.

Type: string
Default: /var/log/rstudio-connect.access.log

CustomHeader#

Custom HTTP header that should be added to responses from RStudio Connect in the format of key: value. The left side of the first colon in the string will become the header name; everything after the first colon will be the header value. Both will be trimmed of leading/trailing whitespace. This will always add a new header with the specified value; it will never override a header that RStudio Connect would otherwise have set. Multiple definitions can be used to provide multiple custom headers.

Type: multi-string
Default: unspecified

FrameOptionsContent#

The value for the X-Frame-Options HTTP header for all user-uploaded content (Shiny apps, RMDs, etc.). If NONE, no header will be added. Allowed values are NONE, DENY or SAMEORIGIN.

Type: string
Default: NONE

FrameOptionsDashboard#

The value for the X-Frame-Options HTTP header for the RStudio Connect dashboard and all other RStudio Connect pages. If NONE, no header will be added. Allowed values are NONE, DENY or SAMEORIGIN.

Type: string
Default: DENY

SameSite#

The value of the SameSite option present in the cookies used by RStudio Connect. If defined as an empty string, SameSite will not be present in the cookies. Allowed values are None or Lax.

Type: string
Default: None

HideVersion#

If enabled, will suppress display of the server version.

Type: boolean
Default: false

NodeName#

The name of this node. If not specified, the contents of the RSTUDIO_CONNECT_NODE_NAME environment variable or the special file /proc/sys/kernel/hostname are used, in that order.

Type: string
Default: $RSTUDIO_CONNECT_NODE_NAME

DefaultContentListView#

The default presentation style for the dashboard content list. The expanded view includes the content image and description when available. The default compact view is a denser presentation without image or description. Allowed values are compact or expanded.

Type: string (case-insensitive)
Default: compact

SharedRunAsUnixGroupEnabled#

Feature switch to allow administrators to set an explicit Applications.SharedRunAsUnixGroup rather than always defaulting to the Applications.RunAs user's primary group.

Type: boolean
Default: true

TensorFlowEnabled#

If false, support for TensorFlow APIs will be disabled.

Type: boolean
Default: true

AuditLog#

The name of the log file that audit log records will be written to. The AuditLogFormat setting must not be none for this to have an effect.

Type: string
Default: /var/log/rstudio-connect.audit.log

AuditLogFormat#

The format of the log file as CSV or JSON. Using none disables logging to a file. Allowed values are none, CSV or JSON.

Type: string (case-insensitive)
Default: none

HideViewerDocumentation#

When enabled, the Documentation menu item in the dashboard is hidden from viewers.

Type: boolean
Default: false

SMTP#

The SMTP section contains configuration properties which controls the email delivery via an SMTP server. These settings should be configured if Server.EmailProvider is set to SMTP.

The properties which follow all must appear after [SMTP] in the configuration file.

SMTP Settings#

Host#

The hostname or IP address of the SMTP server used for email delivery.

Type: string
Default: <empty-string>
Reloadable: true

Port#

The port of the SMTP server. Traditionally, the port 25 is used for unencrypted access.

Type: integer
Default: 25
Reloadable: true

SSL#

Uses SSL/TLS encryption if enabled. This is generally necessary if your SMTP server port is 465.

Type: boolean
Default: false
Reloadable: true

StartTLS#

Upgrades connection to TLS encryption if enabled. This is generally necessary if your SMTP server port is 587. The value detect uses TLS only if available. Allowed values are always, never or detect.

Type: string (case-insensitive)
Default: detect
Reloadable: true

User#

The username used to authenticate against the SMTP server. Authentication is not used if blank.

Type: string
Default: <empty-string>
Reloadable: true

Password#

The password used to authenticate against the SMTP server.

Type: encrypted-string
Default: <empty-string>
Reloadable: true

ClientAddress#

The address of the SMTP client. This value is used to identify the client to the SMTP server. The default is the value of Server.NodeName.

Type: string
Default: <empty-string>

HTTP#

The HTTP section contains configuration properties which control the ability of RStudio Connect to listen for HTTP requests. RStudio Connect must be configured to listen for either HTTP or HTTPS requests (allowing both is acceptable).

These properties must appear after [HTTP] in the configuration file.

HTTP Settings#

Listen#

RStudio Connect will listen on this network address for HTTP connections. The network address can be of the form :80 or 192.168.0.1:80. Either HTTP.Listen or HTTPS.Listen is required.

Type: string
Default: <empty-string>

NoWarning#

Disables warnings about insecure (HTTP) connections.

Type: boolean
Default: false

ForceSecure#

RStudio Connect will mark cookies secure on its unsecured connection. This option should be used when RStudio Connect is behind a secure proxy.

Type: boolean
Default: false

HTTPS#

The HTTPS section contains configuration properties which control the ability of RStudio Connect to listen for HTTPS requests. RStudio Connect must be configured to listen for either HTTP or HTTPS requests (allowing both is acceptable).

These properties must appear after [HTTPS] in the configuration file.

HTTPS Settings#

Listen#

RStudio Connect will listen on this network address for HTTPS connections. The network address can be of the form :443 or 192.168.0.1:443. Either HTTP.Listen or HTTPS.Listen is required.

Type: string
Default: <empty-string>

Key#

Path to a PEM encoded private key file corresponding to the certificate specified with HTTPS.Certificate. Required when HTTPS.Certificate is specified.

Type: string
Default: <empty-string>

Certificate#

Path to a PEM encoded TLS certificate file. If the certificate is signed by a certificate authority, the certificate file should be the concatenation of the server's certificate followed by the CA's certificate. Must be paired with HTTPS.Key.

Type: string
Default: <empty-string>

Permanent#

Advertises to all visitors that this server should only ever be hosted securely via HTTPS. WARNING: if this is set to true -- even temporarily -- visitors may be permanently denied access to your server over an unsecured (non-HTTPS) protocol. This sets the secure flag on all session cookies and adds a Strict-Transport-Security HTTP header with a value of 30 days.

Type: boolean
Default: false

MinimumTLS#

Minimum permitted TLS version. Allowed values are 1.0, 1.1, 1.2 or 1.3.

Type: string
Default: 1.0

HTTPRedirect#

The HTTPRedirect section contains configuration properties which control the ability of RStudio Connect to listen for HTTP requests and then redirect all traffic to some alternate location. This is useful when paired with an HTTPS.Listen configuration.

These properties must appear after [HTTPRedirect] in the configuration file.

HTTPRedirect Settings#

Listen#

RStudio Connect will listen on this network address for HTTP connection and redirect to either the HTTPRedirect.Target or Server.Address target location. The network address can be of the form :8080 or 192.168.0.1:8080. Useful when you wish all requests to be served over HTTPS and send users to that location should they accidentally visit via an HTTP URL. Must be paired with either HTTPRedirect.Target or Server.Address.

Type: string
Default: <empty-string>

Target#

The target for redirects when users visit the HTTPRedirect.Listen HTTP service. Server.Address is used as a redirect target if this property is not specified.

Type: string
Default: <empty-string>

Licensing#

The Licensing section contains configuration properties which control how RStudio Connect interacts with its licensing system.

These properties must appear after [Licensing] in the configuration file.

Licensing Settings#

LicenseType#

Enable local activation or remote floating licenses. Allowed values are local or remote.

Type: string (case-insensitive)
Default: local

RemoteRetryFrequency#

When RStudio Connect loses its lease, it will begin automatically attempting to acquire a lease by RemoteRetryFrequency. Use a value of 0 to disable retries.

Type: duration
Default: 10s

ExpirationEmail#

Enables sending of email when the license approaches expiration.

Type: boolean
Default: true

ExpirationUIWarning#

Enables display of a warning to administrators and publishers when the license approaches expiration.

Type: boolean
Default: true

Database#

The Database section contains configuration properties which control the location of and how RStudio Connect interacts with its database.

These properties must appear after [Database] in the configuration file.

Database Settings#

Provider#

The type of database. Allowed values are SQLite or Postgres.

Type: string (case-insensitive)
Default: SQLite

Dir#

Includes the SQLite database and other storage data, including the shared encryption key. The SQLite.Dir setting must be customized when this location is a networked file system.

Type: string
Default: {Server.DataDir}/db

MaxIdleConnections#

The maximum number of database connections that should be retained after they become idle. If this value is less-than or equal-to zero, no idle connections are retained.

Type: integer
Default: 5

MaxOpenConnections#

The maximum number of open connections to the database. If this value is less-than or equal-to zero, then there is no limit to the number of open connections.

Type: integer
Default: 10

ConnectionMaxLifetime#

The maximum amount of time a connection to the database may be reused. If this value is less-than or equal-to zero, then connections are reused forever.

Type: duration
Default: 60s

SQLite#

The SQLite section contains configuration properties which control the location of and how RStudio Connect interacts with the SQLite database.

These properties must appear after [SQLite] in the configuration file.

SQLite Settings#

Dir#

The directory containing the internal SQLite database. Must reference a directory on the local filesystem and not on a networked volume like NFS.

Type: string
Default: {Database.Dir}

Backup#

When enabled and Provider is SQLite, periodically backs up the database

Type: boolean
Default: true

BackupFrequency#

How often to back up the SQLite database

Type: duration
Default: 24h

BackupRetentionLimit#

RStudio Connect will periodically delete backups older than this number. Set to 0 to disable sweeping, for example, if you plan to manage your backups with an external task.

Type: integer
Default: 3

Postgres#

The Postgres section contains configuration properties which control the location of and how RStudio Connect interacts with its postgres.

These properties must appear after [Postgres] in the configuration file.

Postgres Settings#

URL#

The fully qualified PostgreSQL database connection URL.

Type: string
Default: <empty-string>

InstrumentationURL#

The fully qualified PostgreSQL database connection URL that contains instrumentation data.

Type: string
Default: <empty-string>

Password#

The encrypted password for the Postgres.URL.

Type: encrypted-string
Default: <empty-string>

InstrumentationPassword#

The encrypted password for the Postgres.InstrumentationURL.

Type: encrypted-string
Default: <empty-string>

Authentication#

The Authentication section contains configuration properties which control how users will log into RStudio Connect.

These properties must appear after [Authentication] in the configuration file.

Authentication Settings#

Provider#

Specifies the type of user authentication. Allowed values are password, ldap, pam, oauth2, proxy or saml.

Type: string (case-insensitive)
Default: password

Name#

Specifies a meaningful name for your authentication provider. This presented on the sign-in page and gives users context about the credentials being requested. If unspecified, RStudio Connect will use a generic name for the chosen provider. Just using your company name is often a good choice.

Type: string
Default: RStudio Connect

Lifetime#

The longest period of time that an authenticated session may be considered valid. A user will need to reauthenticate after this period of time regardless of session activity. The default 24h setting forces users to sign in at least once a day. The Authentication.Inactivity setting may invalidate idle sessions before this limit.

Type: duration
Default: 24h

Inactivity#

The period of time before an inactive session is considered idle. A user will need to reauthenticate after their session becomes idle. Has no effect when greater than Authentication.Lifetime. Disabled with a zero value.

Type: duration
Default: 8h

WarningDelay#

An activity indicator and a warning message will be displayed to the user after clicking 'Log In' if the response from the authentication provider takes longer than the configured delay. Use zero to disable this warning.

Type: duration
Default: 10s

Notice#

Text of notice displayed to the user on the login, sign up, and user completion pages. Useful for displaying notices and reminders to users about the system and the data they enter. This option is not applicable to Single Sign-On providers using SAML, OAuth2 (OpenID) or Proxied authentication.

Type: string
Default: <empty-string>

APIKeyAuth#

Whether API key authentication is enabled.

Type: boolean
Default: true

ChallengeResponseEnabled#

Whether a second factor challenge-response is enabled

Type: boolean
Default: false

CookieSweepDuration#

Duration between sweeps of expired cookies

Type: duration
Default: 1h

Password#

The Password section contains configuration properties which control how RStudio Connect's default password authentication provider behaves.

See the Password Authentication section for details about configuring password authentication for RStudio Connect.

These properties must appear after [Password] in the configuration file.

Password Settings#

MinimumScore#

Specifies the minimum strength of a new password. This must be a value between 0 and 4, with 0 allowing any password.

Type: integer
Default: 0

SelfRegistration#

Allow users to self-register. Self-registered users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

WebSudoMode#

Whether web-sudo mode is enabled. Web-sudo mode will ensure that users are prompted to re-enter their password before performing sensitive actions.

Type: boolean
Default: true

WebSudoModeDuration#

The lifetime of web-sudo mode. This is the amount of time before a user will be prompted to enter their password again when performing sensitive actions.

Type: duration
Default: 5m

OAuth2#

The OAuth2 section contains configuration properties which control how RStudio Connect communicates with OAuth2 servers in order to authenticate users.

See one of the following sections for further details about how to configure RStudio Connect with OAuth2 / OpenID Connect authentication:

These properties must appear after [OAuth2] in the configuration file.

OAuth2 Settings#

ClientId#

Identifier for OAuth2 client. Required for all OAuth2 configurations.

Type: string
Default: <empty-string>

ClientSecret#

Client secret for the configured client ID. One of OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2.

Type: encrypted-string
Default: <empty-string>

ClientSecretFile#

Path to a file containing only the client secret for the configured client ID. The file contents may be encrypted as for ClientSecret. One of OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2.

Type: string
Default: <empty-string>

AllowedDomain#

List of domains permitted to authenticate.

Type: multi-string
Default: unspecified
Reloadable: true

AllowedEmail#

List of email addresses permitted to authenticate. When used without OAuth2.AllowedDomain, only the email addresses listed here will be allowed access. When used with OAuth2.AllowedDomain, the email addresses listed here will be added to those with valid domains.

Type: multi-string
Default: unspecified
Reloadable: true

DemoteSearchErrors#

Disables logging of user search errors. Recommended only for public servers where gmail.com accounts or accounts from multiple, unrelated Google Apps domains appear.

Type: boolean
Default: false

OpenIDConnectIssuer#

The OpenID Connect issuer URL and the location of the '/.well-known/openid-configuration' discovery metadata. Google is the default issuer.

Type: string
Default: https://accounts.google.com

Logging#

Enables logging for all OAuth2 operations.

Type: boolean
Default: false

RequireUsernameClaim#

When enabled cause a failure if the username claim is not present in the authentication. By default the username claim is optional and an editable username derived from the email address without the domain will be defined upon user creation if the claim is not present.

Type: boolean
Default: false

CustomScope#

The scopes passed during authentication so that the non-standard claims can be returned. The scopes openid, profile and email are always requested. Additional scopes are included for Okta (groups) and Google (Directory).

Type: multi-string
Default: unspecified

UniqueIdClaim#

The name of the IDToken or UserInfo claim containing the value of the user unique identifier.

Type: string
Default: sub

EmailClaim#

The name of the IDToken or UserInfo claim containing the value of the user's email.

Type: string
Default: email

UsernameClaim#

The name of the IDToken or UserInfo claim containing the value of the user's username.

Type: string
Default: preferred_username

FirstNameClaim#

The name of the IDToken or UserInfo claim containing the value of the user's first name.

Type: string
Default: given_name

LastNameClaim#

The name of the IDToken or UserInfo claim containing the value of the user's first name.

Type: string
Default: family_name

RoleClaim#

The name of the IDToken or UserInfo claim containing the value of the user's role in RStudio Connect. Assumes Authorization.DefaultUserRole if not defined. It can define roles directly or via Authorization.UserRoleMapping.

Type: string
Default: <empty-string>

GroupsClaim#

The name of the IDToken or UserInfo claim containing the value of the user's groups.

Type: string
Default: groups

GroupsSeparator#

Requires a groups claim. If not empty, expects a single value representing a list of group names separated by the character(s) defined here. By default, the groups claim is expected to be a multi-value, one for each group name.

Type: string
Default: <empty-string>

GroupsAutoProvision#

Enables automatic provisioning of local groups as needed to remain in sync with auth provider specified memberships.

Type: boolean
Default: false

GroupsByUniqueId#

Indicates whether the group identifier sent by the provider during login refers to the group name or a unique identifier. Groups can only be created via the Connect Server API in the later case.

Type: boolean
Default: false

RegisterOnFirstLogin#

Allow users to be created on their first login attempt. Otherwise users must be created ahead of the first login which varies across authentication providers. Users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

LDAP#

The LDAP section contains configuration properties which control how RStudio Connect communicates with an LDAP or Active Directory (AD) server.

See one of the following sections for further details about how to configure RStudio Connect with LDAP authentication:

The LDAP section is different from many other configuration sections, as it allows multiple, distinctly named configuration instances. See Advanced LDAP / AD for more details.

Note

The list below only provide a basic description of each LDAP setting. To understand better how these configuration settings interact with each other, please see the Advanced LDAP / AD appendix.

LDAP Settings#

ServerAddress#

Specifies the location of the LDAP/AD server. This should be of the form <host>:<port>. The host may be either an IP or DNS address. Most LDAP/AD servers operate on port 389 or 636.

Type: string
Default: <empty-string>

TLS#

When enabled, all connections to your LDAP/AD server will use TLS (SSL).

Type: boolean
Default: false

StartTLS#

When enabled, the connection will initially be made on an insecure port then the channel will be upgraded to TLS using StartTLS.

Type: boolean
Default: false

ServerTLSInsecure#

This option controls if RStudio connect will verify the server's certificate chain and host name. When enabled, RStudio Connect will accept any certificate presented by the server and any host name in that certificate. Setting to true is susceptible to man-in-the-middle attacks but is required in some circumstances, such as when using a self-signed certificate.

Type: boolean
Default: false

TLSCACertificate#

Path to a PEM encoded certificate authority file used to connect an LDAP server.

Type: string
Default: <empty-string>

BindDN#

A DN for a read-only administrator account that is used during bind authentication and for certain operations that do not occur during the login sequence (such as searching). Must be paired with BindPassword.

Type: string
Default: <empty-string>

BindPassword#

The password for the BindDN account.

Type: encrypted-string
Default: <empty-string>

BindPasswordFile#

Path to a file containing only the bind password. The file contents may be encrypted as for BindPassword. Either BindPassword or BindPasswordFile may be specified when using LDAP, but if both are set, it is an error.

Type: string
Default: <empty-string>

AnonymousBind#

Enable anonymous bind. An anonymous user must have rights to search and view all pertinent groups, group memberships, and users.

Type: boolean
Default: false

UserSearchBaseDN#

The base DN used when performing user searches.

Type: string
Default: <empty-string>

UserObjectClass#

The name of the LDAP objectClass used to define users.

Type: string
Default: <empty-string>

UserFilterBase#

An LDAP filter clause used to select user objects. Defaults to objectClass={UserObjectClass}.

Type: string
Default: <empty-string>

UserFirstNameAttribute#

The LDAP user attribute containing a user's first name. This is often the givenName attribute.

Type: string
Default: <empty-string>

UserLastNameAttribute#

The LDAP user attribute containing a user's last name. The sn attribute will usually contain last name.

Type: string
Default: <empty-string>

UserEmailAttribute#

The LDAP user attribute containing a user's email address. Many systems use the mail attribute.

Type: string
Default: <empty-string>

UserRoleAttribute#

The LDAP user attribute containing a user's role in RStudio Connect. Assumes Authorization.DefaultUserRole if not defined. It can define roles directly or via Authorization.UserRoleMapping.

Type: string
Default: <empty-string>

UsernameAttribute#

The LDAP user attribute containing a user's username. Commonly used attributes include uid, cn, and sAMAccountName.

Type: string
Default: <empty-string>

UniqueIdAttribute#

The LDAP attribute with an immutable value which uniquely identifies objects. Commonly used attributes include objectGUID (Microsoft AD), entryUUID (OpenLDAP), orclGuid (Oracle OID), ibm-entryUUID (IBM RACF), GUID (Novell eDirectory), nsUniqueID (389 Directory Server). Please refer to your LDAP vendor documentation for the correct value.

Type: string
Default: DN

GroupSearchBaseDN#

The base DN used when performing group searches.

Type: string
Default: <empty-string>

GroupObjectClass#

The name of the LDAP objectClass used to define groups. Commonly this is group or posixGroup.

Type: string
Default: <empty-string>

GroupFilterBase#

An LDAP filter clause used to select group objects. Defaults to objectClass={GroupObjectClass}.

Type: string
Default: <empty-string>

GroupNameAttribute#

The LDAP group attribute containing a group's name. Commonly this is cn or sAMAccountName.

Type: string
Default: <empty-string>

GroupUniqueIdAttribute#

The LDAP attribute with an immutable value which uniquely identifies groups. In general, users and groups use the same value. Please refer to your LDAP vendor documentation for the correct value for groups.

Type: string
Default: DN

PermittedLoginGroup#

Limit who can log into RStudio Connect by specifying a group DN. Multiple definitions can be used to provide multiple groups.

Type: multi-string
Default: unspecified

GroupsAutoLookup#

Enable pre-fetching all group memberships during the user login.

Type: boolean
Default: true

CacheTTL#

Amount of time to cache LDAP group membership. Use a higher value if the content list loads slowly. Use a lower value if frequent changes to group memberships are expected.

Type: duration
Default: 15m

MembershipUpdateInterval#

Interval of time to obtain updates of group memberships for each user from LDAP in addition to the memberships obtained on login. Requires GroupsAutoLookup to be enabled.

Type: duration
Default: 4h

Logging#

Enables logging for all LDAP operations.

Type: boolean
Default: false

GroupsAutoProvision#

Enables automatic provisioning of local groups as needed to remain in sync with auth provider specified memberships.

Type: boolean
Default: false

GroupsByUniqueId#

Indicates whether the group identifier sent by the provider during login refers to the group name or a unique identifier. Groups can only be created via the Connect Server API in the later case.

Type: boolean
Default: false

WebSudoMode#

Whether web-sudo mode is enabled. Web-sudo mode will ensure that users are prompted to re-enter their password before performing sensitive actions.

Type: boolean
Default: true

WebSudoModeDuration#

The lifetime of web-sudo mode. This is the amount of time before a user will be prompted to enter their password again when performing sensitive actions.

Type: duration
Default: 5m

RegisterOnFirstLogin#

Allow users to be created on their first login attempt. Otherwise users must be created ahead of the first login which varies across authentication providers. Users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

SAML#

The SAML section contains configuration properties which control how RStudio Connect communicates with a SAML Identity Provider server.

See one of the following sections for further details about how to configure RStudio Connect with SAML authentication:

All of the SAML configuration properties must appear after [SAML] in the configuration file.

SAML Settings#

IdPMetaDataPath#

The URL to the metadata on the Identity Provider (IdP). This overrides the other IdP-related configuration properties.

Type: string
Default: <empty-string>

IdPMetaDataURL#

The file name of the metadata for the Identity Provider (IdP). This overrides the other IdP-related configuration properties.

Type: string
Default: <empty-string>

IdPEntityID#

The entity identifier (name or URI) of the Identity Provider (IdP). If a metadata with multiple entries is used, this value must be configured to select the correct IdP.

Type: string
Default: <empty-string>

IdPSingleSignOnServiceURL#

The HTTP endpoint able to receive authentication requests on the Identity Provider (IdP).

Type: string
Default: <empty-string>

IdPSigningCertificate#

The path to a PEM file of the public certificate to be used for validating the digital signature of a SAML response.

Type: string
Default: <empty-string>

IdPSingleSignOnPostBinding#

When true uses HTTP POST for authentication requests to the Identity Provider (IdP). Uses HTTP redirect otherwise.

Type: boolean
Default: false

SPEncryptionKey#

The path to a private RSA key PEM file corresponding to the encryption certificate provided to the IdP for encrypting SAML responses.

Type: string
Default: <empty-string>

SPEncryptionCertificate#

The path to a PEM file of the public certificate to be provided to the IdP for encrypting SAML responses.

Type: string
Default: <empty-string>

SPSigningKey#

The path to a private RSA key PEM file corresponding to the signing certificate provided to the IdP for signed SAML requests. If an encryption key is defined, that key will be used instead and this option will be ignored.

Type: string
Default: <empty-string>

SPSigningCertificate#

The path to a PEM file of the public certificate to be provided to the IdP for verifying the signatures of SAML request. If an encryption certificate is defined, that certificate will be used and this option will be ignored.

Type: string
Default: <empty-string>

SPRequestSigningMethod#

The method used to sign authentication requests. This option require Allowed values are sha1, sha256 or sha512.

Type: string
Default: <empty-string>

IdPAttributeProfile#

The name of an IdP attribute profile to use. If this is specified, it overrides any of the other IdP attribute name options. Allowed values are default, okta, onelogin, azure or jumpcloud.

Type: string (case-insensitive)
Default: <empty-string>

IdPAttributeProfileGroups#

Enables (true) or disables (false) group support in the specified profile; requires IdPAttributeProfile.

Type: boolean
Default: true

NameIDFormat#

The expected format for the user's NameID. This will be what RStudio Connect will request when initiating a single sign-on from the IdP. Allowed values are unspecified, transient, emailAddress or persistent.

Type: string (case-insensitive)
Default: <empty-string>

UniqueIDAttribute#

The name or URI of the SAML attribute containing the user's unique identifier. If NameIDFormat = transient the value cannot be the default of NameID.

Type: string
Default: NameID

UsernameAttribute#

The name or URI of the SAML attribute containing the username. Use NameID to refer to its value instead of an attribute.

Type: string
Default: <empty-string>

FirstNameAttribute#

The name or URI of the SAML attribute containing the user's first name.

Type: string
Default: <empty-string>

LastNameAttribute#

The name or URI of the SAML attribute containing the user's last name.

Type: string
Default: <empty-string>

EmailAttribute#

The name or URI of the SAML attribute containing the user's email address. Use NameID to refer to its value instead of an attribute.

Type: string
Default: <empty-string>

RoleAttribute#

The name or URI of the SAML attribute containing the user's role in RStudio Connect. Assumes Authorization.DefaultUserRole if not defined. It can define roles directly or via Authorization.UserRoleMapping.

Type: string
Default: <empty-string>

GroupsAttribute#

The name or URI of the SAML attribute containing the names of the groups the user belongs to.

Type: string
Default: <empty-string>

SSOInitiated#

Indicates who (IdP and/or SP) can initiate a login sequence. Allowed values are IdP, SP or IdPAndSP.

Type: string (case-insensitive)
Default: IdPAndSP

SSOFollowHTTPHeaders#

Indicates whether HTTP headers such as Host, X-RSC-Request, X-Forwarded-Host will be used to determine the SAML address for RStudio Connect instead of Server.Address.

Type: boolean
Default: false

Logging#

Enables logging for all SAML operations.

Type: boolean
Default: false

GroupsSeparator#

Requires a groups attribute to be mapped. If not empty, expects a single value representing a list of group names separated by the character(s) defined here. By default, the groups attribute is expected to be a multi-value, one for each group name.

Type: string
Default: <empty-string>

GroupsAutoProvision#

Enables automatic provisioning of local groups as needed to remain in sync with auth provider specified memberships.

Type: boolean
Default: false

GroupsByUniqueId#

Indicates whether the group identifier sent by the provider during login refers to the group name or a unique identifier. Groups can only be created via the Connect Server API in the later case.

Type: boolean
Default: false

RegisterOnFirstLogin#

Allow users to be created on their first login attempt. Otherwise users must be created ahead of the first login which varies across authentication providers. Users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

PAM#

The PAM section contains configuration properties which control how RStudio Connect interacts with the PAM (Pluggable Authentication Module) API.

See one of the following sections for further details about how to configure RStudio Connect with PAM authentication:

See the PAM Sessions section for information about using PAM sessions when launching processes.

These properties must appear after [PAM] in the configuration file.

PAM Settings#

Service#

Specifies the PAM service name that RStudio Connect will use when authenticating users.

Type: string
Default: rstudio-connect

UseSession#

Use PAM sessions when launching R processes.

Type: boolean
Default: false

SessionService#

Specifies the PAM service name that RStudio Connect will use for running R processes. This PAM service cannot require user credentials when executed by root, or all R processes run by RStudio Connect will fail yielding error code 70.

Type: string
Default: su

AuthenticatedSessionService#

Specifies the PAM service name that RStudio Connect will use for running R processes with cached user credentials. This can be used with a Kerberized PAM service if Kerberos exposes certain resources to the R process.

Type: string
Default: su

ForwardPassword#

If true, will retain the user's password when they login so that it can be provided to PAM when spawning proceses on this user's behalf. This can be used where PAM features such as Kerberos or pam_mount which require the user's password are in use.

Type: boolean
Default: false

PasswordLifetime#

The duration of time for which a password should be retained in memory. Only used if ForwardPassword is true.

Type: duration
Default: 24h

Logging#

Enables logging for all PAM operations.

Type: boolean
Default: false

WebSudoMode#

Whether web-sudo mode is enabled. Web-sudo mode will ensure that users are prompted to re-enter their password before performing sensitive actions.

Type: boolean
Default: true

WebSudoModeDuration#

The lifetime of web-sudo mode. This is the amount of time before a user will be prompted to enter their password again when performing sensitive actions.

Type: duration
Default: 5m

RegisterOnFirstLogin#

Allow users to be created on their first login attempt. Otherwise users must be created ahead of the first login which varies across authentication providers. Users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

Proxied Authentication#

The ProxyAuth section contains configuration properties which control how RStudio Connect utilizes an external authentication server which proxies all requests.

See the Proxied Authentication section for details about configuring proxied authentication with RStudio connect.

ProxyAuth Settings#

LoginURL#

The proxy URL for login. If not defined the 'Log In' and 'Log Out' links will not be visible in the Dashboard.

Type: string
Default: <empty-string>

LogoutURL#

The proxy URL for logout. If not defined the 'Log Out' link will not be visible in the Dashboard unless LoginURL is defined.

Type: string
Default: <empty-string>

UniqueIdHeader#

Specifies the name of the header that will contain a user unique identifier provided by the proxy. By using this setting the RStudio Connect Server API will require an unique_id value to create users.

Type: string
Default: <empty-string>

UsernameHeader#

Specifies the name of the header that will contain a username provided by the proxy.

Type: string
Default: X-Auth-Username

FirstNameHeader#

Specifies the name of the header that will contain the user's first name provided by the proxy.

Type: string
Default: <empty-string>

LastNameHeader#

Specifies the name of the header that will contain the user's last name provided by the proxy.

Type: string
Default: <empty-string>

EmailHeader#

Specifies the name of the header that will contain the user's email provided by the proxy.

Type: string
Default: <empty-string>

RoleHeader#

Specifies the name of the header that will contain a user role provided by the proxy.

Type: string
Default: <empty-string>

Logging#

Enables logging for all Proxy Auth operations.

Type: boolean
Default: false

GroupsHeader#

Requires Authorization.UserGroups. Specifies the name of the header that will contain the group or groups of which the authenticated user is a member.

Type: string
Default: <empty-string>

GroupsHeaderSeparator#

Requires GroupsHeader. If not empty expects a single header value representing a list of group names separated by the character(s) defined here. By default, the header in GroupsHeader is expected to be received multiple times, one for each group name.

Type: string
Default: <empty-string>

GroupsAutoProvision#

Enables automatic provisioning of local groups as needed to remain in sync with auth provider specified memberships.

Type: boolean
Default: false

GroupsByUniqueId#

Indicates whether the group identifier sent by the provider during login refers to the group name or a unique identifier. Groups can only be created via the Connect Server API in the later case.

Type: boolean
Default: false

RegisterOnFirstLogin#

Allow users to be created on their first login attempt. Otherwise users must be created ahead of the first login which varies across authentication providers. Users will be created using the role specified in the Authorization.DefaultUserRole setting.

Type: boolean
Default: true

Authorization#

The Authorization section contains configuration properties which control permissions and privileges when accessing RStudio Connect.

These properties must appear after [Authorization] in the configuration file.

Authorization Settings#

UserGroups#

Enable the group support in RStudio Connect using locally-stored groups. This option is also required for associating remote groups to RStudio Connect users. RStudio Connect will fail to start if this setting is disabled and groups exist.

Type: boolean
Default: true

UserInfoEditableBy#

Specifies who is able to modify user attributes. By default users can edit their own attributes. If Admin is specified, only administrators can edit user attributes. Allowed values are Admin or AdminAndSelf.

Type: string (case-insensitive)
Default: AdminAndSelf

DefaultUserRole#

Specifies what abilities given to a newly created user. Allowed values are publisher or viewer.

Type: string (case-insensitive)
Default: viewer

PublishersCanOwnGroups#

When disabled only administrator can own and manage groups.

Type: boolean
Default: false

PublishersCanAddUsers#

When disabled only administrator can add other users.

Type: boolean
Default: false

PublishersCanManageVanities#

When disabled only administrator can manage custom 'vanity' URLs.

Type: boolean
Default: false

ViewersCanOnlySeeThemselves#

When disabled viewers can see all users available in RStudio Connect.

Type: boolean
Default: false

ContentCredentialsUseGUID#

When enabled RStudio Connect will forward user and group GUIDs instead of their names for various content. Use this to ensure uniqueness.

Type: boolean
Default: false

ContentCredentialsUseDN#

When enabled RStudio Connect will forward user and group DNs instead of their names for various content.

Type: boolean
Default: false

UserRoleMapping#

When enabled, maps values for user role received from an authentication provider during logging to custom values. Roles without matches defined will be skipped during mapping. If disabled, received roles must match exactly viewer, publisher or administrator.

Type: boolean
Default: false

UserRoleGroupMapping#

When enabled, ignores the user role received from an authentication provider and instead uses the group names for role mapping. It cannot be used with UserRoleMapping enabled.

Type: boolean
Default: false

UserRoleMappingRestrictive#

Define the mapping behavior if multiple matches are found for a same user. By default, picks the role with more privileges. If enabled, picks the role with less privileges.

Type: boolean
Default: false

ViewerRoleMapping#

The values or group names that should map to the viewer role.

Type: multi-string
Default: unspecified

PublisherRoleMapping#

The values or group names that should map to the publisher role.

Type: multi-string
Default: unspecified

AdministratorRoleMapping#

The values or group names that should map to the administrator role.

Type: multi-string
Default: unspecified

Applications#

The Applications section contains configuration properties which control how RStudio Connect communicates with the processes associated with deployed content.

These properties must appear after [Applications] in the configuration file.

Applications Settings#

RunAs#

User used to invoke R.

Type: string
Default: rstudio-connect

RunAsCurrentUser#

Allows content to execute as the logged-in user when using PAM authentication.

Type: boolean
Default: false

SharedRunAsUnixGroup#

A Unix group used to share data between the Applications.RunAs Unix user and other customized RunAs configurations. The Applications.RunAs user must be a member of this group. The default is the primary group of the Applications.RunAs user.

Type: string
Default: <empty-string>

RConfigActive#

Specifies a value for the R_CONFIG_ACTIVE environment variable for R processes; supported by the config package.

Type: string
Default: rsconnect

Supervisor#

Specifies a command to wrap the execution of the target command.

Type: string
Default: <empty-string>

HomeMounting#

Specifies that the contents of /home should be hidden from R processes with additional bind mounts. The existing /home will have the home directory of the RunAs user mounted over it. If RunAs does not have a home directory, an empty temporary directory will mask /home instead. Launched R processes can discover this location through the the HOME environment variable.

Type: boolean
Default: false

ProhibitedEnvironment#

Environment variables that users are not allowed to override. Environment variables specified here will be added to the default set.

Type: multi-string
Default: CONNECT_SHARED_SECRET, HOME, LOGNAME, PWD, R_CONFIG_ACTIVE, RETICULATE_PYTHON, RSC_EMAIL_SUBJECT, RSC_REPORT_NAME, RSC_REPORT_RENDERING_URL, RSC_REPORT_SUBSCRIPTION_URL, RSC_REPORT_URL, TMPDIR, USER, USERNAME, VIRTUALENV, VIRTUALENV_HOME, WORKON_HOME

InitializationErrorMessage#

Text to display when interactive content encounters an initialization error.

Type: string
Default: Contact the author or review the logs for more information.

ShinyBookmarking#

Toggles support for on-disk Shiny bookmarking state. Configuring Shiny applications to use server bookmarking is described in this article.

Type: boolean
Default: true

ShinyErrorSanitization#

Toggles support for Shiny error sanitization as described in this article.

Type: boolean
Default: true

ShinyIsolation#

Specifies if a multi-Shiny R Markdown document deployment attempts to serve all documents from a single process. Disable if interactive documents expect in-process shared state.

Type: boolean
Default: true

Pandoc1Dir#

Directory containing pandoc and pandoc-citeproc binaries compatible with Pandoc 1.x. This Pandoc installation is used with rmarkdown package versions < 1.9

Type: string
Default: /opt/rstudio-connect/ext/pandoc/1.19

Pandoc2Dir#

Directory containing pandoc and pandoc-citeproc binaries compatible with Pandoc 2.x before 2.11. This Pandoc installation is used with rmarkdown package versions >= 1.9 and < 2.5.

Type: string
Default: /opt/rstudio-connect/ext/pandoc/2.9

Pandoc211Dir#

Directory containing a pandoc binary compatible with Pandoc 2.11. This Pandoc installation is used with rmarkdown package versions >= 2.5.

Type: string
Default: /opt/rstudio-connect/ext/pandoc/2.11

MostPermissiveAccessType#

The broadest access type publishers may assign to content. More permissive access types are disallowed. Applies to administrators when Applications.AdminMostPermissiveAccessType is not set. Allowed values are all, logged_in or acl.

Type: string (case-insensitive)
Default: all

AdminMostPermissiveAccessType#

The broadest access type administrators may assign to content. More permissive access types are disallowed. The Applications.MostPermissiveAccessType value applies to administrators when this property is not set. Allowed values are all, logged_in or acl.

Type: string (case-insensitive)
Default: all

MaxAppImageSize#

The maximum file size(in bytes) allowed for an application image.

Type: integer
Default: 10000000

DefaultServerEnv#

Provide a CONNECT_SERVER environment variable to all content. It will be set to the Server.Address configuration value.

Type: boolean
Default: true

DefaultAPIKeyEnv#

Provide an ephemeral CONNECT_API_KEY environment variable to all content. The API key will correspond to the content owner and will only exist during the content runtime.

Type: boolean
Default: true

RenderingSweepLimit#

The maximum number of renderings retained for any one application. When this limit is reached, the oldest renderings for an application will be removed. If this setting is not set or is less than 1, RStudio Connect will not remove renderings with respect to the number of renderings per application.

Type: integer
Default: 30

RenderingSweepAge#

The maximum age of a rendering retained for any one application. Renderings older than this setting will be removed. If this setting is not set or is of a zero value, RStudio Connect will not remove renderings with regards to its age.

Type: duration
Default: 30d

RenderingSweepFrequency#

How often should RStudio Connect look for and purge renderings.

Type: duration
Default: 1h

ViewerOnDemandReports#

Allow logged in report viewers to generate an ad-hoc rendering. The ViewerCustomizedReports property is implicitly disabled when this property is disabled.

Type: boolean
Default: false

ViewerCustomizedReports#

Allow logged in report viewers to customize the parameters of an ad-hoc rendering.

Type: boolean
Default: false

BundleReapFrequency#

Time between passes for the worker that deletes filesystem data for bundles in excess of our retention limit.

Type: duration
Default: 24h

BundleRetentionLimit#

Maximum number of bundles per app for which we want to retain filesystem data. The default is 0, which means retain everything.

Type: integer
Default: 0

PythonEnvironmentReapFrequency#

Time between passes for the worker that deletes python package environments that are no longer in use.

Type: duration
Default: 24h

ScheduleConcurrency#

Number of scheduled reports permitted to execute in parallel. A setting of zero disables scheduled execution on this host.

Type: integer
Default: 2

DisabledProtocol#

List of protocols to disable on the SockJS client. Allowed values are websocket, xhr-streaming, iframe-eventsource, iframe-htmlfile, xhr-polling, iframe-xhr-polling or jsonp-polling.

Type: multi-string (case-insensitive)
Default: xdr-streaming, xdr-polling, eventsource, htmlfile

PermissionRequest#

If disabled, users won't be able to request permissions to content they dont' have access to. Permission request notifications are delivered to the content owner and all collaborators. Notification recipient behavior can be configured with the Applications.NotificationsToOwnerOnly setting.

Type: boolean
Default: true

NotificationsToOwnerOnly#

When enabled, email notifications for permission requests and application errors will be sent to the content owner exclusively. Content collaborators will not be notified.

Type: boolean
Default: false

RuntimeSessionInitTimeout#

Maximum time to wait for rsc-session to start. With a zero value, takes the largest Scheduler.InitTimeout value.

Type: duration
Default: 0

Packages#

The Packages section contains configuration properties which alter how R packages are installed and managed. See the R Package Management section for details.

These properties must appear after [Packages] in the configuration file.

Packages Settings#

HTTPProxy#

Value to be set for the http_proxy environment variable during package installation when content is deployed. When set, this will override the http_proxy environment variable only when content is built by connect.

Type: string
Default: <empty-string>

HTTPSProxy#

Value to be set for the https_proxy environment variable during package installation when content is deployed. When set, this will override the https_proxy environment variable only when content is built by connect.

Type: string
Default: <empty-string>

External#

Package to be excluded from packrat build. This can be provided multiple times, once for each package. You will need this package available in your library path.

Type: multi-string
Default: unspecified

ExternalsCheckIsFatal#

If true, RStudio Connect will fail to start up if a package listed in Packages.External cannot be found in any of the available R versions. Change to false to make this check log a warning only.

Type: boolean
Default: true

Client#

The Client section contains configuration properties which control the behavior of browsers when interacting with applications. Interactive Shiny applications are the primary example.

These properties must appear after [Client] in the configuration file.

Client Settings#

ReconnectTimeout#

The amount of time to allow a user connection to be restored. If a zero value, reconnects will be disabled. Disabling reconnects can cause instability with the session$allowReconnects(TRUE) feature in Shiny. Note that this amount is always added to a Shiny Application Usage end time.

Type: duration
Default: 15s

Runtime/Scheduler#

The Scheduler section contains configuration properties which control how RStudio Connect manages processes for deployed applications and APIs. These properties are managed on an individual application under the Runtime tab.

RStudio Connect makes a determination on each new client connection about whether or not it needs to spawn an additional process. That computation analyzes the number of current processes and the number of active connections against those processes. If a substantial percentage of connections are consumed, RStudio Connect will create a new process rather than causing the existing processes to become more busy. That percentage of connection use is called the "load factor".

The algorithm that considers the current load factor looks like the following pseudocode.

// Given:
//   numProcesses
//     - The number of processes for the current application.
//   numConnections
//     - The number of connections across all processes associated
//       with the current application.
allowedConnections = numProcesses * Scheduler.MaxConnsPerProcess
currentLoadFactor = numConnections / allowedConnections
if currentLoadFactor > Scheduler.LoadFactor {
    // Create a new process if the new process will not exceed
    // Scheduler.MaxProcesses
}

The Scheduler.InitTimeout and Scheduler.IdleTimeout properties may need adjusting when an application takes a very long time to startup. Increasing InitTimeout will allow more time for the application to start. An increase to IdleTimeout lets associated idle processes linger longer so they are available the next time a request arrives - avoiding the startup penalty.

Worker processes are terminated when none of the following hold:

  • Active client connections to the process
  • Client connection during prior Schedule.IdleTimeout period
  • Process is needed to satisfy the LoadFactor application setting
  • Process is needed to satisfy the MinProcesses application setting

Any one of these conditions will keep a worker process alive. Consider a Shiny application configured with IdleTimeout=10m and MinProcesses=1. The process continues running if it is the only instance of that application, well beyond its configured IdleTimeout. Terminating that process would violate the MinProcesses=1 constraint.

The scheduler properties can be changed in the configuration file and apply to all applications. The RStudio Connect dashboard allows custom scheduler settings for individual applications.

We recommend that Scheduler property adjustment be done gradually.

These properties must appear after [Scheduler] in the configuration file, and apply to all types of applications.

You can also configure defaults for specific types of applications using a configuration heading of [Scheduler "<type>"], where <type> is one of the following:

  • shiny for Shiny applications
  • rmd-shiny for Shiny applications embedded in R Markdown documents
  • api for Plumber APIs
  • python-api for Python Flask APIs
  • python-dash for Python Dash apps
  • python-bokeh for Python Bokeh apps
  • python-streamlit for Python Streamlit apps
  • tensorflow-saved-model for TensorFlow model APIs

Scheduler Settings#

MaxProcesses#

Specifies the total number of concurrent processes allowed for a single application per RStudio Connect node.

Type: integer
Default: 3

MaxConnsPerProcess#

Specifies the maximum number of client connections allowed to an individual process. Incoming connections which will exceed this limit are routed to a new process or rejected.

Type: integer
Default: 20

LoadFactor#

Controls how aggressively new processes are spawned.

Type: decimal
Default: 0.5

InitTimeout#

Maximum time to wait for an app to start.

Type: duration
Default: 60s

IdleTimeout#

Minimum time a worker process remains alive after it goes idle (no active connections).

Type: duration
Default: 5s

MinProcessesLimit#

Maximum value allowed for the MinProcesses setting on an application level. All applications default to MinProcesses=0, but MinProcesses can be increased to this limit per application.

Type: integer
Default: 10

MaxProcessesLimit#

Maximum value allowed for the MaxProcesses setting on an application level. All applications take the value of MaxProcesses as default but can be individually adjusted. This setting prohibits a single application from consuming too many processes.

Type: integer
Default: 20

ConnectionTimeout#

Maximum time allowed without data sent or received across a client connection. A value of 0 means connections will never time-out (not recommended). Once a session is determined to be idle and terminated, the related usage information is marked as ended.

Type: duration
Default: 1h

ReadTimeout#

Maximum time allowed without data received from a client connection. A value of 0 means a lack of client (browser) interaction never causes the connection to close. This is useful when deploying applications which send regular updates but have no need for interactivity. Once a session is determined to be idle and terminated, the related usage information is marked as ended.

Type: duration
Default: 1h

Jobs#

The Jobs section contains configuration properties which control the retention of metadata associated with process execution.

These properties must appear after [Jobs] in the configuration file.

Jobs Settings#

MaxCompleted#

The maximum number of completed jobs preserved on disk for any one application. When this limit is reached, the oldest completed jobs for an application will be deleted as new jobs are launched. On-disk job metadata is removed if either the MaxCompleted or OldestCompleted restrictions are violated.

Type: integer
Default: 1000

OldestCompleted#

The maximum age of a completed job retained on disk. Jobs older than this setting will be deleted. Set to zero to remove restrictions on the age of a completed job. On-disk job metadata is removed if either the MaxCompleted or OldestCompleted restrictions are violated.

Type: duration
Default: 30d

Historical Information#

The Metrics section contains configuration properties which control how RStudio Connect manages the rserver-monitor process for monitoring the use of resources (CPU, memory, etc.) for historical metrics. It also controls how discrete event instrumentation is managed.

See the Historical Information section for more details about historical information in Connect.

These properties must appear after [Metrics] in the configuration file.

Metrics Settings#

Enabled#

Specifies whether or not the rserver-monitor process that collects historical metrics will be started.

Type: boolean
Default: true

User#

The user for the rserver-monitor process.

Type: string
Default: {Applications.RunAs}

DataPath#

The path for writing log entries and RRD database files.

Type: string
Default: {Server.DataDir}/metrics

Interval#

The frequency of historical metrics collection.

Type: duration
Default: 60s

RRDEnabled#

Enable logging of historical metrics to RRD.

Type: boolean
Default: true

GraphiteEnabled#

Enable logging of historical metrics to Graphite.

Type: boolean
Default: false

GraphiteHost#

Host to which to send Graphite historical metrics.

Type: string
Default: 127.0.0.1

GraphitePort#

Port to which to send Graphite historical metrics.

Type: integer
Default: 2003

GraphiteClientId#

Optional Client ID to include along with Graphite historical metrics.

Type: string
Default: <empty-string>

Instrumentation#

Enable the recording of instrumented data, such as shiny app usage by user.

Type: boolean
Default: true

InstrumentationServerHeartbeat#

Controls how often the server will update its lifetime.

Type: duration
Default: 30m

Python#

The Python section contains configuration properties pertaining to Python support for deployable content that can be optionally enabled in RStudio Connect. See the Python section for further details.

Python Settings#

Enabled#

Python feature toggle.

Type: boolean
Default: false

VersionMatching#

Specifies how RStudio Connect attempts to match Python versions associated with uploaded content with the Python versions available on the system. Allowed values are major-minor or exact.

Type: string (case-insensitive)
Default: major-minor

Executable#

Path to a Python executable. Multiple definitions can be used to provide multiple versions of Python.

Type: multi-string
Default: unspecified

ProhibitedPackage#

List of prohibited python packages.

Type: multi-string
Default: anaconda-clean, anaconda-client, anaconda-navigator, anaconda-project, appnope, appscript, bonjour-py, clyent, conda, conda-build, conda-env, conda-package-handling, conda-verify, libcxx, libcxxabi, libgfortran, menuinst, mkl-fft, mkl-random, mkl-service, msinttypes, navigator-updater, nb-anacondacloud, nb-conda, nb-conda-kernels, pywin32, pywinpty, python.app, rsconnect-jupyter, rsconnect_jupyter, rsconnect, rsconnect-python, rsp-jupyter, vc-14, vc-9, vs2008_runtime, vs2008_win-32, vs2008_win-64, vs2013_runtime, vs2015_runtime, vs2015_win-32, vs2015_win-64, vs2017_win-64, win-inet-pton, win_inet_pton, win_unicode_console, wincertstore, winkerberos, winpty, xlwings

External#

Package to be excluded from pip environment restore. This can be provided multiple times, once for each package. You will need this package available in your Python library path.

Type: multi-string
Default: unspecified

ExternalVersionMatching#

If true, RStudio Connect will require external packages to match the version requested in the uploaded content; if they do not match, the requested version will be installed in the python environment and the external package will not be used. If false, an external package will match any requested version, and content will always use the external package.

Type: boolean
Default: false

ExternalsCheckIsFatal#

If true, RStudio Connect will fail to start up if a package listed in Python.External cannot be found in any of the available Python versions. Change to false to make this check log a warning only.

Type: boolean
Default: true

MaxEnvironmentBuildDuration#

Maximum time allowed for Python packages to be installed in an environment. RStudio Connect will wait until the environment build lock file is removed by the package build process, or until this time expires, to run Python content that does not have a built package cache. You may wish to extend this time if your Python environments take a long time to rebuild.

Type: duration
Default: 30m

Git#

The Git section contains configuration properties which affect applications which are backed by git repositories.

Git Settings#

Concurrency#

Number of git operations permitted to execute in parallel

Type: integer
Default: 2

Enabled#

Git feature toggle

Type: boolean
Default: true

Executable#

Path to the git executable. Uses the git executable on the system path if not defined.

Type: string
Default: <empty-string>

PollingFrequency#

Specifies how often RStudio Connect should check git repositories for updates.

Type: duration
Default: 15m

GitCredential#

The GitCredential section contains configuration used to authenticate with remote git repositories. More than one GitCredential section is permitted:

[GitCredential "GitHub"]
Host = "github.com"
Username = "my_username"
Password = my-encrypted-password
Protocol = "https"

[GitCredential "BitBucket"]
Host = "bitbucket.org"
Username = "my_bitbucket_username"
Password = my-encrypted-password
Protocol = "https"

GitCredential Settings#

Host#

The hostname or IP address, optionally including the port, of the git server.

Type: string
Default: <empty-string>

Username#

The username to use when accessing the git server.

Type: string
Default: <empty-string>

Password#

The encrypted password (access token) to use when accessing the git server.

Type: encrypted-string
Default: <empty-string>

Protocol#

Protocol to use when accessing the git server. Allowed values are http or https.

Type: string (case-insensitive)
Default: <empty-string>

CORS#

The CORS section contains configuration used for enabling and configuring Cross-Origin Resource Sharing.

Note

CORS uses the scheme, hostname, and port when matching allowed origins. If scheme and port are omitted, we will assume http for the scheme and 80 for the port on AllowOrigin hostnames.

CORS Settings#

Enabled#

When enabled, RStudio Connect will provide CORS headers and pre-flight OPTIONS endpoints.

Type: boolean
Default: false

AllowOrigin#

The values checked during CORS handling of requests to RStudio Connect. The special value '*' may be used to allow all origins. Multiple definitions may be used to provide multiple origins.

Type: multi-string
Default: unspecified

RPackageRepository#

The RPackageRepository section lets you override the URL for an R package repository. For example, you can direct the "CRAN" repository to a private mirror that is hosted by your organization:

; /etc/rstudio-connect/rstudio-connect.gcfg
[RPackageRepository "CRAN"]
URL = "https://cran-mirror.company.com/"

This configuration forces the "CRAN" repository to your private mirror even if the R developer used a different definition for that repository when writing their code. For example, they may have been pointing at the RStudio CRAN mirror:

options(repos = c(CRAN = "https://cran.rstudio.com/"))

The RPackageRepository name must exactly match the name your developers use when configuring options("repos") in R. An RPackageRepository definition is used only when a particular piece of content references that repository name.

You can override more than one repository location with multiple RPackageRepository sections.

Let's assume that your R developers install packages from the RStudio CRAN mirror and from a package repository hosting internally developed, private packages. In R, they may have used something like:

options(
  repos = c(
    CRAN = "https://cran.rstudio.com/",
    CORPORATE = "https://corporate-packages.development.company.com"
  )
)

Your production environment contains alternate locations for both repositories. Give each repository its production location.

; /etc/rstudio-connect/rstudio-connect.gcfg
[RPackageRepository "CRAN"]
URL = "https://cran-mirror.production.company.com/"

[RPackageRepository "CORPORATE"]
URL = "https://corporate-packages.production.company.com/"

Important: Perform a full rebuild of the packrat R package cache whenever you change RPackageRepository overrides. If you skip this step, your package cache will contain packages installed from both the old and new repository URLs; your content will use packages coming from both locations.

Use the following command to rebuild the packrat cache:

/opt/rstudio-connect/bin/migrate rebuild-packrat --force

RPackageRepository Settings#

URL#

The URL that RStudio Connect should use for the given package repository

Type: string
Default: <empty-string>

Copyright © RStudio, PBC. All Rights Reserved