<commit_before>[[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 <<ref-shield-files-location, configuration directory>> 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 <<custom-realms, custom authentication realms>> to integrate with the <<cache-eviction-api, cache eviction api>>.

.bug fixes
* <<configuring-auditing, Auditing>> now captures requests from nodes using a different system key as tampered requests.
* The <<audit-index, index output for auditing>> stores the type of request when available.
* <<ip-filtering, IP filtering>> 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
* <<setting-up-field-and-document-level-security, Document and Field Level Security>> support has been added and can be
configured per role.
* Support for <<custom-realms, custom authentication realms>> has been added, allowing Shield to integrate with more authentication sources and methods.
* <<submitting-requests-for-other-users, User impersonation support>> 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 <<ldap-user-search,LDAP user search>> mechanism, connection errors during startup no longer cause the node to stop.
* The <<cache-eviction-api,Cache Eviction API>> no longer generates invalid JSON.
* The <<audit-index,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.

[float]
==== 1.3.1

.bug fixes
* Fixes <<enable-message-authentication,message authentication>> 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 <<upgrade-instructions,upgrade procedure>>.

[float]
==== 1.3.0

.new features
* <<pki,PKI Realm>>: Adds Public Key Infrastructure (PKI) authentication through the use of X.509 certificates in place of
 username and password credentials.
* <<configuring-auditing, 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 <<ref-cache-hash-algo,`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.

.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` <<anonymous-access,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`.

[float]
==== 1.2.3

.bug fixes
* Fixes <<enable-message-authentication,message authentication>> 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 <<upgrade-instructions,upgrade procedure>>.

[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` <<ref-ssl-tls-settings,settings>> 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}/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 <<ldap-user-search, ldap user search>>
for more information.
** User distinguished names (DNs) can now be used for <<ldap-role-mapping, role mapping>>.
* Authentication:
** <<anonymous-access, Anonymous access>> is now supported (disabled by default).
* IP Filtering:
** IP Filtering settings can now be <<dynamic-ip-filtering,dynamically updated>> using the {ref}/cluster-update-settings.html[Cluster Update Settings API].

.enhancements
* Significant memory footprint reduction of internal data structures<commit_msg>Shield Docs: Fixed another cross doc problem.<commit_after>[[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 <<ref-shield-files-location, configuration directory>> 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 <<custom-realms, custom authentication realms>> to integrate with the <<cache-eviction-api, cache eviction api>>.

.bug fixes
* <<configuring-auditing, Auditing>> now captures requests from nodes using a different system key as tampered requests.
* The <<audit-index, index output for auditing>> stores the type of request when available.
* <<ip-filtering, IP filtering>> 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
* <<setting-up-field-and-document-level-security, Document and Field Level Security>> support has been added and can be
configured per role.
* Support for <<custom-realms, custom authentication realms>> has been added, allowing Shield to integrate with more authentication sources and methods.
* <<submitting-requests-for-other-users, User impersonation support>> 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 <<ldap-user-search,LDAP user search>> mechanism, connection errors during startup no longer cause the node to stop.
* The <<cache-eviction-api,Cache Eviction API>> no longer generates invalid JSON.
* The <<audit-index,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.

[float]
==== 1.3.1

.bug fixes
* Fixes <<enable-message-authentication,message authentication>> 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 <<upgrade-instructions,upgrade procedure>>.

[float]
==== 1.3.0

.new features
* <<pki,PKI Realm>>: Adds Public Key Infrastructure (PKI) authentication through the use of X.509 certificates in place of
 username and password credentials.
* <<configuring-auditing, 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 <<ref-cache-hash-algo,`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.

.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` <<anonymous-access,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`.

[float]
==== 1.2.3

.bug fixes
* Fixes <<enable-message-authentication,message authentication>> 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 <<upgrade-instructions,upgrade procedure>>.

[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` <<ref-ssl-tls-settings,settings>> 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 <<ldap-user-search, ldap user search>>
for more information.
** User distinguished names (DNs) can now be used for <<ldap-role-mapping, role mapping>>.
* Authentication:
** <<anonymous-access, Anonymous access>> is now supported (disabled by default).
* IP Filtering:
** IP Filtering settings can now be <<dynamic-ip-filtering,dynamically updated>> using the {ref}/cluster-update-settings.html[Cluster Update Settings API].

.enhancements
* Significant memory footprint reduction of internal data structures
{'fraction_non_alphanumeric': 0.09352860629874382, 'fraction_numerical': 0.01321664582961243, 'mean_word_length': 4.473444118605409, 'pattern_counts': {'":': 0, '<': 103, '<?xml version=': 0, '>': 103, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2966775', 'n_tokens_mistral': 4670, 'n_tokens_neox': 4417, 'n_words': 2141}