« SysOp Setup MENU System Configuration »

Configuration Files

General Information

ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format.

Hot-Reload

Nearly all of ENiGMA½’s configuration can be hot-reloaded. That is, a live system can have it’s configuration modified and it will be loaded in place.

:bulb: Monitoring live logs is useful when making live changes. The system will complain if something is wrong!

Common Directives

Includes

Most configuration files offer an includes directive that allows users to break up large configuration files into smaller and organized parts. For example, consider a system with many menus/screens. Instead of a single menu.hjson, the SysOp may break this into message-base.hjson, file-base.hjson, etc.

The includes directive may be used the top-level scope of a configuration file:

// menu.hjson
{
    includes: [
        message-base.hjson
        file-base.hjson
    ]

    menus: {
        someOtherMenu: {
            // ...
        }
    }
}

// message-base.hjson
{
    menus: {
        someMessageMenu: {
            // ...
        }
    }
}

References

Often times in a configuration you will find that you’re repeating yourself quite a bit. ENiGMA½ provides an @reference that can help with this in the form of @reference:dot.path.to.section.

Consider actionKeys in a menu. Often times you may show a screen and the user presses Q or ESC to fall back to the previous. Instead of repeating this in many menus, a generic block can be referenced:

{
    //  note that 'recycle' here is arbitrary;
    //  only 'menus' and 'prompts' is reserved at this level.
    recycle: {
        prevMenu: [
            {
                keys: [ "escape" ]
                action: @systemMethod:prevMenu
            }
        ]
    }

    menus: {
        someMenu: {
            form: {
                0: {
                    actionKeys: @reference:recycle.prevMenu
                }
            }
        }
    }
}

:information_source: An unresolved @reference will be left intact.

Environment Variables

Especially in a container environment such as Docker, environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the @environment directive. The most basic form of @environment:VAR_NAME produces a string value. Additionally a :type suffix can be supplied to coerece the value to a particular type. Variables pointing to a comma separated list can be turned to arrays using an additional :array suffix.

Below is a table of the various forms:

Form Variable Value Produces
@environment:SOME_VAR “Foo” "Foo" (without quotes)
@environment:SOME_VAR “123” "123" (without quotes)
@environment:SOME_VAR:string “Bar” "Bar" (without quotes)
@environment:SOME_VAR:string:array “Foo,Bar” [ 'Foo', 'Bar' ]
@environment:SOME_VAR:boolean “1” true
@environment:SOME_VAR:boolean “True” true
@environment:SOME_VAR:boolean “false” false
@environment:SOME_VAR:boolean “cat” false
@environment:SOME_VAR:boolean:array “True,false,TRUE” [ true, false, true ]
@environment:SOME_VAR:number “123” 123
@environment:SOME_VAR:number:array “123,456” [ 123, 456 ]
@environment:SOME_VAR:number “kitten” (invalid)
@environment:SOME_VAR:object ’{“a”:”b”}’ { 'a' : 'b' }
@environment:SOME_VAR:object:array ’{“a”:”b”},{“c”:”d”}’ [ { 'a' : 'b' }, { 'c' : 'd' } ]
@environment:SOME_VAR:timestamp “2020-01-05” A moment object representing 2020-01-05
@environment:SOME_VAR:timestamp:array “2020-01-05,2016-05-16T01:15:37’” An array of moment objects representing 2020-01-05 and 2016-05-16T01:15:37

:bulb: bool may be used as an alias to boolean.

:bulb: timestamp values can be in any form that moment can parse.

:information_source: An unresolved or invalid @environment will be left intact.

Consider the following fragment:

{
    foo: {
        bar: @environment:BAR_VAR:number
    }
}

If the environment has BAR_VAR=1337, this would produce:

{
    foo: {
        bar: 1337
    }
}

Secret Files

For secrets that should not be stored in config.hjson (passwords, API keys, tokens, etc.), ENiGMA½ supports the @file directive to read a value from a file at startup. This is particularly useful in container environments where secrets are injected as files (e.g. Docker/Podman secrets under /run/secrets/).

The path may be absolute or relative to the directory containing config.hjson.

loginServers: {
    ssh: {
        // absolute path (e.g. a Docker/Podman secret)
        privateKeyPass: "@file:/run/secrets/ssh_key_pass"
    }
}

email: {
    transport: {
        auth: {
            user: bbs@example.com
            // relative path — resolved from the config directory
            pass: "@file:secrets/smtp_pass"
        }
    }
}

The file contents are trimmed of leading/trailing whitespace (including the trailing newline that most editors and secrets managers append).

:information_source: If the file cannot be read, a warning is logged and the literal @file:… string is left intact rather than crashing the system.

:bulb: @file works for any string-valued config key — SSH passphrase, SMTP/IMAP passwords, BinkP session passwords, FTN packet passwords, JWT secrets, etc.

:bulb: On POSIX systems, restrict secret files with chmod 600.

See Also

« SysOp Setup System Configuration »