os-release fields¶
This page is for image authors and operators who read an image's os-release or a refusal that names one of its fields. It lists the os-release fields chalkos sets, their values and the checks that read them. The image explains what an image is and Upgrades how these checks keep an upgrade within its platform.
Where os-release is¶
An image carries one os-release file in two places with the same content:
/etc/os-releaseon the running node, in the read-only/etcthe image assembles at boot;- the
.osrelsection of the image's UKI, next to the kernel command line that names the store's root hash.
The UKI's Secure Boot signature covers its .osrel section, so on a node with
Secure Boot enforced, an image cannot claim another
name or platform than the one it was signed
with. chalkctl and chalkd read the UKI's copy of an image they are
about to install, and /etc/os-release for the image a node runs.
Fields chalkos sets¶
| Field | Value | Source | Images |
|---|---|---|---|
IMAGE_ID |
chalkos; chalkos-installer on the installer |
system.image.id |
every image |
IMAGE_VERSION |
empty | modules/node/upgrade.nix; system.image.version must stay unset |
every image |
CHALKOS_IMAGE |
the image's name, such as node-metal |
chalkos.image.name |
node images; not the installer |
CHALKOS_PLATFORM |
the platform's name, such as metal or kvm |
chalkos.platform.name |
node images; not the installer |
CHALKOS_BOOT_TRIES |
a positive integer, 3 by default |
chalkos.upgrade.bootTries |
every image |
Image options describes the options in the Source column.
IMAGE_VERSION is empty in every image, so the generation in the file name orders the UKIs, as
Boot, health and rollback explains. The build fails when
system.image.version is set, with the message
chalkos orders boot entries by generation; pass revision and tag to mkImages for provenance. The
image ID matches [a-z0-9._-]+: it starts the UKIs' file names, systemd-boot lowercases only
the IDs of entries without a tries counter, and a + starts the counter. A platform's name
matches [a-z0-9][a-z0-9-]*.
The other fields are NixOS's, unchanged: ID=nixos, NAME, VERSION, VERSION_ID,
BUILD_ID, PRETTY_NAME and the URLs. chalkos does not read them.
The os-release of the lab template's image for kvm, as its UKI carries it:
ANSI_COLOR="0;38;2;126;186;228"
BUG_REPORT_URL="https://github.com/NixOS/nixpkgs/issues"
BUILD_ID="26.11.20261003.a7868a7"
CHALKOS_BOOT_TRIES=3
CHALKOS_IMAGE="node-kvm"
CHALKOS_PLATFORM=kvm
CPE_NAME="cpe:/o:nixos:nixos:26.11"
DEFAULT_HOSTNAME=nixos
DOCUMENTATION_URL="https://nixos.org/learn.html"
HOME_URL="https://nixos.org/"
ID=nixos
IMAGE_ID=chalkos
IMAGE_VERSION=""
LOGO="nix-snowflake"
NAME=NixOS
PRETTY_NAME="NixOS 26.11 (Zokor)"
SUPPORT_URL="https://nixos.org/community.html"
VENDOR_NAME=NixOS
VENDOR_URL="https://nixos.org/"
VERSION="26.11 (Zokor)"
VERSION_CODENAME=zokor
VERSION_ID="26.11"
The installer's carries IMAGE_ID="chalkos-installer" and CHALKOS_BOOT_TRIES, and no
CHALKOS_IMAGE or CHALKOS_PLATFORM.
What reads each field¶
| Field | Read by | Check |
|---|---|---|
IMAGE_ID |
chalkd's Upgrade | The new image's ID equals the running image's. |
IMAGE_ID |
chalkd's upgrade and install, on the UKI | The UKI's ID equals the image header's. The UKI's file name on the ESP is <IMAGE_ID>_<generation>.efi. |
IMAGE_ID |
chalkd's upgrade, on the ESP | Only UKIs of the running image's ID, and files that are no UKI whose names give a generation of it, are removed; other UKIs on the ESP stay. Every name <IMAGE_ID>_<n>.efi counts for the highest generation, whatever its UKI holds. |
IMAGE_VERSION |
chalkctl, reading an image | Set and empty; an image without it or with a value is refused. |
IMAGE_VERSION |
chalkd's upgrade and install, on the UKI | Set and empty, as for chalkctl. |
CHALKOS_PLATFORM |
chalkd's Upgrade | The new image's equals the running image's; a running image without it takes no upgrade. |
CHALKOS_PLATFORM |
chalkd's upgrade and install, on the UKI | The UKI's platform equals the image header's. |
CHALKOS_IMAGE, CHALKOS_PLATFORM |
chalkctl, reading an image | Both are set; an image without them is no node image and is refused. |
CHALKOS_PLATFORM |
chalkctl install and upgrade | The image is built for the platform of the image the node runs, or, on the installer, of the node's image in the inventory, as its directory's metadata.json gives it. |
CHALKOS_PLATFORM |
chalkd's Install in place and ApplyConfig | The config is translated for the running image's platform: changing a node's platform is a reinstall. |
CHALKOS_IMAGE, CHALKOS_PLATFORM |
chalkd's Contract | Reported as they are, with the image's schemas and its layers' facts. chalkctl's install in place, config apply and storage reset refuse a node whose image is built for another platform than its image in the inventory. |
CHALKOS_BOOT_TRIES |
chalkd's upgrade, on the UKI | A positive integer, which becomes the boot counter in the UKI's name, +3 by default. An install writes no counter. |
IMAGE_ID, CHALKOS_IMAGE, CHALKOS_PLATFORM |
chalkd's Info | Reported as they are; empty on an image that sets none. |
CHALKOS_PLATFORM |
chalkd's Status | Reported, and shown by chalkctl status beside the platform of the node's image in the inventory. |
chalkctl upgrade --image without --nodes upgrades the nodes whose CHALKOS_IMAGE equals the
image's. No other check compares it: a node may change the image it runs through an upgrade, and
the check of its config against the new image's schemas decides whether the image suits it.
No check reads the image's version, because it has none: chalkd's Info and Status name the running image by the root hash on the kernel command line, and the record of a boot that was not found healthy by that root hash and the entry's generation.
Node API describes the methods in the Read by column.
Sources: system.nixos.extraOSReleaseArgs in modules/node/upgrade.nix for the CHALKOS_*
fields and the empty IMAGE_VERSION, modules/node/base/appliance.nix and
modules/installer/default.nix for the image ID, and pkg/uki/uki.go and pkg/chalkd/info.go
for the checks that read them.