Config

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)

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: "etcha.jsonnet"

configReloadSec

Number of seconds to periodically reload the config and reload the application, if > 0.

Default: 0

configWatch

Boolean, if true then the configPath will be watched for changes. On a change, the application will be reloaded.

Default: false

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: ""

http

listenAddress

String, the listen address and port number for the service.

Default: ":4000"

rateLimitKey

String, a HTTP header key that can be provided using x-rate-limit-key to bypass rate limiting.

Default: ""

rateLimitPatterns

Map of paths and rate limits. Rate limits are configured as count-duration-status, e.g. 5-1h means 5 requests every 1 hour. Status is an HTTP status code, the rate limiter will apply if the response is greater than the status code, e.g. 5-1h-400 will apply if the response status code is > 400. If the rate limit is an empty string (""), it will be disabled for that path.

Default: Run etcha config | etcha jq .http.rateLimitPatterns

tlsCertificateBase64

String, base64 encoded PEM certificate for HTTPS.

Default: ""

tlsCertificatePath

String, path to a PEM certificate for HTTPS.

Default: ""

tlsKeyBase64

String, base64 encoded PEM key for HTTPS.

Default: ""

tlsKeyPath

String, path to a PEM key for HTTPS.

Default: ""

xForwardedTrustedCIDRs

A list of subnets or CIDRs that will be trusted for sending X-Forwarded-For headers. If an IP address in the X-Forwarded-For header matches one of these subnets, the client IP will be the left most address before the matched IP. This should be the host or network of a trusted proxies like NGINX or Traefik.

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

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

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: ""

verifyCommands (recommended)

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

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.