go.etcd.io/etcd@v3.3.27+incompatible/Documentation/op-guide/configuration.md (about) 1 --- 2 title: Configuration flags 3 --- 4 5 etcd is configurable through a configuration file, various command-line flags, and environment variables. 6 7 A reusable configuration file is a YAML file made with name and value of one or more command-line flags described below. In order to use this file, specify the file path as a value to the `--config-file` flag. The [sample configuration file][sample-config-file] can be used as a starting point to create a new configuration file as needed. 8 9 Options set on the command line take precedence over those from the environment. If a configuration file is provided, other command line flags and environment variables will be ignored. 10 For example, `etcd --config-file etcd.conf.yml.sample --data-dir /tmp` will ignore the `--data-dir` flag. 11 12 The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all flags. 13 14 The [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. 15 16 To start etcd automatically using custom settings at startup in Linux, using a [systemd][systemd-intro] unit is highly recommended. 17 18 ## Member flags 19 20 ### --name 21 + Human-readable name for this member. 22 + default: "default" 23 + env variable: ETCD_NAME 24 + 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. 25 26 ### --data-dir 27 + Path to the data directory. 28 + default: "${name}.etcd" 29 + env variable: ETCD_DATA_DIR 30 31 ### --wal-dir 32 + 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. 33 + default: "" 34 + env variable: ETCD_WAL_DIR 35 36 ### --snapshot-count 37 + Number of committed transactions to trigger a snapshot to disk. 38 + default: "100000" 39 + env variable: ETCD_SNAPSHOT_COUNT 40 41 ### --heartbeat-interval 42 + Time (in milliseconds) of a heartbeat interval. 43 + default: "100" 44 + env variable: ETCD_HEARTBEAT_INTERVAL 45 46 ### --election-timeout 47 + Time (in milliseconds) for an election to timeout. See [Documentation/tuning.md][tuning] for details. 48 + default: "1000" 49 + env variable: ETCD_ELECTION_TIMEOUT 50 51 ### --listen-peer-urls 52 + 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 http or https. Alternatively, use `unix://<file-path>` or `unixs://<file-path>` for unix sockets. 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:2380" 54 + env variable: ETCD_LISTEN_PEER_URLS 55 + example: "http://10.0.0.1:2380" 56 + invalid example: "http://example.com:2380" (domain name is invalid for binding) 57 58 ### --listen-client-urls 59 + 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. Alternatively, use `unix://<file-path>` or `unixs://<file-path>` for unix sockets. 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. 60 + default: "http://localhost:2379" 61 + env variable: ETCD_LISTEN_CLIENT_URLS 62 + example: "http://10.0.0.1:2379" 63 + invalid example: "http://example.com:2379" (domain name is invalid for binding) 64 65 ### --max-snapshots 66 + Maximum number of snapshot files to retain (0 is unlimited) 67 + default: 5 68 + env variable: ETCD_MAX_SNAPSHOTS 69 + The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended. 70 71 ### --max-wals 72 + Maximum number of wal files to retain (0 is unlimited) 73 + default: 5 74 + env variable: ETCD_MAX_WALS 75 + The default for users on Windows is unlimited, and manual purging down to 5 (or some preference for safety) is recommended. 76 77 ### --cors 78 + Comma-separated white list of origins for CORS (cross-origin resource sharing). 79 + default: "" 80 + env variable: ETCD_CORS 81 82 ### --quota-backend-bytes 83 + Raise alarms when backend size exceeds the given quota (0 defaults to low space quota). 84 + default: 0 85 + env variable: ETCD_QUOTA_BACKEND_BYTES 86 87 ### --backend-batch-limit 88 + BackendBatchLimit is the maximum operations before commit the backend transaction. 89 + default: 0 90 + env variable: ETCD_BACKEND_BATCH_LIMIT 91 92 ### --backend-batch-interval 93 + BackendBatchInterval is the maximum time before commit the backend transaction. 94 + default: 0 95 + env variable: ETCD_BACKEND_BATCH_INTERVAL 96 97 ### --max-txn-ops 98 + Maximum number of operations permitted in a transaction. 99 + default: 128 100 + env variable: ETCD_MAX_TXN_OPS 101 102 ### --max-request-bytes 103 + Maximum client request size in bytes the server will accept. 104 + default: 1572864 105 + env variable: ETCD_MAX_REQUEST_BYTES 106 107 ### --grpc-keepalive-min-time 108 + Minimum duration interval that a client should wait before pinging server. 109 + default: 5s 110 + env variable: ETCD_GRPC_KEEPALIVE_MIN_TIME 111 112 ### --grpc-keepalive-interval 113 + Frequency duration of server-to-client ping to check if a connection is alive (0 to disable). 114 + default: 2h 115 + env variable: ETCD_GRPC_KEEPALIVE_INTERVAL 116 117 ### --grpc-keepalive-timeout 118 + Additional duration of wait before closing a non-responsive connection (0 to disable). 119 + default: 20s 120 + env variable: ETCD_GRPC_KEEPALIVE_TIMEOUT 121 122 ## Clustering flags 123 124 `--initial-advertise-peer-urls`, `--initial-cluster`, `--initial-cluster-state`, and `--initial-cluster-token` 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. 125 126 `--discovery` prefix flags need to be set when using [discovery service][discovery]. 127 128 ### --initial-advertise-peer-urls 129 130 + 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. 131 + default: "http://localhost:2380" 132 + env variable: ETCD_INITIAL_ADVERTISE_PEER_URLS 133 + example: "http://example.com:2380, http://10.0.0.1:2380" 134 135 ### --initial-cluster 136 + Initial cluster configuration for bootstrapping. 137 + default: "default=http://localhost:2380" 138 + env variable: ETCD_INITIAL_CLUSTER 139 + 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. 140 141 ### --initial-cluster-state 142 + 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. 143 + default: "new" 144 + env variable: ETCD_INITIAL_CLUSTER_STATE 145 146 [static bootstrap]: clustering.md#static 147 148 ### --initial-cluster-token 149 + Initial cluster token for the etcd cluster during bootstrap. 150 + default: "etcd-cluster" 151 + env variable: ETCD_INITIAL_CLUSTER_TOKEN 152 153 ### --advertise-client-urls 154 + List of this member's client URLs to advertise to the rest of the cluster. These URLs can contain domain names. 155 + default: "http://localhost:2379" 156 + env variable: ETCD_ADVERTISE_CLIENT_URLS 157 + example: "http://example.com:2379, http://10.0.0.1:2379" 158 + 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. 159 160 ### --discovery 161 + Discovery URL used to bootstrap the cluster. 162 + default: "" 163 + env variable: ETCD_DISCOVERY 164 165 ### --discovery-srv 166 + DNS srv domain used to bootstrap the cluster. 167 + default: "" 168 + env variable: ETCD_DISCOVERY_SRV 169 170 ### --discovery-srv-name 171 + Suffix to the DNS srv name queried when bootstrapping using DNS. 172 + default: "" 173 + env variable: ETCD_DISCOVERY_SRV_NAME 174 175 ### --discovery-fallback 176 + Expected behavior ("exit" or "proxy") when discovery services fails. "proxy" supports v2 API only. 177 + default: "proxy" 178 + env variable: ETCD_DISCOVERY_FALLBACK 179 180 ### --discovery-proxy 181 + HTTP proxy to use for traffic to discovery service. 182 + default: "" 183 + env variable: ETCD_DISCOVERY_PROXY 184 185 ### --strict-reconfig-check 186 + Reject reconfiguration requests that would cause quorum loss. 187 + default: true 188 + env variable: ETCD_STRICT_RECONFIG_CHECK 189 190 ### --auto-compaction-retention 191 + Auto compaction retention for mvcc key value store in hour. 0 means disable auto compaction. 192 + default: 0 193 + env variable: ETCD_AUTO_COMPACTION_RETENTION 194 195 ### --auto-compaction-mode 196 + Interpret 'auto-compaction-retention' one of: 'periodic', 'revision'. 'periodic' for duration based retention, defaulting to hours if no time unit is provided (e.g. '5m'). 'revision' for revision number based retention. 197 + default: periodic 198 + env variable: ETCD_AUTO_COMPACTION_MODE 199 200 ### --enable-v2 201 + Accept etcd V2 client requests 202 + default: true 203 + env variable: ETCD_ENABLE_V2 204 205 ## Proxy flags 206 207 `--proxy` prefix flags configures etcd to run in [proxy mode][proxy]. "proxy" supports v2 API only. 208 209 ### --proxy 210 + Proxy mode setting ("off", "readonly" or "on"). 211 + default: "off" 212 + env variable: ETCD_PROXY 213 214 ### --proxy-failure-wait 215 + Time (in milliseconds) an endpoint will be held in a failed state before being reconsidered for proxied requests. 216 + default: 5000 217 + env variable: ETCD_PROXY_FAILURE_WAIT 218 219 ### --proxy-refresh-interval 220 + Time (in milliseconds) of the endpoints refresh interval. 221 + default: 30000 222 + env variable: ETCD_PROXY_REFRESH_INTERVAL 223 224 ### --proxy-dial-timeout 225 + Time (in milliseconds) for a dial to timeout or 0 to disable the timeout 226 + default: 1000 227 + env variable: ETCD_PROXY_DIAL_TIMEOUT 228 229 ### --proxy-write-timeout 230 + Time (in milliseconds) for a write to timeout or 0 to disable the timeout. 231 + default: 5000 232 + env variable: ETCD_PROXY_WRITE_TIMEOUT 233 234 ### --proxy-read-timeout 235 + Time (in milliseconds) for a read to timeout or 0 to disable the timeout. 236 + Don't change this value if using watches because use long polling requests. 237 + default: 0 238 + env variable: ETCD_PROXY_READ_TIMEOUT 239 240 ## Security flags 241 242 The security flags help to [build a secure etcd cluster][security]. 243 244 ### --ca-file 245 246 **DEPRECATED** 247 248 + 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. 249 + default: "" 250 + env variable: ETCD_CA_FILE 251 252 ### --cert-file 253 + Path to the client server TLS cert file. 254 + default: "" 255 + env variable: ETCD_CERT_FILE 256 257 ### --key-file 258 + Path to the client server TLS key file. 259 + default: "" 260 + env variable: ETCD_KEY_FILE 261 262 ### --client-cert-auth 263 + Enable client cert authentication. 264 + default: false 265 + env variable: ETCD_CLIENT_CERT_AUTH 266 + CN authentication is not supported by gRPC-gateway. 267 268 ### --client-crl-file 269 + Path to the client certificate revocation list file. 270 + default: "" 271 + env variable: ETCD_CLIENT_CRL_FILE 272 273 ### --trusted-ca-file 274 + Path to the client server TLS trusted CA cert file. 275 + default: "" 276 + env variable: ETCD_TRUSTED_CA_FILE 277 278 ### --auto-tls 279 + Client TLS using generated certificates 280 + default: false 281 + env variable: ETCD_AUTO_TLS 282 283 ### --peer-ca-file 284 285 **DEPRECATED** 286 287 + 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. 288 + default: "" 289 + env variable: ETCD_PEER_CA_FILE 290 291 ### --peer-cert-file 292 + Path to the peer server TLS cert file. This is the cert for peer-to-peer traffic, used both for server and client. 293 + default: "" 294 + env variable: ETCD_PEER_CERT_FILE 295 296 ### --peer-key-file 297 + Path to the peer server TLS key file. This is the key for peer-to-peer traffic, used both for server and client. 298 + default: "" 299 + env variable: ETCD_PEER_KEY_FILE 300 301 ### --peer-client-cert-auth 302 + Enable peer client cert authentication. 303 + default: false 304 + env variable: ETCD_PEER_CLIENT_CERT_AUTH 305 306 ### --peer-crl-file 307 + Path to the peer certificate revocation list file. 308 + default: "" 309 + env variable: ETCD_PEER_CRL_FILE 310 311 ### --peer-trusted-ca-file 312 + Path to the peer server TLS trusted CA file. 313 + default: "" 314 + env variable: ETCD_PEER_TRUSTED_CA_FILE 315 316 ### --peer-auto-tls 317 + Peer TLS using generated certificates 318 + default: false 319 + env variable: ETCD_PEER_AUTO_TLS 320 321 ### --peer-cert-allowed-cn 322 + Allowed CommonName for inter peer authentication. 323 + default: none 324 + env variable: ETCD_PEER_CERT_ALLOWED_CN 325 326 ### --cipher-suites 327 + Comma-separated list of supported TLS cipher suites between server/client and peers. 328 + default: "" 329 + env variable: ETCD_CIPHER_SUITES 330 331 ### --experimental-peer-skip-client-san-verification 332 + Skip verification of SAN field in client certificate for peer connections. 333 + default: false 334 + env variable: ETCD_EXPERIMENTAL_PEER_SKIP_CLIENT_SAN_VERIFICATION 335 336 ## Logging flags 337 338 ### --logger 339 340 **Available from v3.4** 341 342 + Specify 'zap' for structured logging or 'capnslog'. 343 + default: capnslog 344 + env variable: ETCD_LOGGER 345 346 ### --log-outputs 347 + Specify 'stdout' or 'stderr' to skip journald logging even when running under systemd, or list of comma separated output targets. 348 + default: default 349 + env variable: ETCD_LOG_OUTPUTS 350 + 'default' use 'stderr' config for v3.4 during zap logger migraion 351 352 ### --debug 353 + Drop the default log level to DEBUG for all subpackages. 354 + default: false (INFO for all packages) 355 + env variable: ETCD_DEBUG 356 357 ### --log-package-levels 358 + Set individual etcd subpackages to specific log levels. An example being `etcdserver=WARNING,security=DEBUG` 359 + default: "" (INFO for all packages) 360 + env variable: ETCD_LOG_PACKAGE_LEVELS 361 362 ## Unsafe flags 363 364 Please be CAUTIOUS when using unsafe flags because it will break the guarantees given by the consensus protocol. 365 For example, it may panic if other members in the cluster are still alive. 366 Follow the instructions when using these flags. 367 368 ### --force-new-cluster 369 + Force to create a new one-member cluster. It commits configuration changes forcing to remove all existing members in the cluster and add itself, but is strongly discouraged. Please review the [disaster recovery][recovery] documentation for preferred v3 recovery procedures. 370 + default: false 371 + env variable: ETCD_FORCE_NEW_CLUSTER 372 373 ## Miscellaneous flags 374 375 ### --version 376 + Print the version and exit. 377 + default: false 378 379 ### --config-file 380 + Load server configuration from a file. 381 + default: "" 382 + example: [sample configuration file][sample-config-file] 383 + env variable: ETCD_CONFIG_FILE 384 385 ## Profiling flags 386 387 ### --enable-pprof 388 + Enable runtime profiling data via HTTP server. Address is at client URL + "/debug/pprof/" 389 + default: false 390 + env variable: ETCD_ENABLE_PPROF 391 392 ### --metrics 393 + Set level of detail for exported metrics, specify 'extensive' to include histogram metrics. 394 + default: basic 395 + env variable: ETCD_METRICS 396 397 ### --listen-metrics-urls 398 + List of additional URLs to listen on that will respond to both the `/metrics` and `/health` endpoints 399 + default: "" 400 + env variable: ETCD_LISTEN_METRICS_URLS 401 402 ## Auth flags 403 404 ### --auth-token 405 + Specify a token type and token specific options, especially for JWT. Its format is "type,var1=val1,var2=val2,...". Possible type is 'simple' or 'jwt'. Possible variables are 'sign-method' for specifying a sign method of jwt (its possible values are 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512', 'PS256', 'PS384', or 'PS512'), 'pub-key' for specifying a path to a public key for verifying jwt, 'priv-key' for specifying a path to a private key for signing jwt, and 'ttl' for specifying TTL of jwt tokens. 406 + For asymmetric algorithms ('RS', 'PS', 'ES'), the public key is optional, as the private key contains enough information to both sign and verify tokens. 407 + Example option of JWT: '--auth-token jwt,pub-key=app.rsa.pub,priv-key=app.rsa,sign-method=RS512,ttl=10m' 408 + default: "simple" 409 + env variable: ETCD_AUTH_TOKEN 410 411 ### --bcrypt-cost 412 + Specify the cost / strength of the bcrypt algorithm for hashing auth passwords. Valid values are between 4 and 31. 413 + default: 10 414 + env variable: (not supported) 415 416 ## Experimental flags 417 418 ### --experimental-backend-bbolt-freelist-type 419 + The freelist type that etcd backend(bboltdb) uses (array and map are supported types). 420 + default: array 421 + env variable: ETCD_EXPERIMENTAL_BACKEND_BBOLT_FREELIST_TYPE 422 423 ### --experimental-corrupt-check-time 424 + Duration of time between cluster corruption check passes 425 + default: 0s 426 + env variable: ETCD_EXPERIMENTAL_CORRUPT_CHECK_TIME 427 428 [build-cluster]: clustering.md#static 429 [reconfig]: runtime-configuration.md 430 [discovery]: clustering.md#discovery 431 [iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt 432 [proxy]: ../v2/proxy.md 433 [restore]: ../v2/admin_guide.md#restoring-a-backup 434 [security]: security.md 435 [systemd-intro]: http://freedesktop.org/wiki/Software/systemd/ 436 [tuning]: ../tuning.md#time-parameters 437 [sample-config-file]: ../../etcd.conf.yml.sample 438 [recovery]: recovery.md#disaster-recovery