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

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

`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

`dataPath`

String, an optional path where Rot will save modifications to. Use this to have your rot.jsonnet file be editable and import the dataPath file that Rot will edit, e.g.:

(import 'rot_data.jsonnet`) + {
  dataPath: 'rot_data.jsonnet',
}

Default: cli.ConfigPath

`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!"
}

Some special purpose meta keys:

_ Changes the name of the environment variable for the value in run.
_links_dst A comma separated list of paths that will also be updated when this value changes.
_links_src The path that updates this value.
publicKey rot val-add-prv will store the public key here.

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