github.com/matm/etcd@v0.3.1-0.20140328024009-5b4a473f1453/Documentation/modules.md (about) 1 ## Modules 2 3 etcd has a number of modules that are built on top of the core etcd API. 4 These modules provide things like dashboards, locks and leader election. 5 6 ### Dashboard 7 8 An HTML dashboard can be found at `http://127.0.0.1:4001/mod/dashboard/`. 9 This dashboard is compiled into the etcd binary and uses the same API as regular etcd clients. 10 11 Use the `-cors='*'` flag to allow your browser to request information from the current master as it changes. 12 13 ### Lock 14 15 The Lock module implements a fair lock that can be used when lots of clients want access to a single resource. 16 A lock can be associated with a value. 17 The value is unique so if a lock tries to request a value that is already queued for a lock then it will find it and watch until that value obtains the lock. 18 You may supply a `timeout` which will cancel the lock request if it is not obtained within `timeout` seconds. If `timeout` is not supplied, it is presumed to be infinite. If `timeout` is `0`, the lock request will fail if it is not immediately acquired. 19 If you lock the same value on a key from two separate curl sessions they'll both return at the same time. 20 21 Here's the API: 22 23 **Acquire a lock (with no value) for "customer1"** 24 25 ```sh 26 curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 27 ``` 28 29 **Acquire a lock for "customer1" that is associated with the value "bar"** 30 31 ```sh 32 curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar 33 ``` 34 35 **Acquire a lock for "customer1" that is associated with the value "bar" only if it is done within 2 seconds** 36 37 ```sh 38 curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar -d timeout=2 39 ``` 40 41 **Renew the TTL on the "customer1" lock for index 2** 42 43 ```sh 44 curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d index=2 45 ``` 46 47 **Renew the TTL on the "customer1" lock for value "customer1"** 48 49 ```sh 50 curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar 51 ``` 52 53 **Retrieve the current value for the "customer1" lock.** 54 55 ```sh 56 curl http://127.0.0.1:4001/mod/v2/lock/customer1 57 ``` 58 59 **Retrieve the current index for the "customer1" lock** 60 61 ```sh 62 curl http://127.0.0.1:4001/mod/v2/lock/customer1?field=index 63 ``` 64 65 **Delete the "customer1" lock with the index 2** 66 67 ```sh 68 curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?index=2 69 ``` 70 71 **Delete the "customer1" lock with the value "bar"** 72 73 ```sh 74 curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?value=bar 75 ``` 76 77 78 ### Leader Election 79 80 The Leader Election module wraps the Lock module to allow clients to come to consensus on a single value. 81 This is useful when you want one server to process at a time but allow other servers to fail over. 82 The API is similar to the Lock module but is limited to simple strings values. 83 84 Here's the API: 85 86 **Attempt to set a value for the "order_processing" leader key:** 87 88 ```sh 89 curl -X PUT http://127.0.0.1:4001/mod/v2/leader/order_processing?ttl=60 -d name=myserver1.foo.com 90 ``` 91 92 **Retrieve the current value for the "order_processing" leader key:** 93 94 ```sh 95 curl http://127.0.0.1:4001/mod/v2/leader/order_processing 96 myserver1.foo.com 97 ``` 98 99 **Remove a value from the "order_processing" leader key:** 100 101 ```sh 102 curl -X DELETE http://127.0.0.1:4001/mod/v2/leader/order_processing?name=myserver1.foo.com 103 ``` 104 105 If multiple clients attempt to set the value for a key then only one will succeed. 106 The other clients will hang until the current value is removed because of TTL or because of a `DELETE` operation. 107 Multiple clients can submit the same value and will all be notified when that value succeeds. 108 109 To update the TTL of a value simply reissue the same `PUT` command that you used to set the value. 110 111 112