84 lines
3.3 KiB
Plaintext
84 lines
3.3 KiB
Plaintext
---
|
|
layout: commands
|
|
page_title: 'Commands: Exec'
|
|
description: >-
|
|
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.
|
|
---
|
|
|
|
# Consul Exec
|
|
|
|
Command: `consul exec`
|
|
|
|
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.
|
|
|
|
Remote execution works by specifying a job, which is stored in the KV store.
|
|
Agents are informed about the new job using the [event system](/commands/event),
|
|
which propagates messages via the [gossip protocol](/docs/internals/gossip).
|
|
As a result, delivery is best-effort, and there is **no guarantee** of execution.
|
|
|
|
While events are purely gossip driven, remote execution relies on the KV store
|
|
as a message broker. As a result, the `exec` command will not be able to
|
|
properly function during a Consul outage.
|
|
|
|
**Verbose output warning:** use care to make sure that your command does not
|
|
produce a large volume of output. Writes to the KV store for this output go
|
|
through the Consul servers and the Raft consensus algorithm, so having a large
|
|
number of nodes in the cluster flow a large amount of data through the KV store
|
|
could make the cluster unavailable.
|
|
|
|
The table below shows the [required ACLs](/api#authentication) in order to
|
|
execute this command.
|
|
|
|
| ACL Required | Scope |
|
|
| --------------- | ----------------- |
|
|
| `agent:read` | local agent |
|
|
| `session:write` | local agent |
|
|
| `key:write` | `"_rexec"` prefix |
|
|
| `event:write` | `"_rexec"` prefix |
|
|
|
|
In addition to the above, the policy associated with the [agent token](https://www.consul.io/docs/security/acl/acl-system#acl-agent-token) should have `write` on `"_rexec"` key prefix. This is for the agents to read the `exec` command and write its output back to the KV store.
|
|
|
|
## Usage
|
|
|
|
Usage: `consul exec [options] [-|command...]`
|
|
|
|
The only required option is a command to execute. This is either given
|
|
as trailing arguments, or by specifying `-`; STDIN will be read to
|
|
completion as a script to evaluate.
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
#### Command Options
|
|
|
|
- `-prefix` - Key prefix in the KV store to use for storing request data.
|
|
Defaults to `_rexec`.
|
|
|
|
- `-node` - Regular expression to filter nodes which should evaluate the event.
|
|
|
|
- `-service` - Regular expression to filter to only nodes with matching services.
|
|
|
|
- `-shell` - Optional, use a shell to run the command. The default value is true.
|
|
|
|
- `-tag` - Regular expression to filter to only nodes with a service that has
|
|
a matching tag. This must be used with `-service`. As an example, you may
|
|
do `-service mysql -tag secondary`.
|
|
|
|
- `-wait` - Specifies the period of time in which no agent's respond before considering
|
|
the job finished. This is basically the quiescent time required to assume completion.
|
|
This period is not a hard deadline, and the command will wait longer depending on
|
|
various heuristics.
|
|
|
|
- `-wait-repl` - Period to wait after writing the job specification for replication.
|
|
This is a heuristic value and enables agents to do a stale read of the job. Defaults
|
|
to 200 msec.
|
|
|
|
- `-verbose` - Enables verbose output.
|