necouchman commented on code in PR #261:
URL: https://github.com/apache/guacamole-manual/pull/261#discussion_r2020290726
##########
src/duo-auth.md.j2:
##########
@@ -0,0 +1,112 @@
+{# vim: set filetype=markdown.jinja : #}
+{%- import 'include/ext-macros.md.j2' as ext with context -%}
+
+Using Duo for multi-factor authentication
+=========================================
+
+Guacamole's Duo authentication extension allows the third-party Duo service to
+be used as an additional authentication factor for users of your Guacamole
+installation. If installed, users that attempt to authenticate against
+Guacamole will be sent to Duo's service for further verification.
+
+```{include} include/warn-config-changes.md
+```
+
+(duo-architecture)=
+
+How Duo works with Guacamole
+----------------------------
+
+Duo is strictly a service for verifying the identities of users that have
+already been partially verified through another authentication method. Thus,
+for Guacamole to make use of Duo, at least one other authentication mechanism
+will need be configured, such as [a supported database](jdbc-auth) or
+[LDAP](ldap-auth).
Review Comment:
Will Duo work with the SSO-based modules? Might be worth either including
them here as examples of supported or warnings of unsupported methods.
##########
src/include/mysql-optional.properties.in:
##########
@@ -0,0 +1,121 @@
+#
+# The hostname or IP address of the server hosting your database. If not
+# specified, "localhost" will be used by default.
+#
+mysql-hostname: localhost
+
+#
+# The port number of the MySQL or MariaDB database to connect to. If not
+# specified, the standard MySQL / MariaDB port 3306 will be used.
+#
+mysql-port: 3306
+
+#
+# Controls which JDBC driver the extension attempts to load. By default, the
+# installed JDBC driver will be automatically detected. Possible values are:
+#
+# mysql
+# : [The **MySQL** Connector/J JDBC
driver](https://dev.mysql.com/downloads/connector/j/).
+#
+# mariadb
+# : [The **MariaDB** Connector/J JDBC
driver](https://mariadb.com/kb/en/about-mariadb-connector-j/).
+#
+mysql-driver: mariadb
+
+#
+# Specifies the timezone the MySQL server is configured to run in. While the
+# MySQL driver attempts to auto-detect the timezone in use by the server, there
+# are many cases where the timezone provided by the operating system is either
+# unknown by Java, or matches multiple timezones. In these cases MySQL may
+# either complain or refuse the connection unless the timezone is specified as
+# part of the connection. This property allows the timezone of the server to be
+# specified so that the connection can continue and the JDBC driver can
+# properly translate timestamps. The property accepts timezones in the
+# following formats:
+#
+# Region/Locale
+# : Well-known time zone identifiers, in the Region/Locale format, as defined
+# by the [IANA time zone
database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones),
+# such as `America/Los_Angeles`, `Africa/Johannesburg`, or `China/Shanghai`.
+#
+# GMT+/-HH:MM
+# : GMT or custom timezones specified by GMT offset, such as `GMT`, `GMT+0130`,
+# `GMT+06:00`, or `GMT-9`.
+#
+# The MySQL Driver implements several parameters specific to
+# configuring SSL for secure connections to MySQL servers that support
+# or require encrypted communications. *Older versions of MySQL
+# Connector/J have known issues with SSL verification - if you
+# experience problems connecting to SSL-secured MySQL databases it is
+# recommended that you update to a current version of the driver.*
Review Comment:
I suspect that this comment block should be _below_ the
`mysql-server-timezone` property just below it. I could be wrong - it's
possible that the timezone impacts SSL verification; however, since there's no
language there that makes that association, I'm guessing this block should be
moved down a bit.
##########
src/guacamole-native.md:
##########
@@ -0,0 +1,771 @@
+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 (or
+libjpeg-turbo), libpng, and libuuid (or 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
+ - `libpng-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libpng-devel`
+ :::
+
+ In some previous versions of Debian such as Debian 8 / Ubuntu 16.04, you need
+ the `libpng12-dev` package.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libpng12-dev`
+ :::
+
+[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`, `libswscale-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` or `freerdp3-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 and SFTP support. If you do not wish to build SSH
+ or SFTP support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libssh2-1-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libssh2-devel`
+ :::
+
+[libtelnet](https://github.com/seanmiddleditch/libtelnet)
+: libtelnet is required for telnet support. If you do not wish to build telnet
+ support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libtelnet-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libtelnet-devel`
+ :::
+
+[libVNCServer](http://libvnc.github.io/)
+: libVNCServer provides libvncclient, which is required for VNC support. If you
+ do not wish to build VNC support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libvncserver-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libvncserver-devel`
+ :::
+
+[libwebsockets](https://libwebsockets.org/)
+: libwebsockets is required for Kubernetes support. If you do not wish to build
+ Kubernetes support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libwebsockets-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libwebsockets-devel`
+ :::
+
+[PulseAudio](http://www.freedesktop.org/wiki/Software/PulseAudio/)
+: PulseAudio provides libpulse, which is used by Guacamole's VNC support to
+ provide experimental audio support. If you are not going to be using the
+ experimental audio support for VNC, you do not need this library.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libpulse-dev`
+ * - Fedora / CentOS / RHEL package
+ - `pulseaudio-libs-devel`
+ :::
+
+[OpenSSL](https://www.openssl.org/)
+: OpenSSL provides support for SSL and TLS - two common encryption schemes that
+ make up the majority of encrypted web traffic.
+
+ If you have libssl installed, guacd will be built with SSL support, allowing
+ communication between the web application and guacd to be encrypted. This
+ library is also required for SSH support, for manipulating public/private
keys,
+ and for Kubernetes support, for SSL/TLS connections to the Kubernetes server.
+
+ Without SSL support, there will be no option to encrypt communication to
+ guacd, and support for SSH and Kubernetes cannot be built.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libssl-dev`
+ * - Fedora / CentOS / RHEL package
+ - `openssl-devel`
+ :::
+
+[libvorbis](http://xiph.org/vorbis/)
+: libvorbis provides support for Ogg Vorbis - a free and open standard for
+ sound compression. If installed, libguac will be built with support for Ogg
+ Vorbis, and protocols supporting audio will use Ogg Vorbis compression when
+ possible.
+
+ Otherwise, sound will only be encoded as WAV (uncompressed), and will only be
+ available if your browser also supports WAV.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libvorbis-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libvorbis-devel`
+ :::
+
+[libwebp](https://developers.google.com/speed/webp/)
+: libwebp is used by libguac to write WebP images. Though support for WebP is
+ not mandated by the Guacamole protocol, WebP images will be used if supported
+ by both the browser and by libguac.
+
+ Lacking WebP support, Guacamole will simply use JPEG in cases that it would
+ have preferred WebP.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libwebp-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libwebp-devel`
+ :::
+
+(guacamole-server-source)=
+
+### Obtaining the source code
+
+You can obtain a copy of the guacamole-server source from the Guacamole project
+web site. These releases are stable snapshots of the latest code which have
+undergone enough testing that the Guacamole team considers them fit for public
+consumption. Source downloaded from the project web site will take the form of
+a `.tar.gz` archive which you can extract
+from the command line:
+
+```console
+$ tar -xzf guacamole-server-1.6.0.tar.gz
+$ cd guacamole-server-1.6.0/
+$
+```
+
+If you want the absolute latest code, and don't care that the code hasn't been
+as rigorously tested as the code in stable releases, you can also clone the
+Guacamole team's git repository on GitHub:
+
+```console
+$ git clone git://github.com/apache/guacamole-server.git
+Cloning into 'guacamole-server'...
+remote: Counting objects: 6769, done.
+remote: Compressing objects: 100% (2244/2244), done.
+remote: Total 6769 (delta 3058), reused 6718 (delta 3008)
+Receiving objects: 100% (6769/6769), 2.32 MiB | 777 KiB/s, done.
+Resolving deltas: 100% (3058/3058), done.
+$
+```
+
+(guacamole-server-build-process)=
+
+### The build process
+
+Once the guacamole-server source has been downloaded and extracted, you need to
+run `configure`. This is a shell script automatically generated by GNU
+Autotools, a popular build system used by the Guacamole project for
+guacamole-server. Running `configure` will determine which libraries are
+available on your system and will select the appropriate components for
+building depending on what you actually have installed.
+
+:::{important}
+Source downloaded directly from git will not contain this `configure` script,
+as autogenerated code is not included in the project's repositories. If you
+downloaded the code from the project's git repositories directly, you will need
+to generate `configure` manually:
+
+```console
+$ cd guacamole-server/
+$ autoreconf -fi
+$
+```
+
+Doing this requires GNU Autotools to be installed.
+
+Source archives downloaded from the project website contain the `configure`
+script and all other necessary build files, and thus do not require GNU
+Autotools to be installed on the build machine.
+:::
+
+Once you run `configure`, you can see what a listing of what libraries were
+found and what it has determined should be built:
+
+```console
+$ ./configure --with-init-dir=/etc/init.d
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+
+------------------------------------------------
+guacamole-server version 1.6.0
+------------------------------------------------
+
+ Library status:
+
+ freerdp ............. yes (3.x)
+ pango ............... yes
+ libavcodec .......... yes
+ libavformat ......... yes
+ libavutil ........... yes
+ libssh2 ............. yes
+ libssl .............. yes
+ libswscale .......... yes
+ libtelnet ........... yes
+ libVNCServer ........ yes
+ libvorbis ........... yes
+ libpulse ............ yes
+ libwebsockets ....... yes
+ libwebp ............. yes
+ wsock32 ............. no
+
+ Protocol support:
+
+ Kubernetes .... yes
+ RDP ........... yes
+ SSH ........... yes
+ Telnet ........ yes
+ VNC ........... yes
+
+ Services / tools:
+
+ guacd ...... yes
+ guacenc .... yes
+ guaclog .... yes
+
+ FreeRDP plugins: /usr/lib/pkgconfig/../../lib/freerdp3
+ Init scripts: /etc/init.d
+ Systemd units: no
+
+Type "make" to compile guacamole-server.
+
+$
+```
+
+The `--with-init-dir=/etc/init.d` shown above prepares the build to install a
+startup script for guacd into the `/etc/init.d` directory, such that we can
+later easily configure guacd to start automatically on boot. If you do not wish
+guacd to start automatically at boot, leave off the `--with-init-dir` option.
+If the directory containing your distribution's startup scripts differs from
+the common `/etc/init.d`, replace `/etc/init.d` with the proper directory here.
+You may need to consult your distribution's documentation, or do a little
+digging in `/etc`, to determine the proper location.
+
+Here, `configure` has found everything, including all optional libraries, and
+will build all protocol support, even support for Ogg Vorbis sound in RDP. If
+you are missing some libraries, some of the "`yes`" answers above will read
+"`no`". If a library which is strictly required is missing, the script will
+fail outright, and you will need to install the missing dependency. If, after
+running `configure`, you find support for something you wanted is missing,
+simply install the corresponding dependencies and run `configure` again.
+
+:::{important}
+All protocols that require a terminal (Kubernetes, SSH, and telnet) require
+that fonts are installed on the Guacamole server in order to function, as
+output from the terminal cannot be rendered otherwise. Support for these
+protocols will build just fine if fonts are not installed, but it will fail to
+connect when used:
+
+```
+Aug 23 14:09:45 my-server guacd[5606]: Unable to get font "monospace"
+```
+
+If terminal-based connections are not working and you see such a message in
+syslog, you should make sure fonts are installed and try again.
+:::
+
+Once `configure` is finished, just type "`make`", and it will guacamole-server
+will compile:
+
+```console
+$ make
+Making all in src/libguac
+make[1]: Entering directory
`/home/mjumper/guacamole/guacamole-server/src/libguac'
+...
+make[1]: Leaving directory
`/home/mjumper/guacamole/guacamole-server/src/protocols/vnc'
+make[1]: Entering directory `/home/mjumper/guacamole/guacamole-server'
+make[1]: Nothing to be done for `all-am'.
+make[1]: Leaving directory `/home/mjumper/guacamole/guacamole-server'
+$
+```
+
+Quite a bit of output will scroll up the screen as all the components are
+compiled.
+
+(guacamole-server-installation)=
+
+### Installation
+
+Once everything finishes, all you have left to do is type "`make install`" to
+install the components that were built, and then "`ldconfig`" to update your
+system's cache of installed libraries:
+
+```console
+# make install
+Making install in src/libguac
+make[1]: Entering directory
`/home/mjumper/guacamole/guacamole-server/src/libguac'
+make[2]: Entering directory
`/home/mjumper/guacamole/guacamole-server/src/libguac'
+...
+----------------------------------------------------------------------
+Libraries have been installed in:
+ /usr/local/lib
+
+If you ever happen to want to link against installed libraries
+in a given directory, LIBDIR, you must either use libtool, and
+specify the full pathname of the library, or use the `-LLIBDIR'
+flag during linking and do at least one of the following:
+ - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
+ during execution
+ - add LIBDIR to the `LD_RUN_PATH' environment variable
+ during linking
+ - use the `-Wl,-rpath -Wl,LIBDIR' linker flag
+ - have your system administrator add LIBDIR to `/etc/ld.so.conf'
+
+See any operating system documentation about shared libraries for
+more information, such as the ld(1) and ld.so(8) manual pages.
+----------------------------------------------------------------------
+make[2]: Nothing to be done for `install-data-am'.
+make[2]: Leaving directory
`/home/mjumper/guacamole/guacamole-server/src/protocols/vnc'
+make[1]: Leaving directory
`/home/mjumper/guacamole/guacamole-server/src/protocols/vnc'
+make[1]: Entering directory `/home/mjumper/guacamole/guacamole-server'
+make[2]: Entering directory `/home/mjumper/guacamole/guacamole-server'
+make[2]: Nothing to be done for `install-exec-am'.
+make[2]: Nothing to be done for `install-data-am'.
+make[2]: Leaving directory `/home/mjumper/guacamole/guacamole-server'
+make[1]: Leaving directory `/home/mjumper/guacamole/guacamole-server'
+# ldconfig
+#
+```
+
+At this point, everything is installed, but guacd is not running. You will need
+to run guacd in order to use Guacamole once the client components are installed
+as well.
+
+Beware that even after installing guacd and its startup script, you will likely
+still have to activate the service for it to start automatically. Doing this
+varies by distribution, but each distribution will have documentation
+describing how to do so.
+
+(building-guacamole-client)=
+
+guacamole-client
+----------------
+
+:::{important}
+Normally, you don't need to build guacamole-client, as it is written in Java
+and is cross-platform. You can easily obtain the latest version of
+guacamole-client from the release archives of the Guacamole project web site,
+including all supported extensions, without having to build it yourself.
+
+If you do not want to build guacamole-client from source, just download
+`guacamole.war` from the project web site, along with any desired extensions,
+and skip ahead to [](deploying-guacamole).
+:::
+
+guacamole-client contains all Java and JavaScript components of Guacamole
+(guacamole, guacamole-common, guacamole-ext, and guacamole-common-js). These
+components ultimately make up the web application that will serve the HTML5
+Guacamole client to users that connect to your server. This web application
+will then connect to guacd, part of guacamole-server, on behalf of connected
+users in order to serve them any remote desktop they are authorized to access.
+
+To compile guacamole-client, all you need is Apache Maven and a copy of the
+Java JDK. Most, if not all, Linux distributions will provide packages for
+these.
+
+You can obtain a copy of the guacamole-client source from the Guacamole project
+web site. These releases are stable snapshots of the latest code which have
+undergone enough testing that the Guacamole team considers them fit for public
+consumption. Source downloaded from the project web site will take the form of
+a `.tar.gz` archive which you can extract from the command line:
+
+```console
+$ tar -xzf guacamole-client-1.6.0.tar.gz
+$ cd guacamole-client-1.6.0/
+$
+```
+
+As with guacamole-server, if you want the absolute latest code, and don't care
+that the code hasn't been as rigorously tested as the code in stable releases,
+you can also clone the Guacamole team's git repository on GitHub:
+
+```console
+$ git clone git://github.com/apache/guacamole-client.git
+Cloning into 'guacamole-client'...
+remote: Counting objects: 12788, done.
+remote: Compressing objects: 100% (4183/4183), done.
+remote: Total 12788 (delta 3942), reused 12667 (delta 3822)
+Receiving objects: 100% (12788/12788), 3.23 MiB | 799 KiB/s, done.
+Resolving deltas: 100% (3942/3942), done.
+$
+```
+
+Unlike guacamole-server, even if you grab the code from the git repositories,
+you won't need to run anything before building. There are no scripts that need
+to be generated before building - all Maven needs is the `pom.xml` file
+provided with the source.
Review Comment:
Not sure if it's worth mentioning, here, that while there aren't any
additional dependencies, Internet access is a dependency because Maven will
pull the requirements from the Maven repositories?
##########
src/guacamole-native.md:
##########
@@ -0,0 +1,771 @@
+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 (or
+libjpeg-turbo), libpng, and libuuid (or 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
+ - `libpng-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libpng-devel`
+ :::
+
+ In some previous versions of Debian such as Debian 8 / Ubuntu 16.04, you need
+ the `libpng12-dev` package.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libpng12-dev`
+ :::
+
+[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`, `libswscale-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` or `freerdp3-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 and SFTP support. If you do not wish to build SSH
+ or SFTP support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libssh2-1-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libssh2-devel`
+ :::
+
+[libtelnet](https://github.com/seanmiddleditch/libtelnet)
+: libtelnet is required for telnet support. If you do not wish to build telnet
+ support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libtelnet-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libtelnet-devel`
+ :::
+
+[libVNCServer](http://libvnc.github.io/)
+: libVNCServer provides libvncclient, which is required for VNC support. If you
+ do not wish to build VNC support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libvncserver-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libvncserver-devel`
+ :::
+
+[libwebsockets](https://libwebsockets.org/)
+: libwebsockets is required for Kubernetes support. If you do not wish to build
+ Kubernetes support, this library is not needed.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libwebsockets-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libwebsockets-devel`
+ :::
+
+[PulseAudio](http://www.freedesktop.org/wiki/Software/PulseAudio/)
+: PulseAudio provides libpulse, which is used by Guacamole's VNC support to
+ provide experimental audio support. If you are not going to be using the
+ experimental audio support for VNC, you do not need this library.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libpulse-dev`
+ * - Fedora / CentOS / RHEL package
+ - `pulseaudio-libs-devel`
+ :::
+
+[OpenSSL](https://www.openssl.org/)
+: OpenSSL provides support for SSL and TLS - two common encryption schemes that
+ make up the majority of encrypted web traffic.
+
+ If you have libssl installed, guacd will be built with SSL support, allowing
+ communication between the web application and guacd to be encrypted. This
+ library is also required for SSH support, for manipulating public/private
keys,
+ and for Kubernetes support, for SSL/TLS connections to the Kubernetes server.
+
+ Without SSL support, there will be no option to encrypt communication to
+ guacd, and support for SSH and Kubernetes cannot be built.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libssl-dev`
+ * - Fedora / CentOS / RHEL package
+ - `openssl-devel`
+ :::
+
+[libvorbis](http://xiph.org/vorbis/)
+: libvorbis provides support for Ogg Vorbis - a free and open standard for
+ sound compression. If installed, libguac will be built with support for Ogg
+ Vorbis, and protocols supporting audio will use Ogg Vorbis compression when
+ possible.
+
+ Otherwise, sound will only be encoded as WAV (uncompressed), and will only be
+ available if your browser also supports WAV.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libvorbis-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libvorbis-devel`
+ :::
+
+[libwebp](https://developers.google.com/speed/webp/)
+: libwebp is used by libguac to write WebP images. Though support for WebP is
+ not mandated by the Guacamole protocol, WebP images will be used if supported
+ by both the browser and by libguac.
+
+ Lacking WebP support, Guacamole will simply use JPEG in cases that it would
+ have preferred WebP.
+
+ :::{list-table}
+ :stub-columns: 1
+ * - Debian / Ubuntu package
+ - `libwebp-dev`
+ * - Fedora / CentOS / RHEL package
+ - `libwebp-devel`
+ :::
+
+(guacamole-server-source)=
+
+### Obtaining the source code
+
+You can obtain a copy of the guacamole-server source from the Guacamole project
+web site. These releases are stable snapshots of the latest code which have
+undergone enough testing that the Guacamole team considers them fit for public
+consumption. Source downloaded from the project web site will take the form of
+a `.tar.gz` archive which you can extract
+from the command line:
+
+```console
+$ tar -xzf guacamole-server-1.6.0.tar.gz
+$ cd guacamole-server-1.6.0/
+$
+```
+
+If you want the absolute latest code, and don't care that the code hasn't been
+as rigorously tested as the code in stable releases, you can also clone the
+Guacamole team's git repository on GitHub:
+
+```console
+$ git clone git://github.com/apache/guacamole-server.git
+Cloning into 'guacamole-server'...
+remote: Counting objects: 6769, done.
+remote: Compressing objects: 100% (2244/2244), done.
+remote: Total 6769 (delta 3058), reused 6718 (delta 3008)
+Receiving objects: 100% (6769/6769), 2.32 MiB | 777 KiB/s, done.
+Resolving deltas: 100% (3058/3058), done.
+$
+```
+
+(guacamole-server-build-process)=
+
+### The build process
+
+Once the guacamole-server source has been downloaded and extracted, you need to
+run `configure`. This is a shell script automatically generated by GNU
+Autotools, a popular build system used by the Guacamole project for
+guacamole-server. Running `configure` will determine which libraries are
+available on your system and will select the appropriate components for
+building depending on what you actually have installed.
+
+:::{important}
+Source downloaded directly from git will not contain this `configure` script,
+as autogenerated code is not included in the project's repositories. If you
+downloaded the code from the project's git repositories directly, you will need
+to generate `configure` manually:
+
+```console
+$ cd guacamole-server/
+$ autoreconf -fi
+$
+```
+
+Doing this requires GNU Autotools to be installed.
+
+Source archives downloaded from the project website contain the `configure`
+script and all other necessary build files, and thus do not require GNU
+Autotools to be installed on the build machine.
+:::
+
+Once you run `configure`, you can see what a listing of what libraries were
+found and what it has determined should be built:
+
+```console
+$ ./configure --with-init-dir=/etc/init.d
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+
+------------------------------------------------
+guacamole-server version 1.6.0
+------------------------------------------------
+
+ Library status:
+
+ freerdp ............. yes (3.x)
+ pango ............... yes
+ libavcodec .......... yes
+ libavformat ......... yes
+ libavutil ........... yes
+ libssh2 ............. yes
+ libssl .............. yes
+ libswscale .......... yes
+ libtelnet ........... yes
+ libVNCServer ........ yes
+ libvorbis ........... yes
+ libpulse ............ yes
+ libwebsockets ....... yes
+ libwebp ............. yes
+ wsock32 ............. no
+
+ Protocol support:
+
+ Kubernetes .... yes
+ RDP ........... yes
+ SSH ........... yes
+ Telnet ........ yes
+ VNC ........... yes
+
+ Services / tools:
+
+ guacd ...... yes
+ guacenc .... yes
+ guaclog .... yes
+
+ FreeRDP plugins: /usr/lib/pkgconfig/../../lib/freerdp3
+ Init scripts: /etc/init.d
+ Systemd units: no
+
+Type "make" to compile guacamole-server.
+
+$
+```
+
+The `--with-init-dir=/etc/init.d` shown above prepares the build to install a
+startup script for guacd into the `/etc/init.d` directory, such that we can
+later easily configure guacd to start automatically on boot. If you do not wish
+guacd to start automatically at boot, leave off the `--with-init-dir` option.
+If the directory containing your distribution's startup scripts differs from
+the common `/etc/init.d`, replace `/etc/init.d` with the proper directory here.
+You may need to consult your distribution's documentation, or do a little
+digging in `/etc`, to determine the proper location.
Review Comment:
Might be worth adding a mention in this section of the systemd alternative
to init scripts?
--
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.
To unsubscribe, e-mail: dev-unsubscr...@guacamole.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
