diff --git a/command/agent/command.go b/command/agent/command.go index 2ca2f015cd..f3fc964577 100644 --- a/command/agent/command.go +++ b/command/agent/command.go @@ -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) } diff --git a/command/force_leave.go b/command/force_leave.go index 329ffa0f75..4839135d61 100644 --- a/command/force_leave.go +++ b/command/force_leave.go @@ -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) diff --git a/command/join.go b/command/join.go index d0e52a1c57..ea22e1906b 100644 --- a/command/join.go +++ b/command/join.go @@ -22,8 +22,8 @@ Usage: consul join [options] address ... Options: - -rpc-addr=127.0.0.1:7373 RPC address of the Consul agent. - -wan Joins a server to another server in the WAN pool + -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) } diff --git a/command/leave.go b/command/leave.go index 03318dcb93..b402f9e35d 100644 --- a/command/leave.go +++ b/command/leave.go @@ -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) } diff --git a/command/members.go b/command/members.go index 46bd0915b7..5194ff62a4 100644 --- a/command/members.go +++ b/command/members.go @@ -30,12 +30,12 @@ Options: -role= 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= If provided, output is filtered to only nodes matching + -status= 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 + -wan If the agent is in server mode, this can be used to return the other peers in the WAN pool ` return strings.TrimSpace(helpText) diff --git a/command/monitor.go b/command/monitor.go index ae470f051f..f24646662c 100644 --- a/command/monitor.go +++ b/command/monitor.go @@ -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) } diff --git a/website/source/docs/commands/agent.html.markdown b/website/source/docs/commands/agent.html.markdown index ccf9c1c942..43e366a520 100644 --- a/website/source/docs/commands/agent.html.markdown +++ b/website/source/docs/commands/agent.html.markdown @@ -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. diff --git a/website/source/docs/commands/event.html.markdown b/website/source/docs/commands/event.html.markdown deleted file mode 100644 index 3833c89066..0000000000 --- a/website/source/docs/commands/event.html.markdown +++ /dev/null @@ -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. diff --git a/website/source/docs/commands/force-leave.html.markdown b/website/source/docs/commands/force-leave.html.markdown index df49a08d20..6664bfccb6 100644 --- a/website/source/docs/commands/force-leave.html.markdown +++ b/website/source/docs/commands/force-leave.html.markdown @@ -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. diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index d7eb5ee1df..dcf9f6e1cf 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/website/source/docs/commands/index.html.markdown @@ -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] [] +$ consul +usage: consul [--version] [--help] [] 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= 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= 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 ``` diff --git a/website/source/docs/commands/join.html.markdown b/website/source/docs/commands/join.html.markdown index 70fb450edc..a386ab2f6a 100644 --- a/website/source/docs/commands/join.html.markdown +++ b/website/source/docs/commands/join.html.markdown @@ -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). diff --git a/website/source/docs/commands/keygen.html.markdown b/website/source/docs/commands/keygen.html.markdown index f6fa387e59..8eb68702ad 100644 --- a/website/source/docs/commands/keygen.html.markdown +++ b/website/source/docs/commands/keygen.html.markdown @@ -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. diff --git a/website/source/docs/commands/leave.html.markdown b/website/source/docs/commands/leave.html.markdown index 17958c2359..f897867529 100644 --- a/website/source/docs/commands/leave.html.markdown +++ b/website/source/docs/commands/leave.html.markdown @@ -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. diff --git a/website/source/docs/commands/members.html.markdown b/website/source/docs/commands/members.html.markdown index 5fed38879f..45ede2ac0d 100644 --- a/website/source/docs/commands/members.html.markdown +++ b/website/source/docs/commands/members.html.markdown @@ -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. + diff --git a/website/source/docs/commands/monitor.html.markdown b/website/source/docs/commands/monitor.html.markdown index f4b48ee4fa..09a4ddc28a 100644 --- a/website/source/docs/commands/monitor.html.markdown +++ b/website/source/docs/commands/monitor.html.markdown @@ -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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 31da7fc196..d9b0713be1 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -10,7 +10,7 @@ Upgrading and Compatibility