A Configuration Options

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

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

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

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

; Comment
[BooleanExamples]
property1 = true
property2 = off
property3 = 1

[IntegerExamples]
Property1 = 42
Property2 = -123

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

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

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

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

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

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

[Example]
A = aligator
B = 2

[Example]
A = aardvark
C = shining

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

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

Property definitions always have the form:

Name = value

The equals sign (=) is mandatory.

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

[MultiExample]
Color = black
Color = blue

[NonMulti]
Animal = cat
Animal = dog

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

Configuration properties all have one of the following types:

string

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

multi-string

A property that takes multiple string values. The property name is listed with each individual input value. For example, providing Color = black and Color = blue results in two separate values.

boolean

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

integer

An integral value.

decimal

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

duration

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

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

version

A string representing a version. A version may have one to four numeric components, separated by periods or hyphens. Examples include 2, 2.5, 2.5.6, 2.5.6.1, and 2.5-6-11.

bytesize

A string representing a size in bytes. Valid examples include 10MB, 1 tb, 3 terabytes, and 2 GB.

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

Some properties are marked as “reloadable”. Sending a HUP signal to the Package Manager process causes the on-disk configuration to be reread. The server is reconfigured with the latest values of these reloadable properties. See 5.1 for details about sending a HUP signal to your Package Manager process.

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

A HUP signal only reloads configuration settings that have explicitly changed. Commenting out a setting will not affect the configuration when using the HUP signal. If you have commented out a setting instead of changing the setting value, restart the RStudio Package Manager service instead of using the HUP signal.

A.1 Server

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

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

---

DataDir

The directory where RStudio Package Manager will store its variable data.

Type: string

Default: /var/lib/rstudio-pm

TempDir

The directory that will contain all temporary directories needed by R processes. May not be a child path of Server.DataDir. If TMPDIR environment variable is not defined then /tmp.

Type: string

Default: $TMPDIR

CacheTimeout

The amount of time we wait for files to appear in the cache directory after the database reports they are available. The default of 65 seconds should accommodate the NFS default directory caching limit of 60 seconds

Type: duration

Default: 65s

RVersion

Path to an R installation root.

Type: multi-string

Default: unspecified

Address

A public URL for this RStudio Package Manager server.

Type: string

Default: <empty-string>

ContentTypeSniffing

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

Type: boolean

Default: false

ServerName

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

Type: string

Default: <empty-string>

AccessLog

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

Type: string

Default: /var/log/rstudio-pm.access.log

ServiceLog

Path to the file that RStudio Package Manager will use for its service logs logs. Disabled when empty.

Type: string

Default: <empty-string>

CustomHeader

Custom HTTP header that should be added to responses from Package Manager 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 Package Manager would otherwise have set. Multiple definitions can be used to provide multiple custom headers.

Type: multi-string

Default: unspecified

FrameOptionsUI

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

Type: string

Default: DENY

HideVersion

When true, the /version API returns a blank string and the product version is not displayed in the UI.

Type: boolean

Default: false

Reloadable: true

SockFileDir

RStudio Package Manager will use this directory to create a socket file for admin connections.

Type: string

Default: /var/run/rstudio-pm

UsageDataEnabled

If true, will enable tracking of package downloads.

Type: boolean

Default: true

UsageDataRetention

The number of days for which usage data will be retained. If 0, data will be preserved forever.

Type: integer

Default: 365

UsageDataSchedule

The schedule for usage data aggregation. Must be a valid crontab string.

Type: string

Default: 0 0 * * *

Reloadable: true

EncryptionKeyPath

The filepath of the encryption key used to store sensitive data at rest. Must be 512 bits (64 bytes) and file mode must be 0600. For cluster environments every server must have a copy of the same key file.

Type: string

Default: {Server.DataDir}/rstudio-pm.key

A.2 API

The API section contains configuration properties which apply to the RStudio Package Manager API.

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

---

MaxApiResults

Limits the maximum number of results that can be returned from API endpoints that support a _limit parameter. When zero, there is no limit. Please consider performance implications before raising this limit.

Type: integer

Default: 1000

DefaultApiResultsLimit

The default limit on the number of results returned from API endpoints that support a _limit parameter. When zero, there is no limit.

Type: integer

Default: 100

