Image options¶
This page is for image authors who set the options of chalkos's node modules in an image's
NixOS modules, the modules of mkImage and mkImages. Every image and the
installer carry these modules. The options an extension uses to declare kinds, facts, outputs
and effects are on Extension API.
Disk¶
The sizes of the partitions an image's build lays out.
chalkos.disk.espSize¶
Type: string · Default: "1G" · Declared in: modules/node/base/disk.nix
Size of the EFI system partition, which holds the UKIs of both slots; at least 260M, the smallest systemd-repart formats as vfat.
chalkos.disk.stateSize¶
Type: string · Default: "128M" · Declared in: modules/node/base/disk.nix
Size of the STATE partition holding the node's config and secrets; at least 64M, the smallest encrypted ext4 partition systemd-repart makes.
chalkos.disk.storeSize¶
Type: string or null · Default: "3G" · Declared in: modules/node/base/disk.nix
Size of each store slot's erofs data partition; null sizes it to its contents, for images that are never upgraded.
chalkos.disk.storeVeritySize¶
Type: string or null · Default: "128M" · Declared in: modules/node/base/disk.nix
Size of each store slot's dm-verity hash partition; null sizes it to its contents. The image build fails when the hash tree takes more than 80% of it. With 4 KiB blocks the tree needs up to about 1/128 of storeSize.
Kernel¶
The kernel modules an image carries.
chalkos.kernel.allModules¶
Type: boolean · Default: false · Declared in: modules/node/kernel.nix
Carry every module of the kernel instead of the groups and names.
chalkos.kernel.extraModules¶
Type: list of string · Default: [ ] · Declared in: modules/node/kernel.nix
Kernel modules the image carries besides its groups, with what they depend on. A name the kernel does not know fails the build.
Example: [ "kvm_amd" ]
chalkos.kernel.groups¶
Type: map of submodule · Default: { } · Declared in: modules/node/kernel.nix
Groups of kernel modules by name, which chalkos.kernel.moduleGroups selects. chalkos
declares the groups of the hardware an image may run on and of its base software:
can, filesystems, gpu, industrial, infiniband, media, network, platform, sound, storage, virtualisation and wireless. The module of a feature declares the group the feature
needs, such as the base firewall's firewall, and adds it to
chalkos.kernel.moduleGroups while the feature is on.
The options within each, by their path below chalkos.kernel.groups:
| Option | Type | Default | Description |
|---|---|---|---|
<name>.directories |
list of string | [ ] |
Directories of the kernel's module tree, relative to its kernel/ directory, whose modules the group holds, with those of their subdirectories. A directory without modules fails the build. Example: [ "drivers/net/ethernet" ] |
<name>.modules |
list of string | [ ] |
Kernel modules the group holds besides those of its directories. A name the kernel does not know fails the build. Example: [ "tun" ] |
chalkos.kernel.moduleGroups¶
Type: list of string · Default: [ ] · Declared in: modules/node/kernel.nix
Groups of chalkos.kernel.groups whose modules the image carries. Every image carries
storage, network, virtualisation, filesystems, platform and firewall; the layer an image runs adds the groups it
needs, and an image's modules add to them, for example [ "gpu" ]; lib.mkForce
replaces them. A name that chalkos.kernel.groups does not declare fails the
evaluation. Modules from boot.extraModulePackages are always included whole, with the
modules of the kernel they depend on.
Example: [ "gpu" ]
Kubernetes and CNI¶
Whether an image runs Kubernetes, the packages and images it runs it with, and its CNI.
chalkos.kubernetes.bgp.enable¶
Type: boolean · Default: true · Declared in: modules/node/kubernetes/bgp/default.nix
Whether Kubernetes images carry FRR, which runs BGP and BFD, and accept the kinds BGPPeer and BGPSpeaker. Only with the Kubernetes layer; set it false in an image's modules to leave the feature out of it.
chalkos.kubernetes.enable¶
Type: boolean · Default: false · Declared in: modules/node/kubernetes/default.nix
Whether the image runs Kubernetes: containerd, the kubelet and the preparation of the
node's Kubernetes configuration. An image's modules set it by listing the Kubernetes layer,
chalkos.nixosModules.kubernetes; the installer runs none.
chalkos.kubernetes.package¶
Type: package · Default: the release chalkos.kubernetes.version selects · Declared in: modules/node/kubernetes/default.nix
Kubernetes release whose kubelet the image runs, whose version the image's Kubernetes
facts name. The Cluster document names the images of the control plane, kube-proxy,
CoreDNS, flannel and the pod sandbox, and the image's checker holds their versions to
Kubernetes's version skew policy against this kubelet's. Set it for a release
chalkos.kubernetes.version does not offer, such as another patch release; an image
that sets both names one minor in both.
chalkos.kubernetes.registry.enable¶
Type: boolean · Default: true · Declared in: modules/node/kubernetes/registry/default.nix
Whether Kubernetes images carry chalkos-registry, the cluster registry, and accept the kind ClusterRegistry. Only with the Kubernetes layer; set it false in an image's modules to leave the feature out of it.
chalkos.kubernetes.version¶
Type: one of 1.35, 1.36, 1.37 · Default: "1.37" · Declared in: modules/node/kubernetes/default.nix
Minor release of Kubernetes whose kubelet the image runs, which selects
chalkos.kubernetes.package: one of the three newest minors, the newest by default.
chalkos pins each to a patch release, whose kubelet the image's build compiles from
source, so the image's nixpkgs does not choose the release.
Example: "1.36"
chalkos.cni.plugins¶
Type: list of one of dhcp, host-local, static, bridge, dummy, host-device, ipvlan, loopback, macvlan, ptp, tap, vlan, bandwidth, firewall, portmap, sbr, tuning, vrf · Default: [ ] · Declared in: modules/node/kubernetes/cni.nix
CNI reference plugins the image ships, in containerd's plugin directory. With
flannel they are bridge, host-local, loopback and portmap, which its network runs,
besides flannel's own plugin; with none every reference plugin nixpkgs builds, since
the cluster's own network may use any. Definitions add to these; lib.mkForce
replaces them.
Example: [ "bandwidth" ]
chalkos.cni.provider¶
Type: one of flannel, none · Default: "flannel" · Declared in: modules/node/kubernetes/cni.nix
Pod network of an image with Kubernetes. flannel connects pods across nodes with
VXLAN, configured by the node's Flannel document; none installs no network, for
clusters whose Addon documents bring their own, and ships every CNI reference plugin
(see chalkos.cni.plugins).
Router and forwarding¶
Whether an image carries the router layer, and whether its node forwards packets between its interfaces.
chalkos.router.bgp.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/bgp/default.nix
Whether router images carry FRR, which runs BGP and BFD, and accept the kinds BGP, BGPPeer, CommunityList, PrefixList and RoutingPolicy. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.dhcp.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/dhcp/default.nix
Whether router images carry the DHCP server, Kea, which chalkos builds from source, and accept the kind DHCPSubnet. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.dhcpRelay.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/dhcp-relay/default.nix
Whether router images carry the DHCP relay, dnsmasq, and accept the kind DHCPRelay. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.enable¶
Type: boolean · Default: false · Declared in: modules/node/router/default.nix
Whether the image carries the router layer, which forwards IPv4 and IPv6 packets between
the node's interfaces and accepts the kinds of router.chalkos.dev. An image's modules set
it by listing the router layer, chalkos.nixosModules.router; an image carries one layer at
most, the installer none.
chalkos.router.nat64.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/nat64/default.nix
Whether router images carry Jool, the kernel module and tool of the NAT64 instances, and accept the kind NAT64. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.ntp.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/ntp/default.nix
Whether router images carry an NTP server, the node's chrony, and accept the kind TimeServer. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.resolver.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/resolver/default.nix
Whether router images carry Unbound, the DNS resolvers of the router's VRFs, and accept the kind Resolver. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.router.wireguard.enable¶
Type: boolean · Default: true · Declared in: modules/node/router/wireguard/default.nix
Whether router images carry WireGuard, whose interfaces networkd runs, with wireguard-tools for its diagnostic, and accept the kinds WireGuard and WireGuardPeer. Only with the router layer; set it false in an image's modules to leave the feature out of it.
chalkos.forwarding.enable¶
Type: boolean · Default: false · Declared in: modules/node/network.nix
Whether the node forwards IPv4 and IPv6 packets between its interfaces, as a Kubernetes node does for its pods and a router for its networks. The Kubernetes and the router layer turn it on.
Upgrade and health¶
How many times systemd-boot boots a new image before it falls back, and when a boot of it is healthy.
chalkos.upgrade.bootTries¶
Type: integer of at least 1 · Default: 3 · Declared in: modules/node/upgrade.nix
How often systemd-boot boots this image after an upgrade installed it before it falls back to the image the node ran before, unless a boot was found healthy first.
chalkos.upgrade.healthIgnoreUnits¶
Type: list of string · Default: [ ] · Declared in: modules/node/upgrade.nix
Units of the boot whose failure leaves the node healthy. Only units multi-user.target and sysinit.target pull in count; jobs that timers and sockets start never do. A config's trial ignores them too.
Example: [ "example-sync.service" ]
chalkos.upgrade.healthTimeout¶
Type: integer of at least 1 · Default: 300 · Declared in: modules/node/upgrade.nix
Seconds a boot of this image that systemd-boot counts has to become healthy. Then chalkd reboots the node, so the boot loader tries again or falls back. A boot that is not healthy this long after systemd finished starting it has settled, also when it is not counted, and chalkctl stops waiting for it.
Console¶
The kernel's consoles, where the boot and its passphrase prompts appear, whether chalkd serves the console on the machine's screen, and whether the console may act on the node.
chalkos.consoles¶
Type: non-empty (list of string matching the pattern [A-Za-z0-9]+(,[A-Za-z0-9]+)*) · Default: [ "ttyS0,115200" "tty0" ] · Declared in: modules/node/consoles.nix
The kernel's consoles in order, each as the kernel's console= takes it, such as
ttyS0,115200 for the first serial port at 115200 baud or tty0 for the screen. The
kernel prints on every one, and systemd asks for each passphrase and recovery key on every
one, so any of them can answer. An image whose modules set the list twice fails to build,
unless one of them uses lib.mkDefault or lib.mkForce.
The last entry becomes /dev/console, where systemd's boot status, the emergency shell and
chalkd's lines (its fingerprint and addresses among them) appear. While it is tty0 or
tty1 and the console runs on tty1, chalkd keeps off /dev/console and the console shows
the fingerprint and addresses. While it is a virtual terminal, chalkos-serial-log@ copies
chalkd's lines from the journal to every serial port of the list (ttyS0, ttyAMA0,
ttyUSB0, hvc0, …), so a BMC's serial-over-LAN shows them. An entry of another form,
such as uart8250,mmio32,0xfe215040, gets only the kernel's messages.
The metal platform, a platform of your own and the installer put the screen last; kvm
has the first serial port alone. Where people watch a BMC's serial-over-LAN, put that port
last, such as [ "tty0" "ttyS0,115200" ], so the boot's status and the emergency shell
appear there too.
Example: [ "tty0" "ttyS1,115200" ]
chalkos.console.actions.enable¶
Type: boolean · Default: true · Declared in: modules/node/console.nix
Whether the console may reboot and shut down the node and roll back its image and its config. Anyone at the machine's keyboard can use them; chalkd refuses them on the console's socket when this is false.
chalkos.console.enable¶
Type: boolean · Default: true · Declared in: modules/node/console.nix
Whether the console runs on the machine's screen, tty1, in place of a login prompt.
chalkd serves it, chalkos-console, through the socket /run/chalkd/console.sock, which
root alone reaches, without TLS. The console holds no certificate: it calls what the API
reference says the console may call.
Debug and maintenance¶
The debug tools an image carries, and the OS CA whose clients its maintenance mode accepts.
chalkos.debug.tools¶
Type: boolean · Default: false · Declared in: modules/node/base/closure.nix
Add coreutils, grep, sed, findutils, procps, iproute2 and util-linux to the system path,
and crictl on images with Kubernetes; systemd, bash, less, nftables and kmod are on it
already. Nodes have no logins; use them from a privileged pod on the node, for example
kubectl debug node/<node> -it --profile=sysadmin --image=busybox -- chroot /host /run/current-system/sw/bin/bash.
chalkos.maintenance.osCA¶
Type: path or null · Default: null · Declared in: modules/node/chalkd.nix
The OS CA the image carries, from which chalkd in maintenance mode accepts client
certificates; null accepts any client until the node is installed. mkImage and mkInstaller
set it, in every image and the installer, from their osCA argument,
which describes the file; the image's build checks the file's version again.
Set by mkImage¶
mkImage sets these from its arguments; a module reads them rather than setting them.
chalkos.image.name¶
Type: string or null · Default: null · Declared in: modules/node/settings.nix
The image's name, which mkImage sets, recorded as CHALKOS_IMAGE in its os-release and
as name in its image directory's metadata.json. chalkctl upgrade --image upgrades
the nodes running an image of this name. null on the installer, which is no node image.
No check compares it: a node may change the image it runs through an upgrade, and the
image's schemas decide which config it takes.
chalkos.platform.name¶
Type: string matching [a-z0-9][a-z0-9-]* or null · Default: null · Declared in: modules/node/settings.nix
The platform the image is built for, mkImage's platform, which mkImage sets; null on
the installer, which installs images of every platform. A node refuses an image of another
platform, and translates its config for its own.
chalkos.provenance.revision¶
Type: string or null · Default: null · Declared in: modules/node/base/image-directory.nix
The git revision metadata.json records; mkImage sets it from its
revision argument.
chalkos.provenance.tag¶
Type: string or null · Default: null · Declared in: modules/node/base/image-directory.nix
The git tag metadata.json records; mkImage sets it from its tag
argument.
Sources: the option declarations of the node modules in modules/node/, through
nixosOptionsDoc.