QI Blockchain CLI Parameters
This reference describes the syntax of the QI Blockchain Command Line Interface (CLI) 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 theBESU_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
Syntax
--api-gas-price-blocks=<INTEGER>
Number of blocks back from the head block to examine for
eth_gasPrice
. The default is 100
.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).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 to100
. - Lowest gas price in
--api-gas-price-blocks
, set to0
.
Syntax
--bootnodes[=<enode://id@host:port>[,<enode://id@host: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.Syntax
--color-enabled[=<true|false>]
ExampleEnvironment variableExample configuration file
Enables or disables color output to console. The default is
true
.Syntax
--config-file=<FILE>
The path to the TOML configuration file. The default is
none
.Syntax
--data-path=<PATH>
The path to the Besu data directory. The default is the directory you installed Besu in.
Syntax
--discovery-dns-url=<enrtree URL>
The
enrtree
URL of the DNS node list for node discovery via DNS. The default is null
.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>
.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.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
.Syntax
--ethstats=<nodename:secret@host:port>
Reporting URL of an Ethstats server.
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.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
.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.Syntax
--graphql-http-cors-origins=<graphQLHttpCorsAllowedOrigins>
A list of comma-separated origin domain URLs for CORS validation. The default is none.
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
.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
.Syntax
--graphql-http-port=<PORT>
The port (TCP) on which GraphQL HTTP listens. The default is
8547
. Ports must be exposed appropriately.Syntax
-h, --help
Show the help message and exit.
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.
Syntax
-l, --logging=<LEVEL>
Sets logging verbosity. Log levels are
OFF
, FATAL
, ERROR
, WARN
, INFO
, DEBUG
, TRACE
, ALL
. The default is INFO
.Syntax
--max-peers=<INTEGER>
The maximum number of P2P connections you can establish. The default is 25.
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.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.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
.Syntax
--metrics-port=<PORT>
The port (TCP) on which Prometheus accesses Besu metrics. The default is
9545
. Ports must be exposed appropriately.Syntax
--metrics-protocol=<metrics-protocol>
Metrics protocol to use:
PROMETHEUS
, OPENTELEMETRY
, or NONE
. The default is PROMETHEUS
.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.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.Syntax
--metrics-push-interval=<INTEGER>
The interval, in seconds, to push metrics when in
push
mode. The default is 15.Syntax
--metrics-push-port=<PORT>
The port (TCP) of the Prometheus Push Gateway. The default is
9001
. Ports must be exposed appropriately.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.Syntax
--miner-enabled[=<true|false>]
Enables or disables mining when you start the node. The default is
false
.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.
Syntax
--miner-stratum-enabled
Enables a node to perform stratum mining. The default is
false
.Syntax
--miner-stratum-host=<HOST>
The host of the stratum mining service. The default is
0.0.0.0
.Syntax
--miner-stratum-port=<PORT>
The port of the stratum mining service. The default is
8008
. You must expose ports appropriately.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
.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.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.
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.Syntax
--p2p-enabled[=<true|false>]
Enables or disables all P2P communication. The default is
true
.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.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).
Syntax
--p2p-port=<PORT>
The P2P listening ports (UDP and TCP). The default is
30303
. You must expose ports appropriately.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.
Syntax
--pruning-blocks-retained=<INTEGER>
The minimum number of recent blocks to keep the entire world state for. The default is 1024.
Syntax
--pruning-enabled
Enables pruning to reduce storage required for the world state. The default is
false
.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
.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
.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.
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.
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.
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.Syntax
--rpc-http-authentication-credentials-file=<FILE>
The credentials file for JSON-RPC API authentication.
Syntax
--rpc-http-authentication-enabled[=<true|false>]
Enables or disables authentication for the HTTP JSON-RPC service.
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.Syntax
--rpc-http-enabled[=<true|false>]
Enables or disables the HTTP JSON-RPC service. The default is
false
.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.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.
Syntax
--rpc-http-port=<PORT>
The port (TCP) on which HTTP JSON-RPC listens. The default is
8545
. You must expose ports appropriately.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.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.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.
Syntax
--rpc-http-tls-keystore-password-file=<FILE>
The path to the file containing the password to decrypt the keystore.
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.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.
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.Syntax
--rpc-ws-enabled[=<true|false>]
Enables or disables the WebSocket JSON-RPC service. The default is
false
.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
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.
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).
Syntax
--rpc-ws-port=<PORT>
The port (TCP) on which WebSocket JSON-RPC listens. The default is
8546
. You must expose ports appropriately.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
.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.
Syntax
-V, --version
Prints version information and exit.
Last modified 11mo ago