Proxmox to NetBox Sync GUI

A desktop GUI application for synchronizing Virtual Machines (VMs), LXC Containers, and Proxmox VE nodes (as Devices) from Proxmox environments to a NetBox instance.

Overview

This tool provides a user-friendly interface to connect to one or more Proxmox VE nodes, fetch information about virtualized resources and the nodes themselves, and then synchronize this data to NetBox. It helps keep your NetBox inventory up-to-date with your Proxmox virtualization platform.

Features

GUI Interface: Easy-to-use desktop application built with PyQt6.
Multiple Proxmox Nodes: Configure and switch between multiple Proxmox nodes.
VM/LXC Synchronization:
- Syncs VMs and LXC containers to NetBox Virtualization.
- Maps Proxmox VM status to NetBox VM status.
- Syncs vCPUs, memory, and primary disk size.
- Syncs network interfaces, including MAC addresses, IP addresses (if static), and VLAN tags.
- Syncs Proxmox tags to NetBox tags.
- Extracts OS information from Proxmox notes (e.g., os: Ubuntu 22.04) or uses ostype.
- Synchronizes detailed virtual disk information (name, size, storage ID, boot disk).
- Populates various Proxmox-specific details into NetBox custom fields.
- Advanced IP Address Discovery:
  - Identifies IP addresses statically configured on VM/LXC interfaces directly in Proxmox.
  - For running QEMU VMs, if a static IP is not found (e.g., VMs with DHCP), the application will attempt to retrieve active IP addresses by querying the QEMU Guest Agent installed in the VM. This ensures more accurate and up-to-date IP information in NetBox.
  - The first non-link-local IP address (IPv4 or IPv6) obtained will be used to set the primary IP for the VM in NetBox.
Proxmox Node to NetBox Device Synchronization:
- Syncs the Proxmox VE node itself as a "Device" in NetBox DCIM.
- Allows mapping to NetBox Site, Device Role, Manufacturer, Device Type, and Platform.
- Syncs node hardware details (CPU model, sockets, cores, total memory, root FS size) to custom fields.
- Syncs node network interfaces (physical, bridges, bonds, VLANs) with their IP addresses to the NetBox Device.
Orphan Handling: Marks NetBox VMs as "Deleted" (via a custom field) if they no longer exist in Proxmox.
Configuration Management:
- Settings dialog to manage global NetBox connection details and Proxmox node configurations.
- Configurations are stored in a local .env file or managed via the GUI.
Logging: View real-time logs of operations within the application.
Background Operations: Long-running tasks (API calls, synchronization) are performed in background threads to keep the GUI responsive.

Preserving Node Interfaces in NetBox

During the synchronization of a Proxmox node to a NetBox Device, interfaces that exist in NetBox but are not found in the Proxmox node's configuration are typically considered "orphaned" and are deleted by default.

However, ProxSyncBox will preserve interfaces in NetBox if their standard boolean field mgmt_only (Management Only) is set to True. This is particularly useful for out-of-band (OOB) management interfaces or other specific logical interfaces that are tracked in NetBox but are not part of the Proxmox node's manageable network configuration. These 'management only' interfaces are not deleted during the node synchronization process due to their specific nature, ensuring they remain in your NetBox inventory.

Prerequisites

Python: Version 3.8 or higher.
Proxmox VE: A running Proxmox VE environment with API access.
- An API token for authentication is recommended.
NetBox: A running NetBox instance (version 3.x or higher recommended) with API access.
- An API token with appropriate permissions (read, create, update, delete for virtualization and DCIM components).

Creating a Proxmox VE API Token

To allow ProxSyncBox to access your Proxmox VE data, you need to create an API token. It's recommended to use a dedicated user and an API token with specific permissions. The PVEAuditor role is generally sufficient for this application as it primarily reads data.

