2014-09-01 22:03:37 +00:00
---
2020-09-01 15:14:13 +00:00
layout: commands
2020-04-07 18:55:19 +00:00
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.
2014-09-01 22:03:37 +00:00
---
# Consul Exec
Command: `consul exec`
2014-10-19 23:40:10 +00:00
The `exec` command provides a mechanism for remote execution. For example,
2014-09-01 22:03:37 +00:00
this can be used to run the `uptime` command across all machines providing
the `web` service.
2015-01-02 18:30:11 +00:00
Remote execution works by specifying a job, which is stored in the KV store.
2020-10-14 15:23:05 +00:00
Agents are informed about the new job using the [event system](/commands/event),
2020-04-09 23:46:54 +00:00
which propagates messages via the [gossip protocol](/docs/internals/gossip).
2014-09-01 22:03:37 +00:00
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.
2016-02-06 01:36:19 +00:00
**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
2016-02-10 00:37:06 +00:00
through the Consul servers and the Raft consensus algorithm, so having a large
2016-02-06 01:36:19 +00:00
number of nodes in the cluster flow a large amount of data through the KV store
could make the cluster unavailable.
2020-04-09 23:20:00 +00:00
The table below shows the [required ACLs](/api#authentication) in order to
2017-07-20 16:30:08 +00:00
execute this command.
| ACL Required | Scope |
2020-04-07 18:55:19 +00:00
| --------------- | ----------------- |
2017-07-20 16:30:08 +00:00
| `agent:read` | local agent |
| `session:write` | local agent |
| `key:write` | `"_rexec"` prefix |
| `event:write` | `"_rexec"` prefix |
2021-03-25 21:49:47 +00:00
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.
2014-09-01 22:03:37 +00:00
## Usage
Usage: `consul exec [options] [-|command...]`
The only required option is a command to execute. This is either given
2016-11-25 16:00:02 +00:00
as trailing arguments, or by specifying `-`; STDIN will be read to
2014-09-01 22:03:37 +00:00
completion as a script to evaluate.
2017-02-08 21:57:46 +00:00
#### API Options
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
2020-04-07 23:56:08 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_server.mdx'
2014-09-01 22:03:37 +00:00
2017-02-08 21:57:46 +00:00
#### Command Options
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-prefix` - Key prefix in the KV store to use for storing request data.
2016-11-25 16:00:02 +00:00
Defaults to `_rexec`.
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-node` - Regular expression to filter nodes which should evaluate the event.
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-service` - Regular expression to filter to only nodes with matching services.
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-shell` - Optional, use a shell to run the command. The default value is true.
2017-10-04 23:48:00 +00:00
2020-04-07 18:55:19 +00:00
- `-tag` - Regular expression to filter to only nodes with a service that has
2014-09-01 22:03:37 +00:00
a matching tag. This must be used with `-service`. As an example, you may
2016-11-25 16:00:02 +00:00
do `-service mysql -tag secondary`.
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-wait` - Specifies the period of time in which no agent's respond before considering
2014-09-01 22:03:37 +00:00
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.
2020-04-07 18:55:19 +00:00
- `-wait-repl` - Period to wait after writing the job specification for replication.
2014-09-01 22:03:37 +00:00
This is a heuristic value and enables agents to do a stale read of the job. Defaults
2016-11-25 16:00:02 +00:00
to 200 msec.
2014-09-01 22:03:37 +00:00
2020-04-07 18:55:19 +00:00
- `-verbose` - Enables verbose output.