View source for Team Nordex:Nordex Virtual Machines on HV-04

= HF-HV04 Virtual Machine User Guide =

'''Server:''' HF-HV04 (148.113.50.80)<br/>
'''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 <code>your-username</code> with your actual username (e.g., kolja, satyakam, ...).

'''What this does:'''
* <code>-L 3389:localhost:3389</code> 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:

<pre>
localhost:3389
</pre>

'''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: <code>148.113.50.80</code>
#* Port: <code>22</code>
# In "Connection → SSH → Tunnels" category:
#* Source port: <code>3389</code>
#* Destination: <code>localhost:3389</code>
#* 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: <code>localhost:3389</code>
# 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:''' <code>user-vm</code><br/>
'''Location:''' Dedicated storage pool on separate hard drive<br/>
'''Format:''' qcow2 (thin-provisioned)

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

=== Creating a VM ===

'''Step 1: Launch virt-manager'''

From the terminal in your XRDP session:

<syntaxhighlight lang="bash">
virt-manager
</syntaxhighlight>

'''Step 2: Connect to localhost'''

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

'''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: <code>user-vm</code>
** 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:''' <code>user-vm</code>
# Click "+" to create new volume
# Name your disk (e.g., <code>myvm.qcow2</code>)
# Choose disk size (GB)
# Format: <code>qcow2</code> (recommended - thin provisioned)

'''Step 7: Configure Network (CRITICAL)'''

'''Network Selection:'''
* '''Virtual network:''' <code>pfsense-lan</code>
* '''Network source:''' Select <code>pfsense-lan</code> 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:'''

{| class="wikitable"
! 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 <code>pfsense-lan</code> 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 <code>user-vm</code> pool)
#* Click "Delete"

'''Manual Storage Cleanup (if needed):'''

If storage wasn't deleted automatically:

<syntaxhighlight lang="bash">
# List volumes in user-vm pool
virsh vol-list user-vm

# Delete specific volume
virsh vol-delete --pool user-vm myvm.qcow2
</syntaxhighlight>

== 3. Creating Virtual Machines with Vagrant ==

Vagrant automates VM creation and management using configuration files.

=== Prerequisites ===

'''Install Vagrant and Plugins:'''

<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

=== Storage Location for Vagrant VMs ===

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

=== Creating a VM with Vagrant ===

'''Step 1: Create Project Directory'''

<syntaxhighlight lang="bash">
mkdir -p ~/vagrant-projects/myvm
cd ~/vagrant-projects/myvm
</syntaxhighlight>

'''Step 2: Create Vagrantfile'''

Create a file named <code>Vagrantfile</code>:

<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
</syntaxhighlight>

'''Network Configuration Explained:'''

<syntaxhighlight lang="ruby">
config.vm.network "private_network",
  :type => "dhcp",
  :libvirt__network_name => "pfsense-lan"
</syntaxhighlight>

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

'''Step 3: Start the VM'''

<syntaxhighlight lang="bash">
vagrant up
</syntaxhighlight>

'''What happens:'''
# Downloads the base box (first time only)
# Creates VM with specified settings
# Creates disk in <code>user-vm</code> storage pool
# Connects to <code>pfsense-lan</code> network
# Starts the VM
# Provisions if configured

'''Step 4: Access the VM'''

'''SSH into VM:'''
<syntaxhighlight lang="bash">
vagrant ssh
</syntaxhighlight>

'''Check VM status:'''
<syntaxhighlight lang="bash">
vagrant status
</syntaxhighlight>

=== Managing Vagrant VMs ===

'''Stop VM (keeps disk):'''
<syntaxhighlight lang="bash">
vagrant halt
</syntaxhighlight>

'''Suspend VM (saves RAM state):'''
<syntaxhighlight lang="bash">
vagrant suspend
</syntaxhighlight>

'''Resume suspended VM:'''
<syntaxhighlight lang="bash">
vagrant resume
</syntaxhighlight>

'''Restart VM:'''
<syntaxhighlight lang="bash">
vagrant reload
</syntaxhighlight>

'''Restart and re-provision:'''
<syntaxhighlight lang="bash">
vagrant reload --provision
</syntaxhighlight>

'''Show SSH config:'''
<syntaxhighlight lang="bash">
vagrant ssh-config
</syntaxhighlight>

=== Deleting a Vagrant VM ===

'''Step 1: Destroy the VM'''

From the project directory:

<syntaxhighlight lang="bash">
vagrant destroy
</syntaxhighlight>

Confirm with <code>y</code> when prompted.

'''What this does:'''
* Stops the VM
* Deletes the VM definition
* Deletes the virtual hard drive from <code>user-vm</code> storage pool

'''Step 2: Remove Project Directory (optional)'''

<syntaxhighlight lang="bash">
cd ..
rm -rf ~/vagrant-projects/myvm
</syntaxhighlight>

'''Remove Downloaded Box (optional):'''

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

<syntaxhighlight lang="bash">
# List downloaded boxes
vagrant box list

# Remove specific box
vagrant box remove generic/ubuntu2204
</syntaxhighlight>

=== 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
</syntaxhighlight>

'''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"
</syntaxhighlight>

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

