diff --git a/docs/Configuring-Pantheon/Using-Configuration-File.md b/docs/Configuring-Pantheon/Using-Configuration-File.md new file mode 100644 index 0000000000..676c3b1070 --- /dev/null +++ b/docs/Configuring-Pantheon/Using-Configuration-File.md @@ -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 + ``` diff --git a/docs/Getting-Started/Starting-Pantheon.md b/docs/Getting-Started/Starting-Pantheon.md index 78a4aba2ff..064600d2e4 100644 --- a/docs/Getting-Started/Starting-Pantheon.md +++ b/docs/Getting-Started/Starting-Pantheon.md @@ -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=/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=/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=/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=/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303 ``` Where `` is the path to the `/pantheon` directory. @@ -101,7 +108,7 @@ Where `` is the path to the `/pantheon` directory. To run a node on Rinkeby specifying a data directory: ```bash -$ bin/pantheon --rinkeby --datadir=/rinkebyDataDir +pantheon --rinkeby --datadir=/rinkebyDataDir ``` Where `` and `` are the path and directory where the Rinkeby chain data is to be saved. @@ -110,7 +117,7 @@ Where `` and `` 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=/ +pantheon --goerli --datadir=/ ``` Where `` and `` are the path and directory where the Goerli chain data is to be saved. @@ -118,10 +125,16 @@ Where `` and `` 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 ``` \ No newline at end of file diff --git a/docs/Reference/Pantheon-CLI-Syntax.md b/docs/Reference/Pantheon-CLI-Syntax.md index d258d0f7ec..c6213520e5 100644 --- a/docs/Reference/Pantheon-CLI-Syntax.md +++ b/docs/Reference/Pantheon-CLI-Syntax.md @@ -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=[,...]... ``` -```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=[,...]... ``` -```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= ``` -```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= ``` -```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-` 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-` 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). @@ -120,6 +110,10 @@ The path to the Pantheon data directory. The default location is the `/build/dis ```bash tab="Syntax" --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. @@ -138,8 +132,12 @@ Default is `false`. --genesis= ``` -```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=[,...]... 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= ``` -```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= ``` -```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= ``` -```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= ``` -```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= ``` -```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= ``` -```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= ``` -```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" ``` `` 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=[=[,...]...] +--nodes-whitelist[=[,...]...] ``` -```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= ``` -```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= ``` -```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=[,...]... ``` -```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= +--rpc-cors-origins= or all ``` -```bash tab="Single domain xample" -# You can whitelist one single domains. - ---rpc-cors-origins="http://medomain.com" -``` - -```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=[,...]... ``` -```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= ``` -```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= ``` -```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`. diff --git a/mkdocs.yml b/mkdocs.yml index 0f1a113b5b..82e2d08bcd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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