# jprov Configuration

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/"
```

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@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/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/
overlay = "overlay"

# Optional: environment variables passed to the provisioning command
[env]
FOO = "bar"

# 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]]
host = "/usr/local/jails/volumes/foo"
jail = "/mnt/foo"
readonly = false
```

Notes:

- `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`.