diff --git a/docs/pxe_test/README.md b/docs/pxe_test/README.md new file mode 100644 index 0000000..c515aab --- /dev/null +++ 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 `` block corresponding to the `.img` file (the one with ``). + +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 +``` diff --git a/docs/pxe_test_setup.sh b/docs/pxe_test/pxe_vm_lab_setup.sh similarity index 79% rename from docs/pxe_test_setup.sh rename to docs/pxe_test/pxe_vm_lab_setup.sh index 67c66c6..f53cea3 100755 --- a/docs/pxe_test_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" < ${NET_HARMONYLAN} - - - 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." ;;