diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index 98399cca4..6a8e96b65 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/website/source/docs/agent/options.html.markdown @@ -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 +## 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,