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