PegaProx

https://docs.pegaprox.com/
Admin
PegaProx is an open-source centralized management platform for Proxmox VE and XCP-ng clusters,...
Tokens:57,608
Snippets:585
Trust Score:4.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start a VM

Source: https://docs.pegaprox.com/

Starts a virtual machine on a specified cluster.

```APIDOC
## Start a VM

### Description
Starts a virtual machine on a specified cluster.

### Method
POST

### Endpoint
/api/clusters/{id}/vms/{node}/qemu/{vmid}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **node** (string) - Required - The node where the VM is located.
- **vmid** (integer) - Required - The ID of the virtual machine.

### Request Example
```bash
curl -s -X POST https://pegaprox.local:5000/api/clusters/c1a2b3/vms/pve1/qemu/100/start \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **upid** (string) - Unique Process ID for the VM operation.

### Response Example
```json
{"message": "VM started", "upid": "UPID:pve1:000F4A2B:01E3AC40:65D8F1A0:qmstart:100:root@pam:"}
```
```

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

### Manual PegaProx Installation

Source: https://docs.pegaprox.com/

Steps for manually installing PegaProx, involving cloning the repository, installing Python dependencies, and starting the server. Ensure you have Python 3 installed.

```bash
# Clone the repository
git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox

# Install Python dependencies
pip install -r requirements.txt

# Start the server
python3 pegaprox_multi_cluster.py
```

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

### Start a VM

Source: https://docs.pegaprox.com/

Starts a specific virtual machine on a given cluster. Requires a Bearer token and the cluster ID, VM type, and VM ID.

```bash
curl -s -X POST https://pegaprox.local:5000/api/clusters/c1a2b3/vms/pve1/qemu/100/start \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json
{"message": "VM started", "upid": "UPID:pve1:000F4A2B:01E3AC40:65D8F1A0:qmstart:100:root@pam:"}
```

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

### Install QEMU Guest Agent

Source: https://docs.pegaprox.com/

Install the QEMU Guest Agent on Debian/Ubuntu or RHEL/CentOS systems to enable enhanced VM visibility and control features.

```bash
# Debian/Ubuntu
sudo apt install -y qemu-guest-agent && sudo systemctl enable --now qemu-guest-agent

# RHEL/CentOS
sudo yum install -y qemu-guest-agent && sudo systemctl enable --now qemu-guest-agent
```

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

### Full Example Plugin Implementation

Source: https://docs.pegaprox.com/

This example demonstrates route registration, accessing cluster managers, querying the database, and utilizing request context within a PegaProx plugin. All plugin routes are automatically protected by authentication.

```python
# plugins/hello_world/__init__.py
"""
Hello World Plugin - Example plugin for PegaProx
All plugin routes are automatically protected by authentication.
"""
import logging
from flask import request
from pegaprox.api.plugins import register_plugin_route
from pegaprox.globals import cluster_managers
from pegaprox.core.db import get_db

PLUGIN_NAME = "Hello World"

def _get_status():
    """Route handler: returns plugin status + connected cluster count"""
    # Access cluster managers (same API as core PegaProx)
    connected = sum(1 for m in cluster_managers.values() if m.is_connected)
    total = len(cluster_managers)

    # Access request context (user info from auth)
    user = getattr(request, 'session', {}).get('user', 'unknown')

    return {
        'plugin': 'hello_world',
        'status': 'running',
        'authenticated_user': user,
        'clusters': {'connected': connected, 'total': total}
    }

def _get_info():
    """Route handler: returns plugin metadata"""
    return {
        'name': PLUGIN_NAME,
        'version': '1.0.0',
        'routes': ['status', 'info']
    }

def register(app):
    """Called by PegaProx when the plugin is enabled."""
    register_plugin_route('hello_world', 'status', _get_status)
    register_plugin_route('hello_world', 'info', _get_info)
    logging.info("[PLUGINS] Hello World plugin registered")

