Guacamole Plugin Extension
User Guide Version 1.0
Copyright © 2016 PTC Inc. and/or Its Subsidiary Companies. All Rights Reserved.
User and training guides and related documentation from PTC Inc. and its subsidiary companies (collectively “PTC”) are subject to the copyright
laws of the United States and other countries and are provided under a license agreement that restricts copying, disclosure, and use of such
documentation. PTC hereby grants to the licensed software user the right to make copies in printed form of this documentation if provided on
software media, but only for internal/personal use and in accordance with the license agreement under which the applicable software is licensed.
Any copy made shall include the PTC copyright notice and any other proprietary notice provided by PTC. Training materials may not be copied
without the express written consent of PTC. This documentation may not be disclosed, transferred, modified, or reduced to any form, including
electronic media, or transmitted or made publicly available by any means without the prior written consent of PTC and no authorization is
granted to make copies for such purposes.
Information described herein is furnished for general information only, is subject to change without notice, and should not be construed as a
warranty or commitment by PTC. PTC assumes no responsibility or liability for any errors or inaccuracies that may appear in this document.
The software described in this document is provided under written license agreement, contains valuable trade secrets and proprietary information,
and is protected by the copyright laws of the United States and other countries. It may not be copied or distributed in any form or medium,
disclosed to third parties, or used in any manner not provided for in the software licenses agreement except with written prior approval from PTC.
UNAUTHORIZED USE OF SOFTWARE OR ITS DOCUMENTATION CAN RESULT IN CIVIL DAMAGES AND CRIMINAL
PROSECUTION. PTC regards software piracy as the crime it is, and we view offenders accordingly. We do not tolerate the piracy of PTC
software products, and we pursue (both civilly and criminally) those who do so using all legal means available, including public and private
surveillance resources. As part of these efforts, PTC uses data monitoring and scouring technologies to obtain and transmit data on users of illegal
copies of our software. This data collection is not performed on users of legally licensed software from PTC and its authorized distributors. If you
are using an illegal copy of our software and do not consent to the collection and transmission of such data (including to the United States), cease
using the illegal version, and contact PTC to obtain a legally licensed copy.
Important Copyright, Trademark, Patent, and Licensing Information: See the About Box, or copyright notice, of your PTC software.
UNITED STATES GOVERNMENT RESTRICTED RIGHTS LEGEND
This document and the software described herein are Commercial Computer Documentation and Software, pursuant to FAR 12.212(a)-(b)
(OCT’95) or DFARS 227.7202-1(a) and 227.7202-3(a) (JUN’95), and are provided to the US Government under a limited commercial license
only. For procurements predating the above clauses, use, duplication, or disclosure by the Government is subject to the restrictions set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 252.227-7013 (OCT’88) or Commercial
Computer Software-Restricted Rights at FAR 52.227-19(c)(1)-(2) (JUN’87), as applicable. 01012015
PTC Inc., 140 Kendrick Street, Needham, MA 02494 USA
Software Change Log ....................................................................................................................................2
Guacamole Plugin Extension User Guide
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
1
Guacamole Plugin Extension User Guide
Software Change Log
Version
1.0
Release Date
9/19/2016
Changes
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.
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.
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:
2
Guacamole Plugin Extension User Guide
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
The concrete implementation of the Guacamole servlet in Thingworx is distributed as a .jar file.
At runtime, the servlet container (e.g. Tomcat) will receive requests and dispatch them to the
appropriate servlet based on how they are mapped.
In Thingworx, all servlets are distributed as .jar files and are located in
[Tomcat_Home]/webapps/Thingworx/WEB-INF/lib
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
o
o
cd [ROOT]/ThingworxStorage/extensions/GuacamolePlugin_Extension
sudo cp thingworx-guacamole-extension.jar guacamole-common-0.9.7.jar
[Tomcat_Home]/webapps/Thingworx/WEB-INF/lib
Enter your root password
3
Guacamole Plugin Extension User Guide
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.
4
Guacamole Plugin Extension User Guide
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
TargetMachineIP
TargetMachinePort
GuacamoleHost1
GuacamolePort
Connect
A string property for displaying a text for the user in the IDE
The address/Hostname of your target machine to which you want to
connect through RDP
The port on which the RDC is initiated. This is 3389 by default for all
Windows machines.
The host name for the guacamole daemon. By default this is localhost, but
it can be changed by the user.
The port on which the guacamole daemon listens. By default this is 4822,
but it can be changed by the user.
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
IfyourguacamolehostisaLinuxvirtualmachine,makesureyoumodifythistotheIPaddressoftherespective
virtualmachine
5
Guacamole Plugin Extension User Guide
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.
6
Guacamole Plugin Extension User Guide
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.
7
Guacamole Plugin Extension User Guide
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
OS
ThingWorx 7.1.0
Windows 7, Service Pack 1
Document Revision History
Revision Date
Version
Description of Change
8
Guacamole Plugin Extension User Guide
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
PleasenotethattheGuacamoleJavascriptAPIhasbeenalteredtosupportapplication/jsonformatforsending
requests,whichisaThingworx-compliantcontenttype.
9
Guacamole Plugin Extension User Guide
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 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.
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:
10
Guacamole Plugin Extension User Guide
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 libfreerdpdev 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:
11
Guacamole Plugin Extension User Guide
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.
12
Guacamole Plugin Extension User Guide
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
For example, if you have your Tomcat server on one machine and you are using a Linux box for
hosting the Guacamole daemon, you should add the IP address of the virtual machine as the
guacd-hostname.
# Hostname and port of guacamole proxy
guacd-hostname: 192.168.43.136
guacd-port: 4822
13