TN 6022: Guacamole Integration

Adding an Apache Guacamole broker to enhance Remote client connections

Overview

Sassafras suite 7.7 in the LabSight and AllSight product tiers offer integration with Apache Guacamole. Using a broker server you can have fully web based remote connections that are cross platform consistent and have enhanced capabilities from traditional direct VNC and RDP connections. This article details how you can integrate your Sassafras server with your Guacamole server.

Files required for this can be found in Integrations/Guacamole of full disk image:

  • remote-broker-7.7.0.war
  • sassafras.json
  • Prerequisites

  • Java (8/1.8 sufficient)
  • Tomcat 9
  • Guacamole Server (guacd) 1.2.0
  • Note that Guacamole has several of it's own dependancies for compiling. In addition, you want to make sure several "optional" packages are in fact present so you have RDP, VNC, and SSL support.

    Tomcat will be installed somewhere like /usr/local/tomcat9.
    Create if needed: /etc/guacamole

    Here is an example of compiling and installing on Ubuntu:

    sudo apt install libpng-dev
    sudo apt install libjpeg-dev
    sudo apt install libvncserver-dev
    sudo apt install freerdp2-dev
    sudo apt install cairo-5c
    sudo apt install libcairo-5c-dev
    sudo apt install libcairo2-dev
    sudo apt install libuuid1
    sudo apt install libossp-uuid-dev
    sudo apt install libwebsockets-dev
    sudo apt install libssh2-1-dev
    sudo apt install libpango1.0-dev
    
    cd /path/to/guacamole-server-1.2.0
    ./configure --with-init-dir=/etc/init.d --with-systemd-dir=/etc/systemd/system --with-websockets --with-ssh
    sudo make install
    sudo systemctl start guacd
    

    Configuration

    Guacamole Server

    Copy the sassafras.json file into /etc/guacamole. Edit the file to contain the URL of the KeyServer in the server and uri values.

    {
    	"server": "https://keyserver.sample.net",
    	"uri": "https://keyserver.sample.net",
    	"websockets":false,
    	"guacdhost":"localhost",
    	"guacdport":4822,
    	"configs":[
    	]
    }
    
    The server parameter is what Java will use to talk to the KeyServer. Note that you can only use https:// if the server has a proper, trusted SSL certificate, otherwise use http://. The uri parameter is what is used for the UI (Back to Maps) button, so this can be customized with a frame-core for example, or even point to a specific Floorplan. Also include the port if it’s not the default (80 or 443 by protocol).

    Note the configs parameter may not be there by default, and is not needed unless you use scopes (see below).

    Copy the war file into tomcat’s web apps directory and remove the version string for ease of upgrade in the future.

       cp remote-broker-7.7.0.1.war /usr/local/tomcat9/webapps/remote-broker.war

    By removing the version string you can easily upgrade the war file in future releases by replacing the old one without needing to reconfigure the Sassafras server side. For example, minor improvements were made in 7.7.0.1 from 7.7.0.

    Restart Tomcat as needed to apply changes to the json and ensure the war file is unpacked by Guacamole and initialized. You will see a folder named remote-broker created in the webapps folder the first time this happens.

    Scope Options

    If needed, you can set up “common” passwords on a per-protocol, per-map, or per-computer basis by editing the sassafras.json file. These options are added to the configs section of the above file format. Simply add stanzas per the below example between the brackets. The value for each configuration stanza's “scope” can be one of:

    vnc://computerid
    computerid
    vnc://connectionaddress
    connectionaddress
    vnc://mapname
    mapname
    vnc://
    

    This specifies to use a specific protocol, or be independant of protocol, or replace “vnc” with “rdp” as needed. That is, you can scope to a specific id/address/map but not protocol, or to a protocol only (global), or to a specific protocol for a specific id/address/map depending on the syntax used.

    The configurations will be checked in the order written in the json file, first match wins.

    So for example if all the vnc computers in “Lab A” had a common name/pass, you’d have:

    	"configs":[
    	  {
    		"scope": "vnc://@Lab A",
    		"username": "bob",
    		"password": "secret"
    	  }
    	]
    

    Or if all the rdp computers had a common name/pass, you could use "rdp://Lab A” instead. Or if all the computers, regardless of vnc/rdp had the same name/pass, you’d just use “Lab A” for the scope.

    Note that each scope will be a separate stanza from other scopes, do not merge them. There must be a comma after the } if there is another stanza after it.

    Sassafras Server

    Once the Guacamole server is set up, you need to change the Remote Settings as needed on your Floorplans in the Sassafras Web UI. For example, set Mac to VNC Broker and Windows to RDP Broker, along with setting the Broker Server address and optionally using the Pass Full Credentials option if your users are authenticating to the Sassafras Web using Active Directory or LDAP.

    The URL for the Broker will be something like:

       http://guac.host.name:8080/remote-broker
    

    Note this assumes the default Tomcat port is being used, which is configurable if you like. It also assumes you followed the above information to rename the war file so it is easily upgraded. Also note the default Guacamole front end url pathing is not used here, so all you likely need to change from the example is your Sassafras server address.

    The account used to sign into the Sassafras web portal must have a new privilege on the computers you try to remote to. Computer Privileges -> Connect Remotely (via KeyReporter). This can be in a role the account holds, or you can use the Remote Connection Role for ease of adding this to existing accounts. You can also add that role to the KeyReporter Guest or Community if you want this to be open, or add it to your default account in a fully authenticated configuration.

    Note if you're using Active Directory as your authentication you must be using Secure Authentication not NTLM or Kerberos for the credentials to pass. For clarity, passing credentials will not work if you use one of the new SSO authentication options (Azure, Google, Okta).

    Tools

    Once you are connected to the remote machine, there is a toolbar that will drop down if you mouse to the top of the screen.

    Remote Desktop Toolbar

    The Sassafras logo will return you to our Web UI.

    The arrow buttons change the way screen size is handled. The "in" arrows are scale mode (default for VNC), which means whatever the remote resolution is set to we will fit it to the browser window. The "out" arrows are auto mode (default for RDP), which means the remote resolution will increase or decrease with the browser window. Either way we fit to the window, but scale could result in very tiny resolution, while auto will look more natural but is limited by your local screen size. Note that VNC (usually) does not respect auto mode.

    The clipboard box is for sending and retrieving text from the remote clipboard. If you paste in text, it will be available on the remote system for paste. If you copy text on the remote system, it will be available in the box to re-copy and paste locally.

    Troubleshooting

    There are a few common issues we have seen with customers setting up this integration. First and foremost, re-check the above information. Ensure you are using the required versions of Tomcat and Gaucamole. Also ensure you are using the latest WAR file as updates were made from 7.7.0.0 to 7.7.0.1 and are likely to happen again. Make sure you are using the proper urls in all locations, and the proper file syntax in the json file.

    If you receive a 512 error again check the above. This was last seen when a site used a pre 1.2 version of guacd.

    If you receive a 515 or 516 error check your network configuration. This tends to mean remote access is not enabled or reachable on the workstation, or the workstation can not reply to the Guac server. Remember in this scenario the workstation is the server and the guac server is the client when talking communication protocols.

    If you see a white screen and nothing more, it is likely you are experiencing an syntax issue with your domain authentication. Try logging in to our Web UI with user@domain syntax instead of domain\user syntax. It is also possible there are special characters in your division or computer identifiers that are unexpected or corruption in your station IDs. Contact us for assistance troubleshooting that issue.

    As always please contact support if you need assistance.