Config

Reference documentation for Rot’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, i.e. ROT_cli_logLevel=debug

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

algorithms

Configuration values for setting the algorithms Rot will use by default.

asymmetric

Specify the asymmetric encryption algorithm to use. See rot alg for options.

Default: "best"

pbkdf

Specify the Password Based Key Derivation Function (PBKDF) encryption algorithm to use. See rot alg for options.

Default: "best"

symmetric

Specify the symmetric encryption algorithm to use. See rot alg for options.

Default: "best"

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

noColor

Boolean, disables colored log output.

Default: false

noPaging

Boolean, disables paging of log output using less.

Default: false

decryptKeys

A map of key names to key configurations.

Default: {}

modified

String, the UTC time the key was last modified.

Default: ""

privateKeys

A map of Keyring names to Private Keys and Signatures.

Default: {}

privateKey

String, the Keyring’s Private Key encrypted using the Decrypt Public Key.

Default: ""

signature

String, a signature created by the Keyring’s Private Key of the Decrypt Public Key. This is used to prevent tampering of public keys.

Default: ""

publicKey

String, the Decrypt Public Key.

Default: ""

privateKeySSS

List of encrypted values used by Shamir Secret Sharing.

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

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

disableGetOS

Disable the getOS function.

Default: false

disableGetPath

Disable the getPath function.

Default: false

disableGetRecord

Disable the getRecord function.

Default: true

keyrings

A map of Keyring names to Keyring details.

encryptValues

Boolean, controls if the Keyring Values will have their Name and Meta properties encrypted too. See Manage Keyrings for more information.

Default: false

privateKey

String, the decrypted Keyring Private Key. This is used to pass the Keyring Private Key via environment variables, such as from a external script that decrypts a decryptKey..privateKey using a HSM or KMS. Rot will never save this value to disk.

Default: ""

publicKey

String, the Keyring Public Key.

Default: ""

values

A map of Value names to a map of Version Time and Value configurations.

{
  "path/valueA": {
    "2024-04-24T00:00:00Z": {
      "key": "ecdhx25519hkdfsha256:MCowBQYDK2VwAyEAxNCdx0pHwQUh3f8QzhcYZ0qfmcvX1VF90iGfs+NWWUA=@xchacha20poly1305:A4f/zp076OopQaz8v1LOKqBLXH7QaXqSV190CaGwx0sAp3ah/ToFYdR
aAkobxojV4zCQtV7EQPwBrQ0rpNLLwNvzGNe8VNEV41KSPz9gcBACDZIz6cxpfCwZmz2HqvSTVyN+pDlix0Y=:s1cAADoakP",
      "meta": {
        "comment": "it's a value!"
      },
      "value": "xchacha20poly1305:D5hi10kxIiLH1URXJHlLscNeRBwfUR6q8YYvlRogAQfbReV/wErcskLebCsY3e0NJyX0YOlalEmMRSr+ncUbXqfyTYpBXWYoV/6qXWzMMlRQt5c0WIyaS/r9KoOa54IyWcHm32e
rgnkKo/0IdvXJHerUxusItlGhQns4G7ww+YlNSFDgyrq7UaZFROxAoqMxfe6n9h6HaSrXKxAn9bHdybV2ruUOOSrStwIVMyZdY97RYeyGYBZX5cqkcweE1HYoUO/r:cR5faafTQA",
    }
  }
}

key

String, the Rot Public Key encrypted symmetric key, used to encrypt/decrypt the value

Default: ""

Meta

A map of strings containing various metadata about the Value.

{
  "comment": "a comment!"
}

Default: {}

value

String, a value encrypted using the key.

Default: ""

valuesEncrypted

A map of encrypted Value Names to Value properties.

{
  "xchacha20poly1305:6WnHSGlNLOYqiyGb1TGr/R3rb2mQFroSU7NyM4smsehUhnSPvb6yoXn7DAo=:fJveNApidl": {
    "key": "ecdhx25519hkdfsha256:MCowBQYDK2VwAyEAcQ+04/QsBhzONfYGq/99IlHWVeQV5Y+7h7lBKmwPz20=@xchacha20poly1305:+YC8IlIbpzH2Qs5GBtIId1gB+V3+ehMHdkugB+ARHUHYEC1ciEckP9VMaqcVDfywmUd78Mf23Jnn/G/mEDnn341lJlYgq7fgvW7TFd2fBtNloxCDBrs6JZryoVaIn5DnVeM9x1C7v/A=:JsZ8NTCNYS",
    "meta": {},
    "modified": "2024-04-25T00:00:00Z",
    "value": "xchacha20poly1305:bidJE4tsmHA4BrR58VWncRLXAeMD8kssOguy8kb8Yt3lNTlSFlrnMERxFOLPckE=:fJveNApidl"
  }
}

key

String, the Rot Public Key encrypted symmetric key, used to encrypt/decrypt the value

Default: ""

meta

A map of encrypted string keys to encrypted string values.

Default: {}

modified

String, the encrypted date the value was modified.

Default: {}

value

String, a value encrypted using the key.

Default: ""

keys

A list of strings containing Decrypt Private Keys. This is mostly used to pass Decrypt Private Keys via environment variables. Rot will never save this value to disk.

Default: ""

keyPath

String, the path to a file containing Decrypt Private Keys, one per line. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.

Default: ".rot-keys"

licenseKey

String, the Rot license key provided to your organization.

Default: ""

unmask

A list of Value names to unmask.

Default: []

version

String, the version of the Rot configuration.

Default: "<current Rot version>"