From 5f46fde558c467414fa151ad962caaf7f07628fa Mon Sep 17 00:00:00 2001
From: Jan Tuomi <jan@jantuomi.fi>
Date: Mon, 16 Feb 2026 12:59:14 +0200
Subject: Initial commit

---
 docs/CONFIG.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 docs/CONFIG.md

(limited to 'docs/CONFIG.md')

diff --git a/docs/CONFIG.md b/docs/CONFIG.md
new file mode 100644
index 0000000..bdc5b02
--- /dev/null
+++ b/docs/CONFIG.md
@@ -0,0 +1,65 @@
+# 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"
+
+[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"
+
+# Required
+# Command executed inside the jail via: jexec <jailname> <cmd>
+cmd = "/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: append raw jail.conf content
+extra_jail_conf = """
+allow.raw_sockets = 1;
+"""
+
+# Optional: nullfs mounts
+[[mounts]]
+host = "/usr/local/jails/volumes/foo"
+jail = "/mnt/foo"
+readonly = false
+```
+
+Notes:
+- `cmd` is executed as a direct command (no implicit shell wrapping); jprov only checks its exit code.
+- `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`.
-- 
cgit v1.3