etcd(1)

🌸 etcd 🌸 (that's etcd(1) bestie, a User Command, she's iconic)

okay so picture this: you need a key value store that is highly-available. That's her. That's etcd. She's the main character of your cluster and she never misses. 💖

---

✨ NAME ✨

etcd — highly-available key value store. yes that's the whole name. she's simple like that. 👑

---

✨ SYNOPSIS ✨

etcd [flags]

that's it. that's the whole vibe. flags only, no positional args, no drama. 🎀

---

💅 FLAGS 💅

🎀 Member 🎀

all the stuff about this member specifically, her little identity crisis corner 🦋

• --name 'default' — a human-readable name for this member. give her a name bestie, she deserves one.
• --data-dir '${name}.etcd' — path to the data directory. notice the default literally interpolates the member name, she's self-referential like that.
• --wal-dir '' — path to the dedicated wal directory.
• --snapshot-count '100000' — how many committed transactions pile up before she triggers a snapshot to disk.
• --heartbeat-interval '100' — heartbeat interval, in milliseconds.
• --election-timeout '1000' — how long, in milliseconds, an election gets before it times out. See the tuning documentation for the deets, iykyk.
• --initial-election-tick-advance 'true' — whether to fast-forward the initial election ticks on boot so the election happens faster.
• --listen-peer-urls 'http://localhost:2380' — the list of URLs to listen on for peer traffic.
• --listen-client-urls 'http://localhost:2379' — the list of URLs to listen on for client traffic.
• --max-snapshots '5' — max snapshot files to keep around (0 means unlimited, go off).
• --max-wals '5' — max wal files to keep around (0 means unlimited).
• --quota-backend-bytes '0' — raises alarms when the backend size goes over the quota you gave (0 defaults to the low space quota).
• --backend-batch-interval '' — BackendBatchInterval is the maximum time before committing the backend transaction.
• --backend-batch-limit '0' — BackendBatchLimit is the maximum operations before committing the backend transaction.
• --max-txn-ops '128' — max number of operations allowed inside one transaction.
• --max-request-bytes '1572864' — biggest client request size in bytes the server will accept.
• --max-concurrent-streams 'math.MaxUint32' — max concurrent streams each client can have open at once.
• --grpc-keepalive-min-time '5s' — minimum duration a client should wait before pinging the server.
• --grpc-keepalive-interval '2h' — how often the server pings the client to check the connection is alive (0 to disable).
• --grpc-keepalive-timeout '20s' — extra wait before closing a non-responsive connection (0 to disable).

🎀 Clustering 🎀

she's not like other girls, she's a distributed consensus girlie 🌈

• --initial-advertise-peer-urls 'http://localhost:2380' — the list of this member's peer URLs to advertise to the rest of the cluster.
• --initial-cluster 'default=http://localhost:2380' — initial cluster config for bootstrapping.
• --initial-cluster-state 'new' — initial cluster state, either 'new' or 'existing'.
• --initial-cluster-token 'etcd-cluster' — the initial cluster token for the etcd cluster during bootstrap. specifying this protects you from unintended cross-cluster interaction when you're running multiple clusters. very much a "boundaries" moment. 💅
• --advertise-client-urls 'http://localhost:2379' — the list of this member's client URLs to advertise to the public. these advertised client URLs should be reachable by machines that talk to the etcd cluster, and etcd client libraries parse these URLs to connect to the cluster. no cap.
• --discovery '' — discovery URL used to bootstrap the cluster.
• --discovery-fallback 'proxy' — expected behavior ('exit' or 'proxy') when the discovery service fails. "proxy" supports the v2 API only. 🫠
• --discovery-proxy '' — HTTP proxy to use for traffic to the discovery service.
• --discovery-srv '' — DNS srv domain used to bootstrap the cluster.
• --discovery-srv-name '' — suffix to the dns srv name queried when bootstrapping.
• --strict-reconfig-check 'true' — reject reconfiguration requests that would cause quorum loss. she's protective, we love that.
• --pre-vote 'false' — enable this to run an additional Raft election phase.
• --auto-compaction-retention '0' — auto compaction retention length. 0 means auto compaction is disabled.
• --auto-compaction-mode 'periodic' — how to interpret 'auto-compaction-retention', one of: periodic|revision. 'periodic' is duration-based retention and defaults to hours if you don't give a time unit (e.g. '5m'). 'revision' is revision-number-based retention.
• --enable-v2 'false' — accept etcd V2 client requests.

🎀 Security 🎀

TLS era. lock it down bestie, she's got certificates and she's not afraid to use them 🔐✨

