pgo: Fast Proxmox Guest Connector & Status Viewer

README.md

pgo: Fast Proxmox Guest Connector & Status Viewer

A lightweight set of Bash scripts for Proxmox VE to quickly list and enter LXC containers and Virtual Machines directly from the node console. It bypasses the Proxmox Perl API by reading configuration files and PID states directly, reducing query times from several seconds to milliseconds.

Supports resolving targets by ID or exact hostname.

Installation

1. Place both files (pgo and list-targets) into a directory that is part of your $PATH (e.g., ~/.local/bin/ or /usr/local/bin/).
2. Make the scripts executable:

   chmod +x ~/.local/bin/pgo ~/.local/bin/list-targets

3. (Optional) If using ~/.local/bin/, ensure it is added to your $PATH in your ~/.bashrc or ~/.profile:

   export PATH="$HOME/.local/bin:$PATH"

Usage

To display a formatted, color-coded table of all VMs and LXCs and their current state:

list-targets

To enter a guest, provide its ID or Name. The script automatically detects if it is an LXC or a VM and uses the appropriate connection method (pct enter or qm terminal).

pgo 100
pgo my-webserver

Upon exiting the guest session (via exit for LXC or Ctrl+O for VM terminals), pgo will return to the host node and automatically print the updated list of targets.

list-targets

#!/bin/bash

echo ''
echo '-= Targets =-'
echo ''

GREEN=$'\e[32m'
RED=$'\e[31m'
BLUE=$'\e[36m'
RESET=$'\e[0m'

gather_data() {
    # 1. LXCs
    for conf in /etc/pve/lxc/*.conf; do
        [ -e "$conf" ] || continue
        vmid=$(basename "$conf" .conf)
        name=$(grep -m 1 '^hostname:' "$conf" | cut -d' ' -f2-)

        if systemctl is-active --quiet pve-container@"${vmid}"; then
            status="${GREEN}running${RESET}"
        else
            status="${RED}stopped${RESET}"
        fi
        echo "$vmid|LXC|$status|$name"
    done

    # 2. VMs
    for conf in /etc/pve/qemu-server/*.conf; do
        [ -e "$conf" ] || continue
        vmid=$(basename "$conf" .conf)
        name=$(grep -m 1 '^name:' "$conf" | cut -d' ' -f2-)

        if [ -f "/var/run/qemu-server/${vmid}.pid" ]; then
            status="${GREEN}running${RESET}"
        else
            status="${RED}stopped${RESET}"
        fi
        echo "$vmid|VM|$status|$name"
    done
}

gather_data | sort -n | column -t -s '|' -N "ID,TYPE,STATUS,NAME"

echo ""
echo "Use ${BLUE}pgo <ID>${RESET} to enter."
echo ""

pgo

#!/bin/bash
target="$1"

HIGHLIGHT=$'\e[36m'
RESET=$'\e[0m'

# Check if target is provided
if [ -z "$target" ]; then
    echo "Please provide an ID or Name. Usage: ${HIGHLIGHT}pgo <ID|NAME>${RESET}"
    exit 1
fi

vmid=""

# Check if the target is purely numeric (ID)
if [[ "$target" =~ ^[0-9]+$ ]]; then
    vmid="$target"
else
    # Target is not a number, search for a matching name
    matches=()

    # Search in LXC configs
    for conf in /etc/pve/lxc/*.conf; do
        [ -e "$conf" ] || continue
        # Use awk for exact string matching to prevent regex issues
        if awk -v t="$target" '($1=="hostname:" && $2==t) {found=1; exit} END {exit !found}' "$conf"; then
            matches+=("$(basename "$conf" .conf)")
        fi
    done

    # Search in VM configs
    for conf in /etc/pve/qemu-server/*.conf; do
        [ -e "$conf" ] || continue
        if awk -v t="$target" '($1=="name:" && $2==t) {found=1; exit} END {exit !found}' "$conf"; then
            matches+=("$(basename "$conf" .conf)")
        fi
    done

    # Evaluate the results of the search
    if [ ${#matches[@]} -eq 1 ]; then
        vmid="${matches[0]}"
    elif [ ${#matches[@]} -gt 1 ]; then
        echo "Error: Name ${HIGHLIGHT}$target${RESET} is not unique. Found IDs: ${matches[*]}"
        exit 1
    else
        echo "Error: No LXC or VM found with name ${HIGHLIGHT}$target${RESET}."
        exit 1
    fi
fi

# Execute connection based on the resolved vmid
if [ -f "/etc/pve/lxc/${vmid}.conf" ]; then
    echo "Type ${HIGHLIGHT}exit${RESET} to leave the LXC."
    echo ""
    pct enter "$vmid"

elif [ -f "/etc/pve/qemu-server/${vmid}.conf" ]; then
    echo "Press ${HIGHLIGHT}Ctrl+O${RESET} to leave a VM terminal."
    echo "See https://forum.proxmox.com/threads/how-to-enter-a-vm-from-the-the-node-console.55323/#post-475926 for config."
    echo ""
    qm terminal "$vmid"

else
    echo "Error: Neither LXC nor VM with the ID ${HIGHLIGHT}$vmid${RESET} found."
    exit 1
fi

echo ""
echo "Welcome back!"
list-targets