mike-jumper commented on a change in pull request #165:
URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642141369
##########
File path: src/configuring-guacamole.md
##########
@@ -0,0 +1,2770 @@
+Configuring Guacamole
+=====================
+
+After installing Guacamole, you need to configure users and connections before
+Guacamole will work. This chapter covers general configuration of Guacamole and
+the use of its default authentication method.
+
+Guacamole's default authentication method reads all users and connections from
+a single file called `user-mapping.xml`. This authentication method is intended
+to be:
+
+1. Sufficient for small deployments of Guacamole.
+
+2. A relatively-easy means of verifying that Guacamole has been properly set
+ up.
+
+Other, more complex authentication methods which use backend databases, LDAP,
+etc. are discussed in a separate, dedicated chapters.
+
+Regardless of the authentication method you use, Guacamole's configuration
+always consists of two main pieces: a directory referred to as
+`GUACAMOLE_HOME`, which is the primary search location for configuration files,
+and `guacamole.properties`, the main configuration file used by Guacamole and
+its extensions.
+
+(guacamole-home)=
+
+`GUACAMOLE_HOME` (`/etc/guacamole`)
+---------------------------------------
+
+`GUACAMOLE_HOME` is the name given to Guacamole's configuration directory,
+which is located at `/etc/guacamole` by default. All configuration files,
+extensions, etc. reside within this directory. The structure of
+`GUACAMOLE_HOME` is rigorously defined, and consists of the following optional
+files:
+
+`guacamole.properties`
+: The main Guacamole configuration file. Properties within this file dictate
+ how Guacamole will connect to guacd, and may configure the behavior of
+ installed authentication extensions.
+
+`logback.xml`
+: Guacamole uses a logging system called Logback for all messages. By
+ default, Guacamole will log to the console only, but you can change this
+ by providing your own Logback configuration file.
+
+`extensions/`
+: The install location for all Guacamole extensions. Guacamole will
+ automatically load all `.jar` files within this directory on startup.
+
+`lib/`
+: The search directory for libraries required by any Guacamole extensions.
+ Guacamole will make the `.jar` files within this directory available to
+ all extensions. If your extensions require additional libraries, such as
+ database drivers, this is the proper place to put them.
+
+(overriding-guacamole-home)=
+
+### Overriding `GUACAMOLE_HOME`
+
+If you cannot or do not wish to use `/etc/guacamole` for `GUACAMOLE_HOME`, the
+location can be overridden through any of the following methods:
+
+1. Creating a directory named `.guacamole`, within the home directory of *the
+ user running the servlet container*. This directory will automatically be
+ used for `GUACAMOLE_HOME` if it exists.
+
+2. Specifying the full path to an alternative directory with the environment
+ variable `GUACAMOLE_HOME`. *Be sure to consult the documentation for your
+ servlet container to determine how to properly set environment variables.*
+
+3. Specifying the full path to an alternative directory with the system
+ property guacamole.home.
+
+(initial-setup)=
+
+`guacamole.properties`
+------------------------
+
+The Guacamole web application uses one main configuration file called
+`guacamole.properties`. This file is the common location for all configuration
+properties read by Guacamole or any extension of Guacamole, including
+authentication providers.
+
+In previous releases, this file had to be in the classpath of your servlet
+container. Now, the location of `guacamole.properties` can be explicitly
+defined with environment variables or system properties, and the classpath is
+only used as a last resort. When searching for `guacamole.properties`,
+Guacamole will check, in order:
+
+1. Within `GUACAMOLE_HOME`, as defined above.
+
+2. The classpath of the servlet container.
+
+The `guacamole.properties` file is optional and is used to configure Guacamole
+in situations where the defaults are insufficient, or to provide additional
+configuration information for extensions. There are several standard properties
+that are always available for use:
+
+`api-session-timeout`
+: The amount of time, in minutes, to allow Guacamole sessions
+ (authentication tokens) to remain valid despite inactivity. If omitted,
+ Guacamole sessions will expire after 60 minutes of inactivity.
+
+`api-max-request-size`
+: The maximum number of bytes to accept within the entity body of any
+ particular HTTP request, where 0 indicates that no limit should be
+ applied. If omitted, requests will be limited to 2097152 bytes (2 MB) by
+ default. This limit does not apply to file uploads.
+
+ If using a reverse proxy for SSL termination, *keep in mind that reverse
+ proxies may enforce their own limits independently of this*. For example,
+ [Nginx will enforce a 1 MB request size limit by
+ default](nginx-file-upload-size).
+
+`allowed-languages`
+: A comma-separated whitelist of language keys to allow as display language
+ choices within the Guacamole interface. For example, to restrict Guacamole
+ to only English and German, you would specify:
+
+ ```
+ allowed-languages: en, de
+ ```
+
+ As English is the fallback language, used whenever a translation key is
+ missing from the chosen language, English should only be omitted from this
+ list if you are absolutely positive that no strings are missing.
+
+ The corresponding JSON of any built-in languages not listed here will
+ still be available over HTTP, but the Guacamole interface will not use
+ them, nor will they be used automatically based on local browser language.
+ If omitted, all defined languages will be available.
+
+`enable-environment-properties`
+: If set to "true", Guacamole will first evaluate its environment to obtain
+ the value for any given configuration property, before using a value
+ specified in `guacamole.properties` or falling back to a default value. By
+ enabling this option, you can easily override any other configuration
+ property using an environment variable.
+
+ ```
+ enable-environment-properties: true
+ ```
+
+ When searching for a configuration property in the environment, the name
+ of the property is first transformed by converting all lower case
+ characters to their upper case equivalents, and by replacing all hyphen
+ characters (`-`) with underscore characters (`_`). For example, the
+ `guacd-hostname` property would be transformed to `GUACD_HOSTNAME` when
+ searching the environment.
+
+`guacd-hostname`
+: The host the Guacamole proxy daemon (guacd) is listening on. If omitted,
+ Guacamole will assume guacd is listening on localhost.
+
+`guacd-port`
+: The port the Guacamole proxy daemon (guacd) is listening on. If omitted,
+ Guacamole will assume guacd is listening on port 4822.
+
+`guacd-ssl`
+: If set to "true", Guacamole will require SSL/TLS encryption between the
+ web application and guacd. By default, communication between the web
+ application and guacd will be unencrypted.
+
+ Note that if you enable this option, you must also configure guacd to use
+ SSL via command line options. These options are documented in the manpage
+ of guacd. You will need an SSL certificate and private key.
+
+`skip-if-unavailable`
+: A comma-separated list of the identifiers of authentication providers that
+ should be allowed to fail internally without aborting the authentication
+ process. For example, to request that Guacamole ignore failures due to the
+ LDAP directory or MySQL server being unexpectedly down, allowing other
+ authentication providers to continue functioning:
+
+ ```
+ skip-if-unavailable: mysql, ldap
+ ```
+
+ By default, Guacamole takes a conservative approach to internal failures,
+ aborting the authentication process if an internal error occurs within any
+ authentication provider. Depending on the nature of the error, this may
+ mean that no users can log in until the cause of the failure is dealt
+ with. The `skip-if-unavailable` property may be used to explicitly inform
+ Guacamole that one or more underlying systems are expected to occasionally
+ experience failures, and that other functioning systems should be relied
+ upon if they do fail.
+
+
+```
+# Hostname and port of guacamole proxy
+guacd-hostname: localhost
+guacd-port: 4822
+```
Review comment:
I'll add some introductory text above the example. I think the placement
is OK, but is missing the context originally added by the description text for
the example.
--
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
