Configure Besu
Besu comes with a default configuration that is suitable for staking.
You can override the default values by specifying configuration options on the command line, as environment variables, or in a TOML configuration file that can be reused across node startups.
You can also use a pre-configured profile for some common use cases or create and apply a custom profile.
Configuration order of precedence
For options specified in multiple places, the order of precedence is as follows:
- Command line
- Environment variable
- Configuration file specified by
--config-file
- Pre-configured profile specified by
--profile
- Default values (used if no other configuration source is available)
For example, if you specify a config.toml
configuration file and staker
profile, and an option
is not found in the environment variables, Besu looks for it in config.toml
.
If the option is not found in config.toml
, Besu looks for it in staker.toml
.
If the option is not found in staker.toml
, Besu uses the default value for that option.
TOML configuration file
The configuration file is used for node-level settings. You can specify network-wide settings in the genesis file.
Specify the configuration file using the --config-file
option.
The configuration file must be a valid TOML file composed of key/value pairs. Each key is the same as the corresponding command line option name without the leading dashes (--
).
Values must conform to TOML specifications for string, numbers, arrays, and booleans. Specific differences between the command line and the TOML file format are:
- Comma-separated lists on the command line are string arrays in the TOML file.
- Enclose file paths, hexadecimal numbers, URLs, and <host:port> values in quotes.
Table headings are ignored in TOML files. If you specify a valid Besu option under a table heading in the configuration file, Besu ignores the table heading and reads the option in the same way it does for options not under table headings.
The command line reference includes configuration file examples for each option.
# Valid TOML config file
data-path="~/besudata" # Path
# Network
bootnodes=["enode://001@123:4567", "enode://002@123:4567", "enode://003@123:4567"]
p2p-host="1.2.3.4"
p2p-port=1234
max-peers=42
rpc-http-host="5.6.7.8"
rpc-http-port=5678
rpc-ws-host="9.10.11.12"
rpc-ws-port=9101
# Chain
genesis-file="~/genesis.json" # Path to the custom genesis file
# Mining
miner-enabled=true
miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"
besu --config-file=/home/me/me_node/config.toml
Default configuration
The following tables describe important default values of Besu's configuration. When using the default configuration, Besu is optimized for staking. You can extend these defaults using a profile.
For example, extending the default configuration using the staker profile directs Besu to use Mainnet, creating a staking-optimized node ready to run with a validator and consensus client.
Peering
Configuration option | Default | Description |
---|---|---|
discovery-enabled | true | Besu assumes the node will automatically discover other Ethereum nodes using P2P. |
p2p-enabled | true | Besu assumes the node will connect P2P. |
engine-rpc-enabled | true | Besu assumes the Engine API will be required to communicate with the consensus layer. |
Storage
Configuration option | Default | Description |
---|---|---|
data-storage-format | BONSAI | Besu uses Bonsai Tries, the most space-efficient data storage format. |
Sync
Configuration option | Default | Description |
---|---|---|
sync-mode | SNAP | Besu syncs using snap sync, the most time-efficient sync method. |
You can see all default configuration values in the configuration options reference.