[[release-notes]] == Release Notes [float] [[version-compatibility]] === Version Compatibility Shield {version} is compatible with: * Elasticsearch: {version} * License plugin: {version} [float] [[upgrade-instructions]] === Upgrading Shield 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: [source,shell] --------------------------------------------------- bin/plugin remove shield bin/plugin install shield --------------------------------------------------- Then start the node. Larger sites should follow the steps in the {ref}/rolling-upgrades.html[rolling upgrade section] 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. [float] ==== updated role definitions 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 `roles.yml.new` after upgrading to the new version of Shield. We recommend copying the changes listed below to your `roles.yml` file. * added[2.0.0-beta2] The permission on all the roles are updated to the verbose format to make it easier to enable field level and document level security. `transport_client` role updated to work with Elasticsearch 2.0.0-beta2. `kibana3`, `marvel_user`, and `marvel_agent` roles removed. * added[1.1.0] `kibana4_server` role added that defines the minimum set of permissions necessary for the Kibana 4 server. * added[1.0.1] `kibana4` role updated to work with new features in Kibana 4 RC1 [float] [[changelist]] === Change List [float] ==== 2.0.0 .breaking changes * All files that Shield uses must be kept in the <> due to the enhanced security of Elasticsearch 2.0. * The network format has been changed from all previous versions of Shield and a full cluster restart is required to upgrade to Shield 2.0. [float] ==== 2.0.0-rc1 .enhancements * Added a caching interface that can be used by <> to integrate with the <>. .bug fixes * <> now captures requests from nodes using a different system key as tampered requests. * The <> stores the type of request when available. * <> could have allowed a user to block all access to their node if the system was incorrectly configured, but now explicitly allows connections from all addresses that the node is bound to so that connections coming from the node's host will not be blocked. [float] ==== 2.0.0-beta2 .new features * <> support has been added and can be configured per role. * Support for <> has been added, allowing Shield to integrate with more authentication sources and methods. * <> has also been added, which allows a user to send a request to elasticsearch that will be run with the specified user's permissions. .bug fixes * `esusers` and `syskeygen` work when spaces are in the elasticsearch installation path. * Fixed a rare issue where authentication fails even when the username and password are correct. [float] ==== 2.0.0-beta1 This release is primarily for compatibility with Elasticsearch 2.0.0-beta1. [float] ==== 1.3.2 .bug fixes * When using the <> mechanism, connection errors during startup no longer cause the node to stop. * The <> no longer generates invalid JSON. * The <> starts properly when forwarding the audit events to a remote cluster and uses the correct user to index the audit events. [float] ==== 1.3.1 .bug fixes * Fixes <> serialization to work with Shield 1.2.1 and earlier. ** NOTE: if you are upgrading from Shield 1.3.0 or Shield 1.2.2 a {ref-17}/setup-upgrade.html#restart-upgrade[cluster restart upgrade] will be necessary. When upgrading from other versions of Shield, follow the normal <>. [float] ==== 1.3.0 .new features * <>: Adds Public Key Infrastructure (PKI) authentication through the use of X.509 certificates in place of username and password credentials. * <>: 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 <>. 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. .enhancements * 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` <> 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`. [float] ==== 1.2.3 .bug fixes * Fixes <> serialization to work with Shield 1.2.1 and earlier. ** NOTE: if you are upgrading from Shield 1.2.2 a {ref-17}/setup-upgrade.html#restart-upgrade[cluster restart upgrade] will be necessary. When upgrading from other versions of Shield, follow the normal <>. [float] ==== 1.2.2 .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 {ref-17}/query-dsl-terms-filter.html#_caching_19[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` <> will be used. * The auditing mechanism now logs authentication failed events when a request contains an invalid authentication token. [float] ==== 1.2.1 .bug fixes * Several bug fixes including a fix to ensure that {ref-17}/disk.html[Disk-based Shard Allocation] works properly with Shield [float] ==== 1.2.0 .enhancements * Adds support for Elasticsearch 1.5 [float] ==== 1.1.1 .bug fixes * Several bug fixes including a fix to ensure that {ref-17}/disk.html[Disk-based Shard Allocation] works properly with Shield [float] ==== 1.1.0 .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 <> for more information. ** User distinguished names (DNs) can now be used for <>. * Authentication: ** <> is now supported (disabled by default). * IP Filtering: ** IP Filtering settings can now be <> using the {ref}/cluster-update-settings.html[Cluster Update Settings API]. .enhancements * 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 <>, 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 <> .bug fixes * Filter out sensitive settings from the settings APIs [float] ==== 1.0.2 .bug fixes * Filter out sensitive settings from the settings APIs * Significant memory footprint reduction of internal data structures [float] ==== 1.0.1 .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