qm-vncproxy

Proxy a specific virtual machine

$ qm [[v|vncproxy]] [vm_id]

qm-vncproxy <vmid> [--listen <IP_ADDRESS>] [--port <PORT>] [--vnc <VNC_PORT>] [--websocket <0|1>] [--path <PATH>] [--ssl-cert <FILE>] [--ssl-key <FILE>] [--daemon] [--verbose]

<vmid>
    The unique numeric ID of the virtual machine or container for which VNC access is being proxied.

--listen <IP_ADDRESS>
    Specifies the IP address on which the proxy should listen for incoming client connections. Defaults to '127.0.0.1' (localhost) for internal Proxmox UI use.

--port <PORT>
    Defines the TCP port number on which the proxy will listen for client connections (e.g., from a web browser). This is the external-facing port.

--vnc <VNC_PORT>
    Specifies the port on which the guest's internal VNC server is listening. This is the internal port on the VM/CT accessible from the Proxmox host.

--websocket <0|1>
    Enables (1) or disables (0) WebSocket proxying. This is crucial for seamless integration with modern web browsers and the Proxmox web UI. It is typically enabled by default.

--path <PATH>
    Sets the URL path for WebSocket connections, e.g., '/websockify'. This option is relevant when integrating with specific web server configurations or reverse proxies.

--ssl-cert <FILE>
    Provides the path to the SSL certificate file (e.g., in PEM format) to enable encrypted WebSocket connections (WSS) between the client and the proxy.

--ssl-key <FILE>
    Provides the path to the SSL private key file corresponding to the SSL certificate, used for establishing encrypted WebSocket connections (WSS).

--daemon
    Runs the qm-vncproxy process in the background as a daemon, detaching it from the controlling terminal.

--verbose
    Enables verbose output, providing more detailed logging and debugging information to the console or log files.

qm-vncproxy is a fundamental utility within Proxmox Virtual Environment (PVE) that acts as a secure VNC proxy for both KVM virtual machines and LXC containers. Its primary function is to facilitate in-browser console access, an integral part of the Proxmox web interface. When a user requests a graphical console session through the PVE UI, qm-vncproxy establishes a secure WebSocket connection (often SSL/TLS encrypted) between the user's web browser and the Proxmox host. It then intelligently bridges and forwards the VNC traffic originating from the guest's internal VNC server to the browser. This architecture eliminates the need for users to install a dedicated VNC client, significantly enhancing security by centralizing access control through the robust PVE authentication system and simplifying connectivity management.

While qm-vncproxy enhances VNC security by centralizing access through the Proxmox authentication system, direct exposure of the proxy to the public internet without proper firewall rules, SSL/TLS encryption, and a robust reverse proxy is highly discouraged. It is primarily designed to operate behind the Proxmox web interface's authentication layer. Each active VNC proxy session consumes system resources (CPU, RAM, network bandwidth) on the Proxmox host. Ensure network configuration permits traffic to the proxy port if access is required from external networks.

qm-vncproxy fundamentally relies on WebSocket technology to translate the traditional VNC protocol into a format consumable by web browsers. This integration, often powered by or compatible with the underlying principles of the noVNC project, is critical for its role in providing a 'clientless' console experience directly within the Proxmox web user interface, enhancing accessibility and ease of use.

It is crucial to understand that qm-vncproxy typically operates within a pre-authenticated context. It does not perform user authentication itself. Instead, it is invoked by the Proxmox web interface on behalf of a user who has already successfully authenticated and been authorized to access the specific virtual machine or container. This design delegates the crucial security and access control responsibilities to the comprehensive Proxmox authentication and authorization system.

qm-vncproxy's development is closely intertwined with the evolution of web-based virtualization management interfaces, particularly within the Proxmox Virtual Environment (PVE) ecosystem. As modern web applications moved towards providing rich, interactive experiences without requiring external client software, components like qm-vncproxy became indispensable. It emerged as a solution to bridge the traditional VNC protocol with WebSocket technology, often leveraging projects like noVNC, enabling seamless in-browser console access. This marked a significant step in Proxmox VE's commitment to delivering an integrated, secure, and user-friendly virtualization platform, evolving from simpler direct VNC forwarding methods to a more robust and integrated proxy solution over the platform's history.

qm(1), pct(1), vncviewer(1), noVNC(1), websockify(1)