Configuration

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

Configuration Basics

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

[ByteSizeExamples]
Memory1 = 5 MB
Memory2 = 5 KiB
Memory3 = 42

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 quoting (") of strings is recommended. A literal double quote MUST itself be quoted and escaped like QuotedValue = "J.R. \"Bob\" Dobbs".

Strings containing the comment characters ; and # MUST be quoted.

A literal backslash MUST be quoted and escaped like SlashValue = "first\\second".

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 encrypt-config-value which outputs the encrypted version of the entered value. Encrypted values are tied to the Posit Connect installation that generated them in most cases. For convenience and backwards compatibility, plain text values are accepted. However, in this case Connect logs a message on startup saying that the value should have been encrypted. Please refer to the Posit 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).

byte-size

A value specifying a number of bytes. Raw numbers are interpreted as bytes. Units can also be specified, using abbreviations for decimal or binary prefixes, such as 5 MB, 0.5 GiB, or 1 KB. Units above exabytes/exbibytes are not recognized.

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.

Tip

Use a HUP signal when your configuration changes only modify the values of properties marked as reloadable. Perform a full restart of Posit Connect for other configuration changes.

Environment Variables

Configuration settings can be set by environment variables on the Posit Connect process. You can use environment variables to augment the configuration in your /etc/rstudio-connect/rstudio-connect.gcfg file.

Environment variables with the prefix CONNECT_ are automatically associated to configuration settings based on configuration section, its (optional) name, and the property name. These CONNECT_ environment variables are not visible to subprocesses or to content.

Environment variables take precedence over settings in the configuration file, and command-line arguments (where present) take precedence over environment variables.

This example uses environment variables to set Server.Address and Authorization.DefaultUserRole:

CONNECT_SERVER_ADDRESS=http://connect.company.com/
CONNECT_AUTHORIZATION_DEFAULTUSERROLE=publisher

These environment variables are equivalent to the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Server]
Address = "http://connect.company.com/

[Authorization]
DefaultUserRole = "publisher"

Environment variables can be used to set configuration settings with named sections. This example uses an environment variable to set the GitCredential.Protocol property for the GitHub remote.

CONNECT_GITCREDENTIAL_GitHub_PROTOCOL=https

This environment variable setting corresponds to the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[GitCredential "GitHub"]
Protocol = "https"

Section names (like GitHub above) should not contain whitespace, as such values are difficult to set via environment variable. Instead, we recommend using snake_case or kebab-case for section names.

Multi-valued properties can be set by environment variables with a comma (“,”) to separate values. Values from environment variables for multi-value properties are added to existing defaults or other configuration values. This example uses an environment variable to provide two R.Executable locations:

CONNECT_R_EXECUTABLE=/opt/R/4.1.0/bin/R,/opt/R/4.0.1/bin/R

This environment variable setting corresponds to the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[R]
Executable = "/opt/R/4.1.0/bin/R"
Executable = "/opt/R/4.0.1/bin/R"

Server

The Server section contains configuration properties which apply across the whole of Posit 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 Posit Connect will store its variable data. This filesystem needs to be mounted with the exec option.

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

`TempDir`

The directory that will contain all temporary directories needed by R processes. If the TMPDIR environment variable is not defined then /tmp. This filesystem needs to be mounted with the exec option.

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>

`Robots`

An absolute file path for Connect to use as the robots.txt file served from /robots.txt. The default robots.txt disallows all indexing from all user agents.

Type: string
Default: /opt/rstudio-connect/assets/robots.txt
Reloadable: true

`EnableSitemap`

Specifies if Posit 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

`CompilationConcurrency`

The number of processes allowed by make during R and Python package installation. This setting is passed to make as the -j value. High values may encounter memory capacity issues on lightweight hosts.

Type: integer
Default: 1

`Address`

A public URL for this Posit 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 Posit 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>

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

`SenderEmail`

An email address used by Posit 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 used by Posit Connect when sending administrative email from Server.SenderEmail.

Type: string
Default: Posit Connect
Reloadable: true

`EmailFromUserAddresses`

Controls the From and Sender fields of emailed reports. If enabled, uses the content owner’s email as the From address, and Server.SenderEmail as the Sender address. By default, uses Server.SenderEmail as the From address, and content owner’s name as the display name. Note: Some mail servers may not allow your Server.SenderEmail to send messages on behalf of other addresses.

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 Posit Connect are being flagged as spam.

Type: string
Default: <empty-string>

`EmailSubjectPrefix`

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

Type: string
Default: [Posit Connect]

`HideEmailAddresses`

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

Type: boolean
Default: false
Reloadable: true

`MailAll`

When enabled, Posit Connect will allow scheduled and on-demand documents to send email to all users of the system. If disabled, turns off emailing all users for existing schedules. Subsequently enabling the setting will not restore these schedule preferences. Any schedule changes made in this manner will appear in the audit logs.

Type: boolean
Default: false

`ViewerKiosk`

Deprecated

This setting is deprecated and will be removed in an upcoming release. Use Authorization.ViewersCanRequestPrivileges instead.

When enabled, users with viewer role will not be allowed to submit permission requests for content access or to request elevated role privileges.

Type: boolean
Default: false

`PublicWarning`

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

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

`LoggedInWarning`

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

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

`DeprecatedSettingsUIWarning`

Enables display of a warning to administrators when deprecated settings are in use.

Type: boolean
Default: true

`DashboardPath`

The URL path name to be used where Posit Connect’s dashboard is hosted. This must be only the path and it must not include any proxy prefix. Valid path examples, /company-work and /my-company/work.

Type: string
Default: /connect

`RootRedirect`

The URL users will be redirected to when visiting the base URL.

