Revision as of 09:35, 22 November 2025

HF-HV04 Virtual Machine User Guide

Server: HF-HV04 (148.113.50.80)
Last Updated: 2025-11-22

This guide explains how to access the virtualization server and create virtual machines.

1. Connecting to XRDP via SSH Tunnel

For security reasons, the XRDP remote desktop service (port 3389) is not directly accessible from the internet. You must create an SSH tunnel to access it.

From Linux/macOS

Step 1: Create SSH Tunnel

Open a terminal and run:

ssh -L 3389:localhost:3389 your-username@148.113.50.8

Replace your-username with your actual username (e.g., kolja, satyakam, ...).

What this does:

-L 3389:localhost:3389 forwards your local port 3389 to the server's port 3389
Leave this terminal window open while using remote desktop

Step 2: Connect with RDP Client

Open your RDP client (Remmina, rdesktop, xfreerdp, etc.) and connect to:

localhost:3389

Example with xfreerdp:

xfreerdp /v:localhost:3389 /u:your-username

Example with rdesktop:

rdesktop localhost:3389 -u your-username

From Windows

Step 1: Create SSH Tunnel

Option A: Using PuTTY

Open PuTTY
In "Session" category:
- Host Name: 148.113.50.80
- Port: 22
In "Connection → SSH → Tunnels" category:
- Source port: 3389
- Destination: localhost:3389
- Click "Add"
Return to "Session" category and click "Open"
Login with your username and password
Leave PuTTY window open

Option B: Using OpenSSH (Windows 10/11)

Open PowerShell or Command Prompt and run:

ssh -L 3389:localhost:3389 your-username@IPADDRESS

Leave this window open while using remote desktop.

Step 2: Connect with Remote Desktop

Open "Remote Desktop Connection" (mstsc.exe)
Computer: localhost:3389
Username: your username
Click "Connect"

Important Notes:

Keep the SSH connection open during your entire remote desktop session
If you close the SSH terminal, the RDP connection will fail
You can minimize the SSH window, but don't close it

2. Creating Virtual Machines with virt-manager

Prerequisites

Connected to HF-HV04 via XRDP (see section 1)
virt-manager is available in the remote desktop session

Storage Location for Virtual Machines

Storage Pool: user-vm
Location: Dedicated storage pool on separate hard drive
Format: qcow2 (thin-provisioned)

All user VMs must store their virtual hard drives in the user-vm storage pool.

Creating a VM

Step 1: Launch virt-manager

From the terminal in your XRDP session:

virt-manager

Step 2: Connect to localhost

virt-manager should automatically connect to QEMU/KVM User Session.

Step 3: Create New Virtual Machine

Click "Create a new virtual machine" button (top-left)
Choose installation method:
- Local install media (ISO): For ISO files
- Network install (HTTP/FTP/NFS): For network installation
- Import existing disk image: For pre-built VM images

Step 4: Select Installation Media

For ISO: Browse to your ISO file location
- Storage pool: user-vm
- Or browse local filesystem
Choose OS type and version (helps optimize VM settings)

Step 5: Configure Memory and CPU

Memory (RAM): Allocate in MB (e.g., 2048 = 2GB)
CPUs: Number of virtual CPUs to allocate

Step 6: Configure Storage

Important: Storage Location

Check "Enable storage for this virtual machine"
Click "Manage..." to choose location
Select storage pool: user-vm
Click "+" to create new volume
Name your disk (e.g., myvm.qcow2)
Choose disk size (GB)
Format: qcow2 (recommended - thin provisioned)

Step 7: Configure Network (CRITICAL)

Network Selection:

Virtual network: pfsense-lan
Network source: Select pfsense-lan from dropdown

MAC Address Assignment (for Static IP):

To get a predictable IP address via DHCP reservation, assign one of the reserved MAC addresses:

In VM configuration, go to "NIC" section
Click "MAC address" field
Enter one of the reserved MAC addresses (see table below)

Reserved MAC Addresses:

MAC Address	Assigned IP	Status
52:54:00:00:00:90	10.7.1.90	Available
52:54:00:00:00:91	10.7.1.91	Available
52:54:00:00:00:92	10.7.1.92	Available
52:54:00:00:00:93	10.7.1.93	Available
52:54:00:00:00:94	10.7.1.94	Available
52:54:00:00:00:95	10.7.1.95	Available
52:54:00:00:00:96	10.7.1.96	Available
52:54:00:00:00:97	10.7.1.97	Available
52:54:00:00:00:98	10.7.1.98	Available
52:54:00:00:00:99	10.7.1.99	Available

How it works:

