You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@bookkeeper.apache.org by si...@apache.org on 2017/08/07 18:47:09 UTC
[bookkeeper] branch branch-4.5 updated: ISSUE #349: Documentation
for security feature in 4.5.0
This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch branch-4.5
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git
The following commit(s) were added to refs/heads/branch-4.5 by this push:
new ee8fca9 ISSUE #349: Documentation for security feature in 4.5.0
ee8fca9 is described below
commit ee8fca97f069244caa62f222e227d7be37f1577d
Author: Sijie Guo <si...@apache.org>
AuthorDate: Mon Aug 7 11:46:19 2017 -0700
ISSUE #349: Documentation for security feature in 4.5.0
Descriptions of the changes in this PR:
- add a section for `security`
- overview to introduce security feature
- encryption and authentication using tls
- sasl authentication
- zookeeper authentication
Author: Sijie Guo <si...@apache.org>
Reviewers: Luc Perkins <lu...@gmail.com>, Matteo Merli <mm...@apache.org>
This closes #350 from sijie/security_docs, closes #349
(cherry picked from commit 49b90a66f830482fc970ba625057c7101c201f62)
Signed-off-by: Sijie Guo <si...@apache.org>
---
.../bookkeeper/conf/ServerConfiguration.java | 1 -
site/_data/sidebar.yaml | 11 ++
site/docs/security/index.md | 21 +++
site/docs/security/sasl.md | 202 ++++++++++++++++++++
site/docs/security/tls.md | 210 +++++++++++++++++++++
site/docs/security/zookeeper.md | 41 ++++
6 files changed, 485 insertions(+), 1 deletion(-)
diff --git a/bookkeeper-server/src/main/java/org/apache/bookkeeper/conf/ServerConfiguration.java b/bookkeeper-server/src/main/java/org/apache/bookkeeper/conf/ServerConfiguration.java
index 733e0f7..ce8b1bf 100644
--- a/bookkeeper-server/src/main/java/org/apache/bookkeeper/conf/ServerConfiguration.java
+++ b/bookkeeper-server/src/main/java/org/apache/bookkeeper/conf/ServerConfiguration.java
@@ -155,7 +155,6 @@ public class ServerConfiguration extends AbstractConfiguration {
protected final static String ALLOW_MULTIPLEDIRS_UNDER_SAME_DISKPARTITION = "allowMultipleDirsUnderSameDiskPartition";
- protected final static String TLS_CLIENT_AUTHENTICATION = "tlsClientAuthentication";
protected final static String TLS_KEYSTORE_TYPE = "tlsKeyStoreType";
protected final static String TLS_KEYSTORE = "tlsKeyStore";
protected final static String TLS_KEYSTORE_PASSWORD_PATH = "tlsKeyStorePasswordPath";
diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index 5136df6..1211a48 100644
--- a/site/_data/sidebar.yaml
+++ b/site/_data/sidebar.yaml
@@ -52,6 +52,17 @@ groups:
endpoint: protocol
#- name: Codebase
# endpoint: codebase
+- name: Security
+ dir: security
+ docs:
+ - name: Overview
+ endpoint: index
+ - name: TLS Authentication
+ endpoint: tls
+ - name: SASL Authentication
+ endpoint: sasl
+ - name: ZooKeeper Authentication
+ endpoint: zookeeper
- name: Reference
dir: reference
docs:
diff --git a/site/docs/security/index.md b/site/docs/security/index.md
new file mode 100644
index 0000000..059a309
--- /dev/null
+++ b/site/docs/security/index.md
@@ -0,0 +1,21 @@
+---
+title: BookKeeper Security
+next: ./tls.html
+---
+
+In the 4.5.0 release, the BookKeeper community added a number of features that can be used, together or separately, to secure a BookKeeper cluster.
+The following security measures are currently supported:
+
+1. Authentication of connections to bookies from clients, using either [TLS](./tls) or [SASL (Kerberos)](./sasl).
+2. Authentication of connections from clients, bookies, autorecovery daemons to [ZooKeeper](./zookeeper), when using zookeeper based ledger managers.
+3. Encryption of data transferred between bookies and clients, between bookies and autorecovery daemons using [TLS](./tls).
+
+It’s worth noting that security is optional - non-secured clusters are supported, as well as a mix of authenticated, unauthenticated, encrypted and non-encrypted clients.
+
+NOTE: currently `authorization` is not yet available in `4.5.0`. The Apache BookKeeper community is looking for adding this feature in subsequent releases.
+
+## Next Steps
+
+- [Encryption and Authentication using TLS](./tls)
+- [Authentication using SASL](./sasl)
+- [ZooKeeper Authentication](./zookeeper)
diff --git a/site/docs/security/sasl.md b/site/docs/security/sasl.md
new file mode 100644
index 0000000..ffb972a
--- /dev/null
+++ b/site/docs/security/sasl.md
@@ -0,0 +1,202 @@
+---
+title: Authentication using SASL
+prev: ../tls
+next: ../zookeeper
+---
+
+Bookies support client authentication via SASL. Currently we only support GSSAPI (Kerberos). We will start
+with a general description of how to configure `SASL` for bookies, clients and autorecovery daemons, followed
+by mechanism-specific details and wrap up with some operational details.
+
+## SASL configuration for Bookies
+
+1. Select the mechanisms to enable in the bookies. `GSSAPI` is the only mechanism currently supported by BookKeeper.
+2. Add a `JAAS` config file for the selected mechanisms as described in the examples for setting up [GSSAPI (Kerberos)](#kerberos).
+3. Pass the `JAAS` config file location as JVM parameter to each Bookie. For example:
+
+ ```shell
+ -Djava.security.auth.login.config=/etc/bookkeeper/bookie_jaas.conf
+ ```
+
+4. Enable SASL auth plugin in bookies, by setting `bookieAuthProviderFactoryClass` to `org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory`.
+
+
+ ```shell
+ bookieAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory
+ ```
+
+5. If you are running `autorecovery` along with bookies, then you want to enable SASL auth plugin for `autorecovery`, by setting
+ `clientAuthProviderFactoryClass` to `org.apache.bookkeeper.sasl.SASLClientProviderFactory`.
+
+ ```shell
+ clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+ ```
+
+6. Follow the steps in [GSSAPI (Kerberos)](#kerberos) to configure SASL.
+
+#### <a name="notes"></a> Important Notes
+
+1. `Bookie` is a section name in the JAAS file used by each bookie. This section tells the bookie which principal to use
+ and the location of the keytab where the principal is stored. It allows the bookie to login using the keytab specified in this section.
+2. `Auditor` is a section name in the JASS file used by `autorecovery` daemon (it can be co-run with bookies). This section tells the
+ `autorecovery` daemon which principal to use and the location of the keytab where the principal is stored. It allows the bookie to
+ login using the keytab specified in this section.
+3. The `Client` section is used to authenticate a SASL connection with ZooKeeper. It also allows the bookies to set ACLs on ZooKeeper nodes
+ which locks these nodes down so that only the bookies can modify it. It is necessary to have the same primary name across all bookies.
+ If you want to use a section name other than `Client`, set the system property `zookeeper.sasl.client` to the appropriate name
+ (e.g `-Dzookeeper.sasl.client=ZKClient`).
+4. ZooKeeper uses `zookeeper` as the service name by default. If you want to change this, set the system property
+ `zookeeper.sasl.client.username` to the appropriate name (e.g. `-Dzookeeper.sasl.client.username=zk`).
+
+## SASL configuration for Clients
+
+To configure `SASL` authentication on the clients:
+
+1. Select a `SASL` mechanism for authentication and add a `JAAS` config file for the selected mechanism as described in the examples for
+ setting up [GSSAPI (Kerberos)](#kerberos).
+2. Pass the `JAAS` config file location as JVM parameter to each client JVM. For example:
+
+ ```shell
+ -Djava.security.auth.login.config=/etc/bookkeeper/bookkeeper_jaas.conf
+ ```
+
+3. Configure the following properties in bookkeeper `ClientConfiguration`:
+
+ ```shell
+ clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+ ```
+
+Follow the steps in [GSSAPI (Kerberos)](#kerberos) to configure SASL for the selected mechanism.
+
+## <a name="kerberos"></a> Authentication using SASL/Kerberos
+
+### Prerequisites
+
+#### Kerberos
+
+If your organization is already using a Kerberos server (for example, by using `Active Directory`), there is no need to
+install a new server just for BookKeeper. Otherwise you will need to install one, your Linux vendor likely has packages
+for `Kerberos` and a short guide on how to install and configure it ([Ubuntu](https://help.ubuntu.com/community/Kerberos),
+[Redhat](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/installing-kerberos.html)).
+Note that if you are using Oracle Java, you will need to download JCE policy files for your Java version and copy them to `$JAVA_HOME/jre/lib/security`.
+
+#### Kerberos Principals
+
+If you are using the organization’s Kerberos or Active Directory server, ask your Kerberos administrator for a principal
+for each Bookie in your cluster and for every operating system user that will access BookKeeper with Kerberos authentication
+(via clients and tools).
+
+If you have installed your own Kerberos, you will need to create these principals yourself using the following commands:
+
+```shell
+sudo /usr/sbin/kadmin.local -q 'addprinc -randkey bookkeeper/{hostname}@{REALM}'
+sudo /usr/sbin/kadmin.local -q "ktadd -k /etc/security/keytabs/{keytabname}.keytab bookkeeper/{hostname}@{REALM}"
+```
+
+##### All hosts must be reachable using hostnames
+
+It is a *Kerberos* requirement that all your hosts can be resolved with their FQDNs.
+
+### Configuring Bookies
+
+1. Add a suitably modified JAAS file similar to the one below to each Bookie’s config directory, let’s call it `bookie_jaas.conf`
+for this example (note that each bookie should have its own keytab):
+
+ ```
+ Bookie {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ keyTab="/etc/security/keytabs/bookie.keytab"
+ principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
+ };
+ // ZooKeeper client authentication
+ Client {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ keyTab="/etc/security/keytabs/bookie.keytab"
+ principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
+ };
+ // If you are running `autorecovery` along with bookies
+ Auditor {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ keyTab="/etc/security/keytabs/bookie.keytab"
+ principal="bookkeeper/bk1.hostname.com@EXAMPLE.COM";
+ };
+ ```
+
+ The `Bookie` section in the JAAS file tells the bookie which principal to use and the location of the keytab where this principal is stored.
+ It allows the bookie to login using the keytab specified in this section. See [notes](#notes) for more details on Zookeeper’s SASL configuration.
+
+2. Pass the name of the JAAS file as a JVM parameter to each Bookie:
+
+ ```shell
+ -Djava.security.auth.login.config=/etc/bookkeeper/bookie_jaas.conf
+ ```
+
+ You may also wish to specify the path to the `krb5.conf` file
+ (see [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details):
+
+ ```shell
+ -Djava.security.krb5.conf=/etc/bookkeeper/krb5.conf
+ ```
+
+3. Make sure the keytabs configured in the JAAS file are readable by the operating system user who is starting the Bookies.
+
+4. Enable SASL authentication plugin in the bookies by setting following parameters.
+
+ ```shell
+ bookieAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLBookieAuthProviderFactory
+ # if you run `autorecovery` along with bookies
+ clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+ ```
+
+### Configuring Clients
+
+To configure SASL authentication on the clients:
+
+1. Clients will authenticate to the cluster with their own principal (usually with the same name as the user running the client),
+ so obtain or create these principals as needed. Then create a `JAAS` file for each principal. The `BookKeeper` section describes
+ how the clients like writers and readers can connect to the Bookies. The following is an example configuration for a client using
+ a keytab (recommended for long-running processes):
+
+ ```
+ BookKeeper {
+ com.sun.security.auth.module.Krb5LoginModule required
+ useKeyTab=true
+ storeKey=true
+ keyTab="/etc/security/keytabs/bookkeeper.keytab"
+ principal="bookkeeper-client-1@EXAMPLE.COM";
+ };
+ ```
+
+
+2. Pass the name of the JAAS file as a JVM parameter to the client JVM:
+
+ ```shell
+ -Djava.security.auth.login.config=/etc/bookkeeper/bookkeeper_jaas.conf
+ ```
+
+ You may also wish to specify the path to the `krb5.conf` file (see
+ [JDK’s Kerberos Requirements](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/KerberosReq.html) for more details).
+
+ ```shell
+ -Djava.security.krb5.conf=/etc/bookkeeper/krb5.conf
+ ```
+
+
+3. Make sure the keytabs configured in the `bookkeeper_jaas.conf` are readable by the operating system user who is starting bookkeeper client.
+
+4. Enable SASL authentication plugin in the client by setting following parameters.
+
+ ```shell
+ clientAuthProviderFactoryClass=org.apache.bookkeeper.sasl.SASLClientProviderFactory
+ ```
+
+## Enabling Logging for SASL
+
+To enable SASL debug output, you can set `sun.security.krb5.debug` system property to `true`.
+
diff --git a/site/docs/security/tls.md b/site/docs/security/tls.md
new file mode 100644
index 0000000..ff5ac2c
--- /dev/null
+++ b/site/docs/security/tls.md
@@ -0,0 +1,210 @@
+---
+title: Encryption and Authentication using TLS
+prev: ../index.html
+next: ../sasl
+---
+
+Apache BookKeeper allows clients and autorecovery daemons to communicate over TLS, although this is not enabled by default.
+
+## Overview
+
+The bookies need their own key and certificate in order to use TLS. Clients can optionally provide a key and a certificate
+for mutual authentication. Each bookie or client can also be configured with a truststore, which is used to
+determine which certificates (bookie or client identities) to trust (authenticate).
+
+The truststore can be configured in many ways. To understand the truststore, consider the following two examples:
+
+1. the truststore contains one or many certificates;
+2. it contains a certificate authority (CA).
+
+In (1), with a list of certificates, the bookie or client will trust any certificate listed in the truststore.
+In (2), with a CA, the bookie or client will trust any certificate that was signed by the CA in the truststore.
+
+(TBD: benefits)
+
+## <a name="bookie-keystore"></a> Generate TLS key and certificate
+
+The first step of deploying TLS is to generate the key and the certificate for each machine in the cluster.
+You can use Java’s `keytool` utility to accomplish this task. We will generate the key into a temporary keystore
+initially so that we can export and sign it later with CA.
+
+```shell
+keytool -keystore bookie.keystore.jks -alias localhost -validity {validity} -genkey
+```
+
+You need to specify two parameters in the above command:
+
+1. `keystore`: the keystore file that stores the certificate. The *keystore* file contains the private key of
+ the certificate; hence, it needs to be kept safely.
+2. `validity`: the valid time of the certificate in days.
+
+<div class="alert alert-success">
+Ensure that common name (CN) matches exactly with the fully qualified domain name (FQDN) of the server.
+The client compares the CN with the DNS domain name to ensure that it is indeed connecting to the desired server, not a malicious one.
+</div>
+
+## Creating your own CA
+
+After the first step, each machine in the cluster has a public-private key pair, and a certificate to identify the machine.
+The certificate, however, is unsigned, which means that an attacker can create such a certificate to pretend to be any machine.
+
+Therefore, it is important to prevent forged certificates by signing them for each machine in the cluster.
+A `certificate authority (CA)` is responsible for signing certificates. CA works likes a government that issues passports —
+the government stamps (signs) each passport so that the passport becomes difficult to forge. Other governments verify the stamps
+to ensure the passport is authentic. Similarly, the CA signs the certificates, and the cryptography guarantees that a signed
+certificate is computationally difficult to forge. Thus, as long as the CA is a genuine and trusted authority, the clients have
+high assurance that they are connecting to the authentic machines.
+
+```shell
+openssl req -new -x509 -keyout ca-key -out ca-cert -days 365
+```
+
+The generated CA is simply a *public-private* key pair and certificate, and it is intended to sign other certificates.
+
+The next step is to add the generated CA to the clients' truststore so that the clients can trust this CA:
+
+```shell
+keytool -keystore bookie.truststore.jks -alias CARoot -import -file ca-cert
+```
+
+NOTE: If you configure the bookies to require client authentication by setting `sslClientAuthentication` to `true` on the
+[bookie config](../../reference/config), then you must also provide a truststore for the bookies and it should have all the CA
+certificates that clients keys were signed by.
+
+```shell
+keytool -keystore client.truststore.jks -alias CARoot -import -file ca-cert
+```
+
+In contrast to the keystore, which stores each machine’s own identity, the truststore of a client stores all the certificates
+that the client should trust. Importing a certificate into one’s truststore also means trusting all certificates that are signed
+by that certificate. As the analogy above, trusting the government (CA) also means trusting all passports (certificates) that
+it has issued. This attribute is called the chain of trust, and it is particularly useful when deploying TLS on a large BookKeeper cluster.
+You can sign all certificates in the cluster with a single CA, and have all machines share the same truststore that trusts the CA.
+That way all machines can authenticate all other machines.
+
+## Signing the certificate
+
+The next step is to sign all certificates in the keystore with the CA we generated. First, you need to export the certificate from the keystore:
+
+```shell
+keytool -keystore bookie.keystore.jks -alias localhost -certreq -file cert-file
+```
+
+Then sign it with the CA:
+
+```shell
+openssl x509 -req -CA ca-cert -CAkey ca-key -in cert-file -out cert-signed -days {validity} -CAcreateserial -passin pass:{ca-password}
+```
+
+Finally, you need to import both the certificate of the CA and the signed certificate into the keystore:
+
+```shell
+keytool -keystore bookie.keystore.jks -alias CARoot -import -file ca-cert
+keytool -keystore bookie.keystore.jks -alias localhost -import -file cert-signed
+```
+
+The definitions of the parameters are the following:
+
+1. `keystore`: the location of the keystore
+2. `ca-cert`: the certificate of the CA
+3. `ca-key`: the private key of the CA
+4. `ca-password`: the passphrase of the CA
+5. `cert-file`: the exported, unsigned certificate of the bookie
+6. `cert-signed`: the signed certificate of the bookie
+
+(TBD: add a script to automatically generate truststores and keystores.)
+
+## Configuring Bookies
+
+Bookies support TLS for connections on the same service port. In order to enable TLS, you need to configure `tlsProvider` to be either
+`JDK` or `OpenSSL`. If `OpenSSL` is configured, it will use `netty-tcnative-boringssl-static`, which loads a corresponding binding according
+to the platforms to run bookies.
+
+> Current `OpenSSL` implementation doesn't depend on the system installed OpenSSL library. If you want to leverage the OpenSSL installed on
+the system, you can check [this example](http://netty.io/wiki/forked-tomcat-native.html) on how to replaces the JARs on the classpath with
+netty bindings to leverage installed OpenSSL.
+
+The following TLS configs are needed on the bookie side:
+
+```shell
+tlsProvider=OpenSSL
+# key store
+tlsKeyStoreType=JKS
+tlsKeyStore=/var/private/tls/bookie.keystore.jks
+tlsKeyStorePasswordPath=/var/private/tls/bookie.keystore.passwd
+# trust store
+tlsTrustStoreType=JKS
+tlsTrustStore=/var/private/tls/bookie.truststore.jks
+tlsTrustStorePasswordPath=/var/private/tls/bookie.truststore.passwd
+```
+
+NOTE: it is important to restrict access to the store files and corresponding password files via filesystem permissions.
+
+Optional settings that are worth considering:
+
+1. tlsClientAuthentication=false: Enable/Disable using TLS for authentication. This config when enabled will authenticate the other end
+ of the communication channel. It should be enabled on both bookies and clients for mutual TLS.
+2. tlsEnabledCipherSuites= A cipher suite is a named combination of authentication, encryption, MAC and key exchange
+ algorithm used to negotiate the security settings for a network connection using TLS network protocol. By default,
+ it is null. [OpenSSL Ciphers](https://www.openssl.org/docs/man1.0.2/apps/ciphers.html)
+ [JDK Ciphers](http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites)
+3. tlsEnabledProtocols = TLSv1.2,TLSv1.1,TLSv1 (list out the TLS protocols that you are going to accept from clients).
+ By default, it is not set.
+
+To verify the bookie's keystore and truststore are setup correctly you can run the following command:
+
+```shell
+openssl s_client -debug -connect localhost:3181 -tls1
+```
+
+NOTE: TLSv1 should be listed under `tlsEnabledProtocols`.
+
+In the output of this command you should see the server's certificate:
+
+```shell
+-----BEGIN CERTIFICATE-----
+{variable sized random bytes}
+-----END CERTIFICATE-----
+```
+
+If the certificate does not show up or if there are any other error messages then your keystore is not setup correctly.
+
+## Configuring Clients
+
+TLS is supported only for the new BookKeeper client (BookKeeper versions 4.5.0 and higher), the older clients are not
+supported. The configs for TLS will be the same as bookies.
+
+If client authentication is not required by the bookies, the following is a minimal configuration example:
+
+```shell
+tlsProvider=OpenSSL
+clientTrustStore=/var/private/tls/client.truststore.jks
+clientTrustStorePasswordPath=/var/private/tls/client.truststore.passwd
+```
+
+If client authentication is required, then a keystore must be created for each client, and the bookies' truststores must
+trust the certificate in the client's keystore. This may be done using commands that are similar to what we used for
+the [bookie keystore](#bookie-keystore).
+
+And the following must also be configured:
+
+```shell
+tlsClientAuthentication=true
+clientKeyStore=/var/private/tls/client.keystore.jks
+clientKeyStorePasswordPath=/var/private/tls/client.keystore.passwd
+```
+
+NOTE: it is important to restrict access to the store files and corresponding password files via filesystem permissions.
+
+(TBD: add example to use tls in bin/bookkeeper script?)
+
+## Enabling TLS Logging
+
+You can enable TLS debug logging at the JVM level by starting the bookies and/or clients with `javax.net.debug` system property. For example:
+
+```shell
+-Djavax.net.debug=all
+```
+
+You can find more details on this in [Oracle documentation](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html) on
+[debugging SSL/TLS connections](http://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html).
diff --git a/site/docs/security/zookeeper.md b/site/docs/security/zookeeper.md
new file mode 100644
index 0000000..e16be69
--- /dev/null
+++ b/site/docs/security/zookeeper.md
@@ -0,0 +1,41 @@
+---
+title: ZooKeeper Authentication
+prev: ../sasl
+---
+
+## New Clusters
+
+To enable `ZooKeeper` authentication on Bookies or Clients, there are two necessary steps:
+
+1. Create a `JAAS` login file and set the appropriate system property to point to it as described in [GSSAPI (Kerberos)](../sasl#notes).
+2. Set the configuration property `zkEnableSecurity` in each bookie to `true`.
+
+The metadata stored in `ZooKeeper` is such that only certain clients will be able to modify and read the corresponding znodes.
+The rationale behind this decision is that the data stored in ZooKeeper is not sensitive, but inappropriate manipulation of znodes can cause cluster
+disruption.
+
+## Migrating Clusters
+
+If you are running a version of BookKeeper that does not support security or simply with security disabled, and you want to make the cluster secure,
+then you need to execute the following steps to enable ZooKeeper authentication with minimal disruption to your operations.
+
+1. Perform a rolling restart setting the `JAAS` login file, which enables bookie or clients to authenticate. At the end of the rolling restart,
+ bookies (or clients) are able to manipulate znodes with strict ACLs, but they will not create znodes with those ACLs.
+2. Perform a second rolling restart of bookies, this time setting the configuration parameter `zkEnableSecurity` to true, which enables the use
+ of secure ACLs when creating znodes.
+3. Currently we don't have provide a tool to set acls on old znodes. You are recommended to set it manually using ZooKeeper tools.
+
+It is also possible to turn off authentication in a secured cluster. To do it, follow these steps:
+
+1. Perform a rolling restart of bookies setting the `JAAS` login file, which enable bookies to authenticate, but setting `zkEnableSecurity` to `false`.
+ At the end of rolling restart, bookies stop creating znodes with secure ACLs, but are still able to authenticate and manipulate all znodes.
+2. You can use ZooKeeper tools to manually reset all ACLs under the znode set in `zkLedgersRootPath`, which defaults to `/ledgers`.
+3. Perform a second rolling restart of bookies, this time omitting the system property that sets the `JAAS` login file.
+
+## Migrating the ZooKeeper ensemble
+
+It is also necessary to enable authentication on the `ZooKeeper` ensemble. To do it, we need to perform a rolling restart of the ensemble and
+set a few properties. Please refer to the ZooKeeper documentation for more details.
+
+1. [Apache ZooKeeper Documentation](http://zookeeper.apache.org/doc/r3.4.6/zookeeperProgrammers.html#sc_ZooKeeperAccessControl)
+2. [Apache ZooKeeper Wiki](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Zookeeper+and+SASL)
--
To stop receiving notification emails like this one, please contact
['"commits@bookkeeper.apache.org" <co...@bookkeeper.apache.org>'].