Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Updated on November 20, 2020

Hyperledger Besu command line

This reference describes the syntax of the Hyperledger Besu Command Line Interface (CLI) options and subcommands.

Specifying options

You can specify Besu options:

If you specify an option in more than one place, the order of priority is command line, environment variable, configuration file.

Besu environment variables

For each command line option, the equivalent environment variable is:

  • Upper-case
  • _ replaces -
  • Has a BESU_ prefix

For example, set --miner-coinbase using the BESU_MINER_COINBASE environment variable.

Options

To start a Besu node run:

besu [OPTIONS] [COMMAND]

auto-log-bloom-caching-enabled

--auto-log-bloom-caching-enabled=false

BESU_AUTO_LOG_BLOOM_CACHING_ENABLED=false

auto-log-bloom-caching-enabled=false

Enables or disables automatic log bloom caching. APIs such as eth_getLogs and eth_getFilterLogs use the cache for improved performance. The default is true.

If automatic log bloom caching is enabled and a log bloom query reaches the end of the cache, Besu performs an uncached query for logs not yet written to the cache.

Automatic log bloom caching has a small impact on performance. If you are not querying logs blooms for a large number of blocks, you might want to disable automatic log bloom caching.

banned-node-ids

--banned-node-ids=<bannedNodeId>[,<bannedNodeId>...]...

--banned-nodeids=0xc35c3...d615f,0xf42c13...fc456

BESU_BANNED_NODEIDS=0xc35c3...d615f,0xf42c13...fc456

banned-nodeids=["0xc35c3...d615f","0xf42c13...fc456"]

A 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.

Tip

The singular --banned-node-id and plural --banned-node-ids are available and are two names for the same option.

bootnodes

