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

Website: cleanup for the docs/agent/options Command-line options section.

This commit is contained in:
Ryan Breen 2015-02-13 14:58:05 -05:00
parent 907bbfa8c9
commit 96c4aecc17
1 changed files with 66 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
website/source/docs/agent/options.html.markdown
View File

@ -3,24 +3,26 @@ layout: "docs"
page_title: "Configuration" page_title: "Configuration"
sidebar_current: "docs-agent-config" sidebar_current: "docs-agent-config"
description: |- 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 # Configuration
The agent has various configuration options that can be specified via The agent has various configuration options that can be specified via
the command-line or via configuration files. All of the configuration the command-line or via configuration files. All of the configuration
options are completely optional and their defaults will be specified options are completely optional. Defaults are specified with their
with their descriptions. descriptions.
When loading configuration, Consul loads the configuration from files 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, will be merged into configuration specified earlier. In most cases,
"merge" means that the later version will override the earlier. But in "merge" means that the later version will override the earlier. In
some cases, such as event handlers, merging just appends the handlers. some cases, such as event handlers, merging appends the handlers to the
The exact merging behavior will be specified. 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 SIGHUP signal. Not all changes are respected, but those that are
are documented below in the are documented below in the
[Reloadable Configuration](#reloadable-configuration) section. 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` - The advertise address 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 `-bind` address is
advertised. However, in some cases, there may be a routable address that cannot 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. 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, 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. 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 * `-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 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, 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. 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. 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. * `-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 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 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. automatically. This cannot be used in conjunction with the `-bootstrap` flag.
* `-bind` - The address that should be bound to for internal cluster communications. * `-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. 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 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 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. have any firewalls, be sure to allow both protocols.
* `-client` - The address that Consul will bind to client interfaces. This * `-client` - The address to which Consul will bind client interfaces,
includes the HTTP, DNS, and RPC servers. By default this is "127.0.0.1" 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 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. commands, such as `consul members`, in order to query a running Consul agent.
* `-config-file` - A configuration file to load. For more information on * `-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 This option can be specified multiple times to load multiple configuration
files. If it is specified multiple times, configuration files loaded later files. If it is specified multiple times, configuration files loaded later
will merge with configuration files loaded earlier. During a config merge, 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. while list types will be appended together.
* `-config-dir` - A directory of configuration files to load. Consul will * `-config-dir` - A directory of configuration files to load. Consul will
load all files in this directory ending in ".json" as configuration files load all files in this directory with the suffix ".json". The load order
in alphabetical order using the same merge routine as the `config-file` is alphabetical order, 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, 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. * `-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 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 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 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 the use of filesystem locking, meaning some types of mounted folders (e.g. VirtualBox
shared folders) may not be suitable. shared folders) may not be suitable.
* `-dc` - This flag controls the datacenter the agent is running in. If not provided * `-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 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 it relies on proper configuration. Nodes in the same data center should be on a single
LAN. LAN.
* `-encrypt` - Specifies the secret key to use for encryption of Consul * `-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 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. 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 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 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 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 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. 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 attempt fails. This is useful for cases where we know the address will become
available eventually. available eventually.
* `-retry-interval` - Time to wait between join attempts. Defaults to 30s. * `-retry-interval` - Time to wait between join attempts. Defaults to 30s.
* `-retry-max` - The maximum number of join attempts to be made before exiting * `-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 with return code 1. By default, this is set to 0 which is interpreted as infinite
retry the join indefinitely. retries.
* `-join-wan` - Address of another wan agent to join upon starting up. This can be * `-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 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 attempt fails. This is useful for cases where we know the address will become
available eventually. 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 * `-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 with return code 1. By default, this is set to 0 which is interpreted as infinite
retry the join -wan indefinitely. retries.
* `-log-level` - The level of logging to show after the Consul agent has * `-log-level` - The level of logging to show after the Consul agent has
started. This defaults to "info". The available log levels are "trace", started. This defaults to "info". The available log levels are "trace",
"debug", "info", "warn", "err". This is the log level that will be shown "debug", "info", "warn", and "err". Note that you can always connect to an
for the agent output, but note you can always connect via `consul monitor` agent via `consul monitor` and use any log level. Also, the log level can
to an agent at any log level. The log level can be changed during a be changed during a config reload.
config reload.
* `-node` - The name of this node in the cluster. This must be unique within * `-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. 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). version. This should be set only when [upgrading](/docs/upgrading.html).
You can view the protocol versions supported by Consul by running `consul -v`. 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 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. 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, * `-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 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 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 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 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 participate in a WAN gossip pool with server nodes in other data centers. Servers act as gateways
to other datacenters and forward traffic as appropriate. to other data centers and forward traffic as appropriate.
* `-syslog` - This flag enables logging to syslog. This is only supported on Linux * `-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. 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 * `-ui-dir` - This flag provides the directory containing the Web UI resources
for Consul. This must be provided to enable the Web UI. Directory must be readable. 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 * `-pid-file` - This flag provides the file path for the agent to store its PID. This is useful for
sending signals to the agent, such as `SIGINT` to close it or `SIGHUP` to update check definitions. 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 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 files. This may be easier in certain situations, for example when Consul is
@ -185,7 +186,7 @@ definitions support being updated during a reload.
```javascript ```javascript
{ {
"datacenter": "east-aws", "data center": "east-aws",
"data_dir": "/opt/consul", "data_dir": "/opt/consul",
"log_level": "INFO", "log_level": "INFO",
"node_name": "foobar", "node_name": "foobar",
@ -201,14 +202,14 @@ definitions support being updated during a reload.
#### Configuration Key Reference #### Configuration Key Reference
* `acl_datacenter` - Only used by servers. This designates the datacenter which * `acl_data center` - Only used by servers. This designates the data center which
is authoritative for ACL information. It must be provided to enable ACLs. 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 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 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, to enhance the ACL support for other features like service discovery,
enforcement might move to the edges, so it's best to just set the enforcement might move to the edges, so it's best to just set the
`acl_datacenter` on all the nodes. `acl_data center` on all the nodes.
* `acl_default_policy` - Either "allow" or "deny", defaults to "allow". The * `acl_default_policy` - Either "allow" or "deny", defaults to "allow". The
default policy controls the behavior of a token when there is no matching default policy controls the behavior of a token when there is no matching
@ -218,12 +219,12 @@ definitions support being updated during a reload.
* `acl_down_policy` - Either "allow", "deny" or "extend-cache" which is the * `acl_down_policy` - Either "allow", "deny" or "extend-cache" which is the
default. In the case that the policy for a token cannot be read from the default. In the case that the policy for a token cannot be read from the
`acl_datacenter` or leader node, the down policy is applied. In "allow" mode, `acl_data center` or leader node, the down policy is applied. In "allow" mode,
all actions are permitted, "deny" restricts all operations, and "extend-cache" all actions are permitted, "deny" restricts all operations, and "extend-cache"
allows any cached ACLs to be used, ignoring their TTL values. If a non-cached allows any cached ACLs to be used, ignoring their TTL values. If a non-cached
ACL is used, "extend-cache" acts like "deny". ACL is used, "extend-cache" acts like "deny".
* `acl_master_token` - Only used for servers in the `acl_datacenter`. This token * `acl_master_token` - Only used for servers in the `acl_data center`. This token
will be created if it does not exist with management level permissions. It allows will be created if it does not exist with management level permissions. It allows
operators to bootstrap the ACL system with a token ID that is well-known. operators to bootstrap the ACL system with a token ID that is well-known.
@ -285,7 +286,7 @@ definitions support being updated during a reload.
* `client_addr` - Equivalent to the `-client` command-line flag. * `client_addr` - Equivalent to the `-client` command-line flag.
* `datacenter` - Equivalent to the `-dc` command-line flag. * `data center` - Equivalent to the `-dc` command-line flag.
* `data_dir` - Equivalent to the `-data-dir` command-line flag. * `data_dir` - Equivalent to the `-data-dir` command-line flag.