```

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

### Automated PegaProx Installation

Source: https://docs.pegaprox.com/

Use this command to automatically install PegaProx, including dependencies, SSL, and systemd service setup. It's the recommended installation method.

```bash
curl -sSL https://raw.githubusercontent.com/PegaProx/project-pegaprox/refs/heads/main/deploy.sh | sudo bash
```

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

### Start Cross-Hypervisor Migration

Source: https://docs.pegaprox.com/

Initiates the cross-hypervisor migration process for a virtual machine.

```APIDOC
## POST /api/xhm/migrate

### Description
Starts the cross-hypervisor migration process.

### Method
POST

### Endpoint
/api/xhm/migrate

### Parameters
#### Request Body
- **source_cluster** (string) - Required - The source cluster identifier.
- **source_vmid** (string) - Required - The ID of the virtual machine to migrate.
- **target_cluster** (string) - Required - The target cluster identifier.
- **target_storage_pool** (string) - Optional - The target storage pool identifier.
- **source_node** (string) - Optional - The source node identifier (required for Proxmox VE to XCP-ng migrations).
```

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

### Hourly Replication Schedule Example

Source: https://docs.pegaprox.com/

Example of a cron syntax for scheduling replication jobs to run every hour. Ensure your RPO (Recovery Point Objective) aligns with this frequency.

```cron
0 * * * *
```

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

### Create Pool Example

Source: https://docs.pegaprox.com/

Example cURL command for creating a Ceph pool via the API.

```APIDOC
## Creating a Pool via API

```bash
curl -X POST https://pegaprox.local:5000/api/clusters/{id}/ceph/pools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "vm-pool", "size": 3, "pg_num": 128}'
```

`size` = replication factor (3 copies). Adjust `pg_num` based on OSD count (~100 PGs per OSD per pool).
```

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

### Daily Replication Schedule Example

Source: https://docs.pegaprox.com/

Example of a cron syntax for scheduling replication jobs to run once daily at 2 AM. This is typically used for backups or non-critical data replication.

```cron
0 2 * * *
```

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

### Cron-like Scheduling Examples

Source: https://docs.pegaprox.com/

Illustrates various scheduling patterns supported by PegaProx, including daily, weekly, and custom time-based executions.

```text
once: 2026-04-15 03:00
daily: 02:30
weekly: Monday, Thursday at 04:00
weekdays: 06:00
weekends: 08:00
```

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

### List all VMs in a cluster

Source: https://docs.pegaprox.com/

This example demonstrates how to list all VMs within a specific cluster using an API token. Ensure your token has the necessary permissions.

```APIDOC
## GET /api/clusters/{cluster_id}/vms

### Description
Retrieves a list of all virtual machines within a specified cluster.

### Method
GET

### Endpoint
/api/clusters/{cluster_id}/vms

### Parameters
#### Path Parameters
- **cluster_id** (string) - Required - The unique identifier of the cluster.

#### Request Example
```bash
curl -H "Authorization: Bearer <your-token>" \
  https://pegaprox.example.com:5000/api/clusters/my-cluster/vms
```

### Response
#### Success Response (200)
- **vms** (array) - A list of VM objects.
  - **vm_id** (string) - The unique identifier of the VM.
  - **name** (string) - The name of the VM.
  - **status** (string) - The current status of the VM (e.g., running, stopped).

#### Response Example
```json
{
  "vms": [
    {
      "vm_id": "vm-123",
      "name": "web-server-01",
      "status": "running"
    },
    {
      "vm_id": "vm-456",
      "name": "db-server-01",
      "status": "stopped"
    }
  ]
}
```
```

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

### 4-Hour Replication Schedule Example

Source: https://docs.pegaprox.com/

Example of a cron syntax for scheduling replication jobs to run every 4 hours. This is suitable for less critical data where a longer RPO is acceptable.

```cron
0 */4 * * *
```

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

### Example Production Environment Variables

Source: https://docs.pegaprox.com/

Set these environment variables in a file like /etc/default/pegaprox for production deployments to configure server port, API rate limits, and SSH session concurrency.

```bash
# /etc/default/pegaprox
PEGAPROX_PORT=5000
PEGAPROX_API_RATE_LIMIT=2400
PEGAPROX_SSH_MAX_CONCURRENT=50
```

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

### Start Migration Job

Source: https://docs.pegaprox.com/

Initiates a virtual machine migration job from the source ESXi host to the Proxmox target. Supports various migration modes and VirtIO injection.

```APIDOC
## POST /api/v2p/migrate