--bootnodes[=<enode://id@host:port>[,<enode://id@host:port>...]...]

--bootnodes=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303

BESU_BOOTNODES=enode://c35c3...d615f@1.2.3.4:30303,enode://f42c13...fc456@1.2.3.5:30303

bootnodes=["enode://c35c3...d615f@1.2.3.4:30303","enode://f42c13...fc456@1.2.3.5:30303"]

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.

config-file

--config-file=<FILE>

--config-file=/home/me/me_node/config.toml

BESU_CONFIG_FILE=/home/me/me_node/config.toml

The path to the TOML configuration file. The default is none.

data-path

--data-path=<PATH>

--data-path=/home/me/me_node

BESU_DATA_PATH=/home/me/me_node

data-path="/home/me/me_node"

The path to the Besu data directory. The default is the directory you installed Besu in, or /opt/besu/database if using the Besu Docker image.

discovery-enabled

--discovery-enabled=false

BESU_DISCOVERY_ENABLED=false

discovery-enabled=false

Enables or disables P2P discovery. The default is true.

fast-sync-min-peers

--fast-sync-min-peers=<INTEGER>

--fast-sync-min-peers=2

BESU_FAST_SYNC_MIN_PEERS=2

fast-sync-min-peers=2

The minimum number of peers required before starting fast sync. 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.

--genesis-file=<FILE>

--genesis-file=/home/me/me_node/customGenesisFile.json

BESU_GENESIS_FILE=/home/me/me_node/customGenesisFile.json

genesis-file="/home/me/me_node/customGenesisFile.json"

The path to the genesis file.

Important

You cannot use the --genesis-file and --network options at the same time.

graphql-http-cors-origins

--graphql-http-cors-origins=<graphQLHttpCorsAllowedOrigins>

--graphql-http-cors-origins="http://medomain.com","https://meotherdomain.com"

BESU_GRAPHQL_HTTP_CORS_ORIGINS="http://medomain.com","https://meotherdomain.com"

graphql-http-cors-origins=["http://medomain.com","https://meotherdomain.com"]

A list of comma-separated origin domain URLs for CORS validation. The default is none.

graphql-http-enabled

--graphql-http-enabled

BESU_GRAPHQL_HTTP_ENABLED=true

graphql-http-enabled=true

Enables 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

--graphql-http-host=<HOST>

# to listen on all interfaces
--graphql-http-host=0.0.0.0

# to listen on all interfaces
BESU_GRAPHQL_HTTP_HOST=0.0.0.0

graphql-http-host="0.0.0.0"

Host for GraphQL HTTP to listen on. The default is 127.0.0.1.

To allow remote connections, set to 0.0.0.0

graphql-http-port

--graphql-http-port=<PORT>

# to listen on port 6175
--graphql-http-port=6175

# to listen on port 6175
BESU_GRAPHQL_HTTP_PORT=6175

graphql-http-port="6175"

The GraphQL HTTP listening port (TCP). The default is 8547. Ports must be exposed appropriately.

help

-h, --help

Show the help message and exit.

host-allowlist

--host-allowlist=<hostname>[,<hostname>...]... or "*"

--host-allowlist=medomain.com,meotherdomain.com

BESU_HOST_ALLOWLIST=medomain.com,meotherdomain.com

host-allowlist=["medomain.com", "meotherdomain.com"]

A comma-separated list of hostnames to allow access to the JSON-RPC API. By default, Besu accepts access 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.

Tip

To allow all hostnames, use "*". We don’t recommend allowing all hostnames for production environments.

identity

--identity=<String>

--identity=MyNode

BESU_IDENTITY=MyNode

identity="MyNode"

The name for the node. If specified, it’s the second section of the client ID provided by some Ethereum network explorers. For example, in the client ID besu/MyNode/v1.3.4/linux-x86_64/oracle_openjdk-java-11, the node name is MyNode.

If a name is not specified, the name section is not included in the client ID. For example, besu/v1.3.4/linux-x86_64/oracle_openjdk-java-11.

key-value-storage

--key-value-storage=<keyValueStorageName>

--key-value-storage=rocksdb

BESU_KEY_VALUE_STORAGE=rocksdb

key-value-storage="rocksdb"

The key-value storage to use. Use this option only if using a storage system provided with a plugin. The default is rocksdb.

logging

-l, --logging=<LEVEL>

--logging=DEBUG

BESU_LOGGING=DEBUG

logging="DEBUG"

Sets logging verbosity. Log levels are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL. The default is INFO.

max-peers

--max-peers=<INTEGER>

--max-peers=42

BESU_MAX_PEERS=42

max-peers=42

The maximum number of P2P connections you can establish. The default is 25.

metrics-category

--metrics-category=<metrics-category>[,metrics-category...]...

--metrics-category=BLOCKCHAIN,PEERS,PROCESS

BESU_METRICS_CATEGORY=BLOCKCHAIN,PEERS,PROCESS

metrics-category=["BLOCKCHAIN","PEERS","PROCESS"]

A comma-separated list of categories for which to track metrics. The defaults are BLOCKCHAIN, ETHEREUM, EXECUTORS, JVM, NETWORK, PEERS, PERMISSIONING, PROCESS, PRUNER, RPC, 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

--metrics-enabled

BESU_METRICS_ENABLED=true

metrics-enabled=true

Enables the metrics exporter. The default is false.

You cannot 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

--metrics-host=<HOST>

--metrics-host=127.0.0.1

BESU_METRICS_HOST=127.0.0.1

metrics-host="127.0.0.1"

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

--metrics-port=<PORT>

--metrics-port=6174

BESU_METRICS_PORT=6174

metrics-port="6174"

The port (TCP) on which Prometheus accesses Besu metrics. The default is 9545. Ports must be exposed appropriately.

metrics-push-enabled

--metrics-push-enabled[=<true|false>]

--metrics-push-enabled

BESU_METRICS_PUSH_ENABLED=true

metrics-push-enabled=true

Enables or disables push gateway integration.

You cannot 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

--metrics-push-host=<HOST>

--metrics-push-host=127.0.0.1

BESU_METRICS_PUSH_HOST=127.0.0.1

metrics-push-host="127.0.0.1"

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

--metrics-push-interval=<INTEGER>

--metrics-push-interval=30

BESU_METRICS_PUSH_INTERVAL=30

metrics-push-interval=30

The interval, in seconds, to push metrics when in push mode. The default is 15.

metrics-push-port

--metrics-push-port=<PORT>

--metrics-push-port=6174

BESU_METRICS_PUSH_PORT=6174

metrics-push-port="6174"

The port (TCP) of the Prometheus Push Gateway. The default is 9001. Ports must be exposed appropriately.

metrics-push-prometheus-job

--metrics-prometheus-job=<metricsPrometheusJob>

--metrics-prometheus-job="my-custom-job"

BESU_METRICS_PROMETHEUS_JOB="my-custom-job"

metrics-prometheus-job="my-custom-job"

The job name when in push mode. The default is besu-client.

miner-coinbase

--miner-coinbase=<Ethereum account address>

--miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73

BESU_MINER_COINBASE=fe3b557e8fb62b89f4916b721be55ceb828dbd73

--miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"

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.

Note

Besu ignores this option in networks using Clique or IBFT 2.0 consensus protocols.

miner-enabled

--miner-enabled

BESU_MINER_ENABLED=true

miner-enabled=true

Enables mining when you start the node. The default is false.

miner-extra-data

--miner-extra-data=<Extra data>

--miner-extra-data=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021

BESU_MINER_EXTRA_DATA=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021

miner-extra-data="0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021"

A hex string representing the 32 bytes included in the extra data field of a mined block. The default is 0x.

miner-stratum-enabled

--miner-stratum-enabled

BESU_MINER_STRATUM_ENABLED=true

miner-stratum-enabled=true

Enables a node to perform stratum mining. The default is false.

miner-stratum-host

--miner-stratum-host=<HOST>

--miner-stratum-host=192.168.1.132

BESU_MINER_STRATUM_HOST=192.168.1.132

miner-stratum-host="192.168.1.132"

The host of the stratum mining service. The default is 0.0.0.0.

miner-stratum-port

--miner-stratum-port=<PORT>

--miner-stratum-port=8010

BESU_MINER_STRATUM_PORT=8010

miner-stratum-port="8010"

The port of the stratum mining service. The default is 8008. You must expose ports appropriately.

min-gas-price

--min-gas-price=<minTransactionGasPrice>

--min-gas-price=1337

BESU_MIN_GAS_PRICE=1337

min-gas-price=1337

The minimum price a transaction offers to include it in a mined block. To retrieve the minimum price in a running node, use eth_gasPrice. The default is 1000 Wei.

In a free gas network, set to zero.

nat-method

--nat-method=UPNP

nat-method="UPNP"

Specify the method for handling NAT environments. The options are:

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.

Notes

Specifying UPNP might introduce delays during node startup, especially on networks without a UPnP gateway device.

You must specify DOCKER when using the Besu Docker image.

network

--network=<NETWORK>

--network=rinkeby

BESU_NETWORK=rinkeby

network="rinkeby"

The predefined network configuration. The default is mainnet.

Possible values are:

Network Chain Type Default Sync Mode Description
mainnet ETH Production FAST The main network
ropsten ETH Test FAST A PoW network similar to the current main Ethereum network
rinkeby ETH Test FAST A PoA network using Clique
goerli ETH Test FAST A PoA network using Clique
dev ETH Development FULL A PoW network with a low difficulty to enable local CPU mining
classic ETC Production FAST The main Ethereum Classic network
mordor ETC Test FAST A PoW network
kotti ETC Test FAST A PoA network using Clique

Tip

Values are case insensitive, so either mainnet or MAINNET works.

Important

You cannot use the --network and --genesis-file options at the same time.

network-id

--network-id=<INTEGER>

--network-id=8675309

BESU_NETWORK_ID=8675309

network-id="8675309"

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

--node-private-key-file=<FILE>

--node-private-key-file=/home/me/me_node/myPrivateKey

BESU_NODE_PRIVATE_KEY_FILE=/home/me/me_node/myPrivateKey

node-private-key-file="/home/me/me_node/myPrivateKey"

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

--p2p-enabled=<true|false>

--p2p-enabled=false

BESU_P2P_ENABLED=false

p2p-enabled=false

Enables or disables all P2P communication. The default is true.

p2p-host

--p2p-host=<HOST>

# to listen on all interfaces
--p2p-host=0.0.0.0

# to listen on all interfaces
BESU_P2P_HOST=0.0.0.0

p2p-host="0.0.0.0"

The host on which P2P listens. The default is 127.0.0.1.

p2p-interface

--p2p-interface=<HOST>

--p2p-interface=192.168.1.132

BESU_P2P_INTERFACE=192.168.1.132

p2p-interface="192.168.1.132"

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

--p2p-port=<PORT>

# to listen on port 1789
--p2p-port=1789

# to listen on port 1789
BESU_P2P_PORT=1789

p2p-port="1789"

The P2P listening ports (UDP and TCP). The default is 30303. You must expose ports appropriately.

permissions-accounts-config-file

--permissions-accounts-config-file=<FILE>

--permissions-accounts-config-file=/home/me/me_configFiles/myPermissionsFile

BESU_PERMISSIONS_ACCOUNTS_CONFIG_FILE=/home/me/me_configFiles/myPermissionsFile

permissions-accounts-config-file="/home/me/me_configFiles/myPermissionsFile"

The accounts permissions configuration file. The default is the permissions_config.toml file in the data directory.

Tip

--permissions-accounts-config-file and --permissions-nodes-config-file can use the same file.

permissions-accounts-config-file-enabled

--permissions-accounts-config-file-enabled[=<true|false>]

--permissions-accounts-config-file-enabled

BESU_PERMISSIONS_ACCOUNTS_CONFIG_FILE_ENABLED=true

permissions-accounts-config-file-enabled=true

Enables or disables file-based account level permissions. The default is false.

permissions-accounts-contract-address

--permissions-accounts-contract-address=<ContractAddress>

--permissions-accounts-contract-address=xyz

BESU_PERMISSIONS_ACCOUNTS_CONTRACT_ADDRESS=xyz

permissions-accounts-contract-address=xyz

The contract address for onchain account permissioning.

permissions-accounts-contract-enabled

--permissions-accounts-contract-enabled[=<true|false>]

--permissions-accounts-contract-enabled

BESU_PERMISSIONS_ACCOUNTS_CONTRACT_ENABLED=true

permissions-accounts-contract-enabled=true

Enables or disables contract-based onchain account permissioning. The default is false.

permissions-nodes-config-file

--permissions-nodes-config-file=<FILE>

--permissions-nodes-config-file=/home/me/me_configFiles/myPermissionsFile

BESU_PERMISSIONS_NODES_CONFIG_FILE=/home/me/me_configFiles/myPermissionsFile

permissions-nodes-config-file="/home/me/me_configFiles/myPermissionsFile"

The nodes permissions configuration file. The default is the permissions_config.toml file in the data directory.

Tip

--permissions-nodes-config-file and --permissions-accounts-config-file can use the same file.

permissions-nodes-config-file-enabled

--permissions-nodes-config-file-enabled[=<true|false>]

--permissions-nodes-config-file-enabled

BESU_PERMISSIONS_NODES_CONFIG_FILE_ENABLED=true

permissions-nodes-config-file-enabled=true

Enables or disables file-based node level permissions. The default is false.

permissions-nodes-contract-address

--permissions-nodes-contract-address=<ContractAddress>

--permissions-nodes-contract-address=xyz

BESU_PERMISSIONS_NODES_CONTRACT_ADDRESS=xyz

permissions-nodes-contract-address=xyz

The contract address for onchain node permissioning.

permissions-nodes-contract-enabled

--permissions-nodes-contract-enabled[=<true|false>]

--permissions-nodes-contract-enabled

BESU_PERMISSIONS_NODES_CONTRACT_ENABLED=true

permissions-nodes-contract-enabled=true

Enables or disables contract-based onchain node permissioning. The default is false.

permissions-nodes-contract-version

--permissions-nodes-contract-version=<ContractVersion>

--permissions-nodes-contract-version=2

BESU_PERMISSIONS_NODES_CONTRACT_VERSION=2

permissions-nodes-contract-version=2

Version of the EEA node permissioning interface. The default is 1.

privacy-enabled

--privacy-enabled[=<true|false>]

--privacy-enabled=false

BESU_PRIVACY_ENABLED=false

privacy-enabled=false

Enables or disables private transactions. The default is false.

Important

Using private transactions with pruning and/or Fast Sync is not supported.

privacy-marker-transaction-signing-key-file

--privacy-marker-transaction-signing-key-file=<FILE>

--privacy-marker-transaction-signing-key-file=/home/me/me_node/myPrivateKey

PANTHEON_PRIVACY_MARKER_TRANSACTION_SIGNING_KEY_FILE=/home/me/me_node/myPrivateKey

privacy-marker-transaction-signing-key-file="/home/me/me_node/myPrivateKey"

<FILE> is the name of the private key file used to sign Privacy Marker Transactions. If you do not specify this option, Besu signs each transaction with a different randomly generated key.

If using account permissioning and privacy, you must specify a private key file and the signing key included in the accounts allowlist.

privacy-multi-tenancy-enabled

--privacy-multi-tenancy-enabled[=<true|false>]

--privacy-multi-tenancy-enabled=false

BESU_PRIVACY_MULTI_TENANCY_ENABLED=false

privacy-multi-tenancy-enabled=false

Enables or disables multi-tenancy for private transactions. The default is false.

privacy-onchain-groups-enabled

--privacy-onchain-groups-enabled[=<true|false>]

--privacy-onchain-groups-enabled=true

BESU_PRIVACY_ONCHAIN_GROUPS_ENABLED=true

privacy-onchain-groups-enabled=true

Set to enable flexible privacy groups. Default is false.

privacy-public-key-file

--privacy-public-key-file=<privacyPublicKeyFile>

--privacy-public-key-file=Orion/nodeKey.pub

BESU_PRIVACY_PUBLIC_KEY_FILE=Orion/nodeKey.pub

privacy-public-key-file="Orion/nodeKey.pub"

The public key of the Orion node.

Important

You cannot specify privacy-public-key-file when --privacy-multi-tenancy-enabled is true

privacy-tls-enabled

--privacy-tls-enabled[=<true|false>]

--privacy-tls-enabled=false

BESU_PRIVACY_TLS_ENABLED=false

privacy-tls-enabled=false

Enables or disables TLS on communication with the Private Transaction Manager. The default is false.

privacy-tls-keystore-file

--privacy-tls-keystore-file=<FILE>

--privacy--keystore-file=/home/me/me_node/key

BESU_PRIVACY_TLS_KEYSTORE_FILE=/home/me/me_node/key

privacy-tls-keystore-file="/home/me/me_node/key"

The keystore file (in PKCS #12 format) containing the private key and the certificate presented during authentication.

You must specify privacy-tls-keystore-file if --privacy-tls-enabled is true.

privacy-tls-keystore-password-file

--privacy-tls-keystore-password-file=<FILE>

--privacy-tls-keystore-password-file=/home/me/me_node/password

BESU_PRIVACY_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password

privacy-tls-keystore-password-file="/home/me/me_node/password"

The path to the file containing the password to decrypt the keystore.

privacy-tls-known-enclave-file

--privacy-tls-known-enclave-file=<FILE>

--privacy-tls-known-enclave-file=/home/me/me_node/knownEnclave

BESU_PRIVACY_TLS_KNOWN_ENCLAVE_FILE=/home/me/me_node/knownEnclave

privacy-tls-known-enclave-file="/home/me/me_node/knownEnclave"

The path to the file containing the hostnames, ports, and SHA256 certificate fingerprints of the authorized privacy enclave.

privacy-url

--privacy-url=<privacyUrl>

--privacy-url=http://127.0.0.1:8888

BESU_PRIVACY_URL=http://127.0.0.1:8888

privacy-url="http://127.0.0.1:8888"

The URL on which the Orion node is running.

pruning-block-confirmations

--pruning-block-confirmations=<INTEGER>

--pruning-block-confirmations=5

BESU_PRUNING_BLOCK_CONFIRMATIONS=5

pruning-block-confirmations=5

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

--pruning-blocks-retained=<INTEGER>

--pruning-blocks-retained=10000

BESU_PRUNING_BLOCKS_RETAINED=10000

pruning-blocks-retained=10000

The minimum number of recent blocks to keep the entire world state for. The default is 1024.

Important

Using pruning with private transactions is not supported.

pruning-enabled

--pruning-enabled

--pruning-enabled=true

BESU_PRUNING_ENABLED=true

pruning-enabled=true

Enables pruning to reduce storage required for the world state.

Important

Using pruning with private transactions is not supported.

remote-connections-limit-enabled

--remote-connections-limit-enabled[=<true|false>]

--remote-connections-limit-enabled=false

BESU_REMOTE_CONNECTIONS_LIMIT_ENABLED=false

remote-connections-limit-enabled=false

Enables or disables limiting the percentage of remote P2P connections initiated by peers. The default is true.

Tip

In private networks with a level of trust between peers, disabling the remote connection limits may increase the speed at which nodes can join the network.

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

--remote-connections-max-percentage=<DOUBLE>

--remote-connections-max-percentage=25

BESU_REMOTE_CONNECTIONS_MAX_PERCENTAGE=25

remote-connections-max-percentage=25

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

--required-block, --required-blocks[=BLOCK=HASH[,BLOCK=HASH...]...]

--required-block=6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80

BESU_REQUIRED_BLOCK=6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80

required-block="6485846=0x43f0cd1e5b1f9c4d5cda26c240b59ee4f1b510d0a185aa8fd476d091b0097a80"

Requires a peer with the specified block number to have the specified hash when connecting, or Besu rejects that peer.

revert-reason-enabled

--revert-reason-enabled[=<true|false>]

--revert-reason-enabled=true

BESU_REVERT_REASON_ENABLED=true

revert-reason-enabled=true

Enables including the revert reason in the transaction receipt. The default is false.

Caution

Enabling revert reason may use a significant amount of memory. We do not recommend enabling revert reason when connected to public Ethereum networks.

rpc-http-api

--rpc-http-api=<api name>[,<api name>...]...

--rpc-http-api=ETH,NET,WEB3

BESU_RPC_HTTP_API=ETH,NET,WEB3

rpc-http-api=["ETH","NET","WEB3"]

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, 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

--rpc-http-authentication-credentials-file=<FILE>

--rpc-http-authentication-credentials-file=/home/me/me_node/auth.toml

BESU_RPC_HTTP_AUTHENTICATION_CREDENTIALS_FILE=/home/me/me_node/auth.toml

rpc-http-authentication-credentials-file="/home/me/me_node/auth.toml"

The credentials file for JSON-RPC API authentication.

rpc-http-authentication-enabled

--rpc-http-authentication-enabled

--rpc-http-authentication-enabled

BESU_RPC_HTTP_AUTHENTICATION_ENABLED=true

rpc-http-authentication-enabled=true

Enables authentication for the HTTP JSON-RPC service.

rpc-http-authentication-jwt-public-key-file

--rpc-http-authentication-jwt-public-key-file=<FILE>

--rpc-http-authentication-jwt-public-key-file=publicKey.pem

BESU_RPC_HTTP_AUTHENTICATION-JWT-PUBLIC-KEY-FILE="publicKey.pem"

rpc-http-authentication-jwt-public-key-file="publicKey.pem"

The JWT provider’s public key file used for JSON-RPC HTTP authentication with an external JWT.

rpc-http-cors-origins

--rpc-http-cors-origins=<url>[,<url>...]... or all or "*"

$# You can allow one or more domains with a comma-separated list.

--rpc-http-cors-origins="http://medomain.com","https://meotherdomain.com"

BESU_RPC_HTTP_CORS_ORIGINS="http://medomain.com","https://meotherdomain.com"

rpc-http-cors-origins=["http://medomain.com","https://meotherdomain.com"]

$# The following allows Remix to interact with your Besu node.

--rpc-http-cors-origins="http://remix.ethereum.org"

A list of domain URLs for CORS validation. You must enclose the URLs in double quotes and separate them with commas.

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 Besu node.

Note

To run a local Besu node as a backend for MetaMask and use MetaMask anywhere, set --rpc-http-cors-origins to "all" or "*". To allow a specific domain to use MetaMask with the Besu node, set --rpc-http-cors-origins to the client domain.

Tip

For testing and development purposes, use "all" or "*" to accept requests from any domain. We don’t recommend accepting requests from any domain for production environments.

rpc-http-enabled

--rpc-http-enabled

BESU_RPC_HTTP_ENABLED=true

rpc-http-enabled=true

Enables the HTTP JSON-RPC service. The default is false.

rpc-http-host

--rpc-http-host=<HOST>

# to listen on all interfaces
--rpc-http-host=0.0.0.0

BESU_RPC_HTTP_HOST=0.0.0.0

rpc-http-host="0.0.0.0"

Specifies 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-port

--rpc-http-port=<PORT>

# to listen on port 3435
--rpc-http-port=3435

BESU_RPC_HTTP_PORT=3435

rpc-http-port="3435"

The HTTP JSON-RPC listening port (TCP). The default is 8545. You must expose ports appropriately.

rpc-http-tls-ca-clients-enabled

--rpc-http-tls-ca-clients-enabled[=<true|false>]

BESU_RPC_HTTP_TLS_CA_CLIENTS_ENABLED=true

rpc-http-tls-ca-clients-enabled=true

Enables 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-client-auth-enabled

--rpc-http-tls-client-auth-enabled

BESU_RPC_HTTP_TLS_CLIENT_AUTH_ENABLED=true

rpc-http-tls-client-auth-enabled=true

Enables TLS client authentication for the JSON-RPC HTTP service. The default is false.

Note

You must specify --rpc-http-tls-ca-clients-enabled and/or rpc-http-tls-known-clients-file.

rpc-http-tls-enabled

--rpc-http-tls-enabled

BESU_RPC_HTTP_TLS_ENABLED=true

rpc-http-tls-enabled=true

Enables TLS for the JSON-RPC HTTP service. The default is false.

Note

--rpc-http-enabled must be enabled.

rpc-http-tls-keystore-file

--rpc-http-tls-keystore-file=<FILE>

--rpc-http-tls-keystore-file=/home/me/me_node/keystore.pfx

BESU_RPC_HTTP_TLS_KEYSTORE_FILE=/home/me/me_node/keystore.pfx

rpc-http-tls-keystore-file="/home/me/me_node/keystore.pfx"

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

--rpc-http-tls-keystore-password-file=<FILE>

--rpc-http-tls-keystore-password-file=/home/me/me_node/password

BESU_RPC_HTTP_TLS_KEYSTORE_PASSWORD_FILE=/home/me/me_node/password

rpc-http-tls-keystore-password-file="/home/me/me_node/password"

The path to the file containing the password to decrypt the keystore.

rpc-http-tls-known-clients-file

--rpc-http-tls-known-clients-file=<FILE>

--rpc-http-tls-known-clients-file=/home/me/me_node/knownClients

BESU_RPC_HTTP_TLS_KNOWN_CLIENTS_FILE=/home/me/me_node/knownClients

rpc-http-tls-known-clients-file="/home/me/me_node/knownClients"

The path to the file used to authenticate clients using self-signed certificates or non-public certificates.

Must contain the certificates’s Common Name, and SHA-256 fingerprint in the format <CommonName> <hex-string>.

Note

You must enable client authentication using the ---rpc-http-tls-client-auth-enabled option.

rpc-tx-feecap

--rpc-tx-feecap=<MAX_FEE>

--rpc-tx-feecap=1200000000000000000

BESU_RPC_TX_FEE=1200000000000000000

rpc-tx-feecap=1200000000000000000

Sets the maximum transaction fee (in Wei) accepted for transactions submitted through the eth_sendRawTransaction RPC. Defaults to 1000000000000000000 (1 ether).

If set to 0, then this option is ignored and no cap is applied.

rpc-ws-api

--rpc-ws-api=<api name>[,<api name>...]...

--rpc-ws-api=ETH,NET,WEB3

BESU_RPC_WS_API=ETH,NET,WEB3

rpc-ws-api=["ETH","NET","WEB3"]

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, 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-authentication-credentials-file

--rpc-ws-authentication-credentials-file=<FILE>

--rpc-ws-authentication-credentials-file=/home/me/me_node/auth.toml

BESU_RPC_WS_AUTHENTICATION_CREDENTIALS_FILE=/home/me/me_node/auth.toml

rpc-ws-authentication-credentials-file="/home/me/me_node/auth.toml"

The path to the credentials file for JSON-RPC API authentication.

rpc-ws-authentication-enabled

--rpc-ws-authentication-enabled

--rpc-ws-authentication-enabled

BESU_RPC_WS_AUTHENTICATION_ENABLED=true

rpc-ws-authentication-enabled=true

Enables authentication for the WebSockets JSON-RPC service.

Note

wscat does not support headers. Authentication requires you to pass an authentication token in the request header. To use authentication with WebSockets, you need an app that supports headers.

rpc-ws-authentication-jwt-public-key-file

--rpc-http-authentication-jwt-public-key-file=<FILE>

--rpc-http-authentication-jwt-public-key-file=publicKey.pem

BESU_RPC_HTTP_AUTHENTICATION-JWT-PUBLIC-KEY-FILE="publicKey.pem"

rpc-http-authentication-jwt-public-key-file="publicKey.pem"

The JWT provider’s public key file used for JSON-RPC websocket authentication with an external JWT.

rpc-ws-enabled

--rpc-ws-enabled

BESU_RPC_WS_ENABLED=true

rpc-ws-enabled=true

Enables the WebSockets JSON-RPC service. The default is false.

rpc-ws-host

--rpc-ws-host=<HOST>

# to listen on all interfaces
--rpc-ws-host=0.0.0.0

BESU_RPC_WS_HOST=0.0.0.0

rpc-ws-host="0.0.0.0"

The host for Websocket WS-RPC to listen on. The default is 127.0.0.1.

To allow remote connections, set to 0.0.0.0

rpc-ws-port

--rpc-ws-port=<PORT>

# to listen on port 6174
--rpc-ws-port=6174

BESU_RPC_WS_PORT=6174

rpc-ws-port="6174"

The Websockets JSON-RPC listening port (TCP). The default is 8546. You must expose ports appropriately.

security-module

--security-module=<NAME>

--security-module=security_module

BESU_SECURITY_MODULE=security_module

security-module="security_module"

Name of the security module plugin to use. For example, a Hardware Security Module (HSM) or V3 filestore plugin

Defaults to using the nodes’s local private key file specified using --node-private-key-file.

sync-mode

--sync-mode=FAST

--sync-mode=FAST

BESU_SYNC_MODE=FAST

sync-mode="FAST"

The synchronization mode. The options are FAST and FULL.

  • 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, except for the dev development network. FAST is also the default if Ethereum mainnet is being connected to by not specifying the --network and --genesis-file options.

Note

When running Besu on some cloud providers, a known RocksDB issue causes fast sync to fail occasionally. The following error is displayed repeatedly:

...
EthScheduler-Services-1 (importBlock) | ERROR | PipelineChainDownloader | Chain download failed. Restarting after short delay.
java.util.concurrent.CompletionException: org.hyperledger.besu.plugin.services.exception.StorageException: org.rocksdb.RocksDBException: block checksum mismatch:
....

The failure has been seen on AWS and Digital Ocean. A full restart of the AWS VM is required to restart the fast sync. Fast sync is not currently supported on Digital Ocean.

Important

Using fast sync with private transactions or on Digital Ocean Droplets is not supported.

target-gas-limit

--target-gas-limit=<INTEGER>

--target-gas-limit=8000000

BESU_TARGET_GAS_LIMIT=8000000

target-gas-limit="8000000"

The gas limit toward which Besu will gradually move on an existing network, if enough miners are in agreement. To change the block gas limit set in the genesis file without creating a new network, use target-gas-limit. The gas limit between blocks can change only 1/1024th, so the target tells the block creator how to set the gas limit in its block. If the values are the same or within 1/1024th, Besu sets the limit to the specified value. Otherwise, the limit moves as far as it can within that constraint.

If a value for target-gas-limit is not specified, the block gas limit remains at the value specified in the genesis file.

tx-pool-max-size

--tx-pool-max-size=<INTEGER>

--tx-pool-max-size=2000

BESU_TX_POOL_MAX_SIZE=2000

tx-pool-max-size="2000"

The maximum number of transactions kept in the transaction pool. The default is 4096.

tx-pool-hashes-max-size

--tx-pool-hashes-max-size=<INTEGER>

--tx-pool-hashes-max-size=2000

BESU_TX_POOL_HASHES_MAX_SIZE=2000

tx-pool-hashes-max-size="2000"

The maximum number of transaction hashes kept in the transaction pool. The default is 4096.

tx-pool-price-bump

--tx-pool-price-bump=<INTEGER>

--tx-pool-price-bump=25

BESU_TX_POOL_PRICE_BUMP=25

tx-pool-price-bump=25

The price bump percentage to replace an existing transaction. The default is 10.

tx-pool-retention-hours

--tx-pool-retention-hours=<INTEGER>

--tx-pool-retention-hours=5

BESU_TX_POOL_RETENTION_HOURS=5

tx-pool-retention-hours=5

The maximum period, in hours, to hold pending transactions in the transaction pool. The default is 13.

Xdns-enabled

--Xdns-enabled=[<true|false>]

--Xdns-enabled=true

BESU_XDNS_ENABLED=true

Xdns-enabled=true

Enables DNS support. The default is false.

Important

Use domain names in private networks only because public networks require using IP addresses. This is an early access feature. Some functionality may be updated before the feature is fully released.

Use DNS with a trusted DNS provider in private networks because of limitations where IP addresses can change. For example, when using Kubernetes pods.

Xdns-update-enabled

--Xdns-update-enabled=[<true|false>]

--Xdns-update-enabled=true

BESU_XDNS_UPDATE_ENABLED=true

Xdns-update-enabled=true

Allow Besu to continuously query the DNS to ensure updates to IP addresses are automatically detected. The default is false.

Xdns-enabled must be set to true.

Important

This is an early access feature. Some functionality may be updated before the feature is fully released.

version

-V, --version

Print version information and exit.

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list besu@lists.hyperledger.org