vms-7bd: virtio-net NIC on the OVMX QEMU runtime (user-mode default, opt-in tap/bridge)

.github/workflows/ci.yml

@@ -105,6 +105,7 @@ jobs:
               - 'tests/qemu/test_release_e2e.sh'
               - 'tests/qemu/test_executive_integral.sh'
               - 'tests/qemu/test_distrib_boot.sh'
+              - 'tests/qemu/test_virtio_nic.sh'
               - 'tests/qemu/test_startup_phase_driver.sh'
               - 'tests/qemu/test_boot_conformance.sh'
               - 'tests/qemu/test_boot_scsnode_hostname_e2e.sh'
@@ -532,6 +533,26 @@ jobs:
             ovmx-boot:latest \
             /test.sh
 
+      # vms-7bd (parent vms-67f, TCP/IP Services). Reuses the image built above
+      # (no extra build). Proves the QEMU runtime gets a virtio-net NIC: the
+      # launcher's arg construction (user-mode SLIRP default, opt-in tap/bridge,
+      # no inbound by default, -nodefaults kept) AND a real boot where the guest
+      # kernel enumerates the virtio-net Ethernet controller with the DEFAULT
+      # user-mode NIC, the PXE ROM is suppressed, and the executive still
+      # attaches (adding the NIC did not regress boot). run-qemu.sh +
+      # Dockerfile.bootable are bind-mounted at /src so the arg-construction
+      # checks run here too, not just the boot check. This is the LINUX-LAYER
+      # NIC only; the VMS device face (EWAn:) is downstream (vms-3be/vms-9d2).
+      - name: virtio-net NIC present on the QEMU runtime (vms-7bd)
+        run: |
+          docker run --rm \
+            -v ${{ github.workspace }}/tests/qemu/test_virtio_nic.sh:/test.sh:ro \
+            -v ${{ github.workspace }}/distro/boot/run-qemu.sh:/src/distro/boot/run-qemu.sh:ro \
+            -v ${{ github.workspace }}/distro/Dockerfile.bootable:/src/distro/Dockerfile.bootable:ro \
+            --entrypoint bash \
+            ovmx-boot:latest \
+            /test.sh
+
   # -----------------------------------------------------------------------
   # cut-release-reproducible (vms-d73, epic vms-a84 RELEASE ENGINEERING)
   #

distro/Dockerfile.bootable

@@ -48,7 +48,7 @@
 # link-native-cmake-x86_64 job uses; OVMX_LINK_NATIVE auto-detects ON only
 # when `$CC -dumpmachine` reports an aarch64/x86_64 *-musl triple, which
 # Ubuntu's musl-gcc wrapper does not.
 FROM --platform=linux/amd64 alpine:3.20 AS link-native
 
 RUN apk add --no-cache cmake gcc g++ musl-dev binutils make linux-headers
 
@@ -734,11 +734,35 @@
 #                         (docs/design-boot-faithful.md §2.2/§3.1). Unset boots
 #                         straight through.
 # SYSDISK_NAME          — disk filename inside /data volume (default: sysdisk.img)
+# OVMX_NET_MODE         — virtio-net NIC mode (vms-7bd, parent vms-67f). The
+#                         guest gets ONE virtio-net-pci device; the guest kernel
+#                         has virtio_net built in (CONFIG_VIRTIO_NET=y) so the
+#                         interface enumerates with no in-guest module load.
+#                         This is the LINUX-LAYER NIC only -- the VMS device
+#                         face (EWAn:) is a separate downstream item.
+#                           user  (DEFAULT) : user-mode NAT (SLIRP), zero host
+#                                             config, works unprivileged / in
+#                                             CI. NO inbound by default.
+#                           tap             : PRE-EXISTING host tap OVMX_NET_TAP
+#                                             (default tap0), script=no; the
+#                                             operator provisions/bridges it.
+#                           bridge          : qemu-bridge-helper to EXISTING
+#                                             host bridge OVMX_NET_BRIDGE
+#                                             (default br0), operator-provisioned.
+#                           none            : no NIC (legacy -nic none behavior).
+#                         tap/bridge need host privileges and will NOT work in
+#                         unprivileged CI; user mode is the safe default. This
+#                         launch never creates a tap/bridge as a side effect.
+# OVMX_NET_TAP          — tap ifname for OVMX_NET_MODE=tap    (default: tap0)
+# OVMX_NET_BRIDGE       — bridge name for OVMX_NET_MODE=bridge (default: br0)
+# OVMX_NET_MAC          — guest NIC MAC (default: QEMU-assigned)
+# OVMX_NET_HOSTFWD      — user-mode ONLY: extra hostfwd rules for deliberate
+#                         inbound (e.g. "tcp::2223-:23"). Empty by default.
 #
 # boot.sh mounts a host directory at /data so the container owns the disk
 # file and can write freely (avoids rootless Docker permission issues).
 # When run standalone (no /data mount), falls back to /tmp/sysdisk.img.
 CMD ARCH=$(uname -m) && \
     if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then \
         QEMU=qemu-system-aarch64; \
         MACHINE="-machine virt -cpu cortex-a57"; \
