github.com/kardianos/nomad@v0.1.3-0.20151022182107-b13df73ee850/website/source/docs/agent/config.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Configuration" 4 sidebar_current: "docs-agent-config" 5 description: |- 6 Learn about the configuration options available for the Nomad agent. 7 --- 8 9 # Configuration 10 11 Nomad agents are highly configurable and expose many configuration options 12 through the use of config files. Config files are written in 13 [HCL](https://github.com/hashicorp/hcl) or JSON syntax. Multiple configuration 14 files or directories of configuration files may be used jointly to configure the 15 Nomad agent. 16 17 When loading configuration files and directories, the Nomad agent parses each 18 file in lexical order. As each file is processed, its contents are merged into 19 the existing configuration, enabling a layered, additive configuration 20 mechanism. During a merge, configuration values are copied from 21 the next configuration file in the set if they have a non-empty value. An 22 empty value means `""` for strings, `0` for integer or float values, and 23 `false` for booleans. More complex data types like arrays or maps are usually 24 appended together. Any exceptions to these rules are documented alongside the 25 configuration options below. 26 27 A subset of the configuration options can also be specified using the 28 command-line interface. See the [CLI Options](#cli) section for further details. 29 30 Nomad's configuration is broken down into logical groupings. Because of the high 31 number of configuration options available, this page is also broken into 32 sections for easier reading. 33 34 ## General Options 35 36 The following configuration options are available to both client and server 37 nodes, unless otherwise specified: 38 39 * <a id="region">`region`</a>: Specifies the region the Nomad agent is a 40 member of. A region typically maps to a geographic region, for example `us`, 41 with potentially multiple zones, which map to [datacenters](#datacenter) such 42 as `us-west` and `us-east`. Defaults to `global`. 43 44 * `datacenter`: Datacenter of the local agent. All members of a datacenter 45 should all share a local LAN connection. Defaults to `dc1`. 46 47 * <a id="name">`name`</a>: The name of the local node. This value is used to 48 identify individual nodes in a given datacenter and must be unique 49 per-datacenter. By default this is set to the local host's name. 50 51 * `data_dir`: A local directory used to store agent state. Client nodes use this 52 directory by default to store temporary allocation data as well as cluster 53 information. Server nodes use this directory to store cluster state, including 54 the replicated log and snapshot data. This option is required to start the 55 Nomad agent. 56 57 * `log_level`: Controls the verbosity of logs the Nomad agent will output. Valid 58 log levels include `WARN`, `INFO`, or `DEBUG` in increasing order of 59 verbosity. Defaults to `INFO`. 60 61 * <a id="bind_addr">`bind_addr`</a>: Used to indicate which address the Nomad 62 agent should bind to for network services, including the HTTP interface as 63 well as the internal gossip protocol and RPC mechanism. This should be 64 specified in IP format, and can be used to easily bind all network services to 65 the same address. It is also possible to bind the individual services to 66 different addresses using the [addresses](#addresses) configuration option. 67 Defaults to the local loopback address `127.0.0.1`. 68 69 * `enable_debug`: Enables the debugging HTTP endpoints. These endpoints can be 70 used with profiling tools to dump diagnostic information about Nomad's 71 internals. It is not recommended to leave this enabled in production 72 environments. Defaults to `false`. 73 74 * `ports`: Controls the network ports used for different services required by 75 the Nomad agent. The value is a key/value mapping of port numbers, and accepts 76 the following keys: 77 <br> 78 * `http`: The port used to run the HTTP server. Applies to both client and 79 server nodes. Defaults to `4646`. 80 * `rpc`: The port used for internal RPC communication between agents and 81 servers, and for inter-server traffic for the consensus algorithm (raft). 82 Defaults to `4647`. Only used on server nodes. 83 * `serf`: The port used for the gossip protocol for cluster membership. Both 84 TCP and UDP should be routable between the server nodes on this port. 85 Defaults to `4648`. Only used on server nodes. 86 87 * <a id="addresses">`addresses`</a>: Controls the bind address for individual 88 network services. Any values configured in this block take precedence over the 89 default [bind_addr](#bind_addr). The value is a map of IP addresses and 90 supports the following keys: 91 <br> 92 * `http`: The address the HTTP server is bound to. This is the most common 93 bind address to change. Applies to both clients and servers. 94 * `rpc`: The address to bind the internal RPC interfaces to. Should be exposed 95 only to other cluster members if possible. Used only on server nodes, but 96 must be accessible from all agents. 97 * `serf`: The address used to bind the gossip layer to. Both a TCP and UDP 98 listener will be exposed on this address. Should be restricted to only 99 server nodes from the same datacenter if possible. Used only on server 100 nodes. 101 102 * `advertise`: Controls the advertise address for individual network services. 103 This can be used to advertise a different address to the peers of a server 104 node to support more complex network configurations such as NAT. This 105 configuration is optional, and defaults to the bind address of the specific 106 network service if it is not provided. This configuration is only appicable 107 on server nodes. The value is a map of IP addresses and supports the 108 following keys: 109 <br> 110 * `rpc`: The address to advertise for the RPC interface. This address should 111 be reachable by all of the agents in the cluster. 112 * `serf`: The address advertised for the gossip layer. This address must be 113 reachable from all server nodes. It is not required that clients can reach 114 this address. 115 116 * `telemetry`: Used to control how the Nomad agent exposes telemetry data to 117 external metrics collection servers. This is a key/value mapping and supports 118 the following keys: 119 <br> 120 * `statsite_address`: Address of a 121 [statsite](https://github.com/armon/statsite) server to forward metrics data 122 to. 123 * `statsd_address`: Address of a [statsd](https://github.com/etsy/statsd) 124 server to forward metrics to. 125 * `disable_hostname`: A boolean indicating if gauge values should not be 126 prefixed with the local hostname. 127 128 * `leave_on_interrupt`: Enables gracefully leave when receiving the 129 interrupt signal. By default, the agent will exit forcefully on any signal. 130 131 * `leave_on_terminate`: Enables gracefully leave when receiving the 132 terminate signal. By default, the agent will exit forcefully on any signal. 133 134 * `enable_syslog`: Enables logging to syslog. This option only work on 135 Unix based systems. 136 137 * `syslog_facility`: Controls the syslog facility that is used. By default, 138 `LOCAL0` will be used. This should be used with `enable_syslog`. 139 140 * `disable_update_check`: Disables automatic checking for security bulletins 141 and new version releases. 142 143 * `disable_anonymous_signature`: Disables providing an anonymous signature 144 for de-duplication with the update check. See `disable_update_check`. 145 146 ## Server-specific Options 147 148 The following options are applicable to server agents only and need not be 149 configured on client nodes. 150 151 * `server`: This is the top-level key used to define the Nomad server 152 configuration. It is a key/value mapping which supports the following keys: 153 <br> 154 * `enabled`: A boolean indicating if server mode should be enabled for the 155 local agent. All other server options depend on this value being set. 156 Defaults to `false`. 157 * <a id="bootstrap_expect">`bootstrap_expect`</a>: This is an integer 158 representing the number of server nodes to wait for before bootstrapping. It 159 is most common to use the odd-numbered integers `3` or `5` for this value, 160 depending on the cluster size. A value of `1` does not provide any fault 161 tolerance and is not recommended for production use cases. 162 * `data_dir`: This is the data directory used for server-specific data, 163 including the replicated log. By default, this directory lives inside of the 164 [data_dir](#data_dir) in the "server" sub-path. 165 * `protocol_version`: The Nomad protocol version spoken when communicating 166 with other Nomad servers. This value is typically not required as the agent 167 internally knows the latest version, but may be useful in some upgrade 168 scenarios. 169 * `num_schedulers`: The number of parallel scheduler threads to run. This 170 can be as many as one per core, or `0` to disallow this server from making 171 any scheduling decisions. This defaults to the number of CPU cores. 172 * `enabled_schedulers`: This is an array of strings indicating which 173 sub-schedulers this server will handle. This can be used to restrict the 174 evaluations that worker threads will dequeue for processing. This 175 defaults to all available schedulers. 176 177 ## Client-specific Options 178 179 The following options are applicable to client agents only and need not be 180 configured on server nodes. 181 182 * `client`: This is the top-level key used to define the Nomad client 183 configuration. Like the server configuration, it is a key/value mapping which 184 supports the following keys: 185 <br> 186 * `enabled`: A boolean indicating if client mode is enabled. All other client 187 configuration options depend on this value. Defaults to `false`. 188 * <a id="state_dir">`state_dir`</a>: This is the state dir used to store 189 client state. By default, it lives inside of the [data_dir](#data_dir), in 190 the "client" sub-path. 191 * <a id="alloc_dir">`alloc_dir`</a>: A directory used to store allocation data. 192 Depending on the workload, the size of this directory can grow arbitrarily 193 large as it is used to store downloaded artifacts for drivers (QEMU images, 194 JAR files, etc.). It is therefore important to ensure this directory is 195 placed some place on the filesystem with adequate storage capacity. By 196 default, this directory lives under the [data_dir](#data_dir) at the 197 "alloc" sub-path. 198 * <a id="servers">`servers`</a>: An array of server addresses. This list is 199 used to register the client with the server nodes and advertise the 200 available resources so that the agent can receive work. 201 * <a id="node_id">`node_id`</a>: This is the value used to uniquely identify 202 the local agent's node registration with the servers. This can be any 203 arbitrary string but must be unique to the cluster. By default, if not 204 specified, a randomly- generate UUID will be used. 205 * <a id="node_class">`node_class`</a>: A string used to logically group client 206 nodes by class. This can be used during job placement as a filter. This 207 option is not required and has no default. 208 * <a id="meta">`meta`</a>: This is a key/value mapping of metadata pairs. This 209 is a free-form map and can contain any string values. 210 * <a id="options">`options`</a>: This is a key/value mapping of internal 211 configuration for clients, such as for driver configuration. 212 * <a id="network_interface">`network_interface`</a>: This is a string to force 213 network fingerprinting to use a specific network interface 214 * <a id="network_speed">`network_speed`</a>: This is an int that sets the 215 default link speed of network interfaces, in megabytes, if their speed can 216 not be determined dynamically. 217 218 ## Atlas Options 219 220 The following options are used to configure [Atlas](https://atlas.hashicorp.com) 221 integration and are entirely optional. 222 223 * `atlas`: The top-level config key used to contain all Atlas-related 224 configuration options. The value is a key/value map which supports the 225 following keys: 226 <br> 227 * <a id="infrastructure">`infrastructure`</a>: The Atlas infrastructure name to 228 connect this agent to. This value should be of the form 229 `<org>/<infrastructure>`, and requires a valid [token](#token) authorized on 230 the infrastructure. 231 * <a id="token">`token`</a>: The Atlas token to use for authentication. This 232 token should have access to the provided [infrastructure](#infrastructure). 233 * <a id="join">`join`</a>: A boolean indicating if the auto-join feature of 234 Atlas should be enabled. Defaults to `false`. 235 * `endpoint`: The address of the Atlas instance to connect to. Defaults to the 236 public Atlas endpoint and is only used if both 237 [infrastructure](#infrastructure) and [token](#token) are provided. 238 239 ## Command-line Options <a id="cli"></a> 240 241 A subset of the available Nomad agent configuration can optionally be passed in 242 via CLI arguments. The `agent` command accepts the following arguments: 243 244 * `alloc-dir=<path>`: Equivalent to the Client [alloc_dir](#alloc_dir) config 245 option. 246 * `-atlas=<infrastructure>`: Equivalent to the Atlas 247 [infrastructure](#infrastructure) config option. 248 * `-atlas-join`: Equivalent to the Atlas [join](#join) config option. 249 * `-atlas-token=<token>`: Equivalent to the Atlas [token](#token) config option. 250 * `-bind=<address>`: Equivalent to the [bind_addr](#bind_addr) config option. 251 * `-bootstrap-expect=<num>`: Equivalent to the 252 [bootstrap_expect](#bootstrap_expect) config option. 253 * `-client`: Enable client mode on the local agent. 254 * `-config=<path>`: Specifies the path to a configuration file or a directory of 255 configuration files to load. Can be specified multiple times. 256 * `-data-dir=<path>`: Equivalent to the [data_dir](#data_dir) config option. 257 * `-dc=<datacenter>`: Equivalent to the [datacenter](#datacenter) config option. 258 * `-dev`: Start the agent in development mode. This enables a pre-configured 259 dual-role agent (client + server) which is useful for developing or testing 260 Nomad. No other configuration is required to start the agent in this mode. 261 * `-log-level=<level>`: Equivalent to the [log_level](#log_level) config option. 262 * `-meta=<key=value>`: Equivalent to the Client [meta](#meta) config option. 263 * `-network-interface<interface>`: Equivalent to the Client 264 [network_interface](#network_interface) config option. 265 * `-network-speed<MBits>`: Equivalent to the Client 266 [network_speed](#network_speed) config option. 267 * `-node=<name>`: Equivalent to the [name](#name) config option. 268 * `-node-class=<class>`: Equivalent to the Client [node_class](#node_class) 269 config option. 270 * `-node-id=<uuid>`: Equivalent to the Client [node_id](#node_id) config option. 271 * `-region=<region>`: Equivalent to the [region](#region) config option. 272 * `-server`: Enable server mode on the local agent. 273 * `-servers=<host:port>`: Equivalent to the Client [servers](#servers) config 274 option. 275 * `-state-dir=<path>`: Equivalent to the Client [state_dir](#state_dir) config 276 option.