🧭 Proxmox Single-Node Administration Guide

Author’s Note:
All paths and commands shown in this guide reflect a real working Proxmox setup.
You can safely adapt them for your own environment if your interface or IP layout differs.

⚙️ Introduction: Why Proxmox VE

Proxmox Virtual Environment (Proxmox VE) is an open-source virtualization platform that combines KVM (for virtual machines) and LXC (for lightweight containers) in a single, powerful web-based interface.

For homelabs, testing, or even small-scale production environments, Proxmox offers:

• Intuitive web UI
• Advanced CLI control
• Built-in backup and snapshot support
• Integrated firewall and VLAN tagging
• Optional clustering and shared storage

💡 Tip: This guide focuses on a single-node setup, ideal for automation and homelab usage.
A follow-up post covers multi-node clustering and Ceph storage.

🧱 1. Installing Proxmox VE

Step 1. Download and Install

1. Download the latest ISO from https://www.proxmox.com/en/downloads
2. Boot the system and install using default guided options.

Step 2. Network Configuration During Install

Assign a static IP for management (e.g., 10.0.0.3), and note your chosen hostname (e.g., pve-node).

Step 3. Accessing the Web Interface

After installation, open your browser:

https://<your-proxmox-ip>:8006

Default user: root@pam

🧩 2. Initial Configuration

Disable Enterprise Repository (for non-subscription users)

sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list
echo "deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription" > /etc/apt/sources.list.d/pve-no-subscription.list
apt update && apt full-upgrade -y

Enable SSH and Configure Access

systemctl enable ssh
systemctl start ssh

You can now SSH in:

ssh [email protected]

🧰 3. User Management and Permissions

While root@pam is the default admin, best practice is to create a dedicated automation user for Terraform and Ansible integration later.

Create User

From the Proxmox Web UI:
Datacenter → Permissions → Users → Add

Example:

• User ID: terraform@pve
• Group: Administrators

Create API Token

Datacenter → Permissions → API Tokens → Add
Associate it with your automation user and note the generated token ID and secret.

🧠 Pro Note: This token-based authentication allows Terraform to connect securely to the Proxmox API.

🧩 4. Working with LXC Containers

Proxmox supports Linux Containers (LXC) for lightweight, resource-efficient environments.

Create a Container via CLI

pct create 201 local:vztmpl/ubuntu-22.04-standard_22.04-2_amd64.tar.zst   -hostname test-lxc   -storage local-lvm   -rootfs local-lvm:8   -net0 name=eth0,bridge=vmbr0,ip=10.0.10.10/24,gw=10.0.10.1   -password

Manage Containers

💡 Tip: Containers can share kernel resources and start in seconds compared to full VMs.

🖥️ 5. Managing Virtual Machines (KVM)

Create a New VM

qm create 101 --name ubuntu-vm --memory 2048 --net0 virtio,bridge=vmbr0
qm importdisk 101 ubuntu.qcow2 local-lvm
qm set 101 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-101-disk-0
qm start 101

Common VM Commands

⚠️ Caution: Always shut down VMs gracefully before destroying to prevent disk lock issues.

🌐 6. Networking in Proxmox

Proxmox uses Linux bridges to connect VMs and LXCs to physical networks.

Example /etc/network/interfaces

auto lo
iface lo inet loopback

auto eno1
iface eno1 inet manual

auto vmbr0
iface vmbr0 inet static
    address 10.0.0.3/24
    gateway 10.0.0.1
    bridge_ports eno1
    bridge_stp off
    bridge_fd 0

VLAN Tagging Example

auto vmbr0.10
iface vmbr0.10 inet static
    address 10.0.10.1/24
    vlan-raw-device vmbr0

💡 Tip: Each container or VM can have its own VLAN tag (configured via tag= in Terraform or UI).

Useful Network Commands

ip a
brctl show
journalctl -u networking

💾 7. Storage Management

List Available Storage

pvesm status

Add NFS Storage

pvesm add nfs backups 10.0.0.10:/mnt/backups

Backup Containers or VMs

vzdump 201 --storage local --compress zstd

Restore from Backup

pct restore 202 /var/lib/vz/dump/vzdump-lxc-201.tar.zst

🧠 Pro Note: For scheduled backups, use Datacenter → Backup from the Web UI.

🧠 8. Maintenance and Troubleshooting

Check Service Status

systemctl status pvedaemon pveproxy pvestatd

Restart Proxmox Services

systemctl restart pve-cluster pvedaemon pveproxy

View Logs

journalctl -xe
tail -f /var/log/pve/tasks/index

System Update and Cleanup

apt update && apt full-upgrade -y
pveperf
apt autoremove -y

💡 Tip: Run pveversion -v to confirm version consistency after updates.

⚙️ 9. Preparing for Automation (Terraform + Ansible)

This section bridges your Proxmox setup with the automation stack.

Enable API Access for Terraform

1. Ensure your automation user (e.g., terraform@pve) exists.
2. Create an API token under that user.
3. Note down the token ID and secret — these will be referenced in terraform.tfvars.

Terraform connects via:

pm_api_url          = "https://<proxmox-ip>:8006/api2/json"
pm_api_token_id     = "terraform@pve!tf-token"
pm_api_token_secret = "<SECRET>"

Prepare for Ansible

Ensure SSH key authentication is working:

ssh automation@<container-ip>

This allows Ansible to run configuration playbooks (like system updates, tool installations, and user creation).

💡 Tip: Keep your /home/automation/.ssh/id_rsa.pub consistent — Terraform injects this key into all new containers automatically.

🧾 10. Command Reference Cheat Sheet

✅ Summary

With this single-node Proxmox setup, you now have:

• A fully functional hypervisor with KVM + LXC support
• Configured networking and storage
• SSH and API access ready for automation

💡 Next step: Integrate Terraform and Ansible to provision and configure containers automatically.
See the companion article: “Terraform + Ansible + Proxmox Automation Guide.”

🔧 Bonus Tips

• Use cron for automatic backups of containers and VMs.
• Export and version-control your /etc/pve folder periodically.
• Keep templates updated (pveam update) for the latest OS images.

End of Guide — Proxmox Single Node Administration