1# Configuration flags 2 3etcd is configurable through command-line flags and environment variables. Options set on the command line take precedence over those from the environment. 4 5The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all flags. 6 7The [official etcd ports][iana-ports] are 2379 for client requests and 2380 for peer communication. The etcd ports can be set to accept TLS traffic, non-TLS traffic, or both TLS and non-TLS traffic. 8 9To start etcd automatically using custom settings at startup in Linux, using a [systemd][systemd-intro] unit is highly recommended. 10 11## Member flags 12 13### --name 14+ Human-readable name for this member. 15+ default: "default" 16+ env variable: ETCD_NAME 17+ This value is referenced as this node's own entries listed in the `--initial-cluster` flag (e.g., `default=http://localhost:2380`). This needs to match the key used in the flag if using [static bootstrapping][build-cluster]. When using discovery, each member must have a unique name. `Hostname` or `machine-id` can be a good choice. 18 19### --data-dir 20+ Path to the data directory. 21+ default: "${name}.etcd" 22+ env variable: ETCD_DATA_DIR 23 24### --wal-dir 25+ Path to the dedicated wal directory. If this flag is set, etcd will write the WAL files to the walDir rather than the dataDir. This allows a dedicated disk to be used, and helps avoid io competition between logging and other IO operations. 26+ default: "" 27+ env variable: ETCD_WAL_DIR 28 29### --snapshot-count 30+ Number of committed transactions to trigger a snapshot to disk. 31+ default: "10000" 32+ env variable: ETCD_SNAPSHOT_COUNT 33 34### --heartbeat-interval 35+ Time (in milliseconds) of a heartbeat interval. 36+ default: "100" 37+ env variable: ETCD_HEARTBEAT_INTERVAL 38 39### --election-timeout 40+ Time (in milliseconds) for an election to timeout. See [Documentation/tuning.md][tuning] for details. 41+ default: "1000" 42+ env variable: ETCD_ELECTION_TIMEOUT 43 44### --listen-peer-urls 45+ List of URLs to listen on for peer traffic. This flag tells the etcd to accept incoming requests from its peers on the specified scheme://IP:port combinations. Scheme can be either http or https.If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports. 46+ default: "http://localhost:2380" 47+ env variable: ETCD_LISTEN_PEER_URLS 48+ example: "http://10.0.0.1:2380" 49+ invalid example: "http://example.com:2380" (domain name is invalid for binding) 50 51### --listen-client-urls 52+ List of URLs to listen on for client traffic. This flag tells the etcd to accept incoming requests from the clients on the specified scheme://IP:port combinations. Scheme can be either http or https. If 0.0.0.0 is specified as the IP, etcd listens to the given port on all interfaces. If an IP address is given as well as a port, etcd will listen on the given port and interface. Multiple URLs may be used to specify a number of addresses and ports to listen on. The etcd will respond to requests from any of the listed addresses and ports. 53+ default: "http://localhost:2379" 54+ env variable: ETCD_LISTEN_CLIENT_URLS 55+ example: "http://10.0.0.1:2379" 56+ invalid example: "http://example.com:2379" (domain name is invalid for binding) 57 58### --max-snapshots 59+ Maximum number of snapshot files to retain (0 is unlimited) 60+ default: 5 61+ env variable: ETCD_MAX_SNAPSHOTS 62+ The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended. 63 64### --max-wals 65+ Maximum number of wal files to retain (0 is unlimited) 66+ default: 5 67+ env variable: ETCD_MAX_WALS 68+ The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended. 69 70### --cors 71+ Comma-separated white list of origins for CORS (cross-origin resource sharing). 72+ default: none 73+ env variable: ETCD_CORS 74 75## Clustering flags 76 77`--initial` prefix flags are used in bootstrapping ([static bootstrap][build-cluster], [discovery-service bootstrap][discovery] or [runtime reconfiguration][reconfig]) a new member, and ignored when restarting an existing member. 78 79`--discovery` prefix flags need to be set when using [discovery service][discovery]. 80 81### --initial-advertise-peer-urls 82 83+ List of this member's peer URLs to advertise to the rest of the cluster. These addresses are used for communicating etcd data around the cluster. At least one must be routable to all cluster members. These URLs can contain domain names. 84+ default: "http://localhost:2380" 85+ env variable: ETCD_INITIAL_ADVERTISE_PEER_URLS 86+ example: "http://example.com:2380, http://10.0.0.1:2380" 87 88### --initial-cluster 89+ Initial cluster configuration for bootstrapping. 90+ default: "default=http://localhost:2380" 91+ env variable: ETCD_INITIAL_CLUSTER 92+ The key is the value of the `--name` flag for each node provided. The default uses `default` for the key because this is the default for the `--name` flag. 93 94### --initial-cluster-state 95+ Initial cluster state ("new" or "existing"). Set to `new` for all members present during initial static or DNS bootstrapping. If this option is set to `existing`, etcd will attempt to join the existing cluster. If the wrong value is set, etcd will attempt to start but fail safely. 96+ default: "new" 97+ env variable: ETCD_INITIAL_CLUSTER_STATE 98 99[static bootstrap]: clustering.md#static 100 101### --initial-cluster-token 102+ Initial cluster token for the etcd cluster during bootstrap. 103+ default: "etcd-cluster" 104+ env variable: ETCD_INITIAL_CLUSTER_TOKEN 105 106### --advertise-client-urls 107+ List of this member's client URLs to advertise to the rest of the cluster. These URLs can contain domain names. 108+ default: "http://localhost:2379" 109+ env variable: ETCD_ADVERTISE_CLIENT_URLS 110+ example: "http://example.com:2379, http://10.0.0.1:2379" 111+ Be careful if advertising URLs such as http://localhost:2379 from a cluster member and are using the proxy feature of etcd. This will cause loops, because the proxy will be forwarding requests to itself until its resources (memory, file descriptors) are eventually depleted. 112 113### --discovery 114+ Discovery URL used to bootstrap the cluster. 115+ default: none 116+ env variable: ETCD_DISCOVERY 117 118### --discovery-srv 119+ DNS srv domain used to bootstrap the cluster. 120+ default: none 121+ env variable: ETCD_DISCOVERY_SRV 122 123### --discovery-fallback 124+ Expected behavior ("exit" or "proxy") when discovery services fails. "proxy" supports v2 API only. 125+ default: "proxy" 126+ env variable: ETCD_DISCOVERY_FALLBACK 127 128### --discovery-proxy 129+ HTTP proxy to use for traffic to discovery service. 130+ default: none 131+ env variable: ETCD_DISCOVERY_PROXY 132 133### --strict-reconfig-check 134+ Reject reconfiguration requests that would cause quorum loss. 135+ default: false 136+ env variable: ETCD_STRICT_RECONFIG_CHECK 137 138### --auto-compaction-retention 139+ Auto compaction retention for mvcc key value store in hour. 0 means disable auto compaction. 140+ default: 0 141+ env variable: ETCD_AUTO_COMPACTION_RETENTION 142 143## Proxy flags 144 145`--proxy` prefix flags configures etcd to run in [proxy mode][proxy]. "proxy" supports v2 API only. 146 147### --proxy 148+ Proxy mode setting ("off", "readonly" or "on"). 149+ default: "off" 150+ env variable: ETCD_PROXY 151 152### --proxy-failure-wait 153+ Time (in milliseconds) an endpoint will be held in a failed state before being reconsidered for proxied requests. 154+ default: 5000 155+ env variable: ETCD_PROXY_FAILURE_WAIT 156 157### --proxy-refresh-interval 158+ Time (in milliseconds) of the endpoints refresh interval. 159+ default: 30000 160+ env variable: ETCD_PROXY_REFRESH_INTERVAL 161 162### --proxy-dial-timeout 163+ Time (in milliseconds) for a dial to timeout or 0 to disable the timeout 164+ default: 1000 165+ env variable: ETCD_PROXY_DIAL_TIMEOUT 166 167### --proxy-write-timeout 168+ Time (in milliseconds) for a write to timeout or 0 to disable the timeout. 169+ default: 5000 170+ env variable: ETCD_PROXY_WRITE_TIMEOUT 171 172### --proxy-read-timeout 173+ Time (in milliseconds) for a read to timeout or 0 to disable the timeout. 174+ Don't change this value if using watches because use long polling requests. 175+ default: 0 176+ env variable: ETCD_PROXY_READ_TIMEOUT 177 178## Security flags 179 180The security flags help to [build a secure etcd cluster][security]. 181 182### --ca-file [DEPRECATED] 183+ Path to the client server TLS CA file. `--ca-file ca.crt` could be replaced by `--trusted-ca-file ca.crt --client-cert-auth` and etcd will perform the same. 184+ default: none 185+ env variable: ETCD_CA_FILE 186 187### --cert-file 188+ Path to the client server TLS cert file. 189+ default: none 190+ env variable: ETCD_CERT_FILE 191 192### --key-file 193+ Path to the client server TLS key file. 194+ default: none 195+ env variable: ETCD_KEY_FILE 196 197### --client-cert-auth 198+ Enable client cert authentication. 199+ default: false 200+ env variable: ETCD_CLIENT_CERT_AUTH 201 202### --trusted-ca-file 203+ Path to the client server TLS trusted CA key file. 204+ default: none 205+ env variable: ETCD_TRUSTED_CA_FILE 206 207### --auto-tls 208+ Client TLS using generated certificates 209+ default: false 210+ env variable: ETCD_AUTO_TLS 211 212### --peer-ca-file [DEPRECATED] 213+ Path to the peer server TLS CA file. `--peer-ca-file ca.crt` could be replaced by `--peer-trusted-ca-file ca.crt --peer-client-cert-auth` and etcd will perform the same. 214+ default: none 215+ env variable: ETCD_PEER_CA_FILE 216 217### --peer-cert-file 218+ Path to the peer server TLS cert file. 219+ default: none 220+ env variable: ETCD_PEER_CERT_FILE 221 222### --peer-key-file 223+ Path to the peer server TLS key file. 224+ default: none 225+ env variable: ETCD_PEER_KEY_FILE 226 227### --peer-client-cert-auth 228+ Enable peer client cert authentication. 229+ default: false 230+ env variable: ETCD_PEER_CLIENT_CERT_AUTH 231 232### --peer-trusted-ca-file 233+ Path to the peer server TLS trusted CA file. 234+ default: none 235+ env variable: ETCD_PEER_TRUSTED_CA_FILE 236 237### --peer-auto-tls 238+ Peer TLS using generated certificates 239+ default: false 240+ env variable: ETCD_PEER_AUTO_TLS 241 242## Logging flags 243 244### --debug 245+ Drop the default log level to DEBUG for all subpackages. 246+ default: false (INFO for all packages) 247+ env variable: ETCD_DEBUG 248 249### --log-package-levels 250+ Set individual etcd subpackages to specific log levels. An example being `etcdserver=WARNING,security=DEBUG` 251+ default: none (INFO for all packages) 252+ env variable: ETCD_LOG_PACKAGE_LEVELS 253 254 255## Unsafe flags 256 257Please be CAUTIOUS when using unsafe flags because it will break the guarantees given by the consensus protocol. 258For example, it may panic if other members in the cluster are still alive. 259Follow the instructions when using these flags. 260 261### --force-new-cluster 262+ Force to create a new one-member cluster. It commits configuration changes forcing to remove all existing members in the cluster and add itself. It needs to be set to [restore a backup][restore]. 263+ default: false 264+ env variable: ETCD_FORCE_NEW_CLUSTER 265 266## Miscellaneous flags 267 268### --version 269+ Print the version and exit. 270+ default: false 271 272### --config-file 273+ Load server configuration from a file. 274+ default: none 275 276## Profiling flags 277 278### --enable-pprof 279+ Enable runtime profiling data via HTTP server. Address is at client URL + "/debug/pprof/" 280+ default: false 281 282### --metrics 283+ Set level of detail for exported metrics, specify 'extensive' to include histogram metrics. 284+ default: basic 285 286[build-cluster]: clustering.md#static 287[reconfig]: runtime-configuration.md 288[discovery]: clustering.md#discovery 289[iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt 290[proxy]: ../v2/proxy.md 291[restore]: ../v2/admin_guide.md#restoring-a-backup 292[security]: security.md 293[systemd-intro]: http://freedesktop.org/wiki/Software/systemd/ 294[tuning]: ../tuning.md#time-parameters 295