Icinga + Guacamole

by Guest Author | Oct 4, 2022

This is a guest blogpost from Cecilia Gripenberg from RedBridge

Integration Magic

One of Icinga’s greatest strengths is its ability to integrate with other systems and use those systems’ data to enrich monitoring. It can write time-series data to InfluxDB, Graphite or even Prometheus with our icinga2-exporter. It can talk to different data sources so that hosts and services can be created and managed automatically. This means that lots of manual work is eliminated. What is also very helpful is being able to pull or present information from those other systems in Icinga’s web user interface, Icingaweb2. So a user does not have to jump from one webpage/tab/window to another just to see information that is relevant to a host, service or application. What if you could connect directly to your server from Icinga?

Remote connections

Quite often monitoring systems are used by IT support teams that work with the servers and applications using remote connections such as Remote Desktop Protocol (RDP), Secure Shell (SSH), Virtual Network Computing (VNC), and even Telnet. But this often means that everyone on the team has to be onboarded and their clients have to be configured with every single connection required. This may be relatively painless if you are dealing with a few dozen servers.
But what if you have hundreds of servers? That’s where a remote desktop gateway can come in handy. Citrix and VMware Horizon are quite popular, but what if your IT department is on a tight budget or you want to use some energy-saving Raspberry Pis? That’s where Apache Guacamole comes in. This is a fully open-source web browser-based remote desktop gateway that supports all the protocols above. This means you can configure all your remote connections once, and everyone on the team can share these remote connections. It also means that your team only needs a modern web browser to connect to the servers. If you’re a Managed Service Provider with overlapping networks, you also can easily install multiple Guacamole instances for
each of these networks.

So how do you integrate Icingaweb2 and Guacamole? By adding links to instantly connect to your servers without ever leaving Icinga.

You can create direct links to your specified connection using a special URL. Guacamole connection URLs are using a connection identifier encoded in base64url (connection id # + null byte + client identifier type + nullbyte + database type) when the database used is MySQL or Postgres. See Guacamole source code on GitHub.

Direct yourself to success

Icinga Director’s Sync & Import is extremely handy if you want to automatically configure your links in Icingaweb2 and you are using these databases. It will save you lots of time re-configuring Icinga when connections change in Guacamole. If you are using the JSON or Quickconnect plugins, there are ways around this.

Add a new Application Resource
Cogwheel => Application => Resources => Create a New Resource

Resource Type: SQL 
Resource Name: guacamole_db Database 
Type: MySQL or PostgreSQL 
Host: guacamole.example.com 
Port: 5432/3306 Database 
Name: guacamole 
Username: guacamole_user 
Password: GuacaGuacaMole

Add a new import source

This will ingest data from the Guacamole database and generate some client connection identifiers
Icinga Director => Automation => Import source => Add

Import source name: guacamole_db
Source Type: SQL
Key column name: connection_name
Resource name: guacamole_db

PostgreSQL DB Query:

SELECT connection_id,connection_name,REPLACE(REPLACE(TRIM( TRAILING
'=' from
encode(concat(connection_id,'\000','c','\000','postgresql')::bytea,
'base64')),'+','-'),'/','_') AS connection_url from
guacamole_connection;

MySQL DB Query:

SELECT connection_id,connection_name,TRIM(TRAILING '=' FROM
REPLACE(REPLACE(
TO_BASE64(CONCAT(connection_id,CHAR(0x00),'c',CHAR(0x00),'mysql')),
'+', '-'), '/', '_')) AS connection_url from guacamole_connection;

Should you have security concerns around reading the table directly, you can always use a VIEW that only exposes the necessary columns. Or you could export a CSV from your query which is accessible to Icinga Director.

Add a property modifier (under Modifiers)

Property: connection_url
Target property: guacamole_whole_url
Modifier: Combine multiple properties
Pattern:
https://guacamole.example.com:8080/#/client/${connection_url}

Add a new sync rule

Property 1 (Adds a custom variable that shows the connection ID number)

Source Name: guacamole_db
Destination Field: Custom variable (vars.)
Custom variable: guacamole_id
Source column: connection_id
Set based on filter: no
Merge Policy: merge

Property 2 (Makes sure that an existing host is matched)

Source Name: guacamole_db
Destination Field: display_name
Source column: connection_name
Set based on filter: no

Property 3 (Adds a partial connection URL)

Source Name: guacamole_db
Destination Field: Custom variable (vars.)
Custom variable: guacamole_identifier
Source column: connection_url
Set based on filter: no
Merge Policy: merge

Property 4 (Adds a complete connection URL)

Source Name: guacamole_db
Destination Field: Custom variable (vars.)
Custom variable: guacamole_url
Source column: guacamole_whole_url
Set based on filter: no
Merge Policy: merge

Once you’ve got your rules running and your Guacamole server up, all you need to do is to add
a Host Action link Icingaweb2.

If you are using the IDO:

Add one new host action to connect with a new web browser window:

Name: Guacamole (window)
Type: Host Action
Target: New Window
URL: $_host_guacamole_url$
Filter: _host_guacamole_identifier=*

Add one new host action to connect within Icingaweb2:

Name: Guacamole (Frame)
Type: Host Action
Target: New Column
URL: $_host_guacamole_url$
Filter: _host_guacamole_identifier=*

If you are using the Icinga DB:

Add one new host action to connect with a new web browser window

Name: Guacamole (window)
Type: Host Action
Target: New Window
URL: $host.vars.guacamole_url$
Filter: host.vars.guacamole_identifier=*

Add one new host action to connect within Icingaweb2

Name: Guacamole (Frame)
Type: Host Action
Target: New Column
URL: $host.vars.guacamole_url$
Filter: host.vars.guacamole_identifier=*

Once you run your import and apply rules, any hosts with matching display names should nowhave a link next to then in the Actions section.

: Actions and Custom variables when using IcingaDB

: Actions and Custom variables when using Icinga IDO

You’re done!

Should you have multiple Guacamole servers, just repeat the steps starting from Application Resource to Add a new sync rule. The import source name, sync rule name, and application resource name must be unique.

Monitoring Guacamole

No guide would be complete without some monitoring guidance.

Component	What	Plugins
Guacamole daemon (guacd)	Ensure it is running and its listening port is up	check_tcp
Guacamole client	Make sure the web page is responding and the Tomcat server is alive	check_http
Database	Check whether your database can be logged into and that it is performing well.	Check out Linuxfabric’s great MySQL monitoring plugins
Tomcat / guacd	Log files	Ship your logs to your favorite logging solution, we really love Loki, as it integrates with Grafana well

Notes

JSON

If you are using the json authentication backend, connection urls are easy to generate as no connection IDs are used. You can add a simple HTML page with Javascript which will translate your connection name to the base64url format.

Quickconnect

If you are using the quickconnect backend, connection urls are generated by talking to the backend. I have made an example page that will let you perform this automatically.