A.3 HTTP

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

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

---

Listen

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

Type: string

Default: <empty-string>

NoWarning

Disables warnings about insecure (HTTP) connections.

Type: boolean

Default: false

ForceSecure

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

Type: boolean

Default: false

A.4 HTTPS

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

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

---

Listen

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

Type: string

Default: <empty-string>

Key

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

Type: string

Default: <empty-string>

Certificate

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

Type: string

Default: <empty-string>

Permanent

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

Type: boolean

Default: false

MinimumTLS

Minimum TLS version supported. Valid values are 1.0, 1.1, and 1.2.

Type: string

Default: 1.1

ExcludedCiphers

List of IANA strings for ciphers to exclude. See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml for a list of all known cipher strings. Multiple definitions can be used to exclude multiple ciphers.

Type: multi-string

Default: unspecified

A.5 HttpRedirect

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

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

---

Listen

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

Type: string

Default: <empty-string>

Target

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

Type: string

Default: <empty-string>

A.6 Git

The Git section contains configuration properties which RStudio Package Manager uses to build R packages from Git repositories.

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

---

BuilderDir

The directory where RStudio Package Manager will store git repos.

Type: string

Default: {Server.DataDir}/git

Reloadable: true

PollInterval

The amount of time to wait between polling git repos to look for package changes.

Type: duration

Default: 5m

Reloadable: true

TagMatching

The regular expression used to determine whether a git tag is a valid version.

Type: string

Default: <empty-string>

BuildRetries

The maximum number of times to attempt building a git package when the build fails.

Type: integer

Default: 3

AllowUnsandboxedGitBuilds

When the Linux user namespace is unavailable, allow unsafe Git package builds without a sandbox.

Type: boolean

Default: false

A.7 Launcher

The Launcher section contains configuration properties which control the RStudio Job Launcher. The RStudio Job Launcher provides the capability to launch executables, allowing RStudio Package Manager to launch R processes for tasks like building R packages.

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

---

Disabled

Disables the job launcher

Type: boolean

Default: false

Port

Port number (0-65535)

Type: integer

Default: 5561

ServerUser

User that runs the job launcher executable.

Type: string

Default: rstudio-pm

AdminGroup

Name of the admin group of users that are able to see/control all jobs in the system of other users.

Type: string

Default: rstudio-pm

DebugLogging

Enables verbose debug logging for the job launcher.

Type: boolean

Default: false

RequestTimeoutSeconds

Number of seconds a plugin has to process a request before it is considered timed out.

Type: integer

Default: 120

TransportTimeoutMinutes

Number of minutes an HTTP request to the launcher has to process before it is considered timed out.

Type: integer

Default: 75

A.8 Metrics

The Metrics section contains configuration properties which control how RStudio Package Manager exposes metrics.

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

---

Enabled

Specifies whether or not the metrics service will be started.

Type: boolean

Default: false

Listen

The address on which to listen for metrics requests.

Type: string

Default: :2112

A.9 Licensing

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

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

---

LicenseType

Enable remote or local validation. local is traditional activation, whereas remote uses floating licensing.

Type: string

Default: local

Reloadable: true

RemoteRetryFrequency

When Package Manager 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: 10

Reloadable: true

A.10 CRAN

The CRAN section contains configuration properties related to the CRAN source in RStudio Package Manager.

---

ManifestURL

The URL to the CRAN manifest service. Do not use this setting unless you want to get CRAN data from your own server.

Type: string

Default: https://rspm-sync.rstudio.com

SyncSchedule

The schedule for CRAN synchronization. Must be a valid crontab string. Use a blank value for manual syncing only.

Type: string

Default: 0 0 * * *

Reloadable: true

SyncMode

The sync mode for CRAN synchronization. Must be either eager or lazy

Type: string

Default: lazy

Reloadable: true

CRANTimeout

The timeout for downloading checkpoints or changes (JSON) from the CRAN manifest

Type: duration

Default: 30m

FetchTimeout

The timeout for downloading a CRAN package tarball.

Type: duration

Default: 10m

Binaries

The distributions for which to enable binary support. Use all to enable all distributions or a comma-separated list: e.g. xenial, bionic, centos7.

Type: string

Default: all

A.11 Database

