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