status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

website: updating documentation on commands

This commit is contained in:
Armon Dadgar 2014-02-18 17:32:13 -08:00
parent 03e62172f1
commit 1fb7b330ad
16 changed files with 97 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
command/agent/command.go
View File

@ -374,7 +374,7 @@ Usage: consul agent [options]
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) return strings.TrimSpace(helpText)
} }

2
command/force_leave.go
View File

@ -62,7 +62,7 @@ Usage: consul force-leave [options] name
Options: 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) return strings.TrimSpace(helpText)

4
command/join.go
View File

@ -22,8 +22,8 @@ Usage: consul join [options] address ...
Options: 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 -wan Joins a server to another server in the WAN pool
` `
return strings.TrimSpace(helpText) return strings.TrimSpace(helpText)
} }

2
command/leave.go
View File

@ -21,7 +21,7 @@ Usage: consul leave
Options: 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) return strings.TrimSpace(helpText)
} }

6
command/members.go
View File

@ -30,12 +30,12 @@ Options:
-role=<regexp> If provided, output is filtered to only nodes matching -role=<regexp> If provided, output is filtered to only nodes matching
the regular expression for role 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 -status=<regexp> If provided, output is filtered to only nodes matching
the regular expression for status the regular expression for status
-wan If the agent is in server mode, this can be used to return -wan If the agent is in server mode, this can be used to return
the other peers in the WAN pool the other peers in the WAN pool
` `
return strings.TrimSpace(helpText) return strings.TrimSpace(helpText)

2
command/monitor.go
View File

@ -32,7 +32,7 @@ Usage: consul monitor [options]
Options: Options:
-log-level=info Log level of the agent. -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) return strings.TrimSpace(helpText)
} }

10
website/source/docs/commands/agent.html.markdown
View File

@ -4,13 +4,13 @@ page_title: "Commands: Agent"
sidebar_current: "docs-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, 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 Due to the power and flexibility of this command, the Consul agent
is documented in its own section. See the [Serf Agent](/docs/agent/basics.html) 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 section for more information on how to use this command and the
options it has. options it has.

76
website/source/docs/commands/event.html.markdown
View File

@ -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.

17
website/source/docs/commands/force-leave.html.markdown
View File

@ -4,29 +4,32 @@ page_title: "Commands: Force Leave"
sidebar_current: "docs-commands-forceleave" 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 "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 eventually rejoin the cluster. The true purpose of this method is to force
remove "failed" nodes. 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), 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 command can be used to transition the "failed" nodes to "left" nodes more
quickly. 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
Usage: `serf force-leave [options] node` Usage: `consul force-leave [options] node`
The following command-line options are available for this command. The following command-line options are available for this command.
Every option is optional: Every option is optional:
* `-rpc-addr` - Address to the RPC server of the agent you want to contact * `-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 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.

49
website/source/docs/commands/index.html.markdown
View File

@ -4,47 +4,58 @@ page_title: "Commands"
sidebar_current: "docs-commands" sidebar_current: "docs-commands"
--- ---
# Serf Commands (CLI) # Consul Commands (CLI)
Serf is controlled via a very easy to use command-line interface (CLI). Consul 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 only a single command-line application: `consul`. This application
then takes a subcommand such as "agent" or "members". The complete list of then takes a subcommand such as "agent" or "members". The complete list of
subcommands is in the navigation to the left. 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` 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 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: no arguments:
``` ```
$ serf $ consul
usage: serf [--version] [--help] <command> [<args>] usage: consul [--version] [--help] <command> [<args>]
Available commands are: Available commands are:
agent Runs a Serf agent agent Runs a Consul agent
event Send a custom event through the Serf cluster
force-leave Forces a member of the cluster to enter the "left" state 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 keygen Generates a new encryption key
leave Gracefully leaves the Serf cluster and shuts down leave Gracefully leaves the Consul cluster and shuts down
members Lists the members of a Serf cluster members Lists the members of a Consul cluster
monitor Stream logs from a Serf agent monitor Stream logs from a Consul agent
version Prints the Serf version version Prints the Consul version
``` ```
To get help for any specific command, pass the `-h` flag to the relevant To get help for any specific command, pass the `-h` flag to the relevant
subcommand. For example, to see help about the `members` subcommand: subcommand. For example, to see help about the `members` subcommand:
``` ```
$ serf members -h $ consul members -h
Usage: serf members [options] Usage: consul members [options]
Outputs the members of a running Serf agent. Outputs the members of a running Consul agent.
Options: 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
``` ```

30
website/source/docs/commands/join.html.markdown
View File