Log in to the Proxmox VE web UI.
Create a dedicated user (Optional but Recommended):
- Navigate to Datacenter > Permissions > Users.
- Click Add.
- Fill in the User name (e.g., netbox_sync_user), select Realm (e.g., pam for local users or pve for PVE realm users), and set a password (though the password won't be used directly by the token).
- Click Add.
Assign PVEAuditor Role to the User (or root@pam):
- Navigate to Datacenter > Permissions.
- Click Add > User Permission.
- Path: / (for access to the entire Proxmox VE instance).
- User: Select the user you created (e.g., netbox_sync_user@pam) or root@pam if you choose to use the root user.
- Role: Select PVEAuditor. This role provides read-only access to most objects.
- Click Add.
Create the API Token:
- Navigate to Datacenter > Permissions > API Tokens.
- Click Add.
- User: Select the user for whom you assigned the PVEAuditor role (e.g., netbox_sync_user@pam or root@pam).
- Token ID: Enter a descriptive name for the token (e.g., netbox_sync_token). This will be your PROXMOX_NODE_<ID_NAME>_TOKEN_NAME in the .env file or GUI settings.
- Privilege Separation: You can leave this unchecked for simplicity with the PVEAuditor role. If checked, the token would only have the permissions of the selected user minus any privileges that require a TTY (like console access), which is fine for API usage.
- Expire: Optionally, set an expiration date for the token. 0 means no expiration.
- Click Add.
Important: A window will pop up displaying the Token ID and the Secret.
- Copy the Secret immediately and store it securely. This is your PROXMOX_NODE_<ID_NAME>_TOKEN_SECRET. The secret will not be shown again.

You will use the selected User (e.g., netbox_sync_user@pam), the Token ID, and the Secret in the ProxSyncBox configuration.

Creating a NetBox API Token

To allow ProxSyncBox to interact with your NetBox instance, you need to create an API token.

Log in to your NetBox web UI.
Navigate to your User Profile:
- Click on your username in the top right corner.
- Select Profile from the dropdown menu.
Go to API Tokens:
- In your profile page, click on the API Tokens tab.
Create a New Token:
- Click the + Add a token button.
- Label (Optional but Recommended): Provide a descriptive label for the token (e.g., proxsyncbox_token).
- Expires (Optional): You can set an expiration date for the token. If left blank, the token will not expire.
- Write enabled: Ensure this box is checked if you want ProxSyncBox to create or update objects in NetBox. If you only want to read data (not typical for this tool's full functionality), you can leave it unchecked.
- Permissions: For full functionality, the token will need permissions to create, view, change, and delete various objects. You can assign specific permissions or, for simplicity during initial setup, grant broader permissions. Key areas include:
  - virtualization | virtual machine
  - virtualization | interface (for VMs)
  - virtualization | cluster
  - dcim | device
  - dcim | interface (for Devices/Nodes)
  - extras | tag
  - And any other objects ProxSyncBox might interact with (e.g., ipam | ip address if IP assignment is involved).
- Click Create.
Important: A window will display your new API token.
- Copy the token immediately and store it securely. This token will not be shown again.

You will use this token as the NETBOX_TOKEN in the ProxSyncBox configuration.

Tested Versions:

This application has been tested with NetBox version 4.3.1 and Proxmox VE version 8.4.1. Compatibility with other versions is likely but not guaranteed.

Installation

Clone the Repository:

git clone <your-repository-url>
cd ProxSyncBox

Create a Virtual Environment (Recommended):
```
python -m venv venv
```
Activate the virtual environment:
- On Windows:
```
.\venv\Scripts\activate
```
- On macOS and Linux:
```
source venv/bin/activate
```
Install Dependencies: Install the required Python packages using the provided requirements.txt file:
```
pip install -r requirements.txt
```

Proxmox API Permissions

For full functionality, including the discovery of IP addresses via the QEMU Guest Agent, the Proxmox API token used by the application needs the following permissions (or a role that includes them, such as PVEVMAdmin):

VM.Audit (to read VM configuration)
VM.Monitor (to interact with the QEMU Guest Agent, e.g., to get IPs)
Sys.Audit (to read Proxmox node information)
Other permissions may be required depending on operations (e.g., Datastore.Audit for storage information).

Configuration

The application settings are stored in a .env file in the application's root directory. You can configure the application in two ways:

1. Via the GUI

Launch the application.
Go to File > Settings.
Global Tab: Configure your NetBox URL, API Token, and the default NetBox Cluster Type name.
Proxmox Nodes Tab: Add, edit, or remove Proxmox node configurations.
- When adding/editing a node, you'll provide Proxmox connection details and specify how the node and its VMs

ProxSyncBox

Install / Use

README