Config
Categories:
Configuration Sources
Configuration is performed using a JSON/Jsonnet configuration file, environment variables, and command line arguments. Configurations from one source will override previous sources, i.e. environment variables override configuration files, command line arguments override environment variables.
Command Line
Every configuration key can be set using -x <a_config_key1>="a value" -x <a_config_key2>="another value"
, i.e. -x cli_logLevel=debug -x cli_logFormat=kv
. Config values can also be set using JSON, i.e. -x cli='{"logLevel": "debug"}'
Command line values override all other sources.
Environment Variables
Every configuration key can be set using rot_section_key=a value
or ROT_section_key=a value
, i.e. rot_cli_logLevel=debug
. A special environment variable, rot_config
can be used to specify a complete JSON/Jsonnet configuration.
Environment Variables override a configuration file.
Configuration File
A configuration file be formatted using JSON or Jsonnet. Rot looks for rot.jsonnet
by default, ascending the directory tree to find it. See the Jsonnet reference for more information. Configuration files are rendered at startup, allowing you to use dynamic Jsonnet functions to dynamically alter the config, i.e.:
local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');
{
cli: [
logLevel: level,
],
}
You can view the rendered configuration by running rot config
.
Configuration Values
build
pushDomainSuffix
String, a domain suffix to append to all targets
for hostname resolution.
Default: ""
pushMaxWorkers
Integer, the number of worker threads to use for pushing Patterns to targets.
Default: Number of CPUs
signingCommands
(recommended)
License Required
This requires an Unlimited LicenseList of Commands to run when signing a JWT instead of using a signingKey
. See Building Patterns for more information.
Default: []
signingExec
Exec configuration for running signingCommands
.
Default: {}
signingKey
(recommended)
String, the cryptographic signing key to use when signing JWTs. See Building Patterns for more information.
Default: ""
signingKeyPath
(recommended)
String, a path to a cryptographic signing key to use when signing JWTs. See Building Patterns for more information. If specified as just a filename, Etcha will ascend directories until it finds a matching filename. Can be used to provide keys used with Rot.
Default: ""
tlsCABase64
(recommended)
String, base64 encoded PEM certificate used by etcha push
and etcha shell
to validate Etcha endpoints. If this or tlsCAPath
is not specified, Etcha will use the system CA certificates to validate certificates.
Default: ""
tlsCAPath
(recommended)
String, base64 encoded PEM certificate used by etcha push
and etcha shell
to validate Etcha endpoints. If this or tlsCABase64
is not specified, Etcha will use the system CA certificates to validate certificates.
Default: false
tlsSkipVerify
Boolean, skip TLS verification when running etcha push
.
Default: false
cli
configPath
String, path to the configuration file. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.
Default: ".jsonnet"
logFormat
String, log format to use for logging: human, kv, or raw.
Default: "human"
logLevel
String, log level to use for logging: none, debug, info, or error.
Default: "info"
macros
A map of macros to simplify and template CLI arguments. An example macro looks like this:
{
"cli": {
"macro": {
"mymacro": {
"argumentsRequired": [
"argument1"
],
"flags": {
"d": {
"usage": "D flag usage!"
},
},
"template": "config",
"usage": "Mymacro usage!",
}
}
}
}
This will add the macro, mymacro
to the CLI.
Default: {}
argumentsRequired
A list of arguments that are required for the macro.
Default: []
argumentsOptional
A list of arguments that are optional for the macro.
Default: []
flags
A map of flags for the macro.
Default: {}
default
A list of strings for the default value of the flag.
Default: []
options
A list of strings the flag can be set to.
Default: []
placeholder
String, the placeholder name for the flag if it accepts a value.
Default: ""
usage
String, the usage instructions for the flag.
Default: ""
template
String, the Go template syntax that will be rendered, appended to the CLI, and ran. The Go template can use these custom functions:
{{ getArg i int f string }}
Get an argument at positioni
or return fallbackf
.{{ getEnv e string f string }}
Get an environment variablee
or return fallbackf
.{{ getFlag f string }}
Get the flag values forf
. For flags with a placeholder, this will be an array of string values, otherwise it will be a boolean.{{ join s []string sep string }}
Join arrays
with separatorsep
.
Default: []
usage
String, the usage documentation for a macro.
Default: ""
noColor
Boolean, disables colored log output.
Default: false
noPaging
Boolean, disables paging of log output using less
.
Default: false
exec
The main exec
configuration. Can be overridden by other configurations. The format for all exec
configurations is below. The defaults for the main exec
are:
{
"allowOverride": true,
"command": "/usr/bin/bash -e -o pipefail -c",
}
allowOverride
Boolean, enables this Exec environment to be overridden by other Exec configurations. The entire Exec configuration will be overridden, no partial overrides. Exec overrides may be deeply nested, like this:
flowchart LR commandExec["command exec"] patternExec["pattern runExec"] sourceExec["source exec"] exec --> sourceExec sourceExec --> patternExec patternExec --> commandExec
Every exec in the path needs to allow overrides for command exec to be allowed.
Default: false
command
String, the command to run before any Commands. If this is specified, other commands will be added after it. You’d typically put a shell interpreter in here, like /usr/bin/bash -c
.
Default: ""
containerEntrypoint
String, override the container entrypoint for the containerImage
.
Default: ""
containerImage
String, the container image to use. If specified, command
, env
, and workDir
will be passed/ran in a container.
Default: ""
containerNetwork
String, the container network to use. Defaults to the default network for the container runtime.
Default: ""
containerPrivileged
Boolean, run the container as a privileged container.
Default: false
containerPull
String, the container pull policy.
Default: ""
containerUser
String, the container user or UID.
Default: ""
containerVolumes
List of strings, the volumes to map into the container.
Default: []
containerWorkDir
String, override the WorkDir of a container.
Default: ""
env
Map of strings in the format "ENVIRONMENT": "value"
, will set these as environment variables.
Default: {}
envInheirt
Boolean, whether to inherit the environment of the main Etcha process.
Default: false
group
String, the group or GID to run the commands with. Using this is typically privileged and requires root or extra capabilities.
Default: ""
sudo
Bool, will check if user is root and run the Commands using sudo -E
if the user is not root.
Default: false
user
String, the user or UID to run the commands with. Using this is typically privileged and requires root or extra capabilities.
Default: ""
workDir
String, the working directory to execute commands within.
Default: ""
jsonnet
Configuration toggles for disabling Jsonnet Native Functions. Some of these functions are disabled by default–namely anything that could perform an external call, like running a command, or performing HTTP or DNS requests. These should only be enabled for Jsonnet files you trust, as they could lead to data exfiltration or worse.
disableGetArch
Disable the getArch
function.
Default: false
disableGetCmd
Disable the getCmd
function.
Default: false
disableGetConfig
Disable the getConfig
function.
Default: false
disableGetEnv
Disable the getEnv
function.
Default: false
disableGetFile
Disable the getFile
function.
Default: false
disableGetFileHTTP
Disable the getFileHTTP
function.
Default: false
disableGetOS
Disable the getOS
function.
Default: false
disableGetPath
Disable the getPath
function.
Default: false
disableGetRecord
Disable the getRecord
function.
Default: false
licenseKey
String, the Etcha license key provided to your organization.
Default: ""
lint
exclude
String, a regexp of files to exclude from linting.
Default: "etcha.jsonnet"
linters
(recommended)
A map of strings and Exec configurations for linters. These linters are ran using etcha lint
. See Linting Patterns for more information.
Default:
{
"shellcheck": {
"command": "-s bash -e 2154 -",
"containerImage": "koalaman/shellcheck"
}
}
run
listenAddress
String, the address to listen on when running Etcha in listen mode (etcha run
).
Default: ":4000"
randomizedStartDelaySec
Integer, the maximum number of seconds to delay starting Etcha in listen mode. A random number between 0 and this number will be chosen, and Etcha will wait to start listening for that amount of time. Used to prevent thundering herds and accidental concurrent configuration applies.
Default: 0
rateLimiterRate
(recommended)
String, the maximum number of requests to allow from an IP address before rate limiting them. Takes the format of
Default: "10-M"
shellTimeoutSec
Integer, the maximum number of idle seconds until a shell session is ended.
Default: 300
(5 minutes)
stateDir
(recommended)
String, path to a writeable directory where Etcha can store patterns for future diffing. Used during etcha run
. Defaults to current working directory if unset.
Default: ""
systemMetricsKey
(recommended)
String, the secret to protect /etcha/v1/system/metrics
endpoint during etcha run
. Setting this value enables the metrics endpoint. See Monitoring for more information.
Default: ""
systemPprofKey
String, the secret to protect /etcha/v1/system/pprof/goroutine
and /etcha/v1/system/pprof/heap
endpoints during etcha run
. Setting this value enables these endpoints. This is mostly used for development and shouldn’t be set during production use.
Default: ""
tlsCertificateBase64
(recommended)
String, base64 encoded PEM certificate used by etcha run
. If this or tlsCertificatePath
is not specified, Etcha will generate a self-signed, in-memory certificate and key.
Default: ""
tlsCertificatePath
(recommended)
String, path to a PEM certificate used by etcha run
. If this or tlsCertificateBase64
is not specified, Etcha will generate a self-signed, in-memory certificate and key.
Default: ""
tlsKeyBase64
(recommended)
String, base64 encoded PEM key used by etcha run
. If this or tlsKeyPath
is not specified, Etcha will generate a self-signed, in-memory certificate and key.
Default: ""
tlsKeyPath
(recommended)
String, path to a PEM key used by etcha rn
. If this or tlsKeyBase64
is not specified, Etcha will generate a self-signed, in-memory certificate and key.
Default: ""
verifyCommands
(recommended)
License Required
This requires an Unlimited LicenseList of Commands to run when verifying a JWT instead of using verifyKeys
. See Running Patterns for more information.
Default: []
verifyExec
Exec configuration for running verifyCommands
.
Default: {}
verifyKeys
(recommended)
List of cryptographic verify keys to use when verifying JWTs. See Running Patterns for more information.
Default: []
sources
Sources is a map of source names to source configurations. See Running Patterns for more information.
Default: {}
allowPush
Boolean, allow a source to receive patterns via push.
Default: false
checkOnly
Boolean, prevents patterns received on this source from running change commands.
Default: false
commands
List of static Commands to run for this source. If allowed, Pattern pushes and pulls will override the list of Commands. Commands will use the source’s exec
config, if allowed by the main exec
config. Commands will be ran at startup unless triggerOnly
is set to true. See Running Commands for more information.
eventsReceive
List of event names that the source patterns can receive.
Default: []
eventsSend
String, a regular expression to match event names that the source patterns can send. Can specify ".*"
to allow everything.
Default: ""
exec
Exec configuration for the source.
Default: {}
noRemove
Boolean, never remove Commands for a Pattern source when diffing.
Default: false
noRestore
Boolean, prevents Etcha from saving/restoring the JWTs for this source
. Useful for preventing push-commands
from re-running at startup.
pullIgnoreVersion
Boolean, don’t consider etchaVersion
property differences in JWTs to require a new pull.
Default: false
pullPaths
List of paths to pull JWTs from for this source. Can be local disk paths or http/https paths. For http/https paths, HTTP headers can be specified by appending #header:value
and separating headers using \r\n
, e.g. #header1:value1\r\nheader2:value2
. A special header, skipVerify
, can also be added to ignore certificate verification errors.
See Running Patterns for more information.
Default: []
runFrequencySec
Integer, the number of seconds between (optionally pulling) and running the source pattern. Setting this to 0 means the source will never be pulled/ran except at startup.
Default: 0
runMulti
Boolean, allows for multiple runs to of the source to happen at the same time. By default, multiple runs will queue. Some scenarios where this might occur include repeated pushes, or pulls with too low of a runFrequencySec
. Use with caution.
Default: false
shell
Exec configuration for starting a shell via etcha shell
. Setting the command
value will enable shell access.
Default: ""
triggerOnly
Boolean, when true
, never run a Pattern unless it’s triggered via Events or Webhooks.
Default: false
verifyCommands
License Required
This requires an Unlimited LicenseSee Run > verifyCommands. Setting this value overrides run.verifyCommands
.
Default: []
verifyExec
See Run > verifyExec. Setting this value overrides run.verifyExec
if run.verifyExec
allows overrides.
Default: {}
verifyKeys
See Run > verifyKeys. Setting this value appends it to run.verifyKeys
.
Default: []
webhookPaths
List of HTTP paths to listen for webhooks. See Running Patterns for more information.
Default: []
vars
A map of Source-specific vars
.
Default: {}
targets
A map of target names to target options for use by etcha push
and etcha shell
:
{
"targets": {
"server1": {
"hostname": "server1.example.com",
"insecure": true,
"port": 4001,
"sources": [
"core",
"nginx"
],
"vars": {
"selinux": true
}
}
}
}
See Running Patterns for more information.
Targets are meant to be flexible and proxyable. Etcha uses standard HTTP/HTTP2 functionality, including Server-Sent Events (SSE) for shell access, and it should work out of the box with most reverse proxies (NGINX, Traefik, HAProxy, etc). You could have all of your Etcha devices behind a proxy and use separate paths (/server1/etcha/v1/push
) or host-based routing on your proxy. This would be the Etcha equivalent of a jumpbox.
hostname
String, the hostname or IP address of the target (default: the target name).
Default: The target name
insecure
Boolean, will use an insecure (not HTTPS) connection when connecting to the target.
Default: false
pathPush
String, the URL path for the push endpoint without any sources.
Default: "/etcha/v1/push"
pathShell
String, the URL path for the shell endpoint without any sources.
Default: "/etcha/v1/shell"
port
String, the port number of the target.
Default: "4000"
sourcePatterns
A map of source names to Pattern paths or Commands. Withca will push to this target if the source is specified with etcha push
. If the Pattern is an empty string, Etcha will allow any Pattern or Command to be pushed if the Source is matched.
Default: {}
vars
A map of Target-specific vars
.
Default: false
vars
A map of strings and any type of value. Can be used during rendering to get/set values. See Patterns - Variables, Building Patterns, and Running Patterns for more information.
Vars are combined in this order:
- Pattern
etchaRunVars
- Top level
vars
(this value) - Source
vars
- Target
vars
(push only)
Vars can be retrieved in Patterns using getConfig
.
Default: {}
The following vars
are added to all Patterns:
source
String, the source name of the Pattern.
sysinfo
Map of values containing useful system information:
containerEngine
: String, the detected container engine (docker or podman)cpuLogical
: Integer, count of logical CPUsdefaultInterface
: String, the interface name used by the default routefqdn
: String, the FQDN of the machinehostname
: String, the short hostname of the machineinterfaces
: Map of interface detailsipv4
: List of IPv4 addresses in CIDR format (1.1.1.1/24
)ipv6
: List of IPv6 addresses in CIDR format (::1/64
)mac
: String, MAC address of interfaceskernelRelease
: String, the kernel release name (uname -r
)kernelVersion
: String, the kernel version (uname -v
)machine
: String, the machine version, (likex86_64
)memoryTotal
: Integer, total system memory in MBosID
: String, theID
of the OS (debian
)osIDLike
: String, theID _LIKE
of the OS (debian
)osName
: String, theNAME
of the OS (Ubuntu
)osType
: String, type of OS (linux
)osVersion
: String, theVERSION
of the OS (24.04 LTS (Noble Numbat)
)osVersionCodename
: String, theVERSION_CODENAME
of the OS (bookworm
)osVersionID
: String, theVERSION_CODENAME
of the OS (12
)packageManager
: String, the package manager in use (apt
)runtimeArch
: String, architecture of the Etcha binary (amd64
)
test
Boolean, will be true
if a Pattern is in test mode.
Build Vars
During a Pattern build
, the following additional vars
will be set:
srcDir
: String, the directory of the Pattern being built.srcPath
: String, the path of the Pattern being built.
Push Vars
During a Pattern push
, the following additional vars
will be set:
source
: String, the source name that was pushed.target
: String, the target name that is being pushed to.
Run Vars
During a Pattern run
, the following additional vars
will be set:
jwt
: String, the contents of the original JWT if the Pattern was run from a JWT.