Skip to main content
CloudEnterprise

Getting Started with the Proxmox VE Integration for NetBox

This guide will help you set up and start using the Proxmox VE Integration for NetBox.

Prerequisites​

Before you begin, ensure you have the following:

  • NetBox Cloud or NetBox Enterprise with NetBox Assurance
  • Orb Agent Pro credentials (required to download the integration agent image)
  • Proxmox VE cluster or standalone node with API access enabled
  • Proxmox VE API Token (token-based authentication is required — see Create an API Token)
  • Host System with Docker support
  • Network connectivity between your host(s) and both your NetBox instance and the Proxmox VE API (default port 8006)

Host Requirements​

System​

  • Operating System: Linux, macOS, or Windows with Docker support
  • Memory: Minimum 2GB RAM (4GB recommended)
  • Storage: 1GB free disk space
  • Network: Stable internet connection for pulling Docker images
  • Docker: Version 20.10 or later

Network​

  • Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
  • Outbound HTTPS access to your Proxmox VE host on port 8006 (default)
  • DNS resolution for both NetBox and Proxmox VE hostnames
  • Firewall rules configured to allow the above connections from your agent host

Proxmox VE Setup​

Create an API Token​

The integration uses API token authentication — it does not use username/password authentication. You must create a dedicated API token in Proxmox VE.

  1. Log into the Proxmox VE web UI
  2. Navigate to Datacenter → Permissions → API Tokens
  3. Click Add
  4. Select the User the token will belong to (e.g., root@pam)
  5. Enter a Token ID (e.g., netbox-integration)
  6. Uncheck "Privilege Separation" to inherit the user's permissions (or configure explicit permissions as needed)
  7. Click Add
  8. Important: Copy and securely store the Token ID and Secret — the secret is only shown once
Important

The Proxmox API token secret is only displayed once at creation time. Store it securely — if you lose it you will need to create a new token.

Minimum Permissions

For read-only access, assign the token at minimum the PVEAuditor role on the / path. This grants read access to all nodes, VMs, containers, and cluster resources.

NetBox Setup​

Generate Diode Client Credentials​

  1. Log into your NetBox instance
  2. Navigate to Diode → Client Credentials
  3. Click + Add a Credential
  4. Enter a descriptive name (e.g., "Proxmox VE Integration")
  5. Click Create Add client credentials
  6. Important: Copy and securely store the Client ID and Client Secret as you will reference this in the agent configuration file in later steps copy client credentials
  7. Navigate to Diode → Settings
  8. Copy the value of the Diode target as you will reference this in the agent configuration file in later steps copy Diode target

Agent Setup and Configuration​

Step 1: Authenticate to the NetBox Labs Image Registry​

From your host machine, authenticate to the NetBox Labs registry, using the CUSTOMER-IDENTIFIER and Token that you have been provided by the NetBox Labs team:

docker login -u<CUSTOMER-IDENTIFIER> netboxlabs.jfrog.io

Example session

% docker login -u<customer-abc123> netboxlabs.jfrog.io # note there are no spaces after -u
# Use the Token provided as the password when prompted
Password:
Login Succeeded

Step 2: Configure the Agent​

  1. Create the configuration file (you can name the file anything you like):
touch agent.yaml
  1. Edit the configuration file with your preferred editor and add the following configuration. Important: Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode > Settings > Diode target in the NetBox UI:
orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: proxmox_agent_1  # Use a meaningful name to identify this agent
  policies:
    worker:
      proxmox_ve_worker:
        config:
          package: nbl_proxmox_ve
          schedule: "*/30 * * * *"  # Every 30 minutes. Set your desired schedule (see examples below)
          PROXMOX_HOST: ${PROXMOX_HOST}
          PROXMOX_PORT: ${PROXMOX_PORT:-8006}
          PROXMOX_USER: ${PROXMOX_USER:-root@pam}
          PROXMOX_TOKEN_NAME: ${PROXMOX_TOKEN_NAME}
          PROXMOX_TOKEN_VALUE: ${PROXMOX_TOKEN_VALUE}
          PROXMOX_SSL_VERIFY: false  # Set to true in production with valid certificates
          SITE_NAME: Proxmox         # Default NetBox site name (fallback for unmapped nodes)
          # CLUSTER_NAME: "my-cluster"     # Optional: override auto-detected cluster name
          # NODE_SITE_MAP: "pve1:London,pve2:Amsterdam"  # Optional: per-node site overrides
          # PROXMOX_API_TIMEOUT: 30        # Optional: API request timeout in seconds (default: 30)
          BOOTSTRAP: false           # Set to true for initial setup only
        scope:
          nodes: ["*"]  # Use ["*"] for all nodes, or specify e.g. ["pve1", "pve2"]
Schedule Examples

