From 4d06349d954c10f4207695d3ca358a0a0ad1f177 Mon Sep 17 00:00:00 2001 From: Pratik Patil Date: Thu, 1 Dec 2022 09:20:17 +0530 Subject: [PATCH] added a toml configuration file with comments describing each flag (#607) * added a toml configuration file with comments describing each flag * internal/cli/server: update flag description * docs/cli: update example config and description of flags * docs: update new-cli docs Co-authored-by: Manav Darji --- docs/README.md | 12 ++- docs/cli/example_config.toml | 141 +++++++++++++++++++++++++++++++++ docs/cli/server.md | 14 ++-- docs/config.md | 146 ----------------------------------- internal/cli/server/flags.go | 10 +-- 5 files changed, 159 insertions(+), 164 deletions(-) create mode 100644 docs/cli/example_config.toml delete mode 100644 docs/config.md diff --git a/docs/README.md b/docs/README.md index 5ebdbd7e26..45021e8c7f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,7 @@ # Documentation -- [Command-line-interface](./cli) - -- [Configuration file](./config.md) +- [The new command line interface](./cli) ## Additional notes @@ -13,8 +11,14 @@ $ bor server ``` -- Toml files used earlier just to configure static/trusted nodes are being deprecated. Instead, a toml file now can be used instead of flags and can contain all configuration for the node to run. The link to a sample config file is given above. To simply run bor with a configuration file, the following command can be used. +- The `bor dumpconfig` sub-command prints the default configurations, in the TOML format, on the terminal. One can `pipe (>)` this to a file (say `config.toml`) and use it to start bor. + +- A toml file now can be used instead of flags and can contain all configuration for the node to run. To simply run bor with a configuration file, the following command can be used. ``` $ bor server --config ``` + +- You can find an example config file [here](./cli/example_config.toml) to know more about what each flag is used for, what are the defaults and recommended values for different networks. + +- Toml files used earlier (with `--config` flag) to configure additional fields (like static and trusted nodes) are being deprecated and have been converted to flags. diff --git a/docs/cli/example_config.toml b/docs/cli/example_config.toml new file mode 100644 index 0000000000..bc48b752d5 --- /dev/null +++ b/docs/cli/example_config.toml @@ -0,0 +1,141 @@ +# This configuration file is for reference and learning purpose only. +# The default value of the flags is provided below (except a few flags which has custom defaults which are explicitly mentioned). +# Recommended values for mainnet and/or mumbai are also provided. + +chain = "mainnet" # Name of the chain to sync ("mumbai", "mainnet") or path to a genesis file +identity = "Annon-Identity" # Name/Identity of the node (default = OS hostname) +log-level = "INFO" # Set log level for the server +datadir = "var/lib/bor" # Path of the data directory to store information +keystore = "" # Path of the directory where keystores are located +syncmode = "full" # Blockchain sync mode (only "full" sync supported) +gcmode = "full" # Blockchain garbage collection mode ("full", "archive") +snapshot = true # Enables the snapshot-database mode +"bor.logs" = false # Enables bor log retrieval +ethstats = "" # Reporting URL of a ethstats service (nodename:secret@host:port) + +["eth.requiredblocks"] # Comma separated block number-to-hash mappings to require for peering (=) (default = empty map) + "31000000" = "0x2087b9e2b353209c2c21e370c82daa12278efd0fe5f0febe6c29035352cf050e" + "32000000" = "0x875500011e5eecc0c554f95d07b31cf59df4ca2505f4dbbfffa7d4e4da917c68" + +[p2p] + maxpeers = 50 # Maximum number of network peers (network disabled if set to 0) + maxpendpeers = 50 # Maximum number of pending connection attempts + bind = "0.0.0.0" # Network binding address + port = 30303 # Network listening port + nodiscover = false # Disables the peer discovery mechanism (manual peer addition) + nat = "any" # NAT port mapping mechanism (any|none|upnp|pmp|extip:) + [p2p.discovery] + v5disc = false # Enables the experimental RLPx V5 (Topic Discovery) mechanism + bootnodes = [] # Comma separated enode URLs for P2P discovery bootstrap + bootnodesv4 = [] # List of initial v4 bootnodes + bootnodesv5 = [] # List of initial v5 bootnodes + static-nodes = [] # List of static nodes + trusted-nodes = [] # List of trusted nodes + dns = [] # List of enrtree:// URLs which will be queried for nodes to connect to + +[heimdall] + url = "http://localhost:1317" # URL of Heimdall service + "bor.without" = false # Run without Heimdall service (for testing purpose) + grpc-address = "" # Address of Heimdall gRPC service + +[txpool] + locals = [] # Comma separated accounts to treat as locals (no flush, priority inclusion) + nolocals = false # Disables price exemptions for locally submitted transactions + journal = "transactions.rlp" # Disk journal for local transaction to survive node restarts + rejournal = "1h0m0s" # Time interval to regenerate the local transaction journal + pricelimit = 1 # Minimum gas price limit to enforce for acceptance into the pool (mainnet = 30000000000) + pricebump = 10 # Price bump percentage to replace an already existing transaction + accountslots = 16 # Minimum number of executable transaction slots guaranteed per account + globalslots = 32768 # Maximum number of executable transaction slots for all accounts + accountqueue = 16 # Maximum number of non-executable transaction slots permitted per account + globalqueue = 32768 # Maximum number of non-executable transaction slots for all accounts + lifetime = "3h0m0s" # Maximum amount of time non-executable transaction are queued + +[miner] + mine = false # Enable mining + etherbase = "" # Public address for block mining rewards + extradata = "" # Block extra data set by the miner (default = client version) + gaslimit = 30000000 # Target gas ceiling for mined blocks + gasprice = "1000000000" # Minimum gas price for mining a transaction (recommended for mainnet = 30000000000, default suitable for mumbai/devnet) + +[jsonrpc] + ipcdisable = false # Disable the IPC-RPC server + ipcpath = "" # Filename for IPC socket/pipe within the datadir (explicit paths escape it) + gascap = 50000000 # Sets a cap on gas that can be used in eth_call/estimateGas (0=infinite) + txfeecap = 5.0 # Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap) + [jsonrpc.http] + enabled = false # Enable the HTTP-RPC server + port = 8545 # http.port + prefix = "" # http.rpcprefix + host = "localhost" # HTTP-RPC server listening interface + api = ["eth", "net", "web3", "txpool", "bor"] # API's offered over the HTTP-RPC interface + vhosts = ["localhost"] # Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. + corsdomain = ["localhost"] # Comma separated list of domains from which to accept cross origin requests (browser enforced) + [jsonrpc.ws] + enabled = false # Enable the WS-RPC server + port = 8546 # WS-RPC server listening port + prefix = "" # HTTP path prefix on which JSON-RPC is served. Use '/' to serve on all paths. + host = "localhost" # ws.addr + api = ["net", "web3"] # API's offered over the WS-RPC interface + origins = ["localhost"] # Origins from which to accept websockets requests + [jsonrpc.graphql] + enabled = false # Enable GraphQL on the HTTP-RPC server. Note that GraphQL can only be started if an HTTP server is started as well. + port = 0 # + prefix = "" # + host = "" # + vhosts = ["localhost"] # Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. + corsdomain = ["localhost"] # Comma separated list of domains from which to accept cross origin requests (browser enforced) + +[gpo] + blocks = 20 # Number of recent blocks to check for gas prices + percentile = 60 # Suggested gas price is the given percentile of a set of recent transaction gas prices + maxprice = "5000000000000" # Maximum gas price will be recommended by gpo + ignoreprice = "2" # Gas price below which gpo will ignore transactions (recommended for mainnet = 30000000000, default suitable for mumbai/devnet) + +[telemetry] + metrics = false # Enable metrics collection and reporting + expensive = false # Enable expensive metrics collection and reporting + prometheus-addr = "127.0.0.1:7071" # Address for Prometheus Server + opencollector-endpoint = "127.0.0.1:4317" # OpenCollector Endpoint (host:port) + [telemetry.influx] + influxdb = false # Enable metrics export/push to an external InfluxDB database (v1) + endpoint = "" # InfluxDB API endpoint to report metrics to + database = "" # InfluxDB database name to push reported metrics to + username = "" # Username to authorize access to the database + password = "" # Password to authorize access to the database + influxdbv2 = false # Enable metrics export/push to an external InfluxDB v2 database + token = "" # Token to authorize access to the database (v2 only) + bucket = "" # InfluxDB bucket name to push reported metrics to (v2 only) + organization = "" # InfluxDB organization name (v2 only) + [telemetry.influx.tags] # Comma-separated InfluxDB tags (key/values) attached to all measurements + cloud = "aws" + host = "annon-host" + ip = "99.911.221.66" + region = "us-north-1" + +[cache] + cache = 1024 # Megabytes of memory allocated to internal caching (recommended for mainnet = 4096, default suitable for mumbai/devnet) + gc = 25 # Percentage of cache memory allowance to use for trie pruning (default = 25% full mode, 0% archive mode) + snapshot = 10 # Percentage of cache memory allowance to use for snapshot caching (default = 10% full mode, 20% archive mode) + database = 50 # Percentage of cache memory allowance to use for database io + trie = 15 # Percentage of cache memory allowance to use for trie caching (default = 15% full mode, 30% archive mode) + journal = "triecache" # Disk journal directory for trie cache to survive node restarts + rejournal = "1h0m0s" # Time interval to regenerate the trie cache journal + noprefetch = false # Disable heuristic state prefetch during block import (less CPU and disk IO, more time waiting for data) + preimages = false # Enable recording the SHA3/keccak preimages of trie keys + txlookuplimit = 2350000 # Number of recent blocks to maintain transactions index for (default = about 56 days, 0 = entire chain) + triesinmemory = 128 # Number of block states (tries) to keep in memory + +[accounts] + unlock = [] # Comma separated list of accounts to unlock + password = "" # Password file to use for non-interactive password input + allow-insecure-unlock = false # Allow insecure account unlocking when account-related RPCs are exposed by http + lightkdf = false # Reduce key-derivation RAM & CPU usage at some expense of KDF strength + disable-bor-wallet = true # Disable the personal wallet endpoints + +[grpc] + addr = ":3131" # Address and port to bind the GRPC server + +[developer] + dev = false # Enable developer mode with ephemeral proof-of-authority network and a pre-funded developer account, mining enabled + period = 0 # Block period to use in developer mode (0 = mine only if transaction pending) diff --git a/docs/cli/server.md b/docs/cli/server.md index d52b135fa3..4c291a74b9 100644 --- a/docs/cli/server.md +++ b/docs/cli/server.md @@ -4,7 +4,7 @@ The ```bor server``` command runs the Bor client. ## Options -- ```chain```: Name of the chain to sync +- ```chain```: Name of the chain to sync ('mumbai', 'mainnet') or path to a genesis file - ```identity```: Name/Identity of the node @@ -12,7 +12,7 @@ The ```bor server``` command runs the Bor client. - ```datadir```: Path of the data directory to store information -- ```keystore```: Path of the directory to store keystores +- ```keystore```: Path of the directory where keystores are located - ```config```: File for the config file @@ -30,8 +30,6 @@ The ```bor server``` command runs the Bor client. - ```bor.withoutheimdall```: Run without Heimdall service (for testing purpose) -- ```bor.heimdallgRPC```: Address of Heimdall gRPC service - - ```ethstats```: Reporting URL of a ethstats service (nodename:secret@host:port) - ```gpo.blocks```: Number of recent blocks to check for gas prices @@ -80,8 +78,6 @@ The ```bor server``` command runs the Bor client. - ```cache.preimages```: Enable recording the SHA3/keccak preimages of trie keys -- ```cache.triesinmemory```: Number of block states (tries) to keep in memory (default = 128) - - ```txlookuplimit```: Number of recent blocks to maintain transactions index for (default = about 56 days, 0 = entire chain) ### JsonRPC Options @@ -136,7 +132,7 @@ The ```bor server``` command runs the Bor client. - ```maxpeers```: Maximum number of network peers (network disabled if set to 0) -- ```maxpendpeers```: Maximum number of pending connection attempts (defaults used if set to 0) +- ```maxpendpeers```: Maximum number of pending connection attempts - ```nat```: NAT port mapping mechanism (any|none|upnp|pmp|extip:) @@ -148,11 +144,11 @@ The ```bor server``` command runs the Bor client. - ```mine```: Enable mining -- ```miner.etherbase```: Public address for block mining rewards (default = first account) +- ```miner.etherbase```: Public address for block mining rewards - ```miner.extradata```: Block extra data set by the miner (default = client version) -- ```miner.gaslimit```: Target gas ceiling for mined blocks +- ```miner.gaslimit```: Target gas ceiling (gas limit) for mined blocks - ```miner.gasprice```: Minimum gas price for mining a transaction diff --git a/docs/config.md b/docs/config.md deleted file mode 100644 index 57f4c25fef..0000000000 --- a/docs/config.md +++ /dev/null @@ -1,146 +0,0 @@ - -# Config - -- The `bor dumpconfig` command prints the default configurations, in the TOML format, on the terminal. - - One can `pipe (>)` this to a file (say `config.toml`) and use it to start bor. - - Command to provide a config file: `bor server -config config.toml` -- Bor uses TOML, HCL, and JSON format config files. -- This is the format of the config file in TOML: - - **NOTE: The values of these following flags are just for reference** - - `config.toml` file: -``` -chain = "mainnet" -identity = "myIdentity" -log-level = "INFO" -datadir = "/var/lib/bor/data" -keystore = "path/to/keystore" -syncmode = "full" -gcmode = "full" -snapshot = true -ethstats = "" - -["eth.requiredblocks"] - -[p2p] -maxpeers = 50 -maxpendpeers = 50 -bind = "0.0.0.0" -port = 30303 -nodiscover = false -nat = "any" - -[p2p.discovery] -v5disc = false -bootnodes = ["enode://d860a01f9722d78051619d1e2351aba3f43f943f6f00718d1b9baa4101932a1f5011f16bb2b1bb35db20d6fe28fa0bf09636d26a87d31de9ec6203eeedb1f666@18.138.108.67:30303", "enode://22a8232c3abc76a16ae9d6c3b164f98775fe226f0917b0ca871128a74a8e9630b458460865bab457221f1d448dd9791d24c4e5d88786180ac185df813a68d4de@3.209.45.79:30303"] -bootnodesv4 = [] -bootnodesv5 = ["enr:-KG4QOtcP9X1FbIMOe17QNMKqDxCpm14jcX5tiOE4_TyMrFqbmhPZHK_ZPG2Gxb1GE2xdtodOfx9-cgvNtxnRyHEmC0ghGV0aDKQ9aX9QgAAAAD__________4JpZIJ2NIJpcIQDE8KdiXNlY3AyNTZrMaEDhpehBDbZjM_L9ek699Y7vhUJ-eAdMyQW_Fil522Y0fODdGNwgiMog3VkcIIjKA", "enr:-KG4QDyytgmE4f7AnvW-ZaUOIi9i79qX4JwjRAiXBZCU65wOfBu-3Nb5I7b_Rmg3KCOcZM_C3y5pg7EBU5XGrcLTduQEhGV0aDKQ9aX9QgAAAAD__________4JpZIJ2NIJpcIQ2_DUbiXNlY3AyNTZrMaEDKnz_-ps3UUOfHWVYaskI5kWYO_vtYMGYCQRAR3gHDouDdGNwgiMog3VkcIIjKA"] -static-nodes = ["enode://8499da03c47d637b20eee24eec3c356c9a2e6148d6fe25ca195c7949ab8ec2c03e3556126b0d7ed644675e78c4318b08691b7b57de10e5f0d40d05b09238fa0a@52.187.207.27:30303"] -trusted-nodes = ["enode://2b252ab6a1d0f971d9722cb839a42cb81db019ba44c08754628ab4a823487071b5695317c8ccd085219c3a03af063495b2f1da8d18218da2d6a82981b45e6ffc@65.108.70.101:30303"] -dns = [] - -[heimdall] -url = "http://localhost:1317" -"bor.without" = false - -[txpool] -locals = ["$ADDRESS1", "$ADDRESS2"] -nolocals = false -journal = "" -rejournal = "1h0m0s" -pricelimit = 30000000000 -pricebump = 10 -accountslots = 16 -globalslots = 32768 -accountqueue = 16 -globalqueue = 32768 -lifetime = "3h0m0s" - -[miner] -mine = false -etherbase = "" -extradata = "" -gaslimit = 20000000 -gasprice = "30000000000" - -[jsonrpc] -ipcdisable = false -ipcpath = "/var/lib/bor/bor.ipc" -gascap = 50000000 -txfeecap = 5e+00 - -[jsonrpc.http] -enabled = false -port = 8545 -prefix = "" -host = "localhost" -api = ["eth", "net", "web3", "txpool", "bor"] -vhosts = ["*"] -corsdomain = ["*"] - -[jsonrpc.ws] -enabled = false -port = 8546 -prefix = "" -host = "localhost" -api = ["web3", "net"] -vhosts = ["*"] -corsdomain = ["*"] - -[jsonrpc.graphql] -enabled = false -port = 0 -prefix = "" -host = "" -api = [] -vhosts = ["*"] -corsdomain = ["*"] - -[gpo] -blocks = 20 -percentile = 60 -maxprice = "5000000000000" -ignoreprice = "2" - -[telemetry] -metrics = false -expensive = false -prometheus-addr = "" -opencollector-endpoint = "" - -[telemetry.influx] -influxdb = false -endpoint = "" -database = "" -username = "" -password = "" -influxdbv2 = false -token = "" -bucket = "" -organization = "" - -[cache] -cache = 1024 -gc = 25 -snapshot = 10 -database = 50 -trie = 15 -journal = "triecache" -rejournal = "1h0m0s" -noprefetch = false -preimages = false -txlookuplimit = 2350000 - -[accounts] -unlock = ["$ADDRESS1", "$ADDRESS2"] -password = "path/to/password.txt" -allow-insecure-unlock = false -lightkdf = false -disable-bor-wallet = false - -[grpc] -addr = ":3131" - -[developer] -dev = false -period = 0 -``` diff --git a/internal/cli/server/flags.go b/internal/cli/server/flags.go index 79aec3157a..550d76942b 100644 --- a/internal/cli/server/flags.go +++ b/internal/cli/server/flags.go @@ -11,7 +11,7 @@ func (c *Command) Flags() *flagset.Flagset { f.StringFlag(&flagset.StringFlag{ Name: "chain", - Usage: "Name of the chain to sync", + Usage: "Name of the chain to sync ('mumbai', 'mainnet') or path to a genesis file", Value: &c.cliConfig.Chain, Default: c.cliConfig.Chain, }) @@ -35,7 +35,7 @@ func (c *Command) Flags() *flagset.Flagset { }) f.StringFlag(&flagset.StringFlag{ Name: "keystore", - Usage: "Path of the directory to store keystores", + Usage: "Path of the directory where keystores are located", Value: &c.cliConfig.KeyStoreDir, }) f.StringFlag(&flagset.StringFlag{ @@ -176,7 +176,7 @@ func (c *Command) Flags() *flagset.Flagset { }) f.StringFlag(&flagset.StringFlag{ Name: "miner.etherbase", - Usage: "Public address for block mining rewards (default = first account)", + Usage: "Public address for block mining rewards", Value: &c.cliConfig.Sealer.Etherbase, Default: c.cliConfig.Sealer.Etherbase, Group: "Sealer", @@ -190,7 +190,7 @@ func (c *Command) Flags() *flagset.Flagset { }) f.Uint64Flag(&flagset.Uint64Flag{ Name: "miner.gaslimit", - Usage: "Target gas ceiling for mined blocks", + Usage: "Target gas ceiling (gas limit) for mined blocks", Value: &c.cliConfig.Sealer.GasCeil, Default: c.cliConfig.Sealer.GasCeil, Group: "Sealer", @@ -485,7 +485,7 @@ func (c *Command) Flags() *flagset.Flagset { }) f.Uint64Flag(&flagset.Uint64Flag{ Name: "maxpendpeers", - Usage: "Maximum number of pending connection attempts (defaults used if set to 0)", + Usage: "Maximum number of pending connection attempts", Value: &c.cliConfig.P2P.MaxPendPeers, Default: c.cliConfig.P2P.MaxPendPeers, Group: "P2P",