github.com/jpetazzo/etcd@v0.2.1-0.20140113055439-97f1363afac5/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 If you lock the same value on a key from two separate curl sessions they'll both return at the same time. 19 20 Here's the API: 21 22 **Acquire a lock (with no value) for "customer1"** 23 24 ```sh 25 curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 26 ``` 27 28 **Acquire a lock for "customer1" that is associated with the value "bar"** 29 30 ```sh 31 curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar 32 ``` 33 34 **Renew the TTL on the "customer1" lock for index 2** 35 36 ```sh 37 curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d index=2 38 ``` 39 40 **Renew the TTL on the "customer1" lock for value "customer1"** 41 42 ```sh 43 curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar 44 ``` 45 46 **Retrieve the current value for the "customer1" lock.** 47 48 ```sh 49 curl http://127.0.0.1:4001/mod/v2/lock/customer1 50 ``` 51 52 **Retrieve the current index for the "customer1" lock** 53 54 ```sh 55 curl http://127.0.0.1:4001/mod/v2/lock/customer1?field=index 56 ``` 57 58 **Delete the "customer1" lock with the index 2** 59 60 ```sh 61 curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?index=2 62 ``` 63 64 **Delete the "customer1" lock with the value "bar"** 65 66 ```sh 67 curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?value=bar 68 ``` 69 70 71 ### Leader Election 72 73 The Leader Election module wraps the Lock module to allow clients to come to consensus on a single value. 74 This is useful when you want one server to process at a time but allow other servers to fail over. 75 The API is similar to the Lock module but is limited to simple strings values. 76 77 Here's the API: 78 79 **Attempt to set a value for the "order_processing" leader key:** 80 81 ```sh 82 curl -X PUT http://127.0.0.1:4001/mod/v2/leader/order_processing?ttl=60 -d name=myserver1.foo.com 83 ``` 84 85 **Retrieve the current value for the "order_processing" leader key:** 86 87 ```sh 88 curl http://127.0.0.1:4001/mod/v2/leader/order_processing 89 myserver1.foo.com 90 ``` 91 92 **Remove a value from the "order_processing" leader key:** 93 94 ```sh 95 curl -X DELETE http://127.0.0.1:4001/mod/v2/leader/order_processing?name=myserver1.foo.com 96 ``` 97 98 If multiple clients attempt to set the value for a key then only one will succeed. 99 The other clients will hang until the current value is removed because of TTL or because of a `DELETE` operation. 100 Multiple clients can submit the same value and will all be notified when that value succeeds. 101 102 To update the TTL of a value simply reissue the same `PUT` command that you used to set the value. 103 104 105