From 252a0a392b52e43d88d3bc53be888b97c6881d7c Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 29 May 2018 16:49:02 +0400 Subject: [PATCH] move reactor descriptions to relevant specs --- docs/running-in-production.rst | 90 ------------------- docs/spec/consensus/wal.md | 33 +++++++ docs/spec/reactors/block_sync/reactor.md | 10 +++ .../reactors/consensus/consensus-reactor.md | 8 ++ docs/spec/reactors/evidence/reactor.md | 10 +++ docs/spec/reactors/mempool/reactor.md | 14 +++ docs/spec/reactors/pex/reactor.md | 12 +++ 7 files changed, 87 insertions(+), 90 deletions(-) create mode 100644 docs/spec/consensus/wal.md create mode 100644 docs/spec/reactors/evidence/reactor.md create mode 100644 docs/spec/reactors/mempool/reactor.md create mode 100644 docs/spec/reactors/pex/reactor.md diff --git a/docs/running-in-production.rst b/docs/running-in-production.rst index 432710831..dedbd56d0 100644 --- a/docs/running-in-production.rst +++ b/docs/running-in-production.rst @@ -12,41 +12,6 @@ modules can be found `here <./how-to-read-logs.html#list-of-modules>`__. If you're trying to debug Tendermint or asked to provide logs with debug logging level, you can do so by running tendermint with ``--log_level="*:debug"``. -Consensus WAL -------------- - -Consensus module writes every message to the WAL (write-ahead log). - -It also issues fsync syscall through `File#Sync -`__ for messages signed by this node (to -prevent double signing). - -Under the hood, it uses `autofile.Group -`__, which -rotates files when those get too big (> 10MB). - -The total maximum size is 1GB. We only need the latest block and the block before it, -but if the former is dragging on across many rounds, we want all those rounds. - -Replay -~~~~~~ - -Consensus module will replay all the messages of the last height written to WAL -before a crash (if such occurs). - -The private validator may try to sign messages during replay because it runs -somewhat autonomously and does not know about replay process. - -For example, if we got all the way to precommit in the WAL and then crash, -after we replay the proposal message, the private validator will try to sign a -prevote. But it will fail. That's ok because we’ll see the prevote later in the -WAL. Then it will go to precommit, and that time it will work because the -private validator contains the ``LastSignBytes`` and then we’ll replay the -precommit from the WAL. - -Make sure to read about `WAL corruption -<./specification/corruption.html#wal-corruption>`__ and recovery strategies. - DOS Exposure and Mitigation --------------------------- @@ -55,61 +20,6 @@ Validators are supposed to setup `Sentry Node Architecture to prevent Denial-of-service attacks. You can read more about it `here `__. -Blockchain Reactor -~~~~~~~~~~~~~~~~~~ - -Defines ``maxMsgSize`` for the maximum size of incoming messages, -``SendQueueCapacity`` and ``RecvBufferCapacity`` for maximum sending and -receiving buffers respectively. These are supposed to prevent amplification -attacks by setting up the upper limit on how much data we can receive & send to -a peer. - -Sending incorrectly encoded data will result in stopping the peer. - -Consensus Reactor -~~~~~~~~~~~~~~~~~ - -Defines 4 channels: state, data, vote and vote_set_bits. Each channel -has ``SendQueueCapacity`` and ``RecvBufferCapacity`` and -``RecvMessageCapacity`` set to ``maxMsgSize``. - -Sending incorrectly encoded data will result in stopping the peer. - -Evidence Reactor -~~~~~~~~~~~~~~~~ - -`#1503 `__ - -Sending invalid evidence will result in stopping the peer. - -Sending incorrectly encoded data or data exceeding ``maxMsgSize`` will result -in stopping the peer. - -PEX Reactor -~~~~~~~~~~~ - -Defines only ``SendQueueCapacity``. `#1503 `__ - -Implements rate-limiting by enforcing minimal time between two consecutive -``pexRequestMessage`` requests. If the peer sends us addresses we did not ask, -it is stopped. - -Sending incorrectly encoded data or data exceeding ``maxMsgSize`` will result -in stopping the peer. - -Mempool Reactor -~~~~~~~~~~~~~~~ - -`#1503 `__ - -Mempool maintains a cache of the last 10000 transactions to prevent replaying -old transactions (plus transactions coming from other validators, who are -continually exchanging transactions). Read `Replay Protection -<./app-development.html#replay-protection>`__ for details. - -Sending incorrectly encoded data or data exceeding ``maxMsgSize`` will result -in stopping the peer. - P2P ~~~ diff --git a/docs/spec/consensus/wal.md b/docs/spec/consensus/wal.md new file mode 100644 index 000000000..a2e03137d --- /dev/null +++ b/docs/spec/consensus/wal.md @@ -0,0 +1,33 @@ +# WAL + +Consensus module writes every message to the WAL (write-ahead log). + +It also issues fsync syscall through +[File#Sync](https://golang.org/pkg/os/#File.Sync) for messages signed by this +node (to prevent double signing). + +Under the hood, it uses +[autofile.Group](https://godoc.org/github.com/tendermint/tmlibs/autofile#Group), +which rotates files when those get too big (> 10MB). + +The total maximum size is 1GB. We only need the latest block and the block before it, +but if the former is dragging on across many rounds, we want all those rounds. + +## Replay + +Consensus module will replay all the messages of the last height written to WAL +before a crash (if such occurs). + +The private validator may try to sign messages during replay because it runs +somewhat autonomously and does not know about replay process. + +For example, if we got all the way to precommit in the WAL and then crash, +after we replay the proposal message, the private validator will try to sign a +prevote. But it will fail. That's ok because we’ll see the prevote later in the +WAL. Then it will go to precommit, and that time it will work because the +private validator contains the `LastSignBytes` and then we’ll replay the +precommit from the WAL. + +Make sure to read about [WAL +corruption](https://tendermint.readthedocs.io/projects/tools/en/master/specification/corruption.html#wal-corruption) +and recovery strategies. diff --git a/docs/spec/reactors/block_sync/reactor.md b/docs/spec/reactors/block_sync/reactor.md index c00ea96f3..9a814bead 100644 --- a/docs/spec/reactors/block_sync/reactor.md +++ b/docs/spec/reactors/block_sync/reactor.md @@ -47,3 +47,13 @@ type bcStatusResponseMessage struct { ## Protocol TODO + +## Channels + +Defines `maxMsgSize` for the maximum size of incoming messages, +`SendQueueCapacity` and `RecvBufferCapacity` for maximum sending and +receiving buffers respectively. These are supposed to prevent amplification +attacks by setting up the upper limit on how much data we can receive & send to +a peer. + +Sending incorrectly encoded data will result in stopping the peer. diff --git a/docs/spec/reactors/consensus/consensus-reactor.md b/docs/spec/reactors/consensus/consensus-reactor.md index 21098dcac..0f03b44b7 100644 --- a/docs/spec/reactors/consensus/consensus-reactor.md +++ b/docs/spec/reactors/consensus/consensus-reactor.md @@ -342,3 +342,11 @@ It broadcasts `NewRoundStepMessage` or `CommitStepMessage` upon new round state broadcasting these messages does not depend on the PeerRoundState; it is sent on the StateChannel. Upon receiving VoteMessage it broadcasts `HasVoteMessage` message to its peers on the StateChannel. `ProposalHeartbeatMessage` is sent the same way on the StateChannel. + +## Channels + +Defines 4 channels: state, data, vote and vote_set_bits. Each channel +has `SendQueueCapacity` and `RecvBufferCapacity` and +`RecvMessageCapacity` set to `maxMsgSize`. + +Sending incorrectly encoded data will result in stopping the peer. diff --git a/docs/spec/reactors/evidence/reactor.md b/docs/spec/reactors/evidence/reactor.md new file mode 100644 index 000000000..efa63aa4c --- /dev/null +++ b/docs/spec/reactors/evidence/reactor.md @@ -0,0 +1,10 @@ +# Evidence Reactor + +## Channels + +[#1503](https://github.com/tendermint/tendermint/issues/1503) + +Sending invalid evidence will result in stopping the peer. + +Sending incorrectly encoded data or data exceeding `maxMsgSize` will result +in stopping the peer. diff --git a/docs/spec/reactors/mempool/reactor.md b/docs/spec/reactors/mempool/reactor.md new file mode 100644 index 000000000..2bdbd8951 --- /dev/null +++ b/docs/spec/reactors/mempool/reactor.md @@ -0,0 +1,14 @@ +# Mempool Reactor + +## Channels + +[#1503](https://github.com/tendermint/tendermint/issues/1503) + +Mempool maintains a cache of the last 10000 transactions to prevent +replaying old transactions (plus transactions coming from other +validators, who are continually exchanging transactions). Read [Replay +Protection](https://tendermint.readthedocs.io/projects/tools/en/master/app-development.html?#replay-protection) +for details. + +Sending incorrectly encoded data or data exceeding `maxMsgSize` will result +in stopping the peer. diff --git a/docs/spec/reactors/pex/reactor.md b/docs/spec/reactors/pex/reactor.md new file mode 100644 index 000000000..468f182cc --- /dev/null +++ b/docs/spec/reactors/pex/reactor.md @@ -0,0 +1,12 @@ +# PEX Reactor + +## Channels + +Defines only `SendQueueCapacity`. [#1503](https://github.com/tendermint/tendermint/issues/1503) + +Implements rate-limiting by enforcing minimal time between two consecutive +`pexRequestMessage` requests. If the peer sends us addresses we did not ask, +it is stopped. + +Sending incorrectly encoded data or data exceeding `maxMsgSize` will result +in stopping the peer.