Skip to main content

Options

This reference describes the syntax of the Besu configuration options.

info

This reference contains options that apply to both public and private networks. For private-network-specific options, see the private network options reference.

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 --rpc-http-enabled using the BESU_RPC_HTTP_ENABLED 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
caution

Characters such as smart quotes and long (em) hyphens don't work in Besu command line options. Ensure quotes aren't automatically converted to smart quotes, or double hyphens combined into em hyphens.

Options​

api-gas-price-blocks​

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

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

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

Percentile value to measure for eth_gasPrice. The default is 50.0.

For eth_gasPrice, to return the:

auto-log-bloom-caching-enabled​

--auto-log-bloom-caching-enabled[=<true|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>...]...

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.

block-txs-selection-max-time​

--block-txs-selection-max-time=<INTEGER>

The maximum time, in milliseconds, that can be spent selecting transactions to be included in a block. This value must be less than or equal to the default, 5000.

note

This option only applies to proof-of-stake and proof-of-work networks. For proof-of-authority networks, see --poa-block-txs-selection-max-time.

bonsai-historical-block-limit​

--bonsai-historical-block-limit=<INTEGER>

When using Bonsai Tries, the maximum number of previous blocks for which Bonsai can reconstruct a historical state. The default is 512.

note

If you plan on querying historical blocks or state using the JSON-RPC API, you might need to adjust the default value or your configured value to avoid errors.

bonsai-limit-trie-logs-enabled​

--bonsai-limit-trie-logs-enabled=[=<true|false>]

Enables or disables limiting the number of Bonsai Trie logs that are retained. When enabled, this limit is set to the value of --bonsai-historical-block-limit. The default is true, unless --sync-mode=FULL is set, in which case this option is disallowed and must be set to false.

bonsai-trie-logs-pruning-window-size​

--bonsai-trie-logs-pruning-window-size=<INTEGER>

When using --bonsai-limit-trie-logs-enabled, the number of trie logs to prune during one pruning operation. A larger value might impact node performance. The default is 30000.

bootnodes​

--bootnodes[=<source>[,<source>...]...]

A list of comma-separated sources for P2P discovery bootstrap, where each source can be one of the following:

  • A direct enode URL: enode://<id>@<host>:<port>
  • A local file path: /path/to/bootnodes.txt
  • A file URI: file:///path/to/bootnodes.txt
  • An HTTP(S) URL: https://example.com/bootnodes.txt

Each file or URL must contain one enode URL per line. Blank lines and lines starting with # are ignored. 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.

cache-last-blocks​

--cache-last-blocks=<INTEGER>

The number of recent blocks to cache. Using this option can improve the performance of several RPC calls including: eth_getBlockByNumber, eth_getBlockByHash, eth_getTransactionReceipt, and especially eth_feeHistory. The default is 0.

color-enabled​

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

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

config-file​

--config-file=<FILE>

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

data-path​

--data-path=<PATH>

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>

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

discovery-dns-url​

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

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

discovery-enabled​

--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 early access option --Xp2p-dns-discovery-server=<HOST>.

engine-host-allowlist​

--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-jwt-disabled​

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

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

engine-jwt-secret​

--engine-jwt-secret=<FILE>

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

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

engine-rpc-port​

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

era1-data-uri​

--era1-data-uri=<URI>

The URI or local path to attempt to import ERA1 files from. For local files, a simple path may be used (for example, /home/user/era1). The default is https://mainnet.era1.nimbus.team/.

era1-import-prepipeline-concurrency​

--era1-import-prepipeline-concurrency=<INTEGER>

Number of parallel processes used to import ERA1 archive files before full synchronization begins. Increasing this may improve performance when loading files from remote sources or on systems with high I/O capacity. The default is 1.

In most cases, we recommend using the default unless slow file downloads are a limiting factor.

era1-import-prepipeline-enabled​

--era1-import-prepipeline-enabled[=<Boolean>]

Enables importing pre-merge blocks from ERA1 archive files before full sync begins. Files are loaded from the location specified by--era1-data-uri (supports local paths and HTTP URLs).

This option only applies when --sync-mode=FULL; it has no effect in other sync modes. The default is false.

Use this to accelerate syncing from genesis or to restore full historical data without relying on peer-to-peer downloads.