pfSense DHCP server has static mappings for these MAC addresses
When your VM boots with one of these MACs, it will ALWAYS receive the corresponding IP
This makes your VM's IP address predictable and stable
Choose any available MAC/IP from the table above

Important Network Rules:

User VMs MUST use the pfsense-lan virtual network
User VMs CANNOT use bridged networking (br0) - this is blocked by security policy
All internet access goes through the pfSense firewall (10.7.1.1)
VMs will receive IP addresses in the 10.7.1.x range from pfSense DHCP

Step 8: Finalize

Name your VM
Check "Customize configuration before install" if you want to adjust settings
Click "Finish"

Deleting a VM

Step 1: Shutdown the VM

Right-click the VM in virt-manager
Select "Shut Down → Shutdown" (graceful shutdown)
Or "Shut Down → Force Off" if not responding

Step 2: Delete the VM

Right-click the VM
Select "Delete"
Choose options:
- ☑ "Delete associated storage files" (removes virtual hard drive from user-vm pool)
- Click "Delete"

Manual Storage Cleanup (if needed):

If storage wasn't deleted automatically:

List volumes in user-vm pool

virsh vol-list user-vm

Delete specific volume

virsh vol-delete --pool user-vm myvm.qcow2

3. Creating Virtual Machines with Vagrant

Vagrant automates VM creation and management using configuration files.

Prerequisites

Install Vagrant and Plugins:

Install vagrant

sudo apt install vagrant

Install libvirt provider

vagrant plugin install vagrant-libvirt

Install mutate plugin (for box conversion)

vagrant plugin install vagrant-mutate

Storage Location for Vagrant VMs

Vagrant stores VM disk images in the user-vm storage pool when configured properly.

Creating a VM with Vagrant

Step 1: Create Project Directory

mkdir -p ~/vagrant-projects/myvm cd ~/vagrant-projects/myvm

Step 2: Create Vagrantfile

Create a file named Vagrantfile:

<syntaxhighlight lang="ruby"> Vagrant.configure("2") do |config|

 # Choose base box (example: Ubuntu 22.04)
 config.vm.box = "generic/ubuntu2204"

 # VM hostname
 config.vm.hostname = "myvm"

 # Network configuration
 config.vm.network "private_network",
   :type => "dhcp",
   :libvirt__network_name => "pfsense-lan"

 # Provider-specific settings
 config.vm.provider :libvirt do |libvirt|
   # Memory in MB
   libvirt.memory = 2048

   # Number of CPUs
   libvirt.cpus = 2

   # Disk size (optional - expands base image)
   libvirt.machine_virtual_size = 20  # GB

   # Storage pool
   libvirt.storage_pool_name = "user-vm"
 end

end

Network Configuration Explained:

<syntaxhighlight lang="ruby"> config.vm.network "private_network",

 :type => "dhcp",
 :libvirt__network_name => "pfsense-lan"

:type => "dhcp": VM gets IP automatically from pfSense (10.7.1.x range)
:libvirt__network_name => "pfsense-lan": Connects to the pfsense-lan virtual network
Important: Do NOT use "public_network" - bridged networking is blocked for user VMs

Step 3: Start the VM

vagrant up

What happens:

Downloads the base box (first time only)
Creates VM with specified settings
Creates disk in user-vm storage pool
Connects to pfsense-lan network
Starts the VM
Provisions if configured

Step 4: Access the VM

SSH into VM: vagrant ssh

Check VM status: vagrant status

Managing Vagrant VMs

Stop VM (keeps disk): vagrant halt

Suspend VM (saves RAM state): vagrant suspend

Resume suspended VM: vagrant resume

Restart VM: vagrant reload

Restart and re-provision: vagrant reload --provision

Show SSH config: vagrant ssh-config

Deleting a Vagrant VM

Step 1: Destroy the VM

From the project directory:

vagrant destroy

Confirm with y when prompted.

What this does:

Stops the VM
Deletes the VM definition
Deletes the virtual hard drive from user-vm storage pool

Step 2: Remove Project Directory (optional)

cd .. rm -rf ~/vagrant-projects/myvm

Remove Downloaded Box (optional):

If you want to free space and won't use this box again:

List downloaded boxes

vagrant box list

Remove specific box

vagrant box remove generic/ubuntu2204

Using Reserved MAC Addresses with Vagrant

To assign a reserved MAC address for predictable IP, add to your Vagrantfile:

