From 2d7be2043148dfd6f629f86d107703f74778bb28 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Mon, 1 Sep 2014 15:03:37 -0700 Subject: [PATCH] website: Updating docs --- website/source/docs/agent/http.html.markdown | 3 +- .../source/docs/agent/options.html.markdown | 3 + .../source/docs/commands/exec.html.markdown | 62 +++++++++++++++++++ .../source/docs/commands/index.html.markdown | 2 + .../getting-started/install.html.markdown | 3 + website/source/layouts/docs.erb | 4 ++ 6 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 website/source/docs/commands/exec.html.markdown diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index e24bfeb5f8..929069fbea 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -1209,7 +1209,8 @@ can be specified using the "?dc=" query parameter. The fire endpoint expects a PUT request, with an optional body. The body contents are opaque to Consul, and become the "payload" -of the event. +of the event. Any names starting with the "_" prefix should be considered +reserved, and for Consul's internal use. The `?node=`, `?service=`, and `?tag=` query parameters may optionally be provided. They respectively provide a regular expression to filter diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index 8d91bf0268..088d72712d 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/website/source/docs/agent/options.html.markdown @@ -227,6 +227,9 @@ definitions support being updated during a reload. * `data_dir` - Equivalent to the `-data-dir` command-line flag. +* `disable_remote_exec` - Disables support for remote execution. When set to true, + the agent will ignore any incoming remote exec requests. + * `dns_config` - This object allows a number of sub-keys to be set which can tune how DNS queries are perfomed. See this guide on [DNS caching](/docs/guides/dns-cache.html). The following sub-keys are available: diff --git a/website/source/docs/commands/exec.html.markdown b/website/source/docs/commands/exec.html.markdown new file mode 100644 index 0000000000..540f95eeae --- /dev/null +++ b/website/source/docs/commands/exec.html.markdown @@ -0,0 +1,62 @@ +--- +layout: "docs" +page_title: "Commands: Exec" +sidebar_current: "docs-commands-exec" +--- + +# Consul Exec + +Command: `consul exec` + +The exec command provides a mechahanism 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. +Agent's are informed about the new job using the [event system](/docs/commands/event.html), +which propogates messages via the [gossip protocol](/docs/internals/gossip.html). +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. + +## 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. + +The list of available flags are: + +* `-http-addr` - Address to the HTTP server of the agent you want to contact + to send this command. If this isn't specified, the command will contact + "127.0.0.1:8500" which is the default HTTP address of a Consul agent. + +* `-datacenter` - Datacenter to query. Defaults to that of agent. In version + 0.4, that is the only supported value. + +* `-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. + +* `-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 "-server mysql -tag slave". + +* `-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 200msec. + +* `-verbose` - Enables verbose output. + diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index 3c43cac470..5adf67685e 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/website/source/docs/commands/index.html.markdown @@ -25,6 +25,8 @@ usage: consul [--version] [--help] [] Available commands are: agent Runs a Consul agent + event Fire a new event + exec Executes a command on Consul nodes force-leave Forces a member of the cluster to enter the "left" state info Provides debugging information for operators join Tell Consul agent to join cluster diff --git a/website/source/intro/getting-started/install.html.markdown b/website/source/intro/getting-started/install.html.markdown index 9ef7acaaa3..e224f09eb1 100644 --- a/website/source/intro/getting-started/install.html.markdown +++ b/website/source/intro/getting-started/install.html.markdown @@ -49,6 +49,8 @@ usage: consul [--version] [--help] [] Available commands are: agent Runs a Consul agent + event Fire a new event + exec Executes a command on Consul nodes force-leave Forces a member of the cluster to enter the "left" state info Provides debugging information for operators join Tell Consul agent to join cluster @@ -56,6 +58,7 @@ Available commands are: leave Gracefully leaves the Consul cluster and shuts down members Lists the members of a Consul cluster monitor Stream logs from a Consul agent + reload Triggers the agent to reload configuration files version Prints the Consul version watch Watch for changes in Consul ``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 04855527a0..b123619e8b 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -61,6 +61,10 @@ > event + + + > + exec >