diff options
Diffstat (limited to 'docs/CONFIG.md')
| -rw-r--r-- | docs/CONFIG.md | 49 |
1 files changed, 36 insertions, 13 deletions
diff --git a/docs/CONFIG.md b/docs/CONFIG.md index bdc5b02..252e34d 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -3,41 +3,49 @@ This document defines the main configuration file and per-jail TOML schema. ## Main Config + Default locations (first found wins): + - `/usr/local/etc/jprov.conf` - `/etc/jprov.conf` Schema (TOML): + ```toml base_dir = "/usr/local/jails" +jail_conf_dir = "/etc/jail.conf.d" +log_dir = "/var/log/jprov" [datasets] templates_prefix = "zroot/jails/templates/" containers_prefix = "zroot/jails/containers/" - -jail_conf_dir = "/etc/jail.conf.d" -log_dir = "/var/log/jprov" ``` Notes: + - `base_dir` contains `templates/` and `defs/`. - `templates_prefix` and `containers_prefix` are ZFS dataset name prefixes (must end with `/`). - `log_dir` is where per-run logs are written. ## Per-jail Config + Location: + - `base_dir/defs/<jailname>/jprov.conf` Schema (TOML): + ```toml # Required # Relative to datasets.templates_prefix -# Example: "RELEASE-15.0-p3" resolves to "zroot/jails/templates/RELEASE-15.0-p3" -template = "RELEASE-15.0-p3" +# Example: "RELEASE-15.0-p3@base" resolves to "zroot/jails/templates/RELEASE-15.0-p3@base" +# Note: ZFS clone requires a snapshot (e.g., "@base") in the template name. +template = "RELEASE-15.0-p3@base" -# Required -# Command executed inside the jail via: jexec <jailname> <cmd> -cmd = "/bin/sh /usr/local/sbin/provision.sh" +# Required/optional commands +[cmds] +# Command executed inside the jail via: jexec <jailname> <cmds.provision> +provision = "/bin/sh /usr/local/sbin/provision.sh" # Optional # Overlay defaults to base_dir/defs/<jailname>/overlay/ @@ -47,10 +55,20 @@ overlay = "overlay" [env] FOO = "bar" -# Optional: append raw jail.conf content -extra_jail_conf = """ -allow.raw_sockets = 1; -""" +# Optional: structured jail.conf entries +[jailconf] +vnet = true +persist = true +exec.clean = true +mount.devfs = true +devfs_ruleset = 4 +allow.raw_sockets = 1 + +# Optional: jail lifecycle scripts (become exec.* entries) +# These are prefixed with env variables from [env] when emitted. +prestart = "/usr/local/jails/scripts/prestart.sh" +poststart = "/usr/local/jails/scripts/poststart.sh" +poststop = "/usr/local/jails/scripts/poststop.sh" # Optional: nullfs mounts [[mounts]] @@ -60,6 +78,11 @@ readonly = false ``` Notes: -- `cmd` is executed as a direct command (no implicit shell wrapping); jprov only checks its exit code. + +- `cmds.provision` is executed as a direct command (no implicit shell wrapping); jprov only checks its exit code. +- `[jailconf]` maps key/value pairs directly into `jail.conf` entries (no `+=` support). +- `true` values emit `key;` (no `=`). `false` values are omitted. +- Dotted keys are supported via TOML nesting (e.g., `exec.prestart` becomes a nested table). +- `cmds.*` entries are emitted as `exec.*` entries and are prefixed with `env KEY=VAL` for all variables in `[env]` (unless the command already starts with `env `). - `overlay` is copied into the jail root after it is created. - All `mounts[*].host` paths must exist on the host and are mounted via `nullfs`. |