01ef26dea0
/docs/security/acl/acl-system was renamed in e9a42df from PR #12460 to /docs/security/acl. A corresponding redirect was not added for this page, resulting in a 404 being returned when accessing the old URL path. This commit redirects the former URL path to the new location, and also updates all links on the site to point to the new location.
84 lines
3.2 KiB
Plaintext
84 lines
3.2 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/architecture/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](/docs/security/acl/acl-tokens#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.
|