Skip to main content

Proxmox VE

Knocknoc integrates with Proxmox VE to dynamically control network access using the built-in Proxmox firewall.

The Knocknoc agent maintains a Proxmox firewall ipset. As users authenticate and grants expire, the agent adds and removes IP entries in the ipset over the Proxmox REST API. Existing firewall rules reference the ipset by name, so access is granted in seconds and no rules are rewritten.

An ipset can live at one of two scopes. A cluster (datacentre) ipset is defined once at the datacentre level and can back firewall rules on many VMs at once. A per-VM ipset belongs to a single VM and only affects that VM's firewall. Choose the scope that matches where your firewall rule lives.

Requirements

  • Proxmox VE 7.0 or newer with the firewall feature enabled at the level you intend to protect (datacentre or VM)
  • An ipset already created at that scope, referenced by at least one firewall rule
  • A Proxmox API token with privileges to read and modify the firewall ipset
  • Network reachability from the Knocknoc agent host to the Proxmox API (default port 8006)

Setup

Step 1: Create the API token

  1. Log into the Proxmox web interface as an administrator
  2. Open Datacenter > Permissions > Users and add a user such as knocknoc@pve (the pve realm is the built-in Proxmox authentication realm)
  3. Open Datacenter > Permissions > API Tokens and click Add:
    • User: the account you just created
    • Token ID: e.g. agent. The full token identifier becomes knocknoc@pve!agent
    • Privilege Separation: see the note in Step 2 before deciding. Leaving it ticked is the Proxmox default
  4. Click Add. Proxmox shows the secret value once. Copy it now, you'll paste it into Knocknoc

Step 2: Grant the token firewall privileges

Knocknoc authenticates as the token, so the token itself needs the privileges. First create a role with the privileges for your scope, under Datacenter > Permissions > Roles (or reuse the built-in PVEFirewallAdmin role, or any role that includes the privileges below).

For a cluster ipset, the role needs these privileges, assigned at path /:

  • Sys.Audit to read the cluster firewall
  • Sys.Modify to change the ipset entries

For a per-VM ipset, assign on the VM (path /vms/<vmid>):

  • VM.Audit to read the VM and its firewall
  • VM.Config.Network to change the ipset entries

Now assign the role. Permissions are added from the Datacenter > Permissions panel itself, not the Users or API Tokens tabs and not the user-edit dialog. Click Add at the top of the Permissions panel, then choose the permission type. The dialog has Path, the user or token, Role, and a Propagate checkbox. Leave Propagate ticked so the privilege applies to the firewall sub-paths. Propagate only appears in this Add Permission dialog.

How many permissions you add depends on the token's Privilege Separation setting:

  • Privilege Separation ticked (the default): a token's effective privileges are the intersection of the user's permissions and the token's own permissions, so you must add the role twice. Once via Add > User Permission for the account (e.g. knocknoc@pve), and once via Add > API Token Permission for the token (e.g. knocknoc@pve!agent). Each at path / with Propagate ticked. Granting only one of the two leaves the token with no privileges.
  • Privilege Separation unticked: the token inherits the user's permissions, so a single Add > User Permission for the account is enough.

Step 3: Create the ipset and firewall rule

The agent only edits entries in an ipset that already exists. Create it and reference it from a rule:

  1. For a cluster ipset, go to Datacenter > Firewall > IPSet. For a per-VM ipset, go to the VM's Firewall > IPSet.
  2. Click Create and give it a name, e.g. knocknoc_allowed. The name must start with a letter and contain only letters, digits, underscores, hyphens, or plus signs. Leave it empty, Knocknoc adds entries on the first grant
  3. Open Datacenter > Firewall (the Firewall node is the rules grid itself, there's no separate Rules item) and click Add to create a rule:
    • Direction: in
    • Action: ACCEPT
    • Source: +knocknoc_allowed (the ipset, prefixed with +)
    • Dest. port / Protocol: whatever fits your policy
  4. Make sure the rule sits above any default drop rule, and that the firewall is enabled at that level

Step 4: Configure the Knocknoc Backend

In the Knocknoc admin wizard, create a Knoc and choose the Application type, Active mode, Proxmox VE vendor. Fill in:

Field Value
Proxmox URL https://pve.example.com:8006 (include the scheme and port)
Insecure Tick only if the node uses a self-signed certificate
API Token ID The full identifier, e.g. knocknoc@pve!agent
API Token Secret The secret shown once when the token was created
Scope Cluster (Datacentre) or Per-VM
Proxmox node Per-VM scope only: the node hosting the VM, e.g. pve01
VM ID Per-VM scope only: the numeric VM identifier, e.g. 100
Ipset name The existing ipset name, e.g. knocknoc_allowed

Click Validate connection to confirm the agent can reach the node and read the ipset, then save.

Troubleshooting

Validate connection runs three read-only checks against Proxmox: that the node is reachable and the token authenticates, that the configured node and VM ID exist (per-VM scope only), and that the ipset exists at the chosen scope. A failing check shows an agent error code that links straight to the matching troubleshooting page.

An HTTP 403 (agent error #PROX001) on the first grant almost always means the token has no firewall privileges. With Privilege Separation enabled, the usual cause is granting the role to only the user or only the token. Add it in both places (User Permission and API Token Permission), each at the right path with Propagate ticked, as described in Step 2.

If validation passes but grants don't appear, confirm the role includes the modify privilege for your scope (Sys.Modify for cluster, VM.Config.Network for per-VM), not just the audit privilege.

Error codes

The agent surfaces a specific error code when it cannot apply a grant. Each code links to a docs page with resolution steps.

Code Meaning
PROX000 Proxmox rejected the API token
PROX001 API token lacks the required privileges
PROX002 Proxmox did not respond in time
PROX003 TLS/SSL certificate error
PROX004 Connection refused by Proxmox
PROX005 DNS resolution failed for the Proxmox hostname
PROX006 Proxmox request failed (other transport error)
PROX100 Configured ipset was not found
PROX101 Failed to read ipset contents
PROX102 Failed to add an entry to the ipset
PROX103 Failed to remove an entry from the ipset
PROX104 Proxmox node or VM not found
PROX400 Proxmox returned an unexpected response

Vendor Documentation

Back to top