[GitHub] nkalmar commented on a change in pull request #826: ZOOKEEPER-2750. Document SSL Support for Atomic Broadcast protocol

[GitBox <gi...@apache.org>]

nkalmar commented on a change in pull request #826: ZOOKEEPER-2750. Document SSL Support for Atomic Broadcast protocol
URL: https://github.com/apache/zookeeper/pull/826#discussion_r258564383
 
 

 ##########
 File path: zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md
 ##########
 @@ -1254,39 +1312,124 @@ to **org.apache.zookeeper.ClientCnxnSocketNetty**.
 
 TBD - tuning options for netty - currently there are none that are netty specific but we should add some. Esp around max bound on the number of reader worker threads netty creates.
 
-TBD - how to manage encryption
+<a name="Quorum+TLS"></a>
 
-TBD - how to manage certificates
+#### Quorum TLS
 
-<a name="sc_adminserver_config"></a>
+*New in 3.5.5*
 
-#### AdminServer configuration
+Based on the Netty Framework ZooKeeper ensembles can be set up
+to use TLS encryption in their communication channels. This section
+describes how to set up encryption on the quorum communication.
 
-**New in 3.5.0:** The following
-options are used to configure the [AdminServer](#sc_adminserver).
+Please note that Quorum TLS encapsulates securing both leader election
+and quorum communication protocols.
 
-* *admin.enableServer* :
-    (Java system property: **zookeeper.admin.enableServer**)
-    Set to "false" to disable the AdminServer.  By default the
-    AdminServer is enabled.
+1. Create SSL keystore JKS to store local credentials
 
-* *admin.serverAddress* :
-    (Java system property: **zookeeper.admin.serverAddress**)
-    The address the embedded Jetty server listens on. Defaults to 0.0.0.0.
+One keystore should be created for each ZK instance.
 
-* *admin.serverPort* :
-    (Java system property: **zookeeper.admin.serverPort**)
-    The port the embedded Jetty server listens on.  Defaults to 8080.
+In this example we generate a self-signed certificate and store it 
+together with the private key in `keystore.jks`. This is suitable for 
+testing purposes, but you probably need an official certificate to sign 
+your keys in a production environment.
 
-* *admin.idleTimeout* :
-    (Java system property: **zookeeper.admin.idleTimeout**)
-    Set the maximum idle time in milliseconds that a connection can wait
-    before sending or receiving data. Defaults to 30000 ms.
+Please note that the alias (`-alias`) and the (`-dname`) (distinguished name)
+must match the hostname of the machine that is associated with, otherwise 
+hostname verification won't work.
+
+```
+keytool -genkeypair -alias $(hostname -f) -keyalg RSA -keysize 2048 -dname "cn=$(hostname -f)" -keypass password -keystore keystore.jks -storepass password
+```
+
+2. Extract the signed public key (certificate) from keystore 
+
+*This step might only necessary for self-signed certificates.*
+
+```
+keytool -exportcert -alias $(hostname -f) -keystore keystore.jks -file $(hostname -f).cer -rfc
+```
+
+3. Create SSL truststore JKS containing certificates of all ZooKeeper instances
+
+The same truststore (storing all accepted certs) should be shared on
+participants of the ensemble.
+
+```
+keytool -importcert -file hostname.local.cer -keystore truststore.jks -storepass password`
+```
+
+4. Need to use `NettyServerCnxnFactory` and serverCnxnFactory, because SSL is not supported by NIO.
+
+5. You need the following configuration settings in your `zoo.cfg` config file:
+
+```
+sslQuorum=true
+serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
+ssl.quorum.keyStore.location=/path/to/keystore.jks
+ssl.quorum.keyStore.password=password
+ssl.quorum.trustStore.location=/path/to/truststore.jks
+ssl.quorum.trustStore.password=password
+```
+
+6. Verify in the logs that your ensemble is running on TLS:
+
+```
+INFO  [main:QuorumPeer@1789] - Using TLS encrypted quorum communication
+INFO  [main:QuorumPeer@1797] - Port unification disabled
+...
+INFO  [QuorumPeerListener:QuorumCnxManager$Listener@877] - Creating TLS-only quorum server socket
+```
+
+<a name="Upgrading+existing+nonTLS+cluster"></a>
+
+#### Upgrading existing non-TLS cluster with no downtime
+
+Here're the steps needed to upgrade an already running ZooKeeper ensemble
 
 Review comment:
   super-nit: Is there an abbreviation like "Here're". Just use Here are?
   (But then again I'm not a native speaker either :) )

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services