harmony/docs/pxe_test

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.

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:

   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:

     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:

   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:

   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:

   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.

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:

sudo ./pxe_vm_lab_setup.sh clean