### Description
Start a virtual machine migration job.

### Method
POST

### Endpoint
/api/v2p/migrate

### Parameters
#### Request Body
- **mode** (string) - Required - The migration mode. Options: `auto`, `sshfs_boot`, `offline`, `snapshot_zero`.
- **virtio_inject** (boolean) - Required - Whether to inject VirtIO drivers into the guest.
```

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

### Run PegaProx with Docker

Source: https://docs.pegaprox.com/

Quickly start PegaProx using a single Docker command. Ensure to change the default password after the first login.

```bash
docker run -d --name pegaprox \
  -p 5000:5000 -p 5001:5001 -p 5002:5002 \
  -v pegaprox-config:/app/config \
  -v pegaprox-logs:/app/logs \
  --restart unless-stopped \
  ghcr.io/pegaprox/pegaprox:latest
```

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

### Start PegaProx with Debug Logging

Source: https://docs.pegaprox.com/

Enable debug logging for PegaProx to diagnose issues. This can be done directly via the command line or through systemd.

```bash
# Start with debug logging
python3 pegaprox_multi_cluster.py --debug
```

```bash
# Or via systemd
sudo systemctl stop pegaprox
sudo -u pegaprox python3 /opt/PegaProx/pegaprox_multi_cluster.py --debug
```

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

### VM and Container Management Endpoints

Source: https://docs.pegaprox.com/

Endpoints for managing Virtual Machines (VMs) and Containers (CTs), including starting, stopping, restarting, cloning, and deleting them.

```APIDOC
## GET /api/clusters/<id>/vms

### Description
Lists all VMs and CTs within a specific cluster.

### Method
GET

### Endpoint
/api/clusters/<id>/vms

## POST /api/clusters/<id>/vms/<vmid>/start

### Description
Starts a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/start

## POST /api/clusters/<id>/vms/<vmid>/stop

### Description
Stops a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/stop

## POST /api/clusters/<id>/vms/<vmid>/restart

### Description
Restarts a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/restart

## POST /api/clusters/<id>/vms/<vmid>/shutdown

### Description
Performs an ACPI shutdown on a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/shutdown

## POST /api/clusters/<id>/vms/<vmid>/clone

### Description
Clones a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/clone

## DELETE /api/clusters/<id>/vms/<vmid>

### Description
Deletes a specific VM or CT.

### Method
DELETE

### Endpoint
/api/clusters/<id>/vms/<vmid>

## POST /api/clusters/<id>/vms/<vmid>/migrate

### Description
Migrates a specific VM or CT.

### Method
POST

### Endpoint
/api/clusters/<id>/vms/<vmid>/migrate

## GET /api/clusters/<id>/vms/<vmid>/config

### Description
Retrieves the configuration of a specific VM or CT.

### Method
GET

### Endpoint
/api/clusters/<id>/vms/<vmid>/config

## PUT /api/clusters/<id>/vms/<vmid>/config

### Description
Updates the configuration of a specific VM or CT.

### Method
PUT

### Endpoint
/api/clusters/<id>/vms/<vmid>/config
```

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

### PWA + Web Push Notifications API

Source: https://docs.pegaprox.com/

Manage PWA installation and web push notification subscriptions.

```APIDOC
## GET /api/push/vapid-public-key

### Description
Retrieve the public VAPID key for use in the service worker's subscribe() call.

### Method
GET

### Endpoint
/api/push/vapid-public-key
```

```APIDOC
## POST /api/push/subscribe

### Description
Register the browser endpoint and associated keys for receiving web push notifications.

### Method
POST

### Endpoint
/api/push/subscribe

### Request Body
- **endpoint** (string) - Required - The browser endpoint for push notifications.
- **p256dh** (string) - Required - The P256dh encryption key.
- **auth** (string) - Required - The authentication secret.
```

```APIDOC
## DELETE /api/push/subscribe

