Packages and programs
This page lists every Go program in cmd/ and every package in pkg/, grouped by area. Use it to
find where a piece of logic lives before you change it. Each directory of cmd/ is a main that
wires packages up; the logic lives in pkg/. Paths in the package tables are relative to pkg/.
Architecture for developers shows how the areas fit together.
Every directory of cmd/ and pkg/ that holds Go code other than tests, outside testdata, needs
a row of its own. A directory without Go code, such as pkg/api or pkg/secureboot/microsoft,
has none. The docs check fails on a directory without a row and on a row without Go code.
chalkctl, chalklab, chalkbuild and chalkcfg are cobra command trees in importable packages. Each of
pkg/chalkctl, pkg/chalklab, pkg/chalkbuild and pkg/chalkcfg exports NewCommand(), which
returns the root command, and Execute(ctx, root), which runs it and returns the exit code.
Another program can add their trees to its own, and tests run commands in-process with their
output captured.
These four and chalkd share pkg/internal/cli. Its Execute prints a command's error and sets
the exit status:
- 2, with the command's usage, after a usage error, such as a wrong number of arguments, an
unknown flag or a required flag not set;
- 1 after another error;
- 130 in chalkctl after an error once Ctrl+C cancelled it.
chalkd's tree in cmd/chalkd runs through the same Execute, by way of chalkd.Execute, which
prints each error a failed command joins on a line of its own. Each package keeps its help texts in
help.go. A test requires a short and a long description and an example on every visible command,
because they become the command reference. chalkcfg runs on nodes,
which have no logins, so it has no completion command.
| Program |
What its main does |
cmd/chalkctl |
Runs chalkctl.NewCommand() with a context that Ctrl+C cancels. |
cmd/chalklab |
The same for chalklab.NewCommand(). |
cmd/chalkbuild |
The same for chalkbuild.NewCommand(). |
cmd/chalkcfg |
Runs chalkcfg.NewCommand() on a node. |
cmd/docgen |
Writes the command reference and checks the commands the documentation shows. |
| Package |
What it does |
chalkctl |
The chalkctl command tree, and the list of its layer plugins in layers.go. |
chalkctl/layer |
The interfaces of chalkctl's layer plugins: the plugin, its optional hooks and the Host through which a plugin reaches the cluster and its nodes. |
chalklab |
The chalklab command tree. |
chalkbuild |
The chalkbuild command tree. |
chalkcfg |
The chalkcfg command tree: reads the documents below /run/chalkos/config and the kinds the image's schemas name, and prints them. |
internal/cli |
What the command trees of chalkctl, chalkd, chalklab, chalkbuild and chalkcfg share: usage errors and their exit status, the root and group commands, positional argument checks and flags that take one of a set of values. |
version |
chalkos's version and the git revision of the build, which the linker sets from version.nix and, in the flake's chalkctl and chalkbuild alone, from the flake's revision, and the version command of chalkctl and chalkbuild that prints them. |
inventory |
Reads chalkctl's inventory: the cluster's nodes, the address chalkctl reaches each at, the image each runs and the config files each gets. It passes each node's documents through the filters its caller gives, which chalkctl takes from its layers, and names no layer. |
client |
Connections to chalkd, each with one way to verify the node: by fingerprint in maintenance mode, by the OS CA otherwise; the names chalkd's status gives the OS's certificates and trusted values. |
clustersecrets |
The secrets file: the OS CA and node CA with their keys, the Kubernetes secrets, the recovery secret, the file's age encryption, the rotation of what it holds, and the lock and in-place replacement of the file, which keeps its previous version. |
lab |
QEMU VMs, swtpm, the lab switch and console and the lab's supervisor, for chalklab and the end-to-end tests. |
internal/filecopy |
Copies a disk image without its holes and a plain file to a new one, for chalklab, the lab and image signing. |
Node agent
| Program |
What its main does |
cmd/chalkd |
Builds chalkd's cobra command tree with chalkd.NewCommand and runs it with chalkd.Execute: serve (chalkd.service), load-config (chalkos-config.service), health (chalkos-health.service), check (an image's checker, which another image's chalkd runs) and each layer's commands as chalkd <layer> <command>, such as chalkd kubernetes prepare (chalkos-kubernetes.service). Lists the layer plugins compiled into chalkd in plugins.go, and loads the credentials serve starts with. |
cmd/chalkos-registry |
serve serves pkg/registry on a port of every address, with the node certificate and OS CAs from its systemd credentials, and tells systemd once it listens; catalog PORT prints the repositories of the registry on this node, for a diagnostic. |
| Package |
What it does |
api/node/v1, api/node/v1/nodev1connect |
The messages and Connect client and server of the node API, generated by buf generate. |
chalkd |
The node API server, with the permissions of each NodeService method; the registry of layer plugins it mounts, starts and asks for hooks; and chalkd's work at boot: the node certificate's renewal and the health check. |
chalkd/layer |
The interfaces of chalkd's layer plugins, their optional hooks and the registry of the compiled and active plugins. |
chalkd/renewal |
Renews a certificate, or a set of them, once it is due, for the node certificate and a layer's own; without anything to renew it with, it logs once that the certificate is due. |
layers |
Reads the layers an image carries from their markers in /etc/chalkos/layers, for the plugins chalkd activates and the layers of Info and Contract. |
pki |
The OS CA and node CA, client and node certificates and their checks, client roles, PEM keys and certificate bundles. |
registry |
An OCI registry: distribution's registry handlers with the filesystem storage driver alone, over TLS with the node certificate, which it reads once: its unit restarts it when chalkd replaces the certificate. Anyone reads, and an Authorization header on a read is ignored; writes, deletes and garbage collection take a client certificate of the admin role, verified again for every request, which no certificate of the node CA has. Garbage collection runs on an admin's request alone and refuses writes while it runs. |
diagnostics |
Reads the image's diagnostics.json, checks a call's arguments against their parameters' types, builds the command line, and runs it as a transient systemd unit with a sandbox of its own. |
askpassword |
A systemd password agent: answers the password requests that ask.* files in /run/systemd/ask-password name. |
tool |
Runs the command-line tools chalkd, the installer and the storage code drive, such as cryptsetup, sfdisk and systemctl. |
tool/systemctl |
Asks systemd about units through the tool runner: their properties, whether they are active, the failed units and the units of a target. |
command |
Runs a program of the image's store with bounded output, for command facts and outputs; a failure keeps standard error out of its error. It also follows a path's links within an image's store, and stops a transient unit or reads why one failed. |
Image, install and upgrade
| Package |
What it does |
arch |
The architectures chalkos builds images for, with every name and number each goes by. |
image |
Reads a disk image: its partitions from repart-output.json, its store and hash tree, the UKI and boot loader off its ESP, and the provenance metadata.json names. |
imagepart |
Describes the parts an image is sent in, its store, hash tree, UKI and boot loader, by size and SHA-256, and receives them from a stream. |
imagesign |
Signs an image's boot loader and UKIs, in place or in a signed copy of an image directory. |
ociimage |
Reads, writes, pulls and pushes chalkos images as OCI artifacts: one manifest whose config is the image header and whose layers are the store, hash tree, UKI, boot loader and contract. |
imagepull |
Pulls a chalkos image from a registry, checked as a node checks it, into an image directory with a raw disk image as nix build lays it out, or into the OCI layout the registry serves; chalkctl image pull runs it. |
install |
Installs a node in place or from the installer, step by step and repeatable: STATE, the ESP, the UEFI boot entries, wiping the target and the system region's definitions each have a file, and parts.go holds the steps of an install from the installer. |
upgrade |
Writes an image into the inactive slot and stages it there (Install), makes the staged image the next boot (Activate), or both (Upgrade); the image header and the checks of its UKI and boot loader an install shares; the booted entry and the provenance record. |
storeslot |
The store slots of a disk and the writer an upgrade and an install share: retire a slot, write and verify the store, activate the slot. |
esp |
Lists the UKIs on an ESP with the image and generation each boots, writes a UKI under a temporary name, reads the UKI of an image staged in the inactive slot, and removes and names UKIs, for an install and an upgrade. |
uki |
Reads a UKI's os-release and command line and an EFI binary's architecture, and refuses an image version systemd-boot would order its entry by. |
verity |
Reads and checks dm-verity hash trees. |
secureboot |
Checks an EFI binary's Authenticode signature as Secure Boot firmware does, against db and dbx read from the firmware or against given certificates. Its microsoft/ directory holds Microsoft's KEK, UEFI and option ROM CA certificates, which chalkctl secureboot enroll --microsoft enrols. |
atomicfile |
Replaces a file in one step through a synced temporary file, and syncs directories, so a crash leaves the old content or the new. Writes a new file that must not exist yet, and takes the file locks that keep two processes apart. |
Storage
| Program |
What its main does |
cmd/chalkos-storage |
Opens STATE and sets up the volumes in the initrd, runs as a systemd generator for the other volumes, and prints the storage facts the storage kinds' rules read. |
| Package |
What it does |
storage |
Storage sections, disk references and pins, repart definitions, and the changes a delivered section makes to the recorded one. |
storage/gpt |
Reads and changes partition tables with sfdisk under the disk's lock, waiting a bounded time for it, writes the GPT of a disk image, and names the partition types of the system region. |
storage/hostops |
The host operations the installer, an upgrade and the storage code share: mounts, LUKS and dm-verity volumes, the mount table, and the blkid probe. Ops is the interface the installer, an upgrade and the storage setup call, and that tests replace with a fake. Tools implements it and runs mount, umount, systemd-cryptsetup and veritysetup; it is the one place their command lines are written. Probe, Content and Type run blkid on a tool.Runner. |
storage/node |
Storage on the node: STATE, volumes, VAR and the generator's units; the storage changes chalkd makes and the volumes an install creates and enrols. |
Config pipeline
| Program |
What its main does |
cmd/chalkos-render |
Renders the outputs of the chalkosLib.render.template and .documents renderers and the built-in outputs networkd (with router-networkd on router images), router-sysctl, router-nftables, frr, jool, unbound, kea and dhcp-relay on a node, in an output's sandbox, and a router image's fallback ruleset and FRR config when the image is built. Runs the validator router as chalkos-render validate router. The renderers trust what the schemas, the rules and the validators check, refuse what only they see, such as networkd's unit names, and keep guards, as internal errors, where a bad value would break their output. |
cmd/chalkos-rules |
check checks an image when it is built: every rule compiles within the cost limit and reads facts the image declares, the effects act on units, outputs and kinds the image has, every output and validator is a program of its store, and every diagnostic is one chalkd can run. test runs the image's tests, chalkos.tests, through pkg/check as chalkd checks a delivery, and writes the files, refusals and effects each test got. |
cmd/chalkos-networkd-schema |
Writes the spec schemas of the networkd kinds from systemd's gperf tables, for the image build. |
cmd/chalkos-frr-reload |
Applies a changed frr.conf to the running FRR on a reload of frr.service, through pkg/frr. With -n, prints the commands it would run. |
| Package |
What it does |
config |
Config documents: parsing, the rules of a set, defaults, the redacted form that programs read, the hash, and the translation into the identity the node applies, which runs the translators of the image's layers after the common part. |
config/slot |
Keeps a node's config on STATE, a slot per image with its identity, and writes it for the node's units: the documents below /run/chalkos/config and the secrets the granted units load as credentials. |
identity |
The node's identity, the form its config translates to, which the node applies at boot: the hostname, platform, network and storage every image has, and a part for each layer that adds one, by the layer's name. The package does not interpret the layers' parts. |
schema |
Reads an image's metadata.json and the JSON Schemas of its kinds, checks documents against them and fills in their defaults. |
frr |
Reloads FRR: parses frr.conf and the running config into contexts, works out the commands that turn one into the other, and applies them with vtysh -f, then reads the running config again. It knows the commands the router and Kubernetes renderers write and refuses a config that holds another. |
contract |
Loads an image's contract from one directory, /etc/chalkos on a node or the directory chalkos-rules checks: the schemas, the facts, effects, services, outputs, validators and diagnostics they declare, each definition checked as chalkd needs it. It compiles the change rules and the effects' rules once, when they are first asked for. |
jsonfile |
Reads a JSON file an image may leave out, such as facts.json, effects.json or outputs.json, with each definition by name checked, and decodes JSON that must hold one value of known fields. |
rules |
Compiles the change rules of an image's schemas, with chalkos's CEL functions, and evaluates them against a config, the config it replaces and the node's facts. |
facts |
Loads the facts change rules read: files, and commands of the image's store run in a sandbox. |
check |
Checks a node's config as an image does, in four stages, the methods of check.Image: Translate, Rules, Validate and Render. Each returns a *check.Refusal for a config it refuses. Run runs them in order and plans the effects, for chalkd check and an install in place. A delivery runs them between chalkd's checks of the machine, and chalkctl runs the first three without the node's facts and with the validators it links. |
api/check/v1, api/check/v1/checkv1connect |
What chalkd and an image's checker exchange: the Input chalkd writes to chalkd check, the Result it reads back, and FactsService, which serves the checker the node's facts. Generated by buf generate. |
imagecheck |
Runs an image's chalkd check from the image's own store in a sandboxed transient unit, with the image's store over /nix/store, and serves it the node's facts over a Unix socket. |
outputs |
Runs the programs of an image that read a node's config, renderers and validators, on one input and with one runner: in a sandbox of their own, as an unprivileged user, with their reports of refusals read alike. It swaps rendered outputs in by a symlink rename and records their hashes and failures, and runs the validators chalkctl links in-process on the same input. |
refusals |
The format in which an output's renderer or a validator reports what it refuses of a node's documents: one JSON object on standard output, each refusal naming a document's kind and name and a field's path. |
effects |
Reads the image's services.json, the units granted config kinds, and effects.json, what a delivery does to those units and to chalkd, and refuses an effect chalkd could not carry out. Carries out the due effects on the units: the reloads, the commands and the restarts, in the units' order. |
nodeconfig |
Applies the running image's config slot, chosen by usrhash=, at boot (chalkd load-config) and after every apply: the hostname and /run/chalkos/node.json; writes the config's documents and secrets for the granted units, and renders the outputs at boot, networkd's units and chrony's servers among them. |
networkdschema |
Generates the spec schemas of the networkd kinds from systemd's gperf tables. |
Kubernetes
| Package |
What it does |
api/kubernetes/v1, api/kubernetes/v1/kubernetesv1connect |
The messages and Connect client and server of the Kubernetes layer's API, generated by buf generate. |
chalkd/layers/kubernetes |
chalkd's Kubernetes layer: KubernetesService, the node's Kubernetes loops, the control plane's, the join and the VIP election, the issuer of node certificates, and the chalkd kubernetes commands and actions. |
chalkctl/layers/kubernetes |
chalkctl's Kubernetes layer: the commands that run Kubernetes and etcd and revoke nodes, the Kubernetes section of a node's status, the facts of its images, the share it delivers, the quorum checks, drains and uncordons of the reboot step that upgrade and node reboot share, and the rotations of the Kubernetes secrets. |
kubernetes |
The node's Kubernetes cluster as kubernetes/translate builds it from the config and the image's facts, its flags and address ranges, the node as the Kubernetes part of its identity (NodeIdentity) names it, the kinds of Kubernetes nodes (control plane and worker), and the control plane's ports and paths on a node. |
kubernetes/translate |
The Kubernetes layer's part of a config's translation: builds the cluster from the Node, Cluster and Flannel documents and the image's facts, adds the node's Kubernetes settings to its identity, and reads the sandbox image and the Addon objects. For chalkctl and chalklab it reads a node's type, leaves the Addon documents to control planes, and checks that an inventory's nodes hold the same Cluster, Flannel and ClusterRegistry specs, whose endpoint it returns. Reads the ClusterRegistry for chalkd and chalkctl. |
kubernetes/addons |
Renders the objects chalkos applies to every cluster before its own manifests: RBAC for chalkos's identities, kube-proxy, flannel and CoreDNS. |
kubernetes/apply |
Server-side apply of manifests and approval of kubelet serving certificates. |
kubernetes/clusterregistry |
The cluster registry as Go reads the ClusterRegistry kind: the mirrored hosts as repository path prefixes, the endpoints in the order a node pulls from them, and the URLs containerd pulls a host's images from. Standard library alone, so that chalkos-render can link it. |
kubernetes/credprovider |
The kubelet's image credential provider: writes its config and the node's registry credentials from the Registry documents, and answers the kubelet's requests. |
kubernetes/etcd |
etcd membership: learners, promotion, quorum-safe removal, the node's own member; finds the members from etcd's mirror pods and counts encrypted values by key. |
kubernetes/manifests |
The control plane's static pods. |
kubernetes/node |
The node's Kubernetes files at boot: addresses, kubelet credentials and flags, control-plane certificates, the check that they are prepared, the removal of the static pods. |
kubernetes/nodeip |
Picks the node's address of each family. |
kubernetes/pki |
The Kubernetes certificates: the share, the control plane's leaves, admin kubeconfigs, and the names chalkd's status gives them. |
kubernetes/revoked |
The ConfigMap of revoked nodes, which control planes read before they renew a node certificate, and the admission policy that shuts those nodes out. |
kubernetes/vip |
The etcd election of the control plane that holds the VIPs; adds a VIP to an interface and announces it. |
kubernetes/vxlan |
The nftables table chalkos-vxlan: marks VXLAN to the node's addresses for the firewall and drops pods' VXLAN to the source ranges. |
imageref |
Reads container image references as config names them: a repository with its registry, a tag, a digest, or both. A tag of the form vX.Y.Z carries the version of what the image runs. |
Router
| Package |
What it does |
api/router/v1, api/router/v1/routerv1connect |
The messages and Connect client and server of the router layer's API, generated by buf generate. |
chalkd/layers/router |
chalkd's router layer: RouterService, with the state of the node's FRR, Jool and Unbound and the kernel's routes. |
chalkctl/layers/router |
chalkctl's router layer: chalkctl node routes, the router's section of a node's status and the validator router, which it links. |
frr/status |
Queries local FRR with a bounded wait and reads its BGP sessions from vtysh's JSON. |
router |
Reads a router's state: its BGP paths of each VRF from vtysh's JSON, its NAT64 instances, counters and pools from jool's CSV, the kernel's routes from netlink, and the filter of a Routes call. |
router/derive |
The router's model of a node's config: the router kinds' documents and what the Network and VRF documents say together, such as each link's VRF, the .network units in networkd's order, the NAT64 instances and the tables of policy routing. The router's outputs render from it. It holds the checks of the validator router, Validate, which refuses what the outputs would apply otherwise than the documents say and reports every fault it finds, each once, the VRFs' links first and what reads them once those pass. chalkos-render validate router runs it, and chalkctl links it. It takes the standard library and the package refusals alone. |
router/keaconf |
The part of Kea's DHCPv4 and DHCPv6 configs that the output kea writes: the renderer marshals these types, and chalkd reads the rendered files back into them. |
router/services |
The names of the files, units and runtime directories of the router's services that run once per VRF: Kea, Unbound and dnsmasq's DHCP relay. The renderer, the router modules and chalkd share them. |
dns |
The syntax of the DNS names and record data of a Resolver's local zones, which the rules' isDNSName() and isRecordData() check and the output unbound guards with, so the two cannot drift apart. |
Console and status
| Program |
What its main does |
cmd/chalkos-console |
Runs the console on tty1, in place of a login prompt, and lists the layer tabs compiled into it in layers.go. CHALKOS_CONSOLE_ACTIONS=1 in its unit's environment offers the actions. |
| Package |
What it does |
console |
The console on a machine's screen: a live view of the node that chalkd serves on its console socket, with a header of the node's identity and health, tabs for its status, network, storage and logs, the tabs of the image's layers, and actions for a node that chalkctl cannot reach. |
console/layers/kubernetes |
The console's Kubernetes tab: the layer's section of the node's status, and the warning before a reboot, a shutdown or a rollback, which skip chalkctl's drain. |
console/layers/router |
The console's Router tab: the router layer's section of the node's status, and the DHCP leases and WireGuard peers that the image's diagnostics show. |
statusview |
Writes a node's status as people read it: what chalkctl status prints and the console shows, and the disks of chalkctl disks. |
statusview/layers/kubernetes |
Writes the Kubernetes layer's section of a node's status, for chalkctl status and the console's Kubernetes tab. |
statusview/layers/router |
Writes the router layer's section of a node's status, for chalkctl status and the console's Router tab. |
Shared helpers
| Package |
What it does |
internal/poll |
Checks a condition again and again until it passes, a timeout passes or the context ends, keeping the last check's error. |
internal/strs |
Joins values into the lists of messages and flags: by their String, or names as prose, such as "a, b and c". |
Test helpers
Test helpers live in packages of their own:
| Package |
What it provides |
askpassword/askpasswordtest |
Password requests made as systemd makes them, which record the answers. |
chalkd/chalkdtest |
The layers chalkd compiles in and the Kubernetes image's effects, for the tests that run chalkd's server. |
chalkd/layer/layertest |
Checks of a layer's API against its plugin's permissions. |
chalkd/layers/kubernetes/kubernetestest |
A node's Kubernetes files, shares and CAs, and stand-ins for the preparation, the API server's Node and chalkd. |
chalkd/renewal/renewaltest |
Runs a renewal in a synctest bubble and hands the test each check. |
console/consoletest |
A fake client and test nodes for the console, and helpers that run it on a terminal of 80 columns and 25 lines and compare its screen. |
image/imagetest |
Small disk images, db signers and sbsign. |
internal/cli/clitest |
Checks of the programs' cobra command trees. |
internal/golden |
Compares a test's output with a golden file, which go test -update rewrites. |
internal/netnstest |
Runs a test in a user and network namespace of its own. |
internal/testwait |
Eventually waits in real time for a condition, and Bubble runs a test in a synctest bubble with a fake clock. |
kubernetes/etcd/etcdtest |
In-process etcd members. |
kubernetes/kubetest |
A cluster and its images, a node, and the Cluster and Node documents that describe them. |
ociimage/ocitest |
In-memory OCI registries and small chalkos images. |
pki/pkitest |
Node CAs. |
registry/registrytest |
pkg/registry served on loopback with a node certificate of the test's OS CA. |
router/derive/derivetest |
A router's documents by kind, and the scenarios that the router outputs and the validator router both test. |
schema/schematest |
The fixture schemas of test/fixtures. |
secureboot/secureboottest |
TPM event logs as firmware writes them. |
storage/hostops/hostopstest |
A fake host that keeps its mounts and device-mapper volumes in maps. |
storage/storagetest |
The sysfs, udev and /dev trees of a host's disks. |
tool/tooltest |
A fake tool runner that records commands and answers them by prefix. |
uki/ukitest |
Small UKIs. |
upgrade/upgradetest |
A small image that a UKI boots, and a partition of a disk image as a file. |
Sources: the directories of cmd/ and pkg/, and each package's doc comment.