'''Port Forwarding:'''

<syntaxhighlight lang="ruby">
# Forward host port 8080 to VM port 80
config.vm.network "forwarded_port",
  guest: 80,
  host: 8080
</syntaxhighlight>

=== 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
</syntaxhighlight>

'''Result:''' Web server VM with predictable IP 10.7.1.90

== Network Configuration Summary ==

=== User VM Network Requirements ===

'''Allowed:'''
* ✅ Virtual network: <code>pfsense-lan</code>
* ✅ 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 ===

<pre>
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)
</pre>

'''All user VMs:'''
* Connect to <code>pfsense-lan</code> 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:'''

{| class="wikitable"
! 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:''' <code>user-vm</code><br/>
'''Type:''' Directory-based storage pool<br/>
'''Location:''' Dedicated hard drive (separate from system disk)<br/>
'''Format:''' qcow2 (thin-provisioned)<br/>
'''Purpose:''' Store all user virtual machine disk images

'''Usage in virt-manager:'''
* Appears in storage pool dropdown when creating/managing VMs
* Select <code>user-vm</code> pool when creating new virtual disk

'''Usage in Vagrant:'''
* Configure in Vagrantfile: <code>libvirt.storage_pool_name = "user-vm"</code>
* All Vagrant VM disks will be created in this pool

'''Verify Storage Pool:'''

<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

== Troubleshooting ==

=== SSH Tunnel Issues ===

'''Problem:''' RDP connection fails with "Connection refused"

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

=== VM Network Issues ===

'''Problem:''' VM has no internet access

'''Check:'''
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>

'''Common causes:'''
* VM not connected to <code>pfsense-lan</code> 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: <code>sudo dhclient -r && sudo dhclient</code>

=== Vagrant Issues ===

'''Problem:''' "No usable default provider"

'''Solution:'''
<syntaxhighlight lang="bash">
# Install libvirt provider
vagrant plugin install vagrant-libvirt
</syntaxhighlight>

'''Problem:''' "Call to virStorageVolCreateXML failed"

'''Solution:'''
* Storage pool <code>user-vm</code> might not be active
* Check: <code>virsh pool-list --all</code>
* Start pool: <code>virsh pool-start user-vm</code>
* Disk space full: <code>df -h</code>

'''Problem:''' Wrong network in Vagrant

'''Solution:'''
* Verify Vagrantfile has: <code>:libvirt__network_name => "pfsense-lan"</code>
* NOT "default" or other network names

=== Storage Pool Issues ===

'''Problem:''' <code>user-vm</code> pool not visible

'''Solution:'''
<syntaxhighlight lang="bash">
# Check if pool exists
virsh pool-list --all

# Start the pool
virsh pool-start user-vm

# Set to autostart
virsh pool-autostart user-vm
</syntaxhighlight>

== Quick Reference ==

=== SSH Tunnel (Quick Start) ===

'''Linux/macOS:'''
<syntaxhighlight lang="bash">
ssh -L 3389:localhost:3389 username@HF-HV04
# Then connect RDP to: localhost:3389
</syntaxhighlight>

'''Windows (PowerShell):'''
<syntaxhighlight lang="powershell">
ssh -L 3389:localhost:3389 username@HF-HV04
# Then use Remote Desktop to: localhost:3389
</syntaxhighlight>

=== Vagrant Quick Start with Reserved IP ===

<syntaxhighlight lang="bash">
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
</syntaxhighlight>

'''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: <code>journalctl -u xrdp -f</code> (XRDP)
* Check logs: <code>journalctl -u libvirtd -f</code> (libvirt)
* Check VM console in virt-manager for boot issues
* Verify network: <code>virsh net-list --all</code>
* Verify storage: <code>virsh pool-list --all</code>

== Reserved IP Address Assignment Table ==

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

{| class="wikitable"
! 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 || || || ||
|}