llm-automation-docs-and-remediation-engine/docs/PROXMOX_SETUP.md

Proxmox VE API Integration Setup

This guide explains how to configure the Proxmox collector to connect to your Proxmox VE cluster and collect infrastructure data.

Prerequisites

• Proxmox VE 7.0 or later
• Network access to Proxmox API (default port 8006)
• User account with appropriate permissions

Authentication Methods

The Proxmox collector supports two authentication methods:

Method 1: API Token (RECOMMENDED)

API tokens are more secure than passwords and can be easily revoked. They also support fine-grained permissions.

Advantages:

• More secure (no password exposure)
• Can be revoked independently
• Fine-grained permissions
• Best practice for automation

Setup Steps:

1. Login to Proxmox Web UI

   • Navigate to https://your-proxmox-host:8006
   • Login with your credentials

2. Navigate to API Tokens

   • Click on Datacenter in the left sidebar
   • Go to Permissions → API Tokens

3. Create New Token

   • Click Add button
   • Configure the token:
     • User: Select or create a user (e.g., automation@pam)
     • Token ID: Give it a descriptive name (e.g., docs-collector)
     • Privilege Separation: Leave UNCHECKED for read-only access
     • Click Add

4. Copy Token Secret

   • ⚠️ IMPORTANT: Copy the token secret immediately!
   • It will only be shown once and cannot be retrieved later
   • Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

5. Set Permissions

   • Go to Datacenter → Permissions
   • Click Add → API Token Permission
   • Configure:
     • Path: / (root, for full access)
     • API Token: Select your token (e.g., automation@pam!docs-collector)
     • Role: PVEAuditor (read-only access)
     • Click Add

6. Configure Environment Variables

   # In your .env file:
   PROXMOX_HOST=proxmox.example.com
   PROXMOX_PORT=8006
   PROXMOX_USER=automation@pam
   PROXMOX_TOKEN_NAME=docs-collector
   PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   PROXMOX_VERIFY_SSL=false  # Set to true if using valid SSL cert
   

Method 2: Username + Password

Use this method only if API tokens are not available.

Setup Steps:

1. Create Dedicated User (Optional but Recommended)

   • Go to Datacenter → Permissions → Users
   • Click Add
   • Configure:
     • User name: automation
     • Realm: pam or pve
     • Password: Set a strong password
     • Click Add

2. Set Permissions

   • Go to Datacenter → Permissions
   • Click Add → User Permission
   • Configure:
     • Path: /
     • User: Select your user (e.g., automation@pam)
     • Role: PVEAuditor
     • Click Add

3. Configure Environment Variables

   # In your .env file:
   PROXMOX_HOST=proxmox.example.com
   PROXMOX_PORT=8006
   PROXMOX_USER=automation@pam
   PROXMOX_PASSWORD=your-secure-password
   PROXMOX_VERIFY_SSL=false  # Set to true if using valid SSL cert
   

Roles and Permissions

The collector needs read-only access to gather infrastructure data.

Recommended Role: PVEAuditor

The PVEAuditor role provides read-only access to:

• Virtual Machines (QEMU)
• Containers (LXC)
• Nodes and Cluster Status
• Storage Information
• Network Configuration

This role is perfect for documentation collection as it cannot modify anything.

Custom Role (Optional)

If you want even more restricted access, create a custom role:

1. Go to Datacenter → Permissions → Roles
2. Click Create
3. Name it DocCollector
4. Select these privileges:
   • VM.Audit
   • Datastore.Audit
   • Sys.Audit
5. Use this custom role when assigning permissions

Testing the Connection

After configuring credentials, test the connection:

# Using the test script
python scripts/test_proxmox_docs.py

You should see:

✓ Connected to Proxmox VE version X.Y
Collected N VMs from M nodes

If using mock data, you'll see:

Proxmox host not configured, using mock data for development

Troubleshooting

Connection Refused

Error: Connection failed: [Errno 111] Connection refused

Solutions:

• Check PROXMOX_HOST is correct
• Ensure port 8006 is accessible
• Check firewall rules
• Verify Proxmox API is running: systemctl status pveproxy

Authentication Failed

Error: Connection failed: 401 Unauthorized

Solutions:

• Verify credentials are correct
• Check user/token has required permissions
• Ensure realm is correct (@pam or @pve)
• For tokens: verify token ID matches exactly

SSL Certificate Errors

Error: SSL: CERTIFICATE_VERIFY_FAILED

Solutions:

1. Quick Fix (Development): Set PROXMOX_VERIFY_SSL=false
2. Production Fix:
   • Install valid SSL certificate on Proxmox
   • Or add Proxmox CA to trusted certificates
   • Set PROXMOX_VERIFY_SSL=true

Permission Denied

Error: 403 Forbidden or Permission denied

Solutions:

• Check user/token has PVEAuditor role
• Verify permission is set on path /
• For tokens: ensure "Privilege Separation" is UNCHECKED

Timeout Errors

Error: Connection timeout after 30s

Solutions:

• Increase timeout: PROXMOX_TIMEOUT=60
• Check network latency
• Verify Proxmox server is not overloaded

Security Best Practices

1. Use API Tokens instead of passwords
2. Use Read-Only Role (PVEAuditor)
3. Dedicated User for automation (not root)
4. Valid SSL Certificates in production (PROXMOX_VERIFY_SSL=true)
5. Rotate Tokens periodically
6. Audit Logs regularly to monitor API access
7. Network Segmentation - restrict access to Proxmox API
8. Secret Management - use vault for credentials (not .env in production)

Example Configuration

Development Environment

# .env
PROXMOX_HOST=192.168.1.100
PROXMOX_PORT=8006
PROXMOX_USER=automation@pam
PROXMOX_TOKEN_NAME=docs-dev
PROXMOX_TOKEN_VALUE=12345678-1234-1234-1234-123456789012
PROXMOX_VERIFY_SSL=false
PROXMOX_TIMEOUT=30

Production Environment

# .env (use secrets manager in real production!)
PROXMOX_HOST=proxmox.company.com
PROXMOX_PORT=8006
PROXMOX_USER=automation@pam
PROXMOX_TOKEN_NAME=docs-prod
PROXMOX_TOKEN_VALUE=87654321-4321-4321-4321-210987654321
PROXMOX_VERIFY_SSL=true
PROXMOX_TIMEOUT=60

Additional Resources

• Proxmox VE API Documentation
• Proxmox User Management
• Proxmox API Tokens
• proxmoxer Python Library

Support

If you encounter issues:

1. Check this documentation
2. Review logs: docker-compose logs chat worker
3. Test with mock data first
4. Verify Proxmox API access independently
5. Open an issue on GitHub with logs