Guacamole Plugin Extension User Guide › downloads › … · Guacamole Plugin Extension User Guide 2 Software Change Log Version Release Date Changes 1.0 9/19/2016 Initial Release

Guacamole Plugin Extension User Guide Version 1.0

Guacamole Plugin Extension User Guide

1

Introduction and Installation .......................................................................................................................................................... 2 Installation of the Guacamole Plugin Extension ............................................................................................................................ 2 Configuration and Usage ............................................................................................................................................................... 4

Creating a simple static Mashup to test and understand the widget .......................................................................................... 4 Creating a pop-up mashup with a remote desktop display ........................................................................................................ 6

Compatibility ................................................................................................................................................................................. 8 Document Revision History........................................................................................................................................................... 8 Appendix: Guacomole Server Installation ..................................................................................................................................... 9

Installation of the Guacamole Server....................................................................................................................................... 10


2

Software Change Log

Version Release Date Changes 1.0 9/19/2016 Initial Release

Introduction and Installation The Guacamole Plugin Extension leverages the capabilities of the Guacamole API for enabling remote desktop connections with other machines and devices.

Guacamole is an open-source clientless remote desktop gateway providing support for protocols such as RDP and VNC. This extension was created in conjunction with RDP, but it can be easily customized to support VNC as well.

Installation of the Guacamole Plugin Extension

The Guacamole Plugin Extension is an all-in-one package that contains both a UI widget as well as a servlet implementation for connecting to the guacamole daemon and the remote desktop. The installation of the guacamole daemon is explained in a separate section at the end of this document.

Follow the next steps in order to properly install the extension:

1. Download the GuacamolePlugin_Extension.zip package and go to your Thingworx instance. 2. Go to Import/Export tab in the right upper most menu and click on the Import link under

Extensions:

Please note that even though the guacamole daemon needs to reside in a Linux environment, the application server (e.g.) can be on any type of machine and operating system.


3

3. Choose the GuacamolePlugin_Extension.zip package from your download location on your machine and click on import.

4. Once the import is successful, refresh the composer so that the UI widget is loaded properly. The extension has been uploaded and is available at [ROOT]/ThingworxStorage/extensions/GuacamolePlugin_Extension

5. Go to [ROOT]/ThingworxStorage/extensions/GuacamolePlugin_Extension/lib/common and copy the following .JAR files: thingworx-guacamole-extension.jar guacamole-common-0.9.7.jar

6. Paste the .JAR files in [Tomcat_Home]/webapps/Thingworx/WEB-INF/lib

On Ubuntu, root privileges might be required for executing this operation. In this case, execute the following commands:

o cd [ROOT]/ThingworxStorage/extensions/GuacamolePlugin_Extension o sudo cp thingworx-guacamole-extension.jar guacamole-common-0.9.7.jar

[Tomcat_Home]/webapps/Thingworx/WEB-INF/lib o Enter your root password


4

7. Restart your Tomcat server. Do not skip this step as the servlet container needs to restart in order for the new servlet to be read at runtime.

8. You have successfully installed the Guacamole plugin. Navigate to the next section to see an

example of how you can use this widget in a Mashup.

Configuration and Usage

Creating a simple static Mashup to test and understand the widget

To initially test and see what types of properties this widget has, let’s create a simple static mash-up.

If you filter the list of widgets, you will find the Guacamole Widget:

Drag and drop it to your mashup canvas and resize as accordingly. Please note that the default size is 1024x768 and the remote desktop display will actually depend on the display size of your remote device.

In the IDE, the widget will not contain anything, except a message that informs the developer that area will be used for rendering the remote desktop.


5

Let’s have a look at the widgets properties and services.

The widget has five bindable properties and a service that will actually initiate the RDC.

Message A string property for displaying a text for the user in the IDE TargetMachineIP The address/Hostname of your target machine to which you want to

connect through RDP TargetMachinePort The port on which the RDC is initiated. This is 3389 by default for all

Windows machines. GuacamoleHost1 The host name for the guacamole daemon. By default this is localhost, but

it can be changed by the user. GuacamolePort The port on which the guacamole daemon listens. By default this is 4822,

but it can be changed by the user. Connect The service that actually creates a Guacamole Client and creates a tunnel

for facilitating the RDP connection.

1. Adjust the parameters depending on the device you want to access remotely and your guacamole daemon.

1 If your guacamole host is a Linux virtual machine, make sure you modify this to the IP address of the respective virtual machine


6

2. Go to Workspace tab and select the Mashup. The hover on the arrow and drag and drop the Loaded event on the Guacamole Widget and bind it to ‘Connect’ service.

3. In this simple example, every time the mashup is loaded, a new guacamole tunnel will be created and the remote desktop will be rendered in the mashup canvas at runtime.

4. Save and Test the Mashup. In your mashup the remote desktop should soon appear, prompting you for your login credentials (if the remote machine has login credentials)

Creating a pop-up mashup with a remote desktop display

Since the properties are bindable, you can use the Guacamole widget in a variety of scenarios.


7

The purpose of this example is to model our target device and pass the connection parameters via a service at runtime.

1. Create a Thing that has two String properties, the target host name and port.

2. Create a static mashup (1024x768) and add the Guacamole widget to it. 3. Go to Workspace tab and select Mashup and then hover on the top-left arrow inside the mashup

canvas, click on Configure Mashup Parameters

