1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
ZooKeeper Administration
========================
This section will cover some basic tasks and recommendations when
setting up ZooKeeper for use with Zuul. A complete tutorial for
ZooKeeper is out of scope for this documentation.
Configuration
-------------
The following general configuration setting in
``/etc/zookeeper/zoo.cfg`` is recommended:
.. code-block::
autopurge.purgeInterval=6
This instructs ZooKeeper to purge old snapshots every 6 hours. This
will avoid filling the disk.
Encrypted Connections
---------------------
ZooKeeper version 3.5.1 or greater is required for TLS support.
ZooKeeper performs hostname validation for all ZooKeeper servers
("quorum members"), therefore each member of the ZooKeeper cluster
should have its own certificate. This does not apply to clients which
may share a certificate.
ZooKeeper performs certificate validation on all connections (server
and client). If you use a private Certificate Authority (CA) (which
is generally recommended and discussed below), then these TLS
certificates not only serve to encrypt traffic, but also to
authenticate and authorize clients to the cluster. Only clients with
certificates authorized by a CA explicitly trusted by your ZooKeeper
installation will be able to connect.
.. note:: The instructions below direct you to sign certificates with
a CA that you create specifically for Zuul's ZooKeeper
cluster. If you use a CA you share with other users in your
organization, any certificate signed by that CA will be able
to connect to your ZooKeeper cluster. In this case, you may
need to take additional steps such as network isolation to
protect your ZooKeeper cluster. These are beyond the scope
of this document.
The ``tools/zk-ca.sh`` script in the Zuul source code repository can
be used to quickly and easily generate self-signed certificates for
all ZooKeeper cluster members and clients.
Make a directory for it to store the certificates and CA data, and run
it once for each client:
.. code-block::
mkdir /etc/zookeeper/ca
tools/zk-ca.sh /etc/zookeeper/ca zookeeper1.example.com
tools/zk-ca.sh /etc/zookeeper/ca zookeeper2.example.com
tools/zk-ca.sh /etc/zookeeper/ca zookeeper3.example.com
Add the following to ``/etc/zookeeper/zoo.cfg``:
.. code-block::
# Necessary for TLS support
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
# Client TLS configuration
secureClientPort=2281
ssl.keyStore.location=/etc/zookeeper/ca/keystores/zookeeper1.example.com.jks
ssl.keyStore.password=keystorepassword
ssl.trustStore.location=/etc/zookeeper/ca/certs/cacert.pem
# Server TLS configuration
sslQuorum=true
ssl.quorum.keyStore.location=/etc/zookeeper/ca/keystores/zookeeper1.example.com.jks
ssl.quorum.keyStore.password=keystorepassword
ssl.quorum.trustStore.location=/etc/zookeeper/ca/certs/cacert.pem
Change the name of the certificate filenames as appropriate for the
host (e.g., ``zookeeper1.example.com.jks``). Note that the keystore
password ``keystorepassword``, which is set by the ``zk-ca.sh``
script, does not need to be changed as long as file permissions
provide sufficient protection. The password is present because many
Java utilities misbehave when interacting with keystores with empty or
missing passwords.
In order to disable plaintext connections, ensure that the
``clientPort`` option does not appear in ``zoo.cfg``. Use the new
method of specifying Zookeeper quorum servers, which looks like this:
.. code-block::
server.1=zookeeper1.example.com:2888:3888
server.2=zookeeper2.example.com:2888:3888
server.3=zookeeper3.example.com:2888:3888
This format normally includes ``;2181`` at the end of each line,
signifying that the server should listen on port 2181 for plaintext
client connections (this is equivalent to the ``clientPort`` option).
Omit it to disable plaintext connections. The earlier addition of
``secureClientPort`` to the config file instructs ZooKeeper to listen
for encrypted connections on port 2281.
Be sure to specify port 2281 rather than the standard 2181 in the
:attr:`zookeeper.hosts` setting in ``zuul.conf``.
Finally, add the :attr:`zookeeper.tls_cert`,
:attr:`zookeeper.tls_key`, and :attr:`zookeeper.tls_ca` options. Your
``zuul.conf`` file should look like:
.. code-block::
[zookeeper]
hosts=zookeeper1.example.com:2281,zookeeper2.example.com:2281,zookeeper3.example.com:2281
tls_cert=/etc/zookeeper/ca/certs/client.pem
tls_key=/etc/zookeeper/ca/keys/clientkey.pem
tls_ca=/etc/zookeeper/ca/certs/cacert.pem
|
