A Configuration Options

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

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.

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 = off
property3 = 1

[IntegerExamples]
Property1 = 42
Property2 = -123

[DecimalExamples]
Property1 = 3.14
Property2 = 7.
Property3 = 2
Property4 = .217

[StringExamples]
Property1 = simple
Property2 = "quoted string"
Property3 = "escaped \"quote\" string"

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

[DurationExamples]
Property1 = 1000000000
Property2 = 500ms
Property3 = 1m15s  ; comment with a property

Comments always start with a semi-colon (;) and continue to the end of the line. Comments can be on lines by themselves or on a line with a property or section definition.

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 = aligator
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.

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.

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

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.

boolean

A truth value. The values true, yes, on, and 1 are interpreted as true. The values false, no, off, and 0 are interpreted as false.

integer

An integral value.

decimal

A numeric value with an optional fractional component. Values with and without a decimal point are allowed.

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), and h (hours).

A.1 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.


DataDir

The directory where RStudio Connect will store its variable data.

Type: string

Default: /var/lib/rstudio-connect

EnableSitemap

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

Type: boolean

Default: false

RVersionMatching

Specifies how RStudio Connect attempts to match R version associated with uploaded content with the R versions available on the system. Allows values of nearest or exact.

Type: string

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 amount of parallelism allowed to make during R package installs. This value is passed to make as the value given to the -jNUM flag.

Type: integer

Default: 4

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. Must be configured to enable features like including links to your content in emails.

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>

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

LoggedInWarning

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

Type: string

Default: <empty-string>

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, 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: <empty-string>

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 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 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 empty, no header will be added.

Type: string

Default: <empty-string>

FrameOptionsDashboard

The value for the X-Frame-Options HTTP header for the Connect dashboard and all other Connect pages. If empty, no header will be added.

Type: string

Default: DENY

A.2 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.


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>

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


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

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


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>

A.5 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.


Dir

The directory containing the RStudio Connect database.

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: 0

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: 0

A.6 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.


Provider

Specifies the type of user authentication. Allows values of password, oauth2, ldap, pam, or proxy.

Type: string

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: <empty-string>

A.7 OAuth2

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

Section 8.4 contains more information about configuring RStudio Connect to use Google for authentication.

The DiscoveryEndpoint property should be configured as:

[OAuth2]
DiscoveryEndpoint = https://accounts.google.com/.well-known/openid-configuration

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


DiscoveryEndpoint

Specifies a URL for the OAuth2 discovery endpoint. Required for all OAuth2 configurations.

Type: string

Default: <empty-string>

ClientId

Identifier for OAuth2 client. Required for all OAuth2 configurations.

Type: string

Default: <empty-string>

ClientSecret

Client secret for the configured client ID. Either OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2. OAuth2.ClientSecret takes priority if both properties are set.

Type: string

Default: <empty-string>

ClientSecretFile

Path to file containing the client secret. Either OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2. OAuth2.ClientSecret takes priority if both properties are set.

Type: string

Default: <empty-string>

AllowedDomains

Space-separated list of domains permitted to authenticate.

Type: string

Default: <empty-string>

AllowedEmails

Space-separated list of email addresses permitted to authenticate. When used without OAuth2.AllowedDomains, only the email addresses listed here will be allowed access. When used with OAuth2.AllowedDomains, the email addresses listed here will be added to those with valid domains.

Type: string

Default: <empty-string>

A.8 LDAP

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

See Section 8.3 for details about how to configure RStudio Connect with LDAP authentication. Section C contains many configuration examples.

The LDAP section is different from many other configuration sections, as it allows multiple, distinctly named configuration instances. This name is case sensitive. A named section looks like:

[LDAP "European LDAP Server"]

All of the LDAP configuration properties must appear after [LDAP "<name>"] in the configuration file.


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 certificate authority used to connect an LDAP server.

Type: string

Default: <empty-string>

UserObjectClass

The name of the LDAP objectClass used to define users.

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>

UsernameAttribute

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

Type: string

Default: <empty-string>

BindDN

A DN for a read-only admin account that is used during double-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: 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>

A.9 PAM

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

See Section 8.5 for details about configuring an appropriate PAM authentication profile for RStudio connect.

See Section 10.5 for information about using PAM sessions when launching R processes.

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


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 PAM sessions.

Type: string

Default: su

A.10 Proxied Authentication

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

See Section 8.6 for details about configuring an appropriate proxied authentication for RStudio connect.


UsernameHeader

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

Type: string

Default: X-Auth-Username

A.11 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.


DefaultUserRole

Specifies what abilities given to a newly created user. Allows values viewer, publisher, or administrator.

Type: string

Default: viewer

A.12 Applications

The Applications section contains configuration properties which control how RStudio Connect communicates with R processes.

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


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

Supervisor

Specifies a command to wrap the execution of R.

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

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

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 the worker that deletes filesystem data for bundles in excess of our retention limit.

Type: duration

Default: 24 hours

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

ScheduleConcurrency

Number of scheduled reports permitted to execute in parallel

Type: integer

Default: 2

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

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 will never cause the connection to close. This is useful when deploying dashboard applications which send regular updates but have no need for interactivity.

Type: duration

Default: 1h

DisabledProtocols

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

Type: string

Default: <empty-string>

A.13 Performance/Scheduler

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

RStudio Connect makes a determination on each new client connection about whether or not it needs to spawn an additional R process. That computation analyzes the number of current R 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 R processes for the current application.
//   numConnections
//     - The number of connections across all R 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 a Shiny application takes a very long time to startup. Increasing InitTimeout will allow more time for the Shiny application to start. An increase to IdleTimeout lets idle R processes linger longer so they are available the next time a request arrives - avoiding the startup penalty.

The scheduler properties can be changed in the configuration file and apply to all Shiny applictions. 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.


MaxProcesses

Specifies the total number of concurrent R processes allowed for a single application.

Type: integer

Default: 3

MaxConnsPerProcess

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

Type: integer

Default: 20

LoadFactor

Controls how aggressively new R processes will be spawned.

Type: decimal

Default: 0.5

InitTimeout

Maximum time to wait for an app to start.

Type: duration

Default: 60s

IdleTimeout

Minimum time to keep a worker process alive after it goes idle.

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: 20

A.14 Jobs

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

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


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: 100

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: 720h

A.15 Historical Metrics

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.

See Section 14 for more details about historical metrics in Connect.

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


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>