Type: string
Default: {Server.DashboardPath}

`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, Posit Connect sets the Server HTTP header to something like Posit Connect v1.2.3. This setting allows you to override that value.

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

`CustomHeader`

Custom HTTP header that should be added to responses from Posit 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 Posit 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. 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 Posit Connect dashboard and all other Posit 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 Posit 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

`URLNormalizationRedirects`

If enabled, will redirect when HTTP request paths need normalization. Otherwise, paths are rewritten in-place.

Type: boolean
Default: true

`HideVersion`

If enabled, will suppress display of the server version.

Type: boolean
Default: false

`ProxyHeaderLogging`

If enabled, Connect will log incoming request headers like X-RSC-REQUEST and X-FORWARDED-* which can be used to help debug proxy configurations. This configuration produces a lot of logs and should be disabled once debugging is complete.

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

`PreventDuplicateTasks`

Prevent duplicate tasks from being added to the queue.

Type: boolean
Default: true

`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

`HideViewerDocumentation`

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

Type: boolean
Default: false

`SelfTestOnStartup`

Deprecated

This setting is deprecated and will be removed in an upcoming release. Use Server.SystemCheckOnStartup instead.

Run system checks on Connect startup.

Type: boolean
Default: false

`SelfTestFrequency`

Deprecated

This setting is deprecated and will be removed in an upcoming release. Use Server.SystemCheckFrequency instead.

How often should Posit Connect run its internal system checks. Use a value of 0 to disable periodic system checks.

Type: duration
Default: 0

`SystemCheckOnStartup`

Run system checks on Connect startup.

Type: boolean
Default: false

`SystemCheckFrequency`

How often should Posit Connect run its internal system checks. Use a value of 0 to disable periodic system checks.

Type: duration
Default: 0

`UseFIPSEncryption`

When enabled, built-in encryption will use the AES-256-GCM algorithm approved by FIPS-140 instead of the default Salsa20/Poly1305.

Type: boolean
Default: false

`AllowRuntimeCacheManagement`

Allow administrators to list and delete runtime caches via the API.

Type: boolean
Default: true

`TrustedRedirect`

Domains where Connect can redirect requests, i.e. if an app is embedded into a third-party website and needs to authenticate. Multiple definitions can be used to provide multiple domains.

Type: multi-string
Default: unspecified

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 Posit Connect to listen for HTTP requests. 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`

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

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

Type: boolean
Default: false

HTTPS

The HTTPS section contains configuration properties which control the ability of Posit Connect to listen for HTTPS requests. 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`

Posit 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 the max-age directive set to a default value of 30 days. To use a different value set HTTPS.StrictTransportSecurityMaxAge.

Type: boolean
Default: false

`StrictTransportSecurityMaxAge`

The amount of time, in seconds, to use for max-age. This setting is only used when either HTTPS.Permanent or HTTP.ForceSecure are enabled.

Type: duration
Default: 2592000s

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

Posit 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 Posit Connect interacts with its licensing system. The License Management page explains how to activate your product license.

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 Posit 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 to administrators when the license approaches expiration.

Type: boolean
Default: true

`ExpirationUIWarning`

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

Type: boolean
Default: true

`EndOfSupportUIWarning`

Enables display of a dashboard warning to administrators when the Connect product version support window ends. See the Posit Support Agreement for timelines. Has no effect when Server.HideVersion is enabled.

Type: boolean
Default: true

`StrictUsersEnforcement`

Enforce the user limit as specified by the license. Suppresses any additional allowance.

Type: boolean
Default: false

Database

The Database section contains configuration properties which control the location of and how Posit 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 Posit Connect interacts with its 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`

Posit 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 Posit Connect interacts with its PostgreSQL database.

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 Posit 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, Posit Connect will use a generic name for the chosen provider. Just using your company name is often a good choice.

Type: string
Default: Posit 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

`MirroredLDAPServers`

Specifies if LDAP servers can be considered mirrors of each other (having the exact same users and groups). This setting helps LDAP search performance when there is more than one LDAP server configured. Disable this setting when LDAP servers contain partitioned data and complement, rather than mirror, each other.

Type: boolean
Default: true

Password

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

See the Password Authentication section for details about configuring password authentication for Posit 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 Posit Connect communicates with OAuth2 servers in order to authenticate users.

See one of the following sections for further details about how to configure Posit 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 last name.

Type: string
Default: family_name

`RoleClaim`

The name of the IDToken or UserInfo claim containing the value of the user’s role that maps to roles configured in Posit 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. GroupsSeparator is ignored when groups claim is a valid JSON. 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 Posit Connect communicates with an LDAP or Active Directory (AD) server.

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

Active Directory (on-premise)
- With service credentials
- Without service credentials
LDAP:
- With service credentials
- Without service credentials

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 Posit Connect will verify the server’s certificate chain and host name. When enabled, Posit 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 value that maps to roles configured in Posit Connect. Roles are assigned when users log in. If not defined, the first user to log in will be an administrator and every subsequent user will be Authorization.DefaultUserRole. Administrators can then manually upgrade roles. The value of the attribute from LDAP is matched against either the defaults of viewer, publisher or administrator. Or, if Authorization.UserRoleMapping is enabled, it is matched against custom mappings defined by Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping and Authorization.AdministratorRoleMapping. If the value does not match any of the roles, existing users retain their current role and new users receive the Authorization.DefaultUserRole role.

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 Posit 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. When GroupsAutoProvision is enabled, user groups not yet known by Connect will be provisioned.

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`

Type: boolean
Default: true

SAML

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

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

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

`SAML` Settings

`IdPMetaDataPath`

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

Type: string
Default: <empty-string>

