CipherLabs
/
besu
mirror of https://github.com/hyperledger/besu
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Configuration file content (#517)

Browse Source 
* started

* WIP

* Added configuration file examples

* Review rework
MadelineMurray 6 years ago committed by GitHub
parent f672433fce
commit 5e46d1b2ba
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 229 additions and 79 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 48
      docs/Configuring-Pantheon/Using-Configuration-File.md
  2. 41
      docs/Getting-Started/Starting-Pantheon.md
  3. 218
      docs/Reference/Pantheon-CLI-Syntax.md
  4. 1
      mkdocs.yml

48
docs/Configuring-Pantheon/Using-Configuration-File.md
Unescape View File

@ -0,0 +1,48 @@
# Using a Configuration File
To specify command line options in a file, use a TOML configuration file.
The configuration file can be saved and reused across node startups. To specify the configuration file,
use the [`--config` option](../Reference/Pantheon-CLI-Syntax.md#config).
To override an option specified in the configuration file, specify the same option on the command line.
When an option is specified in both places, Pantheon is started with the command line value.
## TOML Specification
The configuration file must be a valid TOML file and is composed of key/value pairs. Each key is the
same as the corresponding command line option name without the leading dashes (`--`).
Values must be be specified according to TOML specifications for string, numbers, arrays, and booleans.
Specific differences between the command line and the TOML file format are:
* Comma-separated lists on the command line are string arrays in the TOML file
* File paths, hexadecimal numbers, URLs, and <host:port> values must be enclosed in quotes.
!!!tip
The [command line reference](../Reference/Pantheon-CLI-Syntax.md) includes configuration file examples for each option.
!!!example "Example TOML configuration file"
```toml
# Valid TOML config file
datadir="~/pantheondata" # Path
# Network
bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"]
p2p-listen="1.2.3.4:1234" # IP:port
max-peers=42
rpc-listen="5.6.7.8:5678" # IP:port
ws-listen="9.10.11.12:9101" # IP:port
# Chain
genesis="~/genesis.json" # Path to the custom genesis file
# Mining
miner-enabled=true
miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
```
!!!example "Starting Pantheon with a Configuration File"
```bash
pantheon --config=/home/me/me_node/config.toml
```

41
docs/Getting-Started/Starting-Pantheon.md
Unescape View File

@ -62,18 +62,25 @@ call [JSON-RPC API methods](../Reference/JSON-RPC-API-Methods.md) to confirm the
}
```
## Run a Node on Ethereum Mainnet
## Run a Node for Testing
To run a node on the Ethereum mainnet:
To run a node that mines blocks at a rate suitable for testing purposes:
```bash
$ bin/pantheon
pantheon --dev-mode --network-id="2018" --bootnodes= --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-cors-origins="all" --ws-enabled --rpc-enabled --datadir=/tmp/tmpDatdir
```
To run a node on mainnet with the HTTP JSON-RPC service enabled:
```bash
$ bin/pantheon --rpc-enabled
Alternatively, use the following [configuration file](../Configuring-Pantheon/) to start a node with the same options as the above command line:
```toml
dev-mode=true
network-id="2018"
bootnodes=[]
miner-enabled=true
miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
rpc-cors-origins="all"
ws-enabled=true
rpc-enabled=true
datadir="/tmp/tmpDatadir"
```
## Run a Node on Ropsten Testnet
@ -85,13 +92,13 @@ $ bin/pantheon --rpc-enabled
To run a node on Ropsten:
```bash
$ bin/pantheon --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303
pantheon --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303
```
To run a node on Ropsten with the HTTP JSON-RPC service enabled and allow Remix to access the node:
```bash
$ bin/pantheon --rpc-enabled --rpc-cors-origins "http://remix.ethereum.org" --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303
pantheon --rpc-enabled --rpc-cors-origins "http://remix.ethereum.org" --network-id=3 --genesis=<path>/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303
```
Where `<path>` is the path to the `/pantheon` directory.
@ -101,7 +108,7 @@ Where `<path>` is the path to the `/pantheon` directory.
To run a node on Rinkeby specifying a data directory:
```bash
$ bin/pantheon --rinkeby --datadir=<path>/rinkebyDataDir
pantheon --rinkeby --datadir=<path>/rinkebyDataDir
```
Where `<path>` and `<rinkebyDataDir>` are the path and directory where the Rinkeby chain data is to be saved.
@ -110,7 +117,7 @@ Where `<path>` and `<rinkebyDataDir>` are the path and directory where the Rinke
To run a node on [Goerli](https://github.com/goerli/testnet) specifying a data directory:
```bash
$ bin/pantheon --goerli --datadir=<path>/<goerliDataDir>
pantheon --goerli --datadir=<path>/<goerliDataDir>
```
Where `<path>` and `<goerliDataDir>` are the path and directory where the Goerli chain data is to be saved.
@ -118,10 +125,16 @@ Where `<path>` and `<goerliDataDir>` are the path and directory where the Goerli
!!!note
This option is only available from v0.8.3.
## Run a Node for Testing
## Run a Node on Ethereum Mainnet
To run a node that mines blocks at a rate suitable for testing purposes:
To run a node on the Ethereum mainnet:
```bash
pantheon
```
To run a node on mainnet with the HTTP JSON-RPC service enabled:
```bash
$ bin/pantheon --dev-mode --network-id="2018" --bootnodes= --miner-enabled --miner-coinbase fe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-cors-origins "all" --ws-enabled --rpc-enabled
pantheon --rpc-enabled
```

218
docs/Reference/Pantheon-CLI-Syntax.md
Unescape View File

@ -11,6 +11,9 @@ pantheon [OPTIONS] [COMMAND]
Runs the Pantheon Ethereum full node client.
!!!tip
Use a [configuration file](../Configuring-Pantheon/Using-Configuration-File.md) to save the command line options in a file.
## Options
### accounts-whitelist
@ -34,8 +37,12 @@ Comma separated account public keys for permissioned transactions. You can speci
--banned-nodeids=<bannedNodeId>[,<bannedNodeId>...]...
```
```bash tab="Example"
--banned-nodeids=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303
```bash tab="Example Command Line"
--banned-nodeids=0xc35c3...d615f,0xf42c13...fc456
```
```bash tab="Example Configuration File"
banned-nodeids=["0xc35c3...d615f","0xf42c13...fc456"]
```
List of node IDs with which this node will not peer. The node ID is the public key of the node. You can specify the banned node IDs with or without the `0x` prefix.
@ -49,15 +56,18 @@ List of node IDs with which this node will not peer. The node ID is the public k
--bootnodes=<enode://id@host:port>[,<enode://id@host:port>...]...
```
```bash tab="Example"
```bash tab="Example Command Line"
--bootnodes=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303
```
```bash tab="Example Configuration File"
bootnodes=["enode://c35c3...d615f@1.2.3.4:30303","enode://f42c13...fc456@1.2.3.5:30303"]
```
List of comma-separated enode URLs for P2P discovery bootstrap.
When connecting to mainnet and Rinkeby, the default is a predefined list of enode URLs.
Specify bootnodes when [connecting to Ropsten](../Getting-Started/Starting-Pantheon.md#run-a-node-on-ropsten-testnet) or
a [private network](../Configuring-Pantheon/Testing-Developing-Nodes.md#bootnodes).
When connecting to mainnet or public testnets, the default is a predefined list of enode URLs.
Specify bootnodes when connecting to a [private network](../Configuring-Pantheon/Testing-Developing-Nodes.md#bootnodes).
### config
@ -65,39 +75,15 @@ a [private network](../Configuring-Pantheon/Testing-Developing-Nodes.md#bootnode
--config=<PATH>
```
```bash tab="Example"
```bash tab="Example Command Line"
--config=/home/me/me_node/config.toml
```
The path to the TOML configuration file.
The path to the [TOML configuration file](../Configuring-Pantheon/Using-Configuration-File.md).
The default is `none`.
The TOML file is composed of key/value pairs.
Each key is the same as the corresponding CLI option name without the leading dashes (`--`).
The config option is not used in the config file.
Values must be treated according to TOML specifications for string, numbers, arrays and Booleans.
!!!example "Example TOML configuration file"
```toml
# Valid TOML config file
datadir="~/pantheondata" # Path
# Network
bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"]
p2p-listen="1.2.3.4:1234" # IP:port
max-peers=42
rpc-listen="5.6.7.8:5678" # IP:port
ws-listen="9.10.11.12:9101" # IP:port
# Chain
genesis="~/genesis.json" # Path to the custom genesis file
# Mining
miner-enabled=true
miner-coinbase="0x0000000000000000000000000000000000000002"
```
!!!note
This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#custom-configuration-file).
This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#custom-configuration-file) or in a [configuration file](../Configuring-Pantheon/Using-Configuration-File.md).
### datadir
@ -105,11 +91,15 @@ Values must be treated according to TOML specifications for string, numbers, arr
--datadir=<PATH>
```
```bash tab="Example"
```bash tab="Example Command Line"
--datadir=/home/me/me_node
```
The path to the Pantheon data directory. The default location is the `/build/distributions/pantheon-<version>` directory in the Pantheon installation directory.
```bash tab="Example Configuration File"
datadir="/home/me/me_node"
```
The path to the Pantheon data directory. The default is the `/build/distributions/pantheon-<version>` directory in the Pantheon installation directory.
!!!note
This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#persisting-data).
@ -121,6 +111,10 @@ The path to the Pantheon data directory. The default location is the `/build/dis
--dev-mode
```
```bash tab="Example Configuration File"
dev-mode=true
```
Set this option to `true` to run in development mode.
For example, specify this option to perform CPU mining more easily in a private test network.
In development mode, a custom genesis configuration specifies the chain ID.
@ -138,8 +132,12 @@ Default is `false`.
--genesis=<PATH>
```
```bash tab="Example"
--genesis=/home/me/me_node/genesis_calling_all_stations.json
```bash tab="Example Command Line"
--genesis=/home/me/me_node/customGenesisFile.json
```
```bash tab="Example Configuration File"
genesis="/home/me/me_node/customGenesisFile.json"
```
The path to the genesis file. The default is the embedded genesis file for the Ethereum mainnet.
@ -159,6 +157,10 @@ When using this option, it is recommended to also set the [`--network-id`](#netw
--goerli
```
```bash tab="Example Configuration File"
goerli=true
```
Uses the Goerli test network. Default is false.
!!!note
@ -171,10 +173,14 @@ Uses the Goerli test network. Default is false.
--host-whitelist=<hostname>[,<hostname>...]... or * or all
```
```bash tab="Example"
```bash tab="Example Command Line"
--host-whitelist=medomain.com,meotherdomain.com
```
```bash tab="Example Configuration File"
host-whitelist=["medomain.com", "meotherdomain.com"]
```
Comma-separated list of hostnames to allow access to the HTTP JSON-RPC API. Default is `localhost`.
!!!tip
@ -189,10 +195,14 @@ Comma-separated list of hostnames to allow access to the HTTP JSON-RPC API. Defa
--max-peers=<INTEGER>
```
```bash tab="Example"
```bash tab="Example Command Line"
--max-peers=42
```
```bash tab="Example Configuration File"
max-peers=42
```
Specifies the maximum P2P peer connections that can be established.
The default is 25.
@ -202,10 +212,14 @@ The default is 25.
--max-trailing-peers=<INTEGER>
```
```bash tab="Example"
```bash tab="Example Command Line"
--max-trailing-peers=2
```
```bash tab="Example Configuration File"
max-trailing-peers=2
```
Specifies the maximum P2P peer connections for peers that are trailing behind the local chain head.
The default is unlimited but the number of trailing peers cannot exceed the value specified by [`--max-peers`](#max-peers).
@ -215,10 +229,14 @@ The default is unlimited but the number of trailing peers cannot exceed the valu
--miner-coinbase=<Ethereum account address>
```
```bash tab="Example"
```bash tab="Example Command Line"
--miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73
```
```bash tab="Example Configuration File"
--miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
```
Account to which mining rewards are paid.
You must specify a valid coinbase when you enable mining using the [`--miner-enabled`](#miner-enabled)
option or the [`miner_start`](JSON-RPC-API-Methods.md#miner_start) JSON RPC-API method.
@ -232,7 +250,11 @@ option or the [`miner_start`](JSON-RPC-API-Methods.md#miner_start) JSON RPC-API
--miner-enabled
```
Enables mining when the node is starts.
```bash tab="Example Configuration File"
miner-enabled=true
```
Enables mining when the node is started.
Default is `false`.
### miner-extraData
@ -241,10 +263,14 @@ Default is `false`.
--miner-extraData=<Extra data>
```
```bash tab="Example"
```bash tab="Example Command Line"
--miner-extraData=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021
```
```bash tab="Example Configuration File"
miner-extraData="0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021"
```
A hex string representing the 32 bytes to be included in the extra data field of a mined block.
The default is 0x.
@ -254,10 +280,14 @@ The default is 0x.
--miner-minTransactionGasPriceWei=<minTransactionGasPrice>
```
```bash tab="Example"
```bash tab="Example Command Line"
--miner-minTransactionGasPriceWei=1337
```
```bash tab="Example Configuration File"
miner-minTransactionGasPriceWei="1337"
```
The minimum price that a transaction offers for it to be included in a mined block.
The default is 1000.
@ -267,10 +297,14 @@ The default is 1000.
--network-id=<INTEGER>
```
```bash tab="Example"
```bash tab="Example Command Line"
--network-id=8675309
```
```bash tab="Example Configuration File"
network-id="8675309"
```
P2P network identifier.
The default is set to mainnet with value `1`.
@ -280,6 +314,10 @@ The default is set to mainnet with value `1`.
--no-discovery
```
```bash tab="Example Configuration File"
no-discovery=true
```
Disables P2P peer discovery.
The default is `false`.
@ -289,8 +327,12 @@ The default is `false`.
--node-private-key=<PATH>
```
```bash tab="Example"
--node-private-key=/home/me/me_node/my_precious
```bash tab="Example Command Line"
--node-private-key=/home/me/me_node/myPrivateKey
```
```bash tab="Example Configuration File"
node-private-key="/home/me/me_node/myPrivateKey"
```
`<PATH>` is the path of the private key file of the node.
@ -308,13 +350,17 @@ otherwise, the existing key file specifies the node private key.
### nodes-whitelist
```bash tab="Syntax"
--nodes-whitelist=[=<enode://id@host:port>[,<enode://id@host:port>...]...]
--nodes-whitelist[=<enode://id@host:port>[,<enode://id@host:port>...]...]
```
```bash tab="Example"
```bash tab="Example Command Line"
--nodes-whitelist=enode://c35c3...d615f@3.14.15.92:30303,enode://f42c13...fc456@65.35.89.79:30303
```
```bash tab="Example Configuration File"
nodes-whitelist=["enode://c35c3...d615f@3.14.15.92:30303","enode://f42c13...fc456@65.35.89.79:30303"]
```
Comma-separated enode URLs for permissioned networks.
Not intended for use with mainnet or public testnets.
@ -331,6 +377,10 @@ Not intended for use with mainnet or public testnets.
--ottoman
```
```bash tab="Example Configuration File"
ottoman=true
```
Synchronize against the Ottoman test network. This is only useful if you are using an IBFT genesis file. The default is `false`.
!!!note
@ -342,11 +392,15 @@ Synchronize against the Ottoman test network. This is only useful if you are usi
--p2p-listen=<HOST:PORT>
```
```bash tab="Example"
```bash tab="Example Command Line"
# to listen on all interfaces on port 1789
--p2p-listen=0.0.0.0:1789
```
```bash tab="Example Configuration File"
p2p-listen="0.0.0.0:1789"
```
Specifies the host and port on which P2P peer discovery listens.
The default is 127.0.0.1:30303.
@ -359,6 +413,10 @@ The default is 127.0.0.1:30303.
--rinkeby
```
```bash tab="Example Configuration File"
rinkeby=true
```
Uses the Rinkeby test network.
Default is `false`.
@ -369,6 +427,10 @@ Default is `false`.
--ropsten
```
```bash tab="Example Configuration File"
ropsten=true
```
Uses the Ropsten test network.
Default is `false`.
@ -381,6 +443,10 @@ Default is `false`.
--rpc-enabled
```
```bash tab="Example Configuration File"
rpc-enabled=true
```
Set to `true` to enable the JSON-RPC service (RPC over HTTP).
The default is `false`.
@ -390,9 +456,13 @@ The default is `false`.
--rpc-listen=<HOST:PORT>
```
```bash tab="Example"
```bash tab="Example Command Line"
# to listen on all interfaces on port 3435
--rpc-listen=0.0.0.0:3435.
--rpc-listen=0.0.0.0:3435
```
```bash tab="Example Configuration File"
rpc-listen="0.0.0.0:3435"
```
Specifies the host and port on which JSON-RPC listens.
@ -407,10 +477,14 @@ The default is 127.0.0.1:8545.
--rpc-api=<api name>[,<api name>...]...
```
```bash tab="Example"
```bash tab="Example Command Line"
--rpc-api=ETH,NET,WEB3
```
```bash tab="Example Configuration File"
rpc-api=["ETH","NET","WEB3"]
```
Comma-separated APIs to enable on the JSON-RPC channel.
When you use this option, the `--rpc-enabled` option must also be specified.
The available API options are: `ADMIN`, `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `DEBUG`, and `MINER`.
@ -422,25 +496,23 @@ The default is: `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`.
### rpc-cors-origins
```bash tab="Syntax"
--rpc-cors-origins=<rpcCorsAllowedOrigins>
```
```bash tab="Single domain xample"
# You can whitelist one single domains.
--rpc-cors-origins="http://medomain.com"
--rpc-cors-origins=<rpcCorsAllowedOrigins> or all
```
```bash tab="Multiple domains example"
```bash tab="Example Command Line"
# You can whitelist one or more domains with a comma-separated list.
--rpc-cors-origins="http://medomain.com","https://meotherdomain.com"
```
```bash tab="Example Configuration File"
rpc-cors-origins=["http://medomain.com","https://meotherdomain.com"]
```
```bash tab="Remix IDE domain example"
# The following allows Remix to interact with your Pantheon node without using MetaMask.
--rpc-cors-origins "http://remix.ethereum.org"
--rpc-cors-origins="http://remix.ethereum.org"
```
Specifies domain URLs for CORS validation.
@ -466,6 +538,10 @@ If you don't whitelist any domains, you won't be able to use webapps to interact
--ws-enabled
```
```bash tab="Example Configuration File"
ws-enabled=true
```
Set to `true` to enable the WS-RPC (WebSockets) service.
The default is `false`.
@ -475,10 +551,14 @@ The default is `false`.
--ws-api=<api name>[,<api name>...]...
```
```bash tab="Example"
```bash tab="Example Command Line"
--ws-api=ETH,NET,WEB3
```
```bash tab="Example Configuration File"
ws-api=["ETH","NET","WEB3"]
```
Comma-separated APIs to enable on Websockets channel.
When you use this option, the `--ws-enabled` option must also be specified.
The available API options are: `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `DEBUG`, and `MINER`.
@ -493,11 +573,15 @@ The default is: `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`.
--ws-listen=<HOST:PORT>
```
```bash tab="Example"
```bash tab="Example Command Line"
# to listen on all interfaces on port 6174
--ws-listen=0.0.0.0:6174
```
```bash tab="Example Configuration File"
ws-listen="0.0.0.0:6174"
```
Host and port for WS-RPC (Websocket) to listen on.
The default is 127.0.0.1:8546.
@ -532,10 +616,14 @@ Show the help message and exit.
-l, --logging=<LEVEL>
```
```bash tab="Example"
```bash tab="Example Command Line"
--logging=DEBUG
```
```bash tab="Example Configration File"
logging="DEBUG"
```
Sets the logging verbosity.
Log levels are `OFF`, `FATAL`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`.
Default is `INFO`.

1
mkdocs.yml
Unescape View File

@ -57,6 +57,7 @@ nav:
- Tutorials:
- Creating a Private Network: Tutorials/Create-Private-Network.md
- Configuring Pantheon:
- Using a Configuration File: Configuring-Pantheon/Using-Configuration-File.md
- Network ID and Chain ID: Configuring-Pantheon/NetworkID-And-ChainID.md
- Node Keys: Configuring-Pantheon/Node-Keys.md
- Networking: Configuring-Pantheon/Networking.md

Write Preview
Loading…
Cancel
Save