Github user d2r commented on a diff in the pull request:
https://github.com/apache/storm/pull/838#discussion_r45128428
--- Diff: docs/documentation/Pacemaker.md ---
@@ -0,0 +1,89 @@
+# Pacemaker
+
+### Introduction
+Pacemaker is a storm daemon designed to process heartbeats from workers.
As Storm is scaled up, ZooKeeper begins to become a bottleneck due to high
volumes of writes from workers doing heartbeats. Lots of writes to disk and
traffic across the network is generated as ZooKeeper tries to maintain
consistency.
+
+Because heartbeats are of an ephemeral nature, they do not need to be
persisted to disk or synced across nodes; an in-memory store will do. This is
the role of Pacemaker. Pacemaker functions as a simple in-memory key/value
store with ZooKeeper-like, directory-style keys and byte array values.
+
+The corresponding Pacemaker client is a plugin for the `ClusterState`
interface, `org.apache.storm.pacemaker.pacemaker_state_factory`. Heartbeat
calls are funneled by the `ClusterState` produced by `pacemaker_state_factory`
into the Pacemaker daemon, while other set/get operations are forwarded to
ZooKeeper.
+
+------
+
+### Configuration
+
+ - `pacemaker.host` : The host that the Pacemaker daemon is running on
+ - `pacemaker.port` : The port that Pacemaker will listen on
+ - `pacemaker.max.threads` : Maximum number of threads Pacemaker daemon
will use to handle requests.
+ - `pacemaker.childopts` : Any JVM parameters that need to go to the
Pacemaker. (used by storm-deploy project)
+ - `pacemaker.auth.method` : The authentication method that is used (more
info below)
+
+#### Example
+
+To get Pacemaker up and running, set the following option in the cluster
config on all nodes:
+```
+storm.cluster.state.store:
"org.apache.storm.pacemaker.pacemaker_state_factory"
+```
+
+The Pacemaker host also needs to be set on all nodes:
+```
+pacemaker.host: somehost.mycompany.com
+```
+
+And then start all of your daemons
+
+(including Pacemaker):
+```
+$ storm pacemaker
+```
+
+The Storm cluster should now be pushing all worker heartbeats through
Pacemaker.
+
+### Security
+
+Currently digest (password-based) and Kerberos security are supported.
Security is currently only around reads, not writes. Writes may be performed by
anyone, whereas reads may only be performed by authorized and authenticated
users. This is an area for future development, as it leaves the cluster open to
DoS attacks, but it prevents any sensitive information from reaching
unauthorized eyes, which was the main goal.
+
+#### Digest
+To configure digest authentication, set `pacemaker.auth.method: DIGEST` in
the cluster config on the nodes hosting Nimbus and Pacemaker.
+The nodes must also have `java.security.auth.login.config` set to point to
a jaas config file containing the following structure:
+```
+PacemakerDigest {
+ username="some username"
+ password="some password"
+};
--- End diff --
Do we also need a semicolon `;` after `"some password"`?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
