NAME GuacLite - Toolkit for implementing a frontend server/client the Apache Guacamole system DESCRIPTION GUACAMOLE SYSTEM OVERVIEW The Apache Guacamole system comprises several tools which used in combination can provide access to remote hosts via various protocols. The first component is a daemon, "Guacd", which is a compiled application that uses these various protocols to communicate with host computers. It then accepts inbound connections from clients which speak a unified protocol, called guacamole, to access those hosts. Guacd is therefore both a proxy/relay and a translator. In theory any system could connect to guacd but in practice there is a major client, the Java application called "guacamole-common". It is a server which serves a Javascript application and provides a websocket <-> tcp proxy/relay between the javascript application and guacd. It also has user, group, and host management, authentication, and policy management. Because of these extra features it requires persistence (a database) and api calls to add/update users and hosts in order to use it. Also, because it is written in Java any extension to the system must also be written in Java and served alongside it in a Tomcat or other JSP server. The Javascript application, called "guacamole-common-js", is a browser-native client for guacd with the exception that it speaks websocket rather than direct tcp. Therefore it requires a service that can provide that relay. It also sends keep-alive (ping/pong) messages that don't conform to the guacamole protocol and that the proxy must filter out and reply to. MOTIVATION AND COMPONENTS This project exists to allow non-Java projects that wish to use guacamole-common-js to access a guacd service, without having to conform to the usage expectations of guacamole-common, and without having to alter that application via Java. It provides a toolkit for implementing a frontend server/client to guacd via Perl and Mojolicious, without any built-in business logic (user management, host configuration). It provides the following components, each of which are independent and may be used with any Mojolicious application to provide or embed remote access via a guacd service. Guacd Client GuacLite::Client::Guacd is a Perl/Mojolicious client that communicates with a guacd service. It configures all relevant parameters for communicating with the guacd service and opening a connection to the remote host (including performing the requisite handshake). The current supported version of the protocol is 1.3.0 Guacd Websocket Tunneling Plugin GuacLite::Plugin::Guacd is a plugin that provides a helper method to establish a websocket connection between a client and a guacd service via a configured (but not connected) GuacLite::Client::Guacd instance. It initiates the guacd connection and triggers the handshake, it then passes messages between the guacd connection and the client's websocket, monitoring backpressure between them, and handling the keep-alive messages. In the future, passing a connected guacd client should be possible, but it hasn't been implemented yet. Utilities GuacLite::Util provides utilies for using the system. Currently it only provides one function which can bundle the guacamole-common-js files into a single javascript file and provide an initialize function to defer loading the javascript until necessary, which is required by some newer browsers. Example Web Application GuacLite::Client::Web is an example web application which is intended to be used as a reference and test implementation of the tools. It should function correctly but currently has almost no user interface and for the time being shouldn't be relied on to be in its current state. While the preceding libraries in the distribution are considered production ready and will only change if necessary, this example application can and may change without warning. In the future, perhaps this application will be made into a fully featured web client, however that risks falling into the (my opinion) feature creep seen in the original Java application that it replaces. guaclite script It includes an script which can start the example application or can be used to bundle the javascript via the utility function. See details of both above. Bundled Assets The distribution does include the bundled version guacamole-common-js. The exact version provided is not guaranteed. For production environments, it is encouraged that you download you own copy of the library and either bundle it with the utility or else bundle as you see fit. It also contains the templates/files for the example application, which are subject to the caveats of the example application itself. Containerization Files The distribution contains example Dockerfile and docker-compose.yml files to facilitate easy use of the example application and for deploying both it and a guacd service. These are provided as reference only and should not be relied upon for production use, owing to the same warning as previously about the stability of the example application. AUTHOR Joel Berger, CONTRIBUTORS None yet :) COPYRIGHT AND LICENSE This original work is copyright 2020 - 2021 by "AUTHOR" and "CONTRIBUTORS". This original work is licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. LICENSE NOTICE FOR BUNDLED WORKS This repository and/or library also bundles work from "Apache Guacamole" which is also licensed under the terms of the Apache 2.0 License.