WebVirtMgr allows to access to the VNC/SPICE instance console directly through a web browser using a HTML5 client. To connect to the console, the HTML5 client uses websocket proxy service implemented by webvirtmgr-console script. This script is running in parallel of WebVirtMgr on 6080 TCP port (by default, could be configured using WS_PORT variable in your local_settings.py file) on act as proxy between HTML5 client and instance console socket.
Encrypted and Unencrypted connections
The webvirtmgr-console script is able to handle both encrypted and unencrypted connections. HTML5 client will try to established an encrypted connection if the console page is accessed through HTTPS. To handle encrypted connections, a valid SSL certificate has to be configured for webvirtmgr-console script. This certificate has to be recognized as safe by the client web browser and has to be generated for the right domain name used to connect to webvirtmgr-console script. This domain name could be configured using WS_PUBLIC_HOST variable in your local_settings.py file. If it's not, the domain name (or IP address) used to access to WebVirtMgr will be used.
The certificate used by webvirtmgr-console script has to be configured using WS_CERT variable in local_settings.py file. The absolute path to the certificate file has to be used. This file must contain both private and public keys. You could find an example of file in console/cert.pem.
If the your certificate was issued by a certification authority, you could have to provide certification chain. According to Python SSL documentation, you have to put authorities certificates at the end of your certificate file. Be careful of the certificates orders, it matters.
On click console link, WebVirtMgr will detect instance console type (VNC or SPICE) and open the right HTML5 client in a popup page. This page is called with a token in URL. This token specifies which instance you want to connect to. It's a concatenation of host ID and instance UUID separated by dash.
This token will be passed to webvirtmgr-console script trough a cookie. By using the cookie value, webvirtmgr-console script will retrieve instance console informations, and open socket on it :
- If console is listening on localhost (or a local UNIX socket) and this instance is running on an host which is accessed by WebVirtMgr trough a SSH connection, a SSH tunnel will be used.
- If console is listening on a local UNIX socket and the instance is running on the same host running WebVirtMgr (and access trough local UNIX socket), a connection is opened on the instance UNIX socket.
- In any other cases, console socket is opened by using visualization hostname (or IP address) and the console port.
If a connection is successfully opened to the console socket, webvirtmgr-console script will proxying all traffic between its websocket and the console TCP socket.
"connect timeout" error
This error means your web browser failed to connect to websocket proxy server. Firstly, verify that you have properly configure webvirtmgr-console script (refer to the dedicated section).
Finally, check that your firewall does not block traffic on TCP 6080 port from your web browser.
"Unexpected protocol mismatch." error
This error means that HTML5 client does not understand the server. It's most often a problem corresponding on webvirtmgr-console script : Check the log files in /var/log/supervisor/webvirtmgr-console*.log.
In most cases, proxy failed getting valid informations of the instance's console or failed to connect to it. It could be due to an error in the configuration of the graphics device of your instance (refer to the dedicated section).
Check your installation
Check your instance's console configuration
Check in the XML configuration of your instance that graphics device looks like :
The listen address depends of your installation :
- If WebVirtMgr access to your virtualization host directly trough Libvirt TCP socket, your instances's consoles have to listen to the physical host IP address (or 0.0.0.0) otherwise, proxy can't connect to it.
- If your virtualization host is accessed trough a SSH connection, a SSH tunnel will be used and your instances's console could listen only to the loopback interface.
- If your virtualization host is the same host that running WebVirtMgr, your instances's consoles could also listen only to the loopback interface.
Check webvirtmgr-console is properly configured and running
To known if webvirtmgr-console is properly configured, check that this configuration variables are properly set :
- WS_HOST : the listening IP address. Must be configured with the public IP address of your WebVirtMgr host
- WS_PORT : the listening TCP port. By default, it's 6080 TCP port. If you also use Nova noVNC service that using the same port, you have to change this port.
- WS_CERT : the SSL certificate used for encrypted connection. This parameter is particularly important if your WebVirtMgr web interface is reachable trough HTTPS, that means that console websocket connection will be encrypted. Check Encrypted and Unencrypted connections section to verify that you are using a valid file.
You also have to verify that WebVirtMgr is properly configured to connect on the websocket of webvirtmgr-console script. Check in particular, the WS_PUBLIC_HOST variable : This variable must contain the hostname (or IP address) that clients web browser have to use to connect to the websocket. If you are using a reverse proxy, this variable must contain your reverse proxy hostname.
To known if webvirtmgr-console script is running and listening, run this command :
~# netstat -lnp|grep 6080 tcp 0 0 0.0.0.0:6080 0.0.0.0:* LISTEN 15141/python
The server has to be running on 0.0.0.0 (or the your public IP address) but not on localhost (unless if you are using a reverse proxy).