README (6108B)
1 2------------------------------------------------------------ 3 About this README 4------------------------------------------------------------ 5 6This README is intended to provide quick and to-the-point documentation for 7technical users intending to compile parts of Apache Guacamole themselves. 8 9Source archives are available from the downloads section of the project website: 10 11 http://guacamole.apache.org/ 12 13A full manual is available as well: 14 15 http://guacamole.apache.org/doc/gug/ 16 17 18------------------------------------------------------------ 19 What is guacamole-server? 20------------------------------------------------------------ 21 22The guacamole-server package is a set of software which forms the basis of the 23Guacamole stack. It consists of guacd, libguac, and several protocol support 24libraries. 25 26guacd is the Guacamole proxy daemon used by the Guacamole web application and 27framework. As JavaScript cannot handle binary protocols (like VNC and remote 28desktop) efficiently, a new text-based protocol was developed which would 29contain a common superset of the operations needed for efficient remote desktop 30access, but would be easy for JavaScript programs to process. guacd is the 31proxy which translates between arbitrary protocols and the Guacamole protocol. 32 33 34------------------------------------------------------------ 35 Required dependencies 36------------------------------------------------------------ 37 38All software within guacamole-server is built using the popular GNU Automake, 39and thus provides the standard configure script. Before compiling, at least 40the following required dependencies must already be installed: 41 42 1) Cairo (http://cairographics.org/) 43 44 2) libjpeg-turbo (http://libjpeg-turbo.virtualgl.org/) 45 OR libjpeg (http://www.ijg.org/) 46 47 3) libpng (http://www.libpng.org/pub/png/libpng.html) 48 49 4) OSSP UUID (http://www.ossp.org/pkg/lib/uuid/) 50 51 52------------------------------------------------------------ 53 Optional dependencies 54------------------------------------------------------------ 55 56In addition, the following optional dependencies may be installed in order to 57enable optional features of Guacamole. Note that while the various supported 58protocols are technically optional, you will no doubt wish to install the 59dependencies of at least ONE supported protocol, as Guacamole would be useless 60otherwise. 61 62 RDP: 63 * FreeRDP (http://www.freerdp.com/) 64 65 SSH: 66 * libssh2 (http://www.libssh2.org/) 67 * OpenSSL (https://www.openssl.org/) 68 * Pango (http://www.pango.org/) 69 70 Telnet: 71 * libtelnet (https://github.com/seanmiddleditch/libtelnet) 72 * Pango (http://www.pango.org/) 73 74 VNC: 75 * libVNCserver (http://libvnc.github.io/) 76 77 Support for audio within VNC: 78 * PulseAudio (http://www.freedesktop.org/wiki/Software/PulseAudio/) 79 80 Support for SFTP file transfer for VNC or RDP: 81 * libssh2 (http://www.libssh2.org/) 82 * OpenSSL (https://www.openssl.org/) 83 84 Support for WebP image compression: 85 * libwebp (https://developers.google.com/speed/webp/) 86 87 "guacenc" video encoding utility: 88 * FFmpeg (https://ffmpeg.org/) 89 90 91------------------------------------------------------------ 92 Compiling and installing guacd, libguac, etc. 93------------------------------------------------------------ 94 95All software within guacamole-server is built using the popular GNU Automake, 96and thus provides the standard configure script. 97 981) Run configure 99 100 $ ./configure 101 102 Assuming all dependencies have been installed, this should succeed without 103 errors. If you wish to install the init script as well, you need to specify 104 the location where your system init scripts are located (typically 105 /etc/init.d): 106 107 $ ./configure --with-init-dir=/etc/init.d 108 109 Running configure in this manner will cause the "make install" step to 110 install an init script to the specified directory, which you can then 111 activate using the service management mechanism provided by your 112 distribution). 113 1142) Run make 115 116 $ make 117 118 guacd, libguac, and any available protocol support libraries will now 119 compile. 120 1213) Install (as root) 122 123 # make install 124 125 All software that was just built, including documentation, will be 126 installed. 127 128 guacd will install to your /usr/local/sbin directory by default. You can 129 change the install location by using the --prefix option for configure. 130 131 132------------------------------------------------------------ 133 Running guacd 134------------------------------------------------------------ 135 136If you installed the init script during compile and install, you should be 137able to start guacd through the service management utilities provided by 138your distribution (if any) or by running the init script directly (as root): 139 140 # /etc/init.d/guacd start 141 142Root access is needed to write the pidfile /var/run/guacd.pid. You can also run 143guacd itself directly without the init script (as any user): 144 145 $ guacd 146 147guacd currently takes several command-line options: 148 149 -b HOST 150 151 Changes the host or address that guacd listens on. 152 153 -l PORT 154 155 Changes the port that guacd listens on (the default is port 4822). 156 157 -p PIDFILE 158 159 Causes guacd to write the PID of the daemon process to the specified 160 file. This is useful for init scripts and is used by the provided init 161 script. 162 163 -L LEVEL 164 165 Sets the maximum level at which guacd will log messages to syslog and, 166 if running in the foreground, the console. Legal values are debug, 167 info, warning, and error. The default value is info. 168 169 -f 170 Causes guacd to run in the foreground, rather than automatically 171 forking into the background. 172 173Additional information can be found in the guacd man page: 174 175 $ man guacd 176 177------------------------------------------------------------ 178 Reporting problems 179------------------------------------------------------------ 180 181Please report any bugs encountered by opening a new issue in the JIRA system 182hosted at: 183 184 https://issues.apache.org/jira/browse/GUACAMOLE 185