### Description
Revoke the current subscription for web push notifications.

### Method
DELETE

### Endpoint
/api/push/subscribe
```

```APIDOC
## POST /api/push/test

### Description
Send a test web push notification to the caller's registered subscriptions.

### Method
POST

### Endpoint
/api/push/test
```

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

### Proxmox API Token Creation Command

Source: https://docs.pegaprox.com/

Example of how to format a Proxmox API token for use with PegaProx. Ensure 'Privilege Separation' is unchecked in Proxmox for full access. This token format is required for PegaProx authentication.

```bash
user@realm!tokenid=secret-value
```

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

### Build Frontend Application

Source: https://docs.pegaprox.com/

Execute this command to build the frontend SPA. It concatenates JavaScript files, transpiles JSX, and injects the output into the HTML shell.

```bash
cd web/Dev
bash build.sh
```

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

### Create Plugin Directory

Source: https://docs.pegaprox.com/

Create a new directory for your plugin within the `plugins/` folder. Plugin names should be lowercase and contain no spaces.

```bash
mkdir -p plugins/my_plugin
```

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

### Get WebSocket Auth Token

Source: https://docs.pegaprox.com/

Obtains an authentication token for WebSocket connections.

```APIDOC
## Get WebSocket Auth Token

### Description
Obtains an authentication token for WebSocket connections.

### Method
POST

### Endpoint
/api/ws/token
```

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

### Get Migration Status

Source: https://docs.pegaprox.com/

Retrieves the status and progress of a specific cross-hypervisor migration.

```APIDOC
## GET /api/xhm/migrations/{id}

### Description
Gets the status and progress of a specific migration.

### Method
GET

### Endpoint
/api/xhm/migrations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the migration.
```

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

### Get SSE Auth Token

Source: https://docs.pegaprox.com/

Obtains an authentication token for Server-Sent Events (SSE).

```APIDOC
## Get SSE Auth Token

### Description
Obtains an authentication token for Server-Sent Events (SSE).

### Method
POST

### Endpoint
/api/sse/token
```

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

### Define Plugin Metadata

Source: https://docs.pegaprox.com/

Create a `manifest.json` file to define your plugin's metadata, including its ID, name, version, author, description, and minimum PegaProx version.

```json
{
    "id": "my_plugin",
    "name": "My Plugin",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "What this plugin does",
    "min_pegaprox": "0.9.3"
}
```

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

### Get Metrics

Source: https://docs.pegaprox.com/

Exposes PegaProx internal metrics in OpenMetrics / Prometheus exposition format.

```APIDOC
## GET /api/metrics

### Description
Exposes PegaProx internal metrics in OpenMetrics / Prometheus exposition format for scraping by monitoring systems.

### Method
GET

### Endpoint
/api/metrics

### Auth
Requires an API token. Use either `Authorization: Bearer <token>` header, Basic auth (token as password), or unauthenticated access if explicitly enabled in settings for trusted networks.
```

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

### Enable a Plugin

Source: https://docs.pegaprox.com/

Enables and immediately loads a specified plugin. This action does not require a server restart.

```APIDOC
## POST /api/plugins/{id}/enable

### Description
Enables and immediately loads a plugin. The plugin's routes become available without needing to restart the server.

### Method
POST

### Endpoint
/api/plugins/{id}/enable

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the plugin to enable.

### Permissions
`plugins.manage`
```

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

### Get Notification Config

Source: https://docs.pegaprox.com/

Retrieves the current configuration for push notifications. This endpoint is restricted to administrators.

```APIDOC
## GET /api/plugins/notifications/api/config

### Description
Get the current configuration for push notifications. This endpoint is intended for administrative use only.

### Method
GET

### Endpoint
/api/plugins/notifications/api/config
```

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

### Get Job Status

Source: https://docs.pegaprox.com/

Retrieves the status of a specific migration job, including progress for each phase.

```APIDOC
## GET /api/v2p/jobs/{id}

### Description
Get the status of a migration job by its ID.

### Method
GET

