proxmox/reports/status/LIST_VMS_SUMMARY.md

VM Listing Scripts - Implementation Summary

✅ Completed Tasks

1. Created Python Script (list_vms.py)

• ✅ Lists all VMs (QEMU and LXC) across all Proxmox nodes
• ✅ Retrieves VMID, Name, IP Address, FQDN, and Description
• ✅ Supports API token and password authentication
• ✅ Automatically loads credentials from ~/.env file
• ✅ Falls back to environment variables or JSON config
• ✅ Retrieves IP addresses via QEMU guest agent or network config
• ✅ Gets FQDN from hostname configuration
• ✅ Graceful error handling with helpful messages
• ✅ Formatted table output sorted by VMID

2. Created Shell Script (list_vms.sh)

• ✅ Alternative implementation using pvesh via SSH
• ✅ Works for users with SSH access to Proxmox node
• ✅ Retrieves same information as Python script
• ✅ Uses Python for JSON parsing

3. Documentation

• ✅ LIST_VMS_README.md - Comprehensive documentation
• ✅ LIST_VMS_QUICK_START.md - Quick reference guide
• ✅ LIST_VMS_SUMMARY.md - This summary

4. Features Implemented

IP Address Retrieval

• QEMU VMs: Uses QEMU guest agent (network-get-interfaces) or parses network config
• LXC Containers: Executes hostname -I command inside container
• Shows "N/A" if unavailable

FQDN Retrieval

• Gets hostname from VM/container configuration
• For running VMs, tries hostname -f command
• Falls back to config hostname
• Shows "N/A" if not configured

Description

• Retrieved from VM/container configuration
• Shows "N/A" if not set

File Structure

/home/intlc/projects/proxmox/
├── list_vms.py              # Python script (recommended)
├── list_vms.sh              # Shell script alternative
├── LIST_VMS_README.md       # Full documentation
├── LIST_VMS_QUICK_START.md  # Quick start guide
└── LIST_VMS_SUMMARY.md      # This file

Usage

Python Script (Recommended)

# Credentials loaded from ~/.env automatically
python3 list_vms.py

Shell Script

export PROXMOX_HOST=your-host
export PROXMOX_USER=root
./list_vms.sh

Dependencies

Python Script

• proxmoxer - Proxmox API client
• requests - HTTP library

Install with:

pip install proxmoxer requests

Shell Script

• SSH access to Proxmox node
• pvesh command on Proxmox node
• Python3 for JSON parsing

Configuration

Credentials are loaded from ~/.env file:

PROXMOX_HOST=your-proxmox-host
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value

Output Format

Both scripts output a formatted table:

VMID   | Name                    | Type | IP Address         | FQDN                    | Description
-------|-------------------------|------|-------------------|-------------------------|----------------
100    | vm-example              | QEMU | 192.168.1.100     | vm-example.local         | Example VM
101    | container-example       | LXC  | 192.168.1.101     | container.local         | Example container

Testing Status

• ✅ Script syntax validated
• ✅ Imports successfully
• ✅ Credentials loading from ~/.env verified
• ⚠️ Connection test requires accessible Proxmox host

Next Steps (Optional)

1. Add CSV/JSON output format option
2. Add filtering options (by node, type, status)
3. Add verbose mode for debugging
4. Add export to file option
5. Create wrapper script for easier execution

Notes

• Scripts handle missing information gracefully (shows "N/A")
• Both QEMU VMs and LXC containers are included
• Scripts automatically sort by VMID
• Python script is recommended for better error handling