bookkeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From si...@apache.org
Subject [bookkeeper] branch branch-4.5 updated: ISSUE #349: Documentation for security feature in 4.5.0
Date Mon, 07 Aug 2017 18:47:09 GMT
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 <sijie@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 <sijie@apache.org>
    
    Reviewers: Luc Perkins <lucperkins@gmail.com>, Matteo Merli <mmerli@apache.org>
    
    This closes #350 from sijie/security_docs, closes #349
    
    (cherry picked from commit 49b90a66f830482fc970ba625057c7101c201f62)
    Signed-off-by: Sijie Guo <sijie@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" <commits@bookkeeper.apache.org>'].

Mime
View raw message