@@ -763,14 +787,28 @@
     fi && \
     APPEND="$CONSOLE loglevel=3 quiet" && \
     if [ -n "${BOOT_FLAGS:-}" ]; then APPEND="$APPEND ovmx.flags=$BOOT_FLAGS"; fi && \
+    NET_MODE="${OVMX_NET_MODE:-user}" && \
+    DEV_OPTS="netdev=net0,romfile=" && \
+    if [ -n "${OVMX_NET_MAC:-}" ]; then DEV_OPTS="$DEV_OPTS,mac=$OVMX_NET_MAC"; fi && \
+    case "$NET_MODE" in \
+        user) NETDEV="user,id=net0"; \
+              if [ -n "${OVMX_NET_HOSTFWD:-}" ]; then NETDEV="$NETDEV,hostfwd=$OVMX_NET_HOSTFWD"; fi; \
+              set -- -netdev "$NETDEV" -device "virtio-net-pci,$DEV_OPTS" ;; \
+        tap) set -- -netdev "tap,id=net0,ifname=${OVMX_NET_TAP:-tap0},script=no,downscript=no" \
+                    -device "virtio-net-pci,$DEV_OPTS" ;; \
+        bridge) set -- -netdev "bridge,id=net0,br=${OVMX_NET_BRIDGE:-br0}" \
+                       -device "virtio-net-pci,$DEV_OPTS" ;; \
+        none) set -- -nic none ;; \
+        *) echo "Error: unknown OVMX_NET_MODE='$NET_MODE' (want: user|tap|bridge|none)" >&2; exit 1 ;; \
+    esac && \
     exec $QEMU $MACHINE \
         -kernel /boot/vmlinuz \
         -initrd "$INITRAMFS" \
         -nographic \
         -append "$APPEND" \
         -m $MEMORY \
         -smp 2 \
-        -nic none \
+        "$@" \
         -nodefaults \
         -serial mon:stdio \
         -drive file="$DISK",format=raw,if=virtio \

distro/boot/run-qemu.sh

@@ -15,6 +15,43 @@
 #                (docs/design-boot-faithful.md §2.2/§3.1). Unset (the
 #                default) boots straight through -- SYSBOOT> never appears.
 #
