A Configuration Options
This appendix documents the RStudio Connect configuration file format and enumerates the user-configurable options.
A.1 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.
A.1.1 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 = 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 propertyComments always start with a semi-colon (;) or hash (#) 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 = shiningEach configuration property must be included in its appropriate section. Property and section names are interpreted case-insensitively.
Property definitions always have the form:
Name = valueThe equals sign (=) is mandatory.
A.1.2 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 = dogIf 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.
A.1.3 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 likeQuotedValue = "J.R. \"Bob\" Dobbs". Strings containing the comment characters;and#also need to be quoted.- multi-string
A property that takes multiple string values. The property name is listed with each individual input value. For example, providing
Color = blackandColor = blueresults in two separate values.- boolean
A truth value. The values
true,yes,on, and1are interpreted as true. The valuesfalse,no,off, and0are 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, or1m30s.Valid time units are
ns(nanoseconds),us(microseconds),ms(milliseconds),s(seconds),m(minutes),h(hours), andd(days).- version
A string representing a version. A version may have one to four numeric components, separated by periods or hyphens. Examples include
2,2.5,2.5.6,2.5.6.1, and2.5-6-11.
Each configuration property documented in this appendix includes its description, data type, and default value.
A.1.4 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
5.1 for details about sending a HUP signal to your
Connect process.
Use a
HUPsignal when your configuration changes are limited to properties marked as reloadable. Perform a full restart of RStudio Connect when changing other properties.
A.2 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.
A.2.1 Server Settings
A.2.1.1 DataDir
The directory where RStudio Connect will store its variable data.
Type: string
Default: /var/lib/rstudio-connect
A.2.1.2 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
A.2.1.3 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>
A.2.1.4 EnableSitemap
Specifies if RStudio Connect should provide a /sitemap.xml file enumerating the publicly available apps.
Type: boolean
Default: false
A.2.1.5 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
A.2.1.6 RVersion
Path to an R installation root. Multiple definitions can be used to provide multiple locations with R.
Type: multi-string Default: unspecified
A.2.1.7 RVersionScanning
Scan for R installations in well-known locations.
Type: boolean
Default: true
A.2.1.8 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. The value DEFAULT_CPUS is derived from the number of available CPUs with the following calculation: max(1, min(8, (numcpu-1)/2)).
Type: integer
Default: #DEFAULT_CPUS
A.2.1.9 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>
A.2.1.10 Address
A public URL for this RStudio Connect server such as https://connect.company.com/. Must be configured to enable features like including links to your content in emails.
Type: string Default: <empty-string>
A.2.1.11 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>
A.2.1.12 EmailSubjectPrefix
A leading subject prefix for all mail sent by RStudio Connect.
Type: string
Default: [RStudio Connect]
A.2.1.13 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
A.2.1.14 HideEmailAddresses
When enabled, RStudio Connect will not expose email addresses to non-administrators in API requests or its dashboard.
Type: boolean
Default: false
A.2.1.15 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
A.2.1.16 PublicWarning
An HTML snippet used to inject a message into the RStudio Connect dashboard welcome pages.
Type: string Default: <empty-string> Reloadable: true
A.2.1.17 LoggedInWarning
An HTML snippet used to inject a message into the RStudio Connect recent views.
Type: string Default: <empty-string> Reloadable: true
A.2.1.18 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
A.2.1.19 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: RStudio Connect vX.Y.Z-NNNN
A.2.1.20 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
A.2.1.21 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
A.2.1.22 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>
A.2.1.23 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.1.24 HideVersion
If true, will suppress display of the server version and build numbers.
Type: boolean
Default: false
A.2.1.25 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
A.3 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.
A.3.1 HTTP Settings
A.3.1.1 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.1.2 NoWarning
Disables warnings about insecure (HTTP) connections.
Type: boolean
Default: false
A.3.1.3 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
A.4 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.
A.4.1 HTTPS Settings
A.4.1.1 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>
A.4.1.2 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>
A.4.1.3 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>
A.4.1.4 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.1.5 MinimumTLS
Minimum TLS version supported. Valid values are 1.0, 1.1, and 1.2.
Type: string
Default: 1.1
A.4.1.6 ExcludedCiphers
List of IANA strings for ciphers to exclude. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml for a list of all known cipher strings. e.g.: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA TLS_RSA_WITH_3DES_EDE_CBC_SHA excludes DES ciphers.
Type: multi-string Default: unspecified
A.5 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.
A.5.1 HTTPRedirect Settings
A.5.1.1 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>
A.5.1.2 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.6 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.
A.6.1 Licensing Settings
A.6.1.1 LicenseType
Enable remote or local validation. local is traditional activation, whereas remote uses floating licensing.
Type: string
Default: local
A.6.1.2 RemoteRetryFrequency
When 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
A.6.1.3 ExpirationEmail
Enables sending of email when the license approaches expiration.
Type: boolean
Default: true
A.6.1.4 ExpirationUIWarning
Enables display of a warning to administrators and publishers when the license approaches expiration.
Type: boolean
Default: true
A.7 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.
A.7.1 Database Settings
A.7.1.1 Provider
The type of database. Either sqlite or postgres.
Type: string (case-insensitive)
Default: sqlite
A.7.1.2 Dir
The directory to store database support files.
Type: string
Default: {Server.DataDir}/db
A.7.1.3 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
A.7.1.4 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
A.7.1.5 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
A.8 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.
A.8.1 SQLite Settings
A.8.1.1 Dir
The directory containing the RStudio Connect database. Must reference a directory on the local filesystem and not on a networked volume like NFS.
Type: string
Default: {Database.Dir}
A.8.1.2 Backup
When enabled and Provider is sqlite, periodically backs up the database
Type: boolean
Default: true
A.8.1.3 BackupFrequency
How often to back up the SQLite database
Type: duration
Default: 24h
A.8.1.4 BackupRetentionLimit
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
A.9 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.
A.9.1 Postgres Settings
A.9.1.1 URL
The fully qualified URL to connect to a Postgres database
Type: string Default: <empty-string>
A.9.1.2 InstrumentationURL
The fully qualified URL to connect to a Postgres database where instrumentation data will be written.
Type: string Default: <empty-string>
A.10 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.
A.10.1 Authentication Settings
A.10.1.1 Provider
Specifies the type of user authentication. Allows values of password, ldap, saml, oauth2, pam, or proxy.
Type: string (case-insensitive)
Default: password
A.10.1.2 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
A.10.1.3 Lifetime
The lifetime of an authenticated session.
Type: duration
Default: 30d
A.10.1.4 Inactivity
The period of time after which inactive sessions are considered idle and therefore invalid. Effective only when non-zero and less than Authentication.Lifetime.
Type: duration
Default: 0
A.10.1.5 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.
Type: string Default: <empty-string>
A.10.1.6 APIKeyAuth
Whether API key authentication is enabled.
Type: boolean
Default: true
A.10.1.7 ChallengeResponseEnabled
Whether a second factor challenge-response is enabled
Type: boolean
Default: false
A.10.1.8 CookieSweepDuration
Duration between sweeps of expired cookies
Type: duration
Default: 1h
A.11 Password
The Password section contains configuration properties which control how RStudio
Connect’s default password authentication provider behaves.
See Section 10.5 for details about configuring password authentication for RStudio connect.
These properties must appear after [Password] in the configuration file.
A.11.1 Password Settings
A.11.1.1 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
A.11.1.2 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
A.11.1.3 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
A.12 OAuth2
The OAuth2 section contains configuration properties which control how
RStudio Connect communicates with Google OAuth2 servers in order to
authenticate users.
Section 10.8 contains more information about configuring RStudio Connect to use Google for authentication.
These properties must appear after [OAuth2] in the configuration file.
A.12.1 OAuth2 Settings
A.12.1.1 ClientId
Identifier for OAuth2 client. Required for all OAuth2 configurations.
Type: string Default: <empty-string>
A.12.1.2 ClientSecret
Client secret for the configured client ID. One of OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2.
Type: string Default: <empty-string>
A.12.1.3 ClientSecretFile
Path to file containing the client secret for the configured client ID. One of OAuth2.ClientSecret or OAuth2.ClientSecretFile must be specified when using OAuth2.
Type: string Default: <empty-string>
A.12.1.4 AllowedDomains
Space-separated list of domains permitted to authenticate.
Type: string Default: <empty-string> Reloadable: true
A.12.1.5 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> Reloadable: true
A.12.1.6 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
A.12.1.7 Logging
Enables logging for all OAuth2 operations.
Type: boolean
Default: false
A.12.1.8 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
A.13 LDAP
The LDAP section contains configuration properties which control how RStudio
Connect communicates with an LDAP or Active Directory server.
See Section 10.6 for details about how to configure RStudio Connect with LDAP authentication. Section D 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.
A.13.1 LDAP Settings
A.13.1.1 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>
A.13.1.2 TLS
When enabled, all connections to your LDAP/AD server will use TLS (SSL).
Type: boolean
Default: false
A.13.1.3 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
A.13.1.4 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
A.13.1.5 TLSCACertificate
Path to a certificate authority used to connect an LDAP server.
Type: string Default: <empty-string>
A.13.1.6 UserObjectClass
The name of the LDAP objectClass used to define users.
Type: string Default: <empty-string>
A.13.1.7 UserFilterBase
An LDAP filter clause used to select user objects. Defaults to objectClass={UserObjectClass}.
Type: string Default: <empty-string>
A.13.1.8 UserFirstNameAttribute
The LDAP user attribute containing a user’s first name. This is often the givenName attribute.
Type: string Default: <empty-string>
A.13.1.9 UserLastNameAttribute
The LDAP user attribute containing a user’s last name. The sn attribute will usually contain last name.
Type: string Default: <empty-string>
A.13.1.10 UserEmailAttribute
The LDAP user attribute containing a user’s email address. Many systems use the mail attribute.
Type: string Default: <empty-string>
A.13.1.11 UsernameAttribute
The LDAP user attribute containing a user’s username. Commonly used attributes include uid, cn, and sAMAccountName.
Type: string Default: <empty-string>
A.13.1.12 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
A.13.1.13 BindDN
A DN for a read-only administrator 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>
A.13.1.14 BindPassword
The password for the BindDN account.
Type: string Default: <empty-string>
A.13.1.15 BindPasswordFile
Path to file containing the bind password. Either BindPassword or BindPasswordFile may be specified when using LDAP, but if both are set, it is an error.
Type: string Default: <empty-string>
A.13.1.16 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
A.13.1.17 UserSearchBaseDN
The base DN used when performing user searches.
Type: string Default: <empty-string>
A.13.1.18 PermittedLoginGroup
Limit who can log into Connect by specifying a group DN. Multiple definitions can be used to provide multiple groups.
Type: multi-string Default: unspecified
A.13.1.19 GroupObjectClass
The name of the LDAP objectClass used to define groups. Commonly this is group or posixGroup.
Type: string Default: <empty-string>
A.13.1.20 GroupSearchBaseDN
The base DN used when performing group searches.
Type: string Default: <empty-string>
A.13.1.21 GroupFilterBase
An LDAP filter clause used to select group objects. Defaults to objectClass={GroupObjectClass}.
Type: string Default: <empty-string>
A.13.1.22 GroupNameAttribute
The LDAP group attribute containing a group’s name. Commonly this is cn or sAMAccountName.
Type: string Default: <empty-string>
A.13.1.23 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
A.13.1.24 Logging
Enables logging for all LDAP operations.
Type: boolean
Default: false
A.13.1.25 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
A.13.1.26 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
A.13.1.27 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
A.14 SAML (Beta)
The SAML section contains configuration properties which control how RStudio
Connect communicates with a SAML Identity Provider server.
See Section 10.7 for details about how to configure RStudio Connect with SAML authentication.
All of the SAML configuration properties must appear after [SAML]
in the configuration file.
A.14.1 SAML Settings
A.14.1.1 IdPMetaData
The URL or file name of the metadata for the Identity Provider (IdP). This overrides the other IdP-related configuration properties.
Type: string Default: <empty-string>
A.14.1.2 IdPEntityID
The entity identifier (name or URI) of the Identity Provider (IdP).
Type: string Default: <empty-string>
A.14.1.3 IdPSingleSignOnServiceURL
The HTTP endpoint able to receive authentication requests on the Identity Provider (IdP).
Type: string Default: <empty-string>
A.14.1.4 IdPSigningCertificate
The path to a PEM file or the base64-encoded body of the public certificate to be used for validating the digital signature of a SAML response.
Type: string Default: <empty-string>
A.14.1.5 IdPEncryptionCertificate
The path to a PEM file or the base64-encoded body of the public certificate to be used for decrypting a SAML response.
Type: string Default: <empty-string>
A.14.1.6 IdPSingleSignOnPostBinding
When true uses HTTP POST for authentication requests to the Identity Provider (IdP). Uses HTTP redirect otherwise.
Type: boolean
Default: false
A.14.1.7 NameIDFormat
The expected format for the user’s NameID. One of unspecified, persistent, transient or emailAddress. This will be what RStudio Connect will request when initiating a single sign-on from the IdP.
Type: string Default: <empty-string>
A.14.1.8 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
A.14.1.9 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>
A.14.1.10 FirstNameAttribute
The name or URI of the SAML attribute containing the user’s first name.
Type: string Default: <empty-string>
A.14.1.11 LastNameAttribute
The name or URI of the SAML attribute containing the user’s last name.
Type: string Default: <empty-string>
A.14.1.12 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>
A.14.1.13 SSOInitiated
Indicates who (IdP and/or SP) can initiate a login sequence. Valid values are IdP, SP, or IdPAndSP. It will default to IdPAndSP.
Type: string Default: IdPAndSP
A.14.1.14 Logging
Enables logging for all SAML operations.
Type: boolean
Default: false
A.14.1.15 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
A.15 PAM
The PAM section contains configuration properties which control how RStudio
Connect interacts with the PAM (Pluggable Authentication Module) API.
See Section 10.9 for details about configuring an appropriate PAM authentication profile for RStudio connect.
See Section 13.7 for information about using PAM sessions when launching processes.
These properties must appear after [PAM] in the configuration file.
A.15.1 PAM Settings
A.15.1.1 Service
Specifies the PAM service name that RStudio Connect will use when authenticating users.
Type: string
Default: rstudio-connect
A.15.1.2 UseSession
Use PAM sessions when launching R processes.
Type: boolean
Default: false
A.15.1.3 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 Connect will fail yielding error code 70.
Type: string
Default: su
A.15.1.4 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
A.15.1.5 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
A.15.1.6 PasswordLifetime
The duration of time for which a password should be retained in memory. Only used if ForwardPassword is true.
Type: duration
Default: 24h
A.15.1.7 Logging
Enables logging for all PAM operations.
Type: boolean
Default: false
A.15.1.8 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
A.15.1.9 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
A.15.1.10 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
A.16 Proxied Authentication
The ProxyAuth section contains configuration properties which control how
RStudio Connect utilizes an external authentication server which proxies all
requests.
See Section 10.10 for details about configuring an appropriate proxied authentication for RStudio connect.
A.16.1 ProxyAuth Settings
A.16.1.1 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>
A.16.1.2 UsernameHeader
Specifies the name of the header that will contain a username provided by the proxy.
Type: string
Default: X-Auth-Username
A.16.1.3 FirstNameHeader
Specifies the name of the header that will contain the user’s first name provided by the proxy.
Type: string Default: <empty-string>
A.16.1.4 LastNameHeader
Specifies the name of the header that will contain the user’s last name provided by the proxy.
Type: string Default: <empty-string>
A.16.1.5 EmailHeader
Specifies the name of the header that will contain the user’s email provided by the proxy.
Type: string Default: <empty-string>
A.16.1.6 RoleHeader
Specifies the name of the header that will contain a user role provided by the proxy.
Type: string Default: <empty-string>
A.16.1.7 Logging
Enables logging for all Proxy Auth operations.
Type: boolean
Default: false
A.16.1.8 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>
A.16.1.9 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>
A.16.1.10 GroupsAutoProvision
Requires GroupsHeader. Enables automatic provisioning and removal of local groups as needed to remain in sync with proxy-specified memberships.
Type: boolean
Default: false
A.16.1.11 GroupsAutoRemoval
Requires GroupsAutoProvision. When enabled provisioned groups are removed when there are no more members.
Type: boolean
Default: false
A.16.1.12 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
A.18 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.
A.18.1 Applications Settings
A.18.1.1 RunAs
User used to invoke R.
Type: string
Default: rstudio-connect
A.18.1.2 RunAsCurrentUser
Allows content to execute as the logged-in user when using PAM authentication.
Type: boolean
Default: false
A.18.1.3 RConfigActive
Specifies a value for the R_CONFIG_ACTIVE environment variable for R processes; supported by the config package.
Type: string
Default: rsconnect
A.18.1.4 Supervisor
Specifies a command to wrap the execution of R.
Type: string Default: <empty-string>
A.18.1.5 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
A.18.1.6 TempMounting
Specifies that per-process temporary directories are hidden from other R processes with additional bind mounts. If disabled, R processes may inspect or modify the temporary data of other processes.
Type: boolean
Default: true
A.18.1.7 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, RSTUDIO_PANDOC, TMPDIR, USER, USERNAME, VIRTUALENV, VIRTUALENV_HOME, WORKON_HOME
A.18.1.8 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
A.18.1.9 ShinyErrorSanitization
Toggles support for Shiny error sanitization as described in this article.
Type: boolean
Default: true
A.18.1.10 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
A.18.1.11 ExplicitPublishing
Content requires an explicit publication step after creation.
Type: boolean
Default: false
A.18.1.12 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. Allows values all, logged_in, or acl.
Type: string
Default: all
A.18.1.13 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.
Type: string
Default: all
A.18.1.14 MaxAppImageSize
The maximum file size(in bytes) allowed for an application image.
Type: integer
Default: 10000000
A.18.1.15 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, Connect will not remove renderings with respect to the number of renderings per application.
Type: integer
Default: 30
A.18.1.16 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, Connect will not remove renderings with regards to its age.
Type: duration
Default: 30d
A.18.1.17 RenderingSweepFrequency
How often should Connect look for and purge renderings.
Type: duration
Default: 1h
A.18.1.18 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
A.18.1.19 ViewerCustomizedReports
Allow logged in report viewers to customize the parameters of an ad-hoc rendering.
Type: boolean
Default: false
A.18.1.20 BundleReapFrequency
Time between the worker that deletes filesystem data for bundles in excess of our retention limit.
Type: duration
Default: 24h
A.18.1.21 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
A.18.1.22 ScheduleConcurrency
Number of scheduled reports permitted to execute in parallel. A setting of zero disables scheduled execution on this host.
Type: integer
Default: 2
A.18.1.23 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. Protocols xdr-streaming and xdr-polling are always disabled.
Type: string Default: <empty-string>
A.19 Packages
The Packages section contains configuration properties which alter how R
packages are installed and managed. See Section 17 for
details.
These properties must appear after [Packages] in the configuration file.
A.19.1 Packages Settings
A.19.1.1 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>
A.19.1.2 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>
A.19.1.3 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
A.20 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.
A.20.1 Client Settings
A.20.1.1 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
A.21 Runtime/Scheduler
The Scheduler section contains configuration properties which control how
RStudio Connect manages processes for deployed Shiny 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 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 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.IdleTimeoutperiod - Process is needed to satisfy the
LoadFactorapplication setting - Process is needed to satisfy the
MinProcessesapplication 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 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.
A.21.1 Scheduler Settings
A.21.1.1 MaxProcesses
Specifies the total number of concurrent processes allowed for a single application.
Type: integer
Default: 3
A.21.1.2 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
A.21.1.3 LoadFactor
Controls how aggressively new processes are spawned.
Type: decimal
Default: 0.5
A.21.1.4 InitTimeout
Maximum time to wait for an app to start.
Type: duration
Default: 60s
A.21.1.5 IdleTimeout
Minimum time a worker process remains alive after it goes idle (no active connections).
Type: duration
Default: 5s
A.21.1.6 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
A.21.1.7 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
A.21.1.8 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
A.21.1.9 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
A.22 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.
A.22.1 Jobs Settings
A.22.1.1 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
A.22.1.2 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
A.23 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 Section 18 for more details about historical information in Connect.
These properties must appear after [Metrics] in the configuration file.
A.23.1 Metrics Settings
A.23.1.1 Enabled
Specifies whether or not the rserver-monitor process that collects historical metrics will be started.
Type: boolean
Default: true
A.23.1.2 User
The user for the rserver-monitor process.
Type: string
Default: {Applications.RunAs}
A.23.1.3 DataPath
The path for writing log entries and RRD database files.
Type: string
Default: {Server.DataDir}/metrics
A.23.1.4 Interval
The frequency of historical metrics collection.
Type: duration
Default: 60s
A.23.1.5 RRDEnabled
Enable logging of historical metrics to RRD.
Type: boolean
Default: true
A.23.1.6 GraphiteEnabled
Enable logging of historical metrics to Graphite.
Type: boolean
Default: false
A.23.1.7 GraphiteHost
Host to which to send Graphite historical metrics.
Type: string
Default: 127.0.0.1
A.23.1.8 GraphitePort
Port to which to send Graphite historical metrics.
Type: integer
Default: 2003
A.23.1.9 GraphiteClientId
Optional Client ID to include along with Graphite historical metrics.
Type: string Default: <empty-string>
A.23.1.10 Instrumentation
Enable the recording of instrumented data, such as shiny app usage by user.
Type: boolean
Default: true
A.23.1.11 InstrumentationServerHeartbeat
Controls how often the server will update its lifetime.
Type: duration
Default: 30m
A.24 Load Balancing
The LoadBalancing section contains a configuration property that determines
whether or not clients must use a version of rsconnect with cookie-based
sticky session support.
These properties must appear after [LoadBalancing] in the configuration file.
A.24.1 LoadBalancing Settings
A.24.1.1 EnforceMinRsconnectVersion
Require a minimum version of rsconnect for cookie-based sticky session support.
Type: boolean
Default: false
A.25 Python
The Python section contains configuration properties pertaining to Python
support for deployable content that can be optionally enabled in RStudio
Connect. See section 16 for further details.
A.25.1 Python Settings
A.25.1.1 Enabled
Python feature toggle.
Type: boolean
Default: false
A.25.1.2 VersionMatching
Specifies how RStudio Connect attempts to match Python versions associated with uploaded content with the Python versions available on the system. Allows values of exact or major-minor.
Type: string
Default: major-minor
A.25.1.3 Executable
Path to a Python executable. Multiple definitions can be used to provide multiple versions of Python.
Type: multi-string Default: unspecified
A.25.1.4 ProhibitedPackage
List of prohibited python packages.
Type: multi-string
Default: anaconda-client, anaconda-project, appnope, conda-env, conda, libcxx, libcxxabi, menuinst, mkl-fft, mkl-random, msinttypes, pywin32, pywinpty, rsconnect-jupyter, rsconnect_jupyter, rsconnect, 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