`IdPMetaDataURL`

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

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 Posit 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 value that maps to roles configured in Posit Connect. Assumes Authorization.DefaultUserRole if not defined. It can define roles directly or via Authorization.UserRoleMapping. If the value does not match any of the roles, existing users retain their current role and new users receive the Authorization.DefaultUserRole role.

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 Posit Connect instead of Server.Address.

Type: boolean
Default: false

`Logging`

Enables debug 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`

Type: boolean
Default: true

PAM

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

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

Kerberos
PAM

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 Posit Connect will use when authenticating users.

Type: string
Default: rstudio-connect

`UseSession`

Use PAM sessions when launching R processes. Ignored when Launcher.Kubernetes is enabled.

Type: boolean
Default: false

`SessionService`

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

Type: string
Default: su

`AuthenticatedSessionService`

Specifies the PAM service name that Posit 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. Ignored when Launcher.Kubernetes is enabled.

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

Type: boolean
Default: true

Proxied Authentication

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

See the Proxied Authentication section for details about configuring proxied authentication with Posit 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 Posit 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`

Type: boolean
Default: true

Authorization

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

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

`Authorization` Settings

`UserGroups`

Enable the group support in Posit Connect using locally-stored groups. This option is also required for associating remote groups to Posit Connect users. Posit 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 administrators can own and manage groups.

Type: boolean
Default: false

`PublishersCanAddUsers`

When disabled, only administrators can register additional users. Has no effect when using the built-in password authentication provider and Password.SelfRegistration is enabled.

Type: boolean
Default: false

`PublishersCanManageVanities`

When disabled, only administrators can manage custom ‘vanity’ URLs.

Type: boolean
Default: true

`ViewersCanOnlySeeThemselves`

When disabled, viewers can see all users available in Posit Connect.

Type: boolean
Default: false

`ContentCredentialsUseGUID`

When enabled, Posit 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, Posit 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

`ViewersCanRequestPrivileges`

When disabled, users with the viewer role cannot submit permission requests for content access or for elevated role privileges.

Type: boolean
Default: true

Applications

The Applications section contains configuration properties which control how Posit 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`

When enabled, content may be configured to execute as the logged-in user. See the Process management section for additional details. Available only when using PAM authentication. Ignored when Launcher.Kubernetes is enabled.

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: rstudio-connect

`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. Ignored when Launcher.Kubernetes is enabled.

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_CONTENT_SESSION_TOKEN, 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_PRODUCT, 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.

`InheritSystemEnvVars`

Indicates whether system environment variables are inherited by content processes. PATH is always inherited. No environment variables are inherited when Connect is configured to use off-host execution mode.

Type: boolean
Default: true

`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.16

`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 size allowed for custom content thumbnail images.

Type: byte-size
Default: 10 MB

`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. Disabled when API key authentication is prohibited (via Authentication.APIKeyAuth.

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, Posit 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, Posit Connect will not remove renderings with regards to its age.

Type: duration
Default: 30d

`RenderingSweepFrequency`

How often should Posit 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

`PythonEnvironmentReaping`

Enable the periodic cleanup of unused Python environments.

Type: boolean
Default: false

`PythonEnvironmentReapFrequency`

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

Type: duration
Default: 24h

`PackageAuditingEnabled`

Enable package auditing features.

Type: boolean
Default: true

`PackageMigrationBatchSize`

The number of packages to migrate in a single batch.

Type: integer
Default: 100

`PackageMigrationBatchInterval`

The time between package migration batches.

Type: duration
Default: 1s

`PackageMigrationRetryEnabled`

Retry failed package migrations at Connect startup.

Type: boolean
Default: false

`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, eventsource, iframe-eventsource, iframe-htmlfile, xhr-polling, iframe-xhr-polling or jsonp-polling.

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

`PermissionRequest`

If disabled, users won’t be able to request permissions to content they don’t have access to. This will also disable the Request Access button on the dashboard. 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

`DefaultImageSelectionEnabled`

When enabled, publishers can select a default image for content build/execution by setting default_image_name using the v1/content api. The content’s default_image_name is used when environment.image is not set in the bundle’s manifest.json.

Type: boolean
Default: true

`ManifestImageSelectionEnabled`

When enabled, publishers can select a target image for content build/execution by setting environment.image in the bundle’s manifest.json.

Type: boolean
Default: true

`ManifestEnvironmentManagementSelection`

When enabled, publishers can select the environment management strategy for individual content items by setting environment.environment_management.r or environment.environment_management.python in the manifest, overriding the system defaults given by R.EnvironmentManagement and Python.EnvironmentManagement.

Type: boolean
Default: true

`DefaultEnvironmentManagementSelection`

When enabled, publishers can select the default environment management strategy for individual content items using the Connect Server API Content fields default_r_environment_management and default_py_environment_management, overriding the system defaults given by R.EnvironmentManagement and Python.EnvironmentManagement. When Applications.ManifestEnvironmentManagementSelection is enabled, the selection in the manifest takes precedence.

Type: boolean
Default: true

`OAuthIntegrationsEnabled`

When enabled, administrators can configure OAuth integrations to support dynamic viewer experiences by delegating the viewer’s OAuth credentials to content running on Connect.

Type: boolean
Default: true

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>

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 Posit Connect manages processes for deployed applications and APIs. These configuration settings provide the defaults for all content; an individual application can override those defaults using the Connect Server API or in the Runtime tab of the Connect dashboard.

Posit Connect looks at the number of running processes and the number of connections serviced by each process when determining how to service an incoming client connection. When the target application has running processes with available capacity, the incoming connection is handled by the worker process having the fewest connections. When there are no running workers or no worker has capacity, a new process is started.

