### Start VM

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/design/operational-verbs.md

Starts a QEMU or LXC virtual machine.

```APIDOC
## POST /proxmox/qemu/{vmid}/start

### Description
Starts a QEMU virtual machine.

### Method
POST

### Endpoint
/proxmox/qemu/{vmid}/start

### Parameters
#### Path Parameters
- **vmid** (integer) - Required - The ID of the virtual machine to start.

## POST /proxmox/lxc/{vmid}/start

### Description
Starts an LXC virtual machine.

### Method
POST

### Endpoint
/proxmox/lxc/{vmid}/start

### Parameters
#### Path Parameters
- **vmid** (integer) - Required - The ID of the virtual machine to start.
```

--------------------------------

### Install and Enable Proxbox systemd Service

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/installation/backend-setup.md

Copy the sample service file, reload the systemd daemon, enable and start the Proxbox service, and check its status.

```bash
sudo cp -v /opt/netbox/netbox/netbox-proxbox/contrib/proxbox.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now proxbox
sudo systemctl status proxbox
```

--------------------------------

### Installation and Verification

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/proxbox_cli/README.md

Instructions on how to install and verify the Proxbox CLI.

```APIDOC
## Installation

### From the repository

```bash
pip install "netbox-proxbox[cli]"
```

### Verify

```bash
pxb --help
```
```

--------------------------------

### Install Dependencies from Requirements Files

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Alternatively, install dependencies using requirements files for specific setups.

```bash
pip install -r requirements.txt
pip install -r requirements-docs.txt
```

--------------------------------

### Install and Run Proxbox API Backend

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Set up a virtual environment, install the proxbox-api, and run the Uvicorn server.

```bash
mkdir -p /opt/proxbox-api
cd /opt/proxbox-api
python3 -m venv venv
source venv/bin/activate
pip install --upgrade proxbox-api
uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800
```

--------------------------------

### Verify CLI Installation

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/proxbox_cli/README.md

Check if the CLI is installed correctly by displaying the help menu.

```bash
pxb --help
```

--------------------------------

### Install Companion Plugins

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/companion-plugins/index.md

Install the netbox-proxbox package along with any desired companion plugins using pip.

```bash
source /opt/netbox/venv/bin/activate
pip install netbox-proxbox netbox-pbs netbox-pdm netbox-ceph netbox-packer
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Install the necessary Python packages for building documentation.

```bash
pip install -r requirements-docs.txt
```

--------------------------------

### Display VM Start at Boot Status

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/netbox_proxbox/templates/netbox_proxbox/vm_proxmox_config.html

Shows whether the VM is configured to start automatically at boot.

```html
{% trans "Start at Boot" %}

{% if normalized.start_at_boot is True %} {% trans "Enabled" %} {% elif normalized.start_at_boot is False %} {% trans "Disabled" %} {% else %} — {% endif %}
```

--------------------------------

### VM Snapshot API Examples

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/api/vm-data.md

Examples for listing, filtering, and searching VM snapshots via curl.

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?virtual_machine_id=10"
```

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?subtype=qemu&status=active"
```

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/snapshots/?q=pre-upgrade"
```

--------------------------------

### Install NetBox Proxbox Plugin via Git

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/installation/2-installing-plugin-git.md

Clone the plugin repository, install it using pip, migrate the database, collect static files, and restart NetBox. This is the recommended installation method for the latest development version.

```bash
cd /opt/netbox/netbox
git clone https://github.com/emersonfelipesp/netbox-proxbox.git

source /opt/netbox/venv/bin/activate
pip install -e /opt/netbox/netbox/netbox-proxbox

cd /opt/netbox/netbox
python3 manage.py migrate netbox_proxbox
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox
```

--------------------------------

### Install proxbox-api via pip

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/backend/using-pip.md

Creates a directory and virtual environment to install the proxbox-api package.

```bash
mkdir -p /opt/proxbox-api
cd /opt/proxbox-api
python3 -m venv venv
source venv/bin/activate
pip install --upgrade proxbox-api
```

--------------------------------

