website: Document the lock command

website/source/docs/commands/index.html.markdown

@@ -33,7 +33,9 @@ Available commands are:
     info           Provides debugging information for operators
     join           Tell Consul agent to join cluster
     keygen         Generates a new encryption key
+    keyring        Manages gossip layer encryption keys
     leave          Gracefully leaves the Consul cluster and shuts down
+    lock           Execute a command holding a lock
     members        Lists the members of a Consul cluster
     monitor        Stream logs from a Consul agent
     reload         Triggers the agent to reload configuration files

website/source/docs/commands/lock.html.markdown

@@ -0,0 +1,61 @@
+---
+layout: "docs"
+page_title: "Commands: Lock"
+sidebar_current: "docs-commands-lock"
+description: |-
+  The lock command provides a mechanism for leader election, mutual exclusion,
+  or worker pools. For example, this can be used to ensure a maximum number of
+  services running at once across a cluster.
+---
+
+# Consul Lock
+
+Command: `consul lock`
+
+The `lock` command provides a mechanism for simple distributed locking.
+A lock (or semaphore) is created at a given prefix in the Key/Value store,
+and only when held, is a child process invoked. If the lock is lost or
+communication disrupted, the child process is terminated.A
+
+The number of lock holder is configurable with the `-n` flag. By default,
+a single holder is allowed, and a lock is used for mutual exclusion. This
+uses the [leader election algorithm](/docs/guides/leader-election.html).
+
+If the lock holder count is more than one, then a semaphore is used instead.
+A semaphore allows more than a single holder, but the is less efficient than
+a simple lock. This follows the [semaphore algorithm](/docs/guides/semaphore.html).
+
+An example use case is for highly-available N+1 deployments. In these
+cases, if N instances of a service are required, N+1 are deployed and use
+consul lock with `-n=N` to ensure only N instances are running. For singleton
+services, a hot standby waits until the current leader fails to take over.
+
+## Usage
+
+Usage: `consul lock [options] prefix child...`
+
+The only required options are the key prefix and the command to execute.
+The prefix must be writable. The child is invoked only when the lock is held,
+and the `CONSUL_LOCK_HELD` environment variable will be set to `true`.
+
+If the lock is lost, communication disrupted, or the parent process interrupted,
+the child process will receive a `SIGTERM`. After a grace period, a `SIGKILL`
+will be used to force termination.
+
+The list of available flags are:
+
+* `-http-addr` - Address to the HTTP server of the agent you want to contact
+  to send this command. If this isn't specified, the command will contact
+  "127.0.0.1:8500" which is the default HTTP address of a Consul agent.
+
+* `-n` - Optional, limit of lock holders. Defaults to 1. The underlying
+  implementation switches from a lock to a semaphore when increased past
+  one.
+
+* `-name` - Optional name to associate with the underlying session.
+  If not provided, one is generated based on the child command.
+
+* `-token` - ACL token to use. Defaults to that of agent.
+
+* `-verbose` - Enables verbose output.
+

website/source/layouts/docs.erb

@@ -87,6 +87,10 @@
 					<a href="/docs/commands/leave.html">leave</a>
                     </li>
 
+					<li<%= sidebar_current("docs-commands-lock") %>>
+					<a href="/docs/commands/lock.html">lock</a>
+					</li>
+
 					<li<%= sidebar_current("docs-commands-members") %>>
 					<a href="/docs/commands/members.html">members</a>
 					</li>