The worker connection load helps determine when additional processes are started and stopped. The connection load is determined by considering the current number of workers, current number of connections, and the maximum number of allowed connections. When a substantial number of the allowed connections have been consumed, a new worker process is started and will be available to service future connections.

The logic that determines if an additional worker is needed looks like the following pseudocode:

# Given:
#   numProcesses - Processes for this application.
#   numConnections - Connections across all processes for this application.
allowedConnections = numProcesses * Scheduler.MaxConnsPerProcess
allowedLoad = allowedConnections * Scheduler.LoadFactor * 1.1
if numConnections > allowedLoad:
    # Create a new process if the new process will not violate
    # Scheduler.MaxProcesses
    startWorker()

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

Once a worker has no active connections and has passed its idle period, it may be retired. The logic that determines if a worker is no longer needed looks like the following pseudocode:

# Given:
#   numProcesses - Processes for this application.
#   numConnections - Connections across all processes for this application.
allowedConnections = (numProcesses-1) * Scheduler.MaxConnsPerProcess
allowedLoad = allowedConnections * Scheduler.LoadFactor
if numConnections <= allowedLoad:
    # Stop this process if its termination will not violate
    # Scheduler.MinProcesses
    stopWorker()

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.

Session-based applications such as Shiny and Streamlit have a short default IdleTimeout, since the idle period doesn’t begin until all sessions have been closed. For “transactional” content types, such as Dash apps and Plumber APIs, there isn’t a session maintaining an active connection to the application. The applications are considered idle as soon as they have served any pending requests. Connect uses a longer IdleTimeout value for these applications so that the process stays around to quickly service subsequent requests.

Posit Connect manages processes for many pieces of content simultaneously. If one content item consumes an excessive amount of RAM, it can starve other processes running on the same host or node. To help manage this, you can configure a default MemoryLimit. Processes that allocate memory beyond this limit are terminated automatically. You can also configure a MaxMemoryLimit to set an upper bound on custom scheduler settings for individual content items.

If Posit Connect is configured for off-host execution with Kubernetes, you can also configure a default MemoryRequest, CPULimit, CPURequest, AMDGPULimit, and NvidiaGPULimit as well as corresponding maxes for each. See Resource Management for Pods and Containers and Using device plugins to learn more about how Kubernetes uses Requests and Limits.

Previous versions of Posit Connect did not apply any memory or CPU limits to processes. To keep this behavior, omit these settings or set them to 0.

Note

Memory, CPU, and GPU requests/limits apply to processes that render documents, as well as processes that serve applications and APIs. This is different than other settings in this section, which only apply to worker processes for applications and APIs.

Warning

We recommend configuring memory and CPU limits only after observing the typical usage patterns of content on your server. When a process is terminated due to exceeding allowed RAM, it is terminated by the operating system, and the error message will depend on the specific OS, language, packages, and user code involved. Therefore, it is not possible to give a list of possible error codes, or for Posit Connect to detect that this is the reason for termination.

If your content is failing to render or execute and the reason is ambiguous, try increasing or removing any RAM limits. Similarly, requests for initial CPU or RAM that cannot be fulfilled by Kubernetes may cause errors that appear in Kubernetes logs but not Posit Connect logs. If your content process is failing to start, try increasing or removing initial CPU and RAM requests.

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

Enabling GPUs

To enable GPUs for use during content execution, off-host execution with Kubernetes must be enabled in Posit Connect, and your Kubernetes cluster must have a GPU device plugin installed.

Depending on which GPU device plugin is in use (AMD or NVIDIA), enable the appropriate type of GPU in the Connect scheduler settings.

To enable NVIDIA GPUs for content:

[Scheduler]
; most content does not need a GPU so request 0 GPUs by default
NvidiaGPULimit = 0

; content can request <= 1 NVIDIA GPU when it runs
MaxNvidiaGPULimit = 1

To enable AMD GPUs for content:

[Scheduler]
; most content does not need a GPU so request 0 GPUs by default
AMDGPULimit = 0

; content can request <= 1 AMD GPU when it runs
MaxAMDGPULimit = 1

Content-type Scheduler Settings

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 R applications
static for content deployed without source
rmd-static for R Markdown documents or sites
rmd-shiny for Shiny applications embedded in R Markdown documents
quarto-static for Quarto documents or sites
quarto-shiny for Shiny applications embedded in Quarto documents
api for Plumber APIs
python-shiny for Shiny Python applications
python-api for Python Flask APIs
python-fastapi for Python FastAPI apps
python-dash for Python Dash apps
python-bokeh for Python Bokeh apps
python-gradio for Python Gradio apps
python-streamlit for Python Streamlit apps
jupyter-voila for Voila interactive notebooks
jupyter-static for static notebooks
tensorflow-saved-model for TensorFlow Model APIs
unknown - for content with no known runtime model

`Scheduler` Settings

`MaxProcesses`

Specifies the total number of concurrent processes allowed for a single application per Posit 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. Must be greater than 0.

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

`MemoryRequest`

Minimum amount of RAM a single application or document render requires. 0 means no minimum will be requested. Cannot be greater than 9007198180999168 (8388607 GiB.) Only used when Launcher.Kubernetes is enabled.

Type: byte-size
Default: 0

`MemoryLimit`

Maximum amount of RAM a single application or document render is allowed to consume. 0 means the memory use is unlimited. Cannot be greater than 9007198180999168 (8388607 GiB.) Processes that exceed their limit will be terminated.

Type: byte-size
Default: 0

`CPURequest`