### Install Proxbox Plugin in NetBox

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Install the Proxbox plugin into the NetBox virtual environment and run migrations.

```bash
cd /opt/netbox/netbox
source venv/bin/activate
pip install -e /path/to/netbox-proxbox

# Run migrations
python manage.py migrate netbox_proxbox

# Collect static files
python manage.py collectstatic --no-input

# Restart NetBox
sudo systemctl restart netbox
```

--------------------------------

### Install netbox-pbs via git for development

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/companion-plugins/netbox-pbs.md

Installs a development build of the netbox-pbs plugin directly from its GitHub repository.

```bash
source /opt/netbox/venv/bin/activate
pip install git+https://github.com/emersonfelipesp/netbox-pbs.git
```

--------------------------------

### VM Task History API Examples

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/api/vm-data.md

Examples for listing, filtering, and searching VM task history via curl.

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?virtual_machine_id=10"
```

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?task_type=vzdump&task_state=ERROR"
```

```bash
curl -H "Authorization: Token <token>" \
     "http://netbox.example.com/api/plugins/proxbox/task-history/?q=UPID:pve-node-01"
```

--------------------------------

### Install Optional Plugins (Virtual Environment)

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/README.md

Install desired companion plugins within an activated NetBox virtual environment using pip.

```bash
source /opt/netbox/venv/bin/activate
pip install netbox-pbs netbox-pdm netbox-ceph netbox-packer
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Start a local development server to preview the documentation.

```bash
mkdocs serve
```

--------------------------------

### Start Proxbox API Manually

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/installation/backend-setup.md

Manually starts the proxbox-api service using uvicorn after installation via pip. This command binds the service to all network interfaces on port 8800.

```bash
/opt/proxbox-api/venv/bin/uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800 --app-dir /opt/proxbox-api
```

--------------------------------

### Proxmox API Routes for VM Operations

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/design/operational-verbs.md

These are the available POST and GET routes for managing QEMU and LXC virtual machines via the proxbox-api. They cover starting, stopping, snapshotting, and migrating VMs.

```http
POST /proxmox/qemu/{vmid}/start
POST /proxmox/lxc/{vmid}/start
POST /proxmox/qemu/{vmid}/stop
POST /proxmox/lxc/{vmid}/stop
POST /proxmox/qemu/{vmid}/snapshot
POST /proxmox/lxc/{vmid}/snapshot
POST /proxmox/qemu/{vmid}/migrate
POST /proxmox/lxc/{vmid}/migrate
DELETE /proxmox/qemu/{vmid}/migrate/{task_upid}
DELETE /proxmox/lxc/{vmid}/migrate/{task_upid}
GET  /proxmox/qemu/{vmid}/migrate/{task_upid}/stream
GET  /proxmox/lxc/{vmid}/migrate/{task_upid}/stream
```

--------------------------------

### Initialize CLI Configuration

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/proxbox_cli/README.md

Run the interactive setup to configure the backend URL and request timeout.

```bash
pxb init
```

--------------------------------

### Node-side Discovery User Setup Script

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/configuration/hardware-discovery.md

This script creates a dedicated user on Proxmox nodes for hardware discovery, configures SSH access with a locked-down command, and installs a dispatch script to handle specific commands.

```bash
# 1. Create the user (no shell, no home password)
adduser --disabled-password --gecos "" proxbox-discovery

# 2. Drop your proxbox-discovery ed25519 public key into authorized_keys.
#    Use the locked-down command= prefix so only the discovery script runs:
mkdir -p /home/proxbox-discovery/.ssh
cat > /home/proxbox-discovery/.ssh/authorized_keys <<'EOF'
command="/usr/local/bin/proxbox-discover",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... proxbox-discovery
EOF
chown -R proxbox-discovery:proxbox-discovery /home/proxbox-discovery/.ssh
chmod 700 /home/proxbox-discovery/.ssh
chmod 600 /home/proxbox-discovery/.ssh/authorized_keys

