Configuration#

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

Configuration Basics#

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

An example configuration file that includes all the available configuration settings along with their defaults is installed at /etc/rstudio-pm/rstudio-pm.gcfg.defaults.

File Format#

The 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 (;) or hash (#) and continue to the end of the line. Comments can be on lines by themselves or on a line with a property or section definition.

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

[Example]
A = aligator
B = 2

[Example]
A = aardvark
C = shining

[Example]
A = aardvark
B = 2
C = 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

Multi-value Properties#

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

[MultiExample]
Color = black
Color = blue

[NonMulti]
Animal = cat
Animal = dog

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

Property Types#

Configuration properties all have one of the following types:

string

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

Some parameters with type string may require a valid crontab string. For more information see the appendix section on the crontab format.

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 rspm encrypt which will output the encrypted version of the entered value. Encrypted values are tied to the Package Manager installation that generated them in most cases. For convenience and backwards compatibility, plain text values are accepted. However, in this case Package Manager will log a message on startup saying that the value should have been encrypted. See the Configuration Encryption page for more information.

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

bytesize

A value specifying the data size. When provided as a raw number, the value is interpreted as bytes. Data size values can also be specified as a sequence of decimal numbers, each with optional fraction and unit suffix such as "10MB" for 10 megabytes, "2000" for 2000 bytes, or "1GB" for 1 gigabytes.

Valid data size units are B (bytes), KB (kilobyte), MB (megabyte), GB (gigabyte), and TB (TB).

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

version

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

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 Package Manager 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 Package Manager process.

Environment Variables#

Properties can also be set by environment variables on the Package Manager process.

Environment variables all have the prefix PACKAGEMANAGER_ and are automatically determined by section, class, and property names. For example:

PACKAGEMANAGER_SERVER_PACKAGECACHESIZE=3000
PACKAGEMANAGER_GIT_POLLINTERVAL=10m
PACKAGEMANAGER_S3STORAGE_packages_BUCKET=your-s3-bucket

The first two would set the PackageCacheSize property in the Server section and the PollInterval property in the Git section, respectively. The last would set the Bucket property for the packages class in the S3Storage section.

In addition, the special PACKAGEMANAGER_ENCRYPTION_KEY environment variable can be used to specify the encryption key.

Environment variables take precedence over settings in the configuration file.

Server#

The Server section contains configuration properties which apply across the whole of 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.

Server Settings#

DataDir#

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

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

TempDir#

The directory for temporary files and directories used by R, Python, and runtime processes. It cannot be a subdirectory of Server.DataDir. If neither the TMPDIR environment variable nor this setting are configured, /tmp will be used as the default.

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

PythonVersion#

Path to a Python installation.

Type: string
Default: <empty-string>

Address#

A public URL for this Posit Package Manager server in the format of http(s)://[HOST:PORT]. If Package Manager is deployed behind an HTTP proxy, provide the URL as seen by users through the proxy. It must be configured if Package Manager is served from a subdirectory like /packagemanager/. Otherwise, it is optional and may be left blank or unset. If set, it will be used as the public URL for the PyPI package index pages, Server API documentation, and rspm url create command.

Type: string
Default: <empty-string>

ServerName#

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

Type: string
Default: <empty-string>

ReadTimeout#

The read timeout for the PPM HTTP(s) web server. Note that this is also used as the idle timeout.

Type: duration
Default: 1m

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

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

CustomHomeTitle#

Provide a custom title to customize the welcome text on the Posit Package Manager Web UI Home Page.

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

AccessLog#

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

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

AccessLogFormat#

Switch the access log format. Accepted values are combined for the Apache Combined Log Format and common for the Apache Common Log Format.

Type: string
Default: combined

ServiceLog#

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

Type: string
Default: <empty-string>

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

SockFileDir#

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

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

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

RetainFetchedPackages#

Retain source packages and binaries in persistent storage. If set to auto, packages will be retained in non-air-gapped environments. Valid values include auto, yes, and no.

Type: string
Default: auto

PackageCacheSize#

The approximate number of package requests to cache in memory for faster package serving. Must be greater than 1500.

Type: integer
Default: 16384

PackageCacheLife#

The amount of time to serve package sources and binaries based on cached information.

Type: duration
Default: 5m

MemoryCacheSize#

The amount of memory allocated for in-memory caching. Disabled when zero.

Type: memorycachesize
Default: 100MB

MemoryCacheLife#

The amount of time to cache assets in memory. If zero, lifetime is unbounded.

Type: duration
Default: 0

EvictionEnabled#

If false, eviction of all storage classes is disabled'.

Type: boolean
Default: true

EvictedStorageClasses#

The storage class(es) for which the eviction is enabled. Use a comma-separated list, including any of the following: binaries,bioconductor,cache,cran,metrics,pypi

Type: string
Default: binaries,bioconductor,cache,cran,pypi

EvictionInterval#

The interval at which stale items are evicted from persistent storage

Type: duration
Default: 1h

EvictionSweepSchedule#

The schedule for evicting any unrecorded items in persistent storage. Must be a valid crontab string. Use a blank value to disable.

Type: string
Default: 0 0 * * *

PackagesEvictionSchedule#

The schedule for evicting any orphaned packages in persistent storage. Must be a valid crontab string. Use a blank value to disable.

Type: string
Default: 30 0 * * *

ChunkLimit#

The maximum size for downloaded source packages and binaries. Downloads that exceed this size will be stored in chunks.

Type: bytesize
Default: 10MB

ChunkSize#

The chunk size for downloaded source packages and binaries that are stored in chunks.

Type: bytesize
Default: 1MB

PackageRewriteCompressionLevel#

The gzip compression level (1-9) to use when rewriting local packages. Lower values will result in better performance, but will require more disk space.

Type: integer
Default: 6

PackageRewriteBufferSize#

The size for the write buffer used when rewriting local packages.

Type: bytesize
Default: 32KB

LegacyCalendarTransactionURL#

For single-source repositories, use the old numeric identifier where applicable instead of the default hash value in the calendar URLs

Type: boolean
Default: false

Logging#

The Logging section contains configuration regarding the system log, such as setting the log path and log level.

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

Logging Settings#

SystemLog#

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

Type: string
Default: STDOUT

SystemLogLevel#

The minimum level for logging messages. In increasing order of verbosity, it can be one of: ERROR, WARNING, INFO, DEBUG, or TRACE.

Type: string
Default: INFO
Reloadable: true

SystemLogFormat#

The output format for system logs. It can be one of: TEXT, STRUCTURED, or JSON.

Type: string
Default: TEXT

Authentication#

Advanced

The Authentication section contains configuration properties that control token authentication for the Package Manager API.

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

Authentication Settings#

APITokenAuth#

Enables API token authentication for remote management.

Type: boolean
Default: true

API#

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

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

API Settings#

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

AuditLog#

The AuditLog section contains configuration properties which apply to the Package Manager Audit Log.

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

AuditLog Settings#

Enabled#

Enable audit logging.

Type: boolean
Default: false

AuditLog#

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

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

AuditLogFormat#

The output format for system logs. It can be one of: TEXT, STRUCTURED, or JSON.

Type: string
Default: JSON

Bootstrap#

The Bootstrap section contains configuration properties for creating API tokens without shell access.

Bootstrap Settings#

Enabled#

When true, enables the bootstrap functionality.

Type: boolean
Default: true

PublicKey#

A base64 encoded PEM encoded RSA public key to verify requests and encrypt responses with.

Type: string
Default: <empty-string>

Binaries#

The Binaries section contains configuration properties that control how Package Manager serves R binaries.

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

Binaries Settings#

Distributions#

The distributions for which to enable binary support. Use all to enable all distributions or a comma-separated list, such as: focal, jammy, noble, bullseye, bookworm, centos8, rhel9, opensuse155, opensuse156, macos, windows. Run rspm list distributions to list all valid distributions.

Type: string
Default: all

HTTP#

The HTTP section contains configuration properties which control the ability of Package Manager to listen for HTTP requests. 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.

HTTP Settings#

Listen#

Posit 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: :4242

NoWarning#

Disables warnings about insecure (HTTP) connections.

Type: boolean
Default: false

ForceSecure#

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

Type: boolean
Default: false

HTTPS#

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

HTTPS Settings#

Listen#

Posit 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 permitted TLS version. Allowed values are 1.0, 1.1, 1.2 or 1.3.

Type: string
Default: 1.1

HttpRedirect#

The HttpRedirect section contains configuration properties which control the ability of 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.

HttpRedirect Settings#

Listen#

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

Git#

Advanced

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

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

Git Settings#

BuilderDir#

The directory where Posit 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: {regular expression suppressed}

BuildConcurrency#

The maximum number of packages to build at one time.

Type: integer
Default: 25

BuildRetries#

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

Type: integer
Default: 3

AllowFileURLs#

Allow the use of file:// URLs for git builders. Git must be installed on the server to use file:// URLs.

Type: boolean
Default: false

ForceDescriptionVersion#

By default, branch builds will append .0.0.0.[timestamp] to the package version to ensure uniqueness. Set this to true to use the version in the DESCRIPTION file and replace any existing packages with the same version.

Type: boolean
Default: false

AllowTagVersionMismatch#

By default, Git tags versions must match the DESCRIPTION file version. Set this to true to use the version in the DESCRIPTION file regardless of the Git tag.

Type: boolean
Default: false

AttemptVignettes#

When set to true, the Git build process will attempt to build vignettes for R packages. If the vignette build fails, the process will automatically fallback to using the --no-build-vignettes option.

Type: boolean
Default: false

AllowUnsandboxedGitBuilds#

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

Type: boolean
Default: false

PyPIRepoURL#

By default, Python git builders will pull package dependencies from PyPI. Set this option to a PyPI simple index URL to pull dependencies from a different location.

Type: string
Default: <empty-string>

Metrics#

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

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

Metrics Settings#

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

ReadTimeout#

The read timeout for the PPM HTTP(s) metrics server. Note that this is also used as the idle timeout.

Type: duration
Default: 1m

WriteTimeout#

The write timeout for the PPM HTTP(s) metrics server.

Type: duration
Default: 5m

Licensing#

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

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

Licensing Settings#

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: 10s
Reloadable: true

DisableExpiryBanner#

Disable license expiration warning banner.

Type: boolean
Default: false

ExpiryDaysReminder#

The default threshold in days to show license expiration banner.

Type: integer
Default: 30

Support#

The Support section contains configuration properties which control how Package Manager broadcasts its support window.

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

Support Settings#

DisableExpiryBanner#

Disable support window warning banner.

Type: boolean
Default: false

ExpiryDaysReminder#

The default threshold in days to show support window expiration banner.

Type: integer
Default: 90

Manifest#

Advanced

The Manifest section contains configuration properties related to the general Manifest source configurations (CRAN, Bioconductor, PyPI) in Package Manager.

Manifest Settings#

URL#

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

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

User#

The user to be used in an Authorization HTTP(S) header.

Type: string
Default: <empty-string>

Password#

The encrypted password to be used in an Authorization HTTP(S) header.

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

AllowRedirect#

Supports 307 redirects to the underlying package repositories. This enables the ability for users to download packages directly from the URL location without passing through Package Manager and caching locally. This can both significantly improve package serving performance and reduce storage usage. The end user's system needs outbound internet access to the URL location (by default this is the Posit Package Service, http://rspm-sync.rstudio.com). This is not always feasible depending on the network configuration. Redirects are supported by both R's install.packages() and the Python's pip by default, but if using a non-default download method in R such as curl, you will have to add the download options to follow redirects for that particular method.

Type: boolean
Default: false

CRAN#

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

CRAN Settings#

CRANTimeout#

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

Type: duration
Default: 30m

FetchTimeout#

The timeout for downloading a CRAN package tarball.

Type: duration
Default: 10m

DelaySyncDuration#

The time duration for delaying the CRAN synchronization by a certain number of [hours|days].

Type: duration
Default: 0

Bioconductor#

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

Bioconductor Settings#

ManifestURL#

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

Type: string
Default: https://rspm-sync.rstudio.com/bioc

SyncSchedule#

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

Type: string
Default: 0 0 * * *
Reloadable: true

EnabledVersions#

Bioconductor versions that are created automatically when syncing. When unset, all supported Bioconductor versions are created automatically when syncing if a Bioconductor repo exists.

Type: multi-string
Default: unspecified

Timeout#

The timeout for downloading snapshots or changes (JSON) from the Bioconductor manifest

Type: duration
Default: 30m

FetchTimeout#

The timeout for downloading a Bioconductor package tarball.

Type: duration
Default: 10m

DelaySyncDuration#

The time duration for delaying the Bioconductor synchronization by a certain number of [hours|days].

Type: duration
Default: 0

PyPI#

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

PyPI Settings#

Timeout#

The timeout for downloading snapshots or changes (JSON) from the PyPI manifest

Type: duration
Default: 30m

DownloadConcurrency#

Deprecated: Maximum number of goroutines downloading PyPI JSON from the manifest URL.

Type: integer
Default: 0

DownloadRetryLimit#

Maximum number of times to try downloading PyPI JSON from the manifest URL. Must be between 1 and 50.

Type: integer
Default: 10

FetchTimeout#

The timeout for downloading a PyPI package.

Type: duration
Default: 10m

DelaySyncDuration#

The time duration for delaying the PyPI synchronization by a certain number of [hours|days].

Type: duration
Default: 0

Database#

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

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

Database Settings#

Provider#

The type of database to use. Must be either sqlite for SQLite or postgres for PostgreSQL.

Type: string
Default: sqlite

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

ConnectionTimeout#

The maximum amount of time to wait for a response while connecting to the database. If this value is less-than or equal-to zero, then connections can hang forever.

Type: duration
Default: 60s

SQLite#

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

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

Sqlite Settings#

Dir#

The directory containing the Posit 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

NoNFSCheck#

When enabled, allows using SQLite on an NFS mount. Should only be used in rare circumstances since using SQLite on an NFS mount can lead to data corruption.

Type: boolean
Default: false

PostgreSQL#

The Postgres section contains configuration properties which control the location of and how Package Manager interacts with a PostgreSQL database.

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

Postgres Settings#

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: {Postgres.URL}

Password#

The encrypted password to be used for the URL setting.

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

UsageDataPassword#

The encrypted password to be used for the UsageDataURL setting.

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

OfflineOnUpgrade#

When true, starts up in offline mode after an upgrade or initial installation

Type: boolean
Default: false

PostgresPool#

The PostgresPool section contains configuration properties which control the location of and how 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 PostgreSQL Pool will be used for interactions with Postgres Large Object storage.
• Notifications - An Package Manager cluster uses PostgreSQL NOTIFY/LISTEN messaging to support intra-node communication. The PostgreSQL Pool will be used for this feature.

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

PostgresPool Settings#

MaxOpenConnections#

The maximum number of open connections to the Postgres connection pool. This needs to be either greater than or equal to 10, or 0 for unlimited open connections.

Type: integer
Default: 10

Proxy#

The Proxy section contains configuration properties which allow the Package Manager to use an outbound proxy server. The URL configured here will be used for all HTTP requests and HTTPS requests.

[Proxy]
URL = 127.0.0.1:80

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

Proxy Settings#

URL#

Set the proxy URL for outbound traffic. May be either a complete URL or a host[:port], in which case the http scheme is assumed.

Type: string
Default: <empty-string>

User#

The user to be used in a Proxy-Authorization HTTP(S) header.

Type: string
Default: <empty-string>

Password#

The encrypted password to be used in a Proxy-Authorization HTTP(S) header.

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

Storage#

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

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

Storage Settings#

Default#

Storage default for all storage classes unless otherwise overridden. Must be either file or S3.

Type: string
Default: file

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

CRAN#

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

Type: string
Default: file

Bioconductor#

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

Type: string
Default: file

PyPI#

Storage location for PyPI 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

Persistent#

Storage location for data that should never be deleted. Must be either file or S3.

Type: string
Default: file

StorageAudit#

The StorageAudit section allows you to configure auditing which can be exported using the metrics endpoint. This can also be used in combination with the StorageAlerts section to enable alerts based on usage thresholds.

StorageAudit is enabled by default, but may be disabled if you do not require this functionality.

StorageAudit Settings#

CacheTimeout#

The minimum time between querying for filesystem usage. For large filesystems this can be a time-consuming operation.

Type: duration
Default: 1d

Enabled#

Enable storage auditing. This will periodically check and report on system usage.

Type: boolean
Default: true

StorageAlerts#

The StorageAlerts section allows customizable alerting thresholds based on a fixed size or a percentage basis. Use [StorageAlerts] to set default values or use FileStorage classes to override a specific storage location. For example, [StorageAlerts "cran"]

Alerting is enabled by default, but it can be customized or disabled completely depending on your needs. Alerting is currently supported only for FileStorage classes.

The alerting process will recursively check the free and used size of the disk on which the specified directory is mounted. For example, if your FileStorage is configured as follows, the alerting process will scan the disk on which /path/to/cran resides and report on the results.

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

[StorageAlerts "cran"]
Threshold = 75%

All options are as follows.

[StorageAlerts]
; Enable UI alerts of type 'raw', 'safe', 'name' or disable with 'none'
; UIMessageType = safe
;
; Set a default for each underlying storage class.
; Can be a fixed size such as "10GB" or a percent like "90%"
; Disable by using 0, 0GB, 0% or not setting.
;
; The default alert threshold is 90%. Alerts will shown when storage usage
; exceeds this value.
; Threshold = 90%
;
; Optionally specify thresholds for individual FileStorage classes.
; These function as overrides for the default. Disable using
; one of the "0" values described above.
;
; [StorageAlerts "cache"]
; Threshold = 10GB
;
; [StorageAlerts "cran"]
; Threshold = 75%
;
; [StorageAlerts "packages"]
; Threshold = 0

StorageAlerts Settings#

Threshold#

The default storage alerting threshold. Alerts will shown when storage usage exceeds this value. May be either a percentage or a size. Must end with a '%' or a size 'GB'. For example 90% or 200GB. Leave empty to disable. Can be overridden for class-specific thresholds.

Type: string
Default: 90%

UIMessageType#

The type of message to present to the Posit Package Manager Web UI. Must be one of 'raw' (the full message with details), 'safe' (a message without specific filesystem paths or threshold amounts), 'name' (the name of the filesystem storage class only) or 'none' (hidden from the UI). This setting cannot be overridden by class-specific configuration. Note, the server log will always contain the raw alert value.

Type: string
Default: name

FileStorage#

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

• binaries
• bioconductor
• cache
• cran
• metrics
• packages
• persistent
• pypi

If you wish to change the base storage location for all 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:

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

FileStorage Settings#

Location#

The directory to use for this storage class.

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

S3Storage#

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

• binaries
• bioconductor
• cache
• cran
• metrics
• packages
• persistent
• pypi

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

[Storage]
Default = 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

Alternatively, you can specifiy each variable data class separately:

[Storage]
Binaries = s3
Bioconductor = s3
Cache = s3
CRAN = s3
Metrics = s3
Packages = s3
Persistent = s3
PyPI = s3

[S3Storage]
Bucket = your-s3-bucket

S3Storage Settings#

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. This can also be defined through environment variables, the shared credentials file, or through the shared configuration file (if SharedConfig is enabled). Optional.

Type: string
Default: <empty-string>

Region#

AWS Region to use. This can also be defined through environment variables, the shared credentials file, or through the shared configuration file (if SharedConfig is enabled).

Type: string
Default: <empty-string>

KMSKeyID#

The AWS KMS ID to use for client-side S3 encryption. Note that this is NOT backwards compatible with existing installations. 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

EvictionPolicy#

Eviction policies can be used to keep server disk usage to a minimum. The Server.EvictedStorageClasses setting enables general eviction, however the EvictionPolicy section allows custom control of the objects in each class. You can configure a default EvictionPolicy section to control the lifetime of every cache object, or create custom EvictionPolicy sections for six classes of data if you need fine-grained control:

• binaries
• bioconductor
• cache
• cran
• metrics
• pypi

The following Server Configuration settings control when evictions occur. These settings correspond to the types of evictions enumerated below.

• Server.EvictionInterval
• Server.EvictionSweepSchedule
• Server.PackagesEvictionSchedule

Normal Eviction

• Runs at intervals defined by Server.EvictionInterval, and removes any assets in storage that have a last recorded access time that is older than the MaxAge setting for the storage class. The last recorded access times are stored in the Package Manager database and managed by the Package Manager service.

Sweep Eviction

• Removes orphaned items by enumerating all assets in persistent storage and deleting any for which we have no corresponding database record. A "sweep" eviction is more time consuming, and it runs on the schedule defined by Server.EvictionSweepSchedule.

Packages Eviction

• Removes orphaned packages for local, git, and Curated CRAN sources by enumerating all assets in persistent storage and deleting any for which we have no corresponding database record.

Example:

[Server]
EvictedStorageClasses = "cache, metrics, cran, binaries"
EvictionInterval = 1h
EvictionSweepSchedule = "30 2 * * *"

; Defaults
[EvictionPolicy]
MaxAge = 720h

; Override for a specific persistent storage class
[EvictionPolicy "binaries"]
MaxAge = 300h

EvictionPolicy Settings#

MaxAge#

The duration of no access after which a file from a persistent class is considered stale.

Type: duration
Default: 30d

Exceptions#

A regular expression whose matches will not be evicted from persistent storage unless orphaned. To ignore default exceptions and use no exceptions for a particular storage class, use the string none.

Type: multi-string
Default: unspecified

Migration#

The Migration section contains configuration properties that control the migrations that occur upon upgrading to a new Package Manager version.

Migration Settings#

EnableMixedClassMigration#

Enables migration of CRAN packages to another storage class.

Type: boolean
Default: false

Swagger#

The Swagger section contains configuration properties that control the Server API documentation page served by the server.

Swagger Settings#

Enabled#

If true, enables serving the Swagger Server API Guide over the API.

Type: boolean
Default: true

Host#

Set the domain name or IP address of the host that serves the Server API Guide. Defaults to the host in Server.Address if set.

Type: string
Default: <empty-string>

BasePath#

Set the URL prefix for all API paths, relative to the host. It must start with a leading slash. Defaults to the path in Server.Address if set.

Type: string
Default: <empty-string>

HTTP#

Controls displaying the HTTP schema option on the Server API Guide page. Does not change any server options.

Type: boolean
Default: false

HTTPS#

Controls displaying the HTTPS schema option on the Server API Guide page. Does not change any server options.

Type: boolean
Default: false

Vulnerabilities#

The Vulnerabilities section contains configuration properties that control the vulnerability reporting and syncing functionality of Package Manager.

Vulnerabilities Settings#

Enabled#

Enable vulnerabilities syncing.

Type: boolean
Default: true

FetchTimeout#

The timeout for downloading vulnerability data.

Type: duration
Default: 10m

Debug#

The Debug section contains configuration properties that control the logging behavior of the server.

Debug Settings#

ReadTimeout#

The read timeout for the PPM HTTP(s) debug server. Note that this is also used as the idle timeout.

Type: duration
Default: 1m

WriteTimeout#

The write timeout for the PPM HTTP(s) debug server.

Type: duration
Default: 5m