Minimum amount of CPU cores a single application or document render requires to run, on an ongoing basis. 1.0 is equivalent to consuming 1 entire CPU core. 0.0 means that no CPU minimum will be requested. Only used when Launcher.Kubernetes is enabled.

Type: decimal
Default: 0.0

`CPULimit`

Limits the amount of CPU time a single application or document render can use, on an ongoing basis. 1.0 is equivalent to consuming 1 entire CPU core. 0.0 means that CPU use is unlimited. Processes that exceed their limit will be throttled. Only used when Launcher.Kubernetes is enabled.

Type: decimal
Default: 0.0

`MaxMemoryRequest`

Maximum value allowed for the MemoryRequest setting on any application or document. Cannot be greater than 9007198180999168 (8388607 GiB.)

Type: byte-size
Default: 0

`MaxMemoryLimit`

Maximum value allowed for the MemoryLimit setting on any application or document. Cannot be greater than 9007198180999168 (8388607 GiB.)

Type: byte-size
Default: 0

`MaxCPURequest`

Maximum value allowed for the CPURequest setting on any application or document.

Type: decimal
Default: 0.0

`MaxCPULimit`

Maximum value allowed for the CPULimit setting on any application or document.

Type: decimal
Default: 0.0

`AMDGPULimit`

Minimum number of AMD GPUs a single application or document render requires. A value of zero means content processes do not require a GPU by default. A value greater than zero means all content requires AMD GPUs by default. Only used when Launcher.Kubernetes is enabled.

Type: integer
Default: 0

`MaxAMDGPULimit`

Maximum value allowed for the AMDGPULimit setting on any application or document render. A value of zero means AMD GPUs are disabled for all content. Only used when Launcher.Kubernetes is enabled. The Kubernetes cluster must enable the AMD device plugin.

Type: integer
Default: 0

`NvidiaGPULimit`

Minimum number of NVIDIA GPUs a single application or document render requires. A value of zero means content processes do not request a GPU by default. A value greater than zero means all content requires NVIDIA GPUs by default. Only used when Launcher.Kubernetes is enabled.

Type: integer
Default: 0

`MaxNvidiaGPULimit`

Maximum value allowed for the NvidiaGPULimit setting on any application or document render. A value of zero means NVIDIA GPUs are disabled for all content. Only used when Launcher.Kubernetes is enabled. The Kubernetes cluster must enable the NVIDIA device plugin.

Type: integer
Default: 0

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 Jobs.MaxCompleted or Jobs.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. On-disk job metadata is removed if either the Jobs.MaxCompleted or Jobs.OldestCompleted restrictions are violated.

Type: duration
Default: 30d

Metrics

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

See the Operational Metrics section for more details.

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

`Metrics` Settings

`Enabled`

Specifies whether or not the rserver-monitor process that collects resource 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 resource metrics collection.

Type: duration
Default: 60s

`RRDEnabled`

Enable logging of resource metrics to RRD.

Type: boolean
Default: true

`GraphiteEnabled`

Enable logging of metrics to Graphite.

Type: boolean
Default: false

`GraphiteHost`

Host to which to send Graphite metrics.

Type: string
Default: 127.0.0.1

`GraphitePort`

Port to which to send Graphite metrics.

Type: integer
Default: 2003

`GraphiteClientId`

Optional Client ID to include along with Graphite 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

`InstrumentationInterval`

The interval between batch instrumentation writes to the database.

Type: duration
Default: 2s

`InstrumentationBatchSize`

The maximum size of batch instrumentation writes to the database.

Type: integer
Default: 200

`PrometheusListen`

Posit Connect will listen on this network address to expose metrics in a Prometheus-compatible format. The network address can be of the form :443 or 192.168.0.1:443, an empty value disables this feature.

Type: string
Default: <empty-string>

`HTTPRequestLatencyEnabled`

Enable prometheus metrics for tracking aggregate HTTP request latency for the following api groups: [/v1/content, /v1/groups, /v1/users]

Type: boolean
Default: true

R

The R section contains configuration properties pertaining to R support for deployable content. See the R section for further details.

`R` Settings

`Enabled`

Toggles R support.

Type: boolean
Default: true

`Executable`

Path to an R interpreter.

Type: multi-string
Default: unspecified

`ExecutableScanning`

Scan for R installations in well-known locations. Ignored when Launcher.Kubernetes is enabled.

Type: boolean
Default: true

`ExecutableVersionScanning`

Scan for versioned R installations beneath /opt/R and /opt/local/R. Active only when R.ExecutableScanning is enabled. Ignored when Launcher.Kubernetes is enabled.

Type: boolean
Default: true

`ExecutableSystemScanning`

Scan for R in locations typically used by Linux distributions. Active only when R.ExecutableScanning is enabled. Ignored when Launcher.Kubernetes is enabled.

Type: boolean
Default: false

`ExecutablePathScanning`

Scan for R using the PATH when other approaches do not discover an R installation. Active only when R.ExecutableScanning is enabled. Ignored when Launcher.Kubernetes is enabled.

Type: boolean
Default: false

`VersionMatching`

Specifies how Posit 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

`ConfigActive`

Specifies a value for the R_CONFIG_ACTIVE environment variable when running content that uses R; supported by the config package.

Type: string
Default: rsconnect

`External`

R package that will not be installed or managed by Posit Connect when deploying content. This can be provided multiple times, once for each package. Each external package must be present in the library of each R installation.

Type: multi-string
Default: unspecified

`ExternalsCheckIsFatal`

If true, Posit Connect will fail to start up if a package listed in R.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

`TestLoadBinaryPackages`

If true, test-load binary packages during the installation of R packages. This load test can detect many system incompatibilities during environment restoration.

Type: boolean
Default: true

`RestoreUsesGitCredentials`