# 3. Install the discovery dispatch script
cat > /usr/local/bin/proxbox-discover <<'EOF'
#!/bin/sh
case "$SSH_ORIGINAL_COMMAND" in
  "dmidecode -t 1"|"dmidecode -t 3")
    sudo -n /usr/sbin/$SSH_ORIGINAL_COMMAND ;; 
  "ip -o link show")
    /usr/sbin/$SSH_ORIGINAL_COMMAND ;; 
  ethtool\ *)
    /usr/sbin/$SSH_ORIGINAL_COMMAND ;; 
  *) 
    exit 1 ;; 
esac
EOF
chmod 755 /usr/local/bin/proxbox-discover

# 4. Grant only the two dmidecode calls under sudo
cat > /etc/sudoers.d/proxbox-discovery <<'EOF'
proxbox-discovery ALL=(root) NOPASSWD: /usr/sbin/dmidecode -t 1, /usr/sbin/dmidecode -t 3
EOF
chmod 440 /etc/sudoers.d/proxbox-discovery
visudo -cf /etc/sudoers.d/proxbox-discovery
```

--------------------------------

### Clone and Set Up Proxbox API from Source

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/installation/backend-setup.md

Steps to clone the proxbox-api repository, create and activate a virtual environment, install the package in editable mode, and run Uvicorn.

```bash
cd /opt
git clone https://github.com/emersonfelipesp/proxbox-api.git
cd /opt/proxbox-api

python3 -m venv venv
source venv/bin/activate
pip install -e .

/opt/proxbox-api/venv/bin/uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800 --app-dir /opt/proxbox-api
```

--------------------------------

### Proxbox CLI Init Help

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/reference/proxbox-cli/command-examples/core-commands.md

Displays help information for the `pxb init` command, which is used for interactive configuration of the proxbox-api base URL.

```text
Usage: python -m proxbox_cli init [OPTIONS]                                    

 Interactively configure the proxbox-api base URL.                              
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
```

--------------------------------

### Initialize and Use Proxmox SDK

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/developer/component-deep-dive.md

Demonstrates initializing the ProxmoxSDK with API token authentication and performing various read operations like listing nodes, getting VM configuration, listing storage, and retrieving cluster resources. Requires async execution.

```python
from proxmox_openapi.sdk import ProxmoxSDK

sdk = ProxmoxSDK(host="192.168.1.10", port=8006, token="root@pam!mytoken=<uuid>")

# List all nodes
nodes = await sdk.nodes.get()

# Get QEMU config for VM 100 on node "pve1"
config = await sdk.nodes("pve1").qemu(100).config.get()

# List storage on a specific node
storages = await sdk.nodes("pve1").storage.get()

# Get cluster resources
resources = await sdk.cluster.resources.get()
```

--------------------------------

### Enable and Start RQ Worker Service

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/README.md

Enables the netbox-rq service to start on boot and starts it immediately if it is inactive or missing. This ensures Proxbox jobs are picked up automatically.

```bash
sudo systemctl enable --now netbox-rq
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Install pre-commit hooks to automate checks before committing code.

```bash
pre-commit install
```

--------------------------------

### Display VM Startup

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/netbox_proxbox/templates/netbox_proxbox/vm_proxmox_config.html

Shows the startup configuration for the VM.

```html
{% trans "Startup" %}

{{ normalized.startup }}
```

--------------------------------

### Install Proxbox CLI Dependencies

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/cli/index.md

Install the necessary dependencies for the Proxbox CLI using pip.

```bash
pip install "netbox-proxbox[cli]"
```

--------------------------------

### Release Notes Template Example

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/reference/IMPLEMENTATION-ROADMAP.md

Illustrates the structure and content expected in a release notes file for a new opt-in flag. It details the migration process, form/serializer updates, and backend handler information.

```markdown
IF NOT EXISTS
form / serializer / table surface
_build_base_query_params
backend handler
AST contract test
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/DEVELOP.md

Install project dependencies including development, testing, and CLI extras.

```bash
pip install -e ".[dev,test,cli]"
```

--------------------------------

### Clone and Install NetBox Proxbox Backend

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/backend/using-git.md

Clone the repository, set up a Python virtual environment, and install the backend in editable mode. This is the first step for working with the backend source.

```bash
cd /opt
git clone https://github.com/emersonfelipesp/proxbox-api.git proxbox-api
cd /opt/proxbox-api