The Database section contains configuration properties which control the location of and how RStudio Package Manager interacts with its databases.

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

---

Provider

The type of database to use

Type: string

Default: sqlite3

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

A.12 SQLite

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

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

---

Dir

The directory containing the RStudio Package Manager database. Must reference a directory on the local filesystem and not on a networked volume like NFS.

Type: string

Default: {Server.DataDir}/db

A.13 Postgres

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

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

---

URL

The fully qualified URL to connect to a Postgres database

Type: string

Default: <empty-string>

UsageDataURL

The fully qualified URL to connect to a Postgres database where usage information will be written.

Type: string

Default: <empty-string>

A.14 PostgresPool

The PostgresPool section contains configuration properties which control the location of and how RStudio Package Manager interacts with a special postgres connection pool that is used for the following special purposes:

• Persistent Storage - When configured to use PostgreSQL for persistent storage (caching, etc.), the Postgres Pool will be used for interactions with Postgres Large Object storage.
• Notifications - An RStudio Package Manager cluster uses Postgres NOTIFY/LISTEN messaging to support intra-node communication. The Postgres Pool will be used for this feature.

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

---

MaxOpenConnections

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

Type: integer

Default: 10

A.15 Storage

The Storage configuration section contains properties that control whether variable data should be stored on a local filesystem or S3. You can configure the storage destination for five classes of data. By default, each storage class defaults to file, but you can configure any storage class for S3.

; /etc/rstudio-pm/rstudio-pm.gcfg

[Storage]
; Each class defaults to `file`
; Cache = file
; Launcher = file
;
; You can override the destination to use S3
Metrics = s3
Packages = s3
Binaries = s3

---

Cache

Storage location for the cache. Must be either file or S3.

Type: string

Default: file

Packages

Storage location for packages. Must be either file or S3.

Type: string

Default: file

Binaries

Storage location for binaries. Must be either file or S3.

Type: string

Default: file

Metrics

Storage location for usage metrics aggregation. Must be either file or S3.

Type: string

Default: file

Launcher

Storage location for job launcher logs. Must be either file or S3.

Type: string

Default: file

A.16 FileStorage

The FileStorage section contains configuration properties which control where files are stored. You can configure a FileStorage section for any of five classes of data:

• cache
• launcher
• metrics
• packages
• binaries

If you wish to change the base storage location for all RStudio Package Manager data, please use the Server.DataDir property instead. Use a FileStorage configuration section only when you wish to change the storage location for a particular class of data.

For example, to configure a custom storage location for the cache, you would create the following configuration section:

; /etc/rstudio-pm/rstudio-pm.gcfg

[FileStorage "cache"]
Location = /path/to/cache

---

Location

The directory to use for this storage class.

Type: string

Default: {Server.DataDir}/{StorageClass}

A.17 S3Storage

The S3Storage section contains configuration properties which control where files are stored on S3. You can configure an S3Storage section for any of five classes of data:

• cache
• launcher
• metrics
• packages
• binaries

If you wish to use S3 for all variable data, please use a generic S3Storage configuration section. You can then override the generic settings for any storage class as necessary. For example:

; /etc/rstudio-pm/rstudio-pm.gcfg

[Storage]
Cache = s3
Launcher = s3
Metrics = s3
Packages = s3
Binaries = s3

; Default S3 settings. This is the minimum-required setting for using S3.
[S3Storage]
Bucket = your-s3-bucket

; Override default S3 settings for the "packages" class. This demonstrates
; all the available S3 configuration settings.
[S3Storage "packages"]
Bucket = another-s3-bucket
Prefix = rspm-packages
Profile = dev-rspm
Region = us-west-1
EnableSharedConfig = true

---

Bucket

S3 bucket to use. Required.

Type: string

Default: <empty-string>

Prefix

Prefix to prepend to item address. This is useful for organizing a shared S3 bucket. Optional.

Type: string

Default: {StorageClass}

Profile

AWS Profile to use. AWS profiles can be defined in ~/.aws/config or ~/.aws/credentials. Optional.

Type: string

Default: <empty-string>

Region

AWS Region to use. Optional

Type: string

Default: <empty-string>

EnableSharedConfig

Overrides the AWS_SDK_LOAD_CONFIG env var value and enables the shared config functionality. Optional

Type: boolean

Default: false