### Endpoint
/api/v2p/jobs/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the migration job.
```

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

### Cloud-Init Template Library API

Source: https://docs.pegaprox.com/

Manage and deploy cloud-init templates.

```APIDOC
## GET /api/templates-lib

### Description
Retrieve the catalog of curated and custom cloud-init template entries.

### Method
GET

### Endpoint
/api/templates-lib
```

```APIDOC
## POST /api/templates-lib/deploy

### Description
Deploy a cloud-init template to a specified cluster, node, and storage.

### Method
POST

### Endpoint
/api/templates-lib/deploy

### Request Body
- **catalog_id** (string) - Required - The ID of the catalog entry to deploy.
- **image_url** (string) - Required - The URL of the image to deploy (used if catalog_id is not provided).
- **checksum** (string) - Required - The checksum of the image.
- **cluster** (string) - Required - The target cluster.
- **node** (string) - Required - The target node.
- **storage** (string) - Required - The target storage.
- **vmid** (integer) - Required - The VM ID to assign.
- **name** (string) - Required - The name for the new template.
```

```APIDOC
## GET /api/templates-lib/recent

### Description
Retrieve a list of recent cloud-init template deployments for the current cluster.

### Method
GET

### Endpoint
/api/templates-lib/recent
```

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

### Get HA Status for a Cluster

Source: https://docs.pegaprox.com/

Retrieves the High Availability status and heartbeat information for a specified cluster.

```APIDOC
## GET /api/clusters/{id}/ha/status

### Description
Retrieves the High Availability status and heartbeat information for a specified cluster.

### Method
GET

### Endpoint
/api/clusters/{id}/ha/status

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the cluster.
```

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

### Get RBD Mirroring Status

Source: https://docs.pegaprox.com/

Retrieves the status of RBD mirroring and lists configured mirror peers.

```APIDOC
## GET /api/clusters/{id}/ceph/mirroring

### Description
Retrieves the status of RBD mirroring and lists configured mirror peers.

### Method
GET

### Endpoint
/api/clusters/{id}/ceph/mirroring
```

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

### Restore QEMU VM Image

Source: https://docs.pegaprox.com/

Command to restore a QEMU virtual machine from a backup file using the PegaProx CLI. Specify the VM ID, backup file path, and target storage.

```bash
# For QEMU VM:
qmrestore /var/lib/vz/dump/<backup-file>.vma.zst <VMID> --storage local-lvm
```

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

### Get Portal Configuration

Source: https://docs.pegaprox.com/

Retrieves the public configuration settings for the client portal. This endpoint does not contain sensitive information.

```APIDOC
## GET /api/plugins/client_portal/api/config

### Description
Retrieves the public configuration settings for the client portal.

### Method
GET

### Endpoint
/api/plugins/client_portal/api/config

### Response
#### Success Response (200)
- **portal_title** (string) - The title displayed in the portal header and login page.
- **allowed_actions** (array) - List of actions customers can perform on VMs.
- **allow_snapshots** (boolean) - Whether snapshot management is enabled.
- **max_snapshots_per_vm** (integer) - Maximum snapshots allowed per VM.
- **allow_password_change** (boolean) - Whether customers can change their password.
- **show_resource_usage** (boolean) - Whether to show resource usage on VM cards.
- **show_ip_addresses** (boolean) - Whether to show VM IP addresses.
- **theme_color** (string) - Accent color for the portal UI.
- **custom_logo_url** (string) - URL for a custom logo.
```

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

### Create VM Snapshot

Source: https://docs.pegaprox.com/

Creates a new snapshot for a specified virtual machine.

```APIDOC
## POST /api/plugins/client_portal/api/vm/snapshots

### Description
Creates a snapshot for a virtual machine.

### Method
POST

### Endpoint
/api/plugins/client_portal/api/vm/snapshots

### Parameters
#### Request Body
- **vm_id** (string) - Required - The ID of the virtual machine.
- **name** (string) - Optional - A name for the snapshot.
```

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

### Get Ceph Cluster Status

Source: https://docs.pegaprox.com/

Retrieves the overall status, health, PG states, and capacity of the Ceph cluster.

```APIDOC
## GET /api/clusters/{id}/ceph/status

