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

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: Exec"
     4  sidebar_current: "docs-commands-exec"
     5  description: |-
     6    The exec command provides a mechanism for remote execution. For example, this can be used to run the `uptime` command across all machines providing the `web` service.
     7  ---
     8  
     9  # Consul Exec
    10  
    11  Command: `consul exec`
    12  
    13  The `exec` command provides a mechanism for remote execution. For example,
    14  this can be used to run the `uptime` command across all machines providing
    15  the `web` service.
    16  
    17  Remote execution works by specifying a job, which is stored in the KV store.
    18  Agents are informed about the new job using the [event system](/docs/commands/event.html),
    19  which propagates messages via the [gossip protocol](/docs/internals/gossip.html).
    20  As a result, delivery is best-effort, and there is **no guarantee** of execution.
    21  
    22  While events are purely gossip driven, remote execution relies on the KV store
    23  as a message broker. As a result, the `exec` command will not be able to
    24  properly function during a Consul outage.
    25  
    26  **Verbose output warning:** use care to make sure that your command does not
    27  produce a large volume of output. Writes to the KV store for this output go
    28  through the Consul servers and the Raft consensus algorithm, so having a large
    29  number of nodes in the cluster flow a large amount of data through the KV store
    30  could make the cluster unavailable.
    31  
    32  The table below shows the [required ACLs](/api/index.html#acls) in order to
    33  execute this command.
    34  
    35  | ACL Required    | Scope             |
    36  | ------------    | ------------      |
    37  | `agent:read`    | local agent       |
    38  | `session:write` | local agent       |
    39  | `key:write`     | `"_rexec"` prefix |
    40  | `event:write`   | `"_rexec"` prefix |
    41  
    42  ## Usage
    43  
    44  Usage: `consul exec [options] [-|command...]`
    45  
    46  The only required option is a command to execute. This is either given
    47  as trailing arguments, or by specifying `-`; STDIN will be read to
    48  completion as a script to evaluate.
    49  
    50  #### API Options
    51  
    52  <%= partial "docs/commands/http_api_options_client" %>
    53  <%= partial "docs/commands/http_api_options_server" %>
    54  
    55  #### Command Options
    56  
    57  * `-prefix` - Key prefix in the KV store to use for storing request data.
    58    Defaults to `_rexec`.
    59  
    60  * `-node` - Regular expression to filter nodes which should evaluate the event.
    61  
    62  * `-service` - Regular expression to filter to only nodes with matching services.
    63  
    64  * `-shell` - Optional, use a shell to run the command. The default value is true.
    65  
    66  * `-tag` - Regular expression to filter to only nodes with a service that has
    67    a matching tag. This must be used with `-service`. As an example, you may
    68    do `-service mysql -tag secondary`.
    69  
    70  * `-wait` - Specifies the period of time in which no agent's respond before considering
    71    the job finished. This is basically the quiescent time required to assume completion.
    72    This period is not a hard deadline, and the command will wait longer depending on
    73    various heuristics.
    74  
    75  * `-wait-repl` - Period to wait after writing the job specification for replication.
    76    This is a heuristic value and enables agents to do a stale read of the job. Defaults
    77    to 200 msec.
    78  
    79  * `-verbose` - Enables verbose output.