Apache Guacamole and its interaction with the API: the real case of using oVirt

server one

Hardware vendors offer customers different methods of remote server management that do not depend on the operating system. We have already written about the web-based console for Supermicro motherboards developed by HOSTKEY specialists, which does not require Java to be installed locally. Dell equipment can also be managed remotely via the VNC console built into DRAC. Now, we’re going to tell you how to do it.

Rent dedicated and virtual servers with instant deployment in reliable TIER III class data centers in the Netherlands and the USA. Free protection against DDoS attacks included, and your server will be ready for work in as little as 15 minutes. 24/7 Customer Support.

VNC (Virtual Network Computing) is a system that connects to a remote computer via the RFB (Remote FrameBuffer) protocol. This protocol allows multiple simultaneous user sessions.

Why Apache Guacamole?

The first implementation of our solution required us to activate remote-control port forwarding and open the DARC console via VNC using a special button. Then you had to wait for the console.vv file to load and open it, all this only after having already installed the Virtual Machine Manager tools tools on the local computer. This method is not overly complicated, but it is inconvenient for users and has led to errors when working with rented equipment.

Access VNC console

Example of a file: console.vv

# Password is valid for 120 seconds.


To make life easier for our users, we needed to implement a direct launch of the HTML5 web console from the Client Area without requiring the user to install Virtual Machine Manager tools tools. For this, we chose Apache Guacamole - a free cross-platform remote desktop gateway that supports all popular protocols and technologies: Telnet, SSH/SFTP, RDP, Kubernetes, as well as VNC (RFB). An important advantage of Apache Guacamole - it does not require installing client programs or special plug-ins. The user gains access to hardware management from their browser with a single click in the Client Area:

Access HTML5 console

How does it work?

You can activate the console not only in the browser, but also by curl-request directly to our API:

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=novnc" \
--data "token=SESSION_TOKEN" \
--data "id=SERVER_ID" \
--data "pin=PIN_CODE"

Example of an answer:


The user has to wait for the console to load, but on the service side the process looks more complicated. As an example, let's look at calling the VNC console in a browser.

The general scheme of calling the VNC console in the browser from the Client Area:

The general scheme of calling the VNC console

When requesting via Invapi, a command is given to the API to open the console of a particular server via a message broker cluster (RabbitMQ). To do this, just send the server number to the message broker.

RabbitMQ transfers server and task data to an auxiliary service receiver created by our experts. The receiver takes the data in RabbitMQ, transforms all the necessary information, splits the tasks (e.g. oVirt, Cisco, IPMI, etc.) and sends them to the fence agent.

To manage virtual machines via API or web interface, we chose oVirt. The system uses the KVM hypervisor and is based on several projects, including libvirt, Gluster, PatternFly and Ansible. It's quite easy to use and highly reliable. Our experience with integrating oVirt into a production infrastructure will be discussed in more detail in a separate article.

Structure of the oVirt fence agent:

inputRawURLConsole := inputRawURL + "/vms" + "/" + vm.MustId() + "/graphicsconsoles" + "/" + Vnc
url := noVncURL + url + "/skey/" + *key + "/id/" + *name + "/ovirt/pass/" + passwd_encode + "/port/" + port + "/location/" + *location1

item := APICallBack{Result: "OK", Debug: "debug"}
item.Message = string(body)
jitem, err := json.Marshal(item)
if err != nil {


Fence agents correspond to the types of hardware used in our infrastructure. They access the server with docker-novnc, which has access to the oVirt network. The agent loads the console and fetches the necessary host parameters (IP and password), then decodes the received data and sends a request to the noVnc API via the oVirt router, where data exchange with the Guacamole API takes place. The agent sends a GET request to the server, which contains the IP address and server ID, as well as the session token for the server.

Request structure:

r.Get("/{id}/skey/{key}/id/{uid}/ovirt/pass/{upass}/port/{uport}/location/{uloc}", StageHandler)

Once the request has been processed, the client has access to control the equipment via the VNC console.

Example of an open console for Windows:

Example of an open console for Windows

Example of an open console for CentOS:

Example of an open console for CentOS

The problem with hotkeys

Certain key combinations cannot be pressed in the web application because they are reserved by the OS (e.g. Ctrl-Alt-Del or Alt-Tab) or by the browser. This problem can be solved by calling the Apache Guacamole navigation menu with the Ctrl-Alt-Shift key combination (you can hide the menu by pressing the combination again). There you can select the input method (text, on-screen keyboard), enable mouse emulation mode, select the language and time zone, and close the work session.

The English-language version of the Navigation menu:

The console remains active for two hours, after which the session is automatically closed and the login must be repeated.


Using Apache Guacamole simplifies the management of server hardware from different vendors. In the future, we plan to develop a solution to avoid automatic closure of the console after two hours.

Rent dedicated and virtual servers with instant deployment in reliable TIER III class data centers in the Netherlands and the USA. Free protection against DDoS attacks included, and your server will be ready for work in as little as 15 minutes. 24/7 Customer Support.

Other articles


Creating a Single sign-on service with reminders for users

How to make a simple and reliable password change system and help users remember to change their password timely.


Which graphics card is better for business - RTX 4090 or server RTX A5000?

We shall compare the new gaming graphics card from Nvidia - the GeForce RTX 4090 and the powerful RTX A5000 server card.


Migrating virtual servers from oVirt to VMware

We develop and apply a convenient scheme for quickly transferring servers from oVirt to VMware.


Collecting logs using Go

How to solve some issues with collecting logs using Go


WindowsPE Live-CD in Jenkins/Foreman Infrastructure

Building a WindowsPE distribution in a Linux infrastructure, automating this process using Jenkins, and deploying MS Windows-based systems through this helper.

HOSTKEY Dedicated servers and cloud solutions Pre-configured and custom dedicated servers. AMD, Intel, GPU cards, Free DDoS protection amd 1Gbps unmetered port 30
4.3 67 67