qm-mtunnel

Command used by qmigrate during data migration from a VM to another host

$ qm [[mt|mtunnel]]

qm-mtunnel --vmid <VMID> --type <vnc|spice> [OPTIONS]

--vmid <VMID>
    Specifies the unique virtual machine ID for which the console tunnel should be established.

--type <vnc|spice>
    Defines the type of graphical console protocol to tunnel, either vnc or spice.

--listen-fd <FD>
    Optional. Instructs the tunnel to listen on a pre-opened file descriptor instead of a specific port. This is often used for inter-process communication.

--listen-port <PORT>
    Optional. Specifies the TCP port number that the qm-mtunnel daemon will listen on for incoming tunnel connections. If not specified, a dynamic port is typically assigned by the calling process (e.g., `pveproxy`).

--ssl-cert <FILE>
    Optional. Provides the file path to the SSL certificate for securing the WebSocket tunnel with TLS/SSL. Usually points to Proxmox's default SSL certificate.

--ssl-key <FILE>
    Optional. Provides the file path to the SSL private key associated with the certificate, used for TLS/SSL encryption of the WebSocket tunnel.

--timeout <SECONDS>
    Optional. Sets the timeout for the WebSocket connection in seconds. The default value is 60 seconds.

--host <IP>
    Optional. Specifies the local IP address on which `qm-mtunnel` should bind its listening socket. By default, it listens on all available network interfaces (0.0.0.0).

--debug
    Optional. Enables verbose debug logging output, which can be useful for troubleshooting connection issues.

The qm-mtunnel command, also known as `pve-qemu-server-mtunnel`, is an internal utility within Proxmox Virtual Environment (PVE) designed to establish secure WebSocket tunnels for accessing virtual machine graphical consoles (VNC and SPICE). It acts as an intermediary, proxying connections from a client (e.g., a web browser using the PVE web interface or the `qm console` command) to the actual VNC or SPICE server running on the virtual machine. This mechanism allows users to access VM consoles even when the client is behind a firewall or NAT, or when direct access to the VM's VNC/SPICE port is not feasible or desired. It typically handles SSL/TLS encryption for the tunnel, ensuring secure data transmission. While it's a standalone executable, it is primarily invoked and managed by Proxmox's `pveproxy` service and `qemu-server` components rather than directly by users.

qm-mtunnel is an internal Proxmox VE component and is generally not intended for direct manual execution by users. Its proper functioning relies on the Proxmox environment and its associated services (like `pveproxy`). Improper direct usage can lead to security vulnerabilities or service disruption. It's designed to be invoked programmatically by the Proxmox web interface or the `qm console` command, which handle the necessary parameters and security contexts automatically.

When you open a console to a VM from the Proxmox web interface, `pveproxy` (the Proxmox API daemon) initiates a call to `qm-mtunnel`. `qm-mtunnel` then creates a WebSocket server, often on a dynamically assigned port, and acts as a secure proxy between your browser's console client and the VM's VNC or SPICE server. This provides a single, secure entry point for console access, simplifying network configuration for users.

qm-mtunnel primarily utilizes WebSocket technology to create the tunnel. This allows for persistent, full-duplex communication over a single TCP connection, making it efficient for transmitting console data. When combined with SSL/TLS, it provides an encrypted and secure channel for sensitive console interactions, traversing network proxies and firewalls more easily than traditional VNC/SPICE direct connections.

qm-mtunnel was developed as an integral part of Proxmox Virtual Environment to address the complexities of secure and seamless graphical console access for virtual machines. As Proxmox evolved to provide a robust web-based management interface, the need for a reliable tunneling solution became crucial, especially for environments where VMs are behind firewalls or in private networks. It has been a core component enabling the 'Console' feature in the Proxmox web UI, offering both VNC and SPICE connectivity securely over a WebSocket tunnel since its introduction, evolving with Proxmox VE releases to enhance stability and security.

qm(1), qemu-server(1), pveproxy(8), ssh(1) (for general tunneling concepts)