From 3dfe00fd015812e145369bdab2043a7474f09b49 Mon Sep 17 00:00:00 2001 From: Ekaterina Mekhnetsova Date: Wed, 25 May 2022 18:03:48 +0300 Subject: [PATCH] [documentation]: Review peer management Signed-off-by: Ekaterina Mekhnetsova --- src/guide/configure/register-unregister.md | 69 ++++++++++++++-------- 1 file changed, 44 insertions(+), 25 deletions(-) diff --git a/src/guide/configure/register-unregister.md b/src/guide/configure/register-unregister.md index 58c288cb1..c05d6fa0b 100644 --- a/src/guide/configure/register-unregister.md +++ b/src/guide/configure/register-unregister.md @@ -1,15 +1,17 @@ -# Registering and Unregistering peers +# Peer Management + +If you followed any of the language-specific guides, you now have a +well-functioning network that people want to join. ## Public Blockchain -With any luck, if you followed the guide, you have a well-functioning -network that people want to join. Naturally, in a public blockchain, -joining is a matter of installing the correct software and waiting until -your node gets discovered. +Naturally, in a public blockchain, joining is a matter of installing the +correct software and waiting until your node gets discovered. ::: info -Peer discovery is under construction. +Peer discovery is +[under construction](https://github.com/hyperledger/iroha/issues/1375 '#1375'). ::: @@ -17,11 +19,21 @@ Peer discovery is under construction. In a bank setting, allowing everyone to join at their leisure is a security nightmare. For safety, automatic discovery of peers is turned off for Iroha -2 in the private blockchain configuration. To add a peer to the network, it -must be manually registered. To do that, the user that registers the peer -must have the appropriate `PermissionToken`. This could be granted as part -of a `role`, or as part of a one-time allowance. Granting roles makes sense -if a user is to serve as an administrator of sorts, where it's their +2 in the private blockchain configuration. + +### Registering peers + +To add a peer to the network, it must be manually registered. Let's discuss +the steps that should be taken in order to complete this process. + +#### 1. Grant the user permissions + +The user that registers the peer must have the appropriate +`PermissionToken`. This could be granted as part of a `role`, or as part of +a one-time allowance. + +How to decide if you need to grant a role? Granting roles makes sense if a +user is to serve as an administrator of sorts, where it's their responsibility to maintain the peers in the network long-term. A one-time permission grant is useful when the party registering the peer isn't responsible for registering peers in general, but the network administrator @@ -33,33 +45,40 @@ Permissions for registering a peer are under construction. ::: -After permissions, the new peer must be set up. It's a good idea to request -some information about the peers' configuration in the network. Your best -friend is the `configuration` endpoint of the API socket. Thus far querying -is done only manually. In the next release we plan to implement a -[bootstrapping procedure](https://github.com/hyperledger/iroha/issues/1184 '#1184'), -but for now you'll have to manually check that the timeouts and batch sizes -match. To simplify the process, you can ask the network administrator for a +#### 2. Set up a peer + +After a new peer was granted permissions, it must be set up. + +It's a good idea to request information about the peers' configuration in +the network. Your best friend is the `configuration` endpoint of the API +socket. Thus far querying is done manually. Until the +[bootstrapping procedure](https://github.com/hyperledger/iroha/issues/1184 '#1184') +is implemented, you'll have to manually check that the timeouts and batch +sizes match. + +To simplify the process, you can ask the network administrator for a redacted version of `config.json`, which excludes privileged information, such as `PRIVATE_KEY`s. -_After_ your peer is running. You should submit the _register peer_ +#### 3. Submit the instruction + +_After_ your peer is running, you should submit the _register peer_ instruction. The peer will go through the handshake process and start chatting with the network. ::: tip -Submitting a `Register` instruction **doesn't** (and cannot) +Submitting a `Register` instruction **does not** (and cannot) instantiate a _new peer process_. ::: +### Unregistering peers + What about unregistering peers? For security reasons this process is one-sided. The network reaches consensus that it wants to remove a peer, -but the peer itself doesn't know much about why nobody's talking to it. We -might add an optional feature that will detect if the `Unregister` -instruction contains the public key of the peer itself and remove the -connection from all other peers, but this is not suitable for all cases. In -most circumstances, if you want to unregister a peer, you want to do so, +but the peer itself doesn't know much about why nobody's talking to it. + +In most circumstances, if you want to unregister a peer, you want to do so because it is a Byzantine fault. Just "ghosting" this peer makes the life of the malicious actor on the network harder.