• --cert-file '' — path to the client server TLS cert file.
• --key-file '' — path to the client server TLS key file.
• --client-cert-auth 'false' — enable client cert authentication.
• --client-crl-file '' — path to the client certificate revocation list file.
• --client-cert-allowed-hostname '' — allowed TLS hostname for client cert authentication.
• --trusted-ca-file '' — path to the client server TLS trusted CA cert file.
• --auto-tls 'false' — client TLS using generated certificates.
• --peer-cert-file '' — path to the peer server TLS cert file.
• --peer-key-file '' — path to the peer server TLS key file.
• --peer-client-cert-auth 'false' — enable peer client cert authentication.
• --peer-trusted-ca-file '' — path to the peer server TLS trusted CA file.
• --peer-cert-allowed-cn '' — required CN for client certs connecting to the peer endpoint.
• --peer-cert-allowed-hostname '' — allowed TLS hostname for inter-peer authentication.
• --peer-auto-tls 'false' — peer TLS using self-generated certificates if --peer-key-file and --peer-cert-file aren't provided.
• --peer-crl-file '' — path to the peer certificate revocation list file.
• --cipher-suites '' — comma-separated list of supported TLS cipher suites between client/server and peers (empty means Go auto-populates it).
• --cors '*' — comma-separated whitelist of origins for CORS, aka cross-origin resource sharing (empty or * means allow all).
• --host-whitelist '*' — acceptable hostnames from HTTP client requests, if the server isn't secure (empty or * means allow all).

🎀 Auth 🎀

• --auth-token 'simple' — specify a v3 authentication token type and its options, either 'simple' or 'jwt'.
• --bcrypt-cost 10 — specify the cost / strength of the bcrypt algorithm for hashing auth passwords. valid values are between 4 and 31.
• --auth-token-ttl 300 — time, in seconds, of the auth-token-ttl.

🎀 Profiling and Monitoring 🎀

she's not just pretty, she's observable 📊💖

• --enable-pprof 'false' — enable runtime profiling data via the HTTP server. the address lives at client URL + "/debug/pprof/".
• --metrics 'basic' — set the level of detail for exported metrics. specify 'extensive' to include histogram metrics.
• --listen-metrics-urls '' — list of URLs to listen on for the metrics and health endpoints.

🎀 Logging 🎀

• --logger 'capnslog' — specify 'zap' for structured logging, or 'capnslog'. [WARN] 'capnslog' will be deprecated in v3.5. ⚠️
• --log-outputs 'default' — specify 'stdout' or 'stderr' to skip journald logging even when running under systemd, or a list of comma separated output targets.
• --log-level 'info' — configures the log level. only supports debug, info, warn, error, panic, or fatal.

🎀 v2 Proxy (to be deprecated in v4) 🎀

she's on her way out but we still love her 🥲

• --proxy 'off' — proxy mode setting, one of 'off', 'readonly' or 'on'.
• --proxy-failure-wait 5000 — time, in milliseconds, an endpoint gets held in a failed state.
• --proxy-refresh-interval 30000 — time, in milliseconds, of the endpoints refresh interval.
• --proxy-dial-timeout 1000 — time, in milliseconds, for a dial to timeout.
• --proxy-write-timeout 5000 — time, in milliseconds, for a write to timeout.
• --proxy-read-timeout 0 — time, in milliseconds, for a read to timeout.

🎀 Experimental feature 🎀

"experimental" is the technical term for "we're trying something, wish us luck" 🙈✨

• --experimental-initial-corrupt-check 'false' — enable to check for data corruption before serving any client/peer traffic.
• --experimental-corrupt-check-time '0s' — duration of time between cluster corruption check passes.
• --experimental-enable-v2v3 '' — serve v2 requests through the v3 backend under a given prefix.
• --experimental-backend-bbolt-freelist-type 'array' — ExperimentalBackendFreelistType specifies the type of freelist the boltdb backend uses (array and map are the supported types).
• --experimental-enable-lease-checkpoint 'false' — ExperimentalEnableLeaseCheckpoint enables the primary lessor to persist lease remainingTTL so long lived leases don't auto-renew indefinitely.
• --experimental-compaction-batch-limit 1000 — ExperimentalCompactionBatchLimit sets the maximum revisions deleted in each compaction batch.
• --experimental-peer-skip-client-san-verification 'false' — skip verification of the SAN field in the client certificate for peer connections.
• --experimental-watch-progress-notify-interval '10m' — duration of periodical watch progress notification.
• --experimental-warning-apply-duration '100ms' — a warning is generated if requests take longer than this duration.

🎀 Unsafe feature 🎀

• --force-new-cluster 'false' — force the creation of a new one-member cluster.

⚠️ CAUTIOUS with unsafe flag! It may break the guarantees given by the consensus protocol! seriously bestie, this one is not a vibe, it's a threat 💀

🎀 TO BE DEPRECATED 🎀

• --debug 'false' — enable debug-level logging for etcd. [WARN] will be deprecated in v3.5. use '--log-level=debug' instead.
• --log-package-levels '' — specify a particular log level for each etcd package (eg: 'etcdmain=CRITICAL,etcdserver=DEBUG').

---

🌟 SEE ALSO 🌟

ectdctl(1), /usr/share/doc/etcd-server/op-guide/configuration.md.gz

(no i'm not fixing the typo in ectdctl(1), she's part of the lore now 💀)

---

and that's the whole page bestie!! this is 3.4.23, dated January 2022, from the etcd(1) manual — go be highly available, you absolute icon 🫶✨