### Description
Retrieves the overall status, health, PG states, and capacity of the Ceph cluster.

### Method
GET

### Endpoint
/api/clusters/{id}/ceph/status
```

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

### Download Static Assets for Offline Use

Source: https://docs.pegaprox.com/

Use this command to download all necessary JavaScript and CSS libraries for PegaProx to function in an offline environment. This ensures all front-end assets are available locally.

```bash
# Download static assets for offline use
python3 pegaprox_multi_cluster.py --download-static
```

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

### Control VM Power State

Source: https://docs.pegaprox.com/

Allows starting, stopping, shutting down, or rebooting a virtual machine. Requires the VM's ID.

```APIDOC
## POST /api/plugins/client_portal/api/vm/power

### Description
Starts, stops, shuts down, or reboots a virtual machine.

### Method
POST

### Endpoint
/api/plugins/client_portal/api/vm/power

### Parameters
#### Request Body
- **vm_id** (string) - Required - The ID of the virtual machine.
- **action** (string) - Required - The power action to perform (e.g., "start", "stop", "shutdown", "reboot").
```

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

### Generate Migration Plan

Source: https://docs.pegaprox.com/

Analyzes the source VM's configuration and generates a migration plan with translated hardware settings for the target hypervisor.

```APIDOC
## GET /api/xhm/plan

### Description
Generates a migration plan for cross-hypervisor VM migration.

### Method
GET

### Endpoint
/api/xhm/plan

### Parameters
#### Query Parameters
- **source_cluster** (string) - Required - The source cluster identifier.
- **source_vmid** (string) - Required - The ID of the virtual machine to migrate.
- **target_cluster** (string) - Required - The target cluster identifier.
```

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

### List All VMs via API Token

Source: https://docs.pegaprox.com/

Use an API token with the Authorization header to list all VMs in a cluster. Ensure the token is kept secure and not committed to version control.

```bash
# With Authorization header
curl -H "Authorization: Bearer <your-token>" \
  https://pegaprox.example.com:5000/api/clusters

# Example: List all VMs
curl -H "Authorization: Bearer abc123..." \
  https://pegaprox.example.com:5000/api/clusters/my-cluster/vms
```

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

### Get Ceph Health Checks

Source: https://docs.pegaprox.com/

Fetches detailed health checks and lists any active warnings or errors within the Ceph cluster.

```APIDOC
## GET /api/clusters/{id}/ceph/health

### Description
Fetches detailed health checks and lists any active warnings or errors within the Ceph cluster.

### Method
GET

### Endpoint
/api/clusters/{id}/ceph/health
```

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

### Proxmox User Permissions for PegaProx

Source: https://docs.pegaprox.com/

Demonstrates how to create a dedicated PAM user and grant it administrator privileges on Proxmox. This is an alternative to using 'root@pam' for enhanced security.

```bash
# On the Proxmox host:
# 1. Create Linux user
useradd -m pegaprox
passwd pegaprox

# 2. Grant sudo access (needed for some features)
echo "pegaprox ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/pegaprox

# 3. Add to Proxmox with Administrator role
pveum useradd pegaprox@pam -comment "PegaProx Service Account"
pveum aclmod / -user pegaprox@pam -role Administrator

# 4. Optional: Create API token
pveum user token add pegaprox@pam pegaprox --privsep=0
```

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

### Get VM Console Access

Source: https://docs.pegaprox.com/

Retrieves credentials for accessing the VNC console of a virtual machine, along with a WebSocket token for real-time interaction.

```APIDOC
## GET /api/plugins/client_portal/api/vm/console

### Description
Gets VNC console ticket and WebSocket token for a virtual machine.

### Method
GET

### Endpoint
/api/plugins/client_portal/api/vm/console

### Parameters
#### Query Parameters
- **vm_id** (string) - Required - The ID of the virtual machine.