The schedule field uses cron syntax. Here are some common examples:

  • "*/30 * * * *" - Every 30 minutes
  • "0 * * * *" - Every hour
  • "0 */6 * * *" - Every 6 hours (e.g., 00:00, 06:00, 12:00, 18:00)
  • "0 2 * * *" - Daily at 2:00 AM

Scope Configuration​

The scope section allows you to limit which Proxmox VE nodes are synchronized.

Configuration Options:

nodes:

  • ["*"] or omitted: Syncs all nodes (default)
  • ["pve1", "pve2"]: Syncs only the specified nodes

Examples:

Sync specific nodes only:

scope:
  nodes: ["pve1", "pve2"]

Sync all nodes (default):

scope:
  nodes: ["*"]
Scope Effect

When node scope is configured, only VMs and containers running on the specified nodes will be synchronized. Nodes not in the list are completely excluded — their devices, interfaces, VMs, and IPs will not appear in NetBox.

Node Site Mapping​

By default, all nodes and their VMs are assigned to a single site defined by SITE_NAME. You can override this on a per-node basis using NODE_SITE_MAP to assign different NetBox sites to individual Proxmox VE nodes.

Format: "node1:SiteName,node2:SiteName"

Example:

config:
  SITE_NAME: Proxmox       # Default site for nodes not in the map
  NODE_SITE_MAP: "pve1:London,pve2:Amsterdam,pve3:New York"
Additional Info

The NODE_SITE_MAP applies to both the node Device and all VMs running on that node. If a node is not in the map, the default SITE_NAME is used.

Bootstrap Mode (First-Time Setup)​

Bootstrap mode is used for the initial setup only of the integration. When enabled, it creates the static NetBox schema objects that the integration requires to function properly.

What Bootstrap Mode Creates:

  • Required Custom Fields for storing Proxmox VE metadata
  • Cluster Type ("Proxmox")
  • Tags (proxmox-ve, discovered)
  • Skips all API calls to Proxmox VE
Additional Info

The per-host unique tag (proxmox-{hostname}) is not created in bootstrap mode — it is only created during regular operation when the Proxmox API is contacted.

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-Time Run Process:

  1. Run the agent with BOOTSTRAP: true in your configuration
  2. Monitor the output for the text executed successfully
  3. Stop the agent immediately by pressing Ctrl+C in your terminal once you see executed successfully
  4. Apply the deviations in NetBox Assurance (see Apply Deviations section below)
  5. Set BOOTSTRAP: false for all future runs

Important Notes:

  • Bootstrap mode is only for first-time setup - do not run it on a schedule
  • You must stop the agent manually with Ctrl+C after seeing executed successfully
  • After bootstrap, you'll see deviations for Custom Fields, Tags, and Cluster Type that must be applied
  • Once deviations are applied, set BOOTSTRAP: false for regular operation

Optional - Dry Run Mode​

The agent can be run in Dry Run mode, which means discovered data is written to a json formatted file instead of to NetBox. This can be useful for troubleshooting - for example you could share the file with the NetBox Labs support team to investigate issues ingesting certain data.

Enable this in the Diode section of your agent configuration file, by adding the dry_run key and setting the value to true (it is false by default) and set the dry_run_output_dir value to the location you want the file to be saved.

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/ # this will save the output file into the same directory that you run the agent from

Step 3: Run the Agent​

Run the agent to synchronize data from Proxmox VE into NetBox:

Method 1: Set Environment Variables Manually​

  1. Export Diode credentials as environment variables:
export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"
  1. Export Proxmox VE credentials as environment variables:
export PROXMOX_HOST="proxmox.example.com"
export PROXMOX_TOKEN_NAME="netbox-integration"
export PROXMOX_TOKEN_VALUE="your-api-token-secret"
  1. Run the agent with the following command:
docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e PROXMOX_HOST \
  -e PROXMOX_TOKEN_NAME \
  -e PROXMOX_TOKEN_VALUE \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml
  1. Create a .env file in your current directory:
touch .env
  1. Edit the .env file with your preferred editor and add the following content:
# NetBox Diode credentials (from NetBox Setup above)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

# Proxmox VE credentials
PROXMOX_HOST=proxmox.example.com
PROXMOX_TOKEN_NAME=netbox-integration
PROXMOX_TOKEN_VALUE=your-api-token-secret
Important

Replace the placeholder values with your actual credentials:

  • your-client-id and your-client-secret from the NetBox Diode setup
  • proxmox.example.com with your Proxmox VE hostname or IP address
  • netbox-integration with your API token ID (the user@realm!tokenid portion after !, or just the token name depending on your Proxmox version)
  • your-api-token-secret with the token secret value shown when the token was created
  1. Run the agent with the following command:
docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml
Security Best Practice