<syntaxhighlight lang="ruby"> Vagrant.configure("2") do |config|

 config.vm.box = "generic/ubuntu2204"
 config.vm.hostname = "myvm"

 config.vm.network "private_network",
   :type => "dhcp",
   :libvirt__network_name => "pfsense-lan",
   :mac => "52:54:00:00:00:95"  # Will get IP 10.7.1.95

 config.vm.provider :libvirt do |libvirt|
   libvirt.memory = 2048
   libvirt.cpus = 2
   libvirt.storage_pool_name = "user-vm"
 end

end

Your VM will now always receive IP: 10.7.1.95

Advanced Vagrant Network Configuration

Static IP Address (Alternative Method):

<syntaxhighlight lang="ruby"> config.vm.network "private_network",

 :ip => "10.7.1.100",
 :libvirt__network_name => "pfsense-lan"

Important: Choose IP outside pfSense DHCP range to avoid conflicts. Recommended: Use reserved MAC addresses instead.

Port Forwarding:

Forward host port 8080 to VM port 80

config.vm.network "forwarded_port",

 guest: 80,
 host: 8080

Example Vagrantfile: Web Server with Reserved IP

<syntaxhighlight lang="ruby"> Vagrant.configure("2") do |config|

 config.vm.box = "generic/ubuntu2204"
 config.vm.hostname = "webserver"

 # Network with reserved MAC for static IP
 config.vm.network "private_network",
   :type => "dhcp",
   :libvirt__network_name => "pfsense-lan",
   :mac => "52:54:00:00:00:90"  # Gets IP 10.7.1.90

 # Provider settings
 config.vm.provider :libvirt do |libvirt|
   libvirt.memory = 1024
   libvirt.cpus = 1
   libvirt.storage_pool_name = "user-vm"
 end

 # Provision with shell script
 config.vm.provision "shell", inline: <<-SHELL
   apt-get update
   apt-get install -y nginx
   systemctl enable nginx
   systemctl start nginx
 SHELL

end

Result: Web server VM with predictable IP 10.7.1.90

Network Configuration Summary

User VM Network Requirements

Allowed:

✅ Virtual network: pfsense-lan
✅ DHCP from pfSense (10.7.1.x range)
✅ Reserved MAC addresses for static DHCP (10.7.1.90-99)
✅ Static IP in 10.7.1.x range (outside DHCP pool)

Blocked:

❌ Bridged networking (br0)
❌ Direct internet access
❌ Other virtual networks

How It Works

Your VM (10.7.1.x)
      ↓
pfsense-lan network (virbr-pfsense)
      ↓
pfSense LAN (10.7.1.1)
      ↓
pfSense WAN (148.113.26.212)
      ↓
Internet (OVH)

All user VMs:

Connect to pfsense-lan libvirt network
Route through pfSense firewall for internet access
Managed and filtered by pfSense (NAT, firewall rules, VPN, etc.)

Reserved MAC Addresses for Static IPs

How DHCP Reservations Work:

pfSense DHCP server has 10 static mappings configured
Each MAC address is mapped to a specific IP address
When a VM with a reserved MAC requests DHCP, pfSense always assigns the same IP
This provides stable, predictable IP addresses without manual IP configuration

Available Reservations:

MAC Address	Assigned IP	How to Use
52:54:00:00:00:90	10.7.1.90	Assign this MAC to your VM NIC
52:54:00:00:00:91	10.7.1.91	Assign this MAC to your VM NIC
52:54:00:00:00:92	10.7.1.92	Assign this MAC to your VM NIC
52:54:00:00:00:93	10.7.1.93	Assign this MAC to your VM NIC
52:54:00:00:00:94	10.7.1.94	Assign this MAC to your VM NIC
52:54:00:00:00:95	10.7.1.95	Assign this MAC to your VM NIC
52:54:00:00:00:96	10.7.1.96	Assign this MAC to your VM NIC
52:54:00:00:00:97	10.7.1.97	Assign this MAC to your VM NIC
52:54:00:00:00:98	10.7.1.98	Assign this MAC to your VM NIC
52:54:00:00:00:99	10.7.1.99	Assign this MAC to your VM NIC

Predicting Your VM's IP Address:

When creating VM: Assign one of the reserved MAC addresses to your VM's network interface
Boot the VM: The VM will request DHCP from pfSense
pfSense checks: Recognizes the MAC address in its reservation table
IP assigned: Always assigns the corresponding IP address
Result: Your VM will have the same IP every time it boots

Benefits:

No need to configure static IPs inside the VM
IP survives VM rebuilds (as long as you use the same MAC)
Easy to remember and document (e.g., "my-webserver is always 10.7.1.90")
Simplifies firewall rules and port forwarding in pfSense

Coordination:

