anchor.diff:  [[security-troubleshooting]]
   == {security} Troubleshooting
   
  -[float]
  -=== `settings`
  -
  -Some settings are not returned via the nodes settings API::
  -+
  ---
  +Use the information in this section to troubleshoot common problems and find
  +answers for frequently asked questions.
  +
  +* <<security-trb-settings>>
  +* <<security-trb-roles>>
  +* <<security-trb-extraargs>>
  +* <<trouble-shoot-active-directory>>
  +* <<trb-security-maccurl>>
  +* <<trb-security-sslhandshake>>
  +* <<trb-security-ssl>>
  +* <<trb-security-internalserver>>
  +
  +
  +To get help, see <<xpack-help>>.
  +
  +[[security-trb-settings]]
  +=== Some settings are not returned via the nodes settings API
  +
  +*Symptoms:*
  +
  +* When you use the {ref}/cluster-nodes-info.html[nodes info API] to retrieve
  +settings for a node, some information is missing.
  +
  +*Resolution:*
  +
   This is intentional. Some of the settings are considered to be highly
  -sensitive: all `ssl` settings, ldap `bind_dn`, `bind_password`).
  -For this reason, we filter these  settings and do not expose them via
  +sensitive: all `ssl` settings, ldap `bind_dn`, and `bind_password`.
  +For this reason, we filter these settings and do not expose them via
   the nodes info API rest endpoint. You can also define additional
  -sensitive settings that should be hidden  using the
  +sensitive settings that should be hidden using the
   `xpack.security.hide_settings` setting. For example, this snippet
   hides the `url` settings of the `ldap1` realm and all settings of the
   `ad1` realm.
   
   [source, yaml]
   ------------------------------------------
  -xpack.security.hide_settings: xpack.security.authc.realms.ldap1.url, xpack.security.authc.realms.ad1.*
  +xpack.security.hide_settings: xpack.security.authc.realms.ldap1.url,
  +xpack.security.authc.realms.ad1.*
   ------------------------------------------
   
  ---
  -
  -[float]
  -=== `users`
  -
  -I configured the appropriate roles and the users, but I still get an authorization exception::
  -+
  ---
  -Verify that the role names associated with the users match the roles defined in the `roles.yml` file. You
  -can use the `users` tool to list all the users. Any unknown roles are marked with `*`.
  -
  +[[security-trb-roles]]
  +=== Authorization exceptions
  +
  +*Symptoms:*
  +
  +* I configured the appropriate roles and the users, but I still get an
  +authorization exception.
  +* I can authenticate to LDAP, but I still get an authorization exception.
  +
  +
  +*Resolution:*
  +
  +. Verify that the role names associated with the users match the roles defined
  +in the `roles.yml` file. You can use the `users` tool to list all the users. Any
  +unknown roles are marked with `*`.
  ++
  +--
   [source, shell]
   ------------------------------------------
   bin/xpack/users list
  
positive.code: 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.
  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.
  
  `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.
  --
  
  `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>>.
  --
  
  `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.
  --
  
  `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.
  --
  
  `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`.
  --
  
  `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`.
  --
  
  `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`:
  
  [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
  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.
  
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_ |
  
  