If true, R environment restores will be able to download packages from private repositories on github.com, gitlab.com, and bitbucket.org, using configured Git credentials.

Type: boolean
Default: true

`PositPackageManagerURLRewriting`

Controls how Connect rewrites Posit Package Manager URLs. When set to auto, the default, rewrites URLs for incompatible binary packages to install compatible binary or source packages. Use force-source to rewrite all Posit Package Manager URLs to install source packages, or force-binary for binary packages. Set to none to disable automatic rewriting. For more information, see documentation on Posit Package Manager URL rewriting. This setting affects configured RPackageRepository URLs as well as repositories from published content. Allowed values are auto, force-source, force-binary or none.

Type: string
Default: auto

`PackageRepositoryResolution`

Controls how Connect resolves the set of repositories used to install R packages. Use strict to use only configured RPackageRepository entries. Use lax to use configured RPackageRepository entries and repositories from content. Use legacy to use the list of repositories from content, overwriting matching repositories with URLs configured RPackageRepository entries. For more information, see documentation on controlling R package repositories in use Allowed values are lax, strict or legacy.

Type: string
Default: lax

`EnvironmentManagement`

Whether Posit Connect should be responsible for managing R package installation for the execution environment.

Type: boolean
Default: true

Python

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

`Python` Settings

`Enabled`

Python feature toggle.

Type: boolean
Default: false

`VersionMatching`

Specifies how Posit 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. Ignored when Launcher.Kubernetes is enabled.

Type: multi-string
Default: unspecified

`AllowUv`

If true, Posit Connect will allow the usage of uv as the installer for python packages.

Type: boolean
Default: false

`DefaultPackageManager`

python package manager that Posit Connect should use to install python packages.

Type: string
Default: pip

`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-content-trust, conda-env, conda-package-handling, conda-package-streaming, conda-repo-cli, conda-token, 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, quarto-cli, 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, Posit 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, Posit 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. Posit 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

`EnvironmentManagement`

Whether Posit Connect should be responsible for managing Python package installation for the execution environment.

Type: boolean
Default: true

Quarto

The Quarto section contains configuration properties controlling the optional support for Quarto content by Posit Connect.

Quarto is an open-source scientific and technical publishing system built on Pandoc.

To get started, you will need a Quarto installation on your Connect server and configuration like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[Quarto]
Enabled = true
Executable = "/usr/local/bin/quarto"

`Quarto` Settings

`Enabled`

Allows the use of Quarto.

Type: boolean
Default: false

`VersionMatching`

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

Type: string (case-insensitive)
Default: nearest

`Executable`

Path to a Quarto executable. Multiple definitions can be used to provide multiple versions of Quarto. Ignored when Launcher.Kubernetes is enabled.

Type: multi-string
Default: unspecified

`Profile`

Specifies the default Quarto profile as a value to the QUARTO_PROFILE environment variable. Individual content items may also customize this environment variable.

Type: string
Default: connect

TensorFlow

The TensorFlow section contains configuration properties controlling the optional support for TensorFlow content by Posit Connect.

TensorFlow is an end-to-end platform for machine learning. Connect can use a TensorFlow Serving installation to serve models.

To get started, you will need a TensorFlow Serving on your Connect server and configuration like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[TensorFlow]
Enabled = true
Executable = "/usr/bin/tensorflow_model_server"

`TensorFlow` Settings

`Enabled`

Allows the use of TensorFlow.

Type: boolean
Default: false

`Executable`

Path to a TensorFlow tensorflow_model_server executable. Ignored when Launcher.Kubernetes is enabled.

Type: string
Default: <empty-string>

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 Posit 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. Only one credential per host is supported, and you must name each GitCredential section.

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

Credentials can be used:

To deploy Git-backed content from any HTTP/HTTPS Git host;
To restore R packages from private Git repositories on github.com, gitlab.com, and bitbucket.org.

`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, Posit Connect will provide CORS headers and pre-flight OPTIONS endpoints.

Type: boolean
Default: false

`AllowOrigin`

The values checked during CORS handling of requests to Posit 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

`EnforceWebsocketOrigin`

Validates that the Host and Origin headers are the same for Websocket connections.

Type: boolean
Default: true

RPackageRepository

The RPackageRepository section lets you configure R package repositories for use when restoring packages. These can be made directly available to R, or used to override the URLs for R package repositories. This behavior is controlled by the R.PackageRepositoryResolution setting. See documentation on controlling R package repositories used for package install for details.

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

Important

If you are making other changes to the execution environment when configuring RPackageRepository, you may need to clear R package caches. Specifically, if packages in the cache were compiled for a different execution environment, content will fail to run.

See the Runtime Caches section for instructions about how to clear your runtime caches and selectively rebuild your deployed content.

`RPackageRepository` Settings

`URL`

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

Type: string
Default: <empty-string>

Branding

The Branding section allows you to rebrand Posit Connect, see the available configuration fields below.

`Branding` Settings

`Enabled`

When enabled, Posit Connect will make use of any Branding settings and display Powered by Posit Connect when applicable.

Type: boolean
Default: false
Reloadable: true

`DisplayName`

Name used to replace Posit Connect brand name in product messages and emails.

Type: string
Default: Posit Connect
Reloadable: true

`Logo`

Specify an image file path for Connect to use as the logo. It should be an absolute path that points to the image file in your server. Use only images supported by browsers such as .png, .jpeg, .gif and .svg.

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

`Favicon`

Specify an image file path for Connect to use as the favicon. It should be an absolute path that points to the image file in your server. Use favicon image types supported by browsers such as .png, .ico and .gif.

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

TableauIntegration