@ -4,12 +4,12 @@ page_title: "Commands: Join"
sidebar_current: "docs-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. The `consul join` command tells a Consul agent to join an existing cluster.
A new Serf agent must join with at least one existing member of a 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, in order to join an existing cluster. After joining that one member,
the gossip layer takes over, propagating the updated membership state across the gossip layer takes over, propagating the updated membership state across
the cluster. the cluster.
@ -23,27 +23,19 @@ two nodes join to become a single cluster.
## Usage ## 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 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 multiple clusters. Consul will attempt to join all addresses, and the join
command will fail only if Serf was unable to join with any. 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: 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 * `-wan` - For agents running in server mode, the agent will attempt to join
agent/cluster that is joining. Otherwise, past events will be ignored. 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 * `-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 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).

8
website/source/docs/commands/keygen.html.markdown
View File

@ -4,11 +4,11 @@ page_title: "Commands: Keygen"
sidebar_current: "docs-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 The `consul keygen` command generates an encryption key that can be used for
[Serf agent traffic encryption](/docs/agent/encryption.html). [Consul agent traffic encryption](/docs/agent/encryption.html).
The keygen command uses a cryptographically The keygen command uses a cryptographically
strong pseudo-random number generator to generate the key. strong pseudo-random number generator to generate the key.

12
website/source/docs/commands/leave.html.markdown
View File

@ -4,9 +4,9 @@ page_title: "Commands: Leave"
sidebar_current: "docs-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. 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 "failed". Nodes that leave will not attempt to re-join the cluster
on restarting with a snapshot. 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
Usage: `serf leave` Usage: `consul leave`
The command-line flags are all optional. The list of available flags are: 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 * `-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 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.

21
website/source/docs/commands/members.html.markdown
View File

@ -4,37 +4,38 @@ page_title: "Commands: Members"
sidebar_current: "docs-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 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 reconnect with failed nodes for a certain amount of time in the case
that the failure is actually just a network partition. that the failure is actually just a network partition.
## Usage ## Usage
Usage: `serf members [options]` Usage: `consul members [options]`
The command-line flags are all optional. The list of available flags are: The command-line flags are all optional. The list of available flags are:
* `-detailed` - Will show additional information per member, such as the * `-detailed` - Will show additional information per member, such as the
protocol version that each can understand and that each is speaking. 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 * `-role` - If provided, output is filtered to only nodes matching
the regular expression for role the regular expression for role
* `-rpc-addr` - Address to the RPC server of the agent you want to contact * `-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 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 * `-status` - If provided, output is filtered to only nodes matching
the regular expression for status 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.

10
website/source/docs/commands/monitor.html.markdown
View File

@ -4,12 +4,12 @@ page_title: "Commands: Monitor"
sidebar_current: "docs-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 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 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 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
Usage: `serf monitor [options]` Usage: `consul monitor [options]`
The command-line flags are all optional. The list of available flags are: 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 * `-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 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.

16
website/source/layouts/docs.erb
View File

@ -10,7 +10,7 @@
<a href="/docs/upgrading.html">Upgrading and Compatibility</a> <a href="/docs/upgrading.html">Upgrading and Compatibility</a>
<ul class="nav"> <ul class="nav">
<li<%= sidebar_current("docs-upgrading-upgrading") %>> <li<%= sidebar_current("docs-upgrading-upgrading") %>>
<a href="/docs/upgrading.html">Upgrading Serf</a> <a href="/docs/upgrading.html">Upgrading Consul</a>
</li> </li>
<li<%= sidebar_current("docs-upgrading-compat") %>> <li<%= sidebar_current("docs-upgrading-compat") %>>
@ -20,7 +20,7 @@
</li> </li>
<li<%= sidebar_current("docs-internals") %>> <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"> <ul class="nav">
<li<%= sidebar_current("docs-internals-gossip") %>> <li<%= sidebar_current("docs-internals-gossip") %>>
<a href="/docs/internals/gossip.html">Gossip Protocol</a> <a href="/docs/internals/gossip.html">Gossip Protocol</a>
@ -37,16 +37,12 @@
</li> </li>
<li<%= sidebar_current("docs-commands") %>> <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"> <ul class="nav">
<li<%= sidebar_current("docs-commands-agent") %>> <li<%= sidebar_current("docs-commands-agent") %>>
<a href="/docs/commands/agent.html">agent</a> <a href="/docs/commands/agent.html">agent</a>
</li> </li>
<li<%= sidebar_current("docs-commands-event") %>>
<a href="/docs/commands/event.html">event</a>
</li>
<li<%= sidebar_current("docs-commands-forceleave") %>> <li<%= sidebar_current("docs-commands-forceleave") %>>
<a href="/docs/commands/force-leave.html">force-leave</a> <a href="/docs/commands/force-leave.html">force-leave</a>
</li> </li>
@ -75,7 +71,7 @@
</li> </li>
<li<%= sidebar_current("docs-agent") %>> <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"> <ul class="nav">
<li<%= sidebar_current("docs-agent-running") %>> <li<%= sidebar_current("docs-agent-running") %>>
<a href="/docs/agent/basics.html">Running and Stopping</a> <a href="/docs/agent/basics.html">Running and Stopping</a>
@ -85,10 +81,6 @@
<a href="/docs/agent/options.html">Configuration</a> <a href="/docs/agent/options.html">Configuration</a>
</li> </li>
<li<%= sidebar_current("docs-agent-events") %>>
<a href="/docs/agent/event-handlers.html">Event Handlers</a>
</li>
<li<%= sidebar_current("docs-agent-encryption") %>> <li<%= sidebar_current("docs-agent-encryption") %>>
<a href="/docs/agent/encryption.html">Encryption</a> <a href="/docs/agent/encryption.html">Encryption</a>
</li> </li>