github.com/matm/etcd@v0.3.1-0.20140328024009-5b4a473f1453/README.md (about)

     1  # etcd
     2  
     3  README version 0.3.0
     4  
     5  A highly-available key value store for shared configuration and service discovery.
     6  etcd is inspired by zookeeper and doozer, with a focus on:
     7  
     8  * Simple: curl'able user facing API (HTTP+JSON)
     9  * Secure: optional SSL client cert authentication
    10  * Fast: benchmarked 1000s of writes/s per instance
    11  * Reliable: Properly distributed using Raft
    12  
    13  Etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log.
    14  
    15  See [etcdctl][etcdctl] for a simple command line client.
    16  Or feel free to just use curl, as in the examples below.
    17  
    18  [raft]: http://raftconsensus.github.io/
    19  [etcdctl]: http://github.com/coreos/etcdctl/
    20  
    21  ## Getting Started
    22  
    23  ### Getting etcd
    24  
    25  The latest release and setup instructions are available at [Github][github-release].
    26  
    27  [github-release]: https://github.com/coreos/etcd/releases/
    28  
    29  
    30  ### Building
    31  
    32  You can build etcd from source:
    33  
    34  ```sh
    35  git clone https://github.com/coreos/etcd
    36  cd etcd
    37  ./build
    38  ```
    39  
    40  This will generate a binary called `./bin/etcd`.
    41  
    42  _NOTE_: you need go 1.2+. Please check your installation with
    43  
    44  ```
    45  go version
    46  ```
    47  
    48  See the [development tools documentation][development-tools.md] for alternative build methods like using Vagrant.
    49  
    50  [development-tools.md]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md
    51  
    52  ### Running
    53  
    54  First start a single machine cluster of etcd:
    55  
    56  ```sh
    57  ./bin/etcd
    58  ```
    59  
    60  This will bring up etcd listening on port 4001 for client communication and on port 7001 for server-to-server communication.
    61  
    62  Next lets set a single key and then retrieve it:
    63  
    64  ```
    65  curl -L http://127.0.0.1:4001/v2/keys/mykey -XPUT -d value="this is awesome"
    66  curl -L http://127.0.0.1:4001/v2/keys/mykey
    67  ```
    68  
    69  You have successfully started an etcd on a single machine and written a key to the store. Now it time to dig into the full etcd API and other guides.
    70  
    71  ### Next Steps
    72  
    73  - Explore the full [API][api.md].
    74  - Setup a [multi-machine cluster][clustering.md].
    75  - Learn the [config format, env variables and flags][configuration.md].
    76  - Find [language bindings and tools][libraries-and-tools.md].
    77  - Learn about the dashboard, lock and leader election [modules][modules.md].
    78  - Use TLS to [secure an etcd cluster][security.md].
    79  - [Tune etcd][tuning.md].
    80  
    81  [api.md]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
    82  [clustering.md]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
    83  [configuration.md]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
    84  [libraries-and-tools.md]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
    85  [modules.md]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
    86  [security.md]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
    87  [tuning.md]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
    88  
    89  ## Contact
    90  
    91  - Mailing list: http://coreos.com/lists/etcd-dev/
    92  - IRC: #coreos on irc.freenode.net
    93  - Planning/Roadmap: https://trello.com/b/OiEbU547/etcd
    94  - Bugs: https://github.com/coreos/etcd/issues
    95  
    96  ## Contributing
    97  
    98  See [CONTRIBUTING](https://github.com/coreos/etcd/blob/master/CONTRIBUTING.md) for details on submitting patches and contacting developers via IRC and mailing lists.
    99  
   100  ## Project Details
   101  
   102  ### Versioning
   103  
   104  #### Service Versioning
   105  
   106  etcd uses [semantic versioning][semver].
   107  New minor versions may add additional features to the API.
   108  
   109  You can get the version of etcd by issuing a request to /version:
   110  
   111  ```sh
   112  curl -L http://127.0.0.1:4001/version
   113  ```
   114  
   115  [semver]: http://semver.org/
   116  
   117  #### API Versioning
   118  
   119  Clients are encouraged to use the `v2` API. The `v1` API will not change.
   120  
   121  The `v2` API responses should not change after the 0.2.0 release but new features will be added over time.
   122  
   123  During the pre-v1.0.0 series of releases we may break the API as we fix bugs and get feedback.
   124  
   125  ### License
   126  
   127  etcd is under the Apache 2.0 license. See the [LICENSE][license] file for details.
   128  
   129  [license]: https://github.com/coreos/etcd/blob/master/LICENSE