Cnuas Deployment¶

End-user install / upgrade / remove of Cnuas artefacts. Targets two audiences:

Students who want the full lab in one shot, against a known-good coherent kernel + qemu + drivers + image bundle.
Power users who want to install only CnuasNIC, only CnuasGPU, only CnuasSwitch, or only CnuasLink against an already-installed bundle (or build the component from source themselves).

Quick start (full lab)¶

pip install --user cnuas-tools          # or pull the wheel from a Release
cnuas-tools deploy install              # downloads + installs latest bundle
sudo modprobe cnuas_net cnuas_ib cnuasgpu
sudo usermod -aG kvm $USER && newgrp kvm  # one-time, for vm lab
cnuas-tools vm lab                       # bring up vm-a + vm-b

That's it. The lab is up; ssh -p 2222 cnuas@localhost lands in vm-a.

Quick start (component only)¶

pip install --user cnuas-tools
cnuas-tools deploy install --component cnuasnic         # just CnuasNIC
cnuas-tools deploy install --component cnuasgpu         # just CnuasGPU

The component installer reads a small compat.json from the component's GitHub Release and:

refuses to install if the running kernel doesn't match the kernel the .debs were built against (override with --ignore-kernel if you really know);
leaves your existing bundle (if any) intact.

The kernel + golden qcow2 image are bundle-only artefacts, a CnuasNIC-only install will work against whatever kernel/image you already have, but you DO need to have those somewhere (typically from a prior cnuas-tools deploy install of the bundle, or from your own cnuas-tools image build of a clone).

Two-tier release model¶

Tier	Where it lives	Carries	Audience
Bundle	one Release on `PacketFive/cnuas`	every `.deb`, the qcow2 image, the cnuas-tools wheel	full-lab users
Component	one Release per component repo (CnuasNIC, CnuasGPU, CnuasSwitch, CnuasLink)	just that component's `.deb`(s) + a `compat.json`	focused users

The bundle is the source of truth for "what does this version of the Cnuas look like". Component releases are a convenience for users who don't want the whole stack.

Coherence between component releases is the user's responsibility, enforced via the compat.json kernel-version check. If you mix CnuasNIC v0.2 (built for kernel 6.19) with a kernel from a different bundle, the deploy CLI refuses; if you override that with --ignore-kernel, modprobe itself will refuse, which is fine but less ergonomic.

CLI reference¶

cnuas-tools deploy install [--component NAME] [--version TAG] [--dry-run] [--ignore-kernel]
cnuas-tools deploy list
cnuas-tools deploy check
cnuas-tools deploy uninstall [--component NAME]
cnuas-tools deploy paths

`install`¶

Resolves a release (latest or --version-pinned), downloads the declared assets, verifies every sha256 against compat.json, apt-get installs the .debs, and (bundle only) drops the qcow2 in ~/.local/share/cnuas/images/ and points current.qcow2 at it.

`list`¶

Prints the on-disk install state. Driven by ~/.local/share/cnuas/state/deploy.json, not by the dpkg database, so a dpkg -r cnuas-... doesn't desync the view, but cnuas-tools deploy uninstall does.

`check`¶

Re-validates the kernel version of the currently running host against the kernel the installed bundle / components were built for. Returns non-zero on mismatch, so it's CI-friendly.

`uninstall`¶

apt-get removes the recorded .debs. --component NAME removes only that component; otherwise removes everything from the recorded bundle + recorded individual components. The qcow2 stays around under its versioned name (so you can roll back to a prior install).

`paths`¶

Shows where the deploy CLI looks for state, images, and the current.qcow2 symlink. Useful for shell completion and for the runner-with-no-repo audit trail.

Publisher workflow (release engineers)¶

# Build everything into out/
poetry -C tools run cnuas-tools pkg build cnuas-nic-modules
poetry -C tools run cnuas-tools pkg build cnuas-gpu-modules
# ... etc
poetry -C tools run cnuas-tools image build
poetry -C tools run python -m build tools   # or poetry build

# Preview the manifest
poetry -C tools run cnuas-tools release manifest v0.3.0
poetry -C tools run cnuas-tools release manifest v0.3.0 --component cnuasnic

# Publish (uses `gh` CLI for auth + upload)
poetry -C tools run cnuas-tools release publish v0.3.0           # bundle on cnuas
poetry -C tools run cnuas-tools release publish v0.2.0 \
    --repo PacketFive/CnuasNIC --component cnuasnic                     # per-component

# Verify a published release end-to-end
poetry -C tools run cnuas-tools release verify v0.3.0

The publisher requires the gh CLI on $PATH and a valid gh auth login. Token discovery falls through to GH_TOKEN / GITHUB_TOKEN env vars (so CI runs work).

`compat.json` schema (v1)¶

Two flavours, distinguished by "kind":

Bundle¶

{
  "schema": 1,
  "kind": "bundle",
  "release": "v0.3.0",
  "kernel_version": "6.19.0-cnuas+",
  "qemu_tag": "cnuas-qemu-v0.2.0",
  "components": {
    "cnuasnic":    {"version": "0.1.0"},
    "cnuasgpu":    {"version": "0.2.0"},
    "cnuasswitch": {"version": "0.1.0"},
    "cnuaslink":   {"version": "0.1.0"}
  },
  "assets": [
    {"name": "cnuas-nic-modules_0.1.0_amd64.deb",
     "sha256": "<hex>", "size": 12345},
    ...
  ],
  "image": {"name": "cnuas-vm-v0.2.0.qcow2",
            "sha256": "<hex>", "size": 12345}
}

Component¶

{
  "schema": 1,
  "kind": "component",
  "component": "cnuasnic",
  "version": "0.1.0",
  "kernel_version": "6.19.0-cnuas+",
  "qemu_tag": "cnuas-qemu-v0.2.0",
  "cnuas_min": "0.3.0",
  "assets": [
    {"name": "cnuas-nic-modules_0.1.0_amd64.deb",
     "sha256": "<hex>", "size": 12345}
  ]
}

Schema bumps are forward-incompatible: a CLI that knows schema 1 refuses schema 2. The deploy CLI prints a clear "upgrade cnuas-tools" error in that case.

Why not just `apt`?¶

Long-term, yes, a self-hosted apt repo + signing key would be the obvious next step (Option C in the design discussion). For now, the GitHub Releases approach:

needs zero infra (PacketFive doesn't run a Debian repo);
is trivially mirrorable for air-gapped students (download the Release tarball, copy, cnuas-tools deploy install --from-dir , not yet implemented; a future enhancement);
gives end users the same artefact pinning the CI gates already use.

The CLI surface is designed so a future apt repo backend slots in behind the same cnuas-tools deploy commands.

Cnuas Deployment¶

Quick start (full lab)¶

Quick start (component only)¶

Two-tier release model¶

CLI reference¶

install¶

list¶

check¶

uninstall¶

paths¶