From 6c4a26f248b5a2f385128167483387fb3c8ecd97 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 22:44:29 -0400 Subject: [PATCH 01/10] update readme --- README.md | 17 ++++++++--------- docs/specification/new-spec/README.md | 2 +- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 89c28e9c2..c230e6f9d 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,7 @@ _NOTE: This is alpha software. Please contact us if you intend to run it in prod Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state transition machine - written in any programming language - and securely replicates it on many machines. -For more information, from introduction to installation and application development, [Read The Docs](https://tendermint.readthedocs.io/en/master/). - -For protocol details, see [the specification](./docs/specification/new-spec). +For protocol details, see [the specification](/docs/spec). ## Minimum requirements @@ -36,19 +34,20 @@ Go version | Go1.9 or higher ## Install -To download pre-built binaries, see our [downloads page](https://tendermint.com/downloads). +See the [install instructions](/docs/install.rst) -To install from source, you should be able to: +## Documentation -`go get -u github.com/tendermint/tendermint/cmd/tendermint` - -For more details (or if it fails), [read the docs](https://tendermint.readthedocs.io/en/master/install.html). +- [Run a single Tendermint + node](/docs/using-tendermint.rst) +- [Run a local Tendermint cluster using docker-compose](/networks/local) +- [Run a remote Tendermint cluster using terraform and ansible](/networks/remote) ## Resources ### Tendermint Core -To use Tendermint, build apps on it, or develop it, [Read The Docs](https://tendermint.readthedocs.io/en/master/). +For more on Tendermint and how to build apps, [Read The Docs](https://tendermint.readthedocs.io/en/master/). Additional information about some - and eventually all - of the sub-projects below, can be found at Read The Docs. ### Sub-projects diff --git a/docs/specification/new-spec/README.md b/docs/specification/new-spec/README.md index 20e8e89d7..f5ebd2714 100644 --- a/docs/specification/new-spec/README.md +++ b/docs/specification/new-spec/README.md @@ -1 +1 @@ -Spec moved to [docs/spec](./docs/spec). +Spec moved to [docs/spec](/docs/spec). From d7d12c8030b16418de1a2a4875412352c934d55e Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 23:21:19 -0400 Subject: [PATCH 02/10] update networks/local readme --- Makefile | 4 +++ docs/using-tendermint.rst | 7 ++-- networks/local/README.rst | 74 +++++++++++++++++++++++++++++++-------- 3 files changed, 69 insertions(+), 16 deletions(-) diff --git a/Makefile b/Makefile index 60a81fe35..ce3b9ed56 100755 --- a/Makefile +++ b/Makefile @@ -193,6 +193,10 @@ build-docker: build-linux: GOOS=linux GOARCH=amd64 $(MAKE) build +build-docker-localnode: + cd networks/local + make + # Run a 4-node testnet locally localnet-start: localnet-stop @if ! [ -f build/node0/config/genesis.json ]; then docker run --rm -v $(CURDIR)/build:/tendermint:Z tendermint/localnode testnet --v 4 --o . --populate-persistent-peers --starting-ip-address 192.167.10.2 ; fi diff --git a/docs/using-tendermint.rst b/docs/using-tendermint.rst index f572277cd..56790feae 100644 --- a/docs/using-tendermint.rst +++ b/docs/using-tendermint.rst @@ -28,8 +28,11 @@ genesis file (``genesis.json``) containing the associated public key, in ``$TMHOME/config``. This is all that's necessary to run a local testnet with one validator. -For more elaborate initialization, see our `testnet deployment -tool `__. +For more elaborate initialization, see the `tesnet` command: + +:: + + tendermint testnet --help Run --- diff --git a/networks/local/README.rst b/networks/local/README.rst index d22a24d9b..601d238de 100644 --- a/networks/local/README.rst +++ b/networks/local/README.rst @@ -1,29 +1,79 @@ localnode ========= -It is assumed that you have already `setup docker `__. +Requirements +------------ -Description ------------ -Image for local testnets. +- `Install docker `__. +- `Install docker-compose `__. -Add the tendermint binary to the image by attaching it in a folder to the `/tendermint` mount point. +Build +----- -It assumes that the configuration was created by the `tendermint testnet` command and it is also attached to the `/tendermint` mount point. +Build the `tendermint` binary and the `tendermint/localnode` docker image: -Example: -This example builds a linux tendermint binary under the `build/` folder, creates tendermint configuration for a single-node validator and runs the node: ``` cd $GOPATH/src/github.com/tendermint/tendermint -#Build binary +# Install dependencies (skip if already done) +make get_tools +make get_vendor_deps + +# Build binary in ./build make build-linux -#Create configuration +# Build tendermint/localnode image +make build-docker-localnode + +``` + +Run a testnet +------------- + +To start a 4 node testnet run: + +``` +make localnet-start + +`` + +The nodes bind their RPC servers to ports 46657, 46660, 46662, and 46664 on the host. +This file creates a 4-node network using the localnode image. +The nodes of the network expose their P2P and RPC endpoints to the host machine on ports 46656-46657, 46659-46660, 46661-46662, and 46663-46664 respectively. + +To update the binary, just rebuild it and restart the nodes: + +``` +make build-linux +make localnet-stop +make localnet-start + +``` + +Configuration +----------- + +The `make localnet-start` creates files for a 4-node testnet in `./build` by calling the `tendermint testnet` command. + +The `./build` directory is mounted to the `/tendermint` mount point to attach the binary and config files to the container. + +For instance, to create a single node testnet: + +``` +cd $GOPATH/src/github.com/tendermint/tendermint + +# Clear the build folder +rm -rf ./build + +# Build binary +make build-linux + +# Create configuration docker run -e LOG="stdout" -v `pwd`/build:/tendermint tendermint/localnode testnet --o . --v 1 #Run the node docker run -v `pwd`/build:/tendermint tendermint/localnode + ``` Logging @@ -34,7 +84,3 @@ Special binaries ---------------- If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. -docker-compose.yml -================== -This file creates a 4-node network using the localnode image. The nodes of the network are exposed to the host machine on ports 46656-46657, 46659-46660, 46661-46662, 46663-46664 respectively. - From 420f925a4d78b59bdeefa77766dfd807b4d800e7 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 23:21:42 -0400 Subject: [PATCH 03/10] link bug bounty in readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index c230e6f9d..c5375060d 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ and securely replicates it on many machines. For protocol details, see [the specification](/docs/spec). +To report a security vulnerability, see our [bug bounty +program](https://tendermint.com/security). + ## Minimum requirements Requirement|Notes From d76e2dc3ff0d27d851a8658decfff40999878f04 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 23:26:02 -0400 Subject: [PATCH 04/10] readme.rst -> readme.md --- networks/local/{README.rst => README.md} | 32 +++++++++--------------- 1 file changed, 12 insertions(+), 20 deletions(-) rename networks/local/{README.rst => README.md} (85%) diff --git a/networks/local/README.rst b/networks/local/README.md similarity index 85% rename from networks/local/README.rst rename to networks/local/README.md index 601d238de..af3b6c870 100644 --- a/networks/local/README.rst +++ b/networks/local/README.md @@ -1,14 +1,11 @@ -localnode -========= +# Local Docker Testnet -Requirements ------------- +## Requirements -- `Install docker `__. -- `Install docker-compose `__. +- [Install docker](https://docs.docker.com/engine/installation/) +- [Install docker-compose](https://docs.docker.com/compose/install/) -Build ------ +## Build Build the `tendermint` binary and the `tendermint/localnode` docker image: @@ -24,18 +21,15 @@ make build-linux # Build tendermint/localnode image make build-docker-localnode - ``` -Run a testnet -------------- +## Run a testnet To start a 4 node testnet run: ``` make localnet-start - -`` +``` The nodes bind their RPC servers to ports 46657, 46660, 46662, and 46664 on the host. This file creates a 4-node network using the localnode image. @@ -47,11 +41,9 @@ To update the binary, just rebuild it and restart the nodes: make build-linux make localnet-stop make localnet-start - ``` -Configuration ------------ +## Configuration The `make localnet-start` creates files for a 4-node testnet in `./build` by calling the `tendermint testnet` command. @@ -76,11 +68,11 @@ docker run -v `pwd`/build:/tendermint tendermint/localnode ``` -Logging -------- +## Logging + Log is saved under the attached volume, in the `tendermint.log` file. If the `LOG` environment variable is set to `stdout` at start, the log is not saved, but printed on the screen. -Special binaries ----------------- +## Special binaries + If you have multiple binaries with different names, you can specify which one to run with the BINARY environment variable. The path of the binary is relative to the attached volume. From 26fdfe10fd64c8c0cc05b87203a17a86b22ff4d9 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 23:28:27 -0400 Subject: [PATCH 05/10] update readme --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index c5375060d..0c52f5f74 100644 --- a/README.md +++ b/README.md @@ -39,18 +39,17 @@ Go version | Go1.9 or higher See the [install instructions](/docs/install.rst) -## Documentation +## Quick Start -- [Run a single Tendermint - node](/docs/using-tendermint.rst) -- [Run a local Tendermint cluster using docker-compose](/networks/local) -- [Run a remote Tendermint cluster using terraform and ansible](/networks/remote) +- [Single node](/docs/using-tendermint.rst) +- [Local cluster using docker-compose](/networks/local) +- [Remote cluster using terraform and ansible](/networks/remote) ## Resources ### Tendermint Core -For more on Tendermint and how to build apps, [Read The Docs](https://tendermint.readthedocs.io/en/master/). +For more, [Read The Docs](https://tendermint.readthedocs.io/en/master/). Additional information about some - and eventually all - of the sub-projects below, can be found at Read The Docs. ### Sub-projects From 773e3917ecc821f49adc6bf23525e13b0b4962e4 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sat, 19 May 2018 23:35:45 -0400 Subject: [PATCH 06/10] networks: update readmes --- networks/local/README.md | 15 ++++++++------- networks/remote/README.md | 1 + 2 files changed, 9 insertions(+), 7 deletions(-) create mode 100644 networks/remote/README.md diff --git a/networks/local/README.md b/networks/local/README.md index af3b6c870..528247f18 100644 --- a/networks/local/README.md +++ b/networks/local/README.md @@ -1,28 +1,29 @@ -# Local Docker Testnet +# Local Cluster with Docker Compose ## Requirements +- [Install tendermint](/docs/install.rst) - [Install docker](https://docs.docker.com/engine/installation/) - [Install docker-compose](https://docs.docker.com/compose/install/) ## Build -Build the `tendermint` binary and the `tendermint/localnode` docker image: +Build the `tendermint` binary and the `tendermint/localnode` docker image. + +Note the binary will be mounted into the container so it can be updated without +rebuilding the image. ``` cd $GOPATH/src/github.com/tendermint/tendermint -# Install dependencies (skip if already done) -make get_tools -make get_vendor_deps - -# Build binary in ./build +# Build the linux binary in ./build make build-linux # Build tendermint/localnode image make build-docker-localnode ``` + ## Run a testnet To start a 4 node testnet run: diff --git a/networks/remote/README.md b/networks/remote/README.md new file mode 100644 index 000000000..a5c0d1109 --- /dev/null +++ b/networks/remote/README.md @@ -0,0 +1 @@ +# Remote Cluster with Terraform and Ansible From 1ef415728d583bc05c5f7f00469aa399c837f44a Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 20 May 2018 00:28:47 -0400 Subject: [PATCH 07/10] docs/spec: blockchain and consensus dirs --- docs/spec/README.md | 13 +++++++++---- docs/spec/{ => blockchain}/blockchain.md | 0 docs/spec/{ => blockchain}/encoding.md | 0 docs/spec/{ => blockchain}/light-client.md | 0 docs/spec/{ => blockchain}/pre-amino.md | 0 docs/spec/{ => blockchain}/state.md | 0 docs/spec/{ => consensus}/abci.md | 0 docs/spec/{ => consensus}/bft-time.md | 0 8 files changed, 9 insertions(+), 4 deletions(-) rename docs/spec/{ => blockchain}/blockchain.md (100%) rename docs/spec/{ => blockchain}/encoding.md (100%) rename docs/spec/{ => blockchain}/light-client.md (100%) rename docs/spec/{ => blockchain}/pre-amino.md (100%) rename docs/spec/{ => blockchain}/state.md (100%) rename docs/spec/{ => consensus}/abci.md (100%) rename docs/spec/{ => consensus}/bft-time.md (100%) diff --git a/docs/spec/README.md b/docs/spec/README.md index 12f5525c9..e13e65c1f 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -10,12 +10,17 @@ please submit them to our [bug bounty](https://tendermint.com/security)! ## Contents +- [Overview](#overview) + ### Data Structures -- [Overview](#overview) -- [Encoding and Digests](encoding.md) -- [Blockchain](blockchain.md) -- [State](state.md) +- [Encoding and Digests](./blockchain/encoding.md) +- [Blockchain](./blockchain/blockchain.md) +- [State](./blockchain/state.md) + +### Consensus Protocol + +- TODO ### P2P and Network Protocols diff --git a/docs/spec/blockchain.md b/docs/spec/blockchain/blockchain.md similarity index 100% rename from docs/spec/blockchain.md rename to docs/spec/blockchain/blockchain.md diff --git a/docs/spec/encoding.md b/docs/spec/blockchain/encoding.md similarity index 100% rename from docs/spec/encoding.md rename to docs/spec/blockchain/encoding.md diff --git a/docs/spec/light-client.md b/docs/spec/blockchain/light-client.md similarity index 100% rename from docs/spec/light-client.md rename to docs/spec/blockchain/light-client.md diff --git a/docs/spec/pre-amino.md b/docs/spec/blockchain/pre-amino.md similarity index 100% rename from docs/spec/pre-amino.md rename to docs/spec/blockchain/pre-amino.md diff --git a/docs/spec/state.md b/docs/spec/blockchain/state.md similarity index 100% rename from docs/spec/state.md rename to docs/spec/blockchain/state.md diff --git a/docs/spec/abci.md b/docs/spec/consensus/abci.md similarity index 100% rename from docs/spec/abci.md rename to docs/spec/consensus/abci.md diff --git a/docs/spec/bft-time.md b/docs/spec/consensus/bft-time.md similarity index 100% rename from docs/spec/bft-time.md rename to docs/spec/consensus/bft-time.md From 2df137193c65efc7459dfb1b1047f53e65a3b026 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 20 May 2018 00:29:28 -0400 Subject: [PATCH 08/10] security.md --- README.md | 2 +- SECURITY.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 SECURITY.md diff --git a/README.md b/README.md index 0c52f5f74..f1aab737c 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ and securely replicates it on many machines. For protocol details, see [the specification](/docs/spec). To report a security vulnerability, see our [bug bounty -program](https://tendermint.com/security). +program](SECURITY.md). ## Minimum requirements diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..8b9793782 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,71 @@ +# Security + +As part of our [Coordinated Vulnerability Disclosure +Policy](https://tendermint.com/security), we operate a bug bounty. +See the policy for more details on submissions and rewards. + +Here is a list of examples of the kinds of bugs we're most interested in: + +## Specification + +- Conceptual flaws +- Ambiguities, inconsistencies, or incorrect statements +- Mis-match between specification and implementation of any component + +## Consensus + +Assuming less than 1/3 of the voting power is Byzantine (malicious): + +- Validation of blockchain data structures, including blocks, block parts, + votes, and so on +- Execution of blocks +- Validator set changes +- Proposer round robin +- Two nodes committing conflicting blocks for the same height (safety failure) +- A correct node signing conflicting votes +- A node halting (liveness failure) +- Syncing new and old nodes + +## Networking + +- Authenticated encryption (MITM, information leakage) +- Eclipse attacks +- Sybil attacks +- Long-range attacks +- Denial-of-Service + +## RPC + +- Write-access to anything besides sending transactions +- Denial-of-Service +- Leakage of secrets + +## Denial-of-Service + +Attacks may come through the P2P network or the RPC: + +- Amplification attacks +- Resource abuse +- Deadlocks and race conditions +- Panics and unhandled errors + +## Libraries + +- Serialization (Amino) +- Reading/Writing files and databases +- Logging and monitoring + +## Cryptography + +- Elliptic curves for validator signatures +- Hash algorithms and Merkle trees for block validation +- Authenticated encryption for P2P connections + +## Light Client + +- Validation of blockchain data structures +- Correctly validating an incorrect proof +- Incorrectly validating a correct proof +- Syncing validator set changes + + From 02615c86951fbb919e2f0e2fb4aba760eb23f6e8 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 20 May 2018 00:39:34 -0400 Subject: [PATCH 09/10] update readme --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f1aab737c..6f8606065 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,12 @@ and securely replicates it on many machines. For protocol details, see [the specification](/docs/spec). +## Security + To report a security vulnerability, see our [bug bounty -program](SECURITY.md). +program](https://tendermint.com/security). + +For examples of the kinds of bugs we're looking for, see [SECURITY.md](SECURITY.md) ## Minimum requirements From 301aa92f9c7a9e50375aaf06b956205b8e4477f4 Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 20 May 2018 09:53:38 -0400 Subject: [PATCH 10/10] phony --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index ce3b9ed56..991bfb263 100755 --- a/Makefile +++ b/Makefile @@ -229,5 +229,5 @@ sentry-stop: # To avoid unintended conflicts with file names, always add to .PHONY # unless there is a reason not to. # https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html -.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker sentry-start sentry-config sentry-stop +.PHONY: check build build_race dist install check_tools get_tools update_tools get_vendor_deps draw_deps test_cover test_apps test_persistence test_p2p test test_race test_integrations test_release test100 vagrant_test fmt build-linux localnet-start localnet-stop build-docker build-docker-localnode sentry-start sentry-config sentry-stop