mirror of https://github.com/status-im/consul.git
website: working on docs
This commit is contained in:
Armon Dadgar
parent
467db27813
commit
03e62172f1
|
|
@ -4,75 +4,87 @@ page_title: "Agent"
|
|||
sidebar_current: "docs-agent-running"
|
||||
---
|
||||
|
||||
# Serf Agent
|
||||
# Consul Agent
|
||||
|
||||
The Serf agent is the core process of Serf. The agent maintains membership
|
||||
information, propagates events, invokes event handlers, detects failures,
|
||||
and more. The agent must run on every node that is part of a Serf cluster.
|
||||
The Consul agent is the core process of Consul. The agent maintains membership
|
||||
information, registers services, runs checks, responds to queries
|
||||
and more. The agent must run on every node that is part of a Consul cluster.
|
||||
|
||||
Any Agent may run in one of two modes: client or server. A server
|
||||
node takes on the additional responsibility of being part of the [consensus quorum](#).
|
||||
These nodes take part in Raft, and provide strong consistency and availability in
|
||||
the case of failure. The higher burden on the server nodes means that usually they
|
||||
should be run on dedicated instances, as they are more resource intensive than a client
|
||||
node. Client nodes make up the majority of the cluster, and they are very lightweight
|
||||
as they maintain very little state and interface with the server nodes for most operations.
|
||||
|
||||
## Running an Agent
|
||||
|
||||
The agent is started with the `serf agent` command. This command blocks,
|
||||
The agent is started with the `consul agent` command. This command blocks,
|
||||
running forever or until told to quit. The agent command takes a variety
|
||||
of configuration options but the defaults are usually good enough. When
|
||||
running `serf agent`, you should see output similar to that below:
|
||||
running `consul agent`, you should see output similar to that below:
|
||||
|
||||
```
|
||||
$ serf agent
|
||||
==> Starting Serf agent...
|
||||
==> Serf agent running!
|
||||
Node name: 'mitchellh.local'
|
||||
Bind addr: '0.0.0.0:7946'
|
||||
RPC addr: '127.0.0.1:7373'
|
||||
Encrypted: false
|
||||
Snapshot: false
|
||||
Profile: lan
|
||||
$ consul agent -data=/tmp/consul
|
||||
==> Starting Consul agent...
|
||||
==> Starting Consul agent RPC...
|
||||
==> Consul agent running!
|
||||
Node name: 'Armons-MacBook-Air.local'
|
||||
Datacenter: 'dc1'
|
||||
Advertise addr: '10.1.10.12'
|
||||
RPC addr: '127.0.0.1:8400'
|
||||
HTTP addr: '127.0.0.1:8500'
|
||||
DNS addr: '127.0.0.1:8600'
|
||||
Encrypted: false
|
||||
Server: false (bootstrap: false)
|
||||
|
||||
==> Log data will now stream in as it occurs:
|
||||
|
||||
2013/10/22 10:35:33 [INFO] Serf agent starting
|
||||
2013/10/22 10:35:33 [INFO] serf: EventMemberJoin: mitchellh.local 127.0.0.1
|
||||
2013/10/22 10:35:33 [INFO] Serf agent started
|
||||
2013/10/22 10:35:33 [INFO] agent: Received event: member-join
|
||||
2014/02/18 14:25:02 [INFO] serf: EventMemberJoin: Armons-MacBook-Air.local 10.1.10.12
|
||||
2014/02/18 14:25:02 [ERR] agent: failed to sync remote state: No known Consul servers
|
||||
...
|
||||
```
|
||||
|
||||
There are six important components that `serf agent` outputs:
|
||||
There are several important components that `consul agent` outputs:
|
||||
|
||||
* **Node name**: This is a unique name for the agent. By default this
|
||||
is the hostname of the machine, but you may customize it to whatever
|
||||
you'd like using the `-node` flag.
|
||||
|
||||
* **Bind addr**: This is the address and port used for communication between
|
||||
Serf agents in a cluster. Every Serf agent in a cluster does not have to
|
||||
use the same port.
|
||||
* **Datacenter**: This is the datacenter the agent is configured to run
|
||||
in. Consul has first-class support for multiple datacenters, but to work efficiently
|
||||
each node must be configured to correctly report it's datacenter. The `-dc` flag
|
||||
can be used to set the datacenter. For single-DC configurations, the agent
|
||||
will default to "dc1".
|
||||
|
||||
* **Advertise addr**: This is the address and port used for communication between
|
||||
Consul agents in a cluster. Every Consul agent in a cluster does not have to
|
||||
use the same port, but this address **MUST** be reachable by all other nodes.
|
||||
|
||||
* **RPC addr**: This is the address and port used for RPC communications
|
||||
for other `serf` commands. Other Serf commands such as `serf members`
|
||||
for other `consul` commands. Other Consul commands such as `consul members`
|
||||
connect to a running agent and use RPC to query and control the agent.
|
||||
By default, this binds only to localhost on the default port. If you
|
||||
change this address, you'll have to specify an `-rpc-addr` to commands
|
||||
such as `serf members` so they know how to talk to the agent. This is also
|
||||
the address other applications can use over [RPC to control Serf](/docs/agent/rpc.html).
|
||||
such as `consul members` so they know how to talk to the agent. This is also
|
||||
the address other applications can use over [RPC to control Consul](/docs/agent/rpc.html).
|
||||
|
||||
* **Encrypted**: This shows if Serf is encrypting all traffic that it
|
||||
* **HTTP/DNS addr**: This is the addresses the agent is listening on for the
|
||||
HTTP and DNS interfaces respectively. These are bound to localhost for security,
|
||||
but can be configured to listen on other addresses or ports.
|
||||
|
||||
* **Encrypted**: This shows if Consul is encrypting all traffic that it
|
||||
sends and expects to receive. It is a good sanity check to avoid sending
|
||||
non-encrypted traffic over any public networks. You can read more about
|
||||
[encryption here](/docs/agent/encryption.html).
|
||||
|
||||
* **Snapshot**: This shows if Serf snapshotting is enabled. The snapshot
|
||||
file enables Serf to automatically re-join a cluster after failure and
|
||||
prevents replay of events that have already been seen. It requires storing
|
||||
state on disk, and [must be configured](/docs/agent/options.html)
|
||||
using a CLI flag or in the configuration directory. If it is not provided,
|
||||
other nodes will still attempt to reconnect on recovery, however the node
|
||||
will take longer to join the cluster and will replay old events.
|
||||
|
||||
* **Profile**: The profile controls various timing values which should
|
||||
be appropriate to the environment Serf is running in. It defaults to
|
||||
optimizing for a LAN environment, but can also be set for WAN or
|
||||
local-only communication. The profile can be set in
|
||||
the [configuration](/docs/agent/options.html).
|
||||
* **Server**: This shows if the agent is running in the server or client mode.
|
||||
Server nodes have the extra burden of participating in the consensus quorum,
|
||||
storing cluster state, and handling queries. Additionally, a server may be
|
||||
in "bootstrap" mode. The first server must be in this mode to allow additional
|
||||
servers to join the cluster. Multiple servers cannot be in bootstrap mode,
|
||||
otherwise the cluster state will be inconsistent.
|
||||
|
||||
## Stopping an Agent
|
||||
|
||||
|
|
@ -87,8 +99,13 @@ When force killed, the agent ends immediately. The rest of the cluster will
|
|||
eventually (usually within seconds) detect that the node has died and will
|
||||
notify the cluster that the node has _failed_.
|
||||
|
||||
The difference between a node _failing_ and a node _leaving_ may not be
|
||||
important for your use case. For example, for a web server and load
|
||||
It is especially important that a server node be allowed to gracefully leave,
|
||||
so that there will be a minimal impact on availablity as the server leaves
|
||||
the consensus quorum.
|
||||
|
||||
For client agents, the difference between a node _failing_ and a node _leaving_
|
||||
may not be important for your use case. For example, for a web server and load
|
||||
balancer setup, both result in the same action: remove the web node
|
||||
from the load balancer pool. But for other situations, you may handle
|
||||
each scenario differently.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,22 +6,22 @@ sidebar_current: "docs-agent-encryption"
|
|||
|
||||
# Encryption
|
||||
|
||||
The Serf agent supports encrypting all of its network traffic. The exact
|
||||
The Consul agent supports encrypting all of its network traffic. The exact
|
||||
method of this encryption is described on the
|
||||
[encryption internals page](/docs/internals/security.html).
|
||||
|
||||
## Enabling Encryption
|
||||
|
||||
Enabling encryption only requires that you set an encryption key when
|
||||
starting the Serf agent. The key can be set using the `-encrypt` flag
|
||||
on `serf agent` or by setting the `encrypt_key` in a configuration file.
|
||||
starting the Consul agent. The key can be set using the `-encrypt` flag
|
||||
on `consul agent` or by setting the `encrypt_key` in a configuration file.
|
||||
It is advisable to put the key in a configuration file to avoid other users
|
||||
from being able to discover it by inspecting running processes.
|
||||
The key must be 16-bytes that are base64 encoded. The easiest method to
|
||||
obtain a cryptographically suitable key is by using `serf keygen`.
|
||||
obtain a cryptographically suitable key is by using `consul keygen`.
|
||||
|
||||
```
|
||||
$ serf keygen
|
||||
$ consul keygen
|
||||
cg8StVXbQJ0gPvMd9o7yrg==
|
||||
```
|
||||
|
||||
|
|
@ -29,26 +29,21 @@ With that key, you can enable encryption on the agent. You can verify
|
|||
encryption is enabled because the output will include "Encrypted: true".
|
||||
|
||||
```
|
||||
$ serf agent -encrypt=cg8StVXbQJ0gPvMd9o7yrg==
|
||||
==> Starting Serf agent...
|
||||
==> Serf agent running!
|
||||
Node name: 'mitchellh.local'
|
||||
Bind addr: '0.0.0.0:7946'
|
||||
RPC addr: '127.0.0.1:7373'
|
||||
Encrypted: true
|
||||
$ consul agent -data=/tmp/consul -encrypt=cg8StVXbQJ0gPvMd9o7yrg==
|
||||
==> Starting Consul agent...
|
||||
==> Starting Consul agent RPC...
|
||||
==> Consul agent running!
|
||||
Node name: 'Armons-MacBook-Air.local'
|
||||
Datacenter: 'dc1'
|
||||
Advertise addr: '10.1.10.12'
|
||||
RPC addr: '127.0.0.1:8400'
|
||||
HTTP addr: '127.0.0.1:8500'
|
||||
DNS addr: '127.0.0.1:8600'
|
||||
Encrypted: true
|
||||
Server: false (bootstrap: false)
|
||||
...
|
||||
```
|
||||
|
||||
All nodes within a Serf cluster must share the same encryption key in
|
||||
All nodes within a Consul cluster must share the same encryption key in
|
||||
order to send and receive cluster information.
|
||||
|
||||
## Multiple Clusters
|
||||
|
||||
If you're running multiple Serf clusters, for example a Serf cluster to
|
||||
maintain cache nodes and a Serf cluster to maintain web servers, then you
|
||||
can use different encryption keys for each cluster in order to separately
|
||||
encrypt the traffic.
|
||||
|
||||
This has the added benefit that the Serf agents from one cluster cannot
|
||||
even accidentally join the other cluster, since the two clusters will not
|
||||
be able to communicate without the same encryption key.
|
||||
|
|
|
|||
|
|
@ -11,14 +11,14 @@ the command-line or via configuration files. All of the configuration
|
|||
options are completely optional and their defaults will be specified
|
||||
with their descriptions.
|
||||
|
||||
When loading configuration, Serf loads the configuration from files
|
||||
When loading configuration, Consul loads the configuration from files
|
||||
and directories in the order specified. Configuration specified later
|
||||
will be merged into configuration specified earlier. In most cases,
|
||||
"merge" means that the later version will override the earlier. But in
|
||||
some cases, such as event handlers, merging just appends the handlers.
|
||||
The exact merging behavior will be specified.
|
||||
|
||||
Serf also supports reloading of configuration when it receives the
|
||||
Consul also supports reloading of configuration when it receives the
|
||||
SIGHUP signal. Not all changes are respected, but those that are
|
||||
are documented below.
|
||||
|
||||
|
|
@ -26,18 +26,19 @@ are documented below.
|
|||
|
||||
The options below are all specified on the command-line.
|
||||
|
||||
* `-bind` - The address that Serf will bind to for communication with
|
||||
other Serf nodes. By default this is "0.0.0.0:7946". Serf nodes may
|
||||
have different ports. If a join is specified without a port, we default
|
||||
to locally configured port. Serf uses both TCP and UDP and use the
|
||||
same port for both, so if you have any firewalls be sure to allow both protocols.
|
||||
If this configuration value is changed and no port is specified, the default of
|
||||
"7946" will be used. An important compatibility note, protocol version 2
|
||||
introduces support for non-consistent ports across the cluster. For more information,
|
||||
see the [compatibility page](/docs/compatibility.html).
|
||||
* `-serf-bind` - The address that the underlying Serf library will bind to.
|
||||
This is an IP address that should be reachable by all other nodes in the cluster.
|
||||
By default this is "0.0.0.0", meaning Consul will use the first available private
|
||||
IP address. Consul uses both TCP and UDP and use the same port for both, so if you
|
||||
have any firewalls be sure to allow both protocols.
|
||||
|
||||
* `-server-addr` - The address that the agent will bind to for handling RPC calls
|
||||
if running in server mode. This does not affect clients running in client mode.
|
||||
By default this is "0.0.0.0:8300". This port is used for TCP communications so any
|
||||
firewalls must be configured to allow this.
|
||||
|
||||
* `-advertise` - The advertise flag is used to change the address that we
|
||||
advertise to other nodes in the cluster. By default, the bind address is
|
||||
advertise to other nodes in the cluster. By default, the `-serf-bind` address is
|
||||
advertised. However, in some cases (specifically NAT traversal), there may
|
||||
be a routable address that cannot be bound to. This flag enables gossiping
|
||||
a different address to support this. If this address is not routable, the node
|
||||
|
|
@ -56,33 +57,11 @@ The options below are all specified on the command-line.
|
|||
in alphabetical order. For more information on the format of the configuration
|
||||
files, see the "Configuration Files" section below.
|
||||
|
||||
* `-discover` - Discover provides a cluster name, which is used with mDNS to
|
||||
automatically discover Serf peers. When provided, Serf will respond to mDNS
|
||||
queries and periodically poll for new peers. This feature requires a network
|
||||
environment that supports multicasting.
|
||||
|
||||
* `-encrypt` - Specifies the secret key to use for encryption of Serf
|
||||
network traffic. This key must be 16-bytes that are base64 encoded. The
|
||||
easiest way to create an encryption key is to use `serf keygen`. All
|
||||
easiest way to create an encryption key is to use `consul keygen`. All
|
||||
nodes within a cluster must share the same encryption key to communicate.
|
||||
|
||||
* `-event-handler` - Adds an event handler that Serf will invoke for
|
||||
events. This flag can be specified multiple times to define multiple
|
||||
event handlers. By default no event handlers are registered. See the
|
||||
[event handler page](/docs/agent/event-handlers.html) for more details on
|
||||
event handlers as well as a syntax for filtering event handlers by event.
|
||||
Event handlers can be changed by reloading the configuration.
|
||||
|
||||
* `-join` - Address of another agent to join upon starting up. This can be
|
||||
specified multiple times to specify multiple agents to join. If Serf is
|
||||
unable to join with any of the specified addresses, agent startup will
|
||||
fail. By default, the agent won't join any nodes when it starts up.
|
||||
|
||||
* `-replay` - If set, old user events from the past will be replayed for the
|
||||
agent/cluster that is joining based on a `-join` configuration. Otherwise,
|
||||
past events will be ignored. This configures for the initial join
|
||||
only.
|
||||
|
||||
* `-log-level` - The level of logging to show after the Serf agent has
|
||||
started. This defaults to "info". The available log levels are "trace",
|
||||
"debug", "info", "warn", "err". This is the log level that will be shown
|
||||
|
|
@ -93,46 +72,47 @@ The options below are all specified on the command-line.
|
|||
* `-node` - The name of this node in the cluster. This must be unique within
|
||||
the cluster. By default this is the hostname of the machine.
|
||||
|
||||
* `-profile` - Serf by default is configured to run in a LAN or Local Area
|
||||
Network. However, there are cases in which a user may want to use Serf over
|
||||
the Internet or (WAN), or even just locally. To support setting the correct
|
||||
configuration values for each environment, you can select a timing profile.
|
||||
The current choices are "lan", "wan", and "local". This defaults to "local".
|
||||
If a "lan" or "local" profile is used over the Internet, or a "local" profile
|
||||
over the LAN, a high rate of false failures is risked, as the timing constrains
|
||||
are too tight.
|
||||
* `-rpc-addr` - The address that Consul will bind to for the agent's RPC server.
|
||||
By default this is "127.0.0.1:8400", allowing only loopback connections.
|
||||
The RPC address is used by other Serf commands, such as `consul members`,
|
||||
in order to query a running Consul agent. It is also used by other applications
|
||||
to control Consul using it's [RPC protocol](/docs/agent/rpc.html).
|
||||
|
||||
* `-protocol` - The Serf protocol version to use. This defaults to the latest
|
||||
version. This should be set only when [upgrading](/docs/upgrading.html).
|
||||
You can view the protocol versions supported by Serf by running `serf -v`.
|
||||
* `-data` - This flag provides a data directory for the agent to store state.
|
||||
This is required for all agents. The directory should be durable across reboots.
|
||||
This is especially critical for agents that are running in server mode, as they
|
||||
must be able to persist the cluster state.
|
||||
|
||||
* `-role` - **Deprecated** The role of this node, if any. By default this is blank or empty.
|
||||
The role can be used by events in order to differentiate members of a
|
||||
cluster that may have different functional roles. For example, if you're
|
||||
using Serf in a load balancer and web server setup, you only want to add
|
||||
web servers to the load balancers, so the role of web servers may be "web"
|
||||
and the event handlers can filter on that. This has been deprecated as of
|
||||
version 0.4. Instead "-tag role=foo" should be used. The role can be changed
|
||||
during a config reload
|
||||
* `-dc` - This flag controls the datacenter the agent is running in. If not provided
|
||||
it defaults to "dc1". Consul has first class support for multiple data centers but
|
||||
it relies on proper configuration. Nodes in the same datacenter should be on a single
|
||||
LAN.
|
||||
|
||||
* `-rpc-addr` - The address that Serf will bind to for the agent's RPC server.
|
||||
By default this is "127.0.0.1:7373", allowing only loopback connections.
|
||||
The RPC address is used by other Serf commands, such as `serf members`,
|
||||
in order to query a running Serf agent. It is also used by other applications
|
||||
to control Serf using it's [RPC protocol](/docs/agent/rpc.html).
|
||||
* `-recursor` - This flag provides an address of an upstream DNS server that is used to
|
||||
recursively resolve queries if they are not inside the service domain for consul. For example,
|
||||
a node can use Consul directly as a DNS server, and if the record is outside of the "consul." domain,
|
||||
the query will be resolved upstream using this server.
|
||||
|
||||
* `-snapshot` - The snapshot flag provides a file path that is used to store
|
||||
recovery information, so when Serf restarts it is able to automatically
|
||||
re-join the cluster, and avoid replay of events it has already seen. The path
|
||||
must be read/writable by Serf, and the directory must allow Serf to create
|
||||
other files, so that it can periodically compact the snapshot file.
|
||||
* `-http-addr` - This flag controls the address the agent listens on for HTTP requests.
|
||||
By default it is bound to "127.0.0.1:8500". This port must allow for TCP traffic.
|
||||
|
||||
* `-tag` - The tag flag is used to associate a new key/value pair with the
|
||||
agent. The tags are gossiped and can be used to provide additional information
|
||||
such as roles, ports, and configuration values to other nodes. Multiple tags
|
||||
can be specified per agent. There is a byte size limit for the maximum number
|
||||
of tags, but in practice dozens of tags may be used. Tags can be changed during
|
||||
a config reload.
|
||||
* `-dns-addr` - This flag controls the address the agent listens on for DNS requests.
|
||||
By default it is bound to "127.0.0.1:8600". This port must allow for UDP and TCP traffic.
|
||||
|
||||
* `-server` - This flag is used to control if an agent is in server or client mode. When provided,
|
||||
an agent will act as a Consul server. Each Consul cluster must have at least one server, and ideally
|
||||
no more than 5 *per* datacenter. All servers participate in the Raft consensus algorithm, to ensure that
|
||||
transactions occur in a consistent, linearlizable manner. Transactions modify cluster state, which
|
||||
is maintained on all server nodes to ensure availability in the case of node failure. Server nodes also
|
||||
participate in a WAN gossip pool with server nodes in other datacenters. Servers act as gateways
|
||||
to other datacenters and forward traffic as appropriate.
|
||||
|
||||
* `-bootstrap` - This flag is used to control if a server is in "bootstrap" mode. It is important that
|
||||
no more than one server *per* datacenter be running in this mode. The initial server **must** be in bootstrap
|
||||
mode. Technically, a server in boostrap mode is allowed to self-elect as the Raft leader. It is important
|
||||
that only a single node is in this mode, because otherwise consistency cannot be guarenteed if multiple
|
||||
nodes are able to self-elect. Once there are multiple servers in a datacenter, it is generally a good idea
|
||||
to disable bootstrap mode on all of them.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
|
|
@ -144,65 +124,73 @@ The configuration files are JSON formatted, making them easily readable
|
|||
and editable by both humans and computers. The configuration is formatted
|
||||
at a single JSON object with configuration within it.
|
||||
|
||||
Configuration files are used for more than just setting up the agent,
|
||||
they are also used to provide check and service definitions. These are used
|
||||
to announce the availability of system servers to the rest of the cluster.
|
||||
They are documented seperately under [check configuration](#) and
|
||||
[service configuration](#) respectively.
|
||||
|
||||
#### Example Configuration File
|
||||
|
||||
<pre class="prettyprint lang-json">
|
||||
{
|
||||
"tags": {
|
||||
"role": "load-balancer",
|
||||
"datacenter": "east"
|
||||
},
|
||||
|
||||
"event_handlers": [
|
||||
"handle.sh",
|
||||
"user:deploy=deploy.sh"
|
||||
]
|
||||
"datacenter": "east-aws",
|
||||
"data_dir": "/opt/consul",
|
||||
"log_level": "INFO",
|
||||
"node_name": "foobar",
|
||||
"server": true
|
||||
}
|
||||
</pre>
|
||||
|
||||
#### Configuration Key Reference
|
||||
|
||||
* `node_name` - Equivalent to the `-node` command-line flag.
|
||||
* `bootstrap` - Equivalent to the `-bootstrap` command-line flag.
|
||||
|
||||
* `role` - **Deprecated**. Equivalent to the `-role` command-line flag.
|
||||
* `datacenter` - Equivalent to the `-dc` command-line flag.
|
||||
|
||||
* `tags` - This is a dictionary of tag values. It is the same as specifying
|
||||
the `tag` command-line flag once per tag.
|
||||
* `data_dir` - Equivalent to the `-data` command-line flag.
|
||||
|
||||
* `bind` - Equivalent to the `-bind` command-line flag.
|
||||
* `dns_addr` - Equivalent to the `-dns-addr` command-line flag.
|
||||
|
||||
* `advertise` - Equivalent to the `-advertise` command-line flag.
|
||||
* `recursor` - Equivalent to the `-recursor` command-line flag.
|
||||
|
||||
* `discover` - Equivalent to the `-discover` command-line flag.
|
||||
* `domain` - By default, Consul responds to DNS queries in the "consul." domain.
|
||||
This flag can be used to change that domain. All queries in this domain are assumed
|
||||
to be handled by Consul, and will not be recursively resolved.
|
||||
|
||||
* `encrypt_key` - Equivalent to the `-encrypt` command-line flag.
|
||||
* `encrypt` - Equivalent to the `-encrypt` command-line flag.
|
||||
|
||||
* `http_addr` - Equivalent to the `-http-addr` command-line flag.
|
||||
|
||||
* `log_level` - Equivalent to the `-log-level` command-line flag.
|
||||
|
||||
* `profile` - Equivalent to the `-profile` command-line flag.
|
||||
|
||||
* `protocol` - Equivalent to the `-protocol` command-line flag.
|
||||
* `node_name` - Equivalent to the `-node` command-line flag.
|
||||
|
||||
* `rpc_addr` - Equivalent to the `-rpc-addr` command-line flag.
|
||||
|
||||
* `event_handlers` - An array of strings specifying the event handlers.
|
||||
The format of the strings is equivalent to the format specified for
|
||||
the `-event-handler` command-line flag.
|
||||
* `serf_bind_addr` - Equivalent to the `-serf-bind` command-line flag.
|
||||
|
||||
* `start_join` - An array of strings specifying addresses of nodes to
|
||||
join upon startup.
|
||||
* `serf_lan_port` - This configures which port Serf listens on to communicate
|
||||
with nodes on the local LAN. By default this is 8301. All nodes in the datacenter
|
||||
should be able to reach this port over TCP and UDP.
|
||||
|
||||
* `replay_on_join` - Equivalent to the `-replay` command-line flag.
|
||||
* `serf_wan_port` - This configures which port Serf listens on to communicate
|
||||
with nodes on the remote WAN. By default this is 8302. All nodes in the WAN gossip
|
||||
pool should be able to reach this port over TCP and UDP. This only applies to
|
||||
agents running in server mode.
|
||||
|
||||
* `snapshot_path` - Equivalent to the `-snapshot` command-line flag.
|
||||
* `server_addr` - Equivalent to the `-server-addr` command-line flag.
|
||||
|
||||
* `advertise_addr` - Equivalent to the `-advertise` command-line flag.
|
||||
|
||||
* `server` - Equivalent to the `-server` command-line flag.
|
||||
|
||||
* `leave_on_terminate` - If enabled, when the agent receives a TERM signal,
|
||||
it will send a Leave message to the rest of the cluster and gracefully
|
||||
leave. Defaults to false.
|
||||
|
||||
* `skip_leave_on_interrupt` - This is the similar to`leave_on_terminate` but
|
||||
only affects interrupt handling. By default, an interrupt causes Serf to
|
||||
only affects interrupt handling. By default, an interrupt causes Consul to
|
||||
gracefully leave, but setting this to true disables that. Defaults to false.
|
||||
Interrupts are usually from a Control-C from a shell. (This was previously
|
||||
`leave_on_interrupt` but has since changed).
|
||||
Interrupts are usually from a Control-C from a shell.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,11 +6,11 @@ sidebar_current: "docs-agent-rpc"
|
|||
|
||||
# RPC Protocol
|
||||
|
||||
The Serf agent provides a complete RPC mechanism that can
|
||||
The Consul agent provides a complete RPC mechanism that can
|
||||
be used to control the agent programmatically. This RPC
|
||||
mechanism is the same one used by the CLI, but can be
|
||||
used by other applications to easily leverage the power
|
||||
of Serf without directly embedding. Additionally, it can
|
||||
of Consul without directly embedding. Additionally, it can
|
||||
be used as a fast IPC mechanism to allow applications to
|
||||
receive events immediately instead of using the fork/exec
|
||||
model of event handlers.
|
||||
|
|
@ -46,14 +46,13 @@ All responses may be accompanied by an error.
|
|||
Possible commands include:
|
||||
|
||||
* handshake - Used to initialize the connection, set the version
|
||||
* event - Fires a new user event
|
||||
* force-leave - Removes a failed node from the cluster
|
||||
* join - Requests Serf join another node
|
||||
* members - Returns the list of members
|
||||
* stream - Starts streaming events over the connection
|
||||
* join - Requests Consul join another node
|
||||
* members-lan - Returns the list of lan members
|
||||
* members-wan - Returns the list of wan members
|
||||
* monitor - Starts streaming logs over the connection
|
||||
* stop - Stops streaming logs or events
|
||||
* leave - Serf agent performs a graceful leave and shutdown
|
||||
* stop - Stops streaming logs
|
||||
* leave - Consul agent performs a graceful leave and shutdown
|
||||
|
||||
Below each command is documented along with any request or
|
||||
response body that is applicable.
|
||||
|
|
@ -76,20 +75,6 @@ in the future.
|
|||
There is no special response body, but the client should wait for the
|
||||
response and check for an error.
|
||||
|
||||
### event
|
||||
|
||||
The event command is used to fire a new user event. It takes the
|
||||
following request body:
|
||||
|
||||
```
|
||||
{"Name": "foo", "Payload": "test payload", "Coalesce": true}
|
||||
```
|
||||
|
||||
The `Name` is a string, but `Payload` is just opaque bytes. Coalesce
|
||||
is used to control if Serf should enable [event coalescing](/docs/commands/event.html).
|
||||
|
||||
There is no special response body.
|
||||
|
||||
### force-leave
|
||||
|
||||
This command is used to remove failed nodes from a cluster. It takes
|
||||
|
|
@ -107,12 +92,17 @@ This command is used to join an existing cluster using a known node.
|
|||
It takes the following body:
|
||||
|
||||
```
|
||||
{"Existing": ["192.168.0.1:6000", "192.168.0.2:6000"], "Replay": false}
|
||||
{"Existing": ["192.168.0.1:6000", "192.168.0.2:6000"], "WAN": false}
|
||||
```
|
||||
|
||||
The `Existing` nodes are each contacted, and `Replay` controls if we will replay
|
||||
old user events or if they will simply be ignored. The response body in addition
|
||||
to the header is returned. The body looks like:
|
||||
The `Existing` nodes are each contacted, and `WAN` controls if we are adding a
|
||||
WAN member or LAN member. LAN members are expected to be in the same datacenter,
|
||||
and should be accessible at relatively low latencies. WAN members are expected to
|
||||
be operating in different datacenters, with relatively high access latencies. It is
|
||||
important that only agents running in "server" mode are able to join nodes over the
|
||||
WAN.
|
||||
|
||||
The response body in addition to the header is returned. The body looks like:
|
||||
|
||||
```
|
||||
{"Num": 2}
|
||||
|
|
@ -120,10 +110,12 @@ to the header is returned. The body looks like:
|
|||
|
||||
The body returns the number of nodes successfully joined.
|
||||
|
||||
### members
|
||||
### members-lan
|
||||
|
||||
The members command is used to return all the known members and associated
|
||||
information. There is no request body, but the response looks like:
|
||||
The members-lan command is used to return all the known lan members and associated
|
||||
information. All agents will respond to this command.
|
||||
|
||||
There is no request body, but the response looks like:
|
||||
|
||||
```
|
||||
{"Members": [
|
||||
|
|
@ -146,77 +138,16 @@ information. There is no request body, but the response looks like:
|
|||
}
|
||||
```
|
||||
|
||||
### stream
|
||||
### members-wan
|
||||
|
||||
The stream command is used to subscribe to a stream of all events
|
||||
matching a given type filter. Events will continue to be sent until
|
||||
the stream is stopped. The request body looks like:
|
||||
The members-wan command is used to return all the known wan members and associated
|
||||
information. Only agents in server mode will respond to this command.
|
||||
|
||||
```
|
||||
{"Type": "member-join,user:deploy"}`
|
||||
```
|
||||
|
||||
The format of type is the same as the [event handler](/docs/agent/event-handlers.html),
|
||||
except no script is specified. The one exception is that `"*"` can be specified to
|
||||
subscribe to all events.
|
||||
|
||||
The server will respond with a standard response header indicating if the stream
|
||||
was successful. However, now as events occur they will be sent and tagged with
|
||||
the same `Seq` as the stream command that matches.
|
||||
|
||||
Assume we issued the previous stream command with Seq `50`,
|
||||
we may start getting messages like:
|
||||
|
||||
```
|
||||
{"Seq": 50, "Error": ""}
|
||||
{
|
||||
"Event": "user",
|
||||
"LTime": 123,
|
||||
"Name": "deploy",
|
||||
"Payload": "9c45b87",
|
||||
"Coalesce": true,
|
||||
}
|
||||
|
||||
{"Seq": 50, "Error": ""}
|
||||
{
|
||||
"Event": "member-join",
|
||||
"Members": [
|
||||
{
|
||||
"Name": "TestNode"
|
||||
"Addr": [127, 0, 0, 1],
|
||||
"Port": 5000,
|
||||
"Tags": {
|
||||
"role": "test"
|
||||
},
|
||||
"Status": "alive",
|
||||
"ProtocolMin": 0,
|
||||
"ProtocolMax": 3,
|
||||
"ProtocolCur": 2,
|
||||
"DelegateMin": 0,
|
||||
"DelegateMax": 1,
|
||||
"DelegateCur": 1,
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
It is important to realize that these messages are sent asyncronously,
|
||||
and not in response to any command. That means if a client is streaming
|
||||
commands, there may be events streamed while a client is waiting for a
|
||||
response to a command. This is why the `Seq` must be used to pair requests
|
||||
with their corresponding responses.
|
||||
|
||||
There is no limit to the number of concurrent streams a client can request,
|
||||
however a message is not deduplicated, so if multiple streams match a given
|
||||
event, it will be sent multiple times with the corresponding `Seq` number.
|
||||
|
||||
To stop streaming, the `stop` command is used.
|
||||
There is no request body, and the response is the same as `members-lan`
|
||||
|
||||
### monitor
|
||||
|
||||
The monitor command is similar to the stream command, but instead of
|
||||
events it subscribes the channel to log messages from the Agent.
|
||||
The monitor command subscribes the channel to log messages from the Agent.
|
||||
|
||||
The request is like:
|
||||
|
||||
|
|
@ -249,15 +180,14 @@ To stop streaming, the `stop` command is used.
|
|||
|
||||
### stop
|
||||
|
||||
The stop command is used to stop either a stream or monitor.
|
||||
The stop command is used to stop a monitor.
|
||||
The request looks like:
|
||||
|
||||
```
|
||||
{"Stop": 50}
|
||||
```
|
||||
|
||||
This unsubscribes the client from the monitor and/or stream registered
|
||||
with `Seq` value of 50.
|
||||
This unsubscribes the client from the monitor with `Seq` value of 50.
|
||||
|
||||
There is no special response body.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,35 +6,35 @@ sidebar_current: "docs-agent-telemetry"
|
|||
|
||||
# Telemetry
|
||||
|
||||
The Serf agent collects various metrics data at runtime about the performance
|
||||
The Consul agent collects various metrics data at runtime about the performance
|
||||
of different libraries and sub-systems. These metrics are aggregated on a ten second
|
||||
interval and are retained for one minute.
|
||||
|
||||
To view the telemetry information, you must send a `USR1` signal to the Serf
|
||||
To view the telemetry information, you must send a `USR1` signal to the Consul
|
||||
process. Windows users must use the `BREAK` signal instead.
|
||||
Once Serf receives the signal, it will dump the current telemetry
|
||||
Once Consul receives the signal, it will dump the current telemetry
|
||||
information to the stderr of the agent.
|
||||
|
||||
In general, the telemetry information is used for debugging or otherwise
|
||||
getting a better view into what Serf is doing.
|
||||
getting a better view into what Consul is doing.
|
||||
|
||||
Below is an example output:
|
||||
|
||||
```
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.num_goroutines': 19.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.alloc_bytes': 755960.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.malloc_count': 7550.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.free_count': 4387.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.heap_objects': 3163.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.total_gc_pause_ns': 1151002.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.total_gc_runs': 4.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.agent.ipc.accept': Count: 5 Sum: 5.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.agent.ipc.command': Count: 10 Sum: 10.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events': Count: 5 Sum: 5.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events.foo': Count: 4 Sum: 4.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events.baz': Count: 1 Sum: 1.000
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.memberlist.gossip': Count: 50 Min: 0.007 Mean: 0.020 Max: 0.041 Stddev: 0.007 Sum: 0.989
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.serf.queue.Intent': Count: 10 Sum: 0.000
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.serf.queue.Event': Count: 10 Min: 0.000 Mean: 2.500 Max: 5.000 Stddev: 2.121 Sum: 25.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.num_goroutines': 19.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.alloc_bytes': 755960.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.malloc_count': 7550.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.free_count': 4387.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.heap_objects': 3163.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.total_gc_pause_ns': 1151002.000
|
||||
[2014-01-29 10:56:50 -0800 PST][G] 'consul-agent.runtime.total_gc_runs': 4.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.agent.ipc.accept': Count: 5 Sum: 5.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.agent.ipc.command': Count: 10 Sum: 10.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events': Count: 5 Sum: 5.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events.foo': Count: 4 Sum: 4.000
|
||||
[2014-01-29 10:56:50 -0800 PST][C] 'consul-agent.serf.events.baz': Count: 1 Sum: 1.000
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.memberlist.gossip': Count: 50 Min: 0.007 Mean: 0.020 Max: 0.041 Stddev: 0.007 Sum: 0.989
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.serf.queue.Intent': Count: 10 Sum: 0.000
|
||||
[2014-01-29 10:56:50 -0800 PST][S] 'consul-agent.serf.queue.Event': Count: 10 Min: 0.000 Mean: 2.500 Max: 5.000 Stddev: 2.121 Sum: 25.000
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@ page_title: "Documentation"
|
|||
sidebar_current: "docs-home"
|
||||
---
|
||||
|
||||
# Serf Documentation
|
||||
# Consul Documentation
|
||||
|
||||
Welcome to the Serf documentation! This documentation is more of a reference
|
||||
guide for all available features and options of Serf. If you're just getting
|
||||
started with Serf, please start with the
|
||||
Welcome to the Consul documentation! This documentation is more of a reference
|
||||
guide for all available features and options of Consul. If you're just getting
|
||||
started with Consul, please start with the
|
||||
[introduction and getting started guide](/intro/index.html) instead.
|
||||
|
|
|
|||
Loading…
Reference in New Issue