etcd分布式存储系统 v3.4.30.zip

etcdctl ======== `etcdctl` is a command line client for [etcd][etcd]. The v3 API is used by default on master branch. For the v2 API, make sure to set environment variable `ETCDCTL_API=2`. See also [READMEv2][READMEv2]. If using released versions earlier than v3.4, set `ETCDCTL_API=3` to use v3 API. 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(`_`). ## Key-value commands ### PUT [options] \<key\> \<value\> PUT assigns the specified value with the specified key. If key already holds a value, it is overwritten. RPC: Put #### Options - lease -- lease ID (in hexadecimal) to attach to the key. - prev-kv -- return the previous key-value pair before modification. - ignore-value -- updates the key using its current value. - ignore-lease -- updates the key using its current lease. #### Output `OK` #### Examples ```bash ./etcdctl put foo bar --lease=1234abcd # OK ./etcdctl get foo # foo # bar ./etcdctl put foo --ignore-value # to detache lease # OK ``` ```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 ``` ```bash ./etcdctl put foo bar1 --prev-kv # OK # foo # bar ./etcdctl get foo # foo # bar1 ``` #### Remarks If \<value\> isn't given as command line argument, this command tries to read the value from standard input. When \<value\> begins with '-', \<value\> is interpreted as a flag. Insert '--' for workaround: ```bash ./etcdctl put <key> -- <value> ./etcdctl put -- <key> <value> ``` Providing \<value\> in a new line after using `carriage return` is not supported and etcdctl may hang in that case. For example, following case is not supported: ```bash ./etcdctl put <key>\r <value> ``` A \<value\> can have multiple lines or spaces but it must be provided with a double-quote as demonstrated below: ```bash ./etcdctl put foo "bar1 2 3" ``` ### GET [options] \<key\> [range_end] GET gets the key or a range of keys [key, range_end) if range_end is given. RPC: Range #### 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 - print-value-only -- print only value when used with write-out=simple - 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 #### Output \<key\>\n\<value\>\n\<next_key\>\n\<next_value\>... #### Examples First, populate etcd with some keys: ```bash ./etcdctl put foo bar # OK ./etcdctl put foo1 bar1 # OK ./etcdctl put foo2 bar2 # OK ./etcdctl put foo3 bar3 # OK ``` Get the key named `foo`: ```bash ./etcdctl get foo # foo # bar ``` Get all keys: ```bash ./etcdctl get --from-key '' # foo # bar # foo1 # bar1 # foo2 # foo2 # foo3 # bar3 ``` Get all keys with names greater than or equal to `foo1`: ```bash ./etcdctl get --from-key foo1 # foo1 # bar1 # foo2 # bar2 # foo3 # bar3 ``` Get keys with names greater than or equal to `foo1` and less than `foo3`: ```bash ./etcdctl get foo1 foo3 # foo1 # bar1 # foo2 # bar2 ``` #### Remarks 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. ### DEL [options] \<key\> [range_end] Removes the specified key or range of keys [key, range_end) if range_end is given. RPC: DeleteRange #### Options - prefix -- delete keys by matching prefix - prev-kv -- return deleted key-value pairs - from-key -- delete keys that are greater than or equal to the given key using byte compare #### Output Prints the number of keys that were removed in decimal if DEL succeeded. #### Examples ```bash ./etcdctl put foo bar # OK ./etcdctl del foo # 1 ./etcdctl get foo ``` ```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 ``` ### 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. RPC: Txn #### Options - hex -- print out keys and values as hex encoded strings. - interactive -- input transaction with interactive prompting. #### Input Format ```ebnf <Txn> ::= <CMP>* "\n" <THEN> "\n" <ELSE> "\n" <CMP> ::= (<CMPCREATE>|<CMPMOD>|<CMPVAL>|<CMPVER>|<CMPLEASE>) "\n" <CMPOP> ::= "<" | "=" | ">" <CMPCREATE> := ("c"|"create")"("<KEY>")" <CMPOP> <REVISION> <CMPMOD> ::= ("m"|"mod")"("<KEY>")" <CMPOP> <REVISION> <CMPVAL> ::= ("val"|"value")"("<KEY>")" <CMPOP> <VALUE> <CMPVER> ::= ("ver"|"version")"("<KEY>")" <CMPOP> <VERSION> <CMPLEASE> ::= "lease("<KEY>")" <CMPOP> <LEASE> <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]+"\"" <LEASE> ::= "\""[0-9]+\"" ``` #### Output `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. #### Examples txn in interactive mode: ```bash ./etcdctl txn -i # compares: mod("key1") > "0" # success requests (get, put, delete): put key1 "overwrote-key1" # failure requests (get, put, delete): put key1 "created-key1" put key2 "some extra key" # FAILURE # OK # OK ``` txn in non-interactive mode: ```bash ./etcdctl txn <<<'mod("key1") > "0" put key1 "overwrote-key1" put key1 "created-key1" put key2 "some extra key" ' # FAILURE # OK # OK ``` #### Remarks When using multi-line values within a TXN command, newlines must be represented as `\n`. Literal newlines will cause parsing failures. This differs from other commands (such as PUT) where the shell will convert literal newlines for us. For example: ```bash ./etcdctl txn <<<'mod("key1") > "0" put key1 "overwrote-key1" put key1 "created-key1" put key2 "this is\na multi-line\nvalue" ' # FAILURE # OK # OK ``` ### 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 ``` ### WATCH [options] [key or prefix] [range_end] [--] [exec-command arg1 arg2 ...] 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". RPC: Watch #### Options - hex -- print out key and value as hex encode string - interactive -- begins an i