GUACAMOLE-1820: Merge documentation for key event display and search.
diff --git a/src/auth-ban.md b/src/auth-ban.md
new file mode 100644
index 0000000..df0fe9f
--- /dev/null
+++ b/src/auth-ban.md
@@ -0,0 +1,108 @@
+Securing Guacamole against brute force attacks
+==============================================
+
+Version 1.6.0 of Guacamole introduces an extension that allows you to detect
+and block brute-force login attacks. The extension, `guacamole-auth-ban`, can
+be installed alongside any of Guacamole's other extensions that provide user
+authentication, and will track the IP address of failed authentication attempts
+and, once the threshold of failed logins is reached, will block further logins
+from that IP address for a given amount of time.
+
+:::{important}
+This chapter involves modifying the contents of `GUACAMOLE_HOME` - the
+Guacamole configuration directory. If you are unsure where `GUACAMOLE_HOME` is
+located on your system, please consult [](configuring-guacamole) before
+proceeding.
+:::
+
+Downloading the auth-ban extension
+----------------------------------
+
+The guacamole-auth-ban extension is available separately from the main
+`guacamole.war`. The link for this and all other officially-supported and
+compatible extensions for a particular version of Guacamole are provided on the
+release notes for that version. You can find the release notes for current
+versions of Guacamole here: http://guacamole.apache.org/releases/.
+
+The extension is packaged as a `.tar.gz` file containing only the extension
+itself, `guacamole-auth-ban-1.6.0.jar`, which must ultimately be placed in
+`GUACAMOLE_HOME/extensions`.
+
+(installing-auth-ban)=
+
+Installing the auth-ban extension
+---------------------------------
+
+Guacamole extensions are self-contained `.jar` files which are located within
+the `GUACAMOLE_HOME/extensions` directory. To install the guacamole-auth-ban
+extension, you must:
+
+1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
+ exist.
+
+2. Copy `guacamole-auth-ban-1.6.0.jar` within `GUACAMOLE_HOME/extensions`.
+
+3. [Configure the auth-ban extension thresholds, as described below](auth-ban-config),
+ if want parameters other than the defaults (also noted below).
+
+:::{important}
+You will need to restart Guacamole by restarting your servlet container in
+order to complete the installation. Doing this will disconnect all active
+users, so be sure that it is safe to do so prior to attempting installation.
+:::
+
+(auth-ban-config)=
+
+### Configuring Guacamole for authentication failure protection
+
+This extension has no required properties, and, so long as you are satisfied
+with the default threshold noted below, requires no configuration beyond the
+installation of the extension and reload of the web application.
+
+If you wish to adjust the thresholds for how Guacamole handles protection
+against brute force authentication attacks, the following properties are
+available to you to configure the auth-ban extension:
+
+`ban-max-invalid-attempts`
+: The number of authentication failures ater which the extension will block
+ further logins from the client IP address. This property is optional and
+ the default is 5.
+
+`ban-address-duration`
+: The length of time for which a client IP address will be denied logins
+ after the maximum authentication failures, in seconds. This property is
+ optional and has a default value of 300 seconds (five minutes).
+
+`ban-max-addresses`
+: The maximum number of client IP addresses that the extension will track
+ in-memory before the oldest client IP is discarded in a Least-Recently
+ Used (LRU) fashion. This property is optional and has a default value
+ of 10485670 (1 million IP addresses).
+
+:::{important}
+Because the extension tracks authentication failures based on the client
+IP address, it is important to make sure that Guacamole is receiving the
+correct IP addresses for the clients. This is particularly noteworthy
+when Guacamole is behind a reverse proxy. See the manual page on
+[proxying Guacamole](proxying-guacamole) for more details on configuring
+Guacamole behind a proxy.
+:::
+
+(completing-auth-ban-install)=
+
+### Completing the installation
+
+Guacamole will only reread `guacamole.properties` and load newly-installed
+extensions during startup, so your servlet container will need to be restarted
+before installation of the auth-ban extension will take effect.
+
+(using-auth-ban)=
+
+### Using the extension
+
+Once the extension is installed and the web application restarted, Guacamole
+will immediately begin tracking login failures and blocking login attempts
+from systems that reach the maximum failure threshold. Once an IP address is
+blocked you'll see a message on the login page:
+
+
diff --git a/src/configuring-guacamole.md b/src/configuring-guacamole.md
index f36bdb9..865843d 100644
--- a/src/configuring-guacamole.md
+++ b/src/configuring-guacamole.md
@@ -499,10 +499,16 @@
#### Display settings
-VNC servers do not allow the client to request particular display sizes, so you
-are at the mercy of your VNC server with respect to display width and height.
-However, to reduce bandwidth usage, you may request that the VNC server reduce
-its color depth. Guacamole will automatically detect 256-color images, but this
+Many VNC servers do not allow the client to request or change the display
+size, though there are some that support dynamic display size updates. However,
+unlike RDP, there is no strict requirement that the VNC server honor or
+support those updates, so you are at the mercy of your VNC server with respect
+to display width and height and whether or not it matches that of your client.
+Guacamole, by default, attempts to negotiate this support with the VNC
+server and send the client (browser) display dimensions to the VNC server.
+
+To reduce bandwidth usage, you may request that the VNC server reduce its
+color depth. Guacamole will automatically detect 256-color images, but this
can be guaranteed for absolutely all graphics sent over the connection by
forcing the color depth to 8-bit. Color depth is otherwise dictated by the VNC
server.
@@ -519,6 +525,34 @@
value is chosen here, if a particular update uses less than 256 colors,
Guacamole will always send that update as a 256-color PNG.
+`disable-server-input`
+: Whether or not the VNC client should ask the VNC server to disable local
+ input devices when the client connects. Some VNC servers support this
+ feature in order to give preference to input from the client, and to
+ avoid situations where the local keyboard and/or mouse may be "fighting"
+ with the remote keyboard and/or mouse for control. Note that this
+ requires the remote VNC server to have this feature supported and
+ enabled, and there is no guarantee that the remote system will honor
+ the request. Setting this parameter to "true" will request that the
+ VNC server disable the local input devices; leaving it blank or
+ setting to false will not make that request. This parameter is
+ optional.
+
+`disable-display-resize`
+: Whether or not the VNC client should *not* attempt to update the
+ remote (server) display with its size. By default, when Guacamole
+ connects to a VNC server, it will check for server support for
+ configuring the remote display size, and will attempt to send the
+ size of the browser area to the server to set the remote display
+ to the same size as the browser. Also, if the browser window is
+ resized, Guacamole will detect the resize and send the updated
+ size to the server. If the server supports dynamic resizing, it
+ may adjust the display size to match the browser. If this option
+ is set to true, Guacamole will disable the client-side display
+ updates, and the size of the desktop will not be sent to the
+ VNC server, either during initial connection or when the browser
+ is resized.
+
`swap-red-blue`
: If the colors of your display appear wrong (blues appear orange or red,
etc.), it may be that your VNC server is sending image data incorrectly,
@@ -1676,6 +1710,12 @@
parameter is not provided, the user will be prompted for the passphrase
upon connecting.
+`public-key`
+: If SSH is using certificate-based authentication, this field allows
+ you to provide the Base64-encoded CA certificate that will be used
+ to validate the certificate of the user. This parameter is optional
+ and there is no default value.
+
(ssh-command)=
#### Running a command (instead of a shell)
@@ -2218,10 +2258,15 @@
```
:::{important}
-Guacamole will never overwrite an existing recording. If necessary, a numeric
-suffix like ".1", ".2", ".3", etc. will be appended to <NAME> to avoid
+By default, Guacamole will not overwrite an existing recording, unless you have
+enabled it to do so by use of the `recording-write-existing` connection
+paramter. When the `recording-write-existing` connection parameter is not enabled,
+a numeric suffix like ".1", ".2", ".3", etc. will be appended to <NAME> to avoid
overwriting an existing recording. If even appending a numeric suffix does not
help, the session will simply not be recorded.
+
+If the `recording-write-existing` parameter is enabled, then Guacamole will
+overwrite the existing recording.
:::
`recording-path`
@@ -2284,6 +2329,19 @@
the `recording-path` is not specified, graphical session recording will be
disabled, and this parameter will be ignored.
+`recording-write-exiting`
+: If set to "true", instead of insisting on creation of a new file, and
+ appending numbers until a non-existing file is found, Guacamole will
+ simply write to the existing recording file, overwriting data that
+ may already be present. While overwriting recordings is not generally
+ desirable, this parameter is useful in situations where you want to
+ try to write to a named pipe, FIFO buffer, or other special device
+ that may be sending the recording data elsewhere.
+
+ This parameter only has an effect if graphical recording is enabled. If
+ the `recording-path` is not specified, graphical session recording will
+ be disabled, and this parameter will be ignored.
+
(typescripts)=
#### Text session recording (typescripts)
@@ -2305,10 +2363,14 @@
```
:::{important}
-Guacamole will never overwrite an existing recording. If necessary, a numeric
-suffix like ".1", ".2", ".3", etc. will be appended to `NAME` to avoid
-overwriting an existing recording. If even appending a numeric suffix does not
-help, the session will simply not be recorded.
+By default, Guacamole will not overwrite an existing typescript recordings;
+instead, it will append a numeric suffix like ".1", ".2", ".3", etc., to
+`NAME` to avoid overwriting an existing recording. If even appending a
+numeric suffix does not help, the session will simply not be recorded.
+
+However, if the `typescript-write-existing` parameter is enabled, then
+Guacamole will be allowed to use the existing recording file, potentially
+ovewriting any data in that file.
:::
`typescript-path`
@@ -2348,6 +2410,20 @@
the `typescript-path` is not specified, recording of typescripts will be
disabled, and this parameter will be ignored.
+`typescript-write-existing`
+: If this parameter is set to "true", instead of attempting to generate
+ unique file names by appending incremental numbers to the typescript name,
+ Guacamole will be allowed to write to an existing typescript file,
+ potentially ovewriting any data in that file. While this is not
+ desirable in most cases, it may be necessary in situations where the
+ typescript recording is being sent to a named pipe, FIFO buffer, or
+ other special device that is processing the data and sending it
+ elsewhere.
+
+ This parameter only has an effect if typescript recording is enabled. If
+ the `typescript-path` is not specified, recording of typescripts will be
+ disabled, and this parameter will be ignored.
+
(terminal-behavior)=
#### Controlling terminal behavior
@@ -2496,6 +2572,15 @@
below parameters control the behavior of this functionality, which is disabled
by default.
+When this functionality is enabled, Guacamole will attempt to connect to the
+specified hostname or IP and the TCP port number used in the connection prior
+to sending the WoL packet. If the connection succeeds, the host is determined
+to be up, and the WoL packet will not be sent. After the initial WoL packet
+is sent, Guacamole will wait the amount of time specified by `wol-wait-time`,
+retry the connection to the host, and then send another WoL packet. This
+loop will be repeated up to five times to attempt to wake the host, or
+the connection will fail.
+
:::{important}
There are several factors that can impact the ability of Wake-on-LAN (WoL) to
function correctly, many of which are outside the scope of Guacamole
diff --git a/src/images/too-many-failed-logins.png b/src/images/too-many-failed-logins.png
new file mode 100644
index 0000000..0c79f63
--- /dev/null
+++ b/src/images/too-many-failed-logins.png
Binary files differ
diff --git a/src/index.md b/src/index.md
index 9804098..eed953f 100644
--- a/src/index.md
+++ b/src/index.md
@@ -49,6 +49,7 @@
saml-auth
radius-auth
adhoc-connections
+ban-auth
using-guacamole
recording-playback
administration
diff --git a/src/ldap-auth.md b/src/ldap-auth.md
index d3b3333..2430b32 100644
--- a/src/ldap-auth.md
+++ b/src/ldap-auth.md
@@ -262,6 +262,18 @@
the `-D` option. Your servlet container will provide some means of specifying
startup options for the JVM.
+`ldap-ssl-protocol`
+: Configures the SSL/TLS protocol version that will be used to contact the
+ LDAP server, if LDAP encryption is enabled. Legal values are "SSLv3" for
+ (legacy) SSL version 3 encryption, and "TLSv1", "TLSv1.1", "TLSv1.2", or
+ "TLSv1.3" for the various versions of TLS, version 1.0 - 1.3. The default
+ is to use the latest, TLSv1.3.
+
+ Please note that the legacy versions of SSLv3 and TLSv1 and TLSv1.1 have
+ many known vulnerabilities and attack vectors, and you should use the
+ latest possible TLS version that your LDAP servers support in order
+ to best protect communication between Guacamole and your LDAP servers.
+
`ldap-max-search-results`
: The maximum number of search results that can be returned by a single LDAP
query. LDAP queries which exceed this maximum will fail. *This property is
diff --git a/src/saml-auth.md b/src/saml-auth.md
index 803d1dc..956431d 100644
--- a/src/saml-auth.md
+++ b/src/saml-auth.md
@@ -106,6 +106,18 @@
management within Guacamole Client, particularly when layered with other
authentication modules. This property is optional, and defaults to "groups".
+`saml-x509-cert-path`
+: The path to a certificate that will be used to sign SAML requests before
+ they are sent to the IdP, enhancing the integrity of the SAML authentication
+ process. This property is optional, and, if not present, SAML requests
+ will not be signed.
+
+`saml-private-key-path`
+: The path to a private key file to use to encrypt SAML requests sent to the
+ IdP, enhancing the confidentiality and integrity of the authentication
+ process. This property is optional, and, if not present, SAML requests
+ will not be encrypted before they are sent to the IdP.
+
### Controlling login behavior
```{include} include/sso-login-behavior.md
diff --git a/src/vault.md b/src/vault.md
index ff0a8e7..5c7a943 100644
--- a/src/vault.md
+++ b/src/vault.md
@@ -158,6 +158,12 @@
the KSM vault support itself, it is unlikely that you need to set this
property.**
+`ksm-api-call-interval`
+: Specify the minimum number of milliseconds between calls to the KSM API. The
+ API allows a limited number of calls per month, and calls over the included
+ amount generate additional cost. Setting this property allows you to
+ limit Guacamole's impact on that cost.
+
(completing-vault-install)=
### Completing the installation
