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

layout	page_title	sidebar_current	description
docs	Commands: Lock	docs-commands-lock	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 is disrupted, the child process is terminated.

The number of lock holders 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.

If the lock holder count is more than one, then a semaphore is used instead. A semaphore allows more than a single holder, but this is less efficient than a simple lock. This follows the semaphore algorithm.

All locks using the same prefix must agree on the value of -n. If conflicting values of -n are provided, an error will be returned.

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 is disrupted, or the parent process interrupted, the child process will receive a SIGTERM. After a grace period of 5 seconds, a SIGKILL will be used to force termination. For Consul agents on Windows, the child process is always terminated with a SIGKILL, since Windows has no POSIX compatible notion for SIGTERM.

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. All locks on the same prefix must use the same value.

• -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.

• -pass-stdin - Pass stdin to child process.

• -try - Attempt to acquire the lock up to the given timeout. The timeout is a positive decimal number, with unit suffix, such as "500ms". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

• -monitor-retry - Retry up to this number of times if Consul returns a 500 error while monitoring the lock. This allows riding out brief periods of unavailability without causing leader elections, but increases the amount of time required to detect a lost lock in some cases. Defaults to 3, with a 1s wait between retries. Set to 0 to disable.

• -verbose - Enables verbose output.

SHELL

Consul lock launches its children in a shell. By default, Consul will use the shell defined in the environment variable SHELL. If SHELL is not defined, it will default to /bin/sh. It should be noted that not all shells terminate child processes when they receive SIGTERM. Under Ubuntu, /bin/sh is linked to dash, which does not terminate its children. In order to ensure that child processes are killed when the lock is lost, be sure to set the SHELL environment variable appropriately.