Merge pull request #700 from ryanbreen/options
Website: cleanup for the docs/agent/options Command-line options section
This commit is contained in:
Armon Dadgar
commit
93fce93750
|
|
@ -3,24 +3,26 @@ layout: "docs"
|
|||
page_title: "Configuration"
|
||||
sidebar_current: "docs-agent-config"
|
||||
description: |-
|
||||
The agent has various configuration options that can be specified via the command-line or via configuration files. All of the configuration options are completely optional and their defaults will be specified with their descriptions.
|
||||
The agent has various configuration options that can be specified via the command-line or via configuration files. All of the configuration options are completely optional. Defaults are specified with their descriptions.
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
The agent has various configuration options that can be specified via
|
||||
the command-line or via configuration files. All of the configuration
|
||||
options are completely optional and their defaults will be specified
|
||||
with their descriptions.
|
||||
options are completely optional. Defaults are specified with their
|
||||
descriptions.
|
||||
|
||||
When loading configuration, Consul loads the configuration from files
|
||||
and directories in the order specified. Configuration specified later
|
||||
and directories in lexical order. For example, configuration file `basic_config.json`
|
||||
will be processed before `extra_config.js`. 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.
|
||||
"merge" means that the later version will override the earlier. In
|
||||
some cases, such as event handlers, merging appends the handlers to the
|
||||
existing configuration. The exact merging behavior is specified for each
|
||||
option below.
|
||||
|
||||
Consul also supports reloading of configuration when it receives the
|
||||
Consul also supports reloading configuration when it receives the
|
||||
SIGHUP signal. Not all changes are respected, but those that are
|
||||
are documented below in the
|
||||
[Reloadable Configuration](#reloadable-configuration) section. The
|
||||
|
|
@ -34,64 +36,64 @@ The options below are all specified on the command-line.
|
|||
* `-advertise` - The advertise address is used to change the address that we
|
||||
advertise to other nodes in the cluster. By default, the `-bind` address is
|
||||
advertised. However, in some cases, 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 will be in a constant flapping state,
|
||||
be bound. This flag enables gossiping a different address to support this.
|
||||
If this address is not routable, the node will be in a constant flapping state
|
||||
as other nodes will treat the non-routability as a failure.
|
||||
|
||||
* `-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. Technically, a server in bootstrap 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 guaranteed if multiple nodes are able to self-elect.
|
||||
no more than one server *per* data center be running in this mode. Technically, a server in bootstrap mode
|
||||
is allowed to self-elect as the Raft leader. It is important that only a single node is in this mode;
|
||||
otherwise, consistency cannot be guaranteed as multiple nodes are able to self-elect.
|
||||
It is not recommended to use this flag after a cluster has been bootstrapped.
|
||||
|
||||
* `-bootstrap-expect` - This flag provides the number of expected servers in the datacenter.
|
||||
Either this value should not be provided, or the value must agree with other servers in
|
||||
* `-bootstrap-expect` - This flag provides the number of expected servers in the data center.
|
||||
Either this value should not be provided or the value must agree with other servers in
|
||||
the cluster. When provided, Consul waits until the specified number of servers are
|
||||
available, and then bootstraps the cluster. This allows an initial leader to be elected
|
||||
available and then bootstraps the cluster. This allows an initial leader to be elected
|
||||
automatically. This cannot be used in conjunction with the `-bootstrap` flag.
|
||||
|
||||
* `-bind` - The address that should be bound to for internal cluster communications.
|
||||
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.
|
||||
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 the same port for both. If you
|
||||
have any firewalls, be sure to allow both protocols.
|
||||
|
||||
* `-client` - The address that Consul will bind to client interfaces. This
|
||||
includes the HTTP, DNS, and RPC servers. By default this is "127.0.0.1"
|
||||
* `-client` - The address to which Consul will bind client interfaces,
|
||||
including the HTTP, DNS, and RPC servers. By default, this is "127.0.0.1",
|
||||
allowing only loopback connections. The RPC address is used by other Consul
|
||||
commands, such as `consul members`, in order to query a running Consul agent.
|
||||
|
||||
* `-config-file` - A configuration file to load. For more information on
|
||||
the format of this file, read the "Configuration Files" section below.
|
||||
the format of this file, read the [Configuration Files](#configuration_files) section.
|
||||
This option can be specified multiple times to load multiple configuration
|
||||
files. If it is specified multiple times, configuration files loaded later
|
||||
will merge with configuration files loaded earlier. During a config merge,
|
||||
single-value keys (string, int, bool) will simply have their values replaced,
|
||||
single-value keys (string, int, bool) will simply have their values replaced
|
||||
while list types will be appended together.
|
||||
|
||||
* `-config-dir` - A directory of configuration files to load. Consul will
|
||||
load all files in this directory ending in ".json" as configuration files
|
||||
in alphabetical order using the same merge routine as the `config-file`
|
||||
load all files in this directory with the suffix ".json". The load order
|
||||
is alphabetical, and the the same merge routine is used as with the `config-file`
|
||||
option above. For more information on the format of the configuration files,
|
||||
see the "Configuration Files" section below.
|
||||
see the [Configuration Files](#configuration_files) section.
|
||||
|
||||
* `-data-dir` - 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. Additional, the directory must support
|
||||
This is especially critical for agents that are running in server mode as they
|
||||
must be able to persist cluster state. Additionally, the directory must support
|
||||
the use of filesystem locking, meaning some types of mounted folders (e.g. VirtualBox
|
||||
shared folders) may not be suitable.
|
||||
|
||||
* `-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
|
||||
* `-dc` - This flag controls the data center in which the agent is running. 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 data center should be on a single
|
||||
LAN.
|
||||
|
||||
* `-encrypt` - Specifies the secret key to use for encryption of Consul
|
||||
network traffic. This key must be 16-bytes that are base64 encoded. The
|
||||
network traffic. This key must be 16-bytes that are Base64-encoded. The
|
||||
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.
|
||||
The provided key is automatically persisted to the data directory, and loaded
|
||||
The provided key is automatically persisted to the data directory and loaded
|
||||
automatically whenever the agent is restarted. This means that to encrypt
|
||||
Consul's gossip protocol, this option only needs to be provided once on each
|
||||
agent's initial startup sequence. If it is provided after Consul has been
|
||||
|
|
@ -103,37 +105,36 @@ The options below are all specified on the command-line.
|
|||
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.
|
||||
|
||||
* `-retry-join` - Similar to `-join`, but allows retrying a join if the first
|
||||
* `-retry-join` - Similar to `-join` but allows retrying a join if the first
|
||||
attempt fails. This is useful for cases where we know the address will become
|
||||
available eventually.
|
||||
|
||||
* `-retry-interval` - Time to wait between join attempts. Defaults to 30s.
|
||||
|
||||
* `-retry-max` - The maximum number of join attempts to be made before exiting
|
||||
with return code 1. By default, this is set to 0, which will continue to
|
||||
retry the join indefinitely.
|
||||
with return code 1. By default, this is set to 0 which is interpreted as infinite
|
||||
retries.
|
||||
|
||||
* `-join-wan` - Address of another wan agent to join upon starting up. This can be
|
||||
specified multiple times to specify multiple agents that are on the WAN to join. If Consul is
|
||||
specified multiple times to specify multiple WAN agents to join. If Consul is
|
||||
unable to join with any of the specified addresses, agent startup will
|
||||
fail. By default, the agent won't join -wan any nodes when it starts up.
|
||||
fail. By default, the agent won't `-join-wan` any nodes when it starts up.
|
||||
|
||||
* `-retry-join-wan` - Similar to `retry-join`, but allows retrying a wan join if the first
|
||||
* `-retry-join-wan` - Similar to `retry-join` but allows retrying a wan join if the first
|
||||
attempt fails. This is useful for cases where we know the address will become
|
||||
available eventually.
|
||||
|
||||
* `-retry-interval-wan` - Time to wait between join -wan attempts. Defaults to 30s.
|
||||
* `-retry-interval-wan` - Time to wait between `-join-wan` attempts. Defaults to 30s.
|
||||
|
||||
* `-retry-max-wan` - The maximum number of join -wan attempts to be made before exiting
|
||||
with return code 1. By default, this is set to 0, which will continue to
|
||||
retry the join -wan indefinitely.
|
||||
* `-retry-max-wan` - The maximum number of `-join-wan` attempts to be made before exiting
|
||||
with return code 1. By default, this is set to 0 which is interpreted as infinite
|
||||
retries.
|
||||
|
||||
* `-log-level` - The level of logging to show after the Consul 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
|
||||
for the agent output, but note you can always connect via `consul monitor`
|
||||
to an agent at any log level. The log level can be changed during a
|
||||
config reload.
|
||||
"debug", "info", "warn", and "err". Note that you can always connect to an
|
||||
agent via `consul monitor` and use any log level. Also, the log level can
|
||||
be changed during a config reload.
|
||||
|
||||
* `-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.
|
||||
|
|
@ -142,29 +143,29 @@ The options below are all specified on the command-line.
|
|||
version. This should be set only when [upgrading](/docs/upgrading.html).
|
||||
You can view the protocol versions supported by Consul by running `consul -v`.
|
||||
|
||||
* `-rejoin` - When provided Consul will ignore a previous leave and attempt to
|
||||
* `-rejoin` - When provided, Consul will ignore a previous leave and attempt to
|
||||
rejoin the cluster when starting. By default, Consul treats leave as a permanent
|
||||
intent, and does not attempt to join the cluster again when starting. This flag
|
||||
intent and does not attempt to join the cluster again when starting. This flag
|
||||
allows the previous state to be used to rejoin the cluster.
|
||||
|
||||
* `-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
|
||||
an agent will act as a Consul server. Each Consul cluster must have at least one server and ideally
|
||||
no more than 5 per data center. All servers participate in the Raft consensus algorithm to ensure that
|
||||
transactions occur in a consistent, linearizable 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.
|
||||
participate in a WAN gossip pool with server nodes in other data centers. Servers act as gateways
|
||||
to other data centers and forward traffic as appropriate.
|
||||
|
||||
* `-syslog` - This flag enables logging to syslog. This is only supported on Linux
|
||||
and OSX. It will result in an error if provided on Windows.
|
||||
|
||||
* `-ui-dir` - This flag provides a the directory containing the Web UI resources
|
||||
for Consul. This must be provided to enable the Web UI. Directory must be readable.
|
||||
* `-ui-dir` - This flag provides the directory containing the Web UI resources
|
||||
for Consul. This must be provided to enable the Web UI. The directory must be readable.
|
||||
|
||||
* `-pid-file` - This flag provides the file path for the agent to store it's PID. This is useful for
|
||||
sending signals to the agent, such as `SIGINT` to close it or `SIGHUP` to update check definitions.
|
||||
* `-pid-file` - This flag provides the file path for the agent to store its PID. This is useful for
|
||||
sending signals (for example, `SIGINT` to close the agent or `SIGHUP` to update check definitions) to the agent.
|
||||
|
||||
## Configuration Files
|
||||
## <a name="configuration_files"></a> Configuration Files
|
||||
|
||||
In addition to the command-line options, configuration can be put into
|
||||
files. This may be easier in certain situations, for example when Consul is
|
||||
|
|
@ -201,9 +202,9 @@ definitions support being updated during a reload.
|
|||
|
||||
#### Configuration Key Reference
|
||||
|
||||
* `acl_datacenter` - Only used by servers. This designates the datacenter which
|
||||
* `acl_datacenter` - Only used by servers. This designates the data center which
|
||||
is authoritative for ACL information. It must be provided to enable ACLs.
|
||||
All servers and datacenters must agree on the ACL datacenter. Setting it on
|
||||
All servers and data centers must agree on the ACL data center. Setting it on
|
||||
the servers is all you need for enforcement, but for the APIs to work on the
|
||||
clients, it must be set on them too (to forward properly). Also, if we want
|
||||
to enhance the ACL support for other features like service discovery,
|
||||
|
|
|
|||
Loading…
Reference in New Issue