go.etcd.io/etcd@v3.3.27+incompatible/etcdctl/READMEv2.md (about) 1 etcdctl 2 ======== 3 4 `etcdctl` is a command line client for [etcd][etcd]. 5 It can be used in scripts or for administrators to explore an etcd cluster. 6 7 ## Getting etcdctl 8 9 The latest release is available as a binary at [Github][github-release] along with etcd. 10 11 etcdctl can also be built from source using the build script found in the parent directory. 12 13 ## Configuration 14 ### --debug 15 + output cURL commands which can be used to reproduce the request 16 17 ### --no-sync 18 + don't synchronize cluster information before sending request 19 + Use this to access non-published client endpoints 20 + Without this flag, values from `--endpoint` flag will be overwritten by etcd cluster when it does internal sync. 21 22 ### --output, -o 23 + output response in the given format (`simple`, `extended` or `json`) 24 + default: `"simple"` 25 26 ### --discovery-srv, -D 27 + domain name to query for SRV records describing cluster endpoints 28 + default: none 29 + env variable: ETCDCTL_DISCOVERY_SRV 30 31 ### --peers 32 + a comma-delimited list of machine addresses in the cluster 33 + default: `"http://127.0.0.1:2379"` 34 + env variable: ETCDCTL_PEERS 35 36 ### --endpoint 37 + a comma-delimited list of machine addresses in the cluster 38 + default: `"http://127.0.0.1:2379"` 39 + env variable: ETCDCTL_ENDPOINT 40 + Without `--no-sync` flag, this will be overwritten by etcd cluster when it does internal sync. 41 42 ### --cert-file 43 + identify HTTPS client using this SSL certificate file 44 + default: none 45 + env variable: ETCDCTL_CERT_FILE 46 47 ### --key-file 48 + identify HTTPS client using this SSL key file 49 + default: none 50 + env variable: ETCDCTL_KEY_FILE 51 52 ### --ca-file 53 + verify certificates of HTTPS-enabled servers using this CA bundle 54 + default: none 55 + env variable: ETCDCTL_CA_FILE 56 57 ### --username, -u 58 + provide username[:password] and prompt if password is not supplied 59 + default: none 60 + env variable: ETCDCTL_USERNAME 61 62 ### --timeout 63 + connection timeout per request 64 + default: `"1s"` 65 66 ### --total-timeout 67 + timeout for the command execution (except watch) 68 + default: `"5s"` 69 70 ## Usage 71 72 ### Setting Key Values 73 74 Set a value on the `/foo/bar` key: 75 76 ```sh 77 $ etcdctl set /foo/bar "Hello world" 78 Hello world 79 ``` 80 81 Set a value on the `/foo/bar` key with a value that expires in 60 seconds: 82 83 ```sh 84 $ etcdctl set /foo/bar "Hello world" --ttl 60 85 Hello world 86 ``` 87 88 Conditionally set a value on `/foo/bar` if the previous value was "Hello world": 89 90 ```sh 91 $ etcdctl set /foo/bar "Goodbye world" --swap-with-value "Hello world" 92 Goodbye world 93 ``` 94 95 Conditionally set a value on `/foo/bar` if the previous etcd index was 12: 96 97 ```sh 98 $ etcdctl set /foo/bar "Goodbye world" --swap-with-index 12 99 Goodbye world 100 ``` 101 102 Create a new key `/foo/bar`, only if the key did not previously exist: 103 104 ```sh 105 $ etcdctl mk /foo/new_bar "Hello world" 106 Hello world 107 ``` 108 109 Create a new in-order key under dir `/fooDir`: 110 111 ```sh 112 $ etcdctl mk --in-order /fooDir "Hello world" 113 ``` 114 115 Create a new dir `/fooDir`, only if the key did not previously exist: 116 117 ```sh 118 $ etcdctl mkdir /fooDir 119 ``` 120 121 Update an existing key `/foo/bar`, only if the key already existed: 122 123 ```sh 124 $ etcdctl update /foo/bar "Hola mundo" 125 Hola mundo 126 ``` 127 128 Create or update a directory called `/mydir`: 129 130 ```sh 131 $ etcdctl setdir /mydir 132 ``` 133 134 135 ### Retrieving a key value 136 137 Get the current value for a single key in the local etcd node: 138 139 ```sh 140 $ etcdctl get /foo/bar 141 Hello world 142 ``` 143 144 Get the value of a key with additional metadata in a parseable format: 145 146 ```sh 147 $ etcdctl -o extended get /foo/bar 148 Key: /foo/bar 149 Modified-Index: 72 150 TTL: 0 151 Etcd-Index: 72 152 Raft-Index: 5611 153 Raft-Term: 1 154 155 Hello World 156 ``` 157 158 ### Listing a directory 159 160 Explore the keyspace using the `ls` command 161 162 ```sh 163 $ etcdctl ls 164 /akey 165 /adir 166 $ etcdctl ls /adir 167 /adir/key1 168 /adir/key2 169 ``` 170 171 Add `--recursive` to recursively list subdirectories encountered. 172 173 ```sh 174 $ etcdctl ls --recursive 175 /akey 176 /adir 177 /adir/key1 178 /adir/key2 179 ``` 180 181 Directories can also have a trailing `/` added to output using `-p`. 182 183 ```sh 184 $ etcdctl ls -p 185 /akey 186 /adir/ 187 ``` 188 189 ### Deleting a key 190 191 Delete a key: 192 193 ```sh 194 $ etcdctl rm /foo/bar 195 ``` 196 197 Delete an empty directory or a key-value pair 198 199 ```sh 200 $ etcdctl rmdir /path/to/dir 201 ``` 202 203 or 204 205 ```sh 206 $ etcdctl rm /path/to/dir --dir 207 ``` 208 209 Recursively delete a key and all child keys: 210 211 ```sh 212 $ etcdctl rm /path/to/dir --recursive 213 ``` 214 215 Conditionally delete `/foo/bar` if the previous value was "Hello world": 216 217 ```sh 218 $ etcdctl rm /foo/bar --with-value "Hello world" 219 ``` 220 221 Conditionally delete `/foo/bar` if the previous etcd index was 12: 222 223 ```sh 224 $ etcdctl rm /foo/bar --with-index 12 225 ``` 226 227 ### Watching for changes 228 229 Watch for only the next change on a key: 230 231 ```sh 232 $ etcdctl watch /foo/bar 233 Hello world 234 ``` 235 236 Continuously watch a key: 237 238 ```sh 239 $ etcdctl watch /foo/bar --forever 240 Hello world 241 .... client hangs forever until ctrl+C printing values as key change 242 ``` 243 244 Continuously watch a key, starting with a given etcd index: 245 246 ```sh 247 $ etcdctl watch /foo/bar --forever --index 12 248 Hello world 249 .... client hangs forever until ctrl+C printing values as key change 250 ``` 251 252 Continuously watch a key and exec a program: 253 254 ```sh 255 $ etcdctl exec-watch /foo/bar -- sh -c "env | grep ETCD" 256 ETCD_WATCH_ACTION=set 257 ETCD_WATCH_VALUE=My configuration stuff 258 ETCD_WATCH_MODIFIED_INDEX=1999 259 ETCD_WATCH_KEY=/foo/bar 260 ETCD_WATCH_ACTION=set 261 ETCD_WATCH_VALUE=My new configuration stuff 262 ETCD_WATCH_MODIFIED_INDEX=2000 263 ETCD_WATCH_KEY=/foo/bar 264 ``` 265 266 Continuously and recursively watch a key and exec a program: 267 ```sh 268 $ etcdctl exec-watch --recursive /foo -- sh -c "env | grep ETCD" 269 ETCD_WATCH_ACTION=set 270 ETCD_WATCH_VALUE=My configuration stuff 271 ETCD_WATCH_MODIFIED_INDEX=1999 272 ETCD_WATCH_KEY=/foo/bar 273 ETCD_WATCH_ACTION=set 274 ETCD_WATCH_VALUE=My new configuration stuff 275 ETCD_WATCH_MODIFIED_INDEX=2000 276 ETCD_WATCH_KEY=/foo/barbar 277 ``` 278 279 ## Return Codes 280 281 The following exit codes can be returned from etcdctl: 282 283 ``` 284 0 Success 285 1 Malformed etcdctl arguments 286 2 Failed to connect to host 287 3 Failed to auth (client cert rejected, ca validation failure, etc) 288 4 400 error from etcd 289 5 500 error from etcd 290 ``` 291 292 ## Endpoint 293 294 If the etcd cluster isn't available on `http://127.0.0.1:2379`, specify a `--endpoint` flag or `ETCDCTL_ENDPOINT` environment variable. One endpoint or a comma-separated list of endpoints can be listed. This option is ignored if the `--discovery-srv` option is provided. 295 296 ```sh 297 ETCDCTL_ENDPOINT="http://10.0.28.1:4002" etcdctl set my-key to-a-value 298 ETCDCTL_ENDPOINT="http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002" etcdctl set my-key to-a-value 299 etcdctl --endpoint http://10.0.28.1:4002 my-key to-a-value 300 etcdctl --endpoint http://10.0.28.1:4002,http://10.0.28.2:4002,http://10.0.28.3:4002 etcdctl set my-key to-a-value 301 ``` 302 303 ## Username and Password 304 305 If the etcd cluster is protected by [authentication][authentication], specify username and password using the [`--username`][username-flag] or `ETCDCTL_USERNAME` environment variable. When `--username` flag or `ETCDCTL_USERNAME` environment variable doesn't contain password, etcdctl will prompt password in interactive mode. 306 307 ```sh 308 ETCDCTL_USERNAME="root:password" etcdctl set my-key to-a-value 309 ``` 310 311 ## DNS Discovery 312 313 To discover the etcd cluster through domain SRV records, specify a `--discovery-srv` flag or `ETCDCTL_DISCOVERY_SRV` environment variable. This option takes precedence over the `--endpoint` flag. 314 315 ```sh 316 ETCDCTL_DISCOVERY_SRV="some-domain" etcdctl set my-key to-a-value 317 etcdctl --discovery-srv some-domain set my-key to-a-value 318 ``` 319 320 ## Project Details 321 322 ### Versioning 323 324 etcdctl uses [semantic versioning][semver]. 325 Releases will follow lockstep with the etcd release cycle. 326 327 ### License 328 329 etcdctl is under the Apache 2.0 license. See the [LICENSE][license] file for details. 330 331 [authentication]: ../Documentation/v2/authentication.md 332 [etcd]: https://github.com/coreos/etcd 333 [github-release]: https://github.com/coreos/etcd/releases/ 334 [license]: ../LICENSE 335 [semver]: http://semver.org/ 336 [username-flag]: #--username--u