Fieres 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://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.

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:secret@host: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.