Revision as of 11:55, 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)

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.

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

:

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:

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

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:

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):

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

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

Connecting to the 10.7.1.0/24 network

From Pune office, the network is routed and you can reach out to your vm by using it's ip.

From Home Office, you can use your openVPN client to connect to the network.

use this configfile (username and password is the same as the vpn login that you use for H+F VPN access already) :

dev tun
persist-tun
persist-key
data-ciphers AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305:AES-256-CBC
data-ciphers-fallback AES-256-CBC
auth SHA256
tls-client
client
resolv-retry infinite
remote 148.113.26.212 1194 udp4
nobind
auth-user-pass
remote-cert-tls server
explicit-exit-notify

<ca>
-----BEGIN CERTIFICATE-----
MIIDMzCCAhugAwIBAgIIOQA2nMrG8e8wDQYJKoZIhvcNAQELBQAwFjEUMBIGA1UE
AxMLaW50ZXJuYWwtY2EwHhcNMjUxMTIxMDk1MDI5WhcNMzUxMTE5MDk1MDI5WjAW
MRQwEgYDVQQDEwtpbnRlcm5hbC1jYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAJRl5chLFhhttaQ+SIb8WsL2JCSfehhfOKBXVvq6sl8ybQBmH6y7QQEi
ijdZW1tnqce8xhDfBlbNe/haTRYi6Hr9Hme5VmtKunmCUydzj2oSz070NpEvirDf
UPWmgW9RviPkX+3MLBw4GKTIKimWkPa6SFovSN9k0mHjxQ583EsVkb95MImHbAXl
9A1I1ITlqDqKq9yWV0EjWm7piatNo6ZdqDc0NUhYhAhS7BzmCPe7DZZMRAgO/QxR
vR4G4vKV4RPsszVQZ3RsqLxif5lBNPQ2SjrGF4Cq8J3pEKfufl+Rjb5xaQLlOFM5
Dl4P70kV9ynFwT2Fff9wGi8t5FMVDDUCAwEAAaOBhDCBgTAdBgNVHQ4EFgQUnADh
dcajDF+zAIXLJKEUi8dbhQYwRQYDVR0jBD4wPIAUnADhdcajDF+zAIXLJKEUi8db
hQahGqQYMBYxFDASBgNVBAMTC2ludGVybmFsLWNhggg5ADacysbx7zAMBgNVHRME
BTADAQH/MAsGA1UdDwQEAwIBBjANBgkqhkiG9w0BAQsFAAOCAQEAb6wXZ5d7uW6Z
BkZxfDECJe9EM3IkxFK1UPtlbu4wIpAK94K0nC6JhPzysNwYD9x09cy19ts8Al7M
QxySy9yQ7tlBkoD4lM0VrZstbTKU2RMUEZ6NS72azS0lvt6FPSZEBNR65e08KNwZ
TUl2N8xRZ6jaRbSkNr+mR9sUMOnCY/dWtzPHSu3yG/USWiunK04YUID8qars4VCH
ZOFuiyVlPnU/b+1Gb7ZbSRmJoQVLkNUINaUDKS3ywxTVqwcRRVQyNA18hJ5LbxiF
pxfdSqUF4ATYXes9ASJ641sKaw2/VPvJQpDyJ4wqvMQN7rL840Si1ezb3Zm9h17C
NtvlkpvVtg==
-----END CERTIFICATE-----
</ca>
setenv CLIENT_CERT 0
key-direction 1
<tls-auth>
#
# 2048 bit OpenVPN static key
#
-----BEGIN OpenVPN Static key V1-----
89eee22bd6b6d2631cfb42217b86992b
69df8c59c3de0cd0ce062f3d31464988
2520dd98f5510f4da8a5d41ac43a5f46
f4ec4c8d9cc9cdcd0aeffa2538c161b9
00b1c0f806fb62e52a8c76c71e2bf617
896076f9fe12f2a2727d1c539da883b1
2bc90b424bc296f67a15ec3030d872d9
2c5798f75ae2668f4ff6276cefbd1bc7
ebeee682b8d6d9b398001f2559ec3411
cbe55ddcfaf01c35c119cb0e425aa3ea
8aac56bf8dc302d8f8c53f8d24de0cfc
508900d4603aa2a98b7413cc066177ec
6a91d278aca525ef1cec4c212448ecdc
8a01525388f69b899b11c26212e50db6
d14c10210ae1dcc2171621fd982facb4
0e57d658a6c27619b873dd9eebbfeb9b
-----END OpenVPN Static key V1-----
</tls-auth>