proxmox/docs/01-getting-started/LIST_VMS_README.md

# List Proxmox VMs Scripts

Two scripts to list all Proxmox VMs with VMID, Name, IP Address, FQDN, and Description.

## Scripts

### 1. `list_vms.py` (Python - Recommended)

Python script using the Proxmox API. More robust and feature-rich.

**Features:**
- Supports both API token and password authentication
- Automatically loads credentials from `~/.env` file
- Retrieves IP addresses via QEMU guest agent or network config
- Gets FQDN from hostname configuration
- Handles both QEMU VMs and LXC containers
- Graceful error handling

**Prerequisites:**
```bash
pip install proxmoxer requests
# Or if using venv:
source venv/bin/activate
pip install proxmoxer requests
```

**Usage:**

**Option 1: Using ~/.env file (Recommended)**
```bash
# Create/edit ~/.env file with:
PROXMOX_HOST=your-proxmox-host
PROXMOX_USER=root@pam
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value
# OR use password:
PROXMOX_PASSWORD=your-password

# Then run:
python3 list_vms.py
```

**Option 2: Environment variables**
```bash
export PROXMOX_HOST=your-proxmox-host
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=your-token-name
export PROXMOX_TOKEN_VALUE=your-token-value
python3 list_vms.py
```

**Option 3: JSON config file**
```bash
export PROXMOX_MCP_CONFIG=/path/to/config.json
python3 list_vms.py
```

### 2. `list_vms.sh` (Shell Script)

Shell script using `pvesh` via SSH. Requires SSH access to Proxmox node.

**Prerequisites:**
- SSH access to Proxmox node
- `pvesh` command available on Proxmox node
- Python3 for JSON parsing

**Usage:**
```bash
export PROXMOX_HOST=your-proxmox-host
export PROXMOX_USER=root
./list_vms.sh
```

## 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
```

## How IP Addresses are Retrieved

### For QEMU VMs:
1. First tries QEMU guest agent (`network-get-interfaces`)
2. Falls back to network configuration parsing
3. Shows "N/A" if neither method works

### For LXC Containers:
1. Executes `hostname -I` command inside container
2. Filters out localhost addresses
3. Shows "N/A" if command fails or container is stopped

## How FQDN is Retrieved

1. Gets hostname from VM/container configuration
2. For running VMs, tries to execute `hostname -f` command
3. Falls back to hostname from config if command fails
4. Shows "N/A" if no hostname is configured

## Troubleshooting

### Connection Timeout
- Verify Proxmox host is reachable: `ping your-proxmox-host`
- Check firewall rules allow port 8006
- Verify credentials in `~/.env` are correct

### Authentication Failed
- Verify API token is valid and not expired
- Check user permissions in Proxmox
- Try using password authentication instead

### IP Address Shows "N/A"
- For QEMU: Ensure QEMU guest agent is installed and running in VM
- For LXC: Container must be running to execute commands
- Check network configuration in VM/container

### FQDN Shows "N/A"
- Set hostname in VM/container configuration
- For running VMs, ensure hostname command is available

## Examples

### List all VMs
```bash
python3 list_vms.py
```

### List VMs from specific host
```bash
PROXMOX_HOST=192.168.11.10 python3 list_vms.py
```

### Using shell script
```bash
PROXMOX_HOST=192.168.11.10 PROXMOX_USER=root ./list_vms.sh
```

## Notes

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