SALVE Attributes, Precedence, and Config Files

In what order do variables override one another? How do I specify machine-specific configuration and apply it globally to a manifest tree? Here we describe the configuration files, their order of application, and the behavior of blocks with respect to these.

Global Attributes

Global attributes are values plugged directly into the SALVE runtime, and therefore apply to all blocks uniformly. They are specified in the SALVE settings.

Sensible Defaults

As much as possible, SALVE attempts to define all behavior on underspecified blocks. There is an underlying set of "sensible defaults" baked into the system, but most of the default settings are also specified in the default INI config.

Defaults INI Format

The ini file is applied to blocks based on simple matching rules. Consider this config file:

[global]
backup_dir=$HOME/.salve/backups
backup_log=$HOME/.salve/backup.log

[file]
mode=600
user=$USER
group=$SALVE_USER_PRIMARY_GROUP
action=copy

[directory]
mode=755
user=$USER
group=$SALVE_USER_PRIMARY_GROUP
action=copy

[manifest]

This specifies that the global attributes backup_dir and backup_log should be set to $HOME/.salve/backups and $HOME/.salve/backup.log respectively. Similarly, all file blocks should have a mode of 600, and so forth.

Attribute Precedence

There are numerous locations at which the attribute value of a block can be specified. Here we lay out the precedence order for attributes. This should be mostly intuitive, as the most tightly scoped value is always taken. The entirety of this can be summarized as block specific > block default > default.

Global Attribute Precedence

Global attributes have the highest precedence level. Any attribute assignation in a block's section of the config, or in a single block, will be replaced with a global attribute. This is mostly done so that global configuration can be hooked into the existing attribute system without allowing blocks to break global config, but also allows the use of global attributes as overrides if necessary.

Block Specific Attribute Precedence

A value specified in a block takes precedence over any defaults. If a block has an attribute assigned in its declaration, that value is used no matter what the surrounding configuration state is (excepting Globals).

Block Section Attribute Precedence

Any ini file attributes specific to a block type act as the default values for that block. For example, if the config specifies a default value of action=create for file blocks, then all file blocks that do not specify action will share this value.

Default Section Attribute Precedence

Default attributes have the lowest precedence level. Defaults are only used when no other attributes apply. They are useful for specifying cross-cutting attributes in config files, like setting USER for all file and directory blocks.

Config File Precedence

The precedence of ini files is Command Line Specified, then $HOME/.salverc, and finally $SALVE_INSTALL_LOCATION/default_settings.ini. If an ini file is given in the commandline, it takes precedence over all other files, and so forth: all of these config files are loaded and inspected, overriding one another in order. The salverc is therefore a good way of applying overrides that apply to a specific system. For example, I might maintain a default_settings.ini that looks something like this:

[file]
user=sirosen
group=sirosen

If there is a machine on which I am not the administrator, and my primary group on that machine is developers, then I might want to add a salverc with the following content:

[file]
group=developers

All of my other attribute specifications in the default settings file are still used, but I have overridden the file[group] on the machine. In this way, overrides allow me to preserve my settings while maintaining system-specific configuration.

Environment Variable Precedence

Environment variables can be used to override the values found in config files. They have a higher precedence level than any configuration files, but still have ordinary precedence with respect to block attribute application.

The correct form for an environment override is SALVE_<section>_<attribute>. This applies an override to the specified attribute in the specified section of the config, so the SALVE_GLOBAL_BACKUP_LOG environment attribute specifies the value for the backup_log attribute of the global section.