Skip to content

HOWTO: Testing CheriBSD

Jump to bottom
George V. Neville-Neil edited this page May 13, 2026 · 4 revisions

The testing of desktop operating systems is a difficult matter,
It isn't just one of your holiday games; — Apologies to T.S. Eliot

Scope and conventions

This plan covers manual testing of a CheriBSD release image on an Arm Morello development board. Each section is a self-contained block of steps with a checklist; mark each box as you go and note any deviations in the Notes field at the bottom of the block.

Reference documents (read before starting):

Test record header (fill in once, at the top of your test run log):

Field Value
CheriBSD release under test e.g. 25.03
Image filename e.g. cheribsd-memstick-arm64-aarch64c-25.03.img
Image SHA-256
Morello firmware revision
Tester
Test date
Board serial / asset tag

0. Prerequisites

Before any of the test blocks below, you need a working Morello board, a workstation to write the USB image and drive the management console, and (for the full installation test and everything after it) an Internet connected network .

0.1 Hardware and cabling

  • Morello board powered and connected to the workstation via the management USB cable (see https://ctsrd-cheri.github.io/cheribsd-getting-started/morello-console/index.html).
  • HDMI display attached to the board (required for Desktop Testing).
  • USB keyboard and mouse attached to the board (required for Desktop Testing).
  • Ethernet cable attached to the board and to a network that provides DHCP and outbound Internet access.
  • At least one USB stick of 8 GiB or larger, dedicated to the installer image.
  • Terminal emulator on the workstation that can speak to two USB serial ports (e.g. cu, tio, minicom, screen, PuTTY or Serial on macOS).

0.2 Image acquisition

0.3 Firmware

The Morello firmware must be reasonably current; older revisions have a bug that makes OS-triggered reboot unreliable, which will affect several test blocks below.

1. Installation Testing

The goal of an installation test is to confirm that a new image can be fully installed, including both the Desktop Software and the Virtualization packages. A full installation test requires a working Internet connection so that the Desktop and Virtualization packages can be installed. An Image Only installation test requires only that you have the installation image on some form of removable media.

Instructions for how to obtain the installer image are in §0.2 above and at https://ctsrd-cheri.github.io/cheribsd-getting-started/downloading/index.html.

1.1 Image-Only installation

This block exercises the installer itself with no network dependency. It must be possible to complete this block on an air-gapped board.

  • Disconnect the Ethernet cable from the board.
  • Insert the prepared USB stick into one of the board's USB ports.
  • Power the board on and observe MCC output on the management console.
  • When prompted, press Escape on the system console to enter the UEFI boot menu.
  • Select Boot Manager and then the USB stick. Confirm that the CheriBSD boot loader is displayed and that the kernel boots without panics scrolling past.
  • At the installer menu, select Install.
  • Set the hostname (record value): __________________________________
  • Select system components. Accept the defaults for an image-only test.
  • Partition the internal disk using Auto (ZFS)
  • Set the root password.
  • At the Network Configuration screen, Skip network setup.
  • At the Desktop Environment prompt, answer No.
  • At the CHERI VM Support prompt, answer No.
  • Complete the installer and exit to live system (or reboot, see caveat below).
  • Remove the USB stick before the post-install reboot, otherwise the installer will run again.
  • If reboot hangs, type reboot on the MCC console (see §0.3).
  • After reboot, log in as root on the serial console.
  • Run uname -a and confirm the release string matches the image under test. Record output:
(paste uname -a here)
  • Run dmesg | grep -i panic and dmesg | grep -i error. Note anything unexpected.

Result: ☐ PASS ☐ FAIL ☐ BLOCKED

Notes:

1.2 Full installation (Desktop + Virtualization)

The full test installs the system from the same image but with network access enabled and both add-on package sets selected.

  • Reconnect Ethernet.
  • Re-insert the USB stick and power-cycle the board.
  • Enter the UEFI boot menu and boot the USB installer.
  • Start a new install. Wipe the disk used in .
  • Set the hostname, root password, and disk layout as in §1.1.
  • At the Network Configuration screen, configure the wired interface (DHCP is normally correct). Record the assigned IP: __________________________________
  • Confirm DNS resolution from the installer shell if available (Live CD → host www.cheribsd.org).
  • At the Desktop Environment prompt, answer Yes. The installer will fetch the cheri-desktop package set; expect this to take several minutes.
  • At the CHERI VM Support prompt, answer Yes. The installer will fetch the bhyve / VM support packages.
  • Watch the installer log for pkg fetch failures. If any package fails, record the package name and abort with FAIL.
  • Complete the installer, remove the USB stick, reboot.
  • Log in as root on the serial console.
  • Confirm cheri-desktop is installed: pkg64 info cheri-desktop
  • Confirm bhyve / VM packages installed: pkg64 info | grep -i bhyve
  • Confirm sddm is enabled in /etc/rc.conf and that the graphical login screen appears on the HDMI output.

Result: ☐ PASS ☐ FAIL ☐ BLOCKED

Notes:

2. Desktop Testing

Prerequisite: §1.2 PASS. The desktop is a basic KDE/Wayland environment compiled for CheriABI, using the on-SoC Mali Bifrost GPU via Panfrost and DRM. Feature documentation: https://ctsrd-cheri.github.io/cheribsd-getting-started/features/desktop.html.

2.1 Graphical login

  • On the HDMI display, the SDDM login greeter appears within 60 s of the multi-user boot completing.
  • The greeter accepts the root password (or, preferred, a non-root user created during installation).
  • A KDE Plasma session starts and the panel renders without artifacts.

2.2 Window manager basics

  • Open and close a window (e.g. System Settings). Window decorations render correctly.
  • Move, resize, minimize, maximize a window with the mouse.
  • Switch between two open windows with Alt+Tab.
  • Open a second virtual desktop and move a window to it.

2.3 Terminal and core apps

  • Launch Konsole. The shell prompt appears within 5 s.
  • Run uname -a inside Konsole and confirm CheriBSD kernel.
  • Run procstat -ac $$ to confirm the shell is a CheriABI process.
  • Launch Dolphin (file manager) and browse /.
  • Launch the text editor (KWrite or Kate); open, edit, save a file in /tmp.

2.4 Browser (hybrid ABI, optional)

The cheri-desktop-hybrid-extras package ships a hybrid-ABI Chromium for 24.05+; check pkg64 info before testing.

2.5 Logout / shutdown

  • Log out of the KDE session and return to SDDM.
  • From SDDM, request Shutdown. Board powers down cleanly (or hangs due to the known firmware reboot bug — if so, note and use reboot on the MCC console).

Result: ☐ PASS ☐ FAIL ☐ BLOCKED

Notes:

3. Virtualization Testing

Prerequisite: §1.2 PASS with CHERI VM Support selected. CheriBSD ships an experimental CHERI-extended bhyve on Morello; see https://ctsrd-cheri.github.io/cheribsd-getting-started/features/bhyve.html.

3.1 Module and tool presence

  • kldstat | grep vmm shows the vmm module loaded (or loadable via kldload vmm).
  • which bhyve bhyveload bhyvectl vm returns paths for each.
  • sysctl hw.vmm returns at least one OID without error.

3.2 Network bridge for guests

  • Create a bridge and tap interface for the guest:
ifconfig tap0 create
sysctl net.link.tap.up_on_open=1
ifconfig bridge0 create
ifconfig bridge0 addm <ethernet-iface> addm tap0 up
  • Confirm the bridge is up and learning addresses with ifconfig.

3.3 Boot a CheriBSD guest under bhyve

Use the same memstick image used to install the host, or download a second copy into /var/tmp on the host.

  • Stage the guest image on the host: cp /var/tmp/cheribsd-memstick-arm64-aarch64c-25.03.img /var/vm/guest.img
  • Launch bhyve (adjust device names as needed for your environment):
bhyve -c 2 -m 2G \
    -s 0,hostbridge \
    -s 1,virtio-blk,/var/vm/guest.img \
    -s 2,virtio-net,tap0 \
    -s 31,lpc \
    -l com1,stdio \
    cheri-guest
  • Confirm the guest kernel banner appears on the host's controlling terminal.
  • Confirm the guest reaches a login prompt or installer menu.
  • From the guest, run uname -a and confirm a CheriBSD kernel.
  • From the guest, ping the host bridge address; confirm reachability.
  • Destroy the guest cleanly: bhyvectl --destroy --vm=cheri-guest.

3.4 Stability

  • Re-launch the guest a second time without rebooting the host.
  • After guest exit, host dmesg shows no vmm panics or capability faults.

Result: ☐ PASS ☐ FAIL ☐ BLOCKED

Notes:

4. Specific Features

These blocks exercise CHERI-specific functionality that distinguishes CheriBSD from stock FreeBSD. Each is independent; pick the ones relevant to the release under test based on the release notes (https://www.cheribsd.org/release-notes/25.03/index.html).

4.1 Process ABI sanity

Reference: https://ctsrd-cheri.github.io/cheribsd-getting-started/features/processes.html

cat > hello.c <<'EOF'
#include <stdio.h>
int main(void) { puts("hello, CHERI"); return 0; }
EOF
cc -o hello hello.c
file ./hello
./hello
  • file ./hello reports a CheriABI binary by default; the program prints hello, CHERI.

4.2 Capability violation is caught

  • Build and run a deliberately out-of-bounds test:
cat > oob.c <<'EOF'
#include <stdio.h>
#include <string.h>
int main(void) {
    char buf[16];
    char *p = buf;
    p[32] = 'x';   /* out of bounds */
    puts("should not get here");
    return 0;
}
EOF
cc -o oob oob.c
./oob || echo "trapped as expected: $?"
  • The program is killed with a capability-related signal; the should not get here line does not appear.
  • dmesg | tail shows a corresponding in-address-space capability fault diagnostic.

4.3 Heap temporal memory safety

Reference: https://ctsrd-cheri.github.io/cheribsd-getting-started/features/temporal.html

  • Confirm temporal safety is enabled for userspace by default (sysctl security.cheri.runtime_revocation_default returns 1 on 25.03).
  • Build and run a use-after-free test:
cat > uaf.c <<'EOF'
#include <stdio.h>
#include <stdlib.h>
int main(void) {
    int *p = malloc(sizeof *p);
    *p = 42;
    free(p);
    printf("%d\n", *p);   /* use-after-free */
    return 0;
}
EOF
cc -o uaf uaf.c
./uaf || echo "trapped as expected: $?"
  • The program is killed by the revoker rather than printing 42.

4.4 Library-based compartmentalization (c18n)

Reference: https://ctsrd-cheri.github.io/cheribsd-getting-started/features/c18n.html

  • Confirm the c18n runtime is present: ls /libexec/ld-elf-c18n.so.1.
  • Enable c18n globally for the session: sysctl security.cheri.lib_based_c18n_default=1
  • Re-run a non-trivial workload (e.g. make buildworld-equivalent or simply re-launching the desktop session). Confirm it completes without spurious crashes.
  • procstat compartments <pid> lists compartments for a running process.
  • Restore the previous value when done.

4.5 Package system

Reference: https://ctsrd-cheri.github.io/cheribsd-getting-started/packages/index.html

  • pkg64 update succeeds.
  • pkg64 search nginx returns at least one hit.
  • pkg64 install -y curl installs and curl --version runs.

4.6 ZFS (lightly tested per release notes)

Only run this block if the host was installed with ZFS in §1.

  • zpool status reports ONLINE with no errors.
  • zfs list shows the boot datasets.
  • Create, snapshot, and destroy a test dataset:
zfs create zroot/cheri-test
touch /zroot/cheri-test/x
zfs snapshot zroot/cheri-test@s1
zfs destroy -r zroot/cheri-test
  • All operations complete without error.

4.7 Clean shutdown

  • From a serial session, shutdown -p now powers the board off (or hangs at the syncer message due to the known firmware bug — if so, recover with reboot on the MCC console and record).

Result: ☐ PASS ☐ FAIL ☐ BLOCKED

Notes:

5. Summary

Block Result Notes
0. Prerequisites
1.1 Image-Only installation
1.2 Full installation
2. Desktop
3. Virtualization
4.1 Process ABI
4.2 Capability fault
4.3 Temporal safety
4.4 c18n
4.5 Packages
4.6 ZFS
4.7 Shutdown

Overall result: ☐ PASS ☐ FAIL ☐ BLOCKED

File issues against the CheriBSD GitHub repository: https://github.com/CTSRD-CHERI/cheribsd/issues. For test-plan or documentation issues, use: https://github.com/CTSRD-CHERI/cheribsd-getting-started/issues.

Clone this wiki locally