The TableauIntegration section allows you to configure Posit Connect to host Tableau Analytics Extensions built in both R and Python. These extensions can be used from Tableau workbooks to make realtime requests from Tableau to Connect. See Tableau Integration for more information.

`TableauIntegration` Settings

`Enabled`

When enabled, Connect supports the hosting of Tableau extensions and routes requests from Tableau to the targeted content.

Type: boolean
Default: true

`Logging`

A flag that notes whether debug output should be enabled as Connect processes Tableau requests.

Type: boolean
Default: false

Bootstrap

The Bootstrap section allows you to configure programmatic provisioning of a fresh Posit Connect instance. See Programmatic Provisioning for more information.

`Bootstrap` Settings

`Enabled`

When enabled, Posit Connect will expose an endpoint which will allow you to create the first administrator user programmatically, allowing using its API key for bootstrapping Connect.

Type: boolean
Default: false

`SecretKey`

A Base64-encoded secret key used to sign and verify JWT tokens used by the bootstrapping endpoint.

Type: string
Default: <empty-string>

`SecretKeyFile`

Path to file containing a Base64-encoded secret key used to sign and verify JWT tokens used in the bootstrapping endpoint.

Type: string
Default: <empty-string>

Logging

The Logging section contains properties which control structured logging in Posit Connect.

`Logging` Settings

`ServiceLog`

The output destination for service logs. It can be STDOUT, STDERR or a file path.

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

`ServiceLogLevel`

The minimum level for logging messages. It can be one of: INFO, WARN, or ERROR.

Type: string
Default: INFO
Reloadable: true

`ServiceLogFormat`

The output format for service logs. It can be one of: TEXT or JSON.

Type: string
Default: TEXT

`AccessLog`

The output destination for access logs. If empty, access logs will be disabled. It can be STDOUT, STDERR or a file path.

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

`AccessLogFormat`

The output format for access logs. It can be one of: COMMON, COMBINED, or JSON.

Type: string
Default: COMMON

`AuditLog`

The output destination for audit logs. If not specified, audit logs will be stored only in the database. It can be STDOUT, STDERR or a file path.

Type: string
Default: <empty-string>

`AuditLogFormat`

The output format for audit logs. It can be one of: TEXT or JSON.

Type: string
Default: TEXT

Launcher

The Launcher section contains settings for configuring Posit Connect to use the Posit Job Launcher. This allows Connect to run content jobs on Kubernetes using containers. To enable this functionality, Posit recommends using the Connect Helm chart to deploy Connect on Kubernetes. When using the Helm chart, do not set these configurations in the main rstudio-connect.gcfg. Instead, modify the values.yaml configuration file that is used when invoking the helm command. Helm then generates the rstudio-connect.gcfg configuration for Connect. For a detailed overview of this feature, see the Connect Off-Host Execution documentation.

Note

The Launcher process used by Posit Connect is bundled with the Connect installation and is fully managed by Connect. Administrators do not need to install a separate instance of the Launcher to use this feature. Connect generates all necessary configuration files at runtime. To avoid conflict with an existing installation of the Launcher used by Posit Workbench, Posit does not recommend installing Connect on the same server as an existing Launcher installation.

`Launcher` Settings

`Enabled`

Enable use of the Posit Job Launcher when building and executing content.

Type: boolean
Default: false

`Kubernetes`

Enable the use of the Kubernetes launcher plugin. Launcher.Enabled must also be true.

Type: boolean
Default: false

`KubernetesAPIURL`

URL where the Kubernetes API can be found. Defaults to the value of the KUBERNETES_API_URL environment variable, if set.

Type: string
Default: <empty-string>

`KubernetesAuthToken`

API token for the Kubernetes cluster. Defaults to the value of the KUBERNETES_AUTH_TOKEN environment variable, if set.

Type: string
Default: <empty-string>

`KubernetesNamespace`

Namespace in which the launcher should try to execute Posit Connect jobs.

Type: string
Default: rstudio-connect

`KubernetesSSLVerification`

Whether the launcher should verify the Kubernetes API’s SSL certificate.

Type: boolean
Default: true

`KubernetesCACertificateData`

Certificate authority to use when connecting to the Kubernetes API server with HTTPS. This must be a Base64-encoded PEM certificate. Defaults to the value of the KUBERNETES_CA_CERT_DATA environment variable, if set. Leave this blank to use the system root CA store.

Type: string
Default: <empty-string>

`KubernetesProfilesConfig`

Path to the launcher.kubernetes.profiles.conf file.

Type: string
Default: /etc/rstudio-connect/launcher/launcher.kubernetes.profiles.conf

`KubernetesUseTemplates`

Enable the use of launcher templates (job and service).

Type: boolean
Default: true

`KubernetesJobExpiryHours`

Number of hours (fractions allowed) before completed jobs are removed from the system.

Type: decimal
Default: 0.25

`KubernetesContentServiceAccountSelection`

Enable content-specific Kubernetes service accounts.

Type: boolean
Default: true

`KubernetesDefaultServiceAccount`

The global default service account to use for Kubernetes jobs.

Type: string
Default: default

`KubernetesValidateServiceAccounts`

Enable validation of the global default and content-specific Kubernetes service accounts against service accounts found on Kubernetes.

Type: boolean
Default: true

`ClusterDefinition`

A path to a runtimes.yaml configuration file containing a list of valid container images for running jobs on Kubernetes.

Type: multi-string
Default: unspecified

`User`

The local Linux user to run the launcher as.

Type: string
Default: rstudio-connect

`Group`

The local Linux group that has launcher admin privileges.

Type: string
Default: rstudio-connect

`ConfigDir`

The directory where configuration files for the launcher will be managed.