### Response
#### Success Response (200)
- **vnc_ticket** (string) - The VNC ticket for console access.
- **websocket_token** (string) - The token for WebSocket connection.
```

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

### Connect to ESXi Host

Source: https://docs.pegaprox.com/

Establishes a connection to the VMware ESXi host. Requires host address, username, and password.

```APIDOC
## POST /api/v2p/connect

### Description
Connect to an ESXi host using provided credentials.

### Method
POST

### Endpoint
/api/v2p/connect

### Parameters
#### Request Body
- **host** (string) - Required - The hostname or IP address of the ESXi host.
- **user** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
```

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

### Network Interface Configuration

Source: https://docs.pegaprox.com/

Commands to configure a static IP address for the PegaProx instance. Use `nano` to edit the interfaces file or `nmtui` for an interactive text-based interface.

```bash
# Edit network interfaces
nano /etc/network/interfaces
# Or use interactive TUI
nmtui
```

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

### Revoke an API Token

Source: https://docs.pegaprox.com/

This example shows how to revoke an existing API token using its ID. This action requires administrative privileges or ownership of the token.

```APIDOC
## DELETE /api/user/api-tokens/{token_id}

### Description
Revokes a specific API token, rendering it unusable for future authentication.

### Method
DELETE

### Endpoint
/api/user/api-tokens/{token_id}

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The unique identifier of the API token to revoke.

#### Request Example
```bash
curl -X DELETE -H "Authorization: Bearer <admin-token>" \
  https://pegaprox:5000/api/user/api-tokens/{token_id}
```

### Response
#### Success Response (204)
No Content. The token has been successfully revoked.
```

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

### Build PegaProx Locally

Source: https://docs.pegaprox.com/

Build the PegaProx Docker image from source and run it locally. This is useful for development or testing custom builds.

```bash
git clone https://github.com/PegaProx/project-pegaprox.git
cd project-pegaprox
docker build -t pegaprox .
docker run -d --name pegaprox \
  -p 5000:5000 -p 5001:5001 -p 5002:5002 \
  -v pegaprox-config:/app/config \
  -v pegaprox-logs:/app/logs \
  --restart unless-stopped \
  pegaprox
```

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

### PegaProx CLI Options

Source: https://docs.pegaprox.com/

Lists available command-line options for running the PegaProx script. Use these to configure debug mode, server port, host, and other operational parameters.

```bash
python3 pegaprox_multi_cluster.py [OPTIONS]

Options:
  --debug               Enable debug mode with verbose logging
  --port PORT           Set the server port (default: 5000)
  --host HOST           Set the bind address (default: 0.0.0.0)
  --requirements        Install/update Python dependencies
  --download-static     Download static assets for offline mode
  --help                Show help message
```

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

### CIS Hardening Audit Categories

Source: https://docs.pegaprox.com/

Lists the categories and example checks evaluated during a CIS hardening audit in PegaProx, highlighting areas for security improvement.

```text
Category| Controls| Example Checks  
---|---|---  
SSH| 5| Root login, protocol v2, max auth tries, idle timeout, strong ciphers  
Kernel / sysctl| 6| IP forwarding, SYN cookies, ICMP redirects, ASLR, core dumps  
Filesystem| 4| /tmp noexec, sticky bit, USB storage disabled  
Authentication| 4| Password max age, min length, lockout, no empty passwords  
Logging| 4| rsyslog active, log permissions, remote logging, auditd  
AppArmor| 3| Loaded, profiles enforcing, no unconfined processes  
Network| 3| Unused protocols disabled, TCP wrappers, firewall active  
Services| 3| No legacy services, NTP sync, unneeded services disabled  
```

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

### Update PegaProx using Git Pull

Source: https://docs.pegaprox.com/

Manual update method using Git. This involves pulling the latest code, installing dependencies, and restarting the PegaProx service.

```bash
cd /opt/PegaProx
git pull origin main
pip install -r requirements.txt
sudo systemctl restart pegaprox
```

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

### Create Site Recovery Plan

Source: https://docs.pegaprox.com/

Creates a new site recovery plan. Requires a Bearer token and a JSON payload specifying the plan name and source/target clusters.

```bash
curl -s -X POST https://pegaprox.local:5000/api/site-recovery/plans \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "DR Plan", "source_cluster": "prod-01", "target_cluster": "dr-01"}'
```

```json
{"id": "a1b2c3", "message": "Plan created"}
```

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

### ESXi Migration API

Source: https://docs.pegaprox.com/

Endpoints for migrating virtual machines from ESXi.

```APIDOC
## POST /api/esxi/connectConnect to ESXi host

