Config

Reference documentation for Etcha’s configuration

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 License

List 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 position i or return fallback f.
{{ getEnv e string f string }}
Get an environment variable e or return fallback f.
{{ getFlag f string }}
Get the flag values for f. 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 array s with separator sep.

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 -, where “10-M” means 10 requests/minute. Rate limiting is applied to every HTTP request.

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 License

List 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 License

See 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 CPUs
defaultInterface: String, the interface name used by the default route
fqdn: String, the FQDN of the machine
hostname: String, the short hostname of the machine
interfaces: Map of interface details
ipv4: 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 interfaces
kernelRelease: String, the kernel release name (uname -r)
kernelVersion: String, the kernel version (uname -v)
machine: String, the machine version, (like x86_64)
memoryTotal: Integer, total system memory in MB
osID: String, the ID of the OS (debian)
osIDLike: String, the ID _LIKE of the OS (debian)
osName: String, the NAME of the OS (Ubuntu)
osType: String, type of OS (linux)
osVersion: String, the VERSION of the OS (24.04 LTS (Noble Numbat))
osVersionCodename: String, the VERSION_CODENAME of the OS (bookworm)
osVersionID: String, the VERSION_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.

Config

Configuration Sources

Command Line

Environment Variables

Configuration File

Configuration Values

build

pushDomainSuffix

pushMaxWorkers

signingCommands (recommended)

License Required

signingExec

signingKey (recommended)

signingKeyPath (recommended)

tlsCABase64 (recommended)

tlsCAPath (recommended)

tlsSkipVerify

cli

configPath

logFormat

logLevel

macros

argumentsRequired

argumentsOptional

flags

default

options

placeholder

usage

template

usage

noColor

noPaging

exec

allowOverride

command

containerEntrypoint

containerImage

containerNetwork

containerPrivileged

containerPull

containerUser

containerVolumes

containerWorkDir

env

envInheirt

group

sudo

user

workDir

jsonnet

disableGetArch

disableGetCmd

disableGetConfig

disableGetEnv

disableGetFile

disableGetFileHTTP

disableGetOS

disableGetPath

disableGetRecord

licenseKey

lint

exclude

linters (recommended)

run

listenAddress

randomizedStartDelaySec

rateLimiterRate (recommended)

shellTimeoutSec

stateDir (recommended)

systemMetricsKey (recommended)

systemPprofKey

tlsCertificateBase64 (recommended)

tlsCertificatePath (recommended)

tlsKeyBase64 (recommended)

tlsKeyPath (recommended)

verifyCommands (recommended)

License Required

verifyExec

verifyKeys (recommended)

`build`

`pushDomainSuffix`

`pushMaxWorkers`

`signingCommands` (recommended)

`signingExec`

`signingKey` (recommended)

`signingKeyPath` (recommended)

`tlsCABase64` (recommended)

`tlsCAPath` (recommended)

`tlsSkipVerify`

`cli`

`configPath`

`logFormat`

`logLevel`

`macros`

`argumentsRequired`

`argumentsOptional`

`flags`

`default`

`options`

`placeholder`

`usage`

`template`

`usage`

`noColor`

`noPaging`

`exec`

`allowOverride`

`command`

`containerEntrypoint`

`containerImage`

`containerNetwork`

`containerPrivileged`

`containerPull`

`containerUser`

`containerVolumes`

`containerWorkDir`

`env`

`envInheirt`

`group`

`sudo`

`user`

`workDir`

`jsonnet`

`disableGetArch`

`disableGetCmd`

`disableGetConfig`

`disableGetEnv`

`disableGetFile`

`disableGetFileHTTP`

`disableGetOS`

`disableGetPath`

`disableGetRecord`

`licenseKey`

`lint`

`exclude`

`linters` (recommended)

`run`

`listenAddress`

`randomizedStartDelaySec`

`rateLimiterRate` (recommended)

`shellTimeoutSec`

`stateDir` (recommended)

`systemMetricsKey` (recommended)

`systemPprofKey`

`tlsCertificateBase64` (recommended)

`tlsCertificatePath` (recommended)

`tlsKeyBase64` (recommended)

`tlsKeyPath` (recommended)

`verifyCommands` (recommended)

`verifyExec`

`verifyKeys` (recommended)

`sources`

`allowPush`

`checkOnly`

`commands`

`eventsReceive`

`eventsSend`

`exec`

`noRemove`