Type: string
Default: /etc/rstudio-connect/launcher

`ScratchPath`

The directory where launcher stores its temporary state.

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

`Port`

The port the launcher will be configured to listen on.

Type: integer
Default: 5559

`MonitorInterval`

Duration between health check API requests from Connect to the launcher.

Type: duration
Default: 1m

`DataDir`

The directory where Connect stores its persistent data, to be used as the data Volume for Connect’s content runtime. This setting must reference the same physical storage location as the Server.DataDir.

Type: string
Default: <empty-string>

`DataDirPVCName`

The name of the PersistentVolumeClaim in Kubernetes where Connect stores its persistent data, to be used as the data Volume for Connect’s content runtime. This setting must reference the same physical storage location as the Server.DataDir.

Type: string
Default: <empty-string>

`DataDirNFSHost`

The hostname or IP address of the NFS host where Connect stores its persistent data, to be used as the data Volume for Connect’s content runtime. When this setting is used, Launcher.DataDir must contain the NFS export path. This setting must reference the same physical storage location as the Server.DataDir.

Type: string
Default: <empty-string>

Notifications

The Notifications section contains configuration used to specify additional email recipients for content permission requests and content errors. More than one Notifications section is permitted, and each section must specify the type of notifications to receive: *, permission_requests, or errors.

Example:

[Notifications "*"]
Email = "super-admin@example.com"

[Notifications "permission_requests"]
Email = "user-admin@example.com"

[Notifications "errors"]
Email = "manager@example.com"
Email = "qa@example.com"

Note

The email addresses do not have to be Connect administrators or users, but Connect displays a warning if they are not. You should ensure that notification recipients have the necessary permissions to take action on the notifications they receive.

`Notifications` Settings

`Email`

The email address(es) to which Notifications will be sent. This can be provided multiple times, once for each email address.

Type: multi-string
Default: unspecified

Early Access

The EarlyAccess section contains configuration that allows you to enable features available for preview before general release. See the Early Access section of the user guide for details about each available feature.

`EarlyAccess` Settings

`ShareLink`

When enabled, Posit Connect will allow publishers to create shareable links to content.

Type: boolean
Default: false

Configuration Basics

File Format

Multi-value Properties

Property Types

Reloadable Properties

Environment Variables

Server

Server Settings

DataDir

TempDir

LandingDir

Robots

EnableSitemap

JumpStartEnabled

CompilationConcurrency

Address

EmailProvider

SenderEmail

SenderEmailDisplayName

EmailFromUserAddresses

EmailTo

EmailSubjectPrefix

HideEmailAddresses

MailAll

ViewerKiosk

PublicWarning

LoggedInWarning

DeprecatedSettingsUIWarning

DashboardPath

RootRedirect

ContentTypeSniffing

ServerName

CustomHeader

FrameOptionsContent

FrameOptionsDashboard

SameSite

URLNormalizationRedirects

HideVersion

ProxyHeaderLogging

NodeName

PreventDuplicateTasks

DefaultContentListView

HideViewerDocumentation

SelfTestOnStartup

SelfTestFrequency

SystemCheckOnStartup

SystemCheckFrequency

UseFIPSEncryption

AllowRuntimeCacheManagement

TrustedRedirect

SMTP

SMTP Settings

Host

Port

SSL

StartTLS

User

Password

ClientAddress

HTTP

HTTP Settings

Listen

NoWarning

ForceSecure

HTTPS

HTTPS Settings

Listen

Key

Certificate

Permanent

StrictTransportSecurityMaxAge

MinimumTLS

HTTPRedirect

HTTPRedirect Settings

Listen

Target

Licensing

Licensing Settings

LicenseType

RemoteRetryFrequency

`Server` Settings

`DataDir`

`TempDir`

`LandingDir`

`Robots`

`EnableSitemap`

`JumpStartEnabled`

`CompilationConcurrency`

`Address`

`EmailProvider`

`SenderEmail`

`SenderEmailDisplayName`

`EmailFromUserAddresses`

`EmailTo`

`EmailSubjectPrefix`

`HideEmailAddresses`

`MailAll`

`ViewerKiosk`

`PublicWarning`

`LoggedInWarning`

`DeprecatedSettingsUIWarning`

`DashboardPath`

`RootRedirect`

`ContentTypeSniffing`

`ServerName`

`CustomHeader`

`FrameOptionsContent`

`FrameOptionsDashboard`

`SameSite`

`URLNormalizationRedirects`

`HideVersion`

`ProxyHeaderLogging`

`NodeName`

`PreventDuplicateTasks`

`DefaultContentListView`

`HideViewerDocumentation`

`SelfTestOnStartup`

`SelfTestFrequency`

`SystemCheckOnStartup`

`SystemCheckFrequency`

`UseFIPSEncryption`

`AllowRuntimeCacheManagement`

`TrustedRedirect`

`SMTP` Settings

`Host`

`Port`

`SSL`

`StartTLS`

`User`

`Password`

`ClientAddress`

`HTTP` Settings

`Listen`

`NoWarning`

`ForceSecure`

`HTTPS` Settings

`Listen`

`Key`

`Certificate`

`Permanent`

`StrictTransportSecurityMaxAge`

`MinimumTLS`

`HTTPRedirect` Settings

`Listen`

`Target`

`Licensing` Settings

`LicenseType`

`RemoteRetryFrequency`

`ExpirationEmail`

`ExpirationUIWarning`

`EndOfSupportUIWarning`

`StrictUsersEnforcement`

`Database` Settings

`Provider`

`Dir`

`MaxIdleConnections`

`MaxOpenConnections`

`ConnectionMaxLifetime`

`SQLite` Settings

`Dir`