anchor.diff:  logger.authc.level = DEBUG
   ----------------
   
  -A successful authentication should produce debug statements that list groups and role mappings.
  ---
  -
  -
  -[float]
  -=== Encryption & Certificates
  -
  -`curl` on the Mac returns a certificate verification error even when the `--cacert` option is used::
  -+
  ---
  -Apple's integration of `curl` with their keychain technology disables the `--cacert` option.
  +A successful authentication should produce debug statements that list groups and
  +role mappings.
  +--
  +
  +[[security-trb-extraargs]]
  +=== Users command fails due to extra arguments
  +
  +*Symptoms:*
  +
  +* The `users` command fails with the following message:
  +`ERROR: extra arguments [...] were provided`.
  +
  +*Resolution:*
  +
  +This error occurs when the `users` tool is parsing the input and finds
  +unexpected arguments. This can happen when there are special characters used in
  +some of the arguments. For example, on Windows systems the `,` character is
  +considered a parameter separator; in other words `-r role1,role2` is translated
  +to `-r role1 role2` and the `users` tool only recognizes `role1` as an expected
  +parameter. The solution here is to quote the parameter: `-r "role1,role2"`.
  +
  +For more information about this command, see
  +{ref}/users-command.html[Users Command].
  +
  +[[trouble-shoot-active-directory]]
  +=== Users are frequently locked out of Active Directory
  +
  +*Symptoms:*
  +
  +* Certain users are being frequently locked out of Active Directory.
  +
  +*Resolution:*
  +
  +Check your realm configuration; realms are checked serially, one after another.
  +If your Active Directory realm is being checked before other realms and there
  +are usernames that appear in both Active Directory and another realm, a valid
  +login for one realm might be causing failed login attempts in another realm.
  +
  +For example, if `UserA` exists in both Active Directory and a file realm, and
  +the Active Directory realm is checked first and file is checked second, an
  +attempt to authenticate as `UserA` in the file realm would first attempt to
  +authenticate against Active Directory and fail, before successfully
  +authenticating against the `file` realm. Because authentication is verified on
  +each request, the Active Directory realm would be checked - and fail - on each
  +request for `UserA` in the `file` realm. In this case, while the authentication
  +request completed successfully, the account on Active Directory would have
  +received several failed login attempts, and that account might become
  +temporarily locked out. Plan the order of your realms accordingly.
  +
  +Also note that it is not typically necessary to define multiple Active Directory
  +realms to handle domain controller failures. When using Microsoft DNS, the DNS
  +entry for the domain should always point to an available domain controller.
  +
  +
  +[[trb-security-maccurl]]
  +=== Certificate verification fails for curl on Mac
  +
  +*Symptoms:*
  +
  +* `curl` on the Mac returns a certificate verification error even when the
  +`--cacert` option is used.
  +
  +
  +*Resolution:*
  +
  +Apple's integration of `curl` with their keychain technology disables the
  +`--cacert` option.
   See http://curl.haxx.se/mail/archive-2013-10/0036.html for more information.
   
  -You can use another tool, such as `wget`, to test certificates. Alternately, you can add the certificate for the
  -signing certificate authority MacOS system keychain, using a procedure similar to the one detailed at the
  -http://support.apple.com/kb/PH14003[Apple knowledge base]. Be sure to add the signing CA's certificate and not the server's certificate.
  ---
  -
  -[float]
  -==== SSLHandshakeException causing connections to fail
  -
  -A `SSLHandshakeException` will cause a connection to a node to fail and indicates that there is a configuration issue. Some of the
  -common exceptions are shown below with tips on how to resolve these issues.
  +You can use another tool, such as `wget`, to test certificates. Alternately, you
  +can add the certificate for the signing certificate authority MacOS system
  +keychain, using a procedure similar to the one detailed at the
  +http://support.apple.com/kb/PH14003[Apple knowledge base]. Be sure to add the
  +signing CA's certificate and not the server's certificate.
  +
  +
  +[[trb-security-sslhandshake]]
  +=== SSLHandshakeException causes connections to fail
  +
  +*Symptoms:*
  +
  +* A `SSLHandshakeException` causes a connection to a node to fail and indicates
  +that there is a configuration issue. Some of the common exceptions are shown
  +below with tips on how to resolve these issues.
  +
  +
  +*Resolution:*
   
   `java.security.cert.CertificateException: No name matching node01.example.com found`::
   +
   --
  -Indicates that a client connection was made to `node01.example.com` but the certificate returned did not contain the name `node01.example.com`.
  -In most cases, the issue can be resolved by ensuring the name is specified during certificate creation. For more information, see <<ssl-tls>>.
  -Another scenario is when the environment does not wish to use DNS names in certificates at all. In this scenario, all settings
  -in `elasticsearch.yml` should only use IP addresses including the `network.publish_host` setting.
  +Indicates that a client connection was made to `node01.example.com` but the
  +certificate returned did not contain the name `node01.example.com`. In most
  +cases, the issue can be resolved by ensuring the name is specified during
  +certificate creation. For more information, see <<ssl-tls>>. Another scenario is
  +when the environment does not wish to use DNS names in certificates at all. In
  +this scenario, all settings in `elasticsearch.yml` should only use IP addresses
  +including the `network.publish_host` setting.
   --
   
   `java.security.cert.CertificateException: No subject alternative names present`::
   +
   --
  -Indicates that a client connection was made to an IP address but the returned certificate did not contain any `SubjectAlternativeName` entries.
  -IP addresses are only used for hostname verification if they are specified as a `SubjectAlternativeName` during certificate creation. If the intent was to use IP addresses for hostname verification, then the certificate
  -will need to be regenerated with the appropriate IP address. See <<ssl-tls>>.
  +Indicates that a client connection was made to an IP address but the returned
  +certificate did not contain any `SubjectAlternativeName` entries. IP addresses
  +are only used for hostname verification if they are specified as a
  +`SubjectAlternativeName` during certificate creation. If the intent was to use
  +IP addresses for hostname verification, then the certificate will need to be
  +regenerated with the appropriate IP address. See <<ssl-tls>>.
   --
   
   `javax.net.ssl.SSLHandshakeException: null cert chain` and `javax.net.ssl.SSLException: Received fatal alert: bad_certificate`::
   +
   --
  -The `SSLHandshakeException` above indicates that a self-signed certificate was returned by the client that is not trusted
  -as it cannot be found in the `truststore` or `keystore`. The `SSLException` above is seen on the client side of the connection.
  +The `SSLHandshakeException` indicates that a self-signed certificate was
  +returned by the client that is not trusted as it cannot be found in the
  +`truststore` or `keystore`. This `SSLException` is seen on the client side of
  +the connection.
   --
   
   `sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target` and `javax.net.ssl.SSLException: Received fatal alert: certificate_unknown`::
   +
   --
  -The `SunCertPathBuilderException` above indicates that a certificate was returned during the handshake that is not trusted.
  -This message is seen on the client side of the connection. The `SSLException` above is seen on the server side of the
  -connection. The CA certificate that signed the returned certificate was not found in the `keystore` or `truststore` and
  -needs to be added to trust this certificate.
  ---
  -
  -[float]
  -==== Other SSL/TLS related exceptions
  -
  -The are other exceptions related to SSL that may be seen in the logs. Below you will find some common exceptions and their
  -meaning.
  -
  -WARN: received plaintext http traffic on a https channel, closing connection::
  -+
  ---
  -Indicates that there was an incoming plaintext http request. This typically occurs when an external applications attempts
  -to make an unencrypted call to the REST interface. Please ensure that all applications are using `https` when calling the
  -REST interface with SSL enabled.
  +This `SunCertPathBuilderException` indicates that a certificate was returned
  +during the handshake that is not trusted. This message is seen on the client
  +side of the connection. The `SSLException` is seen on the server side of the
  +connection. The CA certificate that signed the returned certificate was not
  +found in the `keystore` or `truststore` and needs to be added to trust this
  +certificate.
  +--
  +
  +[[trb-security-ssl]]
  +=== Common SSL/TLS exceptions
  +
  +*Symptoms:*
  +
  +* You might see some exceptions related to SSL/TLS in your logs. Some of the
  +common exceptions are shown below with tips on how to resolve these issues. +
  +
  +
  +
  +*Resolution:*
  +
  +`WARN: received plaintext http traffic on a https channel, closing connection`::
  ++
  +--
  +Indicates that there was an incoming plaintext http request. This typically
  +occurs when an external applications attempts to make an unencrypted call to the
  +REST interface. Please ensure that all applications are using `https` when
  +calling the REST interface with SSL enabled.
   --
   
   `org.elasticsearch.common.netty.handler.ssl.NotSslRecordException: not an SSL/TLS record:`::
   +
   --
  -Indicates that there was incoming plaintext traffic on an SSL connection. This typically occurs when a node is not
  -configured to use encrypted communication and tries to connect to nodes that are using encrypted communication. Please
  -verify that all nodes are using the same setting for `xpack.security.transport.ssl.enabled`.
  +Indicates that there was incoming plaintext traffic on an SSL connection. This
  +typically occurs when a node is not configured to use encrypted communication
  +and tries to connect to nodes that are using encrypted communication. Please
  +verify that all nodes are using the same setting for
  +`xpack.security.transport.ssl.enabled`.
  +
  +For more information about this setting, see
  +{ref}/security-settings.html[Security Settings in {es}].
   --
   
   `java.io.StreamCorruptedException: invalid internal transport message format, got`::
   +
   --
  -Indicates an issue with data received on the transport interface in an unknown format. This can happen when a node with
  -encrypted communication enabled connects to a node that has encrypted communication disabled. Please verify that all
  -nodes are using the same setting for `xpack.security.transport.ssl.enabled`.
  +Indicates an issue with data received on the transport interface in an unknown
  +format. This can happen when a node with encrypted communication enabled
  +connects to a node that has encrypted communication disabled. Please verify that
  +all nodes are using the same setting for `xpack.security.transport.ssl.enabled`.
  +
  +For more information about this setting, see
  +{ref}/security-settings.html[Security Settings in {es}].
   --
   
   `java.lang.IllegalArgumentException: empty text`::
   +
   --
  -The exception is typically seen when a `https` request is made to a node that is not using `https`. If `https` is desired,
  -please ensure the following setting is in `elasticsearch.yml`:
  +This exception is typically seen when a `https` request is made to a node that
  +is not using `https`. If `https` is desired, please ensure the following setting
  +is in `elasticsearch.yml`:
   
   [source,yaml]
   ----------------
   xpack.security.http.ssl.enabled: true
   ----------------
  ---
  -
  -ERROR: unsupported ciphers [...] were requested but cannot be used in this JVM::
  -+
  ---
  -This error occurs when a SSL/TLS cipher suite is specified that cannot supported by the JVM that Elasticsearch is running
  -in. Security will try to use the specified cipher suites that are supported by this JVM. This error can occur when using
  -the Security defaults as some distributions of OpenJDK do not enable the PKCS11 provider by default. In this case, we
  -recommend consulting your JVM documentation for details on how to enable the PKCS11 provider.
  -
  -Another common source of this error is requesting cipher suites that use encrypting with a key length greater than 128 bits
  -when running on an Oracle JDK. In this case, you will need to install the <<ciphers, JCE Unlimited Strength Jurisdiction Policy Files>>.
  ---
  -
  -[float]
  -==== Internal Server Error in Kibana
  -
  -If the Security plugin is enabled in Elasticsearch but disabled in Kibana, you must
  +
  +For more information about this setting, see
  +{ref}/security-settings.html[Security Settings in {es}].
  +--
  +
  +`ERROR: unsupported ciphers [...] were requested but cannot be used in this JVM`::
  ++
  +--
  +This error occurs when a SSL/TLS cipher suite is specified that cannot supported
  +by the JVM that {es} is running in. Security tries to use the specified cipher
  +suites that are supported by this JVM. This error can occur when using the
  +Security defaults as some distributions of OpenJDK do not enable the PKCS11
  +provider by default. In this case, we recommend consulting your JVM
  +documentation for details on how to enable the PKCS11 provider.
  +
  +Another common source of this error is requesting cipher suites that use
  +encrypting with a key length greater than 128 bits when running on an Oracle JDK.
  +In this case, you must install the
  +<<ciphers, JCE Unlimited Strength Jurisdiction Policy Files>>.
  +--
  +
  +[[trb-security-internalserver]]
  +=== Internal Server Error in Kibana
  +
  +*Symptoms:*
  +
  +* In 5.1.1, an `UnhandledPromiseRejectionWarning` occurs and {kib} displays an
  +Internal Server Error.
  +//TBD: Is the same true for later releases?
  +
  +*Resolution:*
  +
  +If the Security plugin is enabled in {es} but disabled in {kib}, you must
   still set `elasticsearch.username` and `elasticsearch.password` in `kibana.yml`.
  -Otherwise, Kibana cannot connect to Elasticsearch. In 5.1.1, this results in an
  -`UnhandledPromiseRejectionWarning` and Kibana displays an Internal Server Error.
  +Otherwise, {kib} cannot connect to {es}.
  
positive.code: 
  |_role definition_|
  
  The role definition may be missing or invalid.
  
  |======================
  
  To help track down these possibilities, add the following lines to the end of the `log4j2.properties` configuration file in the
  `CONFIG_DIR`:
  
  [source,properties]
  ----------------
  
negative.code: jacknich       : monitoring,unknown_role* <1>
  ------------------------------------------
  <1> `unknown_role` was not found in `roles.yml`
  
  For more information about this command, see
  {ref}/users-command.html[Users Command].
  --
  
  . If you are authenticating to LDAP, a number of configuration options can cause
  this error.
  +
  --
  |======================
  |_group identification_ |
  
  