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.
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
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
setting implements prop:procedure. For an instance S:
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
(define-setting PICKED_NUMBER (integer-in 0 100) 0)
8.2 Runtime Configuration
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.
Do nothing. Every setting has a hard-coded default.
Set an environment variable, e.g. export XIDEN_VERBOSE="#t".
Open an rcfile and add (define XIDEN_VERBOSE #t).
When applicable, use --XIDEN_VERBOSE '#t' in a command line (or an alternative flag).
In a program, use (XIDEN_VERBOSE #t (lambda () ...)).
8.2.2 Runtime Configuration Files
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
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
8.2.3 Runtime Configuration API
A hash table of all defined settings
, such that the key for
each setting is (setting-id S)
Each call to call-with-rcfile reads the content of the
target rcfile into memory.
8.2.4 Setting Reference
These are the defined settings for Xiden, along with their default
values and command-line flags.
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.
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
CLI Flags: +s/++install-source/--XIDEN_INSTALL_SOURCES
Defines installations in a transaction.
Each list in XIDEN_INSTALL_SOURCES consists of three strings:
The path to a symbolic link to create with respect to (current-directory).
The name of a desired output from a package definition.
A URL, file path, or plugin-specific string used to find the package definition.
CLI Flags: +a/++install-abbreviated/--XIDEN_INSTALL_ABBREVIATED_SOURCES
, except each item in the list only needs to
be a URL, file path, or plugin-specific string used to find the package
. The symbolic link name is assumed to be the string bound to
in the definition, and the output is assumed to be
CLI Flags: +d/++install-default/--XIDEN_INSTALL_DEFAULT_SOURCES
The path of a symbolic link to create with respect to (current-directory).
A URL, file path, or plugin-specific string used to find the package definition.
The output is assumed to be "default".
CLI Flags: -X/--plugin/--XIDEN_PLUGIN_MODULE
When not #f
, the given module path will be used in dynamic-require
to load extensions.
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
CLI Flags: +x/++trust-exe/++trust-executable/--XIDEN_TRUSTED_EXECUTABLES
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
CLI Flags: +t/++trust-host-executable/--XIDEN_TRUSTED_HOST_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.
CLI Flags: -F/--fasl-output/--XIDEN_FASL_OUTPUT
CLI Flags: -R/--reader-friendly-output/--XIDEN_READER_FRIENDLY_OUTPUT
When true, each program output value v
is printed on STDOUT using
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.
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.
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.
CLI Flags: -p/--fetch-pkgdef-size/--XIDEN_FETCH_PKGDEF_SIZE_MB
CLI Flags: -d/--fetch-timeout/--XIDEN_FETCH_TIMEOUT_MS
The maximum number of seconds to wait for the next available byte from a
CLI Flags: -v/--verbose/--XIDEN_VERBOSE
When true, emit more detailed program output.
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
"PATH" is included regardless of the value of this setting.
CLI Flags: -r/--subprocess-timeout/--XIDEN_SUBPROCESS_TIMEOUT_S
The maximum number of seconds a subprocess spawned by a package
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
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
CLI Flags: -g/--generated-input-name/--XIDEN_GENERATED_INPUT_NAME
CLI Flags: --byte-encoding/--XIDEN_BYTE_ENCODING
The encoding to use when generating byte expressions.
CLI Flags: --md/--XIDEN_MESSAGE_DIGEST_ALGORITHM
The algorithm to use when creating digests on user request.
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
Xiden will attempt to sign input expressions when at least a public
key source and private key is available.