+# Networking (vms-7bd, parent vms-67f TCP/IP Services). The guest gets ONE
+# virtio-net NIC. The guest kernel (ubuntu generic) has virtio_net built in
+# (CONFIG_VIRTIO_NET=y), so the interface enumerates with no in-guest module
+# load; this is the LINUX-LAYER NIC only -- the VMS device face (EWAn:) is a
+# separate downstream item. The PXE option ROM is disabled (romfile=) so the
+# guest never pauses to attempt a network boot.
+#   OVMX_NET_MODE  - user  (DEFAULT) : user-mode NAT (SLIRP). Zero host config,
+#                                      works unprivileged / in CI. NO inbound
+#                                      by default (no hostfwd) -- outbound NAT
+#                                      to the host/gateway only.
+#                    tap             : attach to a PRE-EXISTING host tap device
+#                                      (OVMX_NET_TAP, default tap0). script=no,
+#                                      so QEMU never runs a host up/down script.
+#                                      The operator creates and bridges the tap;
+#                                      this launcher never touches host networking.
+#                    bridge          : attach via qemu-bridge-helper to an
+#                                      EXISTING host bridge (OVMX_NET_BRIDGE,
+#                                      default br0). Needs a setuid bridge helper
+#                                      + an allow entry in the host's
+#                                      /etc/qemu/bridge.conf; operator-provisioned.
+#                    none            : no NIC at all (legacy -nic none behavior).
+#   OVMX_NET_TAP   - tap ifname for OVMX_NET_MODE=tap    (default: tap0)
+#   OVMX_NET_BRIDGE- bridge name for OVMX_NET_MODE=bridge (default: br0)
+#   OVMX_NET_MAC   - guest NIC MAC (default: QEMU-assigned 52:54:00:xx:xx:xx)
+#   OVMX_NET_HOSTFWD - user-mode ONLY: extra -netdev hostfwd rules for
+#                      deliberate inbound (e.g. "tcp::2223-:23"). Empty by
+#                      default -- opt-in, never inbound-by-default.
+#
+#   tap and bridge need host privileges / operator-provisioned host state and
+#   will NOT work in unprivileged CI; user mode is the safe default. This
+#   launcher never creates a tap or a bridge as a side effect.
+#
+# Testing hook:
+#   OVMX_QEMU_DRYRUN=1 - print the fully-assembled QEMU argv (one token per
+#                        line) and exit 0 instead of exec'ing QEMU. Lets a test
+#                        assert the launch args deterministically without a boot.
+#
 # Initramfs variants:
 #   initramfs-ovmx.cpio.gz       — fat: all binaries (first boot / install)
 #   initramfs-ovmx-slim.cpio.gz  — slim: bootstrap only (needs system disk)
@@ -60,15 +97,58 @@ if [ -n "$BOOT_FLAGS" ]; then
     APPEND="$APPEND ovmx.flags=$BOOT_FLAGS"
 fi
 
-exec $QEMU $MACHINE \
+# --- virtio-net NIC (vms-7bd) ------------------------------------------------
+# Build the -netdev/-device pair for the chosen mode. We keep -nodefaults, so
+# nothing but this device is attached. romfile= disables the PXE option ROM so
+# the guest does not pause to attempt a network boot.
+NET_MODE="${OVMX_NET_MODE:-user}"
+NET_MAC="${OVMX_NET_MAC:-}"
+NET_ARGS=()
+DEV_OPTS="netdev=net0,romfile="
+if [ -n "$NET_MAC" ]; then
+    DEV_OPTS="$DEV_OPTS,mac=$NET_MAC"
+fi
+case "$NET_MODE" in
+    user)
+        NETDEV="user,id=net0"
+        if [ -n "${OVMX_NET_HOSTFWD:-}" ]; then
+            NETDEV="$NETDEV,hostfwd=${OVMX_NET_HOSTFWD}"
+        fi
+        NET_ARGS=(-netdev "$NETDEV" -device "virtio-net-pci,$DEV_OPTS")
+        ;;
+    tap)
+        NET_ARGS=(-netdev "tap,id=net0,ifname=${OVMX_NET_TAP:-tap0},script=no,downscript=no" \
+                  -device "virtio-net-pci,$DEV_OPTS")
+        ;;
+    bridge)
+        NET_ARGS=(-netdev "bridge,id=net0,br=${OVMX_NET_BRIDGE:-br0}" \
+                  -device "virtio-net-pci,$DEV_OPTS")
+        ;;
+    none)
+        NET_ARGS=(-nic none)
+        ;;
+    *)
+        echo "Error: unknown OVMX_NET_MODE='$NET_MODE' (want: user|tap|bridge|none)" >&2
+        exit 1
+        ;;
+esac
+
+QEMU_CMD=("$QEMU" $MACHINE \
     -kernel "$KERNEL" \
     -initrd "$INITRD" \
     -nographic \
     -append "$APPEND" \
     -m "$MEMORY" \
     -smp 2 \
-    -nic none \
+    "${NET_ARGS[@]}" \
     -nodefaults \
     -serial mon:stdio \
     -no-reboot \
-    $DISK_ARGS
+    $DISK_ARGS)
+
+if [ -n "${OVMX_QEMU_DRYRUN:-}" ]; then
+    printf '%s\n' "${QEMU_CMD[@]}"
+    exit 0
+fi
+
+exec "${QEMU_CMD[@]}"