Configuration
An instance is configured in one TOML file. Change it with vigile config set, which checks the value before writing it.
The file
name = "main"
data_dir = "data"
log_level = "info"
[listen]
address = "127.0.0.1"
port = 8700
[auth]
keyless_user = "agent1"
[backup]
enabled = true
every_hours = 24
folder = "backups"
keep = 30
[auth.keys]
admin = "vig_..."
vigile config init writes it, with a new admin key, readable by your account only. Every command is told where it is with --config <file> or the VIGILE_CONFIG variable; there is no default location.
Settings
| Setting | Default | Takes | Environment variable | Option of serve | What it is |
|---|---|---|---|---|---|
name | "vigile" | text, at most 40 characters | VIGILE_NAME | --name | A label for this instance, shown in the web page and at startup. |
data_dir | "data" | text | VIGILE_DATA_DIR | --data_dir | Where the data lives; relative paths start at the config file's folder. |
log_level | "info" | debug, info, quiet | VIGILE_LOG_LEVEL | --log_level | Debug, info or quiet. |
listen.address | "127.0.0.1" | text | VIGILE_LISTEN_ADDRESS | --listen.address | The address to listen on. |
listen.port | 8700 | a whole number, 1 to 65535 | VIGILE_LISTEN_PORT | --listen.port | The port to listen on. |
auth.keyless_user | "agent1" | text | VIGILE_AUTH_KEYLESS_USER | --auth.keyless_user | Who a connection without an API key acts as; empty refuses such connections. |
backup.enabled | true | true or false | VIGILE_BACKUP_ENABLED | --backup.enabled | Whether the service takes backups of the data by itself: true or false. |
backup.every_hours | 24 | a number, 0.25 to 8760 | VIGILE_BACKUP_EVERY_HOURS | --backup.every_hours | How many hours lie between two automatic backups; 0.5 is half an hour. |
backup.folder | "backups" | text | VIGILE_BACKUP_FOLDER | --backup.folder | Where automatic backups go; relative paths start at the config file's folder. |
backup.keep | 30 | a whole number, 1 to 10000 | VIGILE_BACKUP_KEEP | --backup.keep | How many automatic backups of each tenant are kept; older ones are removed. |
What the settings mean in use:
nameis how the instance calls itself: on the page, at startup, and to the command line, which checks it before sending a key.data_diris where the data lives. A relative path starts at the folder of the config file, so by default the data is indata/next toconfig.toml.log_level:infowrites a line for every change and for every call that fails;debugalso for every read;quietwrites no lines for operations. What goes wrong inside the service is written at every level.listen.addressis127.0.0.1unless you change it: the service answers to this machine only. Read Security before setting another.auth.keyless_useris who a connection without a key acts as. Empty, every connection needs a key. It cannot beadmin, and it has to be a user that exists.
API keys, under [auth.keys], are not settings to set by hand: they are made and removed with vigile user.
Changing a setting
vigile config set auth.keyless_user ""
vigile config unset log_level
vigile config set listen.port 8701
vigile config show
The commands here are typed in a terminal that is set up as Install and first run leaves it, with the instance running.
The change of the port comes last for a reason: once the config names another port than the one the service runs on, the commands that ask the running service no longer reach it until it is started again. That is every operation, such as vigile list-tasks, and config set auth.keyless_user with a username, which asks the service whether there is such a user.
config setchecks the value and writes it. A value that fails the check is never written. One setting is checked by asking the service:auth.keyless_user. When no service runs on the config's data it is written unchecked, with a warning, and the service does not start while it names a user that does not exist.config unsetremoves a setting, so that its default applies.config showprints the values in effect and where each came from: the file, the environment, an option, or the default. Keys are masked.
The same check runs when a value is set, when the service starts, and in the doctor. A config that fails it never starts the service. It refuses a name that is no setting, a value of the wrong kind, a missing admin key, and two users with the same key.
When a change applies
- Users and keys (
[auth]) apply at once, without a restart. - Everything else (
name,data_dir,log_level,[listen],[backup]) applies when the service starts. Stop it and runvigile serveagain.
Until the restart, after a change of name, data_dir or [listen], the commands that call the service do not: it is still what it was started as, and no longer what the config describes. The doctor's check "running settings match the config" says when a restart is due.
For one run
A setting can be overridden for one run, without touching the file, by its environment variable or by an option of serve:
VIGILE_LISTEN_PORT=8701 vigile serve
vigile serve --listen.port 8701
Either line starts the service, so they are two ways to do one thing, for an instance that is not running.
An option wins over the environment, and the environment over the file. What a run is started with holds for the whole run. A VIGILE_ variable that is no setting is ignored, and the doctor points it out.
How the file is written
The command line and the running service both write this file, each change as a whole, so the file is rebuilt from its settings every time: comments written into it by hand are not kept. A file that is a link to one kept elsewhere stays a link.
The empty file config.toml.hold beside it is what keeps two changes from happening at once. Leave it where it is.
Several instances
Each instance has its own config file, data folder and port, and they share nothing:
vigile config init --config ~/vigile/second/config.toml --name second --port 8701