QI Blockchain CLI Parameters

This reference describes the syntax of the QI Blockchain Command Line Interface (CLI) options.
Specifying options
You can specify QI options:
On the command line.
besu [OPTIONS] [SUBCOMMAND]
As an environment variable. For each command line option, the equivalent environment variable is:
Uppercase.
_ replaces -.
Has a BESU_ prefix.
For example, set --miner-coinbase using the BESU_MINER_COINBASE environment variable.
If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file.
If using Bash or Z shell, you can view option suggestions by entering -- and pressing the Tab key twice.
besu --Tab+Tab
Options
api-gas-price-blocks
Syntax
--api-gas-price-blocks=<INTEGER>
Number of blocks back from the head block to examine for eth_gasPrice. The default is 100.
api-gas-price-max
Syntax
--api-gas-price-max=<INTEGER>
Maximum gas price to return for eth_gasPrice, regardless of the percentile value measured. The default is 500000000000 (500 GWei).
api-gas-price-percentile
Syntax
--api-gas-price-percentile=<DOUBLE>
Percentile value to measure for eth_gasPrice. The default is 50.0.
For eth_gasPrice, to return the:
Highest gas price in --api-gas-price-blocks, set to 100.
Lowest gas price in --api-gas-price-blocks, set to 0.
​
bootnodes
Syntax
--bootnodes[=<enode://[email protected]:port>[,<enode://[email protected]:port>...]...]
A list of comma-separated enode URLs for P2P discovery bootstrap.
When connecting to Mainnet or public testnets, the default is a predefined list of enode URLs.
In private networks defined using --genesis-file or when using --network=dev, the default is an empty list of bootnodes.
color-enabled
Syntax
--color-enabled[=<true|false>]
ExampleEnvironment variableExample configuration file
Enables or disables color output to console. The default is true.
config-file
Syntax
--config-file=<FILE>
The path to the TOML configuration file. The default is none.
data-path
Syntax
--data-path=<PATH>
The path to the Besu data directory. The default is the directory you installed Besu in.
discovery-dns-url
Syntax
--discovery-dns-url=<enrtree URL>
The enrtree URL of the DNS node list for node discovery via DNS. The default is null.
discovery-enabled
Syntax
--discovery-enabled[=<true|false>]
Enables or disables P2P discovery. The default is true.
Note
You can override the default DNS server if it’s unreliable or doesn’t serve TCP DNS requests, using the experimental option --Xp2p-dns-discovery-server=<HOST>.
engine-host-allowlist
Syntax
--engine-host-allowlist=<hostname>[,<hostname>...]... or "*"
A comma-separated list of hostnames to allow for Engine API access (applies to both HTTP and WebSocket).
Tip
To allow all hostnames, use "*". We don’t recommend allowing all hostnames in production environments.
engine-rpc-port
Syntax
--engine-rpc-port=<PORT>
The listening port for the Engine API calls (ENGINE, ETH) for JSON-RPC over HTTP and WebSocket. The default is 8551.
ethstats
Syntax
--ethstats=<nodename:[email protected]:port>
Reporting URL of an Ethstats server.
ethstats-contact
Syntax
--ethstats-contact=<CONTACT>
Contact email address to send to the Ethstats server specified by --ethstats.
Note
A server must be specified by --ethstats in order to use this option.
fast-sync-min-peers
Syntax
--fast-sync-min-peers=<INTEGER>
The minimum number of peers required before starting fast synchronization. The default is 5.
Note
If synchronizing in FAST mode, most historical world state data is unavailable. Any methods attempting to access unavailable world state data return null.
genesis-file
Use the genesis file to create a custom network.
Tip
To use a public Ethereum network such as Rinkeby, use the --network option. The network option defines the genesis file for public networks.
Syntax
--genesis-file=<FILE>
The path to the genesis file.
Important
You cannot use the --genesis-file and --network options at the same time.
graphql-http-cors-origins
Syntax
--graphql-http-cors-origins=<graphQLHttpCorsAllowedOrigins>
A list of comma-separated origin domain URLs for CORS validation. The default is none.
graphql-http-enabled
Syntax
---graphql-http-enabled[=<true|false>]
Enables or disables the GraphQL HTTP service. The default is false.
The default GraphQL HTTP service endpoint is http://127.0.0.1:8547/graphql if set to true.
graphql-http-host
Syntax
--graphql-http-host=<HOST>
The host on which GraphQL HTTP listens. The default is 127.0.0.1.
To allow remote connections, set to 0.0.0.0.
graphql-http-port
Syntax
--graphql-http-port=<PORT>
The port (TCP) on which GraphQL HTTP listens. The default is 8547. Ports must be exposed appropriately.
help
Syntax
-h, --help
Show the help message and exit.
host-allowlist
Syntax
--host-allowlist=<hostname>[,<hostname>...]... or "*"
A comma-separated list of hostnames to access the JSON-RPC API and pull Besu metrics. By default, Besu accepts requests from localhost and 127.0.0.1.
Note
If using Prometheus to pull metrics from a node, you must specify all the other nodes you want to pull metrics from in the list of allowed hostnames.
logging
Syntax
-l, --logging=<LEVEL>
Sets logging verbosity. Log levels are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL. The default is INFO.
max-peers
Syntax
--max-peers=<INTEGER>
The maximum number of P2P connections you can establish. The default is 25.
metrics-category
Syntax
--metrics-category=<metrics-category>[,metrics-category...]...
A comma-separated list of categories for which to track metrics. The defaults are BLOCKCHAIN, ETHEREUM, EXECUTORS, JVM, NETWORK, PEERS, PERMISSIONING, PROCESS, PRUNER, RPC, STRATUM, SYNCHRONIZER, and TRANSACTION_POOL.
Other categories are KVSTORE_ROCKSDB, KVSTORE_PRIVATE_ROCKSDB, KVSTORE_ROCKSDB_STATS, and KVSTORE_PRIVATE_ROCKSDB_STATS.
Categories containing PRIVATE track metrics when you enable private transactions.
metrics-enabled
Syntax
---metrics-enabled[=<true|false>]
Enables or disables the metrics exporter. The default is false.
You can’t specify --metrics-enabled with --metrics-push-enabled. That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once.
metrics-host
Syntax
--metrics-host=<HOST>
The host on which Prometheus accesses Besu metrics. The metrics server respects the --host-allowlist option.
The default is 127.0.0.1.
metrics-port
Syntax
--metrics-port=<PORT>
The port (TCP) on which Prometheus accesses Besu metrics. The default is 9545. Ports must be exposed appropriately.
metrics-protocol
Syntax
--metrics-protocol=<metrics-protocol>
Metrics protocol to use: PROMETHEUS, OPENTELEMETRY, or NONE. The default is PROMETHEUS.
metrics-push-enabled
Syntax
--metrics-push-enabled[=<true|false>]
Enables or disables push gateway integration.
You can’t specify --metrics-push-enabled with --metrics-enabled. That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once.
metrics-push-host
Syntax
--metrics-push-host=<HOST>
The host of the Prometheus Push Gateway. The default is 127.0.0.1. The metrics server respects the --host-allowlist option.
Note
When pushing metrics, ensure you set --metrics-push-host to the machine on which the push gateway is. Generally, this is a different machine to the machine on which Besu is running.
metrics-push-interval
Syntax
--metrics-push-interval=<INTEGER>
The interval, in seconds, to push metrics when in push mode. The default is 15.
metrics-push-port
Syntax
--metrics-push-port=<PORT>
The port (TCP) of the Prometheus Push Gateway. The default is 9001. Ports must be exposed appropriately.
miner-coinbase
Syntax
--miner-coinbase=<Ethereum account address>
The account you pay mining rewards to. You must specify a valid coinbase when you enable mining using the --miner-enabled option or the miner_start JSON-RPC API method.
miner-enabled
Syntax
--miner-enabled[=<true|false>]
Enables or disables mining when you start the node. The default is false.
miner-extra-data
Syntax
--miner-extra-data=<Extra data>
A hex string representing the 32 bytes included in the extra data field of a mined block. The default is 0x.
miner-stratum-enabled
Syntax
--miner-stratum-enabled
Enables a node to perform stratum mining. The default is false.
miner-stratum-host
Syntax
--miner-stratum-host=<HOST>
The host of the stratum mining service. The default is 0.0.0.0.
miner-stratum-port
Syntax
--miner-stratum-port=<PORT>
The port of the stratum mining service. The default is 8008. You must expose ports appropriately.
min-gas-price
Syntax
--min-gas-price=<minTransactionGasPrice>
The minimum price a transaction offers to include it in a mined block. The minimum gas price is the lowest value eth_gasPrice can return. The default is 1000 Wei.
Important
In a free gas network, ensure the minimum gas price is set to zero for every node. Any node with a minimum gas price set higher than zero will silently drop transactions with a zero gas price. You can query a node’s gas configuration using eth_gasPrice.
nat-method
Syntax
--nat-method=UPNP
Specify the method for handling NAT environments. The options are:
UPNP
UPNPP2PONLY
KUBERNETES
DOCKER
AUTO
NONE.
The default is AUTO. NONE disables NAT functionality.
Tip
UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly enable UPnP support.
You must specify DOCKER when using the Besu Docker image.
network-id
Syntax
--network-id=<INTEGER>
The P2P network identifier.
Use this option to override the default network ID. The default value is the same as the chain ID defined in the genesis file.
node-private-key-file
Syntax
--node-private-key-file=<FILE>
The private key file for the node. The default is the key file in the data directory. If no key file exists, Besu creates a key file containing the generated private key, otherwise, the existing key file specifies the node private key.
Attention
The private key is not encrypted.
This option is ignored if --security-module is set to a non-default value.
p2p-enabled
Syntax
--p2p-enabled[=<true|false>]
Enables or disables all P2P communication. The default is true.
p2p-host
Syntax
--p2p-host=<HOST>
The advertised host that can be used to access the node from outside the network in P2P communication. The default is 127.0.0.1.
Info
If --nat-method is set to NONE, --p2p-host is not overridden and must be specified for the node to be accessed from outside the network.
p2p-interface
Syntax
--p2p-interface=<HOST>
The network interface on which the node listens for P2P communication. Use the option to specify the required network interface when the device that Besu is running on has multiple network interfaces. The default is 0.0.0.0 (all interfaces).
p2p-port
Syntax
--p2p-port=<PORT>
The P2P listening ports (UDP and TCP). The default is 30303. You must expose ports appropriately.
pruning-block-confirmations
Syntax
--pruning-block-confirmations=<INTEGER>
The minimum number of confirmations on a block before marking of newly-stored or in-use state trie nodes that cannot be pruned. The default is 10.
Important
Using pruning with private transactions is not supported.
pruning-blocks-retained
Syntax
--pruning-blocks-retained=<INTEGER>
The minimum number of recent blocks to keep the entire world state for. The default is 1024.
pruning-enabled
Syntax
--pruning-enabled
Enables pruning to reduce storage required for the world state. The default is false.
random-peer-priority-enabled
Syntax
--random-peer-priority-enabled[=<true|false>]
Enables or disables random prioritisation of incoming connections. Enable in small, stable networks to prevent closed groups of peers forming. The default is false.
remote-connections-limit-enabled
Syntax
--remote-connections-limit-enabled[=<true|false>]
Enables or disables using the --remote-connections-max-percentage option to limit the percentage of remote P2P connections initiated by peers. The default is true.
Important
To prevent eclipse attacks, ensure you enable the remote connections limit when connecting to any public network, and especially when using --sync-mode and --fast-sync-min-peers.
remote-connections-max-percentage
Syntax
--remote-connections-max-percentage=<DOUBLE>
The percentage of remote P2P connections you can establish with the node. Must be between 0 and 100, inclusive. The default is 60.
required-block
Syntax
--required-block, --required-blocks[=BLOCK=HASH[,BLOCK=HASH...]...]
Requires a peer with the specified block number to have the specified hash when connecting, or Besu rejects that peer.
revert-reason-enabled
Syntax
--revert-reason-enabled[=<true|false>]
Enables or disables including the revert reason in the transaction receipt, eth_estimateGas error response, eth_call error response, and trace response. The default is false.
Caution
Enabling revert reason may use a significant amount of memory. 
rpc-http-api
Syntax
--rpc-http-api=<api name>[,<api name>...]...
A comma-separated list of APIs to enable on the HTTP JSON-RPC channel. When you use this option you must also specify the --rpc-http-enabled option. The available API options are: ADMIN, CLIQUE, DEBUG, EEA, ETH, IBFT, MINER, NET, PERM, PLUGINS, PRIV, QBFT, TRACE, TXPOOL, and WEB3. The default is: ETH, NET, WEB3.
Tip
The singular --rpc-http-api and plural --rpc-http-apis are available and are two names for the same option.
rpc-http-authentication-credentials-file
Syntax
--rpc-http-authentication-credentials-file=<FILE>
The credentials file for JSON-RPC API authentication.
rpc-http-authentication-enabled
Syntax
--rpc-http-authentication-enabled[=<true|false>]
Enables or disables authentication for the HTTP JSON-RPC service.
rpc-http-cors-origins
Syntax
--rpc-http-cors-origins=<url>[,<url>...]... or all or "*"
A list of domain URLs for CORS validation.
Listed domains can access the node using JSON-RPC. If your client interacts with Besu using a browser app (such as Remix or a block explorer), add the client domain to the list.
The default value is "none". If you do not list any domains, browser apps cannot interact with your QI node.
rpc-http-enabled
Syntax
--rpc-http-enabled[=<true|false>]
Enables or disables the HTTP JSON-RPC service. The default is false.
rpc-http-host
Syntax
--rpc-http-host=<HOST>
The host on which HTTP JSON-RPC listens. The default is 127.0.0.1.
To allow remote connections, set to 0.0.0.0.
Caution
Setting the host to 0.0.0.0 exposes the RPC connection on your node to any remote connection. In a production environment, ensure you are using a firewall to avoid exposing your node to the internet.
rpc-http-max-active-connections
Syntax
--rpc-http-max-active-connections=<INTEGER>
The maximum number of allowed HTTP JSON-RPC connections. Once this limit is reached, incoming connections are rejected. The default is 80.
rpc-http-port
Syntax
--rpc-http-port=<PORT>
The port (TCP) on which HTTP JSON-RPC listens. The default is 8545. You must expose ports appropriately.
rpc-http-tls-ca-clients-enabled
Syntax
--rpc-http-tls-ca-clients-enabled[=<true|false>]
Enables or disables clients with trusted CA certificates to connect. The default is false.
Note
You must enable client authentication using the ---rpc-http-tls-client-auth-enabled option.
rpc-http-tls-enabled
Syntax
--rpc-http-tls-enabled[=<true|false>]
Enables or disables TLS for the JSON-RPC HTTP service. The default is false.
Note
--rpc-http-enabled must be enabled.
rpc-http-tls-keystore-file
Syntax
--rpc-http-tls-keystore-file=<FILE>
The Keystore file (in PKCS #12 format) that contains private key and the certificate presented to the client during authentication.
rpc-http-tls-keystore-password-file
Syntax
--rpc-http-tls-keystore-password-file=<FILE>
The path to the file containing the password to decrypt the keystore.
rpc-http-tls-protocol
Syntax
--rpc-http-tls-protocol=<protocolName>[, <protocolName>...]
A list of comma-separated TLS protocols to support. The default is DEFAULT_TLS_PROTOCOLS, a list which includes TLSv1.3 and TLSv1.2.
Tip
The singular --rpc-http-tls-protocol and plural --rpc-http-tls-protocols are available and are two names for the same option.
rpc-tx-feecap
Syntax
--rpc-tx-feecap=<MAX_FEE>
The maximum transaction fee (in Wei) accepted for transactions submitted through the eth_sendRawTransaction RPC. The default is 1000000000000000000 (1 ether).
If set to 0, then this option is ignored and no cap is applied.
rpc-ws-api
Syntax
--rpc-ws-api=<api name>[,<api name>...]...
A comma-separated list of APIs to enable on the WebSockets channel. When you use this option you must also specify the --rpc-ws-enabled option. The available API options are: ADMIN, CLIQUE, DEBUG, EEA, ETH, IBFT, MINER, NET, PERM, PLUGINS, PRIV, QBFT, TRACE, TXPOOL, and WEB3. The default is: ETH, NET, WEB3.
Tip
The singular --rpc-ws-api and plural --rpc-ws-apis options are available and are two names for the same option.
rpc-ws-enabled
Syntax
--rpc-ws-enabled[=<true|false>]
Enables or disables the WebSocket JSON-RPC service. The default is false.
rpc-ws-host
Syntax
--rpc-ws-host=<HOST>
The host on which WebSocket JSON-RPC listens. The default is 127.0.0.1.
To allow remote connections, set to 0.0.0.0
rpc-ws-max-active-connections
Syntax
--rpc-ws-max-active-connections=<INTEGER>
The maximum number of WebSocket connections allowed for JSON-RPC. Once this limit is reached, incoming connections are rejected. The default is 80.
rpc-ws-max-frame-size
Syntax
--rpc-ws-max-frame-size=<INTEGER>
The maximum size in bytes for JSON-RPC WebSocket frames. If this limit is exceeded, the WebSocket disconnects. The default is 1048576 (or 1 MB).
rpc-ws-port
Syntax
--rpc-ws-port=<PORT>
The port (TCP) on which WebSocket JSON-RPC listens. The default is 8546. You must expose ports appropriately.
strict-tx-replay-protection-enabled
Syntax
--strict-tx-replay-protection-enabled[=<true|false>]
Enables or disables replay protection, in accordance with EIP-155, on transactions submitted using JSON-RPC. The default is false.
sync-mode
Syntax
--sync-mode=X_SNAP
The synchronization mode. Use FAST for fast sync, FULL for full sync, X_SNAP for snap sync, and X_CHECKPOINT for checkpoint sync.
The default is FULL when connecting to a private network by not using the --network option and specifying the --genesis-file option.
The default is FAST when using the --network option with named networks.
version
Syntax
-V, --version
Prints version information and exit.
​
Reference: https://besu.hyperledger.org/en/stable/public-networks/reference/cli/options/​
Last modified 7mo ago