doc: PXE test setup script and README file to explain what it does and how to use it

2025-08-20 13:14:00 -04:00 · 2025-08-20 13:14:00 -04:00 · 597dcbc848
commit 597dcbc848
parent a53e8552e9
2 changed files with 126 additions and 22 deletions
--- a/docs/pxe_test/README.md
+++ b/docs/pxe_test/README.md
@ -0,0 +1,108 @@
+# OPNsense PXE Lab Environment
+
+This project contains a script to automatically set up a virtual lab environment for testing PXE boot services managed by an OPNsense firewall.
+
+## Overview
+
+The `pxe_vm_lab_setup.sh` script will create the following resources using libvirt/KVM:
+
+1.  **A Virtual Network**: An isolated network named `harmonylan` (`virbr1`) for the lab.
+2.  **Two Virtual Machines**:
+    *   `opnsense-pxe`: A firewall VM that will act as the gateway and PXE server.
+    *   `pxe-node-1`: A client VM configured to boot from the network.
+
+## Prerequisites
+
+Ensure you have the following software installed on your Arch Linux host:
+
+*   `libvirt`
+*   `qemu`
+*   `virt-install` (from the `virt-install` package)
+*   `curl`
+*   `bzip2`
+
+## Usage
+
+### 1. Create the Environment
+
+Run the `up` command to download the necessary images and create the network and VMs.
+
+```bash
+sudo ./pxe_vm_lab_setup.sh up
+```
+
+### 2. Install and Configure OPNsense
+
+The OPNsense VM is created but the OS needs to be installed manually via the console.
+
+1.  **Connect to the VM console**:
+    ```bash
+    sudo virsh console opnsense-pxe
+    ```
+
+2.  **Log in as the installer**:
+    *   Username: `installer`
+    *   Password: `opnsense`
+
+3.  **Follow the on-screen installation wizard**. When prompted to assign network interfaces (`WAN` and `LAN`):
+    *   Find the MAC address for the `harmonylan` interface by running this command in another terminal:
+        ```bash
+        virsh domiflist opnsense-pxe
+        # Example output:
+        # Interface   Type      Source       Model    MAC
+        # ---------------------------------------------------------
+        # vnet18      network   default      virtio   52:54:00:b5:c4:6d
+        # vnet19      network   harmonylan   virtio   52:54:00:21:f9:ba
+        ```
+    *   Assign the interface connected to `harmonylan` (e.g., `vtnet1` with MAC `52:54:00:21:f9:ba`) as your **LAN**.
+    *   Assign the other interface as your **WAN**.
+
+4.  After the installation is complete, **shut down** the VM from the console menu.
+
+5.  **Detach the installation media** by editing the VM's configuration:
+    ```bash
+    sudo virsh edit opnsense-pxe
+    ```
+    Find and **delete** the entire `<disk>` block corresponding to the `.img` file (the one with `<target ... bus='usb'/>`).
+
+6.  **Start the VM** to boot into the newly installed system:
+    ```bash
+    sudo virsh start opnsense-pxe
+    ```
+
+### 3. Connect to OPNsense from Your Host
+
+To configure OPNsense, you need to connect your host to the `harmonylan` network.
+
+1.  By default, OPNsense configures its LAN interface with the IP `192.168.1.1`.
+2.  Assign a compatible IP address to your host's `virbr1` bridge interface:
+    ```bash
+    sudo ip addr add 192.168.1.5/24 dev virbr1
+    ```
+3.  You can now access the OPNsense VM from your host:
+    *   **SSH**: `ssh root@192.168.1.1` (password: `opnsense`)
+    *   **Web UI**: `https://192.168.1.1`
+
+### 4. Configure PXE Services with Harmony
+
+With connectivity established, you can now use Harmony to configure the OPNsense firewall for PXE booting. Point your Harmony OPNsense scores to the firewall using these details:
+
+*   **Hostname/IP**: `192.168.1.1`
+*   **Credentials**: `root` / `opnsense`
+
+### 5. Boot the PXE Client
+
+Once your Harmony configuration has been applied and OPNsense is serving DHCP/TFTP, start the client VM. It will automatically attempt to boot from the network.
+
+```bash
+sudo virsh start pxe-node-1
+sudo virsh console pxe-node-1
+```
+
+## Cleanup
+
+To destroy all VMs and networks created by the script, run the `clean` command:
+
+```bash
+sudo ./pxe_vm_lab_setup.sh clean
+```
--- a/docs/pxe_test/pxe_vm_lab_setup.sh
+++ b/docs/pxe_test/pxe_vm_lab_setup.sh
@ -18,23 +18,20 @@ VLAN_MASK="255.255.255.0"
 RAM_OPN="2048"
 VCPUS_OPN="2"
 DISK_OPN_GB="10"
-OS_VARIANT_OPN="freebsd13.1" # Using a slightly more recent variant
+OS_VARIANT_OPN="freebsd14.0" # Updated to a more recent FreeBSD variant

 RAM_PXE="4096"
 VCPUS_PXE="2"
 DISK_PXE_GB="40"
 OS_VARIANT_LINUX="centos-stream9"