### Description
Establishes a connection to an ESXi host.

### Method
POST

### Endpoint
/api/esxi/connect

## GET /api/esxi/vmsList ESXi VMs

### Description
Retrieves a list of virtual machines from an ESXi host.

### Method
GET

### Endpoint
/api/esxi/vms

## POST /api/esxi/migrateStart migration

### Description
Initiates a virtual machine migration from ESXi.

### Method
POST

### Endpoint
/api/esxi/migrate

## GET /api/esxi/migrate/statusMigration status

### Description
Retrieves the status of an ongoing migration.

### Method
GET

### Endpoint
/api/esxi/migrate/status
```

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

### List VM Snapshots

Source: https://docs.pegaprox.com/

Retrieves a list of all available snapshots for a specified virtual machine.

```APIDOC
## GET /api/plugins/client_portal/api/vm/snapshots

### Description
Lists all snapshots for a given virtual machine.

### Method
GET

### Endpoint
/api/plugins/client_portal/api/vm/snapshots

### Parameters
#### Query Parameters
- **vm_id** (string) - Required - The ID of the virtual machine.

### Response
#### Success Response (200)
- **snapshots** (array) - A list of snapshot objects for the VM.
```

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

### Force PegaProx Update Script Re-download

Source: https://docs.pegaprox.com/

Command to force the update script to re-download the latest version, even if the current version is already installed. Useful for ensuring the absolute latest files are present.

```bash
# Force re-download even if already on latest version
sudo bash update.sh --force
```

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

### Efficient LVM Snapshots

Source: https://docs.pegaprox.com/

APIs for managing efficient LVM snapshots, including listing, creating, deleting, and rolling back.

```APIDOC
## List Efficient Snapshots

### Description
Lists the efficient LVM snapshots for a virtual machine.

### Method
GET

### Endpoint
`/api/clusters/{id}/vms/{vmid}/efficient-snapshots`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **vmid** (string) - Required - The ID of the virtual machine.

## Create LVM Snapshot

### Description
Creates a new efficient LVM snapshot for a virtual machine.

### Method
POST

### Endpoint
`/api/clusters/{id}/vms/{vmid}/efficient-snapshots`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **vmid** (string) - Required - The ID of the virtual machine.

## Delete Snapshot

### Description
Deletes an efficient LVM snapshot for a virtual machine.

### Method
DELETE

### Endpoint
`/api/clusters/{id}/vms/{vmid}/efficient-snapshots/{snap_id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **vmid** (string) - Required - The ID of the virtual machine.
- **snap_id** (string) - Required - The ID of the snapshot to delete.

## Rollback to Snapshot

### Description
Rolls back a virtual machine to a previous efficient LVM snapshot.

### Method
PUT

### Endpoint
`/api/clusters/{id}/vms/{vmid}/efficient-snapshots/{snap_id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **vmid** (string) - Required - The ID of the virtual machine.
- **snap_id** (string) - Required - The ID of the snapshot to roll back to.

## Check LVM Snapshot Support

### Description
Checks if the virtual machine supports efficient LVM snapshots.

### Method
GET

### Endpoint
`/api/clusters/{id}/vms/{vmid}/snapshots/check-capability`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the cluster.
- **vmid** (string) - Required - The ID of the virtual machine.
```

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

### List Source VMs

Source: https://docs.pegaprox.com/

Retrieves a list of virtual machines detected on the source ESXi host, along with their pre-filled settings.

```APIDOC
## GET /api/v2p/vms

### Description
List all source virtual machines detected on the ESXi host with their current settings.

### Method
GET

### Endpoint
/api/v2p/vms
```
Tokens:
Raw