When using Method 2, add .env to your .gitignore file to prevent accidentally committing sensitive credentials to version control:

echo ".env" >> .gitignore

Expected Output​

After you issue the command to run the agent, depending on the schedule you defined in the configuration file, you should see output similar to the following:

{"time":"2025-09-09T10:15:22.487755639Z","level":"INFO","msg":"worker stderr","log":"    tags {"}
{"time":"2025-09-09T10:15:22.487756472Z","level":"INFO","msg":"worker stderr","log":"      name: \"discovered\""}
{"time":"2025-09-09T10:15:22.48775743Z","level":"INFO","msg":"worker stderr","log":"    }"}
{"time":"2025-09-09T10:15:22.487758389Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487759722Z","level":"INFO","msg":"worker stderr","log":"  tags {"}
{"time":"2025-09-09T10:15:22.487761264Z","level":"INFO","msg":"worker stderr","log":"    name: \"proxmox-ve\""}
{"time":"2025-09-09T10:15:22.487771097Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487772639Z","level":"INFO","msg":"worker stderr","log":"  tags {"}
{"time":"2025-09-09T10:15:22.487773889Z","level":"INFO","msg":"worker stderr","log":"    name: \"discovered\""}
{"time":"2025-09-09T10:15:22.487774305Z","level":"INFO","msg":"worker stderr","log":"  }"}
{"time":"2025-09-09T10:15:22.487777639Z","level":"INFO","msg":"worker stderr","log":"] chunks"}
{"time":"2025-09-09T10:15:22.487777639Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run (trigger: date[2025-09-09 10:13:48 UTC], next run at: 2025-09-09 10:13:48 UTC)\" executed successfully"}
Monitoring and Testing

Success Indicators: Look for the text Successful ingestion in the output, which confirms that data was successfully sent to your NetBox instance via Diode.

Testing Mode: For testing purposes, you can run the agent once and then stop it:

  • Press Ctrl+C in your terminal to stop the agent
  • This is useful for verifying configuration before setting up continuous operation

Continuous Operation: The agent will continue running according to your schedule until manually stopped or the container is terminated.

View and Apply Discovered Data in NetBox Assurance​

You can now work with the Proxmox VE data that has been discovered by the agent in the NetBox Assurance UI.

NetBox Assurance gives you control over operational drift by identifying deviations between your operational state and NetBox, and analytics to understand drift and plan for remediation, and ultimately take action.

Understanding Deviations

Deviations are the delta between the data already in NetBox as the Network Source of Truth, versus the actual operational state of the network as discovered by the controller integration.

From an initial run of the integration it could be that ALL discovered data is a deviation as it may not have existed in NetBox previously. Once the initial sync of data has taken place, and NetBox has been updated, then further integration runs would result in new deviations only.

Accessing NetBox Assurance​

  1. Navigate to the UI of your NetBox instance
  2. Click on Assurance in the main navigation menu

Explore Deviation Types​

  1. Click on Deviation Types to view the types of deviations that have been discovered View deviation types
  2. Click on the Name of a deviation type, to view deviations for a particular type Discovered new virtual machine
  3. Click on the Name of an individual deviation, to view the details Discovered VM details

View Active Deviations​

  1. Click on Active Deviations to view all the deviations that have not yet been Applied or Ignored Active deviations
  2. Click on the Name of a deviation, to view the details

Apply Deviations​

  1. Select all the deviations that you'd like to apply. If you are working with a large number of deviations, first set the Per Page view to 500: select 500
  2. Then select the first deviation, hold down SHIFT and select the last one, and then click Apply Selected: apply deviations
  3. Click Apply X Deviations to apply the deviations to the NetBox database: confirm apply deviations
Apply Deviations to a Branch

Instead of writing the deviations to the Main NetBox database branch, you can select another branch from the drop down menu and apply the deviations to that branch.

Assurance Docs

For more detailed information on working with NetBox Assurance, please refer to the documentation

View the Proxmox VE Data in NetBox​

Now that you have run the integration at least once and applied the discovered data, you can view the Proxmox VE data in the NetBox UI.

  1. Navigate to Virtualization → Virtual Machines to view the synchronized VMs and LXC containers: Proxmox VMs view
  2. Click on an individual VM to view its details, including interfaces, IP addresses, and virtual disks: Proxmox VM details
  3. Navigate to Virtualization → Clusters to view the Proxmox cluster: Proxmox cluster view
  4. Navigate to DCIM → Devices and filter by device role "Hypervisor" to view Proxmox nodes: Proxmox nodes view
  5. Navigate to IPAM → Prefixes to view the synchronized network prefixes: Proxmox prefixes

Additional Resources​

Support​

Email support@netboxlabs.com for support.

Related Topics
AssuranceAutomationDiscoveryGetting StartedIntegrationNetBox
Last updated on