-# ISO URLs and Paths
-OPN_ISO="${IMG_DIR}/OPNsense-latest.iso"
-CENTOS_ISO="${IMG_DIR}/CentOS-Stream-9-latest-boot.iso"
-OPN_URL="https://mirror.wdc1.us.leaseweb.net/opnsense/releases/25.7/OPNsense-25.7-dvd-amd64.iso.bz2"
-CENTOS_URL="https://mirror.stream.centos.org/9-stream/BaseOS/x86_64/os/images/boot.iso"
+OPN_IMG_URL="https://mirror.ams1.nl.leaseweb.net/opnsense/releases/25.7/OPNsense-25.7-serial-amd64.img.bz2"
+OPN_IMG_PATH="${IMG_DIR}/OPNsense-25.7-serial-amd64.img"
+CENTOS_ISO_URL="https://mirror.stream.centos.org/9-stream/BaseOS/x86_64/os/images/boot.iso"
+CENTOS_ISO_PATH="${IMG_DIR}/CentOS-Stream-9-latest-boot.iso"

-# Libvirt connection URI for system-wide daemon
 CONNECT_URI="qemu:///system"

-# --- Helper Functions ---
 download_if_missing() {
  local url="$1"
  local dest="$2"
@ -110,10 +107,7 @@ EOF
  cat > "${STATE_DIR}/${NET_HARMONYLAN}.xml" <<EOF
 <network>
  <name>${NET_HARMONYLAN}</name>
-  <forward mode='nat'/>
  <bridge name='virbr1' stp='on' delay='0'/>
-  <ip address='${VLAN_GW}' netmask='${VLAN_MASK}'>
-  </ip>
 </network>
 EOF

@ -121,31 +115,33 @@ EOF
  ensure_network "default" "${STATE_DIR}/default.xml"
  ensure_network "${NET_HARMONYLAN}" "${STATE_DIR}/${NET_HARMONYLAN}.xml"

-  # --- Create OPNsense VM ---
+  # --- Create OPNsense VM (MODIFIED SECTION) ---
  local disk_opn="${IMG_DIR}/${VM_OPN}.qcow2"
  if [[ ! -f "$disk_opn" ]]; then
    qemu-img create -f qcow2 "$disk_opn" "${DISK_OPN_GB}G"
  fi

-  echo "Creating OPNsense VM..."
+  echo "Creating OPNsense VM using serial image..."
  virt-install \
    --connect "${CONNECT_URI}" \
    --name "${VM_OPN}" \
    --ram "${RAM_OPN}" \
    --vcpus "${VCPUS_OPN}" \
-    --cpu host-model-only \
+    --cpu host-passthrough \
    --os-variant "${OS_VARIANT_OPN}" \
    --graphics none \
    --noautoconsole \
-    --disk path="${disk_opn}",format=qcow2,bus=virtio \
-    --cdrom "${OPN_ISO}" \
+    --disk path="${disk_opn}",device=disk,bus=virtio,boot.order=1 \
+    --disk path="${OPN_IMG_PATH}",device=disk,bus=usb,readonly=on,boot.order=2 \
    --network network=default,model=virtio \
    --network network="${NET_HARMONYLAN}",model=virtio \
-    --boot uefi
+    --boot uefi,menu=on

  echo "OPNsense VM created. Connect with: sudo virsh console ${VM_OPN}"
-  echo "In OPNsense, assign WAN to the NIC with DHCP (default), and LAN to the ${NET_HARMONYLAN} NIC."
-  echo "Set LAN IP to ${VLAN_GW}/24 and enable DHCP on LAN (e.g., ${VLAN_GW%.*}.100 - ${VLAN_GW%.*}.200)."
+  echo "The VM will boot from the serial installation image."
+  echo "Login with user 'installer' and password 'opnsense' to start the installation."
+  echo "Install onto the VirtIO disk (vtbd0)."
+  echo "After installation, shutdown the VM, then run 'sudo virsh edit ${VM_OPN}' and remove the USB disk block to boot from the installed system."

  # --- Create PXE Client VM ---
  local disk_pxe="${IMG_DIR}/${VM_PXE}.qcow2"
@ -159,7 +155,7 @@ EOF
    --name "${VM_PXE}" \
    --ram "${RAM_PXE}" \
    --vcpus "${VCPUS_PXE}" \
-    --cpu host-model-only \
+    --cpu host-passthrough \
    --os-variant "${OS_VARIANT_LINUX}" \
    --graphics none \
    --noautoconsole \
@ -175,8 +171,8 @@ EOF
 case "${1:-}" in
  up)
    mkdir -p "${IMG_DIR}" "${STATE_DIR}"
-    download_if_missing "$OPN_URL" "$OPN_ISO"
-    download_if_missing "$CENTOS_URL" "$CENTOS_ISO"
+    download_if_missing "$OPN_IMG_URL" "$OPN_IMG_PATH"
+    download_if_missing "$CENTOS_ISO_URL" "$CENTOS_ISO_PATH"
    create_lab_environment
    echo "Lab setup complete. Use 'sudo virsh list --all' to see VMs."
    ;;