OpenSearch/shield/docs/public/release-notes.asciidoc

[[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}/setup-upgrade.html#_1_0_and_later[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.

[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-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}/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}/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}/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 <<limitations-disable-cache,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}/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
* 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-roles, `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 <<ref-cache-hash-algo, Cache hash algorithms>>

.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