Keep track of which MAC/IP you're using for each VM
Don't assign the same MAC to multiple VMs
Document your assignments to avoid conflicts

Storage Pool Information

user-vm Storage Pool

Name: user-vm
Type: Directory-based storage pool
Location: Dedicated hard drive (separate from system disk)
Format: qcow2 (thin-provisioned)
Purpose: Store all user virtual machine disk images

Usage in virt-manager:

Appears in storage pool dropdown when creating/managing VMs
Select user-vm pool when creating new virtual disk

Usage in Vagrant:

Configure in Vagrantfile: libvirt.storage_pool_name = "user-vm"
All Vagrant VM disks will be created in this pool

Verify Storage Pool:

List all storage pools

virsh pool-list --all

Show pool details

virsh pool-info user-vm

List volumes in pool

virsh vol-list user-vm

Troubleshooting

SSH Tunnel Issues

Problem: RDP connection fails with "Connection refused"

Solution:

Check SSH tunnel is still running
Verify port forwarding: ssh -L 3389:localhost:3389 -v your-username@HF-HV04
Check XRDP service: systemctl status xrdp (on server)

VM Network Issues

Problem: VM has no internet access

Check:

Inside VM - check IP address

ip addr show

Check gateway

ip route show default

Ping pfSense gateway

ping 10.7.1.1

Ping external IP

ping 8.8.8.8

Common causes:

VM not connected to pfsense-lan network
pfSense firewall rules blocking traffic
DNS not configured in VM

Problem: VM has wrong IP address

Solution:

Verify MAC address matches reserved table
Check pfSense DHCP reservations (Services → DHCP Server)
Release and renew DHCP: sudo dhclient -r && sudo dhclient

Vagrant Issues

Problem: "No usable default provider"

Solution:

Install libvirt provider

vagrant plugin install vagrant-libvirt

Problem: "Call to virStorageVolCreateXML failed"

Solution:

Storage pool user-vm might not be active
Check: virsh pool-list --all
Start pool: virsh pool-start user-vm
Disk space full: df -h

Problem: Wrong network in Vagrant

Solution:

Verify Vagrantfile has: :libvirt__network_name => "pfsense-lan"
NOT "default" or other network names

Storage Pool Issues

Problem: user-vm pool not visible

Solution:

Check if pool exists

virsh pool-list --all

Start the pool

virsh pool-start user-vm

Set to autostart

virsh pool-autostart user-vm

Quick Reference

SSH Tunnel (Quick Start)

Linux/macOS: ssh -L 3389:localhost:3389 username@HF-HV04

Then connect RDP to: localhost:3389

Windows (PowerShell): <syntaxhighlight lang="powershell"> ssh -L 3389:localhost:3389 username@HF-HV04

Then use Remote Desktop to: localhost:3389

Vagrant Quick Start with Reserved IP

mkdir ~/vagrant-projects/test-vm && cd ~/vagrant-projects/test-vm

cat > Vagrantfile <<'EOF' Vagrant.configure("2") do |config|

 config.vm.box = "generic/ubuntu2204"
 config.vm.network "private_network",
   :type => "dhcp",
   :libvirt__network_name => "pfsense-lan",
   :mac => "52:54:00:00:00:99"  # Gets IP 10.7.1.99
 config.vm.provider :libvirt do |lv|
   lv.memory = 1024
   lv.cpus = 1
   lv.storage_pool_name = "user-vm"
 end

end
EOF

vagrant up vagrant ssh

Your VM will have IP: 10.7.1.99

virt-manager Quick Network Setup

Virtual network: pfsense-lan
NIC MAC address: 52:54:00:00:00:XX (choose from table)
Storage pool: user-vm

Support

For issues or questions:

Check logs: journalctl -u xrdp -f (XRDP)
Check logs: journalctl -u libvirtd -f (libvirt)
Check VM console in virt-manager for boot issues
Verify network: virsh net-list --all
Verify storage: virsh pool-list --all

Reserved IP Address Assignment Table

Use this table to track which VMs are using which reserved IPs:

MAC Address	IP Address	VM Name	Owner	Purpose	Notes
52:54:00:00:00:90	10.7.1.90
52:54:00:00:00:91	10.7.1.91
52:54:00:00:00:92	10.7.1.92
52:54:00:00:00:93	10.7.1.93
52:54:00:00:00:94	10.7.1.94
52:54:00:00:00:95	10.7.1.95
52:54:00:00:00:96	10.7.1.96
52:54:00:00:00:97	10.7.1.97
52:54:00:00:00:98	10.7.1.98
52:54:00:00:00:99	10.7.1.99