On this page:
8.1 Settings
setting
define-setting
call-with-applied-settings
8.2 Runtime Configuration
8.2.1 Changing a Runtime Configuration Value
8.2.2 Runtime Configuration Files
8.2.3 Runtime Configuration API
XIDEN_  SETTINGS
call-with-rcfile
dump-xiden-settings
8.2.4 Setting Reference
XIDEN_  MEMORY_  LIMIT_  MB
XIDEN_  TIME_  LIMIT_  S
XIDEN_  INSTALL_  SOURCES
XIDEN_  INSTALL_  ABBREVIATED_  SOURCES
XIDEN_  INSTALL_  DEFAULT_  SOURCES
XIDEN_  PLUGIN_  MODULE
XIDEN_  TRUST_  UNSIGNED
XIDEN_  TRUST_  BAD_  SIGNATURE
XIDEN_  TRUST_  UNVERIFIED_  HOST
XIDEN_  TRUST_  BAD_  DIGEST
XIDEN_  TRUST_  ANY_  EXECUTABLE
XIDEN_  TRUST_  ANY_  PUBLIC_  KEY
XIDEN_  TRUSTED_  PUBLIC_  KEYS
XIDEN_  TRUSTED_  EXECUTABLES
XIDEN_  TRUSTED_  HOST_  EXECUTABLES
XIDEN_  FASL_  OUTPUT
XIDEN_  READER_  FRIENDLY_  OUTPUT
XIDEN_  FETCH_  TOTAL_  SIZE_  MB
XIDEN_  FETCH_  BUFFER_  SIZE_  MB
XIDEN_  FETCH_  PKGDEF_  SIZE_  MB
XIDEN_  FETCH_  TIMEOUT_  MS
XIDEN_  VERBOSE
XIDEN_  CATALOGS
XIDEN_  DOWNLOAD_  MAX_  REDIRECTS
XIDEN_  ALLOW_  UNSUPPORTED_  RACKET
XIDEN_  ALLOW_  ENV
XIDEN_  SUBPROCESS_  TIMEOUT_  S
XIDEN_  INPUT_  OVERRIDES
XIDEN_  GENERATED_  INPUT_  NAME
XIDEN_  BYTE_  ENCODING
XIDEN_  MESSAGE_  DIGEST_  ALGORITHM
XIDEN_  SIGNER
8.0

8 Configuration

Xiden dynamically binds configurable values using settings when launched. A runtime configuration is a parameterization in which every setting defined by xiden/rc is bound to a value that cannot be overridden except by another parameterization.

8.1 Settings

 (require xiden/setting) package: xiden

A setting is an instance of the setting structure. Settings are used as a canonical source of dynamically bound values, along with validation information and contextual help.

struct

(struct setting (id valid? parameter derived-parameter))

  id : symbol?
  valid? : predicate/c
  parameter : parameter?
  derived-parameter : parameter?
Defines a setting. You likely do not need to create an instance directly because the constructor does not enforce a meaningful structural relationship between the fields. Use define-setting instead.

setting implements prop:procedure. For an instance S:

syntax

(define-setting id contract-expr default-expr)

Binds a new setting to id.

contract-expr must evaluate to a flat contract. Any attempt to install a value in the setting that does not pass this contract will fail.

default-expr must evaluate to either a (-> symbol? any/c) procedure, or a non-procedure. The procedure form must accept id (as a symbol) as the sole formal argument and return a default value.

(define-setting PICKED_NUMBER (integer-in 0 100) 0)

procedure

(call-with-applied-settings settings thunk)  any

  settings : 
(if/c hash?
      (hash/c setting? any/c)
      (listof (cons/c setting? any/c)))
  thunk : (-> any)
Applies thunk in a parameterization where each setting in settings is bound to a new value.

(define-setting USERNAME string? "")
(define-setting PASSWORD string? "")
(call-with-applied-settings (hasheq USERNAME "insecure" PASSWORD "hunter2") PASSWORD)
(call-with-applied-settings (list (cons USERNAME "insecure") (cons PASSWORD "hunter2")) PASSWORD)

8.2 Runtime Configuration

 (require xiden/rc) package: xiden

xiden/rc provides several settings that change how Xiden behaves. This section documents each setting with its command-line flags, contract, and default value.

8.2.1 Changing a Runtime Configuration Value

Here are the ways one can change a setting. Each method overrides the method before it.

8.2.2 Runtime Configuration Files

 #lang xiden/rcfile package: xiden

