2014-10-23 03:59:29 +04:00
etcdctl
========
`etcdctl` is a command line client for [etcd][etcd].
2016-06-01 21:28:43 +03:00
Make sure to set environment variable `ETCDCTL_API=3` . For etcdctl v2, please check [READMEv2][READMEv2].
2014-10-23 03:59:29 +04:00
2016-10-14 21:16:25 +03:00
Global flags (e.g., `dial-timeout` , `--cacert` , `--cert` , `--key` ) can be set with environment variables:
```
ETCDCTL_DIAL_TIMEOUT=3s
ETCDCTL_CACERT=/tmp/ca.pem
ETCDCTL_CERT=/tmp/cert.pem
ETCDCTL_KEY=/tmp/key.pem
```
Prefix flag strings with `ETCDCTL_` , convert all letters to upper-case, and replace dash(`-`) with underscore(`_`).
2016-12-13 04:03:09 +03:00
## Key-value commands
2016-09-23 06:35:08 +03:00
2016-06-01 21:28:43 +03:00
### PUT [options] \<key\> \<value\>
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
PUT assigns the specified value with the specified key. If key already holds a value, it is overwritten.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: Put
2016-06-01 21:28:43 +03:00
#### Options
2016-01-13 05:01:57 +03:00
2016-06-01 21:28:43 +03:00
- lease -- lease ID (in hexadecimal) to attach to the key.
2016-01-13 05:01:57 +03:00
2016-09-27 22:14:30 +03:00
- prev-kv -- return the previous key-value pair before modification.
2016-12-05 23:38:43 +03:00
- ignore-value -- updates the key using its current value.
2017-01-25 00:41:19 +03:00
- ignore-lease -- updates the key using its current lease.
2016-12-13 04:03:09 +03:00
#### Output
2016-01-13 05:01:57 +03:00
2016-12-13 04:03:09 +03:00
`OK`
2016-01-13 05:01:57 +03:00
2016-06-01 21:28:43 +03:00
#### Examples
2016-01-13 05:01:57 +03:00
2016-09-15 09:32:38 +03:00
```bash
2016-09-07 10:05:20 +03:00
./etcdctl put foo bar --lease=1234abcd
2016-09-09 12:49:52 +03:00
# OK
2016-09-07 10:05:20 +03:00
./etcdctl get foo
2016-09-09 12:49:52 +03:00
# foo
# bar
2016-12-05 23:38:43 +03:00
./etcdctl put foo --ignore-value # to detache lease
# OK
2016-06-01 21:28:43 +03:00
```
2016-01-13 05:01:57 +03:00
2017-01-25 00:41:19 +03:00
```bash
./etcdctl put foo bar --lease=1234abcd
# OK
./etcdctl put foo bar1 --ignore-lease # to use existing lease 1234abcd
# OK
./etcdctl get foo
# foo
# bar1
```
2016-09-27 22:14:30 +03:00
```bash
./etcdctl put foo bar1 --prev-kv
# OK
# foo
# bar
./etcdctl get foo
# foo
# bar1
```
2016-12-13 04:03:09 +03:00
#### Remarks
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
If \<value\> isn't given as command line argument, this command tries to read the value from standard input.
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
When \<value\> begins with '-', \<value\> is interpreted as a flag.
Insert '--' for workaround:
2014-10-23 03:59:29 +04:00
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl put < key > -- < value >
./etcdctl put -- < key > < value >
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### GET [options] \<key\> [range_end]
GET gets the key or a range of keys [key, range_end) if `range-end` is given.
2016-12-13 04:03:09 +03:00
RPC: Range
2016-06-01 21:28:43 +03:00
#### Options
- hex -- print out key and value as hex encode string
- limit -- maximum number of results
- prefix -- get keys by matching prefix
- order -- order of results; ASCEND or DESCEND
- sort-by -- sort target; CREATE, KEY, MODIFY, VALUE, or VERSION
- rev -- specify the kv revision
2016-08-29 22:09:07 +03:00
- print-value-only -- print only value when used with write-out=simple
2016-09-21 01:15:30 +03:00
- consistency -- Linearizable(l) or Serializable(s)
- from-key -- Get keys that are greater than or equal to the given key using byte compare
- keys-only -- Get only the keys
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
\<key\>\n\<value\>\n\<next_key\>\n\<next_value\>...
2016-06-01 21:28:43 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-21 01:15:30 +03:00
./etcdctl put foo bar
# OK
./etcdctl put foo1 bar1
# OK
./etcdctl put foo2 bar2
# OK
./etcdctl put foo3 bar3
# OK
2016-06-01 21:28:43 +03:00
./etcdctl get foo
2016-09-09 12:49:52 +03:00
# foo
# bar
2016-09-21 01:15:30 +03:00
./etcdctl get --from-key foo1
# foo1
# bar1
# foo2
# bar2
# foo3
# bar3
./etcdctl get foo1 foo3
# foo1
# bar1
# foo2
# bar2
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
#### Remarks
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
If any key or value contains non-printable characters or control characters, simple formatted output can be ambiguous due to new lines. To resolve this issue, set `--hex` to hex encode all strings.
2016-06-01 21:28:43 +03:00
### DEL [options] \<key\> [range_end]
Removes the specified key or range of keys [key, range_end) if `range-end` is given.
2016-12-13 04:03:09 +03:00
RPC: DeleteRange
2016-06-01 21:28:43 +03:00
#### Options
- prefix -- delete keys by matching prefix
2016-09-21 21:46:53 +03:00
- prev-kv -- return deleted key-value pairs
2016-09-22 19:15:56 +03:00
- from-key -- delete keys that are greater than or equal to the given key using byte compare
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints the number of keys that were removed in decimal if DEL succeeded.
2016-06-01 21:28:43 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl put foo bar
2016-09-09 12:49:52 +03:00
# OK
2016-06-01 21:28:43 +03:00
./etcdctl del foo
2016-09-09 12:49:52 +03:00
# 1
2016-09-07 15:09:24 +03:00
./etcdctl get foo
2016-06-01 21:28:43 +03:00
```
2016-09-22 19:15:56 +03:00
```bash
./etcdctl put key val
# OK
./etcdctl del --prev-kv key
# 1
# key
# val
./etcdctl get key
```
```bash
./etcdctl put a 123
# OK
./etcdctl put b 456
# OK
./etcdctl put z 789
# OK
./etcdctl del --from-key a
# 3
./etcdctl get --from-key a
```
```bash
./etcdctl put zoo val
# OK
./etcdctl put zoo1 val1
# OK
./etcdctl put zoo2 val2
# OK
./etcdctl del --prefix zoo
# 3
./etcdctl get zoo2
```
2016-06-01 21:28:43 +03:00
### TXN [options]
TXN reads multiple etcd requests from standard input and applies them as a single atomic transaction.
A transaction consists of list of conditions, a list of requests to apply if all the conditions are true, and a list of requests to apply if any condition is false.
2016-12-13 04:03:09 +03:00
RPC: Txn
2016-06-01 21:28:43 +03:00
#### Options
2016-12-13 04:03:09 +03:00
- hex -- print out keys and values as hex encoded strings.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
- interactive -- input transaction with interactive prompting.
2016-06-01 21:28:43 +03:00
#### Input Format
```ebnf
< Txn > ::= < CMP > * "\n" < THEN > "\n" < ELSE > "\n"
< CMP > ::= (< CMPCREATE > |< CMPMOD > |< CMPVAL > |< CMPVER > ) "\n"
< CMPOP > ::= "< " | "=" | ">"
< CMPCREATE > := ("c"|"create")"("< KEY > ")" < REVISION >
< CMPMOD > ::= ("m"|"mod")"("< KEY > ")" < CMPOP > < REVISION >
< CMPVAL > ::= ("val"|"value")"("< KEY > ")" < CMPOP > < VALUE >
< CMPVER > ::= ("ver"|"version")"("< KEY > ")" < CMPOP > < VERSION >
< THEN > ::= < OP > *
< ELSE > ::= < OP > *
< OP > ::= ((see put, get, del etcdctl command syntax)) "\n"
< KEY > ::= (%q formatted string)
< VALUE > ::= (%q formatted string)
< REVISION > ::= "\""[0-9]+"\""
< VERSION > ::= "\""[0-9]+"\""
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
`SUCCESS` if etcd processed the transaction success list, `FAILURE` if etcd processed the transaction failure list. Prints the output for each command in the executed request list, each separated by a blank line.
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
#### Examples
txn in interactive mode:
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl txn -i
2016-10-19 17:25:09 +03:00
# compares:
2016-06-01 21:28:43 +03:00
mod("key1") > "0"
2016-10-19 17:25:09 +03:00
# success requests (get, put, delete):
2016-06-01 21:28:43 +03:00
put key1 "overwrote-key1"
2016-10-19 17:25:09 +03:00
# failure requests (get, put, delete):
2016-06-01 21:28:43 +03:00
put key1 "created-key1"
put key2 "some extra key"
2016-09-09 12:49:52 +03:00
# FAILURE
2016-06-01 21:28:43 +03:00
2016-09-09 12:49:52 +03:00
# OK
2016-06-01 21:28:43 +03:00
2016-09-09 12:49:52 +03:00
# OK
2016-06-01 21:28:43 +03:00
```
txn in non-interactive mode:
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl txn < < < 'mod("key1") > "0"
put key1 "overwrote-key1"
put key1 "created-key1"
put key2 "some extra key"
'
2016-09-15 09:32:38 +03:00
2016-09-09 12:49:52 +03:00
# FAILURE
2016-06-01 21:28:43 +03:00
2016-09-09 12:49:52 +03:00
# OK
2016-06-01 21:28:43 +03:00
2016-09-09 12:49:52 +03:00
# OK
```
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
### COMPACTION [options] \<revision\>
COMPACTION discards all etcd event history prior to a given revision. Since etcd uses a multiversion concurrency control
model, it preserves all key updates as event history. When the event history up to some revision is no longer needed,
all superseded keys may be compacted away to reclaim storage space in the etcd backend database.
RPC: Compact
#### Options
- physical -- 'true' to wait for compaction to physically remove all old revisions
#### Output
Prints the compacted revision.
#### Example
```bash
./etcdctl compaction 1234
# compacted revision 1234
```
2016-06-08 02:31:15 +03:00
### WATCH [options] [key or prefix] [range_end]
2014-10-23 03:59:29 +04:00
2016-11-08 22:46:52 +03:00
Watch watches events stream on keys or prefixes, [key or prefix, range_end) if `range-end` is given. The watch command runs until it encounters an error or is terminated by the user. If range_end is given, it must be lexicographically greater than key or "\x00".
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: Watch
2016-06-01 21:28:43 +03:00
#### Options
- hex -- print out key and value as hex encode string
- interactive -- begins an interactive watch session
- prefix -- watch on a prefix if prefix is set.
2016-07-02 05:17:01 +03:00
- prev-kv -- get the previous key-value pair before the event happens.
2016-06-01 21:28:43 +03:00
- rev -- the revision to start watching. Specifying a revision is useful for observing past events.
2016-12-13 04:03:09 +03:00
#### Input format
2016-06-01 21:28:43 +03:00
Input is only accepted for interactive mode.
```
watch [options] < key or prefix > \n
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
\<event\>[\n\<old_key\>\n\<old_value\>]\n\<key\>\n\<value\>\n\<event\>\n\<next_key\>\n\<next_value\>\n...
2016-03-09 15:04:01 +03:00
2016-06-01 21:28:43 +03:00
#### Examples
##### Non-interactive
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl watch foo
2016-09-09 12:49:52 +03:00
# PUT
# foo
# bar
2016-06-01 21:28:43 +03:00
```
##### Interactive
2016-09-15 09:32:38 +03:00
```bash
2016-06-01 21:28:43 +03:00
./etcdctl watch -i
watch foo
watch foo
2016-09-09 12:49:52 +03:00
# PUT
# foo
# bar
# PUT
# foo
# bar
2016-03-09 15:04:01 +03:00
```
2016-06-01 21:28:43 +03:00
### LEASE \<subcommand\>
LEASE provides commands for key lease management.
### LEASE GRANT \<ttl\>
LEASE GRANT creates a fresh lease with a server-selected time-to-live in seconds
greater than or equal to the requested TTL value.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: LeaseGrant
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a message with the granted lease ID.
2016-06-01 21:28:43 +03:00
#### Example
```bash
./etcdctl lease grant 10
2016-09-09 12:49:52 +03:00
# lease 32695410dcc0ca06 granted with TTL(10s)
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### LEASE REVOKE \<leaseID\>
LEASE REVOKE destroys a given lease, deleting all attached keys.
2016-12-13 04:03:09 +03:00
RPC: LeaseRevoke
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
Prints a message indicating the lease is revoked.
2016-06-01 21:28:43 +03:00
#### Example
```bash
./etcdctl lease revoke 32695410dcc0ca06
2016-09-09 12:49:52 +03:00
# lease 32695410dcc0ca06 revoked
2014-10-23 03:59:29 +04:00
```
2016-09-20 14:10:58 +03:00
### LEASE TIMETOLIVE \<leaseID\> [options]
2016-09-09 02:21:58 +03:00
LEASE TIMETOLIVE retrieves the lease information with the given lease ID.
2016-12-13 04:03:09 +03:00
RPC: LeaseTimeToLive
2016-09-20 14:10:58 +03:00
#### Options
- keys -- Get keys attached to this lease
2016-12-13 04:03:09 +03:00
#### Output
2016-09-09 02:21:58 +03:00
2016-12-13 04:03:09 +03:00
Prints lease information.
2016-09-09 02:21:58 +03:00
#### Example
```bash
./etcdctl lease grant 500
2016-09-09 12:49:52 +03:00
# lease 2d8257079fa1bc0c granted with TTL(500s)
2016-09-09 02:21:58 +03:00
./etcdctl put foo1 bar --lease=2d8257079fa1bc0c
2016-09-13 18:03:51 +03:00
# OK
2016-09-09 02:21:58 +03:00
./etcdctl put foo2 bar --lease=2d8257079fa1bc0c
2016-09-13 18:03:51 +03:00
# OK
2016-09-09 02:21:58 +03:00
./etcdctl lease timetolive 2d8257079fa1bc0c
2016-09-09 12:49:52 +03:00
# lease 2d8257079fa1bc0c granted with TTL(500s), remaining(481s)
2016-09-09 02:21:58 +03:00
./etcdctl lease timetolive 2d8257079fa1bc0c --keys
2016-09-09 12:49:52 +03:00
# lease 2d8257079fa1bc0c granted with TTL(500s), remaining(472s), attached keys([foo2 foo1])
2016-09-09 02:21:58 +03:00
./etcdctl lease timetolive 2d8257079fa1bc0c --write-out=json
2016-09-09 12:49:52 +03:00
# {"cluster_id":17186838941855831277,"member_id":4845372305070271874,"revision":3,"raft_term":2,"id":3279279168933706764,"ttl":465,"granted-ttl":500,"keys":null}
2016-09-09 02:21:58 +03:00
./etcdctl lease timetolive 2d8257079fa1bc0c --write-out=json --keys
2016-09-09 12:49:52 +03:00
# {"cluster_id":17186838941855831277,"member_id":4845372305070271874,"revision":3,"raft_term":2,"id":3279279168933706764,"ttl":459,"granted-ttl":500,"keys":["Zm9vMQ==","Zm9vMg=="]}
2016-09-09 02:21:58 +03:00
```
2016-06-01 21:28:43 +03:00
### LEASE KEEP-ALIVE \<leaseID\>
LEASE KEEP-ALIVE periodically refreshes a lease so it does not expire.
2016-12-13 04:03:09 +03:00
RPC: LeaseKeepAlive
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a message for every keep alive sent or prints a message indicating the lease is gone.
2016-06-01 21:28:43 +03:00
#### Example
```bash
2016-09-09 12:49:52 +03:00
./etcdctl lease keep-alive 32695410dcc0ca0
# lease 32695410dcc0ca0 keepalived with TTL(100)
# lease 32695410dcc0ca0 keepalived with TTL(100)
# lease 32695410dcc0ca0 keepalived with TTL(100)
2016-06-01 21:28:43 +03:00
...
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
## Cluster maintenance commands
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
### MEMBER \<subcommand\>
MEMBER provides commands for managing etcd cluster membership.
2016-09-22 12:34:54 +03:00
### MEMBER ADD \<memberName\> [options]
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
MEMBER ADD introduces a new member into the etcd cluster as a new peer.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: MemberAdd
2016-06-01 21:28:43 +03:00
#### Options
2016-06-23 19:52:25 +03:00
- peer-urls -- comma separated list of URLs to associate with the new member.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints the member ID of the new member and the cluster ID.
2016-06-01 21:28:43 +03:00
#### Example
```bash
2016-06-23 19:52:25 +03:00
./etcdctl member add newMember --peer-urls=https://127.0.0.1:12345
2016-12-22 08:43:49 +03:00
Member ced000fda4d05edf added to cluster 8c4281cc65c7b112
ETCD_NAME="newMember"
ETCD_INITIAL_CLUSTER="newMember=https://127.0.0.1:12345,default=http://10.0.0.30:2380"
ETCD_INITIAL_CLUSTER_STATE="existing"
2014-10-23 03:59:29 +04:00
```
2016-09-22 12:34:54 +03:00
### MEMBER UPDATE \<memberID\> [options]
2016-06-01 21:28:43 +03:00
MEMBER UPDATE sets the peer URLs for an existing member in the etcd cluster.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: MemberUpdate
2016-06-01 21:28:43 +03:00
#### Options
2016-06-23 19:52:25 +03:00
- peer-urls -- comma separated list of URLs to associate with the updated member.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints the member ID of the updated member and the cluster ID.
2016-06-01 21:28:43 +03:00
#### Example
```bash
2016-06-23 19:52:25 +03:00
./etcdctl member update 2be1eb8f84b7f63e --peer-urls=https://127.0.0.1:11112
2016-09-09 12:49:52 +03:00
# Member 2be1eb8f84b7f63e updated in cluster ef37ad9dc622a7c4
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### MEMBER REMOVE \<memberID\>
MEMBER REMOVE removes a member of an etcd cluster from participating in cluster consensus.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: MemberRemove
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints the member ID of the removed member and the cluster ID.
2016-06-01 21:28:43 +03:00
#### Example
```bash
./etcdctl member remove 2be1eb8f84b7f63e
2016-09-09 12:49:52 +03:00
# Member 2be1eb8f84b7f63e removed from cluster ef37ad9dc622a7c4
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### MEMBER LIST
MEMBER LIST prints the member details for all members associated with an etcd cluster.
2016-12-13 04:03:09 +03:00
RPC: [MemberList][member_list_rpc].
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a humanized table of the member IDs, statuses, names, peer addresses, and client addresses.
2016-06-01 21:28:43 +03:00
#### Examples
```bash
./etcdctl member list
2016-09-09 12:49:52 +03:00
# 8211f1d0f64f3269, started, infra1, http://127.0.0.1:12380, http://127.0.0.1:2379
# 91bc3c398fb3c146, started, infra2, http://127.0.0.1:22380, http://127.0.0.1:22379
# fd422379fda50e48, started, infra3, http://127.0.0.1:32380, http://127.0.0.1:32379
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
```bash
./etcdctl -w json member list
2016-09-09 12:49:52 +03:00
# {"header":{"cluster_id":17237436991929493444,"member_id":9372538179322589801,"raft_term":2},"members":[{"ID":9372538179322589801,"name":"infra1","peerURLs":["http://127.0.0.1:12380"],"clientURLs":["http://127.0.0.1:2379"]},{"ID":10501334649042878790,"name":"infra2","peerURLs":["http://127.0.0.1:22380"],"clientURLs":["http://127.0.0.1:22379"]},{"ID":18249187646912138824,"name":"infra3","peerURLs":["http://127.0.0.1:32380"],"clientURLs":["http://127.0.0.1:32379"]}]}
2016-06-01 21:28:43 +03:00
```
2014-10-30 03:42:21 +03:00
2016-06-01 21:28:43 +03:00
```bash
./etcdctl -w table member list
+------------------+---------+--------+------------------------+------------------------+
| ID | STATUS | NAME | PEER ADDRS | CLIENT ADDRS |
+------------------+---------+--------+------------------------+------------------------+
| 8211f1d0f64f3269 | started | infra1 | http://127.0.0.1:12380 | http://127.0.0.1:2379 |
| 91bc3c398fb3c146 | started | infra2 | http://127.0.0.1:22380 | http://127.0.0.1:22379 |
| fd422379fda50e48 | started | infra3 | http://127.0.0.1:32380 | http://127.0.0.1:32379 |
+------------------+---------+--------+------------------------+------------------------+
2014-10-30 03:42:21 +03:00
```
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
### ENDPOINT \<subcommand\>
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
ENDPOINT provides commands for querying individual endpoints.
2014-10-23 03:59:29 +04:00
2017-06-21 01:24:50 +03:00
#### Options
- cluster -- fetch and use all endpoints from the etcd cluster member list
2016-06-01 21:28:43 +03:00
### ENDPOINT HEALTH
ENDPOINT HEALTH checks the health of the list of endpoints with respect to cluster. An endpoint is unhealthy
when it cannot participate in consensus with the rest of the cluster.
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
If an endpoint can participate in consensus, prints a message indicating the endpoint is healthy. If an endpoint fails to participate in consensus, prints a message indicating the endpoint is unhealthy.
2016-06-01 21:28:43 +03:00
#### Example
2017-06-21 01:24:50 +03:00
Check the default endpoint's health:
2016-06-01 21:28:43 +03:00
```bash
./etcdctl endpoint health
2016-09-09 12:49:52 +03:00
# 127.0.0.1:2379 is healthy: successfully committed proposal: took = 2.095242ms
2017-06-21 01:24:50 +03:00
```
Check all endpoints for the cluster associated with the default endpoint:
```bash
./etcdctl endpoint --cluster health
# http://127.0.0.1:2379 is healthy: successfully committed proposal: took = 1.060091ms
# http://127.0.0.1:22379 is healthy: successfully committed proposal: took = 903.138µs
# http://127.0.0.1:32379 is healthy: successfully committed proposal: took = 1.113848ms
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### ENDPOINT STATUS
ENDPOINT STATUS queries the status of each endpoint in the given endpoint list.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
##### Simple format
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a humanized table of each endpoint URL, ID, version, database size, leadership status, raft term, and raft status.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
##### JSON format
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a line of JSON encoding each endpoint URL, ID, version, database size, leadership status, raft term, and raft status.
2016-06-01 21:28:43 +03:00
#### Examples
2017-06-21 01:24:50 +03:00
Get the status for the default endpoint:
2016-06-01 21:28:43 +03:00
```bash
./etcdctl endpoint status
2016-09-09 12:49:52 +03:00
# 127.0.0.1:2379, 8211f1d0f64f3269, 3.0.0, 25 kB, false, 2, 63
2014-10-23 03:59:29 +04:00
```
2017-06-21 01:24:50 +03:00
Get the status for the default endpoint as JSON:
2016-06-01 21:28:43 +03:00
```bash
./etcdctl -w json endpoint status
2017-06-21 01:24:50 +03:00
# [{"Endpoint":"127.0.0.1:2379","Status":{"header":{"cluster_id":17237436991929493444,"member_id":9372538179322589801,"revision":2,"raft_term":2},"version":"3.0.0","dbSize":24576,"leader":18249187646912138824,"raftIndex":32623,"raftTerm":2}}]
2016-06-01 21:28:43 +03:00
```
2014-10-23 03:59:29 +04:00
2017-06-21 01:24:50 +03:00
Get the status for all endpoints in the cluster associated with the default endpoint:
2016-06-01 21:28:43 +03:00
```bash
2017-06-21 01:24:50 +03:00
./etcdctl -w table endpoint --cluster status
+------------------------+------------------+----------------+---------+-----------+-----------+------------+
| ENDPOINT | ID | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
+------------------------+------------------+----------------+---------+-----------+-----------+------------+
| http://127.0.0.1:2379 | 8211f1d0f64f3269 | 3.2.0-rc.1+git | 25 kB | false | 2 | 8 |
| http://127.0.0.1:22379 | 91bc3c398fb3c146 | 3.2.0-rc.1+git | 25 kB | false | 2 | 8 |
| http://127.0.0.1:32379 | fd422379fda50e48 | 3.2.0-rc.1+git | 25 kB | true | 2 | 8 |
+------------------------+------------------+----------------+---------+-----------+-----------+------------+
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
### ALARM \<subcommand\>
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Provides alarm related commands
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
### ALARM DISARM
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
`alarm disarm` Disarms all alarms
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
RPC: Alarm
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
`alarm:<alarm type>` if alarm is present and disarmed.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Examples
2016-06-01 21:28:43 +03:00
```bash
2016-12-13 04:03:09 +03:00
./etcdctl alarm disarm
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
If NOSPACE alarm is present:
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
```bash
./etcdctl alarm disarm
# alarm:NOSPACE
```
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
### ALARM LIST
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
`alarm list` lists all alarms.
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
RPC: Alarm
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-09-22 15:49:13 +03:00
2016-12-13 04:03:09 +03:00
`alarm:<alarm type>` if alarm is present, empty string if no alarms present.
2016-09-22 15:49:13 +03:00
2016-12-13 04:03:09 +03:00
#### Examples
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
```bash
./etcdctl alarm list
```
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
If NOSPACE alarm is present:
2016-06-01 21:28:43 +03:00
```bash
2016-12-13 04:03:09 +03:00
./etcdctl alarm list
# alarm:NOSPACE
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### DEFRAG
DEFRAG defragments the backend database file for a set of given endpoints. When an etcd member reclaims storage space
from deleted and compacted keys, the space is kept in a free list and the database file remains the same size. By defragmenting
the database, the etcd member releases this free space back to the file system.
2016-12-13 04:03:09 +03:00
#### Output
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
For each endpoints, prints a message indicating whether the endpoint was successfully defragmented.
2016-06-01 21:28:43 +03:00
#### Example
2016-12-13 04:03:09 +03:00
2016-06-01 21:28:43 +03:00
```bash
./etcdctl --endpoints=localhost:2379,badendpoint:2379 defrag
2016-09-09 12:49:52 +03:00
# Finished defragmenting etcd member[localhost:2379]
# Failed to defragment etcd member[badendpoint:2379] (grpc: timed out trying to connect)
2014-10-23 03:59:29 +04:00
```
2016-12-13 04:03:09 +03:00
#### Remarks
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
DEFRAG returns a zero exit code only if it succeeded defragmenting all given endpoints.
2016-06-01 21:28:43 +03:00
### SNAPSHOT \<subcommand\>
SNAPSHOT provides commands to restore a snapshot of a running etcd server into a fresh cluster.
### SNAPSHOT SAVE \<filename\>
SNAPSHOT SAVE writes a point-in-time snapshot of the etcd backend database to a file.
2016-12-13 04:03:09 +03:00
#### Output
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
The backend snapshot is written to the given file path.
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
#### Example
Save a snapshot to "snapshot.db":
```
./etcdctl snapshot save snapshot.db
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### SNAPSHOT RESTORE [options] \<filename\>
SNAPSHOT RESTORE creates an etcd data directory for an etcd cluster member from a backend database snapshot and a new cluster configuration. Restoring the snapshot into each member for a new cluster configuration will initialize a new etcd cluster preloaded by the snapshot data.
#### Options
The snapshot restore options closely resemble to those used in the `etcd` command for defining a cluster.
- data-dir -- Path to the data directory. Uses \<name\>.etcd if none given.
- initial-cluster -- The initial cluster configuration for the restored etcd cluster.
- initial-cluster-token -- Initial cluster token for the restored etcd cluster.
- initial-advertise-peer-urls -- List of peer URLs for the member being restored.
- name -- Human-readable name for the etcd cluster member being restored.
2016-09-21 13:47:32 +03:00
- skip-hash-check -- Ignore snapshot integrity hash value (required if copied from data directory)
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
A new etcd data directory initialized with the snapshot.
2016-06-01 21:28:43 +03:00
#### Example
Save a snapshot, restore into a new 3 node cluster, and start the cluster:
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
./etcdctl snapshot save snapshot.db
# restore members
bin/etcdctl snapshot restore snapshot.db --initial-cluster-token etcd-cluster-1 --initial-advertise-peer-urls http://127.0.0.1:12380 --name sshot1 --initial-cluster 'sshot1=http://127.0.0.1:12380,sshot2=http://127.0.0.1:22380,sshot3=http://127.0.0.1:32380'
bin/etcdctl snapshot restore snapshot.db --initial-cluster-token etcd-cluster-1 --initial-advertise-peer-urls http://127.0.0.1:22380 --name sshot2 --initial-cluster 'sshot1=http://127.0.0.1:12380,sshot2=http://127.0.0.1:22380,sshot3=http://127.0.0.1:32380'
bin/etcdctl snapshot restore snapshot.db --initial-cluster-token etcd-cluster-1 --initial-advertise-peer-urls http://127.0.0.1:32380 --name sshot3 --initial-cluster 'sshot1=http://127.0.0.1:12380,sshot2=http://127.0.0.1:22380,sshot3=http://127.0.0.1:32380'
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
# launch members
bin/etcd --name sshot1 --listen-client-urls http://127.0.0.1:2379 --advertise-client-urls http://127.0.0.1:2379 --listen-peer-urls http://127.0.0.1:12380 &
bin/etcd --name sshot2 --listen-client-urls http://127.0.0.1:22379 --advertise-client-urls http://127.0.0.1:22379 --listen-peer-urls http://127.0.0.1:22380 &
bin/etcd --name sshot3 --listen-client-urls http://127.0.0.1:32379 --advertise-client-urls http://127.0.0.1:32379 --listen-peer-urls http://127.0.0.1:32380 &
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
### SNAPSHOT STATUS \<filename\>
SNAPSHOT STATUS lists information about a given backend database snapshot file.
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
##### Simple format
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Prints a humanized table of the database hash, revision, total keys, and size.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
##### JSON format
2014-10-23 03:59:29 +04:00
2016-12-13 04:03:09 +03:00
Prints a line of JSON encoding the database hash, revision, total keys, and size.
2016-06-01 21:28:43 +03:00
#### Examples
```bash
./etcdctl snapshot status file.db
2016-09-09 12:49:52 +03:00
# cf1550fb, 3, 3, 25 kB
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
```bash
./etcdctl -write-out=json snapshot status file.db
2016-09-09 12:49:52 +03:00
# {"hash":3474280699,"revision":3,"totalKey":3,"totalSize":24576}
2014-10-23 03:59:29 +04:00
```
2016-06-01 21:28:43 +03:00
```bash
./etcdctl -write-out=table snapshot status file.db
+----------+----------+------------+------------+
| HASH | REVISION | TOTAL KEYS | TOTAL SIZE |
+----------+----------+------------+------------+
| cf1550fb | 3 | 3 | 25 kB |
+----------+----------+------------+------------+
```
2014-10-23 03:59:29 +04:00
2017-06-23 23:05:12 +03:00
### MOVE-LEADER \<hexadecimal-transferee-id\>
MOVE-LEADER transfers leadership from the leader to another member in the cluster.
#### Example
```bash
# to choose transferee
transferee_id=$(./etcdctl \
--endpoints localhost:12379,localhost:22379,localhost:32379 \
endpoint status | grep -m 1 "false" | awk -F', ' '{print $2}')
echo ${transferee_id}
# c89feb932daef420
# endpoints should include leader node
./etcdctl --endpoints ${transferee_ep} move-leader ${transferee_id}
# Error: no leader endpoint given at [localhost:22379 localhost:32379]
# request to leader with target node ID
./etcdctl --endpoints ${leader_ep} move-leader ${transferee_id}
# Leadership transferred from 45ddc0e800e20b93 to c89feb932daef420
```
2016-12-13 04:03:09 +03:00
## Concurrency commands
2014-10-23 03:59:29 +04:00
2017-05-24 23:57:16 +03:00
### LOCK \<lockname\> [command arg1 arg2 ...]
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
LOCK acquires a distributed named mutex with a given name. Once the lock is acquired, it will be held until etcdctl is terminated.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
Once the lock is acquired, the result for the GET on the unique lock holder key is displayed.
2014-10-23 03:59:29 +04:00
2017-05-24 23:57:16 +03:00
If a command is given, it will be launched with environment variables `ETCD_LOCK_KEY` and `ETCD_LOCK_REV` set to the lock's holder key and revision.
2016-12-13 04:03:09 +03:00
#### Example
2017-05-24 23:57:16 +03:00
Acquire lock with standard output display:
2016-12-13 04:03:09 +03:00
```bash
./etcdctl lock mylock
# mylock/1234534535445
```
2016-01-15 13:58:09 +03:00
2017-05-24 23:57:16 +03:00
Acquire lock and execute `echo lock acquired` :
```bash
./etcdctl lock mylock echo lock acquired
# lock acquired
```
2016-12-13 04:03:09 +03:00
#### Remarks
2016-01-15 13:58:09 +03:00
2016-12-13 04:03:09 +03:00
LOCK returns a zero exit code only if it is terminated by a signal and releases the lock.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
If LOCK is abnormally terminated or fails to contact the cluster to release the lock, the lock will remain held until the lease expires. Progress may be delayed by up to the default lease length of 60 seconds.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
### ELECT [options] \<election-name\> [proposal]
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
ELECT participates on a named election. A node announces its candidacy in the election by providing
a proposal value. If a node wishes to observe the election, ELECT listens for new leaders values.
Whenever a leader is elected, its proposal is given as output.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
#### Options
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
- listen -- observe the election.
2016-01-15 13:58:09 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
- If a candidate, ELECT displays the GET on the leader key once the node is elected election.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
- If observing, ELECT streams the result for a GET on the leader key for the current election and all future elections.
2015-07-11 07:41:30 +03:00
2016-06-01 21:28:43 +03:00
#### Example
2015-07-11 07:41:30 +03:00
2016-12-13 04:03:09 +03:00
```bash
./etcdctl elect myelection foo
# myelection/1456952310051373265
# foo
2015-07-11 07:41:30 +03:00
```
2016-12-13 04:03:09 +03:00
#### Remarks
ELECT returns a zero exit code only if it is terminated by a signal and can revoke its candidacy or leadership, if any.
If a candidate is abnormally terminated, election rogress may be delayed by up to the default lease length of 60 seconds.
## Authentication commands
### AUTH \<enable or disable\>
`auth enable` activates authentication on an etcd cluster and `auth disable` deactivates. When authentication is enabled, etcd checks all requests for appropriate authorization.
RPC: AuthEnable/AuthDisable
#### Output
`Authentication Enabled` .
#### Examples
```bash
./etcdctl user add root
# Password of root:#type password for root
# Type password of root again for confirmation:#re-type password for root
# User root created
./etcdctl user grant-role root root
# Role root is granted to user root
./etcdctl user get root
# User: root
# Roles: root
./etcdctl role add root
# Role root created
./etcdctl role get root
# Role root
# KV Read:
# KV Write:
./etcdctl auth enable
# Authentication Enabled
2016-06-01 21:28:43 +03:00
```
2016-09-23 06:35:08 +03:00
### ROLE \<subcommand\>
2016-06-21 20:52:51 +03:00
2016-09-23 06:35:08 +03:00
ROLE is used to specify differnt roles which can be assigned to etcd user(s).
2016-06-21 20:52:51 +03:00
### ROLE ADD \<role name\>
`role add` creates a role.
2016-12-13 04:03:09 +03:00
RPC: RoleAdd
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`Role <role name> created` .
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 role add myrole
# Role myrole created
2016-06-21 20:52:51 +03:00
```
### ROLE GET \<role name\>
`role get` lists detailed role information.
2016-12-13 04:03:09 +03:00
RPC: RoleGet
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
Detailed role information.
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 role get myrole
2016-06-21 20:52:51 +03:00
# Role myrole
# KV Read:
2016-09-09 12:49:52 +03:00
# foo
2016-06-21 20:52:51 +03:00
# KV Write:
2016-09-09 12:49:52 +03:00
# foo
2016-06-21 20:52:51 +03:00
```
2016-12-13 04:03:09 +03:00
### ROLE DELETE \<role name\>
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`role delete` deletes a role.
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
RPC: RoleDelete
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Output
`Role <role name> deleted` .
#### Examples
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
```bash
./etcdctl --user=root:123 role delete myrole
# Role myrole deleted
```
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
### ROLE LIST \<role name\>
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`role list` lists all roles in etcd.
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
RPC: RoleList
#### Output
A role per line.
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-12-13 04:03:09 +03:00
./etcdctl --user=root:123 role list
# roleA
# roleB
# myrole
2016-06-21 20:52:51 +03:00
```
2016-12-13 04:03:09 +03:00
### ROLE GRANT-PERMISSION [options] \<role name\> \<permission type\> \<key\> [endkey]
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`role grant-permission` grants a key to a role.
RPC: RoleGrantPermission
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Options
2016-06-21 20:52:51 +03:00
2017-05-19 21:20:55 +03:00
- from-key -- grant a permission of keys that are greater than or equal to the given key using byte compare
2016-12-13 04:03:09 +03:00
- prefix -- grant a prefix permission
2016-06-21 20:52:51 +03:00
2017-05-19 21:20:55 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2017-05-03 20:01:18 +03:00
`Role <role name> updated` .
2016-06-21 20:52:51 +03:00
#### Examples
2017-05-19 21:20:55 +03:00
Grant read and write permission on the key `foo` to role `myrole` :
2016-09-15 09:32:38 +03:00
```bash
2016-12-13 04:03:09 +03:00
./etcdctl --user=root:123 role grant-permission myrole readwrite foo
# Role myrole updated
2016-06-21 20:52:51 +03:00
```
2017-05-19 21:20:55 +03:00
Grant read permission on the wildcard key pattern `foo/*` to role `myrole` :
```bash
./etcdctl --user=root:123 role grant-permission --prefix myrole readwrite foo/
# Role myrole updated
```
2016-12-13 04:03:09 +03:00
### ROLE REVOKE-PERMISSION \<role name\> \<permission type\> \<key\> [endkey]
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`role revoke-permission` revokes a key from a role.
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
RPC: RoleRevokePermission
2016-06-21 20:52:51 +03:00
2017-05-19 21:20:55 +03:00
#### Options
- from-key -- revoke a permission of keys that are greater than or equal to the given key using byte compare
- prefix -- revoke a prefix permission
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`Permission of key <key> is revoked from role <role name>` for single key. `Permission of range [<key>, <endkey>) is revoked from role <role name>` for a key range. Exit code is zero.
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-12-13 04:03:09 +03:00
./etcdctl --user=root:123 role revoke-permission myrole foo
# Permission of key foo is revoked from role myrole
2016-06-21 20:52:51 +03:00
```
2016-09-23 06:35:08 +03:00
### USER \<subcommand\>
2016-06-21 20:52:51 +03:00
2016-09-23 06:35:08 +03:00
USER provides commands for managing users of etcd.
2016-11-03 20:47:45 +03:00
### USER ADD \<user name or user:password\> [options]
2016-09-23 06:35:08 +03:00
`user add` creates a user.
2016-12-13 04:03:09 +03:00
RPC: UserAdd
2016-09-23 06:35:08 +03:00
#### Options
- interactive -- Read password from stdin instead of interactive terminal
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`User <user name> created` .
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-23 06:35:08 +03:00
./etcdctl --user=root:123 user add myuser
# Password of myuser: #type password for my user
# Type password of myuser again for confirmation:#re-type password for my user
# User myuser created
2016-06-21 20:52:51 +03:00
```
2016-09-23 06:35:08 +03:00
### USER GET \<user name\> [options]
2016-06-21 20:52:51 +03:00
`user get` lists detailed user information.
2016-12-13 04:03:09 +03:00
RPC: UserGet
2016-09-23 06:35:08 +03:00
#### Options
- detail -- Show permissions of roles granted to the user
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
Detailed user information.
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 user get myuser
2016-06-21 20:52:51 +03:00
# User: myuser
# Roles:
```
2016-12-13 04:03:09 +03:00
### USER DELETE \<user name\>
`user delete` deletes a user.
RPC: UserDelete
#### Output
`User <user name> deleted` .
#### Examples
```bash
./etcdctl --user=root:123 user delete myuser
# User myuser deleted
```
### USER LIST
`user list` lists detailed user information.
RPC: UserList
#### Output
- List of users, one per line.
#### Examples
```bash
./etcdctl --user=root:123 user list
# user1
# user2
# myuser
```
2016-09-23 06:35:08 +03:00
### USER PASSWD \<user name\> [options]
2016-06-21 20:52:51 +03:00
`user passwd` changes a user's password.
2016-12-13 04:03:09 +03:00
RPC: UserChangePassword
2016-06-21 20:52:51 +03:00
#### Options
- interactive -- if true, read password in interactive terminal
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`Password updated` .
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 user passwd myuser
# Password of myuser: #type new password for my user
2016-09-21 01:15:30 +03:00
# Type password of myuser again for confirmation: #re-type the new password for my user
2016-06-21 20:52:51 +03:00
# Password updated
```
### USER GRANT-ROLE \<user name\> \<role name\>
`user grant-role` grants a role to a user
2016-12-13 04:03:09 +03:00
RPC: UserGrantRole
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`Role <role name> is granted to user <user name>` .
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 user grant-role userA roleA
2016-06-21 20:52:51 +03:00
# Role roleA is granted to user userA
```
### USER REVOKE-ROLE \<user name\> \<role name\>
`user revoke-role` revokes a role from a user
2016-12-13 04:03:09 +03:00
RPC: UserRevokeRole
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-06-21 20:52:51 +03:00
2016-12-13 04:03:09 +03:00
`Role <role name> is revoked from user <user name>` .
2016-06-21 20:52:51 +03:00
#### Examples
2016-09-15 09:32:38 +03:00
```bash
2016-09-09 12:49:52 +03:00
./etcdctl --user=root:123 user revoke-role userA roleA
2016-06-21 20:52:51 +03:00
# Role roleA is revoked from user userA
```
2016-12-13 04:03:09 +03:00
## Utility commands
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
### MAKE-MIRROR [options] \<destination\>
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
[make-mirror][mirror] mirrors a key prefix in an etcd cluster to a destination etcd cluster.
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Options
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- dest-cacert -- TLS certificate authority file for destination cluster
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- dest-cert -- TLS certificate file for destination cluster
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- dest-key -- TLS key file for destination cluster
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- prefix -- The key-value prefix to mirror
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- dest-prefix -- The destination prefix to mirror a prefix to a different prefix in the destination cluster
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- no-dest-prefix -- Mirror key-values to the root of the destination cluster
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- dest-insecure-transport -- Disable transport security for client connections
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
The approximate total number of keys transferred to the destination cluster, updated every 30 seconds.
2016-09-23 06:35:08 +03:00
#### Examples
2016-12-13 04:03:09 +03:00
```
./etcdctl make-mirror mirror.example.com:2379
# 10
# 18
2016-09-23 06:35:08 +03:00
```
2016-12-13 04:03:09 +03:00
[mirror]: ./doc/mirror_maker.md
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
### MIGRATE [options]
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
Migrates keys in a v2 store to a v3 mvcc store. Users should run migration command for all members in the cluster.
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Options
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- data-dir -- Path to the data directory
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- wal-dir -- Path to the WAL directory
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
- transformer -- Path to the user-provided transformer program (default if not provided)
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
No output on success.
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Default transformer
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
If user does not provide a transformer program, migrate command will use the default transformer. The default transformer transforms `storev2` formatted keys into `mvcc` formatted keys according to the following Go program:
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
```go
func transform(n *storev2.Node) *mvccpb.KeyValue {
if n.Dir {
return nil
}
kv := & mvccpb.KeyValue{
Key: []byte(n.Key),
Value: []byte(n.Value),
CreateRevision: int64(n.CreatedIndex),
ModRevision: int64(n.ModifiedIndex),
Version: 1,
}
return kv
}
2016-09-23 06:35:08 +03:00
```
2016-12-13 04:03:09 +03:00
#### User-provided transformer
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
Users can provide a customized 1:n transformer function that transforms a key from the v2 store to any number of keys in the mvcc store. The migration program writes JSON formatted [v2 store keys][v2key] to the transformer program's stdin, reads protobuf formatted [mvcc keys][v3key] back from the transformer program's stdout, and finishes migration by saving the transformed keys into the mvcc store.
The provided transformer should read until EOF and flush the stdout before exiting to ensure data integrity.
#### Example
```
2017-03-05 04:42:27 +03:00
./etcdctl migrate --data-dir=/var/etcd --transformer=k8s-transformer
2016-12-13 04:03:09 +03:00
# finished transforming keys
```
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
### VERSION
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
Prints the version of etcdctl.
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
#### Output
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
Prints etcd version and API version.
2016-09-23 06:35:08 +03:00
#### Examples
```bash
2016-12-13 04:03:09 +03:00
./etcdctl version
# etcdctl version: 3.1.0-alpha.0+git
# API version: 3.1
2016-09-23 06:35:08 +03:00
```
2016-12-13 04:03:09 +03:00
## Exit codes
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
For all commands, a successful execution return a zero exit code. All failures will return non-zero exit codes.
2016-09-23 06:35:08 +03:00
2016-12-13 04:03:09 +03:00
## Output formats
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
All commands accept an output format by setting `-w` or `--write-out` . All commands default to the "simple" output format, which is meant to be human-readable. The simple format is listed in each command's `Output` description since it is customized for each command. If a command has a corresponding RPC, it will respect all output formats.
2016-06-01 21:28:43 +03:00
2016-12-13 04:03:09 +03:00
If a command fails, returning a non-zero exit code, an error string will be written to standard error regardless of output format.
### Simple
A format meant to be easy to parse and human-readable. Specific to each command.
### JSON
The JSON encoding of the command's [RPC response][etcdrpc]. Since etcd's RPCs use byte strings, the JSON output will encode keys and values in base64.
Some commands without an RPC also support JSON; see the command's `Output` description.
### Protobuf
The protobuf encoding of the command's [RPC response][etcdrpc]. If an RPC is streaming, the stream messages will be concetenated. If an RPC is not given for a command, the protobuf output is not defined.
### Fields
An output format similar to JSON but meant to parse with coreutils. For an integer field named `Field` , it writes a line in the format `"Field" : %d` where `%d` is go's integer formatting. For byte array fields, it writes `"Field" : %q` where `%q` is go's quoted string formatting (e.g., `[]byte{'a', '\n'}` is written as `"a\n"` ).
2016-06-01 21:28:43 +03:00
## Compatibility Support
etcdctl is still in its early stage. We try out best to ensure fully compatible releases, however we might break compatibility to fix bugs or improve commands. If we intend to release a version of etcdctl with backward incompatibilities, we will provide notice prior to release and have instructions on how to upgrade.
2015-07-11 07:41:30 +03:00
2016-06-01 21:28:43 +03:00
### Input Compatibility
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
Input includes the command name, its flags, and its arguments. We ensure backward compatibility of the input of normal commands in non-interactive mode.
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
### Output Compatibility
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
Output includes output from etcdctl and its exit code. etcdctl provides `simple` output format by default.
We ensure compatibility for the `simple` output format of normal commands in non-interactive mode. Currently, we do not ensure
backward compatibility for `JSON` format and the format in non-interactive mode. Currently, we do not ensure backward compatibility of utility commands.
2014-10-23 03:59:29 +04:00
2016-06-01 21:28:43 +03:00
### TODO: compatibility with etcd server
2014-10-23 03:59:29 +04:00
2016-01-15 13:58:09 +03:00
[etcd]: https://github.com/coreos/etcd
2016-06-01 21:28:43 +03:00
[READMEv2]: READMEv2.md
[v2key]: ../store/node_extern.go#L28-L37
[v3key]: ../mvcc/mvccpb/kv.proto#L12-L29
2016-12-13 04:03:09 +03:00
[etcdrpc]: ../etcdserver/etcdserverpb/rpc.proto
[storagerpc]: ../mvcc/mvccpb/kv.proto
2017-03-05 04:42:27 +03:00
[member_list_rpc]: ../etcdserver/etcdserverpb/rpc.proto#L493-L497