| Writing your own Guacamole application |
| ====================================== |
| |
| As Guacamole is an API, one of the best ways to put Guacamole to use is by |
| building your own Guacamole-driven web application, integrating HTML5 remote |
| desktop into whatever you think needs it. |
| |
| The Guacamole project provides an example of doing this called |
| "guacamole-example", but this example is already completed for you, and from a |
| quick glance at this example, it may not be obvious just how easy it is to |
| integrate remote access into a web application. This tutorial will walk you |
| through the basic steps of building an HTML5 remote desktop application using |
| the Guacamole API and Maven. |
| |
| (basic-guacamole-architecture)= |
| |
| The basics |
| ---------- |
| |
| Guacamole's architecture is made up of many components, but it's actually |
| straightforward, especially from the perspective of the web application. |
| |
| Guacamole has a proxy daemon, guacd, which handles communication using remote |
| desktop protocols, exposing those to whatever connects to it (in this case, the |
| web application) using the Guacamole protocol. From where the web application |
| is standing, it doesn't really matter that guacd dynamically loads protocol |
| plugins or that it shares a common library allowing this; all that matters is |
| that the web application just has to connect to port 4822 (where guacd listens |
| by default) and use the Guacamole protocol. The architecture will take care of |
| the rest. |
| |
| Thankfully, the Java side of the Guacamole API provides simple classes which |
| already implement the Guacamole protocol with the intent of tunneling it |
| between guacd and the JavaScript half of your web application. A typical web |
| application leveraging these classes needs |
| only the following: |
| |
| 1. A class which extends `GuacamoleHTTPTunnelServlet`, providing the tunnel |
| between the JavaScript client (presumably using guacamole-common-js) and |
| guacd. |
| |
| `GuacamoleHTTPTunnelServlet` is an abstract class which is provided by the |
| Guacamole API and already implements a fully functional, HTTP-based tunnel |
| which the tunneling objects already part of guacamole-common-js are written |
| to connect to. This class exists to make it easy for you to use Guacamole's |
| existing and robust HTTP tunnel implementation. |
| |
| If you want to not use this class and instead use your own tunneling |
| mechanism, perhaps WebSocket, this is fine; the JavaScript object mentioned |
| above implements a common interface which you can also implement, and the |
| Guacamole JavaScript client which is also part of guacamole-common-js will |
| happily use your implementation as long as it provides that interface. |
| |
| 2. A web page which includes JavaScript files from guacamole-common-js and uses |
| the client and tunnel objects to connect back to the web application. |
| |
| The JavaScript API provided by the Guacamole project includes a full |
| implementation of the Guacamole protocol as a client, implementations of |
| HTTP and WebSocket-based tunnels, and mouse/keyboard/touch input |
| abstraction. Again, as the Guacamole protocol and all parts of the |
| architecture are documented here, you don't absolutely need to use these |
| objects, but it will make your life easier. Mouse and keyboard support in |
| JavaScript is finicky business, and the Guacamole client provided is |
| well-known to work with other components in the API, being the official |
| client of the project. |
| |
| That's really all there is to it. |
| |
| If you want authentication, the place to implement that would be in your |
| extended version of `GuacamoleHTTPTunnelServlet`; this is what the Guacamole |
| web application does. Besides authentication, there are many other things you |
| could wrap around your remote desktop application, but ultimately the base of |
| all this is simple: you have a tunnel which allows the JavaScript client to |
| communicate with guacd, and you have the JavaScript client itself, with the |
| hard part already provided within guacamole-common-js. |
| |
| (web-app-skeleton)= |
| |
| Web application skeleton |
| ------------------------ |
| |
| As with most tutorials, this tutorial begins with creating a project skeleton |
| that establishes a minimal base for the tutorial to enhance in subsequent |
| steps. |
| |
| This tutorial will use Maven, which is the same build system used by the |
| upstream Guacamole project. As the Guacamole project has a Maven repository for |
| both the Java and JavaScript APIs, writing a Guacamole-based application using |
| Maven is much easier; Maven will download and use the Guacamole API |
| automatically. |
| |
| ### `pom.xml` |
| |
| All Maven projects must have a project descriptor, the `pom.xml` file, in the |
| root directory of the project. This file describes project dependencies and |
| specific build requirements. Unlike other build tools like Apache Ant or GNU |
| Autotools, Maven chooses convention over configuration: files within the |
| project must be placed in specific locations, and the project dependencies must |
| be fully described in the pom.xml. If this is done, the build will be handled |
| automatically. |
| |
| The basis of this Guacamole-driven web application will be a simple HTML file |
| which will ultimately become the client. While the finished product will have |
| an HTTP tunnel written in Java, we don't need this yet for our skeleton. We |
| will create a very basic, barebones Maven project containing only `index.html` |
| and a web application descriptor file, `web.xml`. Once these files are in |
| place, the project can be packaged into a `.war` file which can be deployed to |
| your servlet container of choice (such as Apache Tomcat). |
| |
| As this skeleton will contain no Java code, it has no dependencies, and |
| no build requirements beyond the metadata common to any Maven project. |
| The `pom.xml` is thus very simple for the time being: |
| i |
| ```xml |
| <project xmlns="http://maven.apache.org/POM/4.0.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 |
| http://maven.apache.org/maven-v4_0_0.xsd"> |
| |
| <modelVersion>4.0.0</modelVersion> |
| <groupId>org.apache.guacamole</groupId> |
| <artifactId>guacamole-tutorial</artifactId> |
| <packaging>war</packaging> |
| <version>1.5.5</version> |
| <name>guacamole-tutorial</name> |
| |
| <properties> |
| <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> |
| </properties> |
| |
| </project> |
| ``` |
| |
| ### `WEB-INF/web.xml` |
| |
| Before the project will build, there needs to be a web application deployment |
| descriptor, `web.xml`. This file is required by the Java EE standard for |
| building the `.war` file which will contain the web application, and will be |
| read by the servlet container when the application is actually deployed. For |
| Maven to find and use this file when building the `.war`, it must be placed in |
| the `src/main/webapp/WEB-INF/` directory. |
| |
| ```xml |
| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <web-app version="2.5" |
| xmlns="http://java.sun.com/xml/ns/javaee" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://java.sun.com/xml/ns/javaee |
| http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> |
| |
| <!-- Basic config --> |
| <welcome-file-list> |
| <welcome-file>index.html</welcome-file> |
| </welcome-file-list> |
| |
| </web-app> |
| ``` |
| |
| ### `index.html` |
| |
| With the `web.xml` file in place and the skeleton `pom.xml` written, the web |
| application will now build successfully. However, as the `web.xml` refers to a |
| "welcome file" called `index.html` (which will ultimately contain our client), |
| we need to put this in place so the servlet container will have something to |
| serve. This file, as well as any other future static files, belongs within |
| `src/main/webapp`. |
| |
| For now, this file can contain anything, since the other parts of our |
| Guacamole-driven web application are not written yet. It is a placeholder which |
| we will replace later: |
| |
| ```html |
| <!DOCTYPE HTML> |
| <html> |
| |
| <head> |
| <title>Guacamole Tutorial</title> |
| </head> |
| |
| <body> |
| <p>Hello World</p> |
| </body> |
| |
| </html> |
| ``` |
| |
| ### Building the skeleton |
| |
| Once all three of the above files are in place, the web application will build, |
| and can even be deployed to your servlet container. It won't do anything yet |
| other than serve the `index.html` file, but it's good to at least try building |
| the web application to make sure nothing is missing and all steps were followed |
| correctly before proceeding: |
| |
| ```console |
| $ mvn package |
| [INFO] Scanning for projects... |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] Building guacamole-tutorial |
| [INFO] task-segment: [package] |
| [INFO] ------------------------------------------------------------------------ |
| ... |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] BUILD SUCCESSFUL |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] Total time: 4 seconds |
| [INFO] Finished at: Fri Jan 11 13:04:11 PST 2013 |
| [INFO] Final Memory: 18M/128M |
| [INFO] ------------------------------------------------------------------------ |
| $ |
| ``` |
| |
| Assuming you see the "`BUILD SUCCESSFUL`" message when you build the web |
| application, there will be a new file, `target/guacamole-tutorial-1.5.5.war`, |
| which can be deployed to your servlet container and tested. If you changed the |
| name or version of the project in the `pom.xml` file, the name of this new |
| `.war` file will be different, but it can still be found within `target/`. |
| |
| (guacamole-skeleton)= |
| |
| Adding Guacamole |
| ---------------- |
| |
| Once we have a functional web application built, the next step is to actually |
| add the references to the Guacamole API and integrate a Guacamole client into |
| the application. |
| |
| (adding-guac-to-pom)= |
| |
| ### Updating `pom.xml` |
| |
| Now that we're adding Guacamole components to our project, we need to modify |
| `pom.xml` to specify which components are being used, and where they can be |
| obtained. With this information in place, Maven will automatically resolve |
| dependencies and download them as necessary during the build. |
| |
| Regarding the build process itself, there are two main changes: we are now |
| going to be using Java, and we need the JavaScript files from |
| guacamole-common-js included automatically inside the `.war`. |
| |
| Guacamole requires at least Java 8, thus we must add a section to the |
| `pom.xml` which describes the source and target Java versions: |
| |
| ```xml |
| ... |
| |
| <build> |
| <plugins> |
| |
| <!-- Compile using Java 8 --> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-compiler-plugin</artifactId> |
| <version>3.3</version> |
| <configuration> |
| <source>1.8</source> |
| <target>1.8</target> |
| </configuration> |
| </plugin> |
| |
| </plugins> |
| |
| </build> |
| |
| ... |
| ``` |
| |
| Including the JavaScript files from an external project like |
| guacamole-common-js requires using a feature of the maven war plugin called |
| overlays. To add an overlay containing guacamole-common-js, we add a section |
| describing the configuration of the Maven war plugin, listing |
| guacamole-common-js as an overlay: |
| |
| ```xml |
| ... |
| |
| <build> |
| <plugins> |
| |
| ... |
| |
| <!-- Overlay guacamole-common-js (zip) --> |
| <plugin> |
| <groupId>org.apache.maven.plugins</groupId> |
| <artifactId>maven-war-plugin</artifactId> |
| <version>2.6</version> |
| <configuration> |
| <overlays> |
| <overlay> |
| <groupId>org.apache.guacamole</groupId> |
| <artifactId>guacamole-common-js</artifactId> |
| <type>zip</type> |
| </overlay> |
| </overlays> |
| </configuration> |
| </plugin> |
| |
| </plugins> |
| |
| </build> |
| |
| ... |
| ``` |
| |
| With the build now configured, we still need to add dependencies and list the |
| repositories those dependencies can be downloaded from. |
| |
| As this is a web application which will use the Java Servlet API, we must |
| explicitly include this as a dependency, as well as the Guacamole Java and |
| JavaScript APIs: |
| |
| ```xml |
| ... |
| |
| <dependencies> |
| |
| <!-- Servlet API --> |
| <dependency> |
| <groupId>javax.servlet</groupId> |
| <artifactId>servlet-api</artifactId> |
| <version>2.5</version> |
| <scope>provided</scope> |
| </dependency> |
| |
| <!-- Main Guacamole library --> |
| <dependency> |
| <groupId>org.apache.guacamole</groupId> |
| <artifactId>guacamole-common</artifactId> |
| <version>1.5.5</version> |
| <scope>compile</scope> |
| </dependency> |
| |
| <!-- Guacamole JavaScript library --> |
| <dependency> |
| <groupId>org.apache.guacamole</groupId> |
| <artifactId>guacamole-common-js</artifactId> |
| <version>1.5.5</version> |
| <type>zip</type> |
| <scope>runtime</scope> |
| </dependency> |
| |
| </dependencies> |
| |
| ... |
| ``` |
| |
| The Java Servlet API will be provided by your servlet container, so Maven does |
| not need to download it during the build, and it need not exist in any Maven |
| repository. |
| |
| With these changes, the web application will still build at this point, even |
| though no Java code has been written yet. You may wish to verify that |
| everything still works. |
| |
| If the `pom.xml` was updated properly as described above, the web application |
| should build successfully, and the Guacamole JavaScript API should be |
| accessible in the `guacamole-common-js/` subdirectory of your web application |
| after it is deployed. A quick check that you can access |
| `/guacamole-tutorial-1.5.5/guacamole-common-js/all.min.js` is probably worth |
| the effort. |
| |
| (simple-tunnel)= |
| |
| ### The simplest tunnel possible |
| |
| As with the other tutorials in this book, we will keep this simple for the sake |
| of demonstrating the principles behind a Guacamole-based web application, and |
| to give developers a good idea of where to start looking when it's time to |
| consult the API documentation. |
| |
| It is the duty of the class extending `GuacamoleHTTPTunnelServlet` to implement |
| a function called `doConnect()`. This is the only function required to be |
| implemented, and in general it is the only function you should implement; the |
| other functions involved are already optimized for tunneling the Guacamole |
| protocol. |
| |
| The `doConnect()` function returns a `GuacamoleTunnel`, which provides a |
| persistent communication channel for `GuacamoleHTTPTunnelServlet` to use when |
| talking with guacd and initiating a connection with some arbitrary remote |
| desktop using some arbitrary remote desktop protocol. In our simple tunnel, |
| this configuration will be hard-coded, and no authentication will be attempted. |
| Any user accessing this web application will be immediately given a functional |
| remote desktop, no questions asked. |
| |
| Create a new file, `TutorialGuacamoleTunnelServlet.java`, defining a basic |
| implementation of a tunnel servlet class: |
| |
| ```java |
| package org.apache.guacamole.net.example; |
| |
| import javax.servlet.http.HttpServletRequest; |
| import org.apache.guacamole.GuacamoleException; |
| import org.apache.guacamole.net.GuacamoleSocket; |
| import org.apache.guacamole.net.GuacamoleTunnel; |
| import org.apache.guacamole.net.InetGuacamoleSocket; |
| import org.apache.guacamole.net.SimpleGuacamoleTunnel; |
| import org.apache.guacamole.protocol.ConfiguredGuacamoleSocket; |
| import org.apache.guacamole.protocol.GuacamoleConfiguration; |
| import org.apache.guacamole.servlet.GuacamoleHTTPTunnelServlet; |
| |
| public class TutorialGuacamoleTunnelServlet |
| extends GuacamoleHTTPTunnelServlet { |
| |
| @Override |
| protected GuacamoleTunnel doConnect(HttpServletRequest request) |
| throws GuacamoleException { |
| |
| // Create our configuration |
| GuacamoleConfiguration config = new GuacamoleConfiguration(); |
| config.setProtocol("vnc"); |
| config.setParameter("hostname", "localhost"); |
| config.setParameter("port", "5901"); |
| config.setParameter("password", "potato"); |
| |
| // Connect to guacd - everything is hard-coded here. |
| GuacamoleSocket socket = new ConfiguredGuacamoleSocket( |
| new InetGuacamoleSocket("localhost", 4822), |
| config |
| ); |
| |
| // Return a new tunnel which uses the connected socket |
| return new SimpleGuacamoleTunnel(socket);; |
| |
| } |
| |
| } |
| ``` |
| |
| Place this file in the `src/main/java/org/apache/guacamole/net/example` |
| subdirectory of the project. The initial part of this subdirectory, |
| `src/main/java`, is the path required by Maven, while the rest is the directory |
| required by Java based on the package associated with the class. |
| |
| Once the class defining our tunnel is created, it must be added to the |
| `web.xml` such that the servlet container knows which URL maps to it. This URL |
| will later be given to the JavaScript client to establish the connection back |
| to the Guacamole server: |
| |
| ```xml |
| ... |
| |
| <!-- Guacamole Tunnel Servlet --> |
| <servlet> |
| <description>Tunnel servlet.</description> |
| <servlet-name>Tunnel</servlet-name> |
| <servlet-class> |
| org.apache.guacamole.net.example.TutorialGuacamoleTunnelServlet |
| </servlet-class> |
| </servlet> |
| |
| <servlet-mapping> |
| <servlet-name>Tunnel</servlet-name> |
| <url-pattern>/tunnel</url-pattern> |
| </servlet-mapping> |
| |
| ... |
| ``` |
| |
| The first section assigns a unique name, "Tunnel", to the servlet class we just |
| defined. The second section maps the servlet class by it's servlet name |
| ("Tunnel") to the URL we wish to use when making HTTP requests to the servlet: |
| `/tunnel`. This URL is relative to the context root of the web application. In |
| the case of this web application, the final absolute URL will be |
| `/guacamole-tutorial-1.5.5/tunnel`. |
| |
| (simple-client)= |
| |
| ### Adding the client |
| |
| As the Guacamole JavaScript API already provides functional client and tunnel |
| implementations, as well as mouse and keyboard input objects, the coding |
| required for the "web" side of the web application is very minimal. |
| |
| We must create a `Guacamole.HTTPTunnel`, connect it to our |
| previously-implemented tunnel servlet, and pass that tunnel to a new |
| `Guacamole.Client`. Once that is done, and the `connect()` function of the |
| client is called, communication will immediately ensue, and your remote desktop |
| will be visible: |
| |
| ```html |
| ... |
| <body> |
| |
| <!-- Guacamole --> |
| <script type="text/javascript" |
| src="guacamole-common-js/all.min.js"></script> |
| |
| <!-- Display --> |
| <div id="display"></div> |
| |
| <!-- Init --> |
| <script type="text/javascript"> /* <![CDATA[ */ |
| |
| // Get display div from document |
| var display = document.getElementById("display"); |
| |
| // Instantiate client, using an HTTP tunnel for communications. |
| var guac = new Guacamole.Client( |
| new Guacamole.HTTPTunnel("tunnel") |
| ); |
| |
| // Add client to display div |
| display.appendChild(guac.getDisplay().getElement()); |
| |
| // Error handler |
| guac.onerror = function(error) { |
| alert(error); |
| }; |
| |
| // Connect |
| guac.connect(); |
| |
| // Disconnect on close |
| window.onunload = function() { |
| guac.disconnect(); |
| } |
| |
| /* ]]> */ </script> |
| |
| </body> |
| ... |
| ``` |
| |
| If you build and deploy the web application now, it will work, but mouse and |
| keyboard input will not. This is because input is not implemented by the client |
| directly. The `Guacamole.Client` object only decodes the Guacamole protocol and |
| handles the display, providing an element which you can add manually to the |
| DOM. While it will also send keyboard and mouse events for you, you need to |
| call the respective functions manually. The Guacamole API provides keyboard and |
| mouse abstraction objects which make this easy. |
| |
| We need only create a `Guacamole.Mouse` and `Guacamole.Keyboard`, and add event |
| handlers to handle their corresponding input events, calling whichever function |
| of the Guacamole client is appropriate to send the input event through the |
| tunnel to guacd: |
| |
| ```html |
| ... |
| |
| <!-- Init --> |
| <script type="text/javascript"> /* <![CDATA[ */ |
| |
| ... |
| |
| // Mouse |
| var mouse = new Guacamole.Mouse(guac.getDisplay().getElement()); |
| |
| mouse.onmousedown = |
| mouse.onmouseup = |
| mouse.onmousemove = function(mouseState) { |
| guac.sendMouseState(mouseState); |
| }; |
| |
| // Keyboard |
| var keyboard = new Guacamole.Keyboard(document); |
| |
| keyboard.onkeydown = function (keysym) { |
| guac.sendKeyEvent(1, keysym); |
| }; |
| |
| keyboard.onkeyup = function (keysym) { |
| guac.sendKeyEvent(0, keysym); |
| }; |
| |
| /* ]]> */ </script> |
| |
| ... |
| ``` |
| |
| (next-steps)= |
| |
| Where to go from here |
| --------------------- |
| |
| At this point, we now have a fully functional Guacamole-based web application. |
| This web application inherits all the core functionality present in the |
| official Guacamole web application, including sound and video, without very |
| much coding. |
| |
| Extending this application to provide authentication, multiple connections per |
| user, or a spiffy interface which is compatible with mobile is not too much of |
| a stretch. This is exactly how the Guacamole web application is written. |
| Integrating Guacamole into an existing application would be similar. |
| |
