Release Notesedit

Version Compatibilityedit

Shield 1.3.x is compatible with:

  • Elasticsearch: 1.5.0+
  • License plugin: 1.0

Upgrading Shieldedit

To upgrade Shield, just uninstall the current Shield plugin and install the new version of Shield. Your configuration will be preserved and you do this with a rolling upgrade of Elasticsearch. On each node, after you have stopped it run:

bin/plugin -r shield
bin/plugin -i elasticsearch/shield/latest 

latest will install the latest version of Shield compatible with your version of Elasticsearch. A specific version, such as 1.1.0 can also be specified.

Then start the node. Larger sites should follow the steps in the rolling upgrade section in order to ensure recovery is as quick as possible.

On upgrade, your current configuration files will remain untouched. The configuration files provided by the new version of Shield will be added with a .new extension.

updated role definitionsedit

The default role definitions in the roles.yml file may need to be changed to ensure proper functionality with other applications such as Marvel and Kibana. Any role changes will be found in after upgrading to the new version of Shield. We recommend copying the changes listed below to your roles.yml file.

  • [1.1.0] Added in 1.1.0. kibana4_server role added that defines the minimum set of permissions necessary for the Kibana 4 server.
  • [1.0.1] Added in 1.0.1. kibana4 role updated to work with new features in Kibana 4 RC1

Change Listedit


bug fixes

  • Fixes a rare issue during user authentication where valid passwords are treated as invalid.
  • The index output for auditing now properly saves the type of request in the indexed document.


  • Tampered requests with a bad header are now audited.


bug fixes

  • When using the LDAP user search mechanism, connection errors during startup no longer cause the node to stop.
  • The Cache Eviction API no longer generates invalid JSON.
  • The index output for auditing starts properly when forwarding the audit events to a remote cluster and uses the correct user to index the audit events.


bug fixes


new features

  • PKI Realm: Adds Public Key Infrastructure (PKI) authentication through the use of X.509 certificates in place of username and password credentials.
  • Index Output for Audit Events: An index based output has been added for storing audit events in an Elasticsearch index.

breaking changes

  • The sha2 and apr1 hashing algorithms have been removed as options for the cache.hash_algo setting. If your existing Shield installation uses either of these options, remove the setting and use the default ssha256 algorithm.
  • The users file now only supports bcrypt password hashing. All existing passwords stored using the esusers tool have been hashed with bcrypt and are not affected.


  • TLS 1.2 is now the default protocol.
  • Clients that do not support pre-emptive basic authentication can now support both anonymous and authenticated access by specifying the shield.authc.anonymous.authz_exception setting with a value of false.
  • Reduced logging for common SSL exceptions, such as a client closing the connection during a handshake.

bug fixes

  • The esusers and syskeygen tools now work correctly with environment variables in the RPM and DEB installation environment files /etc/sysconfig/elasticsearch and /etc/default/elasticsearch.
  • Default ciphers no longer include TLS_DHE_RSA_WITH_AES_128_CBC_SHA.


bug fixes


bug fixes

  • The esusers tool no longer warns about missing roles that are properly defined in the roles.yml file.
  • The period character, ., is now allowed in usernames and role names.
  • The terms filter lookup cache has been disabled to ensure all requests are properly authorized. This removes the need to manually disable the terms filter cache.
  • For LDAP client connections, only the protocols and ciphers specified in the shield.ssl.supported_protocols and shield.ssl.ciphers settings will be used.
  • The auditing mechanism now logs authentication failed events when a request contains an invalid authentication token.


bug fixes



  • Adds support for Elasticsearch 1.5


bug fixes


new features

  • LDAP:

    • Add the ability to bind as a specific user for LDAP searches, which removes the need to specify user_dn_templates. This mode of operation also makes use of connection pooling for better performance. Please see ldap user search for more information.
    • User distinguished names (DNs) can now be used for role mapping.
  • Authentication:

  • IP Filtering:


  • Significant memory footprint reduction of internal data structures
  • Test if SSL/TLS ciphers are supported and warn if any of the specified ciphers are not supported
  • Reduce the amount of logging when a non-encrypted connection is opened and https is being used
  • Added the kibana4_server role, which is a role that contains the minimum set of permissions required for the Kibana 4 server.
  • In-memory user credential caching hash algorithm defaults now to salted SHA-256 (see Cache hash algorithms

bug fixes

  • Filter out sensitive settings from the settings APIs


bug fixes

  • Filter out sensitive settings from the settings APIs
  • Significant memory footprint reduction of internal data structures


bug fixes

  • Fixed dependency issues with Elasticsearch 1.4.3 and (Lucene 4.10.3 that comes with it)
  • Fixed bug in how user roles were handled. When multiple roles were defined for a user, and one of the roles only had cluster permissions, not all privileges were properly evaluated.
  • Updated kibana4 permissions to be compatible with Kibana 4 RC1
  • Ensure the mandatory base_dn settings is set in the ldap realm configuration