mike-jumper commented on a change in pull request #165: URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642142127
########## File path: src/installing-guacamole.md ########## @@ -0,0 +1,741 @@ +Installing Guacamole natively +============================= + +Guacamole is separated into two pieces: guacamole-server, which provides the +guacd proxy and related libraries, and guacamole-client, which provides the +client to be served by your servlet container, usually [Apache +Tomcat](http://tomcat.apache.org/). + +guacamole-client is available in binary form, but guacamole-server must be +built from source. Don't be discouraged: building the components of Guacamole +from source is *not* as difficult as it sounds, and the build process is +automated. You just need to be sure you have the necessary tools installed +ahead of time. With the necessary dependencies in place, building Guacamole +only takes a few minutes. + +(building-guacamole-server)= + +Building guacamole-server +------------------------- + +guacamole-server contains all the native, server-side components required by +Guacamole to connect to remote desktops. It provides a common C library, +libguac, which all other native components depend on, as well as separate +libraries for each supported protocol, and guacd, the heart of Guacamole. + +guacd is the proxy daemon that runs on your Guacamole server, accepts users' +connections that are tunneled through the Guacamole web application, and then +connects to remote desktops on their behalf. Building guacd creates an +executable called {program}`guacd` which can be run manually or, if you wish, +automatically when your computer starts up. + +To build guacamole-server, you will need a C compiler (such as gcc) and the +libraries that guacamole-server depends on. Some dependencies are absolutely +required, while others are optional. The presence of optional dependencies +enables additional features. + +:::{important} +Many Linux distributions separate library packages into binary and +"development" packages; *you will need to install the development packages*. +These will usually end in a "-dev" or "-devel" suffix. +::: + +### Required dependencies + +In order to build guacamole-server, you will need Cairo, libjpeg, +libpng, and the OSSP UUID library. These libraries are strictly required +*in all cases* - Guacamole cannot be built without them. + + +[Cairo](http://cairographics.org/) +: Cairo is used by libguac for graphics rendering. Guacamole cannot function + without Cairo installed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libcairo2-dev` + * - Fedora / CentOS / RHEL package + - `cairo-devel` + ::: + +[libjpeg-turbo](http://libjpeg-turbo.virtualgl.org/) +: libjpeg-turbo is used by libguac to provide JPEG support. Guacamole will not + build without this library present: + + :::{list-table} + :stub-columns: 1 + * - Debian package + - `libjpeg62-turbo-dev` + * - Ubuntu package + - `libjpeg-turbo8-dev` + * - Fedora / CentOS / RHEL package + - `libjpeg-turbo-devel` + ::: + + If libjpeg-turbo is unavailable on your platform, and you do not wish to + build it from source, [libjpeg](http://www.ijg.org/) will work as well, + though it will not be quite as fast: + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libjpeg62-dev` + * - Fedora / CentOS / RHEL package + - `libjpeg-devel` + ::: + +[libpng](http://www.libpng.org/pub/png/libpng.html) +: libpng is used by libguac to write PNG images, the core image type used by + the Guacamole protocol. Guacamole cannot function without libpng. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libpng12-dev` + * - Fedora / CentOS / RHEL package + - `libpng-devel` + ::: + +[libtool](https://www.gnu.org/software/libtool/manual/libtool.html) +: libtool is used during the build process. libtool creates compiled libraries + needed for Guacamole. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libtool-bin` + * - Fedora / CentOS / RHEL package + - `libtool` + ::: + +libuuid (part of [util-linux](https://www.kernel.org/pub/linux/utils/util-linux/)) +: libuuid is used by libguac to assign unique, internal IDs to each Guacamole + user and connection. These unique IDs are the basis for connection sharing + support. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `uuid-dev` + * - Fedora / CentOS / RHEL package + - `libuuid-devel` + ::: + + If libuuid is unavailable, the [OSSP UUID](http://www.ossp.org/pkg/lib/uuid/) + library may also be used: + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libossp-uuid-dev` + * - Fedora / CentOS / RHEL package + - `uuid-devel` + ::: + +### Optional dependencies + +The optional dependencies of Guacamole dictate which parts of guacamole-server +will be built. This includes the support for various remote desktop protocols, +as well as any additional features of those protocols: + +* VNC support depends on the libvncclient library, which is part of + libVNCServer. + +* RDP support depends on a recent version of FreeRDP (2.0.0 or higher, but + please *not a non-release version from git*). + +* SSH support depends on libssh2, OpenSSL and Pango (a font rendering and text + layout library, used by Guacamole's built-in terminal emulator). + +* Telnet depends on libtelnet and Pango. + +* Kubernetes support depends on libwebsockets, OpenSSL, and Pango. + +The `guacenc` utility, provided by guacamole-server to translate screen +recordings into video, depends on FFmpeg, and will only be built if at least +the libavcodec, libavformat, libavutil, and libswscale libraries provided by +FFmpeg are installed. + +:::{important} +If you lack these dependencies, *then the features or protocols which +depend on them will not be enabled*. Please read this section +carefully before deciding not to install an optional dependency. +::: + +[FFmpeg](https://ffmpeg.org/) +: The libavcodec, libavformat, libavutil, and libswscale libraries provided by + FFmpeg are used by `guacenc` to encode video streams when translating + recordings of Guacamole sessions. Without FFmpeg, the `guacenc` utility will + simply not be built. + + If you do not wish to make graphical recordings of Guacamole sessions, or do + not wish to translate such recordings into video, then FFmpeg is not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libavcodec-dev`, `libavformat-dev`, `libavutil-dev`, `libswsccale-dev` + * - Fedora / CentOS / RHEL package + - `ffmpeg-devel` + ::: + +[FreeRDP](http://www.freerdp.com/) +: FreeRDP 2.0.0 or later is required for RDP support. If you do not wish to + build RDP support, this library is not needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `freerdp2-dev` + * - Fedora / CentOS / RHEL package + - `freerdp-devel` + ::: + +[Pango](http://www.pango.org/) +: Pango is a text layout library which Guacamole uses to render text for + protocols that require a terminal (Kubernetes, SSH, and telnet). If you do + not wish to build any terminal-based protocol support, this library is not + needed. + + :::{list-table} + :stub-columns: 1 + * - Debian / Ubuntu package + - `libpango1.0-dev` + * - Fedora / CentOS / RHEL package + - `pango-devel` + ::: + +[libssh2](http://www.libssh2.org/) +: libssh2 is required for SSH support. If you do not wish to build SSH support, + this library is not needed. Review comment: I agree. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
