Data Model¶

This page documents all persisted models in the Proxbox ecosystem — the Django plugin models stored in NetBox's PostgreSQL database, and the SQLite models used by proxbox-api.

Plugin Models (NetBox PostgreSQL)¶

The netbox-proxbox plugin defines 13 Django models. They inherit from NetBoxModel (which provides tags, custom_fields, timestamps, and ObjectChange tracking) or from NetBoxModel through EndpointBase.

Entity Relationship Diagram¶

erDiagram
    ProxmoxEndpoint {
        int     id
        string  name
        string  domain
        int     port
        string  mode
        string  username
        string  token_name
        string  token_value
        string  version
        fk      ip_address
    }
    NetBoxEndpoint {
        int     id
        string  name
        string  domain
        int     port
        string  token_version
        string  token_name
        string  token_secret
        string  token_key
    }
    FastAPIEndpoint {
        int     id
        string  name
        string  domain
        int     port
        string  backend_token
        bool    verify_ssl
        string  websocket_url
    }
    ProxmoxCluster {
        int     id
        string  name
        fk      proxmox_endpoint
        fk      netbox_cluster
    }
    ProxmoxNode {
        int     id
        string  name
        fk      proxmox_endpoint
        fk      netbox_device
        fk      proxmox_cluster
    }
    ProxmoxStorage {
        int     id
        string  name
        string  storage_type
        string  path
        fk      proxmox_endpoint
    }
    ProxmoxStorageVirtualDisk {
        int     id
        fk      proxmox_storage
        fk      virtual_disk
    }
    BackupRoutine {
        int     id
        string  name
        string  vmid
        fk      proxmox_endpoint
    }
    Replication {
        int     id
        string  name
        string  vmid
        fk      proxmox_endpoint
    }
    VMBackup {
        int     id
        string  volid
        string  format
        string  size
        fk      virtual_machine
    }
    VMSnapshot {
        int     id
        string  name
        string  description
        fk      virtual_machine
    }
    VMTaskHistory {
        int     id
        string  upid
        string  status
        string  type
        fk      virtual_machine
    }
    ProxboxPluginSettings {
        int     id
        bool    sync_enabled
        string  sync_interval
    }

    ProxmoxEndpoint ||--o{ ProxmoxCluster : "has"
    ProxmoxEndpoint ||--o{ ProxmoxNode : "has"
    ProxmoxEndpoint ||--o{ ProxmoxStorage : "has"
    ProxmoxEndpoint ||--o{ BackupRoutine : "has"
    ProxmoxEndpoint ||--o{ Replication : "has"
    ProxmoxCluster ||--o{ ProxmoxNode : "contains"
    ProxmoxStorage ||--o{ ProxmoxStorageVirtualDisk : "links"

NetBox core relationships — Plugin models link to standard NetBox objects via foreign keys:

ProxmoxCluster.netbox_cluster → virtualization.Cluster

ProxmoxNode.netbox_device → dcim.Device

VMBackup.virtual_machine → virtualization.VirtualMachine

VMSnapshot.virtual_machine → virtualization.VirtualMachine

VMTaskHistory.virtual_machine → virtualization.VirtualMachine

ProxmoxEndpoint.ip_address → ipam.IPAddress

VM-Centric Models¶

erDiagram
    VirtualMachine["virtualization.VirtualMachine\n(NetBox core)"] {
        int    id
        string name
        fk     cluster
    }
    VMBackup {
        int    id
        string volid
        string format
        string size
        string notes
    }
    VMSnapshot {
        int    id
        string name
        string description
        string parent
    }
    VMTaskHistory {
        int    id
        string upid
        string status
        string type
        string exitstatus
    }

    VirtualMachine ||--o{ VMBackup : "has backups"
    VirtualMachine ||--o{ VMSnapshot : "has snapshots"
    VirtualMachine ||--o{ VMTaskHistory : "has task history"

Model Summary Tables¶

Endpoint Models¶

Model	Key Fields	Purpose
`ProxmoxEndpoint`	domain, port (8006), username, token_name, token_value, mode, version	Credentials and address for one Proxmox VE instance or cluster
`NetBoxEndpoint`	domain, port (8000), token_version (v1/v2), token_name, token_secret, token_key	Address and credentials for a remote NetBox instance
`FastAPIEndpoint`	domain, port (8000), backend_token, verify_ssl, websocket_url	Address and auth token for the `proxbox-api` backend

Single FastAPIEndpoint constraint

The plugin's HTTP and WebSocket helpers resolve the backend via FastAPIEndpoint.objects.first(). If multiple FastAPIEndpoint rows exist, whichever sorts first in the queryset is used for all backend communication. Keep exactly one row in production.

Infrastructure Models¶

Model	FK to	Purpose
`ProxmoxCluster`	`ProxmoxEndpoint`, `Cluster` (NetBox core)	Mirrors a Proxmox cluster into a NetBox Cluster object
`ProxmoxNode`	`ProxmoxEndpoint`, `Device` (NetBox core), `ProxmoxCluster`	Mirrors a Proxmox hypervisor node into a NetBox Device
`ProxmoxStorage`	`ProxmoxEndpoint`	Inventory of storage pools/directories on a Proxmox cluster
`ProxmoxStorageVirtualDisk`	`ProxmoxStorage`, `VirtualDisk` (NetBox core)	Join table linking storage entries to NetBox virtual disk objects

VM Data Models¶

Model	FK to	Purpose
`VMBackup`	`VirtualMachine` (NetBox core)	Per-VM backup inventory (volid, format, size)
`VMSnapshot`	`VirtualMachine` (NetBox core)	Per-VM snapshot inventory (name, description, parent)
`VMTaskHistory`	`VirtualMachine` (NetBox core)	Per-VM task history from the Proxmox task log (UPID, status, type)

Operational Models¶

Model	Purpose
`BackupRoutine`	Backup routine definitions synced from Proxmox (vzdump jobs)
`Replication`	Replication job definitions synced from Proxmox
`ProxboxPluginSettings`	Singleton plugin settings (sync scheduling, feature flags)

proxbox-api SQLite Models¶

The proxbox-api backend stores its own configuration in a local SQLite database (database.db). These models are managed by SQLModel and are separate from the NetBox database.

erDiagram
    NetBoxEndpoint_BE["NetBoxEndpoint\n(SQLite)"] {
        int     id
        string  url
        string  token_version
        string  token
        string  token_key
        bool    verify_ssl
    }
    ProxmoxEndpoint_BE["ProxmoxEndpoint\n(SQLite)"] {
        int     id
        string  url
        string  token
        string  username
        bool    verify_ssl
        string  cluster_name
    }
    ApiKey {
        int     id
        string  key_hash
        string  description
        datetime created_at
    }
    AuthLockout {
        string  ip
        int     attempts
        datetime last_attempt
    }

Two NetBoxEndpoint concepts

The NetBoxEndpoint in the NetBox plugin (PostgreSQL) stores the remote NetBox address from the plugin's perspective. The NetBoxEndpoint in proxbox-api's SQLite stores the same information from the backend's perspective. They are kept in sync via Django signals and the FastAPIEndpoint.signals auto-registration flow.

SQLite Model Purpose¶

Model	Purpose
`NetBoxEndpoint` (SQLite)	NetBox connection details used by the FastAPI session layer
`ProxmoxEndpoint` (SQLite)	Proxmox connection details used by the FastAPI session layer
`ApiKey`	bcrypt-hashed API keys for `X-Proxbox-API-Key` authentication
`AuthLockout`	IP-based brute-force lockout tracking (5 attempts, 300 s lock)