Specification reference

A specification is a TOML document. Unknown keys are an error, so a typo is reported rather than silently ignored.

Validate one with:

$ rpi-provision validate pi.toml

Secret values

Fields marked secret below take a source, not a literal:

password_hash = { env  = "RPI_PASSWORD_HASH" }
password_hash = { file = "secrets/pw.hash" }     # relative to the spec file
password_hash = { value = "$6$..." }             # discouraged

Exactly one of env, file or value must be present. A bare string is rejected. Values read from a file have their trailing newline removed.

Override the source at run time with --set-secret <path>=env:NAME|file:PATH|value:LITERAL.

[meta]

[system]

[user]

At least one of password_hash and authorized_keys must be present.

[ssh]

[network]

[[network.ethernet]] and [[network.wifi]]

Shared keys:

Ethernet only:

Wi-Fi only:

A statically addressed wired connection is written with may-fail=false, so network-online.target waits for it. Everything else uses may-fail=true.

[network.usb_gadget]

The link is configured with never-default=true and may-fail=true: it must never become the default route, and an unplugged cable must not delay boot.

No DHCP server is installed on the device. Give the host a static address in the same subnet, or rely on IPv4 link-local.

[hardware]

[hardware.uart]

With console = false and debug_connector = false, the stock console=serial0,115200 is removed so that GPIO 14/15 is a plain data port.

[hardware.i2c], [hardware.spi], [hardware.one_wire]

Enabling a bus does not grant the account access to it; add i2c, spi or gpio to user.groups for that.

[[files]]

Files copied onto the root filesystem during the first boot, in addition to everything the tool generates.

Repeat the [[files]] header for each entry. It is a TOML array of tables, so as many as you like may be declared; the double brackets are what make it a list rather than a single table.

[[files]]
source = "files/motd"
destination = "/etc/motd"

[[files]]
source = "files/vimrc"
destination = "/etc/vim/vimrc.local"

[[files]]
source = "files/scripts"        # a directory, copied recursively
destination = "/opt/scripts"
mode = "0755"
owner = "engineer"
group = "engineer"

The contents are staged on the boot partition and installed by step 30-payload, so they are in place before the commands in [[run]].

Entries are installed in order of destination rather than in the order they are written. Nothing depends on the order — each entry writes exactly one path, and two entries may not write the same one — so the two orders are interchangeable in practice.

Two entries may not write the same destination, and a destination that rpi-provision generates itself — a NetworkManager profile, the sshd drop-in, the sudo rule, the gadget script or unit — is rejected rather than silently overwritten by one or the other.

The boot partition is small and FAT formatted, and everything declared here has to fit on it alongside the payload. Fetching a large archive on the device is the better shape; a specification whose transfers exceed 64 MiB is loaded with a warning.

[[run]]

Commands run at the end of the first boot, as step 80-run. Everything else — the account, the transferred files, networking — is in place by then.

Repeat the [[run]] header for each command, as with [[files]]. They run in the order they are written, top to bottom.

[[run]]
description = "refresh the package index"
command = "apt-get update"
ignore_failure = true

[[run]]
description = "install the editors this bench expects"
command = "apt-get install -y --no-install-recommends vim tmux"

[[run]]
command = "systemctl enable my-daemon"

command is the one place a specification contributes code rather than a value: it is emitted into the generated script verbatim, not quoted, because it is meant to be interpreted by the shell. Everything else a specification provides is quoted before it reaches a script.

It must be a single line. Anything longer belongs in a script transferred with [[files]] and invoked here, which also keeps it under review as a file rather than as a string inside a TOML document:

[[files]]
source = "files/setup.sh"
destination = "/usr/local/sbin/setup.sh"
mode = "0755"

[[run]]
command = "/usr/local/sbin/setup.sh"

Unless ignore_failure is set, a failing command stops the step, and the first-boot runner records status=failed. It still removes its own hooks from cmdline.txt, so a failing command cannot produce a boot loop.

[provisioning]

Command line overrides

--set <path>=<value> assigns into the parsed document before validation. The value is parsed as a TOML scalar when possible and as a string otherwise, so --set ssh.port=2222 gives an integer and --set system.hostname=dev-pi-07 gives a string. Array elements are indexed:

--set 'network.ethernet[0].address=192.168.1.57/24'

Missing intermediate tables are created; a missing array element is an error.

Overrides change the specification digest, which is recorded in config.txt, in firstrun.sh and in /var/lib/rpi-provision/status on the device.