github.com/outbrain/consul@v1.4.5/website/source/docs/commands/lock.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Lock"
     4  sidebar_current: "docs-commands-lock"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Consul Lock
    10  
    11  Command: `consul lock`
    12  
    13  The `lock` command provides a mechanism for simple distributed locking.
    14  A lock (or semaphore) is created at a given prefix in the KV store,
    15  and only when held, is a child process invoked. If the lock is lost or
    16  communication is disrupted, the child process is terminated.
    17  
    18  The number of lock holders is configurable with the `-n` flag. By default,
    19  a single holder is allowed, and a lock is used for mutual exclusion. This
    20  uses the [leader election algorithm](/docs/guides/leader-election.html).
    21  
    22  If the lock holder count is more than one, then a semaphore is used instead.
    23  A semaphore allows more than a single holder, but this is less efficient than
    24  a simple lock. This follows the [semaphore algorithm](/docs/guides/semaphore.html).
    25  
    26  All locks using the same prefix must agree on the value of `-n`. If conflicting
    27  values of `-n` are provided, an error will be returned.
    28  
    29  An example use case is for highly-available N+1 deployments. In these
    30  cases, if N instances of a service are required, N+1 are deployed and use
    31  consul lock with `-n=N` to ensure only N instances are running. For singleton
    32  services, a hot standby waits until the current leader fails to take over.
    33  
    34  ## Usage
    35  
    36  Usage: `consul lock [options] prefix child...`
    37  
    38  The only required options are the key prefix and the command to execute.
    39  The prefix must be writable. The child is invoked only when the lock is held,
    40  and the `CONSUL_LOCK_HELD` environment variable will be set to `true`.
    41  
    42  If the lock is lost, communication is disrupted, or the parent process
    43  interrupted, the child process will receive a `SIGTERM`. After a grace period
    44  of 5 seconds, a `SIGKILL` will be used to force termination. For Consul agents
    45  on Windows, the child process is always terminated with a `SIGKILL`, since
    46  Windows has no POSIX compatible notion for `SIGTERM`.
    47  
    48  #### API Options
    49  
    50  <%= partial "docs/commands/http_api_options_client" %>
    51  <%= partial "docs/commands/http_api_options_server" %>
    52  
    53  #### Command Options
    54  
    55  * `-child-exit-code` - Exit 2 if the child process exited with an error
    56    if this is true, otherwise this doesn't propagate an error from the
    57    child. The default value is false.
    58  
    59  * `-monitor-retry` - Retry up to this number of times if Consul returns a 500 error
    60     while monitoring the lock. This allows riding out brief periods of unavailability
    61     without causing leader elections, but increases the amount of time required
    62     to detect a lost lock in some cases. Defaults to 3, with a 1s wait between retries.
    63     Set to 0 to disable.
    64  
    65  * `-n` - Optional, limit of lock holders. Defaults to 1. The underlying
    66    implementation switches from a lock to a semaphore when increased past
    67    one. All locks on the same prefix must use the same value.
    68  
    69  * `-name` - Optional name to associate with the underlying session.
    70    If not provided, one is generated based on the child command.
    71  
    72  * `-shell` - Optional, use a shell to run the command (can set a custom shell via the
    73    SHELL environment variable). The default value is true.
    74  
    75  * `-pass-stdin` - Pass stdin to child process.
    76  
    77  * `-timeout` - Maximum amount of time to wait to acquire the lock, specified
    78     as a duration like `1s` or `3h`. The default value is 0.
    79  
    80  * `-try` - Attempt to acquire the lock up to the given timeout. The timeout is a
    81    positive decimal number, with unit suffix, such as "500ms". Valid time units
    82    are "ns", "us" (or "µs"), "ms", "s", "m", "h".
    83  
    84  * `-verbose` - Enables verbose output.
    85  
    86  ## SHELL
    87  Consul lock launches its children in a shell. By default, Consul will use the shell
    88  defined in the environment variable `SHELL`. If `SHELL` is not defined, it will
    89  default to `/bin/sh`. It should be noted that not all shells terminate child
    90  processes when they receive `SIGTERM`. Under Ubuntu, `/bin/sh` is linked to `dash`,
    91  which does **not** terminate its children. In order to ensure that child processes
    92  are killed when the lock is lost, be sure to set the `SHELL` environment variable
    93  appropriately, or run without a shell by setting `-shell=false`.