2015-01-20 02:43:38 +00:00
---
layout: "docs"
page_title: "Commands: Lock"
sidebar_current: "docs-commands-lock"
description: |-
2015-01-22 01:35:06 +00:00
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.
2015-01-20 02:43:38 +00:00
---
# 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
2015-01-25 10:42:26 +00:00
communication is disrupted, the child process is terminated.
2015-01-20 02:43:38 +00:00
2015-01-25 10:42:26 +00:00
The number of lock holders is configurable with the `-n` flag. By default,
2015-01-20 02:43:38 +00:00
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.
2015-06-01 13:34:54 +00:00
A semaphore allows more than a single holder, but this is less efficient than
2015-01-20 02:43:38 +00:00
a simple lock. This follows the [semaphore algorithm ](/docs/guides/semaphore.html ).
2015-01-23 21:11:15 +00:00
All locks using the same prefix must agree on the value of `-n` . If conflicting
2015-01-22 01:35:06 +00:00
values of `-n` are provided, an error will be returned.
2015-01-20 02:43:38 +00:00
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` .
2015-01-25 10:42:26 +00:00
If the lock is lost, communication is disrupted, or the parent process
2015-05-28 19:24:32 +00:00
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` .
2015-01-20 02:43:38 +00:00
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
2015-01-22 01:35:06 +00:00
one. All locks on the same prefix must use the same value.
2015-01-20 02:43:38 +00:00
* `-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.
2015-09-01 02:00:26 +00:00
* `-pass-stdin` - Pass stdin to child process.
2015-01-20 02:43:38 +00:00
* `-verbose` - Enables verbose output.