estimate-gas-tolerance-ratio​

--estimate-gas-tolerance-ratio=<DECIMAL>

Defines the tolerance used when estimating gas for the eth_estimateGas JSON-RPC method. Lower values increase accuracy but take longer to compute. Higher values speed up estimation but might provide less precise results.

The default is 0.015. Set to 0.0 to disable tolerance and prioritize maximum accuracy.

ethstats​

--ethstats=<[ws://|wss://]nodename:secret@host:[port]>

Reporting URL of an Ethstats server. If specified without a port, the default port is 443 for SSL connections and 80 for non-SSL connections.

You can optionally specify ws:// or wss:// in the Ethstats URL. If you specify this scheme, the connection doesn't need to switch from SSL to non-SSL on each retry logic.

ethstats-cacert-file​

--ethstats-cacert-file=<FILE>

Path to the root certificate authority (CA) certificate file of the Ethstats server specified by --ethstats. This option is useful in non-production environments.

ethstats-contact​

--ethstats-contact=<CONTACT>

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

ethstats-report-interval​

--ethstats-report-interval=<INTEGER>

Interval (in seconds) at which Besu sends status updates to the EthStats server.
The default is 5.

genesis-file​

--genesis-file=<FILE>

The path to the genesis file.

caution

You can't use the --genesis-file and --network options at the same time.

genesis-state-hash-cache-enabled​

--genesis-state-hash-cache-enabled=[=<true|false>]

Enables or disables fast startup from an existing genesis state hash. The default is false.

warning

Enabling this option avoids validating the genesis state hash, trading off security for faster node startup times. We only recommend using this option if you are certain that you have not modified your genesis file or database and understand the security implications.

graphql-http-cors-origins​

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

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

graphql-http-enabled​

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

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

--graphql-http-port=<PORT>

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

graphql-mtls-enabled​

--graphql-mtls-enabled[=<true|false>]

Enables or disables mTLS for the GraphQL HTTP service. The default is false.

note

--graphql-http-enabled must be enabled.

graphql-tls-enabled​

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

Enables or disables TLS for the GraphQL HTTP service. The default is false.

note

--graphql-http-enabled must be enabled.

graphql-tls-keystore-file​

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

Path to the keystore file when enabling TLS for the GraphQL HTTP service. The keystore file contains the private key and certificate presented to the client during authentication.

Specify the keystore password file using --graphql-tls-keystore-password-file.

graphql-tls-keystore-password-file​

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

Path to the file containing the password for the keystore specified in --graphql-tls-keystore-file, when enabling TLS for the GraphQL HTTP service.

graphql-tls-truststore-file​

--graphql-tls-truststore-file=<FILE>

Path to the truststore file when enabling TLS for the GraphQL HTTP service.

Specify the truststore password file using --graphql-tls-truststore-password-file.

graphql-tls-truststore-password-file​

--graphql-tls-truststore-password-file=<FILE>

Path to the file containing the password for the truststore specified in --graphql-tls-truststore-file, when enabling TLS for the GraphQL HTTP service.

help​

-h, --help

Show the help message and exit.

history-expiry-prune​

--history-expiry-prune[=<true|false>]

Enables or disables online pruning of historical block data for pre-merge Proof of Work (PoW) blocks, retaining only the headers. The option also activates garbage collection settings that works for both online and offline pruning mechanisms, so that the reclaimed storage is compacted quickly, freeing disk space without manual intervention.

The default is false.

host-allowlist​

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

info

This isn't a permissioning feature. To restrict access to the API, we recommend using the Besu authentication mechanism with username and password authentication or JWT public key authentication.

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>

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.

json-pretty-print-enabled​

--json-pretty-print-enabled[=<true|false>]

Enables or disables the pretty-print output for HTTP and WebSocket responses. The default is false.

key-value-storage​

--key-value-storage=<keyValueStorageName>

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.

kzg-trusted-setup​

--kzg-trusted-setup=<PATH>

The path to the C-KZG-4844 trusted setup file. Use this option to pass a custom setup file for custom networks or to override the default setup file for named networks.

logging​

-l, --logging=<LEVEL>

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

max-peers​

--max-peers=<INTEGER>

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

metrics-category​

--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, SYNCHRONIZER, and TRANSACTION_POOL.

Other categories are KVSTORE_ROCKSDB, KVSTORE_PRIVATE_ROCKSDB, KVSTORE_ROCKSDB_STATS, and KVSTORE_PRIVATE_ROCKSDB_STATS.

metrics-enabled​

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

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

--metrics-port=<PORT>

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 to use: PROMETHEUS, OPENTELEMETRY, or NONE. The default is PROMETHEUS.

metrics-push-enabled​

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

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

--metrics-push-interval=<INTEGER>

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

metrics-push-port​

--metrics-push-port=<PORT>

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>

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

min-block-occupancy-ratio​

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

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.

note

Besu ignores the --min-block-occupancy-ratio option for proof-of-stake networks, such as Ethereum Mainnet.

min-gas-price​

--min-gas-price=<minTransactionGasPrice>

The minimum price (in wei) 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.

For a running node, use:

tip

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.

min-priority-fee​

--min-priority-fee=<minPriorityFeePerGas>

The minimum priority fee per gas (in wei) offered by a transaction to be included in a block. The default is 0.

For a running node, use:

miner-extra-data​

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

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

nat-method​

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

tip

Use UPNPP2PONLY if you wish to enable UPnP for P2P traffic but not JSON-RPC.

note

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.

net-restrict​

--net-restrict=<subnet>[,<subnet>,...]

A comma-separated list of allowed IP subnets. Peers whose IP addresses fall within the specified subnets are granted permission to interact with the node. If not specified, no subnet-based peer permission restrictions are applied.

network​

--network=<NETWORK>

The predefined network configuration. The default is mainnet.

Possible values include the following:

NetworkChainTypeDefault sync modeConsensus mechanismDescription
mainnetETHProductionSNAPPoS networkThe main Ethereum network
hoodiETHTestSNAPPoS networkMulti-client Ethereum testnet Hoodi
sepoliaETHTestSNAPPoS networkMulti-client Ethereum testnet Sepolia
devETHDevelopmentFULLPoW networkDevelopment network with low difficulty to enable local CPU mining
ephemeryETHTestSNAPPoS networkMulti-client Ethereum testnet Ephemery
linea_mainnetLineaProductionSNAPSequencer-based (zkEVM rollup)The main Linea network
linea_sepoliaLineaTestSNAPSequencer-based (zkEVM rollup)Linea Sepolia testnet
luksoLuksoProductionSNAPPoS networkNetwork for the Lukso chain
tip

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

info

  • You can't use the --network and --genesis-file options at the same time.

  • The following networks and testnets are deprecated: ETC Classic, Holesky, and Mordor.

network-id​

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

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

danger

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

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

p2p-host​

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

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

--p2p-port=<PORT>

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

plugin-block-txs-selection-max-time​

--plugin-block-txs-selection-max-time=<INTEGER>

Maximum time, as a percentage of the overall block creation time, that plugins can use to propose their own transactions during block creation. The default is 50: limiting plugins to up to 50% of the total block creation time.

plugin-continue-on-error​

--plugin-continue-on-error[=<true|false>]

Enables or disables continuing to run Besu if a plugin fails during registration or other startup lifecycle stages. If set to true and any plugin fails, Besu logs an error and continues running. If set to false and any plugin fails, Besu logs an error and stops running.

The default is false.

plugins​

--plugins=<PLUGIN>[,<PLUGIN>,...]

Comma-separated list of plugin names to load. Each plugin must reside in the plugins directory. If you omit this option, Besu automatically loads all plugins found in that directory.

The plugin name is case-sensitive, and is the name of the class that implements BesuPlugin in the plugin source code.

If the specified plugin is not found, Besu exits with an error identifying the missing plugin.

--print-paths-and-exit

Prints the Besu data directory paths and exits without starting the node.

profile​

--profile=<PROFILE>

Loads a pre-configured TOML file containing custom settings for a specific user profile. Possible values are:

The default is null.

random-peer-priority-enabled​

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

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

receipt-compaction-enabled​

--receipt-compaction-enabled=<true|false>

Enables or disables receipt compaction. Compacting receipts reduces storage by trimming unnecessary data from transaction receipts. The default is false.

remote-connections-limit-enabled​

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

tip

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

danger

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>

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>

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

required-block​

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

--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. We don't recommend enabling revert reason when connected to public Ethereum networks.

rpc-gas-cap​

--rpc-gas-cap=<INTEGER>

Sets a limit on the amount of gas for transaction simulation RPC methods. This option allows users to override the transaction's gas limit. This can prevent the simulation of transactions with high gas usage by setting a predefined cap, preventing DoS attacks. Its value must be greater than or equal to 0. The default is 100000000. You can set this to 0 to indicate there is no limit. This cap prevents eth_call requests from using excessive resources.

rpc-http-api​

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

A comma-separated list of APIs to enable on the JSON-RPC HTTP channel. When you use this option you must also specify the --rpc-http-enabled option. The available API options are: ADMIN, CLIQUE, DEBUG, ETH, IBFT, MINER, NET, PERM, PLUGINS, 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-api-methods-no-auth​

--rpc-http-api-methods-no-auth=<api method>[,<api method>,...]

A comma-separated list of JSON-RPC API methods to exclude from authentication services.

note

You must enable JSON-RPC HTTP authentication using --rpc-http-authentication-enabled.

rpc-http-authentication-credentials-file​

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

The credentials file for JSON-RPC API authentication.

rpc-http-authentication-enabled​

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

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

rpc-http-authentication-jwt-algorithm​

---rpc-http-authentication-jwt-algorithm=<algorithm>

The JWT key algorithm used to generate the keypair for JSON-RPC HTTP authentication. Possible values are RS256, RS384, RS512, ES256, ES384, and ES512. The default is RS256.

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

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

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

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

note

To run a local Besu node with MetaMask, set --rpc-http-cors-origins to chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn.

Remember to also include the dapp domain MetaMask interacts with, for example if your app is deployed on Remix and you're using MetaMask to interact with the contract, use --rpc-http-cors-origins=chrome-extension://nkbihfbeogaeaoehlefnkodbefgpgknn,http://remix.ethereum.org

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

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

rpc-http-host​

--rpc-http-host=<HOST>

The host on which JSON-RPC HTTP 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​

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

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

rpc-http-max-request-content-length​

--rpc-http-max-request-content-length=<LONG>

The maximum request content length. Besu only accepts JSON-RPC API requests with a body size less than or equal to this value. The default is 5242880 (5 MB).

rpc-http-max-batch-size​

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

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>

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

rpc-http-tls-ca-clients-enabled​

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

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

Enables or disables 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-cipher-suite​

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

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

tip

The singular --rpc-http-tls-cipher-suite and plural --rpc-http-tls-cipher-suites are available and are two names for the same option.

rpc-http-tls-enabled​

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

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

Path to the keystore file (in PKCS #12 format) when enabling TLS for the JSON-RPC HTTP service. The keystore file contains the private key and certificate presented to the client during authentication.

Specify the keystore password file using --rpc-http-tls-keystore-password-file.

rpc-http-tls-keystore-password-file​

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

Path to the file containing the password for the keystore specified in --rpc-http-tls-keystore-file, when enabling TLS for the JSON-RPC HTTP service.

rpc-http-tls-known-clients-file​

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

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

note

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

rpc-http-tls-protocol​

--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-http-tls-truststore-file​

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

Path to the truststore file when enabling TLS for the JSON-RPC HTTP service.

Specify the truststore password file using --rpc-http-tls-truststore-password-file.

rpc-http-tls-truststore-password-file​

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

Path to the file containing the password for the truststore specified in --rpc-http-tls-truststore-file, when enabling TLS for the JSON-RPC HTTP service.

rpc-max-logs-range​

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

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

caution

Using eth_getLogs to get logs from a large range of blocks, especially an entire chain from its genesis block, might cause Besu to stop responding for an indeterminable amount of time while generating the response.

We recommend setting a range limit or leaving this option at its default value.

rpc-max-trace-filter-range​

--rpc-max-trace-filter-range=<INTEGER>

The maximum number of blocks you can supply to the trace_filter method. The value must be equal to or greater than 0. Setting this option to 0 indicates there is no limit. The default is 1000.

rpc-tx-feecap​

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

--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, ETH, IBFT, MINER, NET, PERM, PLUGINS, 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-api-methods-no-auth​

--rpc-ws-api-methods-no-auth=<api method>[,<api method>,...]

A comma-separated list of JSON-RPC API methods to exclude from authentication services.

note

You must enable JSON-RPC WebSocket authentication using --rpc-ws-authentication-enabled.

rpc-ws-authentication-credentials-file​

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

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

rpc-ws-authentication-enabled​

--rpc-ws-authentication-enabled[=<true|false>]

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

note

wscat doesn't 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-algorithm​

---rpc-ws-authentication-jwt-algorithm=<algorithm>

The JWT key algorithm used to generate the keypair for JSON-RPC WebSocket authentication. Possible values are RS256, RS384, RS512, ES256, ES384, and ES512. The default is RS256.

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

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

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

Enables or disables the WebSocket JSON-RPC service. The default is false.

rpc-ws-host​

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

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

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

--rpc-ws-port=<PORT>

The port (TCP) on which WebSocket JSON-RPC listens. The default is 8546. You must expose ports appropriately.

rpc-ws-ssl-cert-file​

--rpc-ws-ssl-cert-file=<FILE>

Path to the PEM certificate file enabling SSL/TLS for the WebSocket JSON-RPC service. This file contains the public certificate that is used to establish the identity of the server to clients.

Specify the private key file using --rpc-ws-ssl-key-file.

Required if --rpc-ws-ssl-keystore-type is PEM.

rpc-ws-ssl-client-auth-enabled​

--rpc-ws-ssl-client-auth-enabled[=<true|false>]

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

note

When enabling client authentication, specify the truststore type using --rpc-ws-ssl-truststore-type and provide the appropriate file path for the truststore or trust certificate using either --rpc-ws-ssl-truststore-file (for JKS or PKCS12) or --rpc-ws-ssl-trustcert-file (for PEM).

If using JKS or PKCS12, specify the truststore password using --rpc-ws-ssl-truststore-password.

rpc-ws-ssl-enabled​

--rpc-ws-ssl-enabled[=<true|false>]

Enables or disables server SSL/TLS authentication for the WebSocket JSON-RPC service. The default is false.

Set the appropriate keystore type using --rpc-ws-ssl-keystore-type.

rpc-ws-ssl-key-file​

--rpc-ws-ssl-key-file=<FILE>

Path to the PEM certificate file when enabling SSL/TLS for the WebSocket JSON-RPC service. This file contains the private key that corresponds to the public certificate specified using --rpc-ws-ssl-cert-file.

Required if --rpc-ws-ssl-keystore-type is PEM.

rpc-ws-ssl-keystore-file​

--rpc-ws-ssl-keystore-file=<FILE>

Path to the keystore file when enabling SSL/TLS for the WebSocket JSON-RPC service. The keystore file is used to store the server's private key and public certificate in a single file, typically in JKS or PKCS12 format. Use this option if you prefer to manage your SSL/TLS certificates and keys in a keystore rather than separate PEM files.

Required if --rpc-ws-ssl-keystore-type is set to JKS or PKCS12.

Specify the keystore password using --rpc-ws-ssl-keystore-password or --rpc-ws-ssl-keystore-password-file.

rpc-ws-ssl-keystore-password​

--rpc-ws-ssl-keystore-password=<STRING>

Password for the keystore specified in --rpc-ws-ssl-keystore-file, when enabling WebSocket SSL/TLS client authentication.

rpc-ws-ssl-keystore-password-file​

--rpc-ws-ssl-keystore-password-file=<FILE>

Path to the file containing the password for the keystore specified in --rpc-ws-ssl-keystore-file, when enabling WebSocket SSL/TLS client authentication.

rpc-ws-ssl-keystore-type​

--rpc-ws-ssl-keystore-type=<STRING>

Type of the keystore when enabling SSL/TLS for the WebSocket JSON-RPC service. Valid options are JKS, PKCS12, and PEM.

Provide the appropriate file path for the keystore using either --rpc-ws-ssl-keystore-file (for JKS or PKCS12), or --rpc-ws-ssl-key-file and --rpc-ws-ssl-cert-file (for PEM).

rpc-ws-ssl-trustcert-file​

--rpc-ws-ssl-trustcert-file=<FILE>

Path to the PEM trust certificate file when enabling client SSL/TLS authentication for the WebSocket JSON-RPC service.

rpc-ws-ssl-truststore-file​

--rpc-ws-ssl-truststore-file=<FILE>

Path to the truststore file when enabling SSL/TLS client authentication for the WebSocket JSON-RPC service.

Specify the truststore password using --rpc-ws-ssl-truststore-password or --rpc-ws-ssl-truststore-password-file.

rpc-ws-ssl-truststore-password​

--rpc-ws-ssl-truststore-password=<STRING>

Password for the truststore specified using --rpc-ws-ssl-truststore-file, when enabling WebSocket SSL/TLS client authentication.

rpc-ws-ssl-truststore-password-file​

--rpc-ws-ssl-truststore-password-file=<FILE>

Path to the file containing the password for the truststore specified in --rpc-ws-ssl-truststore-file, when enabling WebSocket SSL/TLS client authentication.

rpc-ws-ssl-truststore-type​

--rpc-ws-ssl-truststore-type=<STRING>

Type of the truststore when enabling client SSL/TLS authentication for the WebSocket JSON-RPC service. Valid options are JKS, PKCS12, and PEM.

Specify the required --rpc-ws-ssl-truststore-file for JKS and PKCS12, or --rpc-ws-ssl-trustcert-file for PEM.

security-module​

--security-module=<NAME>

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.

snapsync-server-enabled​

--snapsync-server-enabled[=<true|false>]

Enables or disables serving snap sync data. Set to true to allow other nodes to download data from this node using snap sync. The default is false.

snapsync-synchronizer-pre-checkpoint-headers-only-enabled​

--snapsync-synchronizer-pre-checkpoint-headers-only-enabled[=<true|false>]

If set to false, snap sync downloads full pre-merge Proof of Work (PoW) historical blocks instead of headers only, allowing full historical data to be retained. The default is true.

Setting this option to false increases sync time and disk space usage.

snapsync-synchronizer-transaction-indexing-enabled​

--snapsync-synchronizer-transaction-indexing-enabled[=<true|false>]

Enables or disables transaction indexing during initial sync for snap sync and checkpoint sync. The default is false.

Notes
  • Enable this option to query historical transactions by hash.
  • Setting this option to true increases sync time and disk space usage.

static-nodes-file​

--static-nodes-file=<FILE>

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

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

sync-min-peers, fast-sync-min-peers​

--sync-min-peers=<INTEGER>

The minimum number of peers required before starting sync. The default is 5. Set to 1 to enable static peers to contribute to the initial sync.

info

This option does not apply to Proof of Stake networks.

sync-mode​

--sync-mode=<MODE>

The synchronization mode. Use SNAP for snap sync, 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 SNAP when using the --network option with named networks, except for the dev development network. SNAP is also the default if running Besu on the default network (Ethereum Mainnet) by specifying neither network nor genesis file.
Notes
  • We recommend using snap sync over fast sync because snap sync can be faster by several days.
  • Fast sync is deprecated in Besu version 24.12.0 and later. We recommend updating Besu to a version that supports other sync methods.
  • When using a mode other than FULL, most historical world state data is unavailable. Any methods attempting to access unavailable world state data return null.

target-gas-limit​

--target-gas-limit=<INTEGER>

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.

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​

--tx-pool=<TYPE>

Type of transaction pool to use. Set to layered to use the layered transaction pool implementation. The default is layered.

Set to sequenced to use the sequenced transaction pool. The default is sequenced for the enterprise/private profile.

tx-pool-blob-price-bump​

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

Sets the price bump policy for re-issued blob transactions as a percentage increase in price. A blob transaction can only replace, or be replaced by, another blob transaction. The default is 100.

tx-pool-enable-balance-check​

--tx-pool-enable-balance-check[=<true|false>]

Enables or disables balance checks for pending transactions in the transaction pool. When enabled, the check prevents pending transactions, whose sender doesn't have enough balance to pay their fee, from being included in the prioritized layer. This prevents such transactions from occupying space and potentially being selected for block production. The default is false.

tx-pool-enable-save-restore​

--tx-pool-enable-save-restore[=<true|false>]

Enables or disables saving the transaction pool contents to a file on shutdown and reloading it at startup. The default is false.

You can define a custom path to the transaction pool file using the --tx-pool-save-file option.

tx-pool-layer-max-capacity​

--tx-pool-layer-max-capacity=<INTEGER>

Maximum amount of memory (in bytes) that any layer within the layered transaction pool can occupy. The default is 12500000, or 12.5 MB.

The transaction pool includes two memory-limited layers, resulting in an expected memory consumption that is twice the value specified by this option, or 25 MB by default. Increase this value if you have spare RAM and the eviction rate is high for your network.

tx-pool-limit-by-account-percentage​

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

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

caution

  • With the layered transaction pool implementation, this option is not applicable. Replace this option with --tx-pool-max-future-by-sender to specify the maximum number of sequential transactions from a single sender kept in the pool.

  • The default value is often unsuitable for private networks. This feature mitigates future-nonce transactions from filling the pool without ever being executable by Besu. This is important for Mainnet, but may cause issues on private networks. Please update this value or set to 1 if you know the nodes gossiping transactions in your network.

tx-pool-max-future-by-sender​

--tx-pool-max-future-by-sender=<INTEGER>

The maximum number of sequential transactions from a single sender kept in the layered transaction pool. The default is 200.

Increase this value to allow a single sender to fit more transactions in a single block. For private networks, you can set this in the hundreds or thousands if you want to ensure transactions with large nonce gaps remain in the transaction pool.

tx-pool-max-prioritized​

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

The maximum number of transactions that are prioritized in the layered transaction pool. The default is 2000.

For private networks, we recommend setting this value to the maximum number of transactions that fit in a block in your network.

tx-pool-max-prioritized-by-type​

--tx-pool-max-prioritized-by-type=["<TYPE=INTEGER>",...]

The maximum number of transactions of a specific transaction type that are prioritized in the layered transaction pool.

This option is mostly useful for tuning the amount of prioritized blob transactions in the transaction pool. Keeping the prioritized layer sorted is costly, and only a few blob transactions can fit in a block (currently a maximum of six). Tuning the maximum number of prioritized transactions by type can help maintain the efficiency and performance of the transaction pool. The default is BLOB=6.

tx-pool-max-size​

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

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

caution

With the layered transaction pool implementation, this option is not applicable because the layered pool is limited by memory size instead of the number of transactions. To configure the maximum memory capacity, use --tx-pool-layer-max-capacity.

tx-pool-min-gas-price​

--tx-pool-min-gas-price=<INTEGER>

The minimum gas price, in wei, required for a transaction to be accepted into the transaction pool.

tx-pool-min-score​

--tx-pool-min-score=<INTEGER>

Remove a pending transaction from the layered transaction pool if its score is lower than this value. Accepts a value between -128 and 127. The default is -128.

The lowest score a pending transaction can have is -128. The default value of -128 means that pending transactions will not be removed and will remain in the pool with the lowest score, being selected after all other pending transactions.

tx-pool-no-local-priority​

--tx-pool-no-local-priority[=<true|false>]

If this option is set to true, senders of transactions submitted via RPC are not prioritized over remote transactions in the transaction pool. The default is false.

tx-pool-price-bump​

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

The price bump percentage to replace an existing transaction in the transaction pool. For networks with a base fee and priced gas, the default is 10, or 10%. For networks with zero base fee, or free gas, the default is 0.

tx-pool-priority-senders​

--tx-pool-priority-senders=<address>[,<address>,...]

A comma-separated list of sender addresses to prioritize in the transaction pool. Transactions sent from these addresses, from any source, are prioritized and only evicted after all others. If not specified, only senders submitting transactions via RPC have priority (unless --tx-pool-no-local-priority is set to true).

tx-pool-retention-hours​

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

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

caution

With the layered transaction pool implementation, this option is not applicable because old transactions will expire when the memory cache is full.

tx-pool-save-file​

--tx-pool-save-file=<FILE>

The path to the file that stores the transaction pool's content if the save and restore functionality is enabled using --tx-pool-enable-save-restore. The file is created on shutdown and reloaded during startup. The default file name is txpool.dump in the data directory.

version​

-V, --version

Prints version information and exits.

version-compatibility-protection​

--version-compatibility-protection[=<true|false>]

Enables or disables performing version compatibility checks when starting Besu. If set to true, it checks that the version of Besu being started is the same or later than the version of Besu that previously started with the same data directory.

The default is false for named networks, such as Mainnet or Sepolia, and true for non-named networks.

Xhelp​

-X, --Xhelp

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

caution

The displayed options are unstable and may change between releases.