zmgr/docs/ai/registry-format.md

# Registry Format

All files use KDL v2 syntax. The registry root defaults to `/etc/zmgr/` but can be overridden with `--registry`.

## config.kdl

```kdl
zonepath-prefix "/zones"
default-template "oi"
```

| Field | Type | Default | Description |
|---|---|---|---|
| `zonepath-prefix` | string | `/zones` | Parent directory for zone roots |
| `default-template` | string | `oi` | Template used when `--template` is omitted |

## templates/*.kdl

Templates define one or more `net` blocks, each referencing an IPAM pool.

```kdl
// Single-net template
template "oi" {
  brand "ipkg"
  autoboot #false
  ip-type "exclusive"
  net "internal" {
    pool "internal"
  }
}

// Multi-net template (e.g., router with internal + public)
template "router" {
  brand "ipkg"
  autoboot #true
  ip-type "exclusive"
  net "internal" {
    pool "internal"
  }
  net "public" {
    pool "public"
  }
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `brand` | string | yes | Zone brand (ipkg, nlipkg, etc.) |
| `autoboot` | bool | no | Boot zone after install (default: `#false`) |
| `ip-type` | string | no | IP type (default: `exclusive`) |
| `net "<name>"` | block | yes (1+) | Network attachment with pool reference |

Legacy: a flat `pool "name"` field is accepted as shorthand for a single net named "default".

## pools/*.kdl

Pools support two address source modes: **range** or **list**.

### Range-based pool (contiguous)

```kdl
pool "internal" {
  network "10.1.0.0/24"
  gateway "10.1.0.1"
  stub "oinetint0"
  range-start "10.1.0.10"
  range-end "10.1.0.250"
}
```

### List-based pool (specific addresses)

For public IPs from a hoster where addresses may not be contiguous:

```kdl
pool "public" {
  network "203.0.113.0/28"
  gateway "203.0.113.1"
  stub "pubstub0"
  addresses {
    address "203.0.113.2"
    address "203.0.113.3"
    address "203.0.113.5"
  }
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `network` | CIDR | yes | Network in CIDR notation |
| `gateway` | IPv4 | yes | Default router for zones in this pool |
| `stub` | string | yes | Etherstub/VNIC parent for zone VNICs |
| `range-start` | IPv4 | * | First allocatable address (range mode) |
| `range-end` | IPv4 | * | Last allocatable address (range mode) |
| `addresses` | block | * | Explicit address list (list mode) |

\* Exactly one of range (`range-start` + `range-end`) or `addresses` is required.

## zones/*.kdl

Zone registry entries store per-net address/VNIC/stub/gateway:

```kdl
zone "gateway" {
  template "router"
  created "2026-03-22"
  net "internal" {
    address "10.1.0.10/24"
    gateway "10.1.0.1"
    vnic "gateway0"
    stub "oinetint0"
  }
  net "public" {
    address "203.0.113.2/28"
    gateway "203.0.113.1"
    vnic "gateway1"
    stub "pubstub0"
  }
}
```

These files are created by `zmgr create` and `zmgr import`. They serve as the IPAM allocation ledger — scanning all zone net blocks determines which IPs are in use.

VNIC naming: `<zonename><index>` where index is the position in the net list (0, 1, 2...).

## publishers/*.kdl

```kdl
publisher "openindiana.org" {
  origin "https://pkg.openindiana.org/hipster"
}
```

IPS publisher configurations. Currently informational — future work could apply these during zone install.