Writing answers

An answer is the document an installer receives: a Proxmox answer.toml, an Ubuntu autoinstall user-data, a kickstart, a preseed, an Ignition config, an AutoYaST profile, a Windows unattend.xml. rescriptum’s whole job is to pick the right one for the machine asking and hand it back, assembled from however many layers you wrote.

The layout

One directory per identity. A machine is a directory named after it, holding one document per operating system:

answers/
├── 98fa9b50d810/           one machine
│   ├── proxmox.toml            as Proxmox
│   └── debian.preseed          …and the same hardware as Debian
├── aabbccddeeff/           another machine
│   └── ubuntu.yaml             as Ubuntu
├── default/                when nothing else matches
│   └── proxmox.toml
└── groups/
    ├── rack-a/             shared by a rack, claims its members
    │   ├── proxmox.toml
    │   └── debian.preseed
    └── rhel-compute/       claims machines by what they are
        └── rhel.ks

A machine is a directory named after it — a MAC address, in any separator style — holding that machine’s own configuration, or only the part of it that differs from its group.
A group is a directory under groups/ and is shared. It claims machines by listing them in members, or by a match block tested against the request.
default/ answers when nothing else does. One document per format: a TOML default must not answer a client that asked for kickstart.

The extension decides; the name does not

Inside a directory, the extension is the format and the part before it means nothing. proxmox.toml and answer.toml are the same document to the server; the name is there for whoever opens the folder. rescriptum writes readable ones — proxmox.toml, ubuntu.yaml, debian.preseed, boot.ipxe — and never renames yours.

The one rule that follows: a directory holds at most one document per format. Two .toml in one directory is reported as a problem rather than resolved, because nothing could pick between them that you would have predicted. Two different formats are not a duplicate at all — that is the whole point of the directory.

Storage layout and URL are still deliberately kept apart: a folder can be reorganised, a URL baked into an ISO cannot. See formats.

:::note[Upgrading from a flat directory] Answers used to be files at the top of the directory: 98fa9b50d810.toml beside 98fa9b50d810.preseed. Those are no longer served, and each one is reported by name with its new path. rescriptum migrate shows what it would move; rescriptum migrate --apply moves them. :::

The five things to know


How an answer is picked	By name, by member list, or by what the machine is. Naming always wins; among selectors, more criteria wins; ties break on sorted name
One document per operating system	The extension is the format, the endpoint chooses between them, and a machine can exist as several operating systems at once
Groups and merging	Layers apply lowest to highest and the machine always wins. Maps merge; arrays replace
Templating	`{{ serial }}` filled from the request, so one group file covers a rack
Validating	`render` shows what a machine would get; `check` renders everything and reports what breaks

Control keys

Four keys steer resolution and are stripped before the answer is sent, so the installer never sees them:

Key	Does
`members`	the machines this group answers for
`match`	criteria tested against the request’s facts
`extends`	the group this document layers on top of

They travel in whatever the format allows — top-level keys in TOML, YAML and JSON, an <answer-meta> element in XML, # answer: directives in kickstart and preseed. The per-format spelling is in formats.

Worked examples

The repository’s examples/ directory carries a commented example of every supported format, all selected differently — by hardware, by member list, by directory name — and they are exercised by the test suite:

$ RESCRIPTUM_ANSWERS_DIR=examples rescriptum check
$ RESCRIPTUM_ANSWERS_DIR=examples rescriptum render --query "path=/rhel/ks&serial=7ABC123"

It is the only place the formats are shown composing together; start there when you are unsure what a real file looks like.