HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Consul
Consul Home

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

To apply a lock to a remote WAN federated datacenter, run the command with the -datacenter=<name> flag on a server agent. You cannot use the command with -datacenter on client agents because they are unavailable to the remote datacenter.

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.

Command Options

  • -child-exit-code - Exit 2 if the child process exited with an error if this is true, otherwise this doesn't propagate an error from the child. The default value is false.

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

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

  • -shell - Optional, use a shell to run the command (can set a custom shell via the SHELL environment variable). The default value is true.

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

  • -timeout - 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". The default value is 0.

  • -verbose - Enables verbose output.

API Options

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

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, or run without a shell by setting -shell=false.

Edit this page on GitHub