| Item |
Value |
| Part |
cnuas-tools |
| Type |
Developer and operator tooling |
| Package |
cnuas-tools, version 0.2.0 |
| Version |
fd0f896-dirty |
| Repo |
PacketFive/cnuas |
1. Overview
cnuas-tools turns a checked out superproject into something runnable. It
builds the Debian packages for every component, bakes the golden guest image,
starts and stops the laboratory virtual machines, publishes releases with a
manifest, installs components onto a host, and bridges a sled management
controller to an emulated blade.
Where the control plane operates a running
platform, cnuas-tools produces and installs one.
Key features
- Nine Debian package targets plus a bundle target, built from one command.
- Reproducible golden image build with a checksum and a manifest.
- Direct QEMU virtual machine lifecycle with cloud-init seeding and serial
console capture, with no libvirt dependency.
- Release publication and verification against a manifest.
- Host installation with a component registry and a host tuning step.
- Sled management controller bridge driving an emulated blade over general
purpose input and output through the emulator monitor.
2. Command reference
| Group |
Commands |
Purpose |
pkg |
list, build, clean |
Debian package production |
image |
build, inspect, verify |
Golden guest image |
vm |
up, down, console, ssh, scp, list, lab, lab-down, destroy |
Virtual machine lifecycle |
release |
publish, verify, manifest |
Release artefacts |
deploy |
install, list, check, uninstall, paths, host-tune |
Host installation |
sledbmc |
bridge, status |
Sled management controller to blade bridge |
Root flags: --verbose, --version.
3. Package targets
| Package |
Contents |
cnuas-nic-modules |
cnuas_net.ko, cnuas_ib.ko |
cnuas-gpu-modules |
cnuasgpu.ko and the accelerator tools |
cnuas-vswitchd |
Fabric switch daemon |
cnuas-cli |
Switch command line client |
cnuas-link-cli |
Accelerator fabric command line client |
cnuas-libcnuas-provider |
rdma-core verbs provider |
cnuas-libcnuasrt |
Accelerator runtime, device library and compute backends |
cnuas-linux-image |
Cnuas kernel fork image |
cnuas-nccl-tests |
Collective benchmarks |
cnuas |
Bundle that pulls in the set |
4. Golden image
| Item |
Value |
| Output |
cnuas-vm-vX.Y.Z.qcow2 |
| Base |
Ubuntu 24.04 cloud image, fetched by the recipe |
| Kernel |
Resolved from the kernel fork build, falling back to the build host release |
| Build steps |
Resize, customise, sparsify |
| Recipe controls |
Base image location, disk size, packages, user, modules, services, udev rules, post install steps |
| Products |
The image, a manifest, and a SHA-256 checksum |
image inspect reports what a built image contains and image verify checks it
against the recorded checksum.
5. Virtual machine lifecycle
| Command |
Behaviour |
vm up |
Create a copy on write overlay, build the cloud-init seed, start QEMU |
vm down |
Stop a running machine |
vm console |
Follow the captured serial log |
vm ssh, vm scp |
Reach the guest through the forwarded port |
vm list |
Report machine state |
vm lab, vm lab-down |
Bring the two machine laboratory up or down together |
vm destroy |
Force stop, with optional removal of the overlay |
The engine is QEMU directly. There is no libvirt layer, which keeps the guest
command line visible and reproducible.
6. Deployment registry
| Component key |
Repository |
cnuas |
PacketFive/cnuas |
cnuasnic |
PacketFive/CnuasNIC |
cnuasgpu |
PacketFive/CnuasGPU |
cnuasswitch |
PacketFive/CnuasSwitch |
cnuaslink |
PacketFive/CnuasLink |
deploy check verifies an installation, deploy paths prints where each
component landed, and deploy host-tune applies the host settings the emulated
fabric expects.
7. Validation
| Area |
Test files |
Cases |
| Root command line, process runner, configuration |
tests/test_cli.py, tests/test_run.py, tests/test_config.py |
18 |
| Packaging |
tests/pkg/ |
14 |
| Image build, manifest, recipe |
tests/image/ |
23 |
| Virtual machines |
tests/vm/ |
16 |
| Sled bridge and emulator monitor protocol |
tests/sledbmc/ |
33 |
| Deployment |
tests/deploy/ |
10 |
All 122 cases pass, and they run without a build host or an emulator because the
external steps are exercised through recorded interfaces. See the
Validation Matrix.
| Item |
Value |
| Repo |
PacketFive/cnuas |
| Source |
tools/src/cnuas_tools/ |
| Entry point |
cnuas-tools |
| Python |
3.11 or later |
| External tools |
QEMU, virt-resize, virt-customize, virt-sparsify, dpkg-deb |
| Related |
Deployment |
9. Revision history
| Revision |
Notes |
| A |
First publication. Command tree, package targets and registry read from the source. |