A runtime configuration file, or rcfile, is a xiden/rcfile Racket module. It defines values for a runtime configuration using identifiers that match the setting-id of each defined setting. e.g. (define XIDEN_VERBOSE #t).

The target runtime configuration file, or target rcfile, is located at etc/xiden.rkt with respect to the target workspace.

The xiden/rcfile collection path can be used as a module language or as a reader extension.

The grammar is a superset of setup/infotab, or the info language. It includes the following bindings:

8.2.3 Runtime Configuration API

value

XIDEN_SETTINGS : (hash/c symbol? setting? #:immutable #t)

A hash table of all defined settings, such that the key for each setting is (setting-id S).

procedure

(call-with-rcfile thunk)  any

  thunk : (-> any)
Calls thunk in a parameterization where fallback values for settings consider values from the target rcfile.

Each call to call-with-rcfile reads the content of the target rcfile into memory.

Returns a hash table containing the value of every setting in XIDEN_SETTINGS in the current parameterization.

8.2.4 Setting Reference

These are the defined settings for Xiden, along with their default values and command-line flags.

setting

XIDEN_MEMORY_LIMIT_MB : (>=/c 0) = 200

CLI Flags: -M/--memory-limit/--XIDEN_MEMORY_LIMIT_MB
Defines a memory limit for a custodian managing process resources, in mebibytes. If this is too low, then it is possible for Xiden to halt due to a forced custodian shutdown.

Does not count memory charged when parsing the command line and setting up a runtime configuration.

Has no effect if the running Racket installation does not support per-custodian memory accounting.

setting

XIDEN_TIME_LIMIT_S : (>=/c 0) = 300

CLI Flags: -S/--time-limit/--XIDEN_TIME_LIMIT_S
Sets a time limit for a Xiden process, in seconds. Does not count time spent parsing the command line and setting up a runtime configuration.

CLI Flags: +s/++install-source/--XIDEN_INSTALL_SOURCES
Defines installations in a transaction.

Each list in XIDEN_INSTALL_SOURCES consists of three strings:

  1. The path to a symbolic link to create with respect to (current-directory).

  2. The name of a desired output from a package definition.

  3. A URL, file path, or plugin-specific string used to find the package definition.

CLI Flags: +a/++install-abbreviated/--XIDEN_INSTALL_ABBREVIATED_SOURCES
Like XIDEN_INSTALL_SOURCES, except each item in the list only needs to be a URL, file path, or plugin-specific string used to find the package definition. The symbolic link name is assumed to be the string bound to package in the definition, and the output is assumed to be "default".

CLI Flags: +d/++install-default/--XIDEN_INSTALL_DEFAULT_SOURCES
Like XIDEN_INSTALL_SOURCES, except each list only needs two strings:

  1. The path of a symbolic link to create with respect to (current-directory).

  2. A URL, file path, or plugin-specific string used to find the package definition.

The output is assumed to be "default".

setting

XIDEN_PLUGIN_MODULE : (or/c #f path-string?) = #f

CLI Flags: -X/--plugin/--XIDEN_PLUGIN_MODULE
When not #f, the given module path will be used in dynamic-require to load extensions.

setting

XIDEN_TRUST_UNSIGNED : boolean? = #f

CLI Flags: -U/--trust-unsigned/--XIDEN_TRUST_UNSIGNED
Dangerous. When true, trust any input that lacks a signature.

CLI Flags: -T/--trust-bad-signature/--XIDEN_TRUST_BAD_SIGNATURE
Dangerous. When true, trust any input that has a signature that does not match the input’s integrity information.

CLI Flags: -H/--trust-any-host/--XIDEN_TRUST_UNVERIFIED_HOST
Dangerous. When true, trust any server that was not authenticated using available certificates.

CLI Flags: -Y/--trust-any-digest/--XIDEN_TRUST_BAD_DIGEST
Dangerous. When true, trust any input.

CLI Flags: --trust-any-exe/--XIDEN_TRUST_ANY_EXECUTABLE
Dangerous. When true, allow the Racket runtime to start a subprocess with any executable.

CLI Flags: --trust-any-pubkey/--XIDEN_TRUST_ANY_PUBLIC_KEY
Dangerous. When true, trust any public key used to verify a signature.

CLI Flags: +p/++trust-public-key/--XIDEN_TRUSTED_PUBLIC_KEYS
A list of integrity information used to verify public keys. If a public key fetched for an input passes the integrity check for an element of XIDEN_TRUSTED_PUBLIC_KEYS, then the public key is considered trustworthy.

CLI Flags: +x/++trust-exe/++trust-executable/--XIDEN_TRUSTED_EXECUTABLES
Like XIDEN_TRUSTED_PUBLIC_KEYS, but used to verify executables a package tries to use when creating a subprocess.

Beware: Any executable listed here inherits the OS-level permissions of the process, and is not subject to the restrictions of a Xiden runtime configuration. If you include a Xiden launcher or a sufficiently flexible Racket launcher, a package can start a new Xiden process with a full-trust configuration.

CLI Flags: +t/++trust-host-executable/--XIDEN_TRUSTED_HOST_EXECUTABLES
Like XIDEN_TRUSTED_EXECUTABLES, except this setting is a list of names. Xiden will allow execution of a file if its normalized path equals the value of find-executable-path for an element of that list. You may need to add multiple entries to account for extension differences across platforms.

This can be helpful in the event a package depends on access to an executable on the host system and there is no way to control the content of that executable.

The find-executable-path restriction is meant to prevent packages from creating and then immediately running their own executables just because they have a name in this list. Even so, this can be a dangerous setting, and should only be used if you trust both the package definition and the executables on your system. It’s also why PATH should not include a build directory.

Regardless of the setting’s actual value, Xiden implicitly considers "openssl" an element of its list. The user is therefore responsible for the integrity of their OpenSSL instance.

setting

XIDEN_FASL_OUTPUT : boolean? = #f

CLI Flags: -F/--fasl-output/--XIDEN_FASL_OUTPUT
When true, each value v printed on STDOUT is first transformed using (s-exp->fasl (serialize v)).

CLI Flags: -R/--reader-friendly-output/--XIDEN_READER_FRIENDLY_OUTPUT
When true, each program output value v is printed on STDOUT using pretty-write without being translated to a human-readable message.

Use this to produce (read)able logs. If it aids read performance, combine with XIDEN_FASL_OUTPUT.

setting

XIDEN_FETCH_TOTAL_SIZE_MB : (or/c +inf.0 real?) = 100

CLI Flags: -m/--fetch-total-size/--XIDEN_FETCH_TOTAL_SIZE_MB
The maximum total size of a single download allowed when fetching an input from a source, in mebibytes.

setting

XIDEN_FETCH_BUFFER_SIZE_MB : (real-in 0.1 20) = 10

CLI Flags: -n/--fetch-buffer-size/--XIDEN_FETCH_BUFFER_SIZE_MB
The maximum number of bytes to read at a time from a source, in mebibytes.

setting

XIDEN_FETCH_PKGDEF_SIZE_MB : (real-in 0.1 20) = 0.1

CLI Flags: -p/--fetch-pkgdef-size/--XIDEN_FETCH_PKGDEF_SIZE_MB
Like XIDEN_FETCH_TOTAL_SIZE_MB, except the quota only applies to package definitions named in a user-defined transaction. This quote does not apply to package definitions listed as inputs in another package definition.

setting

XIDEN_FETCH_TIMEOUT_MS : (real-in 100 10000) = 3000

CLI Flags: -d/--fetch-timeout/--XIDEN_FETCH_TIMEOUT_MS
The maximum number of seconds to wait for the next available byte from a source.

setting

XIDEN_VERBOSE : boolean? = #f

CLI Flags: -v/--verbose/--XIDEN_VERBOSE
When true, emit more detailed program output.

setting

XIDEN_CATALOGS : (listof url-string?)

 = ("https://zcpkg.com/$QUERY")
CLI Flags: +h/++host/--XIDEN_CATALOGS
A list of strings representing URL templates.

This setting affects the output of from-catalogs.

CLI Flags: -o/--max-redirects/--XIDEN_DOWNLOAD_MAX_REDIRECTS
The maximum number of HTTP redirects to follow when resolving a GET request.

CLI Flags: -G/--assume-support/--XIDEN_ALLOW_UNSUPPORTED_RACKET
When true, continue installing when a package definition declares that it does not support the running Racket version.

CLI Flags: +e/++env/++envvar/--XIDEN_ALLOW_ENV
Names of environment variables visible to packages, and Xiden subprocesses.

"PATH" is included regardless of the value of this setting.

setting

XIDEN_SUBPROCESS_TIMEOUT_S : (>=/c 0) = 1800

CLI Flags: -r/--subprocess-timeout/--XIDEN_SUBPROCESS_TIMEOUT_S
The maximum number of seconds a subprocess spawned by a package may live.

CLI Flags: +o/++input-override/--XIDEN_INPUT_OVERRIDES
A list of strings used to define package input overrides.

Each element is in the form (cons pattern input-expr). The input of name input-name is replaced with the (evaluated) input-expr for all package queries matching pattern.

If pattern is a string, then it is used as an argument to pregexp before matching. If pattern is a symbol, then it is first coerced to a string and then used as an argument to pregexp.

setting

XIDEN_GENERATED_INPUT_NAME : string? = "default"

CLI Flags: -g/--generated-input-name/--XIDEN_GENERATED_INPUT_NAME
The name to use for generated package input code.

setting

XIDEN_BYTE_ENCODING

 : (or/c 'base64 'base32 'hex 'colon-separated-hex)
 = base64
CLI Flags: --byte-encoding/--XIDEN_BYTE_ENCODING
The encoding to use when generating byte expressions.

setting

XIDEN_MESSAGE_DIGEST_ALGORITHM

 : (or/c 'md4 'md5 'sha1 'sha224 'sha256 'sha3-224 'sha3-256 'sha3-384 'sha3-512 'sha384 'sha512 'sha512-224 'sha512-256)
 = sha384
CLI Flags: --md/--XIDEN_MESSAGE_DIGEST_ALGORITHM
The algorithm to use when creating digests on user request.

setting

XIDEN_SIGNER

 : (list/c (or/c #f string?) (or/c #f path-string?) (or/c #f path-string?))
 = (#f#f#f)
CLI Flags: --signer/--XIDEN_SIGNER
A list containing, in order, a source for a public key, a path to a private key file, and a path to a file containing the password for the private key. Any element can be #f to indicate absense.

Xiden will attempt to sign input expressions when at least a public key source and private key is available.