github.com/sym3tri/etcd@v0.2.1-0.20140422215517-a563d82f95d6/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  **Warning**: Modules are deprecated from v0.4 until we have a solid base we can apply them back onto.
     7  For now, we are choosing to focus on raft algorithm and core etcd to make sure that it works correctly and fast.
     8  And it is time consuming to maintain these modules in this period, given that etcd's API changes from time to time.
     9  Moreover, the lock module has some unfixed bugs, which may mislead users.
    10  But we also notice that these modules are popular and useful, and plan to add them back with full functionality as soon as possible.
    11  
    12  ### Dashboard
    13  
    14  An HTML dashboard can be found at `http://127.0.0.1:4001/mod/dashboard/`.
    15  This dashboard is compiled into the etcd binary and uses the same API as regular etcd clients.
    16  
    17  Use the `-cors='*'` flag to allow your browser to request information from the current master as it changes.
    18  
    19  ### Lock
    20  
    21  The Lock module implements a fair lock that can be used when lots of clients want access to a single resource.
    22  A lock can be associated with a value.
    23  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.
    24  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.
    25  If you lock the same value on a key from two separate curl sessions they'll both return at the same time.
    26  
    27  Here's the API:
    28  
    29  **Acquire a lock (with no value) for "customer1"**
    30  
    31  ```sh
    32  curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60
    33  ```
    34  
    35  **Acquire a lock for "customer1" that is associated with the value "bar"**
    36  
    37  ```sh
    38  curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar
    39  ```
    40  
    41  **Acquire a lock for "customer1" that is associated with the value "bar" only if it is done within 2 seconds**
    42  
    43  ```sh
    44  curl -X POST http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar -d timeout=2
    45  ```
    46  
    47  **Renew the TTL on the "customer1" lock for index 2**
    48  
    49  ```sh
    50  curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d index=2
    51  ```
    52  
    53  **Renew the TTL on the "customer1" lock for value "customer1"**
    54  
    55  ```sh
    56  curl -X PUT http://127.0.0.1:4001/mod/v2/lock/customer1?ttl=60 -d value=bar
    57  ```
    58  
    59  **Retrieve the current value for the "customer1" lock.**
    60  
    61  ```sh
    62  curl http://127.0.0.1:4001/mod/v2/lock/customer1
    63  ```
    64  
    65  **Retrieve the current index for the "customer1" lock**
    66  
    67  ```sh
    68  curl http://127.0.0.1:4001/mod/v2/lock/customer1?field=index
    69  ```
    70  
    71  **Delete the "customer1" lock with the index 2**
    72  
    73  ```sh
    74  curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?index=2
    75  ```
    76  
    77  **Delete the "customer1" lock with the value "bar"**
    78  
    79  ```sh
    80  curl -X DELETE http://127.0.0.1:4001/mod/v2/lock/customer1?value=bar
    81  ```
    82  
    83  
    84  ### Leader Election
    85  
    86  The Leader Election module wraps the Lock module to allow clients to come to consensus on a single value.
    87  This is useful when you want one server to process at a time but allow other servers to fail over.
    88  The API is similar to the Lock module but is limited to simple strings values.
    89  
    90  Here's the API:
    91  
    92  **Attempt to set a value for the "order_processing" leader key:**
    93  
    94  ```sh
    95  curl -X PUT http://127.0.0.1:4001/mod/v2/leader/order_processing?ttl=60 -d name=myserver1.foo.com
    96  ```
    97  
    98  **Retrieve the current value for the "order_processing" leader key:**
    99  
   100  ```sh
   101  curl http://127.0.0.1:4001/mod/v2/leader/order_processing
   102  myserver1.foo.com
   103  ```
   104  
   105  **Remove a value from the "order_processing" leader key:**
   106  
   107  ```sh
   108  curl -X DELETE http://127.0.0.1:4001/mod/v2/leader/order_processing?name=myserver1.foo.com
   109  ```
   110  
   111  If multiple clients attempt to set the value for a key then only one will succeed.
   112  The other clients will hang until the current value is removed because of TTL or because of a `DELETE` operation.
   113  Multiple clients can submit the same value and will all be notified when that value succeeds.
   114  
   115  To update the TTL of a value simply reissue the same `PUT` command that you used to set the value.
   116  
   117  
   118