Command line options

This reference describes the syntax of the Hyperledger Besu command line interface (CLI) options.

Specify options

You can specify Besu 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.

• In a configuration file.

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

--api-gas-price-blocks=<INTEGER>

--api-gas-price-blocks=50

BESU_API_GAS_PRICE_BLOCKS=50

api-gas-price-blocks=50

Number of blocks back from the head block to examine for eth_gasPrice. The default is 100.

api-gas-price-max

--api-gas-price-max=<INTEGER>

--api-gas-price-max=20000

BESU_API_GAS_PRICE_MAX=20000

api-gas-price-max=20000

Maximum gas price to return for eth_gasPrice, regardless of the percentile value measured. The default is 500000000000 (500 GWei).

api-gas-price-percentile

--api-gas-price-percentile=<DOUBLE>

--api-gas-price-percentile=75

BESU_API_GAS_PRICE_PERCENTILE=75

api-gas-price-percentile=75

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.

auto-log-bloom-caching-enabled

--auto-log-bloom-caching-enabled[=<true|false>]

--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-node-ids=0xc35c3...d615f,0xf42c13...fc456

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

banned-node-ids=["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.

bonsai-maximum-back-layers-to-load

--bonsai-maximum-back-layers-to-load=256

--bonsai-maximum-back-layers-to-load=256

BESU_BONSAI_MAXIMUM_BACK_LAYERS_TO_LOAD=256

bonsai-maximum-back-layers-to-load=256

When using Bonsai Tries, the maximum number of layers back Bonsai can go to reconstruct a historical state. The default is 512.

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.

color-enabled

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

--color-enabled=false

BESU_COLOR_ENABLED=false

color-enabled=false

Enables or disables color output to console. The default is true.

compatibility-eth64-forkid-enabled

--compatibility-eth64-forkid-enabled[=<true|false>]

--compatibility-eth64-forkid-enabled=true

BESU_COMPATIBILITY_ETH64_FORKID_ENABLED=true

compatibility-eth64-forkid-enabled=true

Enables or disables the legacy Eth/64 fork ID. For any networks with nodes using Besu v1.4 or earlier and nodes using Besu v20.10.1 or later, either:

• All nodes must be upgraded to v20.10.1 or later.
• All nodes using v20.10.1 or later must have --compatibility-eth64-forkid-enabled set to true.

The default is false.

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.

data-storage-format

--data-storage-format=<FORMAT>

--data-storage-format=BONSAI

BESU_DATA_STORAGE_FORMAT=BONSAI

data-storage-format="BONSAI"

The data storage format to use. Set to BONSAI for Bonsai Tries or FOREST for Forest of Tries. The default is FOREST.

discovery-dns-url

--discovery-dns-url=<enrtree URL>

BESU_DISCOVERY_DNS_URL=enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org

discovery-dns-url="enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org"

The enrtree URL of the DNS node list for node discovery via DNS. The default is null.

discovery-enabled

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

--discovery-enabled=false

BESU_DISCOVERY_ENABLED=false

discovery-enabled=false

Enables or disables P2P discovery. The default is true.

engine-host-allowlist

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

--engine-host-allowlist=localhost,127.0.0.1

BESU_ENGINE_HOST_ALLOWLIST=localhost,127.0.0.1

engine-host-allowlist=["localhost","127.0.0.1"]

A comma-separated list of hostnames to allow for Engine API access (applies to both HTTP and WebSocket).

engine-jwt-disabled

--engine-jwt-disabled[=<true|false>]

--engine-jwt-disabled=true

BESU_ENGINE_JWT_DISABLED=true

engine-jwt-disabled=true

Disables or enables authentication for Engine APIs. The default is false (authentication is enabled by default).

engine-jwt-secret

--engine-jwt-secret=<FILE>

--engine-jwt-secret=jwt.hex

BESU_ENGINE_JWT_SECRET="jwt.hex"

engine-jwt-secret="jwt.hex"

Shared secret used to authenticate consensus clients when using the Engine JSON-RPC API (both HTTP and WebSocket). Contents of file must be at least 32 hex-encoded bytes and not begin with 0x. May be a relative or absolute path. See an example of how to generate this.

engine-rpc-enabled

--engine-rpc-enabled[=<true|false]>

--engine-rpc-enabled

BESU_ENGINE_RPC_ENABLED=true

engine-rpc-enabled=true

Enables or disables the Engine API. The default is false.

engine-rpc-port

--engine-rpc-port=<PORT>

--engine-rpc-port=8551

BESU_ENGINE_RPC_PORT=8551

engine-rpc-port="8551"

The listening port for the Engine API calls (ENGINE, ETH) for JSON-RPC over HTTP and WebSocket. The default is 8551.

ethstats

--ethstats=<nodename:secret@host:port>

--ethstats=Dev-Node-1:secret@127.0.0.1:3001

BESU_ETHSTATS=Dev-Node-1:secret@127.0.0.1:3001

ethstats="Dev-Node-1:secret@127.0.0.1:3001"

Reporting URL of an Ethstats server.

ethstats-contact

--ethstats-contact=<CONTACT>

--ethstats-contact=contact@mail.com

BESU_ETHSTATS_CONTACT=contact@mail.com

ethstats-contact="contact@mail.com"

Contact email address to send to the Ethstats server specified by --ethstats.

fast-sync-min-peers

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

--fast-sync-min-peers=8

BESU_FAST_SYNC_MIN_PEERS=8

fast-sync-min-peers=8

The minimum number of peers required before starting fast synchronization in proof of work networks. The default is 5.

genesis-file

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

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[=<true|false>]

--graphql-http-enabled

BESU_GRAPHQL_HTTP_ENABLED=true

graphql-http-enabled=true

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

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

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

--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 port (TCP) on which GraphQL HTTP listens. 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 access the JSON-RPC API and pull Besu metrics. By default, Besu accepts requests from localhost and 127.0.0.1.

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.

For development use only, the memory option provides ephemeral storage for sync testing and debugging.

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

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

--metrics-enabled

BESU_METRICS_ENABLED=true

metrics-enabled=true

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

--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-protocol

--metrics-protocol=<metrics-protocol>

--metrics-protocol=OPENTELEMETRY

BESU_METRICS_PROTOCOL=OPENTELEMETRY

metrics-protocol="OPENTELEMETRY"

Metrics protocol to use: PROMETHEUS, OPENTELEMETRY, or NONE. The default is PROMETHEUS.

metrics-push-enabled

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

--metrics-push-enabled=true

BESU_METRICS_PUSH_ENABLED=true

metrics-push-enabled=true

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

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

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-push-prometheus-job=<metricsPrometheusJob>

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

BESU_METRICS_PUSH_PROMETHEUS_JOB="my-custom-job"

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

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

min-block-occupancy-ratio

--min-block-occupancy-ratio=<minBlockOccupancyRatio>

--min-block-occupancy-ratio=0.5

BESU_MIN_BLOCK_OCCUPANCY_RATIO=0.5

min-block-occupancy-ratio="0.5"

Minimum occupancy ratio for a mined block if the transaction pool is not empty. When filling a block during mining, the occupancy ratio indicates the threshold at which the node stops waiting for smaller transactions to fill the remaining space. The default is 0.8.

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.

miner-enabled

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

--miner-enabled=true

BESU_MINER_ENABLED=true

miner-enabled=true

Enables or disables 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. The minimum gas price is the lowest value eth_gasPrice can return. The default is 1000 Wei.

nat-method

--nat-method=UPNP

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.

network

--network=<NETWORK>

--network=goerli

BESU_NETWORK=goerli

network="goerli"

The predefined network configuration. The default is mainnet.

Possible values are:

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.

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 advertised host that can be used to access the node from outside the network in P2P communication. 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.

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.

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.

pruning-enabled

--pruning-enabled

--pruning-enabled=true

BESU_PRUNING_ENABLED=true

pruning-enabled=true

Enables pruning to reduce storage required for the world state. The default is false.

random-peer-priority-enabled

--random-peer-priority-enabled[=<true|false>]

--random-peer-priority-enabled=true

BESU_RANDOM_PEER_PRIORITY_ENABLED=true

random-peer-priority-enabled=true

Enables or disables random prioritization of incoming connections. Enable in small, stable networks to prevent closed groups of peers forming. The default is false.

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 using the --remote-connections-max-percentage option to limit the percentage of remote P2P connections initiated by peers. The default is true.

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.

reorg-logging-threshold

--reorg-logging-threshold=<INTEGER>

--reorg-logging-threshold=3

BESU_REORG_LOGGING_THRESHOLD=3

reorg-logging-threshold=3

Minimum depth of chain reorganizations to log. The default is 6.

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

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, QBFT, TRACE, TXPOOL, and WEB3. The default is: ETH, NET, WEB3.

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[=<true|false>]

--rpc-http-authentication-enabled=true

BESU_RPC_HTTP_AUTHENTICATION_ENABLED=true

rpc-http-authentication-enabled=true

Enables or disables 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.

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.

rpc-http-enabled

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

--rpc-http-enabled=true

BESU_RPC_HTTP_ENABLED=true

rpc-http-enabled=true

Enables or disables 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"

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.

rpc-http-max-active-connections

--rpc-http-max-active-connections=<INTEGER>

--rpc-http-max-active-connections=100

BESU_RPC_HTTP_MAX_ACTIVE_CONNECTIONS=100

rpc-http-max-active-connections=100

The maximum number of allowed HTTP JSON-RPC connections. Once this limit is reached, incoming connections are rejected. The default is 80.

rpc-http-max-batch-size

--rpc-http-max-batch-size=<INTEGER>

--rpc-http-max-batch-size=1200

BESU_RPC_HTTP_MAX_BATCH_SIZE=1200

rpc-http-max-batch-size=1200

The maximum number of allowed requests in a RPC batch request. The default limit is 1024, and -1 specifies no limit.

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 port (TCP) on which HTTP JSON-RPC listens. The default is 8545. You must expose ports appropriately.

rpc-http-tls-ca-clients-enabled

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

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

BESU_RPC_HTTP_TLS_CA_CLIENTS_ENABLED=true

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

Enables or disables clients with trusted CA certificates to connect. The default is false.

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

--rpc-http-tls-client-auth-enabled[=<true|false>]

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

BESU_RPC_HTTP_TLS_CLIENT_AUTH_ENABLED=true

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

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

rpc-http-tls-cipher-suite

--rpc-http-tls-cipher-suite=<cipherSuiteName>[, <cipherSuiteName>...]

--rpc-http-tls-cipher-suite=TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

BESU_RPC_HTTP_TLS_CIPHER_SUITE=TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

rpc-http-tls-cipher-suite=["TLS_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"]

A list of comma-separated TLS cipher suites to support.

rpc-http-tls-enabled

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

--rpc-http-tls-enabled=true

BESU_RPC_HTTP_TLS_ENABLED=true

rpc-http-tls-enabled=true

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

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 certificate’s Common Name, and SHA-256 fingerprint in the format <CommonName> <hex-string>.

rpc-http-tls-protocol

--rpc-http-tls-protocol=<protocolName>[, <protocolName>...]

--rpc-http-tls-protocol=TLSv1.3,TLSv1.2

BESU_RPC_HTTP_TLS_PROTOCOL=TLSv1.3,TLSv1.2

rpc-http-tls-protocol=["TLSv1.3","TLSv1.2"]

A list of comma-separated TLS protocols to support. The default is DEFAULT_TLS_PROTOCOLS, a list which includes TLSv1.3 and TLSv1.2.

rpc-max-logs-range

--rpc-max-logs-range=<INTEGER>

--rpc-max-logs-range=500

BESU_RPC_MAX_LOGS_RANGE=500

rpc-max-logs-range=500

When using eth_getLogs, the maximum number of blocks to retrieve logs from. Set to 0 to specify no limit. The default is 1000.

rpc-tx-feecap

--rpc-tx-feecap=<MAX_FEE>

--rpc-tx-feecap=1200000000000000000

BESU_RPC_TX_FEECAP=1200000000000000000

rpc-tx-feecap=1200000000000000000

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

--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, QBFT, TRACE, TXPOOL, and WEB3. The default is: ETH, NET, WEB3.

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[=<true|false>]

--rpc-ws-authentication-enabled=true

BESU_RPC_WS_AUTHENTICATION_ENABLED=true

rpc-ws-authentication-enabled=true

Enables or disables authentication for the WebSocket JSON-RPC service.

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

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

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

BESU_RPC_WS_AUTHENTICATION_JWT_PUBLIC_KEY_FILE="publicKey.pem"

rpc-ws-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[=<true|false>]

--rpc-ws-enabled=true

BESU_RPC_WS_ENABLED=true

rpc-ws-enabled=true

Enables or disables the WebSocket 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 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

--rpc-ws-max-active-connections=<INTEGER>

--rpc-ws-max-active-connections=100

BESU_RPC_WS_MAX_ACTIVE_CONNECTIONS=100

rpc-ws-max-active-connections=100

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

--rpc-ws-max-frame-size=<INTEGER>

--rpc-ws-max-frame-size=65536

BESU_RPC_WS_MAX_FRAME_SIZE=65536

rpc-ws-max-frame-size=65536

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

--rpc-ws-port=<PORT>

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

BESU_RPC_WS_PORT=6174

rpc-ws-port="6174"

The port (TCP) on which WebSocket JSON-RPC listens. 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.

The default is the node’s local private key file specified using --node-private-key-file.

static-nodes-file

--static-nodes-file=<FILE>

--static-nodes-file=~/besudata/static-nodes.json

BESU_STATIC_NODES_FILE=~/besudata/static-nodes.json

static-nodes-file="~/besudata/static-nodes.json"

Static nodes JSON file containing the static nodes for this node to connect to. The default is datapath/static-nodes.json.

strict-tx-replay-protection-enabled

--strict-tx-replay-protection-enabled[=<true|false>]

--strict-tx-replay-protection-enabled=false

STRICT_TX_REPLAY_PROTECTION_ENABLED=false

strict-tx-replay-protection-enabled=false

Enables or disables replay protection, in accordance with EIP-155, on transactions submitted using JSON-RPC. The default is false.

sync-mode

--sync-mode=X_SNAP

--sync-mode=X_SNAP

BESU_SYNC_MODE=X_SNAP

sync-mode="X_SNAP"

The synchronization mode. Use X_SNAP for snap sync, X_CHECKPOINT for checkpoint sync, FAST for fast sync, and FULL for full 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, except for the dev development network. FAST is also the default if running Besu on the default network (Ethereum Mainnet) by specifying neither network nor genesis file.

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/1024^th, 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/1024^th, 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.

Use the miner_changeTargetGasLimit API to update the target-gas-limit while Besu is running. Alternatively restart Besu with an updated target-gas-limit value.

tx-pool-limit-by-account-percentage

--tx-pool-limit-by-account-percentage=<DOUBLE>

--tx-pool-limit-by-account-percentage=0.1

BESU_TX_POOL_LIMIT_BY_ACCOUNT_PERCENTAGE=0.1

tx-pool-limit-by-account-percentage=0.4

The maximum percentage of future transactions kept in the transaction pool, per account. Accepted values are in the range (0–1]. The default is .001 or 0.1% of transactions from a single account to be kept in the pool.

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

Xhelp

-X, --Xhelp

Displays the early access options and their descriptions, and exit.

version

-V, --version

Prints version information and exit.