Adding a Linux PAM User to Proxmox

⚠️

Why this guide exists: Logging into any system as root directly is a security anti-pattern. There is no audit trail — every action looks the same regardless of who performed it. Named user accounts with sudo provide accountability, traceability, and least-privilege access. This guide is specifically designed to let administrators manage a Proxmox host without needing the root login.

Proxmox VE supports two authentication realms for user accounts:

Realm	How It Works
PVE (`@pve`)	Managed entirely within the Proxmox web interface. Does not require a corresponding Linux account.
PAM (`@pam`)	Authenticates against the underlying Linux system. Users can log into the Proxmox host via SSH in addition to the web UI.

This guide walks through creating a PAM user from scratch on a Proxmox host. All commands are run as root.

💡

If the user only needs access to the Proxmox web UI and will never SSH into the host, the PVE realm (@pve) is simpler — it doesn't require a Linux account at all. Use PAM when SSH access is required.

Step 1 — Set the Username Variable

Define a shell variable for the new username. This keeps the remaining commands copy-pasteable — just change this one value.

bash

NEWUSER="theactualusername"

💡

This variable only exists for the current shell session. If you close the terminal and come back, you'll need to set it again before running any of the commands below.

Step 2 — Create the Linux User

Create the system account with a home directory and a bash shell, then set a password.

bash

useradd -m -s /bin/bash $NEWUSER
passwd $NEWUSER

-m creates the home directory at /home/$NEWUSER
-s /bin/bash sets the default shell to bash

💡

The passwd command will pause and prompt for interactive password input — it won't appear in the terminal as you type. Enter the password twice to confirm.

Step 3 — Register in Proxmox as a PAM User

The Linux account exists, but Proxmox doesn't know about it yet. Register the user in the PAM authentication realm.

bash

pveum user add $NEWUSER@pam

The user will now appear in the Proxmox web interface under Datacenter → Permissions → Users.

💡

Proxmox roles and permissions should be assigned through the web GUI: Datacenter → Permissions. This is where you control what resources (VMs, storage, nodes) the user can access and what actions they can perform.

Step 4 — Install Sudo and Grant Privileges

Proxmox (Debian-based) does not ship with sudo installed. Install it and add the new user to the sudo group.

bash

apt update && apt install sudo -y
usermod -aG sudo $NEWUSER

apt install sudo is a one-time requirement — once installed, all future users can be added to the group without repeating this step
-aG sudo appends the user to the sudo group without removing them from any existing groups

Step 5 — Set Up SSH Key Authentication

Create the .ssh directory structure, set the correct permissions, and add the user's public key.

bash

mkdir -p /home/$NEWUSER/.ssh
touch /home/$NEWUSER/.ssh/authorized_keys
chown -R $NEWUSER:$NEWUSER /home/$NEWUSER/.ssh
chmod 700 /home/$NEWUSER/.ssh
chmod 600 /home/$NEWUSER/.ssh/authorized_keys

Open the authorized_keys file and paste the user's public key:

bash

nano /home/$NEWUSER/.ssh/authorized_keys

⚠️

Permissions are critical. SSH will silently reject key authentication if the directory or file permissions are wrong. The .ssh directory must be 700 and the authorized_keys file must be 600.

⚠️

Ownership matters. Since root is creating these files, the chown step is essential — ownership must be handed to the new user. Without this, SSH will reject the key even if the permissions are correct.

Proxmox Root-Only Limitations

Proxmox hardcodes certain web UI features exclusively to root@pam. No role or permission assignment — not even the built-in Administrator role — will unlock these for other users. This is by design and has not changed since at least Proxmox 6.

System Updates (Greyed-Out Upgrade Button)

The Upgrade button on the Updates panel is only clickable when logged in as root@pam. Proxmox restricts this because apt dist-upgrade can execute arbitrary package hook scripts, which would effectively grant root-level access to whoever triggers it.

Workaround: SSH into the host as your named user and run updates via sudo:

bash

sudo apt update && sudo apt dist-upgrade

This is actually better than using the web button — your username appears in auth.log alongside the elevated command, giving you a proper audit trail.

Shell Auto-Login

When root@pam opens the web-based Shell (xterm.js), Proxmox automatically logs in without a prompt. For every other user — even those with full Administrator permissions — the shell presents a login prompt requiring username and password.

There is no configuration option to enable auto-login for non-root users. This is hardcoded in the Proxmox source.

Workaround: Use SSH with key authentication (which this guide sets up) instead of the web shell. You get passwordless login, a proper audit trail, and a better terminal experience.

Additional Notes

PAM vs PVE Realm

For users who only need Proxmox web UI access (no SSH), the PVE realm (@pve) can be used instead. PVE users are managed entirely within Proxmox and do not require a corresponding Linux account — making them simpler to set up and maintain.

Assigning Proxmox Permissions

After creating the user, navigate to Datacenter → Permissions in the Proxmox web interface to assign roles. Roles control what the user can see and do — common choices include PVEVMAdmin for VM management or PVEAuditor for read-only access.