diff --git a/Makefile b/Makefile index 60a81fe35..991bfb263 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 @@ -225,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 diff --git a/README.md b/README.md index 89c28e9c2..6f8606065 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,14 @@ _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/spec). -For protocol details, see [the specification](./docs/specification/new-spec). +## Security + +To report a security vulnerability, see our [bug bounty +program](https://tendermint.com/security). + +For examples of the kinds of bugs we're looking for, see [SECURITY.md](SECURITY.md) ## Minimum requirements @@ -36,19 +41,19 @@ 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: +## Quick Start -`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). +- [Single node](/docs/using-tendermint.rst) +- [Local cluster using docker-compose](/networks/local) +- [Remote 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, [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/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 + + 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 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). 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.md b/networks/local/README.md new file mode 100644 index 000000000..528247f18 --- /dev/null +++ b/networks/local/README.md @@ -0,0 +1,79 @@ +# 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. + +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 + +# 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: + +``` +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 + +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 + +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. + diff --git a/networks/local/README.rst b/networks/local/README.rst deleted file mode 100644 index d22a24d9b..000000000 --- a/networks/local/README.rst +++ /dev/null @@ -1,40 +0,0 @@ -localnode -========= - -It is assumed that you have already `setup docker `__. - -Description ------------ -Image for local testnets. - -Add the tendermint binary to the image by attaching it in a folder to the `/tendermint` mount point. - -It assumes that the configuration was created by the `tendermint testnet` command and it is also attached to the `/tendermint` mount point. - -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 -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 -------- -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 ----------------- -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. - 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