This is an automated email from the ASF dual-hosted git repository.
zhaijia pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git
The following commit(s) were added to refs/heads/master by this push:
new 313cfa6 BOOKKEEPER-1017: Create documentation for ZooKeeper ACLs
313cfa6 is described below
commit 313cfa66018836e8d6372b06c29ec551fca91e34
Author: Enrico Olivelli <eolive...@apache.org>
AuthorDate: Wed Jul 26 17:06:52 2017 +0800
BOOKKEEPER-1017: Create documentation for ZooKeeper ACLs
This is the documentation for ZooKeeper security and there is an intro
about security in general.
It is work-in-progress, I created this PR in order to make it visible and
gather suggestions while writing
Author: Enrico Olivelli <eolive...@apache.org>
Reviewers: Jia Zhai <None>, Sijie Guo <None>
This closes #185 from eolivelli/BOOKKEEPER-1017-zookeeper-docs
---
bookkeeper-server/conf/bk_server.conf | 6 ++++
bookkeeper-server/conf/jaas_example.conf | 44 +++++++++++++++++++++++++++++
doc/bookkeeperSecurity.textile | 48 ++++++++++++++++++++++++++++++++
3 files changed, 98 insertions(+)
diff --git a/bookkeeper-server/conf/bk_server.conf
b/bookkeeper-server/conf/bk_server.conf
index 6068ff3..e10aa3e 100644
--- a/bookkeeper-server/conf/bk_server.conf
+++ b/bookkeeper-server/conf/bk_server.conf
@@ -201,6 +201,12 @@ zkServers=localhost:2181
# JVM garbage collection, disk I/O will cause SESSION_EXPIRED.
# Increment this value could help avoiding this issue
zkTimeout=10000
+# Set ACLs on every node written on ZooKeeper, this way only allowed users
+# will be able to read and write BookKeeper metadata stored on ZooKeeper.
+# In order to make ACLs work you need to setup ZooKeeper JAAS authentication
+# all the Bookies and Client need to share the same user, and this is usually
+# done using Kerberos authentication. See ZooKeeper documentation
+zkEnableSecurity=false
## NIO Server settings
diff --git a/bookkeeper-server/conf/jaas_example.conf
b/bookkeeper-server/conf/jaas_example.conf
new file mode 100644
index 0000000..101b2d9
--- /dev/null
+++ b/bookkeeper-server/conf/jaas_example.conf
@@ -0,0 +1,44 @@
+/*
+* Copyright 2016 The Apache Software Foundation
+*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements. See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership. The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/*
+ Kerberos Example
+
+ Client {
+ com.sun.security.auth.module.Krb5LoginModule required debug=true
+ useKeyTab=true
+ keyTab="/path/to/keytabfile"
+ storeKey=true
+ useTicketCache=false
+ principal="bookkeeper/HOSTNAME@REALM";
+};
+*/
+
+/*
+ DIGEST-MD5 Example
+
+ Client {
+ org.apache.zookeeper.server.auth.DigestLoginModule required
+ user_hd="testpwd";
+};
+*/
+
+
+
diff --git a/doc/bookkeeperSecurity.textile b/doc/bookkeeperSecurity.textile
new file mode 100644
index 0000000..6969e6c
--- /dev/null
+++ b/doc/bookkeeperSecurity.textile
@@ -0,0 +1,48 @@
+Title: BookKeeper Security
+Notice: Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License. You
may
+ obtain a copy of the License at
"http://www.apache.org/licenses/LICENSE-2.0":http://www.apache.org/licenses/LICENSE-2.0.
+ .
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an "AS IS"
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing
permissions
+ and limitations under the License.
+ .
+ .
+
+h1. Security in BookKeeper
+
+Apache BookKeeper is a decentralized platform and there are multiple aspects
to deal with while securing an BookKeeper Cluster.
+
+Metadata are stored on ZooKeeper, so first of all you will need to secure your
ZooKeeper cluster, see "ZooKeeper
security":https://zookeeper.apache.org/security.html
+
+Then you have to take care of access to Bookies, you can configure
authentication and encryption using TLS, out of the box BookKeeper supports
Kerberos authentication, DIGEST-MD5 authentication and TLS encryption. You can
also leverage TLS client authentication in order to protect your data.
+
+h1. ZookKeeper security on BookKeeper
+
+Both clients and Bookies read and write metadata on ZooKeeper, it is also used
for Bookie discovery.
+The best way to protect data stored on ZooKeeper is to put ACLs on every
z-node, this way only authorized users will be able to access (read/write) data
+
+In order to configure BookKeeper and protect ZooKeeper just simply set
zkEnableSecurity=true configuration property on Bookie Configuration
(conf/bk_server.conf).
+On the client side you have to set zkEnableSecurity property to true or use
ClientConfiguration.setZkEnableSecurity(true).
+
+Beware that your Bookies and your clients MUST successfully authenticate to
ZooKeeper cluster.
+You MUST use the same ZooKeeper principal for every Bookie and every Client,
this is usually achived by using Kerberos.
+
+BookKeeper runtime will use ZooDefs.Ids.CREATOR_ALL_ACL ACLs for every new
node. You will get InvalidACL it ZooKeeper authentication is not configured.
+
+In order to make a Bookie authenticate to a secured ZooKeeper cluster you have
to:
+
+- create a jaas.conf file in your "conf" directory (you can just rename
conf/jaas_example.conf and change it according to your needs)
+
+- add -Djava.security.auth.login.config=absolute/path/to/jaas.conf to
BOOKIE_EXTRA_OPTS in conf/bkenv.sh
+
+On the client side you have to follow similar steps but it depends on your
application
+
+Currently there is no migration procedure for changing zkEnableSecurity
+
+if you are moving to zkEnableSecurity=true, new z-nodes will be 'secured' but
old z-nodes will be not covered by ACLs and you will need to set it manually
using ZooKeeper tools
+
+if you are moving to zkEnableSecurity=false you need to reset all ACLs under
the z-node set in zkLedgersRootPath, which defaults to '/ledgers'
--
To stop receiving notification emails like this one, please contact
['"commits@bookkeeper.apache.org" <commits@bookkeeper.apache.org>'].
