Skip to content

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.

Command-line tools

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.