| 1 | package GuacLite; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | |||
| 5 | our $VERSION = '0.02'; | ||
| 6 | $VERSION = eval $VERSION; | ||
| 7 | |||
| 8 | 1; | ||
| 9 | |||
| 10 | =head1 NAME | ||
| 11 | |||
| 12 | GuacLite - Toolkit for implementing a frontend server/client the Apache Guacamole system | ||
| 13 | |||
| 14 | =head1 DESCRIPTION | ||
| 15 | |||
| 16 | =head1 GUACAMOLE SYSTEM OVERVIEW | ||
| 17 | |||
| 18 | The L<Apache Guacamole system|https://guacamole.apache.org/> comprises several tools which used in combination can provide access to remote hosts via various protocols. | ||
| 19 | |||
| 20 | The first component is a daemon, "Guacd", which is a compiled application that uses these various protocols to communicate with host computers. | ||
| 21 | It then accepts inbound connections from clients which speak a unified protocol, called guacamole, to access those hosts. | ||
| 22 | Guacd is therefore both a proxy/relay and a translator. | ||
| 23 | |||
| 24 | In theory any system could connect to guacd but in practice there is a major client, the Java application called "guacamole-common". | ||
| 25 | It is a server which serves a Javascript application and provides a websocket <-> tcp proxy/relay between the javascript application and guacd. | ||
| 26 | It also has user, group, and host management, authentication, and policy management. | ||
| 27 | |||
| 28 | Because of these extra features it requires persistence (a database) and api calls to add/update users and hosts in order to use it. | ||
| 29 | 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. | ||
| 30 | |||
| 31 | 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. | ||
| 32 | Therefore it requires a service that can provide that relay. | ||
| 33 | 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. | ||
| 34 | |||
| 35 | =head1 MOTIVATION AND COMPONENTS | ||
| 36 | |||
| 37 | 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. | ||
| 38 | 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). | ||
| 39 | 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. | ||
| 40 | |||
| 41 | =head2 Guacd Client | ||
| 42 | |||
| 43 | L<GuacLite::Client::Guacd> is a Perl/L<Mojolicious> client that communicates with a guacd service. | ||
| 44 | It configures all relevant parameters for communicating with the guacd service and opening a connection to the remote host (including performing the requisite handshake). | ||
| 45 | |||
| 46 | The current supported version of the protocol is 1.3.0 | ||
| 47 | |||
| 48 | =head2 Guacd Websocket Tunneling Plugin | ||
| 49 | |||
| 50 | L<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) L<GuacLite::Client::Guacd> instance. | ||
| 51 | 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. | ||
| 52 | |||
| 53 | In the future, passing a connected guacd client should be possible, but it hasn't been implemented yet. | ||
| 54 | |||
| 55 | =head2 Utilities | ||
| 56 | |||
| 57 | L<GuacLite::Util> provides utilies for using the system. | ||
| 58 | 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. | ||
| 59 | |||
| 60 | =head2 Example Web Application | ||
| 61 | |||
| 62 | L<GuacLite::Client::Web> is an example web application which is intended to be used as a reference and test implementation of the tools. | ||
| 63 | 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. | ||
| 64 | 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. | ||
| 65 | |||
| 66 | 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. | ||
| 67 | |||
| 68 | =head2 guaclite script | ||
| 69 | |||
| 70 | It includes an script which can start the example application or can be used to bundle the javascript via the utility function. | ||
| 71 | See details of both above. | ||
| 72 | |||
| 73 | =head2 Bundled Assets | ||
| 74 | |||
| 75 | The distribution does include the bundled version guacamole-common-js. | ||
| 76 | The exact version provided is not guaranteed. | ||
| 77 | 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. | ||
| 78 | |||
| 79 | It also contains the templates/files for the example application, which are subject to the caveats of the example application itself. | ||
| 80 | |||
| 81 | =head2 Containerization Files | ||
| 82 | |||
| 83 | 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. | ||
| 84 | 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. | ||
| 85 | |||
| 86 | =head1 AUTHOR | ||
| 87 | |||
| 88 | Joel Berger, <joel.a.berger@gmail.com> | ||
| 89 | |||
| 90 | =head1 CONTRIBUTORS | ||
| 91 | |||
| 92 | None yet :) | ||
| 93 | |||
| 94 | =head1 COPYRIGHT AND LICENSE | ||
| 95 | |||
| 96 | This original work is copyright 2020 - 2021 by L</AUTHOR> and L</CONTRIBUTORS>. | ||
| 97 | |||
| 98 | This original work is licensed under the Apache License, Version 2.0 (the "License"); | ||
| 99 | you may not use this file except in compliance with the License. | ||
| 100 | You may obtain a copy of the License at | ||
| 101 | |||
| 102 | http://www.apache.org/licenses/LICENSE-2.0 | ||
| 103 | |||
| 104 | Unless required by applicable law or agreed to in writing, software | ||
| 105 | distributed under the License is distributed on an "AS IS" BASIS, | ||
| 106 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| 107 | See the License for the specific language governing permissions and | ||
| 108 | limitations under the License. | ||
| 109 | |||
| 110 | =head1 LICENSE NOTICE FOR BUNDLED WORKS | ||
| 111 | |||
| 112 | This repository and/or library also bundles work from L<"Apache Guacamole"|https://guacamole.apache.org/> | ||
| 113 | which is also licensed under the terms of the Apache 2.0 License. |