4. Add two mashup parameters for the target host name and the target IP address.

5. Bind the mashup parameters to the corresponding properties of the Guacamole Widget.

6. Bind the Loaded event from the mashup to the Connect service of the Guacamole widget. Name and save your mashup.

7. Create a new static mashup: add a button and label it Connect and also add a navigation widget.


8

8. Link the Navigation widget MashupName property to the other mashup you have just created, TargetWindows = popup and uncheck the Visible checkbox.

9. Bind the Click event from the button to the Navigate service of the Navigation widget.

10. In the Data panel, search and add the GetProperties service of your Thing –check Mashup Loaded. (In the composer, please set the properties for the port and hostname of the target machine).

11. Bind the TargetHostName and TargetRDPPort from the result to the parameters from the navigation widget, thus transferring the parameters at runtime.

12. Save and test the Mashup.

Compatibility This extension was tested for compatibility with the following ThingWorx Platform version(s) and Operating System(s):

ThingWorx Platform Version ThingWorx 7.1.0

OS Windows 7, Service Pack 1

Document Revision History

Revision Date Version Description of Change


9

Appendix: Guacomole Server Installation Before installing the extension, the user should be aware of the various components that are part of the Guacamole stack.

• Guacamole Daemon (guacd) which consists of a native Linux daemon that acts as a proxy between the web application server and the remote device and is the core of the Guacamole stack. The guacd dynamically loads support for the remote desktop connections based on the instructions received from the web application. The daemon builds on libguac, an open source C library which abstracts the communication between the web application (client) and the remote desktop.

Even though it’s possible, it is highly unadvisable to modify the source code for the guacamole daemon as it will reduce its performance.

• Web application which consists of the the following components:

o The User Interface, through which the end user actually accesses the remote desktop. This is implemented using the Guacamole Javascript API2 and provides functionalities for establishing a tunnel between the web browser and the remote device. It also provides support for mouse and keyboard controls and much more.

o The application server which will contain, among other things, a concrete implementation of the GuacamoleHTTPTunnelServlet. This will process the requests from the Guacamole client (the user interface/HTML page) and dispatch them to the guacamole daemon with connection parameters to the remote device. It leverages the Guacamole Java API.

2 Please note that the Guacamole Javascript API has been altered to support application/json format for sending requests, which is a Thingworx-compliant content type.


10

Installation of the Guacamole Server

Before installing the extension in Thingworx, the guacamole daemon is required to be installed. This is a native daemon process for Linux distributions so it will run optimally on any Linux-based operating system such as Ubuntu, Fedora, etc.

The rest of this chapter will provide instructions for installing guacamole daemon natively on an Ubuntu machine, which is one of the most popular Linux distributions. The installation process is easy and consists of the following steps:

The guacamole developers also provide an already installed guacamole server as a Docker image. The user only needs to have Docker installed on his machine and then just use the Docker image provided by Guacamole. Instructions for this installation are presented here and the download can be done from here.


11

1. Navigate to http://www.guac-dev.org and download the latest version of the guacamole server. At the moment when this document was written, the latest version the latest version was available here. You can find a list of older releases here.

2. Extract the folder with : tar -xzf guacamole-server-0.x.x.tar.gz copy it ( guacamole-server-0.x.x) to a convenient destination on your machine.

3. Before starting the build process for the guacamole-daemon, you need to make sure you have met all the required dependencies as the guacamole daemon relies on several libraries in order to compile.

!!! The first phase of build (configuring the make files) will not succeed if the required libraries are not installed.

The names of all the required and optional libraries and their corresponding packages for various Linux distributions are mentioned here.

4. Install the required libraries and in order to connect via RDP, also install the Free RDP library. You can enable additional support for your guacamole-daemon by installing a variety of other libraries such as for audio support, cryptography, SSH, etc.

Open a terminal window and copy and paste the following command: sudo apt-get install libcairo2-dev libjpeg62-turbo-dev libpng12-dev libossp-uuid-dev libfreerdp- dev libssh2 libtelnet libpango1.0-dev

5. Once the installation of the libraries is complete, you can proceed with the build. Change your working directory to [ROOT]/guacamole-server-0.x.x : cd [ROOT]/guacamole-server-0.x.x and then type: ./configure

If you would like to be able to configure the guacamole daemon to start automatically on system boot, add an option to your command: ./configure --with-init-dir=/etc/init.d

If you failed to meet any of the dependencies in step 4, go back and install the missing libraries. The result of the configure step should look like this:


12

6. In the same terminal window, type make to compile all the sources. The compilation is done recursively for all folders in your guacamole-server folder.

7. In the same terminal window, type sudo make install to install all the built components. This command is executed with root privileges.

8. Type sudo ldconfig to update the cache of your OS with the new libraries. 9. Now you are ready to use the guacamole daemon. To start this daemon process type:

sudo service guacd start

A message similar to this should be displayed:

Additional instructions for installing the guacamole server natively are presented here.


13

By default, the guacamole daemon will listen for requests on your localhost, on port 4822. To alter this, go to /etc/guacamole/guacd.conf and modify the listen address.

# Hostname and port of guacamole proxy guacd-hostname: localhost guacd-port: 4822

Documents

Guacamole Plugin Extension User Guide › downloads › … · Guacamole Plugin Extension User Guide 2 Software Change Log Version Release Date Changes 1.0 9/19/2016 Initial Release