Proxmox VE

Proxmox VE

Purpose

Proxmox VE is the primary hypervisor for the Bytek homelab.

Proxmox hosts and manages:

Proxmox is a critical management system and must remain accessible independently of Pi-hole, Traefik, and Authentik.

Service Information

Management interface:

Open Proxmox VE

Access Policy

The Proxmox management interface must remain private.

Approved access paths include:

The following access methods are prohibited:

Pi-hole resolves pve.bytek.ca directly to 192.168.2.254.

DNS Design

The Proxmox host intentionally uses Quad9 at 9.9.9.9 instead of Pi-hole.

This prevents the hypervisor from depending on a guest VM or LXC for its own DNS service.

The DNS behavior differs depending on the requester:

Proxmox may therefore reach Authentik through the public VPS, WireGuard, and Traefik path.

If that path becomes unreliable for OIDC, a single static entry can map portal.bytek.ca to 192.168.2.182 in the Proxmox /etc/hosts file without changing the general DNS resolver.

Browser DNS Requirement

The private hostname pve.bytek.ca exists only in Pi-hole.

Firefox-based browsers such as Zen may bypass Pi-hole when enhanced DNS protection or DNS over HTTPS is forced.

Recommended browser configuration:

If the private hostname does not load but the IP address works, verify browser DNS protection before changing Proxmox.

Useful Windows checks:

Expected results:

Authentication Model

Normal Authentication

Normal administration uses native OpenID Connect with Authentik.

The matching Authentik provider requires:

Required Authentik bindings:

A user must satisfy both the group and policy requirements.

Authentik Scope Mappings

The Proxmox Authentik provider must include the following selected scope mappings:

Missing scope mappings can allow the browser authorization step to succeed while causing Proxmox to fail at the Authentik userinfo endpoint.

A previously observed failure was:

Selecting the expected mappings in the Authentik provider resolved the authentication flow.

Authentication and Authorization Are Separate

Successful Authentik authentication creates the Proxmox user but does not grant access to VMs, containers, nodes, or storage.

A newly created OIDC user may initially see an empty interface.

The user requires an explicit Proxmox access-control entry.

For the primary administrator:

The username normally ends with the realm:

Do not accidentally grant the permission to the PAM version of the username.

Break-Glass Authentication

The local Proxmox PAM account must remain available.

Never:

The root@pam account should be tested periodically in a private browser session.

Web Service Health

The Proxmox web interface is provided by pveproxy.

Check service state with:

systemctl is-active pveproxy

Expected result:

Check the listener with:

ss -lntp | grep ':8006'

Expected result:

Test locally with:

curl -k https://127.0.0.1:8006/

A 501 method HEAD not available response from a command using curl -I does not indicate an outage. That response confirms the HTTPS service was reached, but the endpoint does not support the HTTP HEAD method.

Network Validation

Test from another LAN VM:

nc -zv -w 5 192.168.2.254 8006

A successful result confirms TCP reachability.

Test HTTPS by IP:

curl -k https://192.168.2.254:8006/

Test HTTPS by private hostname:

curl -k https://pve.bytek.ca:8006/

If the hostname fails but the IP works, investigate DNS rather than pveproxy.

OIDC Validation

Verify that Proxmox can retrieve Authentik discovery information:

curl -fsS https://portal.bytek.ca/application/o/proxmox/.well-known/openid-configuration

The response should contain OIDC metadata such as:

A request to the userinfo endpoint without a bearer token should return an authentication error.

That response is expected and proves the endpoint is reachable.

OIDC Troubleshooting

Review recent Proxmox authentication logs with:

journalctl -u pvedaemon --since "10 minutes ago" --no-pager

Look for terms such as:

Authentication Failure 401

Possible causes include:

Failed to Contact Userinfo Endpoint

Check:

Login Works but No VMs Appear

The OIDC user has not been assigned a Proxmox ACL.

Assign the required role at / with propagation enabled.

Private Hostname Does Not Resolve

Check:

Firewall Policy

Proxmox TCP port 8006 should accept traffic only from approved management sources.

Potential management sources include:

Do not create an internet-wide accept rule for TCP 8006.

SSH should use:

Storage Attached to Proxmox

Review storage state using:

pvesm status

All required storage should show as active.

Backup System

Proxmox uses its built-in scheduled backup system.

Backups are written to:

The general job uses:

The backup mount uses mount-point validation to prevent writing backup data to the Proxmox root filesystem if the HDD is unavailable.

Snapshots

Snapshots are used only for short-term rollback.

Appropriate snapshot cases include:

Snapshots are not backups.

Delete snapshots after the associated change has been validated.

Long-lived snapshots consume thin-pool capacity and increase storage risk.

Planned GPU Passthrough

The RTX 2060 is planned for a dedicated Plex VM.

Before passthrough:

A VM with passed-through hardware cannot use normal live migration.

Proxmox Recovery

If Authentik authentication fails:

If the web interface fails:

If the system disk fails:

Validation Checklist

Document Control