mirror of https://github.com/status-im/consul.git
website: updating documentation on commands
This commit is contained in:
Armon Dadgar
parent
03e62172f1
commit
1fb7b330ad
|
|
@ -374,7 +374,7 @@ Usage: consul agent [options]
|
|||
|
||||
Options:
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 Address to bind the RPC listener.
|
||||
-rpc-addr=127.0.0.1:8400 Address to bind the RPC listener.
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ Usage: consul force-leave [options] name
|
|||
|
||||
Options:
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Consul agent.
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Usage: consul join [options] address ...
|
|||
|
||||
Options:
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Consul agent.
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
-wan Joins a server to another server in the WAN pool
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ Usage: consul leave
|
|||
|
||||
Options:
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Consul agent.
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ Options:
|
|||
-role=<regexp> If provided, output is filtered to only nodes matching
|
||||
the regular expression for role
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Consul agent.
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
|
||||
-status=<regexp> If provided, output is filtered to only nodes matching
|
||||
the regular expression for status
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Usage: consul monitor [options]
|
|||
Options:
|
||||
|
||||
-log-level=info Log level of the agent.
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Consul agent.
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
`
|
||||
return strings.TrimSpace(helpText)
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,13 +4,13 @@ page_title: "Commands: Agent"
|
|||
sidebar_current: "docs-commands-agent"
|
||||
---
|
||||
|
||||
# Serf Agent
|
||||
# Consul Agent
|
||||
|
||||
The `serf agent` command is the heart of Serf: it runs the agent that
|
||||
The `consul agent` command is the heart of Consul: it runs the agent that
|
||||
performs the important task of maintaining membership information,
|
||||
propagating events, detecting failures, etc.
|
||||
running checks, announcing services, handling queries, etc.
|
||||
|
||||
Due to the power and flexibility of this command, the Serf agent
|
||||
is documented in its own section. See the [Serf Agent](/docs/agent/basics.html)
|
||||
Due to the power and flexibility of this command, the Consul agent
|
||||
is documented in its own section. See the [Consul Agent](/docs/agent/basics.html)
|
||||
section for more information on how to use this command and the
|
||||
options it has.
|
||||
|
|
|
|||
|
|
@ -1,76 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Event"
|
||||
sidebar_current: "docs-commands-event"
|
||||
---
|
||||
|
||||
# Serf Event
|
||||
|
||||
Command: `serf event`
|
||||
|
||||
The `serf event` command dispatches a custom user event into a Serf cluster,
|
||||
leveraging Serf's gossip layer for scalable broadcasting of the event to
|
||||
clusters of any size.
|
||||
|
||||
Nodes in the cluster can listen for these custom events and react to them.
|
||||
Example use cases of custom events are to trigger deploys across web nodes
|
||||
by sending a "deploy" event, possibly with a commit payload. Another use
|
||||
case might be to send a "restart" event, asking the cluster members to
|
||||
restart.
|
||||
|
||||
Ultimately, `serf event` is used to send custom events of your choosing
|
||||
that you can respond to in _any way_ you want. The power in Serf's custom
|
||||
events is the scalability over other systems.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `serf event [options] name [payload]`
|
||||
|
||||
The following command-line options are available for this command.
|
||||
Every option is optional:
|
||||
|
||||
* `-coalesce=true/false` - Sets whether or not this event can be coalesced
|
||||
by Serf. By default this is set to true. Read the section on event
|
||||
coalescing for more information on what this means.
|
||||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
|
||||
## Sending an Event
|
||||
|
||||
To send an event, use `serf event NAME` where NAME is the name of the
|
||||
event to send. This call will return immediately, and Serf will use its
|
||||
gossip layer to broadcast the event.
|
||||
|
||||
An event may also contain a payload. You may specify the payload using
|
||||
the second parameter. For example: `serf event deploy 1234567890` would
|
||||
send the "deploy" event with "1234567890" as the payload.
|
||||
|
||||
## Receiving an Event
|
||||
|
||||
The events can be handled by registering an
|
||||
[event handler](/docs/agent/event-handlers.html) with the Serf agent. The
|
||||
documentation for how the user event is dispatched is all contained within
|
||||
that linked page.
|
||||
|
||||
## Event Coalescing
|
||||
|
||||
By default, Serf coalesces events of the same name within a short time
|
||||
period. This means that if many events of the same name are received within
|
||||
a short amount of time, the event handler is only invoked once, with the
|
||||
last event of that name received during that time period.
|
||||
|
||||
Event coalescense works great for idempotent events such as "restart" or
|
||||
events where only the last value in the payload really matters, like the
|
||||
commit in a "deploy" event. In these cases, things just work.
|
||||
|
||||
Some events, however, shouldn't be coalesced. For example, if you had
|
||||
an event "queue" that queues some item, then you want to make sure all
|
||||
of those events are seen, even if many are sent in a short period of time.
|
||||
In this case, the `-coalesce=false` flag should be passed to the
|
||||
`serf event` command.
|
||||
|
||||
If you send some events of the same name with coalescence enabled and some
|
||||
without, then only the events that have coalescing enabled will actually
|
||||
coalesce. The others will always be delivered.
|
||||
|
|
@ -4,29 +4,32 @@ page_title: "Commands: Force Leave"
|
|||
sidebar_current: "docs-commands-forceleave"
|
||||
---
|
||||
|
||||
# Serf Force Leave
|
||||
# Consul Force Leave
|
||||
|
||||
Command: `serf force-leave`
|
||||
Command: `consul force-leave`
|
||||
|
||||
The `force-leave` command forces a member of a Serf cluster to enter the
|
||||
The `force-leave` command forces a member of a Consul cluster to enter the
|
||||
"left" state. Note that if the member is still actually alive, it will
|
||||
eventually rejoin the cluster. The true purpose of this method is to force
|
||||
remove "failed" nodes.
|
||||
|
||||
Serf periodically tries to reconnect to "failed" nodes in case it is a
|
||||
Consul periodically tries to reconnect to "failed" nodes in case it is a
|
||||
network partition. After some configured amount of time (by default 24 hours),
|
||||
Serf will reap "failed" nodes and stop trying to reconnect. The `force-leave`
|
||||
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
|
||||
command can be used to transition the "failed" nodes to "left" nodes more
|
||||
quickly.
|
||||
|
||||
This can be particularly useful for a node that was running as a server,
|
||||
as it will be removed from the Raft quorum.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `serf force-leave [options] node`
|
||||
Usage: `consul force-leave [options] node`
|
||||
|
||||
The following command-line options are available for this command.
|
||||
Every option is optional:
|
||||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
"127.0.0.1:8400" which is the default RPC address of a Consul agent.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,47 +4,58 @@ page_title: "Commands"
|
|||
sidebar_current: "docs-commands"
|
||||
---
|
||||
|
||||
# Serf Commands (CLI)
|
||||
# Consul Commands (CLI)
|
||||
|
||||
Serf is controlled via a very easy to use command-line interface (CLI).
|
||||
Serf is only a single command-line application: `serf`. This application
|
||||
Consul is controlled via a very easy to use command-line interface (CLI).
|
||||
Consul is only a single command-line application: `consul`. This application
|
||||
then takes a subcommand such as "agent" or "members". The complete list of
|
||||
subcommands is in the navigation to the left.
|
||||
|
||||
The `serf` CLI is a well-behaved command line application. In erroneous
|
||||
The `Consul` CLI is a well-behaved command line application. In erroneous
|
||||
cases, a non-zero exit status will be returned. It also responds to `-h` and `--help`
|
||||
as you'd most likely expect. And some commands that expect input accept
|
||||
"-" as a parameter to tell Serf to read the input from stdin.
|
||||
"-" as a parameter to tell Consul to read the input from stdin.
|
||||
|
||||
To view a list of the available commands at any time, just run `serf` with
|
||||
To view a list of the available commands at any time, just run `consul` with
|
||||
no arguments:
|
||||
|
||||
```
|
||||
$ serf
|
||||
usage: serf [--version] [--help] <command> [<args>]
|
||||
$ consul
|
||||
usage: consul [--version] [--help] <command> [<args>]
|
||||
|
||||
Available commands are:
|
||||
agent Runs a Serf agent
|
||||
event Send a custom event through the Serf cluster
|
||||
agent Runs a Consul agent
|
||||
force-leave Forces a member of the cluster to enter the "left" state
|
||||
join Tell Serf agent to join cluster
|
||||
join Tell Consul agent to join cluster
|
||||
keygen Generates a new encryption key
|
||||
leave Gracefully leaves the Serf cluster and shuts down
|
||||
members Lists the members of a Serf cluster
|
||||
monitor Stream logs from a Serf agent
|
||||
version Prints the Serf version
|
||||
leave Gracefully leaves the Consul cluster and shuts down
|
||||
members Lists the members of a Consul cluster
|
||||
monitor Stream logs from a Consul agent
|
||||
version Prints the Consul version
|
||||
```
|
||||
|
||||
To get help for any specific command, pass the `-h` flag to the relevant
|
||||
subcommand. For example, to see help about the `members` subcommand:
|
||||
|
||||
```
|
||||
$ serf members -h
|
||||
Usage: serf members [options]
|
||||
$ consul members -h
|
||||
Usage: consul members [options]
|
||||
|
||||
Outputs the members of a running Serf agent.
|
||||
Outputs the members of a running Consul agent.
|
||||
|
||||
Options:
|
||||
|
||||
-rpc-addr=127.0.0.1:7373 RPC address of the Serf agent.
|
||||
-detailed Additional information such as protocol verions
|
||||
will be shown.
|
||||
|
||||
-role=<regexp> If provided, output is filtered to only nodes matching
|
||||
the regular expression for role
|
||||
|
||||
-rpc-addr=127.0.0.1:8400 RPC address of the Consul agent.
|
||||
|
||||
-status=<regexp> If provided, output is filtered to only nodes matching
|
||||
the regular expression for status
|
||||
|
||||
-wan If the agent is in server mode, this can be used to return
|
||||
the other peers in the WAN pool
|
||||
```
|
||||
|
|
|
|||
|
|
@ -4,12 +4,12 @@ page_title: "Commands: Join"
|
|||
sidebar_current: "docs-commands-join"
|
||||
---
|
||||
|
||||
# Serf Join
|
||||
# Consul Join
|
||||
|
||||
Command: `serf join`
|
||||
Command: `consul join`
|
||||
|
||||
The `serf join` command tells a Serf agent to join an existing cluster.
|
||||
A new Serf agent must join with at least one existing member of a cluster
|
||||
The `consul join` command tells a Consul agent to join an existing cluster.
|
||||
A new Consul agent must join with at least one existing member of a cluster
|
||||
in order to join an existing cluster. After joining that one member,
|
||||
the gossip layer takes over, propagating the updated membership state across
|
||||
the cluster.
|
||||
|
|
@ -23,27 +23,19 @@ two nodes join to become a single cluster.
|
|||
|
||||
## Usage
|
||||
|
||||
Usage: `serf join [options] address ...`
|
||||
Usage: `consul join [options] address ...`
|
||||
|
||||
You may call join with multiple addresses if you want to try to join
|
||||
multiple clusters. Serf will attempt to join all clusters, and the join
|
||||
command will fail only if Serf was unable to join with any.
|
||||
multiple clusters. Consul will attempt to join all addresses, and the join
|
||||
command will fail only if Consul was unable to join with any.
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
* `-replay` - If set, old user events from the past will be replayed for the
|
||||
agent/cluster that is joining. Otherwise, past events will be ignored.
|
||||
* `-wan` - For agents running in server mode, the agent will attempt to join
|
||||
other servers gossiping in a WAN cluster. This is used to form a bridge between
|
||||
multiple datacenters.
|
||||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
"127.0.0.1:8400" which is the default RPC address of a Consul agent.
|
||||
|
||||
## Replaying User Events
|
||||
|
||||
When joining a cluster, the past events that were sent to the cluster are
|
||||
usually ignored. However, if you specify the `-replay` flag, then past events
|
||||
will be replayed on the joining cluster.
|
||||
|
||||
Note that only a fixed amount of past events are stored. At the time of writing
|
||||
this documentation, that fixed amount is 1024 events. Therefore, if you replay
|
||||
events, you'll only receive the past 1024 events (if there are that many).
|
||||
|
|
|
|||
|
|
@ -4,11 +4,11 @@ page_title: "Commands: Keygen"
|
|||
sidebar_current: "docs-commands-keygen"
|
||||
---
|
||||
|
||||
# Serf Keygen
|
||||
# Consul Keygen
|
||||
|
||||
Command: `serf keygen`
|
||||
Command: `consul keygen`
|
||||
|
||||
The `serf keygen` command generates an encryption key that can be used for
|
||||
[Serf agent traffic encryption](/docs/agent/encryption.html).
|
||||
The `consul keygen` command generates an encryption key that can be used for
|
||||
[Consul agent traffic encryption](/docs/agent/encryption.html).
|
||||
The keygen command uses a cryptographically
|
||||
strong pseudo-random number generator to generate the key.
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@ page_title: "Commands: Leave"
|
|||
sidebar_current: "docs-commands-leave"
|
||||
---
|
||||
|
||||
# Serf Leave
|
||||
# Consul Leave
|
||||
|
||||
Command: `serf leave`
|
||||
Command: `consul leave`
|
||||
|
||||
The leave command triggers a graceful leave and shutdown of the agent.
|
||||
|
||||
|
|
@ -14,13 +14,17 @@ This is used to ensure other nodes see the agent as "left" instead of
|
|||
"failed". Nodes that leave will not attempt to re-join the cluster
|
||||
on restarting with a snapshot.
|
||||
|
||||
For nodes in server mode, the node is removed from the Raft peer set
|
||||
in a graceful manner. This is critical, as in certain situation a
|
||||
non-graceful can affect cluster availability.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `serf leave`
|
||||
Usage: `consul leave`
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
"127.0.0.1:8400" which is the default RPC address of a Consul agent.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,37 +4,38 @@ page_title: "Commands: Members"
|
|||
sidebar_current: "docs-commands-members"
|
||||
---
|
||||
|
||||
# Serf Members
|
||||
# Consul Members
|
||||
|
||||
Command: `serf members`
|
||||
Command: `consul members`
|
||||
|
||||
The members command outputs the current list of members that a Serf
|
||||
The members command outputs the current list of members that a Consul
|
||||
agent knows about, along with their state. The state of a node can only
|
||||
be "alive" or "failed".
|
||||
be "alive", "left", or "failed".
|
||||
|
||||
Nodes in the "failed" state are still listed because Serf attempts to
|
||||
Nodes in the "failed" state are still listed because Consul attempts to
|
||||
reconnect with failed nodes for a certain amount of time in the case
|
||||
that the failure is actually just a network partition.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `serf members [options]`
|
||||
Usage: `consul members [options]`
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
* `-detailed` - Will show additional information per member, such as the
|
||||
protocol version that each can understand and that each is speaking.
|
||||
|
||||
* `-format` - Controls the output format. Supports `text` and `json`.
|
||||
The default format is `text`.
|
||||
|
||||
* `-role` - If provided, output is filtered to only nodes matching
|
||||
the regular expression for role
|
||||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
"127.0.0.1:8400 " which is the default RPC address of a Consul agent.
|
||||
|
||||
* `-status` - If provided, output is filtered to only nodes matching
|
||||
the regular expression for status
|
||||
|
||||
* `-wan` - For agents in Server mode, this will return the list of nodes
|
||||
in the WAN gossip pool. These are generally all the server nodes in
|
||||
each datacenter.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,12 +4,12 @@ page_title: "Commands: Monitor"
|
|||
sidebar_current: "docs-commands-monitor"
|
||||
---
|
||||
|
||||
# Serf Monitor
|
||||
# Consul Monitor
|
||||
|
||||
Command: `serf monitor`
|
||||
Command: `consul monitor`
|
||||
|
||||
The monitor command is used to connect and follow the logs of a running
|
||||
Serf agent. Monitor will show the recent logs and then continue to follow
|
||||
Consul agent. Monitor will show the recent logs and then continue to follow
|
||||
the logs, not exiting until interrupted or until the remote agent quits.
|
||||
|
||||
The power of the monitor command is that it allows you to log the agent
|
||||
|
|
@ -18,7 +18,7 @@ logs and watch the debug logs if necessary.
|
|||
|
||||
## Usage
|
||||
|
||||
Usage: `serf monitor [options]`
|
||||
Usage: `consul monitor [options]`
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
|
|
@ -29,5 +29,5 @@ The command-line flags are all optional. The list of available flags are:
|
|||
|
||||
* `-rpc-addr` - Address to the RPC 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:7373" which is the default RPC address of a Serf agent.
|
||||
"127.0.0.1:8400" which is the default RPC address of a Consul agent.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
<a href="/docs/upgrading.html">Upgrading and Compatibility</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-upgrading-upgrading") %>>
|
||||
<a href="/docs/upgrading.html">Upgrading Serf</a>
|
||||
<a href="/docs/upgrading.html">Upgrading Consul</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-upgrading-compat") %>>
|
||||
|
|
@ -20,7 +20,7 @@
|
|||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-internals") %>>
|
||||
<a href="/docs/internals/index.html">Serf Internals</a>
|
||||
<a href="/docs/internals/index.html">Consul Internals</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-internals-gossip") %>>
|
||||
<a href="/docs/internals/gossip.html">Gossip Protocol</a>
|
||||
|
|
@ -37,16 +37,12 @@
|
|||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands") %>>
|
||||
<a href="/docs/commands/index.html">Serf Commands (CLI)</a>
|
||||
<a href="/docs/commands/index.html">Consul Commands (CLI)</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-agent") %>>
|
||||
<a href="/docs/commands/agent.html">agent</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-event") %>>
|
||||
<a href="/docs/commands/event.html">event</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-forceleave") %>>
|
||||
<a href="/docs/commands/force-leave.html">force-leave</a>
|
||||
</li>
|
||||
|
|
@ -75,7 +71,7 @@
|
|||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent") %>>
|
||||
<a href="/docs/agent/basics.html">Serf Agent</a>
|
||||
<a href="/docs/agent/basics.html">Consul Agent</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-agent-running") %>>
|
||||
<a href="/docs/agent/basics.html">Running and Stopping</a>
|
||||
|
|
@ -85,10 +81,6 @@
|
|||
<a href="/docs/agent/options.html">Configuration</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-events") %>>
|
||||
<a href="/docs/agent/event-handlers.html">Event Handlers</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-encryption") %>>
|
||||
<a href="/docs/agent/encryption.html">Encryption</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue