Getting started

Configuration

The host's config.toml. How to change it, what the installer wrote, and where secrets go.

The host is configured by one file, /etc/nibrunner/config.toml. nibrunnerd install writes it and every nibrunnerd start reads it. The reference lists every key.

Changing it

  1. Edit /etc/nibrunner/config.toml.
  2. Put any secret the new configuration needs in /etc/nibrunner/host.env.
  3. Run nibrunnerd start.

start validates the whole file before doing anything, regenerates the files install wrote, and restarts only the units whose configuration changed. If the file is invalid, the error names the key and the reason.

Applied service inputs are recorded under paths.state_dir. A separate install, or an interrupted or failed start, leaves changes pending until activation succeeds. Repeating start with no pending changes leaves services running.

A reboot or a restart outside start makes the previous activation receipt unverified, even if the installed files match it. Receipts from older versions that did not identify the service activation are also unverified.

If a running ZeroFS needs new service inputs, start refuses to restart it automatically: that disconnects every guest disk. Stop the guests that use it, then run nibrunnerd start --restart-zerofs. The same acknowledgement is required on an existing ZeroFS host whose running inputs cannot be verified. --force only permits replacing files; it does not permit a ZeroFS restart.

Validation rules

  • No key has a default. If a section is present, every key in it must be set. A missing key is an error that names the key.
  • Unknown keys are errors. A typo is reported as an unknown key, not as a missing one.
  • Only whole sections are optional. [proxy.http.tls], [proxy.raw], [metrics] and [logs] can be omitted. If present, they must be complete. Optional [host_storage] initializes and mounts an explicitly selected device before the host starts.

Example errors:

volumes.backend is not specified, and nothing here is optional
volumes.zerofs is not read by the local-file backend, which is what volumes.backend says
proxy.http.port is not free, because 21000-28999 is what a slot takes for an app's loopback port

What the installer writes

A complete configuration that works as-is:

KeyValue
max_appsWhat the machine can hold, measured at install time.
[paths]Everything under /var/lib/nibrunner.
[artifacts], [exports]Directories on the local disk.
[volumes]backend = "local-file": sparse files on the local disk.
[cron]At most 10 jobs per app, scheduled in UTC. Both values are written explicitly.
[proxy.http]Plain HTTP on all addresses, port 80.
[logs]The newest 256 MiB of each app's output.

Before running anything real on it, you will probably change two things:

  • The volume backend. zerofs stores volumes in an object store. They survive the machine, and backups are taken from them.
  • The listener. Add [proxy.http.tls] to terminate TLS on the host. Behind an edge that terminates TLS, keep plain HTTP.

deploy/config.example.toml shows every section filled in.

Secrets

config.toml holds no secrets. Optional static object-store credentials and the ZeroFS encryption password go in /etc/nibrunner/host.env. install creates that file with every variable named. S3 credentials resolve through the default provider chain, including EC2 instance roles; static access keys are optional and must be supplied together. nibrunnerd start refuses to run while a variable the configuration needs is still empty.

Ports

Each app slot reserves eight consecutive ports starting at 21000. Every listener in config.toml must be outside the range 21000 to 21000 + 8 × max_apps − 1. Port 0 is rejected. metrics.port must differ from proxy.http.port.

Environment variables

  • NIBRUNNER_CONFIG: path to a different configuration file.
  • NIBRUNNER_LOG: a tracing filter for the daemon's log. Set it in the environment, not in the file.

Which apps run on the host is defined in desired.json, not in config.toml.

Cron policy

[cron] sets the policy for every app on the host:

[cron]
max_jobs_per_app = 10
time_zone = "UTC"

Both keys are required. Set max_jobs_per_app = 0 to disallow jobs. time_zone must name an IANA time zone, such as Europe/Zurich. Apps register jobs through crontab.

Editor support

An editor with TOML schema support (Even Better TOML for VS Code, taplo) validates and autocompletes the file when its first line is:

#:schema https://raw.githubusercontent.com/ilbertt/nibrunner/main/deploy/config.schema.json

On this page