Included profiles¶
The current checkout includes the profiles below. They describe hardware and boot procedures; compatibility still depends on the vendor disk release and the host. Resource values are profile settings, not general recommendations for every release.
| Platform | Embedded profile | Memory (MiB) | Data NICs | Companion files |
|---|---|---|---|---|
| Arista vEOS | arista_veos |
4096 | 20 | Aboot-veos-serial-8.0.0.iso |
| Cisco CSR 1000v | cisco_csr1000v |
4096 | 9 | iosxe_config.txt |
| Cisco Nexus 9000v | cisco_n9kv |
10240 | 8 | OVMF.fd |
| Cisco XRv 9000 | cisco_xrv9k |
16384 | 16 | None listed |
| Community SONiC | community_sonic |
4096 | 16 | None listed |
| NVIDIA Cumulus VX | nvidia_cumulusvx |
4096 | 16 | Embedded nvidia_cumulusvx_breakout.star and .sh.tmpl |
| Juniper vJunos-router | juniper_vjunos-router |
5120 | 96 | None listed |
All profiles in this checkout set managementPassthrough: true. Packaging still uses legacy QEMU user networking. Use a custom YAML path to adapt hardware or boot procedures for a different OS release.
Platform notes¶
- Arista vEOS: Aboot media and PCI placement. The existing directory name
ceosis historical; this is a VM-based vEOS profile. - Cisco CSR 1000v: Bootstrap ISO generated from
iosxe_config.txt. - Cisco Nexus 9000v: UEFI firmware and AHCI disk setup.
- Community SONiC: Console provisioning starts with the packaged
admin/admincredentials. Static management requires a gateway for each configured address family. Restarting a provisioned container is unsupported; remove it and create a fresh node from the image. - Juniper vJunos-router: Nested virtualization, console bootstrap, hierarchical startup configuration, and a longer readiness allowance.
Cisco XRv 9000¶
The cisco_xrv9k profile handles the root-system user dialog, enables baseline management services, and creates the extra internal control and device NICs alongside the management NIC. Its CPU model is qemu64,+ssse3,+sse4.1,+sse4.2; use QEMU_CPU or a tested override where needed. Consult Containerlab's XRv 9000 kind for its interface names and runtime inputs.
NVIDIA Cumulus VX¶
The included profile uses two host CPU cores, virtio NICs, and 4096 MiB RAM. Packaging changes the first-login password to Clab123!, disables ZTP, waits for switchd, and saves configuration. Runtime sets the hostname, management addresses, and selected management services through NVUE.
The current profile uses both IPv4 and IPv6 static template values directly and does not branch for DHCP. For IPv4-only or DHCP labs, adapt the profile using conditional management templates. See the quick start and Containerlab's Cumulus VX kind.
Simulated breakout ports¶
The Cumulus recipe uses the generic profile instruments; its layout parser and
console commands live in two embedded companion files:
nvidia_cumulusvx_breakout.star and nvidia_cumulusvx_breakout.sh.tmpl. Boxen supplies
them automatically when selecting the embedded profile by name or disk detection.
The YAML lists both files in extraFiles. Its virtualMachine.configure function
calls the Starlark layout function to set nicCount; its ordinary
write.contentFromFile step uses the same function before applying guest commands.
To customize the companions without recompiling Boxen, copy the profile and files,
edit them, and build using the custom YAML file path. Its extraFiles entries resolve
beside that YAML and override the embedded companions, including when they use the
same filenames. Both embedded and custom companions are transferred into /boxen.
Bind a user-provided layout at /config/ports.conf. The path is set in the .star
file and can be changed there to read a packaged companion instead. A missing layout
keeps the default 16 data NICs. Packaging also keeps its normal hardware settings;
is_packaging lets the external script distinguish the two phases.
For an existing image, use the runtime/profile rebuild workflow
and copy or mount the companion files into /boxen; that workflow replaces the
runtime and YAML, so new external files must be supplied separately.
The format matches vrnetlab's Cumulus VX support:
entries are N=Mx, separated by newlines or commas. 1x denotes a base port; 2x,
4x, and 8x allocate breakout lanes. Whitespace and # comments are accepted.
Include the highest base port even if it is not split:
Boxen reserves NICs 1 through the highest declared port, then appends every lane in
ascending parent order, including unconnected lanes. Here swp2s0 and swp2s1 use
container interfaces eth65 and eth66; swp10s0 through swp10s3 use eth67
through eth70. Other base ports keep their original indices. Use lane names in
guest configuration and connect lanes rather than their parent ports.
name: cumulus-breakout
topology:
nodes:
leaf:
kind: nvidia_cumulusvx
image: boxen-nvidia_cumulusvx:5.16.1
binds:
- ports.conf:/config/ports.conf:ro
host:
kind: linux
image: alpine:3
links:
- endpoints: ["leaf:eth67", "host:eth1"] # swp10s0 in Cumulus
- endpoints: ["leaf:eth70", "host:eth2"] # swp10s3 in Cumulus
Containerlab PR #3417 adds layout
generation and swpNsM aliases through extras.cumulus-vx. With that support, its
generated /config/ports.conf works directly with Boxen; manual binds and numeric
ethN endpoints also work without those aliases.
The Starlark script parses the layout and derives VM settings before QEMU starts. The console template renames guest interfaces before NVUE runtime commands or startup configuration, using the same externally computed lane mapping.
The guest commands write persistent udev rules
using each guest NIC's MAC, including lanes without a connected container interface.
It reloads saved interface configuration after renaming, including when NVUE has
no configuration changes to apply on a subsequent boot.
This simulates interface names and connectivity; speeds and physical lanes are not
simulated, and the file is not installed as the guest's hardware ports.conf.
Duplicate ports, unsupported lane counts, malformed entries, and layouts exceeding
999 interfaces fail before QEMU starts. To change or remove a layout, create a fresh
container from the packaged image (for Containerlab, deploy --reconfigure) so the
guest disk does not retain old lane names or configuration.
Add another OS¶
Follow adding a platform. Profile names identify Boxen's packaging recipe; Containerlab kinds independently describe how a lab orchestrator handles that platform. Do not assume the two names are identical.