Skip to content

Proxmox VE

TL;DR / when to use this: Proxmox VE is my hypervisor of choice for the home server — it runs the Ubuntu VM that hosts my Docker stack, handles ZFS storage with snapshots, and pairs with Proxmox Backup Server (PBS) for image-level backups. If you're turning a bare-metal box into a hypervisor, this is the guide.

Installing Proxmox

  1. Download the Proxmox VE ISO and burn it to USB (Fedora Media Writer or BalenaEtcher both work), then boot the machine from it.
  2. During install you'll be prompted to name the node — the machine Proxmox is installed on. Use the asset name (e.g. hp-z220) rather than a generic name like proxmox.

DNS

Make sure DNS works before doing anything else:

ping google.com

If it fails, set it at Node → System → DNS — Cloudflare (1.1.1.1) is a fine choice.

Repositories

Proxmox defaults to the enterprise repositories, which error on apt update without a subscription. Disable both enterprise repos at Node → Updates → Repositories, then Add the two no-subscription repositories.

Storage

Pools for VM drives

At the node level, look at Disks and create storage by type:

  • LVM-Thin for single disks storing VM disk volumes
  • ZFS when using an array (RAID)

Both support snapshots. If the disk you want isn't in the dropdown, go to Disks in the tree, select it, and wipe it — if it can't be wiped because it's mounted, unmount it first (Cockpit makes this easy; see below).

Thin-provisioned ZFS

LVM-Thin is obviously thin, but ZFS needs an extra step:

  1. Create the ZFS pool under Disks at the node. I set compression to lz4 and ashift to 12. Starting with a single disk and moving to a mirror later is fine — you can add drives to the mirror with simple commands.
  2. Before creating any VM drives on the pool, go to Datacenter → Storage, click the pool, click Edit, and check Thin provision.

Info

To change compression after the pool exists (only affects new writes):

zfs set compression=lz4 Personal4T

Mounting disks to the host (Cockpit)

Proxmox's UI doesn't offer a clean way to mount/unmount disks to the host, so I install Cockpit:

sudo apt update
sudo apt install cockpit
sudo systemctl enable --now cockpit.socket

Cockpit requires a non-root user:

adduser thomas
usermod -aG sudo thomas

Device passthrough and shared directories

For an external USB drive that multiple trusted VMs need file-level access to:

  1. Mount the drive on the host at a path, e.g. /mnt/external_drive (Cockpit, or mount + fstab). For NTFS drives install ntfs-3g.
  2. At the Datacenter level, create a Directory Mapping pointing at that path.
  3. On the VM: Hardware → Add → Virtiofs, select the Directory Mapping ID.

  4. Inside the VM:

    sudo mount -t virtiofs <mapping-name> /mnt/external_drive

    and persist it in /etc/fstab:

    <mapping-name>  /mnt/external_drive  virtiofs  defaults,nofail  0  0

Converting a RAID1 array to a ZFS mirror

When moving a Linux MD RAID array onto Proxmox, the metadata is still on the drives but the array must be reassembled:

sudo mdadm --detail --scan     # check if the array exists
sudo mdadm --assemble --scan   # reassemble it

The easiest conversion path is to free one disk from the array — the RAID1 keeps running degraded on the remaining drive:

# Mark the disk to remove as failed
mdadm --fail /dev/md0 /dev/sda

# Remove it from the array
mdadm --remove /dev/md0 /dev/sda

# Clear the mdadm metadata so it can be formatted as ZFS
sudo mdadm --zero-superblock /dev/sda

Warning

/dev/md0 is where my array was mounted. If you never mounted the array, check whether you can do this without mounting. Keep careful track of which disk is the old RAID and which is the new ZFS.

After creating the ZFS pool on the freed drive, mount both (the old RAID via Virtiofs) and copy the data across:

sudo rsync -ah --info=progress2 /mnt/md0/ /mnt/zfs/

Expanding a VM disk

Resize at VM → Hardware → Hard Disk → Resize (new size must be greater), then expand inside the guest — Proxmox does not do this for you. For an ext4 guest:

lsblk
sudo growpart /dev/sda 1
sudo resize2fs /dev/sda1

Double-check the right commands for whatever filesystem the VM uses.

Known pitfalls

Proxmox freezing on large rsync (Intel NIC bug)

If Proxmox freezes during large rsync transfers on older hardware, check the logs after a freeze for e1000e: Detected Hardware Unit Hang. Fix by disabling NIC offloading:

sudo ethtool -K eno1 tso off gso off gro off

To persist it, add to /etc/network/interfaces (replace eno1 with your interface from ip address):

iface eno1 inet manual
    post-up ethtool -K eno1 tso off gso off gro off

Reference: Reddit thread on the e1000e hang.

Proxmox Backup Server (PBS)

PBS gives image-level backups of VMs/LXCs to an external drive. The full walkthrough is in Proxmox Backup Server — the short version: mount the drive on the host, create a Directory Mapping, run PBS as a small VM (10 GB disk, 2 GB RAM, 2 CPU) with the datastore mounted via Virtiofs, create a DatastoreAdmin user, add PBS as a Datacenter storage, and schedule a backup job.

See also