[DOCS] bring back the 'Private Network' page (#20262)
This improves the private network page. We now recommend using clique instead of ethash. The networking section is improved as well and now recommends using a regular geth node for bootstrapping instead of running cmd/bootnode. I also added some text about the --netrestrict option.
This commit is contained in:
parent
76bc99158d
commit
a89f10fcdd
|
@ -0,0 +1,295 @@
|
|||
---
|
||||
title: Private Networks
|
||||
sort_key: B
|
||||
---
|
||||
|
||||
This guide explains how to set up a private network of multiple Geth nodes. An Ethereum
|
||||
network is a private network if the nodes are not connected to the main network. In this
|
||||
context private only means reserved or isolated, rather than protected or secure.
|
||||
|
||||
### Choosing A Network ID
|
||||
|
||||
The network ID is an integer number which isolates Ethereum peer-to-peer networks.
|
||||
Connections between blockchain nodes will occur only if both peers use the same genesis
|
||||
block and network ID. Use the `--networkid` command line option to set the network ID used
|
||||
by geth.
|
||||
|
||||
The main network has ID 1. If you supply your own custom network ID which is different
|
||||
than the main network, your nodes will not connect to other nodes and form a private
|
||||
network. If you're planning to connect to your private chain on the Internet, it's best to
|
||||
choose a network ID that isn't already used. You can find a community-run registry of
|
||||
Ethereum networks at <https://chainid.network>.
|
||||
|
||||
### Choosing A Consensus Algorithm
|
||||
|
||||
While the main network uses proof-of-work to secure the blockchain, Geth also supports the
|
||||
the 'clique' proof-of-authority consensus algorithm as an alternative for private
|
||||
networks. We strongly recommend 'clique' for new private network deployments because it is
|
||||
much less resource intensive than proof-of-work. The clique system is also used for
|
||||
several public Ethereum testnets such as [Rinkeby](https://rinkeby.io) and
|
||||
[Görli](https://goerli.net).
|
||||
|
||||
Here are the key differences between the two consensus algorithms available in Geth:
|
||||
|
||||
Ethash consensus, being a proof-of-work algorithm, is a system that allows open
|
||||
participation by anyone willing to dedicate resources to mining. While this is a great
|
||||
property to have for a public network, the overall security of the blockchain strictly
|
||||
depends on the total amount of resources used to secure it. As such, proof-of-work is a
|
||||
poor choice for private networks with few miners. The Ethash mining 'difficulty' is
|
||||
adjusted automatically so that new blocks are created approximately 12 seconds apart. As
|
||||
more mining resources are deployed on the network, creating a new block becomes harder so
|
||||
that the average block time matches the target block time.
|
||||
|
||||
Clique consensus is a proof-of-authority system where new blocks can be created by
|
||||
authorized 'signers' only. The clique consenus protocol is specified in
|
||||
[EIP-225](clique-eip). The initial set of authorized signers is configured in the genesis
|
||||
block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing
|
||||
the set of signers to change while the blockchain operates. Clique can be configured to
|
||||
target any block time (within reasonable limits) since it isn't tied to the difficulty
|
||||
adjustment.
|
||||
|
||||
[clique-eip]: https://eips.ethereum.org/EIPS/eip-225
|
||||
|
||||
### Creating The Genesis Block
|
||||
|
||||
Every blockchain starts with the genesis block. When you run Geth with default settings
|
||||
for the first time, it commits the main net genesis to the database. For a private
|
||||
network, you usually want a different genesis block.
|
||||
|
||||
The genesis block is configured using the _genesis.json_ file. When creating a genesis
|
||||
block, you need to decide on a few initial parameters for your blockchain:
|
||||
|
||||
- Ethereum platform features enabled at launch (`config`). Enabling protocol features
|
||||
while the blockchain is running requires scheduling a hard fork.
|
||||
- Initial block gas limit (`gasLimit`). Your choice here impacts how much EVM computation
|
||||
can happen within a single block. We recommend using the main Ethereum network as a
|
||||
[guideline to find a good amount](gaslimit-char). The block gas limit can be adjusted
|
||||
after launch using the `--targetgaslimit` command-line flag.
|
||||
- Initial allocation of ether (`alloc`). This determines how much ether is available to
|
||||
the addresses you list in the genesis block. Additional ether can be created through
|
||||
mining as the chain progresses.
|
||||
|
||||
[gaslimit-chart]: https://etherscan.io/chart/gaslimit
|
||||
|
||||
#### Clique Example
|
||||
|
||||
This is an example of a genesis.json file for a proof-of-authority network. The `config`
|
||||
section ensures that all known protocol changes are available and configures the 'clique'
|
||||
engine to be used for consensus.
|
||||
|
||||
Note that the initial signer set must be configured through the `extradata` field. This
|
||||
field is required for clique to work.
|
||||
|
||||
First create the signer account keys using the [geth account](./managing-your-accounts)
|
||||
command (run this command multiple times to create more than one signer key).
|
||||
|
||||
```shell
|
||||
geth account new --datadir data
|
||||
```
|
||||
|
||||
Take note of the Ethereum address printed by this command.
|
||||
|
||||
To create the initial extradata for your network, collect the signer addresses and encode
|
||||
`extradata` as the concatenation of 32 zero bytes, all signer addresses, and 65 further
|
||||
zero bytes. In the example below, `extradata` contains a single initial signer address,
|
||||
`0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82`.
|
||||
|
||||
You can use the `period` configuration option to set the target block time of the chain.
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"chainId": 15,
|
||||
"homesteadBlock": 0,
|
||||
"eip150Block": 0,
|
||||
"eip155Block": 0,
|
||||
"eip158Block": 0,
|
||||
"byzantiumBlock": 0,
|
||||
"constantinopleBlock": 0,
|
||||
"petersburgBlock": 0,
|
||||
"clique": {
|
||||
"period": 5,
|
||||
"epoch": 30000
|
||||
}
|
||||
},
|
||||
"difficulty": "1",
|
||||
"gasLimit": "8000000",
|
||||
"extradata": "0x00000000000000000000000000000000000000000000000000000000000000007df9a875a174b3bc565e6424a0050ebc1b2d1d820000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
|
||||
"alloc": {
|
||||
"7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
|
||||
"f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Ethash Example
|
||||
|
||||
Since ethash is the default consensus algorithm, no additional parameters need to be
|
||||
configured in order to use it. You can influence the initial mining difficulty using the
|
||||
`difficulty` parameter, but note that the difficulty adjustment algorithm will quickly
|
||||
adapt to the amount of mining resources you deploy on the chain.
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"chainId": 15,
|
||||
"homesteadBlock": 0,
|
||||
"eip150Block": 0,
|
||||
"eip155Block": 0,
|
||||
"eip158Block": 0,
|
||||
"byzantiumBlock": 0,
|
||||
"constantinopleBlock": 0,
|
||||
"petersburgBlock": 0,
|
||||
"ethash": {}
|
||||
},
|
||||
"difficulty": "1",
|
||||
"gasLimit": "8000000",
|
||||
"alloc": {
|
||||
"7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
|
||||
"f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Initializing the Geth Database
|
||||
|
||||
To create a blockchain node that uses this genesis block, run the following command. This
|
||||
imports and sets the canonical genesis block for your chain.
|
||||
|
||||
```shell
|
||||
geth init --datadir data genesis.json
|
||||
```
|
||||
|
||||
Future runs of geth using this data directory will use the genesis block you have defined.
|
||||
|
||||
```shell
|
||||
geth --datadir data --networkid 15
|
||||
```
|
||||
|
||||
### Scheduling Hard Forks
|
||||
|
||||
As Ethereum protocol development progresses, new Ethereum features become available. To
|
||||
enable these features on your private network, you must schedule a hard fork.
|
||||
|
||||
First, choose any future block number where the hard fork will activate. Continuing from
|
||||
the genesis.json example above, let's assume your network is running and its current block
|
||||
number is 35421. To schedule the 'Istanbul' fork, we pick block 40000 as the activation
|
||||
block number and modify our genesis.json file to set it:
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
...
|
||||
"istanbulBlock": 40000,
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
In order to update to the new fork, first ensure that all Geth instances on your private
|
||||
network actually support the Istanbul fork (i.e. ensure you have the latest version of
|
||||
Geth installed). Now shut down all nodes and re-run the `init` command to enable the new
|
||||
chain configuration:
|
||||
|
||||
```shell
|
||||
geth init --datadir data genesis.json
|
||||
```
|
||||
|
||||
### Setting Up Networking
|
||||
|
||||
Once your node is initialized to the desired genesis state, it is time to set up the
|
||||
peer-to-peer network. Any node can be used as an entry point. We recommend dedicating a
|
||||
single node as the rendezvous point which all other nodes use to join. This node is called
|
||||
the 'bootstrap node'.
|
||||
|
||||
First, determine the IP address of the machine your bootstrap node will run on. If you are
|
||||
using a cloud service such as Amazon EC2, you'll find the IP of the virtual machine in the
|
||||
management console. Please also ensure that your firewall configuration allows both UDP
|
||||
and TCP traffic on port 30303.
|
||||
|
||||
The bootstrap node needs to know about its own IP address in order to be able to relay it
|
||||
others. The IP is set using the `--nat` flag (insert your own IP instead of the example
|
||||
address below).
|
||||
|
||||
```shell
|
||||
geth --datadir data --networkid 15 --nat extip:172.16.254.4
|
||||
```
|
||||
|
||||
Now extract the 'node record' of the bootnode using the JS console.
|
||||
|
||||
```shell
|
||||
geth attach data/geth.ipc --exec admin.nodeInfo.enr
|
||||
```
|
||||
|
||||
This command should print a base64 string such as the following example. Other nodes will
|
||||
use the information contained in the bootstrap node record to connect to your peer-to-peer
|
||||
network.
|
||||
|
||||
```text
|
||||
"enr:-Je4QEiMeOxy_h0aweL2DtZmxnUMy-XPQcZllrMt_2V1lzynOwSx7GnjCf1k8BAsZD5dvHOBLuldzLYxpoD5UcqISiwDg2V0aMfGhGlQhqmAgmlkgnY0gmlwhKwQ_gSJc2VjcDI1NmsxoQKX_WLWgDKONsGvxtp9OeSIv2fRoGwu5vMtxfNGdut4cIN0Y3CCdl-DdWRwgnZf"
|
||||
```
|
||||
|
||||
Setting up peer-to-peer networking depends on your requirements. If you connect nodes
|
||||
across the Internet, please ensure that your bootnode and all other nodes have public IP
|
||||
addresses assigned, and both TCP and UDP traffic can pass the firewall.
|
||||
|
||||
If Internet connectivity is not required or all member nodes connect using well-known IPs,
|
||||
we strongly recommend setting up Geth to restrict peer-to-peer connectivity to an IP
|
||||
subnet. Doing so will further isolate your network and prevents cross-connecting with
|
||||
other blockchain networks in case your nodes are reachable from the Internet. Use the
|
||||
`--netrestrict` flag to configure a whitelist of IP networks:
|
||||
|
||||
```shell
|
||||
geth <other-flags> --netrestrict 172.16.254.0/24
|
||||
```
|
||||
|
||||
With the above setting, Geth will only allow connections from the 172.16.254.0/24 subnet,
|
||||
and will not attempt to connect to other nodes outside of the set IP range.
|
||||
|
||||
### Running Member Nodes
|
||||
|
||||
With the bootnode operational and externally reachable (you can try `telnet <ip> <port>`
|
||||
to ensure it's indeed reachable), you can start more Geth nodes and connect them via the
|
||||
bootstrap node using the `--bootnodes` flag.
|
||||
|
||||
To create a member node running on the same machine as the bootstrap node, choose a
|
||||
separate data directory (example: `data-2`) and listening port (example: `30305`):
|
||||
|
||||
```shell
|
||||
geth --datadir data-2 --networkid 15 --port 30305 --bootnodes <bootstrap-node-record>
|
||||
```
|
||||
|
||||
With the member node running, you can check whether it is connected to the bootstrap node
|
||||
or any other node in your network by attaching a console and running `admin.peers`. It may
|
||||
take up to a few seconds for the nodes to get connected.
|
||||
|
||||
```shell
|
||||
geth attach data-2/geth.ipc --exec admin.peers
|
||||
```
|
||||
|
||||
### Clique: Running A Signer
|
||||
|
||||
To set up Geth for signing blocks in proof-of-authority mode, a signer account must be
|
||||
available. The account must be unlocked to mine blocks. The following command will prompt
|
||||
for the account password, then start signing blocks:
|
||||
|
||||
```shell
|
||||
geth <other-flags> --unlock 0x7df9a875a174b3bc565e6424a0050ebc1b2d1d82 --mine
|
||||
```
|
||||
|
||||
You can further configure mining by changing the default gas limit blocks converge to
|
||||
(with `--targetgaslimit`) and the price transactions are accepted at (with `--gasprice`).
|
||||
|
||||
### Ethash: Running A Miner
|
||||
|
||||
For proof-of-work in a simple private network, a single CPU miner instance is enough to
|
||||
create a stable stream of blocks at regular intervals. To start a Geth instance for
|
||||
mining, run it with all the usual flags and add the following to configure mining:
|
||||
|
||||
```shell
|
||||
geth <other-flags> --mine --minerthreads=1 --etherbase=0x0000000000000000000000000000000000000000
|
||||
```
|
||||
|
||||
This will start mining bocks and transactions on a single CPU thread, crediting all block
|
||||
rewards to the account specified by `--etherbase`.
|
|
@ -1,108 +0,0 @@
|
|||
---
|
||||
title: Private network
|
||||
---
|
||||
An Ethereum network is a private network if the nodes are not connected to the main
|
||||
network nodes. In this context private only means reserved or isolated, rather than
|
||||
protected or secure.
|
||||
|
||||
## Choosing A Network ID
|
||||
|
||||
Since connections between nodes are valid only if peers have identical protocol version
|
||||
and network ID, you can effectively isolate your network by setting either of these to a
|
||||
non default value. We recommend using the `--networkid` command line option for this. Its
|
||||
argument is an integer, the main network has id 1 (the default). So if you supply your own
|
||||
custom network ID which is different than the main network your nodes will not connect to
|
||||
other nodes and form a private network.
|
||||
|
||||
## Creating The Genesis Block
|
||||
|
||||
Every blockchain starts with the genesis block. When you run geth with default settings
|
||||
for the first time, the main net genesis block is committed to the database. For a private
|
||||
network, you usually want a different genesis block.
|
||||
|
||||
Here's an example of a custom genesis.json file. The `config` section ensures that certain
|
||||
protocol upgrades are immediately available. The `alloc` section pre-funds accounts.
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"chainId": 15,
|
||||
"homesteadBlock": 0,
|
||||
"eip155Block": 0,
|
||||
"eip158Block": 0
|
||||
},
|
||||
"difficulty": "200000000",
|
||||
"gasLimit": "2100000",
|
||||
"alloc": {
|
||||
"7df9a875a174b3bc565e6424a0050ebc1b2d1d82": { "balance": "300000" },
|
||||
"f41c74c9ae680c1aa78f42e5647a62f353b7bdde": { "balance": "400000" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To create a database that uses this genesis block, run the following command. This will
|
||||
import and set the canonical genesis block for your chain.
|
||||
|
||||
```text
|
||||
geth --datadir path/to/custom/data/folder init genesis.json
|
||||
```
|
||||
|
||||
Future runs of geth on this data directory will use the genesis block you have defined.
|
||||
|
||||
```text
|
||||
geth --datadir path/to/custom/data/folder --networkid 15
|
||||
```
|
||||
|
||||
## Network Connectivity
|
||||
|
||||
With all nodes that you want to run initialized to the desired genesis state, you'll need
|
||||
to start a bootstrap node that others can use to find each other in your network and/or
|
||||
over the internet. The clean way is to configure and run a dedicated bootnode:
|
||||
|
||||
```text
|
||||
bootnode --genkey=boot.key
|
||||
bootnode --nodekey=boot.key
|
||||
```
|
||||
|
||||
With the bootnode online, it will display an enode URL that other nodes can use to connect
|
||||
to it and exchange peer information. Make sure to replace the displayed IP address
|
||||
information (most probably [::]) with your externally accessible IP to get the actual
|
||||
enode URL.
|
||||
|
||||
Note: You can also use a full fledged Geth node as a bootstrap node.
|
||||
|
||||
### Starting Up Your Member Nodes
|
||||
|
||||
With the bootnode operational and externally reachable (you can try `telnet <ip> <port>`
|
||||
to ensure it's indeed reachable), start every subsequent Geth node pointed to the bootnode
|
||||
for peer discovery via the --bootnodes flag. It will probably also be desirable to keep
|
||||
the data directory of your private network separated, so do also specify a custom
|
||||
`--datadir` flag.
|
||||
|
||||
```text
|
||||
geth --datadir path/to/custom/data/folder --networkid 15 --bootnodes <bootnode-enode-url-from-above>
|
||||
```
|
||||
|
||||
Since your network will be completely cut off from the main and test networks, you'll also
|
||||
need to configure a miner to process transactions and create new blocks for you.
|
||||
|
||||
## Running A Private Miner
|
||||
|
||||
Mining on the public Ethereum network is a complex task as it's only feasible using GPUs,
|
||||
requiring an OpenCL or CUDA enabled ethminer instance. For information on such a setup,
|
||||
please consult the EtherMining subreddit and the Genoil miner repository.
|
||||
|
||||
In a private network setting however, a single CPU miner instance is more than enough for
|
||||
practical purposes as it can produce a stable stream of blocks at the correct intervals
|
||||
without needing heavy resources (consider running on a single thread, no need for multiple
|
||||
ones either). To start a Geth instance for mining, run it with all your usual flags,
|
||||
extended by:
|
||||
|
||||
```text
|
||||
$ geth <usual-flags> --mine --minerthreads=1 --etherbase=0x0000000000000000000000000000000000000000
|
||||
```
|
||||
|
||||
Which will start mining bocks and transactions on a single CPU thread, crediting all
|
||||
proceedings to the account specified by --etherbase. You can further tune the mining by
|
||||
changing the default gas limit blocks converge to (`--targetgaslimit`) and the price
|
||||
transactions are accepted at (`--gasprice`).
|
Loading…
Reference in New Issue