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