python3 -m venv venv
source venv/bin/activate
pip install -e .
```

--------------------------------

### Install NetBox PDM from Git

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/companion-plugins/netbox-pdm.md

Installs the development version of netbox-pdm from its Git repository using pip.

```bash
source /opt/netbox/venv/bin/activate
pip install git+https://github.com/emersonfelipesp/netbox-pdm.git
```

--------------------------------

### Install netbox-pbs via pip

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/companion-plugins/netbox-pbs.md

Installs the netbox-pbs plugin using pip within a virtual environment.

```bash
source /opt/netbox/venv/bin/activate
pip install netbox-pbs
```

--------------------------------

### Initialize and Configure CLI

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/cli/index.md

Initialize the CLI configuration and view the current settings. This step is crucial for the CLI to know the location of the proxbox-api backend.

```bash
pxb init
pxb config
pxb test
```

--------------------------------

### Sync Command Options

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/cli/index.md

Examples of using the 'pxb sync run' command with different options for enqueuing sync jobs, waiting for completion, setting timeouts, and outputting JSON.

```bash
pxb sync run
pxb sync run --wait
pxb sync run --wait --timeout 600
pxb sync run --json
pxb sync run --netbox-path PATH
```

--------------------------------

### Install NetBox Proxbox Plugin via PyPI

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/installation/1-installing-plugin.md

This snippet outlines the steps to install the netbox-proxbox plugin using pip, migrate the database, collect static files, and restart the NetBox service. Ensure you are in the NetBox virtual environment before running these commands.

```bash
source /opt/netbox/venv/bin/activate
pip install netbox-proxbox

cd /opt/netbox/netbox
python3 manage.py migrate netbox_proxbox
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox
```

--------------------------------

### Install Local Dependencies

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/developer/proxmox-mock-local.md

Installs necessary Python packages for end-to-end testing, including the project in editable mode.

```bash
python -m pip install --upgrade pip
python -m pip install -e ".[e2e]"
```

--------------------------------

### Proxbox CLI Virtualization Backups Sync All Help

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/reference/proxbox-cli/command-examples/infrastructure-commands.md

Displays help information for the 'pxb virtualization vms backups-sync-all' command, a long-running process for syncing all VM backups across clusters, nodes, and storages. It can also delete stale backup records.

```text
                                                                                
 Usage: python -m proxbox_cli virtualization vms backups-sync-all               
            [OPTIONS]                                                           
                                                                                
 Sync ALL backups across all clusters/nodes/storages. [NOTE: long-running sync] 
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --delete-stale          Delete stale backup records.                         
│ --json                  Output raw JSON.                                     
│ --yaml                  Output YAML.                                         
│ --help                  Show this message and exit.                          
╰──────────────────────────────────────────────────────────────────────────────╯

```

--------------------------------

### Install NetBox PDM with pip

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/companion-plugins/netbox-pdm.md

Installs netbox-pbs and netbox-pdm using pip after activating the NetBox virtual environment.

```bash
source /opt/netbox/venv/bin/activate
pip install netbox-pbs netbox-pdm
```

--------------------------------

### Run Proxbox API with Uvicorn

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/FASTAPI.md

Starts the backend service using the Uvicorn ASGI server.

```bash
uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800
```

--------------------------------

### Proxbox CLI Virtualization VMs Snapshots Sync All Help

Source: https://github.com/emersonfelipesp/netbox-proxbox/blob/develop/docs/reference/proxbox-cli/command-examples/infrastructure-commands.md

Displays help information for the long-running command that synchronizes all VM snapshots across clusters and nodes.

```text
                                                                                
 Usage: python -m proxbox_cli virtualization vms snapshots-sync-all             
            [OPTIONS]                                                           
                                                                                
 Sync ALL VM snapshots across all clusters/nodes. [NOTE: long-running sync]     
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json          Output raw JSON.                                             
│ --yaml          Output YAML.                                                 
│ --help          Show this message and exit.                                  
╰──────────────────────────────────────────────────────────────────────────────╯

```