github.com/robstrong/etcd@v0.4.4-0.20140620001034-fb32a999a6bb/README.md (about) 1 # etcd 2 3 README version 0.4.3 4 5 A highly-available key value store for shared configuration and service discovery. 6 etcd is inspired by [Apache ZooKeeper][zookeeper] and [doozer][doozer], with a focus on being: 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 [zookeeper]: http://zookeeper.apache.org/ 19 [doozer]: https://github.com/ha/doozerd 20 [raft]: http://raftconsensus.github.io/ 21 [etcdctl]: http://github.com/coreos/etcdctl/ 22 23 If you're considering etcd for production use, please see: [production-ready.md](./Documentation/production-ready.md) 24 25 ## Getting Started 26 27 ### Getting etcd 28 29 The latest release and setup instructions are available at [GitHub][github-release]. 30 31 [github-release]: https://github.com/coreos/etcd/releases/ 32 33 34 ### Building 35 36 You can build etcd from source: 37 38 ```sh 39 git clone https://github.com/coreos/etcd 40 cd etcd 41 ./build 42 ``` 43 44 This will generate a binary called `./bin/etcd`. 45 46 _NOTE_: you need go 1.2+. Please check your installation with 47 48 ``` 49 go version 50 ``` 51 52 See the [development tools documentation][development-tools] for alternative build methods like using Vagrant. 53 54 [development-tools]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md 55 56 ### Running 57 58 First start a single-machine cluster of etcd: 59 60 ```sh 61 ./bin/etcd 62 ``` 63 64 This will bring up etcd listening on port 4001 for client communication and on port 7001 for server-to-server communication. 65 66 Next, let's set a single key, and then retrieve it: 67 68 ``` 69 curl -L http://127.0.0.1:4001/v2/keys/mykey -XPUT -d value="this is awesome" 70 curl -L http://127.0.0.1:4001/v2/keys/mykey 71 ``` 72 73 You have successfully started an etcd on a single machine and written a key to the store. Now it's time to dig into the full etcd API and other guides. 74 75 ### Next Steps 76 77 - Explore the full [API][api]. 78 - Set up a [multi-machine cluster][clustering]. 79 - Learn the [config format, env variables and flags][configuration]. 80 - Find [language bindings and tools][libraries-and-tools]. 81 - Learn about the dashboard, lock and leader election [modules][modules]. 82 - Use TLS to [secure an etcd cluster][security]. 83 - [Tune etcd][tuning]. 84 - [Upgrade from old version][upgrade]. 85 86 [api]: https://github.com/coreos/etcd/blob/master/Documentation/api.md 87 [clustering]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md 88 [configuration]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md 89 [libraries-and-tools]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md 90 [modules]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md 91 [security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md 92 [tuning]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md 93 [upgrade]: https://github.com/coreos/etcd/blob/master/Documentation/upgrade.md 94 95 ## Contact 96 97 - Mailing list: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev) 98 - IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) on freenode.org 99 - Planning/Roadmap: [milestones](https://github.com/coreos/etcd/issues/milestones) 100 - Bugs: [issues](https://github.com/coreos/etcd/issues) 101 102 ## Contributing 103 104 See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow. 105 106 ## Project Details 107 108 ### Versioning 109 110 #### Service Versioning 111 112 etcd uses [semantic versioning](http://semver.org) 113 New minor versions may add additional features to the API. 114 115 You can get the version of etcd by issuing a request to /version: 116 117 ```sh 118 curl -L http://127.0.0.1:4001/version 119 ``` 120 121 #### API Versioning 122 123 Clients are encouraged to use the `v2` API. The `v1` API will not change. 124 125 The `v2` API responses should not change after the 0.2.0 release but new features will be added over time. 126 127 During the pre-v1.0.0 series of releases we may break the API as we fix bugs and get feedback. 128 129 #### 32bit systems 130 131 etcd has known issues on 32bit systems. We plan to address these issues after the 0.4 release. 132 133 ### License 134 135 etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.