Teku command line options
This reference describes the syntax of the Teku command line interface (CLI) options.
The CLI options are currently under development and may change.
Specify options
You can specify Teku options:
-
On the command line.
teku [OPTIONS] [COMMAND]
-
As an environment variable. For each command line option, the equivalent environment variable is:
- Uppercase.
-
is replaced by_
.- Has a
TEKU_
prefix.
-
In a YAML configuration file.
If an option is specified in multiple places, the order of priority is command line, environment variable, configuration file.
Using autocomplete
If using Bash or Z shell, you can enable autocomplete support by navigating to the build
folder and running:
source teku.autocomplete.sh
Autocomplete allows you to view option suggestions by entering --
and pressing the Tab key twice.
teku --Tab+Tab
Options
beacon-liveness-tracking-enabled
Syntax
--beacon-liveness-tracking-enabled[=<BOOLEAN>]
Example
--beacon-liveness-tracking-enabled=true
Environment variable
TEKU_BEACON_LIVENESS_TRACKING_ENABLED=true
Configuration file
beacon-liveness-tracking-enabled: true
Enables or disables validator liveness tracking. Used by doppelganger detection. The default is false
.
builder-bid-compare-factor
Syntax
--builder-bid-compare-factor=<STRING>
Example
--builder-bid-compare-factor=50
Environment variable
TEKU_BUILDER_BID_COMPARE_FACTOR=50
Configuration file
builder-bid-compare-factor: 50
The builder bid compare factor. The default is 100 (100%).
Execution layer clients in Capella-enabled networks provide the execution payload and the payload value. The beacon node compares this value against the builder bid to maximize the validator's profit or decrease network censorship at a low or no cost.
Use this option to set the compare factor applied to the builder bid value when comparing it to the locally produced payload. The factor is expressed in a percentage. For example, a builder bid compare factor of 80
means the local payload is chosen when its value is at least 80% of the builder bid value.
Set this option to BUILDER_ALWAYS
to always use the builder bid, unless the bid is invalid.
builder-endpoint
Syntax
--builder-endpoint=<URL>
Example
--builder-endpoint=http://127.0.0.1:18550
Environment variable
TEKU_BUILDER_ENDPOINT=http://127.0.0.1:18550
Configuration file
builder-endpoint: "http://127.0.0.1:18550"
The address for an external builder endpoint.
builder-set-user-agent-header
Syntax
--builder-set-user-agent-header[=<BOOLEAN>]
Example
--builder-set-user-agent-header=true
Environment variable
TEKU_BUILDER_SET_USER_AGENT_HEADER=true
Configuration file
builder-set-user-agent-header: true
Set the User-Agent header to teku/v<version>
(for example, teku/v23.4.0
) when making a builder bid request to help builders identify clients and versions. The default is true
.
config-file
Syntax
--config-file=<FILE>
Example
--config-file=/home/me/me_node/config.yaml
Environment variable
TEKU_CONFIG_FILE=/home/me/me_node/config.yaml
Path to the YAML configuration file. The default is none
.
data-base-path, data-path
Syntax
--data-base-path=<PATH>
Example
--data-base-path=/home/me/me_node
Environment variable
TEKU_DATA_BASE_PATH=/home/me/me_node
Configuration file
data-base-path: "/home/me/me_node"
Path to the Teku data directory. The default directory is OS-dependent:
- macOS:
~/Library/teku
- Unix/Linux:
$XDG_DATA_HOME/teku
if$XDG_DATA_HOME
is set; otherwise~/.local/share/teku
- Windows:
%localappdata%\teku
.
The default Docker image location is /root/.local/share/teku
.
data-beacon-path
Syntax
--data-beacon-path=<PATH>
Example
--data-beacon-path=/home/me/me_beacon
Environment variable
TEKU_DATA_BEACON_PATH=/home/me/me_beacon
Configuration file
data-beacon-path: "/home/me/me_beaon"
Path to the beacon node data. The default is <data-base-path>/beacon
where <data-base-path>
is specified using --data-base-path
.
data-storage-archive-frequency
Syntax
--data-storage-archive-frequency=<NUMBER>
Example
--data-storage-archive-frequency=1028
Environment variable
TEKU_DATA_STORAGE_ARCHIVE_FREQUENCY=1028
Configuration file
data-storage-archive-frequency: 1028
Set the frequency (in slots) at which to store finalized states to disk. The default is 2048.
This option is ignored if --data-storage-mode
is not set to archive
.
Specifying a larger number of slots as the archive frequency has a potentially higher overhead for retrieving finalized states since more states may need to be regenerated to get to the requested state. Specifying a lower number of slots as the frequency increases the disk space usage.
For example, --data-storage-archive-frequency=1
uses maximum disk space but has the lowest response time for retrieving a finalized state since each slot state is saved, whereas --data-storage-archive-frequency=2048
uses less disk space, but may need to regenerate the state because every 2048th slot state is saved.
data-storage-mode
Syntax
--data-storage-mode=<STORAGE_MODE>
Example
--data-storage-mode=archive
Environment variable
TEKU_DATA_STORAGE_MODE=archive
Configuration file
data-storage-mode: "archive"
Set the strategy for handling historical chain data. Valid options are:
minimal
- Stores the minimal required data to follow the chain and run validators. Finalized states and historic blocks are pruned.prune
- Stores all blocks, but finalized states are pruned.archive
- Stores all blocks and states.
The default is minimal
.
data-storage-non-canonical-blocks-enabled
Syntax
--data-storage-non-canonical-blocks-enabled[=<BOOLEAN>]
Example
--data-storage-non-canonical-blocks-enabled=true
Environment variable
TEKU_DATA_STORAGE_NON_CANONICAL_BLOCKS_ENABLED=true
Configuration file
data-storage-non-canonical-blocks-enabled: true
Specify whether to store non-canonical blocks and blob sidecars. The default is false
.
data-validator-path
Syntax
--data-validator-path=<PATH>
Example
--data-validator-path=/home/me/me_validator
Environment variable
TEKU_DATA_VALIDATOR_PATH=/home/me/me_validator
Configuration file
data-validator-path: "/home/me/me_validator"
Path to the validator client data. The default is <data-base-path>/validator
where <data-base-path>
is specified using --data-base-path
.
doppelganger-detection-enabled
Syntax
--doppelganger-detection-enabled[=<BOOLEAN>]
Example
--doppelganger-detection-enabled=true
Environment variable
TEKU_DOPPELGANGER_DETECTION_ENABLED=true
Configuration file
doppelganger-detection-enabled: true
Enables or disables doppelganger detection. The default is false
.
ee-endpoint
Syntax
--ee-endpoint=<URL>
Example
--ee-endpoint=http://localhost:8550
Environment variable
TEKU_EE_ENDPOINT=http://localhost:8550
Configuration file
ee-endpoint: "http://localhost:8550"
URL of the execution client's Engine JSON-RPC APIs. This replaces eth1-endpoint
after The Merge.
ee-jwt-secret-file
Syntax
--ee-jwt-secret-file=<FILE>
Example
--ee-jwt-secret-file=ee-jwt-secret.hex
Environment variable
TEKU_EE_JWT_SECRET_FILE=ee-jwt-secret.hex
Configuration file
ee-jwt-secret-file: "ee-jwt-secret.hex"
Shared secret used to authenticate execution clients when using the Engine JSON-RPC API. Contents of file must be 32 hex-encoded bytes. May be a relative or absolute path. See an example of how to generate this.
eth1-deposit-contract-address
Syntax
--eth1-deposit-contract-address=<ADDRESS>
Example
--eth1-deposit-contract-address=0x77f7bED277449F51505a4C54550B074030d989bC
Environment variable
TEKU_ETH1_DEPOSIT_CONTRACT_ADDRESS=0x77f7bED277449F51505a4C54550B074030d989bC
Configuration file
eth1-deposit-contract-address: "0x77f7bED277449F51505a4C54550B074030d989bC"
The address of the deposit contract. Only required when creating a custom network.
The deposit contract address can also be defined in:
- The genesis file specified using
--initial-state
- The predefined network supplied using
--network
.
eth1-deposit-contract-max-request-size
Syntax
--eth1-deposit-contract-max-request-size=<INTEGER>
Example
--eth1-deposit-contract-max-request-size=8000
Environment variable
TEKU_ETH1_DEPOSIT_CONTRACT_MAX_REQUEST_SIZE=8000
Configuration file
eth1-deposit-contract-max-request-size: 8000
The maximum number of blocks to request deposit contract event logs for in a single request. The default is 10000.
Setting a smaller max size may help if your ETH1 node is slow at loading deposit event logs, or when receiving warnings that the ETH1 node is unavailable.
eth1-endpoint, eth1-endpoints
Syntax
--eth1-endpoint=<URL>[,<URL>...]...
Example
--eth1-endpoint=http://localhost:8545,https://mainnet.infura.io/v3/d0e21ccd0b1e4eef7784422eabc51111
Environment variable
TEKU_ETH1_ENDPOINT=http://localhost:8545,https://mainnet.infura.io/v3/d0e21ccd0b1e4eef7784422eabc51111
Configuration file
eth1-endpoint: ["http://localhost:8545","https://mainnet.infura.io/v3/d0e21ccd0b1e4eef7784422eabc51111"]
Comma-separated list of JSON-RPC URLs of execution layer (Ethereum 1.0) nodes. Each time Teku makes a call, it finds the first provider in the list that is available, on the right chain, and in sync. This option must be specified if running a validator.
If not specified (that is, you're running a beacon node only), then provide an initial state using the --initial-state
option, or start Teku from an existing database using --data-path
, which provides the initial state to work from. You do not need to provide an initial state if running a public network which has already started (for example, Mainnet or Goerli).
If using a cloud-based service such as Infura, then set the endpoint to the supplied URL. For example, https://goerli.infura.io/v3/<Project_ID>
.
After The Merge, you can't use eth1-endpoint
to specify an external execution layer provider. This option is replaced by ee-endpoint
for each beacon node.
deposit-snapshot-enabled
Syntax
--deposit-snapshot-enabled[=<BOOLEAN>]
Example
--deposit-snapshot-enabled=false
Environment variable
TEKU_DEPOSIT_SNAPSHOT_ENABLED=false
Configuration file
deposit-snapshot-enabled: false
Enables or disables using a bundled deposit contract tree snapshot and persisting the tree after finalization. The default is true
.
Normally, at sync, Teku requests all deposit logs from the execution layer up to the head. At each startup, Teku loads all deposits from the disk and replays them to recreate the merkle tree. Both operations consume peer resources and delay node availability on restart. The feature enabled by this option dramatically decreases the time of both operations by bundling deposit tree snapshots in the Teku distribution for all major networks (Mainnet, Gnosis, Goerli, and Sepolia) and persisting the current tree after finalization. Instead of replaying thousands of deposits on startup, Teku loads the bundled tree or a saved one, whichever is the latest.
If a malicious peer changes the bundled tree, Teku throws InvalidDepositEventsException
on the next deposit received
from the execution layer. The malicious peer can't follow up the chain, and so can't propose with an incorrect
deposit tree snapshot.
exchange-capabilities-monitoring-enabled
Syntax
--exchange-capabilities-monitoring-enabled[=<BOOLEAN>]
Example
--exchange-capabilities-monitoring-enabled=true
Environment variable
TEKU_EXCHANGE_CAPABILITIES_MONITORING_ENABLED=true
Configuration file
exchange-capabilities-monitoring-enabled: true
Enables or disables querying the execution client periodically for the Engine API methods it supports. If enabled and incompatibility is detected, a warning is raised in the logs. The default is true
.
genesis-state
Syntax
--genesis-state=<FILE>
Example
--genesis-state=/home/me/genesis.ssz
Environment variable
TEKU_GENESIS_STATE=/home/me/genesis.ssz
Configuration file
genesis-state: "/home/me/genesis.ssz"
Path or URL to an SSZ-encoded state file. The state file can be used to specify the genesis state, or a recent finalized checkpoint state from which to sync.
This option does not need to be specified if the genesis state is provided by the network specified using the --network
option. It also is not required if the Reconstruct Historical States Service is not being utilised.
If overriding the genesis state in a custom network, you must supply the genesis state file at each restart.
Infura can be used as the source of initial states with --genesis-state https://{projectid}:{secret}@eth2-beacon-mainnet.infura.io/eth/v2/debug/beacon/states/genesis
help
-h, --help
Show the help message and exit.
initial-state
Syntax
--initial-state=<FILE>
Example
--initial-state=/home/me/genesis.ssz
Environment variable
TEKU_INITIAL_STATE=/home/me/genesis.ssz
Configuration file
initial-state: "/home/me/genesis.ssz"
Path or URL to an SSZ-encoded state file. The state file can be used to specify the genesis state, or a recent finalized checkpoint state from which to sync.
This option does not need to be specified if the genesis state is provided by the network specified using the --network
option.
If overriding the initial state in a custom network, you must supply the initial state file at each restart.
checkpoint-sync-url
Syntax
--checkpoint-sync-url=<URL>
Example
--checkpoint-sync-url="https://beaconstate.ethstaker.cc"
Environment variable
TEKU_CHECKPOINT_SYNC_URL="https://beaconstate.ethstaker.cc"
Configuration file
checkpoint-sync-url: "https://beaconstate.ethstaker.cc"
URL of a Checkpointz endpoint used to start Teku from a recent state.
By default, Teku tries to download the finalized state from the endpoint. If it can't download the finalized state, it tries to download the genesis state.
logging
Syntax
-l, --logging=<LEVEL>
Example
--logging=DEBUG
Environment variable
TEKU_LOGGING=DEBUG
Configuration file
logging: "DEBUG"
Sets the logging verbosity. Log levels are OFF
, FATAL
, ERROR
, WARN
, INFO
, DEBUG
, TRACE
, ALL
. Default is INFO
.
log-color-enabled
Syntax
--log-color-enabled[=<BOOLEAN>]
Example
--log-color-enabled=false
Environment variable
TEKU_LOG_COLOR_ENABLED=false
Configuration file
log-color-enabled: false
Specify whether status and event log messages include a console color display code. The default is true
.
log-destination
Syntax
--log-destination=<LOG_DESTINATION>
Example
--log-destination=CONSOLE
Environment variable
TEKU_LOG_DESTINATION=CONSOLE
Configuration file
log-destination: "CONSOLE"
Specify where to output log information. Valid options are:
BOTH
CONSOLE
DEFAULT_BOTH
FILE
The default is DEFAULT_BOTH
. When using BOTH
or DEFAULT_BOTH
, system updates such as blockchain events are displayed on the console, and errors and other information are logged to a file. Specify the log file with the --log-file
command-line option.
For production systems we recommend using the CONSOLE
or FILE
options to ensure all log information is available in one place.
Use DEFAULT_BOTH
when using a custom Log4J2 configuration file. Any other option applies the custom logging changes on top of its default settings.
log-file
Syntax
--log-file=<FILENAME>
Example
--log-file=teku_2020-01-01.log
Environment variable
TEKU_LOG_FILE=teku_2020-01-01.log
Configuration file
log-file: "teku_2020-01-01.log"
Relative or absolute location, and filename of the log file.
The default directory is OS-dependent:
- macOS:
~/Library/teku/logs
- Unix/Linux:
$XDG_DATA_HOME/teku/logs
if$XDG_DATA_HOME
is set; otherwise~/.local/share/teku/logs
- Windows:
%localappdata%\teku\logs
The default Docker image location is /root/.local/share/teku/logs
.
log-file-name-pattern
Syntax
--log-file-name-pattern=<REGEX>
Example
--log-file-name-pattern=tekuL_%d{yyyy-MM-dd}.log
Environment variable
TEKU_LOG_FILE_NAME_PATTERN=tekuL_%d{yyyy-MM-dd}.log
Configuration file
log-file-name-pattern: "tekuL_%d{yyyy-MM-dd}.log"
Filename pattern to apply when creating log files. The default pattern is teku_%d{yyyy-MM-dd}.log
log-include-events-enabled
Syntax
--log-include-events-enabled[=<BOOLEAN>]
Example
--log-include-events-enabled=false
Environment variable
TEKU_LOG_INCLUDE_EVENTS_ENABLED=false
Configuration file
log-include-events-enabled: false
Specify whether to log frequent update events. For example every slot event with validators and attestations. The default is true
.
log-include-validator-duties-enabled
Syntax
--log-include-validator-duties-enabled[=<BOOLEAN>]
Example
--log-include-validator-duties-enabled=false
Environment variable
TEKU_LOG_INCLUDE_VALIDATOR_DUTIES_ENABLED=false
Configuration file
log-include-validator-duties-enabled: false
Specify whether to log details of validator event duties. The default is true
.
Logs could become noisy when running many validators.
metrics-block-timing-tracking-enabled
Syntax
--metrics-block-timing-tracking-enabled[=<BOOLEAN>]
Example
--metrics-block-timing-tracking-enabled=false
Environment variable
TEKU_METRICS_BLOCK_TIMING_TRACKING_ENABLED=false
Configuration file
metrics-block-timing-tracking-enabled: false
Enables or disables block timing metrics. The default is true
.
metrics-enabled
Syntax
--metrics-enabled[=<BOOLEAN>]
Example
--metrics-enabled=true
Environment variable
TEKU_METRICS_ENABLED=true
Configuration file
metrics-enabled: true
Set to true
to enable the metrics exporter. The default is false
.
metrics-host-allowlist
Syntax
--metrics-host-allowlist=<hostname>[,<hostname>...]... or "*"
Example
--metrics-host-allowlist=medomain.com,meotherdomain.com
Environment variable
TEKU_METRICS_HOST_ALLOWLIST=medomain.com,meotherdomain.com
Configuration file
metrics-host-allowlist: ["medomain.com", "meotherdomain.com"]
A comma-separated list of hostnames to allow access to the Teku metrics. By default, Teku accepts access from localhost
and 127.0.0.1
.
To allow all hostnames, use "*"
. We don't recommend allowing all hostnames for production environments.
metrics-categories
Syntax
--metrics-categories=<CATEGORY>[,<CATEGORY>...]...
Example
--metrics-categories=BEACON,JVM,PROCESS
Environment variable
TEKU_METRICS_CATEGORIES=BEACON,JVM,PROCESS
Configuration file
metrics-categories: ["BEACON", "JVM", "PROCESS"]
Categories for which to track metrics. Options are JVM
, PROCESS
, BEACON
, DISCOVERY
, EVENTBUS
, EXECUTOR
, LIBP2P
, NETWORK
, STORAGE
, STORAGE_HOT_DB
, STORAGE_FINALIZED_DB
, REMOTE_VALIDATOR
, VALIDATOR
, VALIDATOR_PERFORMANCE
. All categories are enabled by default.
metrics-interface
Syntax
--metrics-interface=<HOST>
Example
--metrics-interface=192.168.10.101
Environment variable
TEKU_METRICS_INTERFACE=192.168.10.101
Configuration file
metrics-interface: "192.168.10.101"
Host on which Prometheus accesses Teku metrics. The default is 127.0.0.1
.
metrics-port
Syntax
--metrics-port=<PORT>
Example
--metrics-port=6174
Environment variable
TEKU_METRICS_PORT=6174
Configuration file
metrics-port: 6174
Specifies the port (TCP) on which Prometheus accesses Teku metrics. The default is 8008
.
metrics-publish-endpoint
Syntax
--metrics-publish-endpoint=<URL>
Example
--metrics-publish-endpoint=https://beaconcha.in/api/v1/client/metrics?apikey={apikey}
Environment variable
TEKU_METRICS_PUBLISH_ENDPOINT=https://beaconcha.in/api/v1/client/metrics?apikey={apikey}
Configuration file
metrics-publish-endpoint: "https://beaconcha.in/api/v1/client/metrics?apikey={apikey}"
Endpoint URL of an external service such as beaconcha.in to which Teku publishes metrics for node monitoring.
metrics-publish-interval
Syntax
--metrics-publish-interval=<INTEGER>
Example
--metrics-publish-interval=60
Environment variable
TEKU_METRICS_PUBLISH_INTERVAL=60
Configuration file
metrics-publish-interval: "60"
Interval between metric publications to the external service defined in metrics-publish-endpoint, measured in seconds. The default is 60
.
network
Syntax
--network=<NETWORK>
Example
--network=mainnet
Environment variable
TEKU_NETWORK=mainnet
Configuration file
network: "mainnet"
Predefined network configuration. Accepts a predefined network name, or file path or URL to a YAML configuration file. See the consensus specification for examples.
The default is mainnet
.
Possible values are:
Network | Chain | Type | Description |
---|---|---|---|
mainnet | Consensus layer | Production | Main network |
minimal | Consensus layer | Test | Used for local testing and development networks |
goerli | Consensus layer | Test | Multi-client testnet |
gnosis | Consensus layer | Production | Network for the Gnosis chain |
holesky | Consensus layer | Test | Multi-client testnet |
sepolia | Consensus layer | Test | Multi-client testnet |
chiado | Consensus layer | Test | Gnosis testnet |
lukso | Consensus layer | Production | Network for the Lukso chain |
Predefined networks can provide defaults such as the initial state of the network, bootnodes, and the address of the deposit contract.
p2p-advertised-ip
Syntax
--p2p-advertised-ip=<IP_ADDRESS>
Example
--p2p-advertised-ip=192.168.1.132
Environment variable
TEKU_P2P_ADVERTISED_IP=192.168.1.132
Configuration file
p2p-advertised-ip: "192.168.1.132"
Advertised peer-to-peer IP address. The default is 127.0.0.1
.
p2p-enabled
Syntax
--p2p-enabled[=<BOOLEAN>]
Example
--p2p-enabled=false
Environment variable
TEKU_P2P_ENABLED=false
Configuration file
p2p-enabled: false
Enables or disables all P2P communication. The default is true
.
p2p-interface
Syntax
--p2p-interface=<HOST>
Example
--p2p-interface=192.168.1.132
Environment variable
TEKU_P2P_INTERFACE=192.168.1.132
Configuration file
p2p-interface: "192.168.1.132"
Specifies the network interface on which the node listens for P2P communication. The default is 0.0.0.0
(all interfaces).
p2p-nat-method
Syntax
--p2p-nat-method=<STRING>
Example
--p2p-nat-method=UPNP
Environment variable
TEKU_P2P_NAT_METHOD=UPNP
Configuration file
p2p-nat-method: "UPNP"
Specify the method for handling NAT environments. Valid options are NONE
and UPNP
.
The default is NONE
, which disables NAT functionality.
UPnP support is often disabled by default in networking firmware. If disabled by default, explicitly enable UPnP support.
p2p-peer-lower-bound
Syntax
--p2p-peer-lower-bound=<INTEGER>
Example
--p2p-peer-lower-bound=25
Environment variable
TEKU_P2P_PEER_LOWER_BOUND=25
Configuration file
p2p-peer-lower-bound: 25
Lower bound on the target number of peers. Teku will actively seek new peers if the number of peers falls below this value. The default is 64
.
p2p-peer-upper-bound
Syntax
--p2p-peer-upper-bound=<INTEGER>
Example
--p2p-peer-upper-bound=40
Environment variable
TEKU_P2P_PEER_UPPER_BOUND=40
Configuration file
p2p-peer-upper-bound: 40
Upper bound on the target number of peers. Teku will refuse new peer requests that would cause the number of peers to exceed this value. The default is 100
.
p2p-port
Syntax
--p2p-port=<PORT>
Example
# to listen on port 1789
--p2p-port=1789
Environment variable
# to listen on port 1789
TEKU_P2P_PORT=1789
Configuration file
p2p-port: 1789
Specifies the P2P listening ports (UDP and TCP). The default is 9000
.
p2p-discovery-enabled
Syntax
--p2p-discovery-enabled[=<BOOLEAN>]
Example
--p2p-discovery-enabled=false
Environment variable
TEKU_P2P_DISCOVERY_ENABLED=false
Configuration file
p2p-discovery-enabled: false
Enables or disables P2P peer discovery. If disabled, p2p-static-peers
defines the peer connections. The default is true
.
p2p-discovery-site-local-addresses-enabled
Syntax
--p2p-discovery-site-local-addresses-enabled[=<BOOLEAN>]
Example
--p2p-discovery-site-local-addresses-enabled
Environment variable
TEKU_P2P_DISCOVERY_SITE_LOCAL_ADDRESSES_ENABLED=true
Configuration file
p2p-discovery-site-local-addresses-enabled: true
Enables or disables discovery of the following local network (RFC1918) addresses. The default is false
.
10.0.0.0 - 10.255.255.255 (10/8 prefix)
172.16.0.0 - 172.31.255.255 (172.16/12 prefix)
192.168.0.0 - 192.168.255.255 (192.168/16 prefix)
Normal Teku operation shouldn't send traffic to these local network addresses.
In test or private networks, operators might need to enable discovery of local addresses. For example, when you run multiple consensus layer nodes in one local network, these nodes are not discovered on the public internet and are advertised with local (RFC1918) addresses.
p2p-discovery-bootnodes
Syntax
--p2p-discovery-bootnodes=<ENR_ADDRESS>[,<ENR_ADDRESS>...]...
Example
--p2p-discovery-bootnodes=enr:-Iu4QG...wgiMo,enr:-Iu4QL...wgiMo
Environment variable
TEKU_P2P_DISCOVERY_BOOTNODES=enr:-Iu4QG...wgiMo,enr:-Iu4QL...wgiMo
Configuration file
p2p-discovery-bootnodes: ["enr:-Iu4QG...wgiMo",
"enr:-Iu4QL...wgiMo"]
List of comma-separated Ethereum Node Records (ENRs) for P2P discovery bootstrap.
p2p-advertised-port
Syntax
--p2p-advertised-port=<PORT>
Example
--p2p-advertised-port=1789
Environment variable
TEKU_P2P_ADVERTISED_PORT=1789
Configuration file
p2p-advertised-port: 1789
The advertised P2P port. The default is the port specified in --p2p-port
.
The advertised port can differ from the --p2p-port
. For example, you can set the advertised port to 9010, and the --p2p-port
value to 9009, then manually configure the firewall to forward external incoming requests on port 9010 to port 9009 on the Teku node.
p2p-udp-port
Syntax
--p2p-udp-port=<PORT>
Example
--p2p-udp-port=1789
Environment variable
TEKU_P2P_UDP_PORT=1789
Configuration file
p2p-udp-port: 1789
The UDP port used for discovery. The default is the port specified in --p2p-port
.
p2p-advertised-udp-port
Syntax
--p2p-advertised-udp-port=<PORT>
Example
--p2p-advertised-udp-port=1789
Environment variable
TEKU_P2P_ADVERTISED_UDP_PORT=1789
Configuration file
p2p-advertised-udp-port: 1789
The advertised UDP port to external peers. The default is the port specified in --p2p-advertised-port
if it is set. Otherwise, the default is the port specified in --p2p-port
.
p2p-private-key-file
Syntax
--p2p-private-key-file=<PATH_TO_FILE>
Example
--p2p-private-key-file=/home/me/me_node/key
Environment variable
TEKU_P2P_PRIVATE_KEY_FILE=/home/me/me_node/key
Configuration file
p2p-private-key-file: "/home/me/me_node/key"
File containing the node's private key.
p2p-static-peers
Syntax
--p2p-static-peers=<ADDRESS>[,<ADDRESS>...]...
Example
--p2p-static-peers=/ip4/151.150.191.80/tcp/9000/p2p/16Ui...aXRz,/ip4/151.150.191.80/tcp/9000/p2p/16Ui...q6f1
Environment variable
TEKU_P2P_STATIC_PEERS=/ip4/151.150.191.80/tcp/9000/p2p/16Ui...aXRz,/ip4/151.150.191.80/tcp/9000/p2p/16Ui...q6f1
Configuration file
p2p-static-peers: ["/ip4/151.150.191.80/tcp/9000/p2p/16Ui...aXRz",
"/ip4/151.150.191.80/tcp/9000/p2p/16Ui...q6f1"]
List of comma-separated multiaddresses of static peers.
p2p-subscribe-all-subnets-enabled
Syntax
--p2p-subscribe-all-subnets-enabled=<BOOLEAN>
Example
--p2p-subscribe-all-subnets-enabled=true
Environment variable
TEKU_P2P_SUBSCRIBE_ALL_SUBNETS_ENABLED=true
Configuration file
p2p-subscribe-all-subnets-enabled: true
Forces the beacon node to stay subscribed to all subnets regardless of the number of validators. The default is false
.
When set to false
, Teku subscribes to two persistent subnets regardless of the number of validators. Teku also subscribes and unsubscribes from subnets as needed for the running validators.
This option is primarily for users running an external validator client and load balancing it across multiple beacon nodes. Without this flag, depending on how requests are load balanced, the beacon nodes may not have subscribed to the required subnets and be unable to produce aggregates.
When set to true
, Teku uses more CPU and bandwidth, and for most users there’s no need to use this option.
reconstruct-historic-states
Syntax
--reconstruct-historic-states=<BOOLEAN>
Example
--reconstruct-historic-states=true
Environment variable
TEKU_RECONSTRUCT_HISTORIC_STATES=true
Configuration file
reconstruct-historic-states: true
When set to true
the Reconstruct Historical States Service, is enabled where an archive node is able to reconstruct historical states from genesis up to the current checkpoint, running during start up.
When set to false
this service is not enabled.
rest-api-cors-origins
Syntax
--rest-api-cors-origins[=<url>[,<url>...]...] or "*"
Example
--rest-api-cors-origins="http://medomain.com","https://meotherdomain.com"
Environment variable
TEKU_REST_API_CORS_ORIGINS="http://medomain.com","https://meotherdomain.com"
Configuration file
rest-api-cors-origins: ["http://medomain.com","https://meotherdomain.com"]
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 HTTP REST API calls. If your client interacts with Teku using a browser app (such as a block explorer), add the client domain to the list.
The default is "none." If you don't list any domains, browser apps can't interact with your Teku node.
For testing and development purposes, use *
to accept requests from any domain. We don’t recommend accepting requests from any domain for production environments.
rest-api-docs-enabled
Syntax
--rest-api-docs-enabled[=<BOOLEAN>]
Example
--rest-api-docs-enabled=true
Environment variable
TEKU_REST_API_DOCS_ENABLED=true
Configuration file
rest-api-docs-enabled: true
Set to true
to enable the REST API documentation. The default is false
.
The documentation can be accessed at http://<interface>:<port>/swagger-ui
where:
interface
is specified using--rest-api-interface
port
is specified using--rest-api-port
rest-api-enabled
Syntax
--rest-api-enabled[=<BOOLEAN>]
Example
--rest-api-enabled=true
Environment variable
TEKU_REST_API_ENABLED=true
Configuration file
rest-api-enabled: true
Set to true
to enable the REST API service. The default is false
.
If set to true
, then use --rest-api-host-allowlist
to limit access to trusted parties.
rest-api-host-allowlist
Syntax
--rest-api-host-allowlist=<hostname>[,<hostname>...]... or "*"
Example
--rest-api-host-allowlist=medomain.com,meotherdomain.com
Environment variable
TEKU_REST_API_HOST_ALLOWLIST=medomain.com,meotherdomain.com
Configuration file
rest-api-host-allowlist: ["medomain.com", "meotherdomain.com"]
A comma-separated list of hostnames to allow access to the REST API. By default, Teku accepts access from localhost
and 127.0.0.1
.
Only trusted parties should access the REST API. Do not directly expose these APIs publicly on production nodes.
We don't recommend allowing all hostnames ("*"
) for production environments.
rest-api-interface
Syntax
--rest-api-interface=<HOST>
Example
# to listen on all interfaces
--rest-api-interface=0.0.0.0
Environment variable
TEKU_REST_API_INTERFACE=0.0.0.0
Configuration file
rest-api-interface: "0.0.0.0"
Specifies the interface on which the REST API listens. The default is 127.0.0.1
.
rest-api-port
Syntax
--rest-api-port=<PORT>
Example
# to listen on port 3435
--rest-api-port=3435
Environment variable
TEKU_REST_API_PORT=3435
Configuration file
rest-api-port: 3435
Specifies REST API listening port (HTTP). The default is 5051.
sentry-config-file
Syntax
--sentry-config-file=<FILE>
Example
--sentry-config-file=/etc/sentry-node-config.json
Environment variable
TEKU_SENTRY-CONFIG_FILE=/etc/sentry-node-config.json
Path to the sentry node configuration file. The default is none
.
This option can't be used with --beacon-node-api-endpoint
.
version
-V, --version
Displays the version and exits.
validator-api-cors-origins
Syntax
--validator-api-cors-origins="<URL>"[,"<URL>",...] or "*"
Example
--validator-api-cors-origins="http://medomain.com","https://meotherdomain.com"
Environment variable
TEKU_VALIDATOR_API_CORS_ORIGINS="http://medomain.com","https://meotherdomain.com"
Configuration file
validator-api-cors-origins: ["http://medomain.com","https://meotherdomain.com"]
A comma-separated list of domain URLs for CORS validation.
Listed domains can access the node using validator API calls. If your client interacts with Teku using a browser app (such as a block explorer), add the client domain to the list.
The default is "none." If you don't list any domains, browser apps can't interact with your Teku node.
For testing and development purposes, use *
to accept requests from any domain. We don’t recommend accepting requests from any domain for production environments.
validator-api-docs-enabled
Syntax
--validator-api-docs-enabled[=<BOOLEAN>]
Example
--validator-api-docs-enabled=true
Environment variable
TEKU_VALIDATOR_API_DOCS_ENABLED=true
Configuration file
validator-api-docs-enabled: true
Set to true
to enable the validator REST API documentation. The default is false
.
When enabling the API documentation endpoint, you must also specify:
interface
by using--validator-api-interface
.port
by using--validator-api-port
.
validator-api-enabled
Syntax
--validator-api-enabled[=<BOOLEAN>]
Example
--validator-api-enabled=true
Environment variable
TEKU_VALIDATOR_API_ENABLED=true
Configuration file
validator-api-enabled: true
Set to true
to enable the validator client API. The default is false
.
If set to true
, then use --validator-api-host-allowlist
to limit access to trusted parties.
validator-api-host-allowlist
Syntax
--validator-api-host-allowlist=<hostname>[,<hostname>...]... or "*"
Example
--validator-api-host-allowlist=medomain.com,meotherdomain.com
Environment variable
TEKU_VALIDATOR_API_HOST_ALLOWLIST=medomain.com,meotherdomain.com
Configuration file
validator-api-host-allowlist: ["medomain.com", "meotherdomain.com"]
A comma-separated list of hostnames to allow access to the validator REST API. By default, Teku accepts access from localhost
and 127.0.0.1
.
Only trusted parties should access the API. Do not directly expose these APIs publicly on production nodes.
We don't recommend allowing all hostnames ("*"
) for production environments.
validator-api-interface
Syntax
--validator-api-interface=<HOST>
Example
# to listen on all interfaces
--validator-api-interface=0.0.0.0
Environment variable
TEKU_VALIDATOR_API_INTERFACE=0.0.0.0
Configuration file
validator-api-interface: "0.0.0.0"
The interface on which the validator REST API listens. The default is 127.0.0.1
.
validator-api-keystore-file
Syntax
--validator-api-keystore-file=<keystoreFile>
Example
--validator-api-keystore-file=validator_keystorstore.p12
Environment variable
TEKU_VALIDATOR_API_KEYSTORE_FILE=validator_keystore.p12
Configuration file
validator-api-keystore-file: "validator_keystore.p12"
Keystore file for the validator REST API. Teku can use PKCS12 or JKS keystore types. You must create a keystore to enable access.
validator-api-keystore-password-file
Syntax
--validator-api-keystore-password-file=<keystorePasswordFile>
Example
--validator-api-keystore-password-file=validator_keystore_pass.txt
Environment variable
TEKU_VALIDATOR_API_KEYSTORE_PASSWORD_FILE=validator_keystore_pass.txt
Configuration file
validator-api-keystore-password-file: "validator_keystore_pass.txt"
Password used to decrypt the keystore for the validator REST API.
validator-api-port
Syntax
--validator-api-port=<PORT>
Example
--validator-api-port=5052
Environment variable
TEKU_VALIDATOR_API_PORT=5052
Configuration file
validator-api-port: 5052
The validator REST API listening port (HTTP). The default is 5052.
validator-keys
Syntax
--validator-keys=<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>[,<KEY_DIR>:<PASS_DIR> | <KEY_FILE>:<PASS_FILE>...]...
Example for directory
--validator-keys=/home/validator/keys:home/validator/passwords
Example for file
--validator-keys=/home/validator/keys/validator_217179e.json:/home/validator/passwords/validator_217179e.txt
Environment variable
TEKU_VALIDATOR_KEYS=/home/validator/keys:home/validator/passwords
Configuration file
validator-keys: "/home/validator/keys:home/validator/passwords"
Directory or file to load the encrypted keystore file(s) and associated password file(s) from. Keystore files must use the .json
file extension, and password files must use the .txt
file extension.
When specifying directories, Teku expects to find identically named keystore and password files. For example validator_217179e.json
and validator_217179e.txt
.
You can load new validators without restarting Teku if you specify a directory from which to load the keystore files.
When specifying file names, Teku expects that the files exist.
The path separator is operating system dependent, and should be ;
in Windows rather than :
.
validators-builder-registration-default-enabled
Syntax
--validators-builder-registration-default-enabled[=<BOOLEAN>]
Example
--validators-builder-registration-default-enabled=true
Environment variable
TEKU_VALIDATORS_BUILDER_REGISTRATION_DEFAULT_ENABLED=true
Configuration file
validators-builder-registration-default-enabled: true
Set to true
to have all validators managed by the validator client register to the builder endpoint when proposing a block.
validators-early-attestations-enabled
Syntax
--validators-early-attestations-enabled[=<BOOLEAN>]
Example
--validators-early-attestations-enabled=false
Environment variable
TEKU_VALIDATORS_EARLY_ATTESTATIONS_ENABLED=false
Configuration file
validators-early-attestations-enabled: false
Specify whether to use Teku's built-in early attestation production, which creates an attestation as soon as a block is received. The default is true
.
Set this option to false
if running a validator client connected to a load balanced beacon node (including most hosted beacon nodes such as Infura), and validator effectiveness is poor.
Delaying attestation production increases the chances of generating a correct attestation when using a load balanced beacon node, but it increases the risk of inclusion delays.
validators-external-signer-keystore
Syntax
--validators-external-signer-keystore=<FILE>
Example
--validators-external-signer-keystore=teku_client_keystore.p12
Environment variable
TEKU_VALIDATORS_EXTERNAL_KEYSTORE=teku_client_keystore.p12
Configuration file
validators-external-signer-keystore: "teku_client_keystore.p12"
The keystore that Teku presents to the external signer for TLS authentication. Teku can use PKCS12 or JKS keystore types.
Use the PKCS12 keystore type if connecting to Web3Signer.
validators-external-signer-keystore-password-file
Syntax
--validators-external-signer-keystore-password-file=<FILE>
Example
--validators-external-signer-keystore-password-file=keystore_pass.txt
Environment variable
TEKU_VALIDATORS_EXTERNAL_KEYSTORE_PASSWORD_FILE=keystore_pass.txt
Configuration file
validators-external-signer-keystore-password-file: "keystore_pass.txt"
Password file used to decrypt the keystore.
validators-external-signer-public-keys
Syntax
--validators-external-signer-public-keys=<KEY>[,<KEY>...]
Example
--validators-external-signer-public-keys=0xa99a...e44c,0xb89b...4a0b
Environment variable
TEKU_VALIDATORS_EXTERNAL_SIGNER_PUBLIC_KEYS=0xa99a...e44c,0xb89b...4a0b
Configuration file
validators-external-signer-public-keys: ["0xa99a...e44c","0xb89b...4a0b"]
List or URL of validator public keys used by an external signer (for example, Web3Signer).
Use the URL to load the public keys from a remote service. For example:
--validators-external-signer-public-keys=http://localhost:9900/api/v1/eth2/publicKeys
Use the value external-signer
to load all public keys managed by the external signer. Teku automatically queries the external signer's public keys endpoint.
--validators-external-signer-public-keys=external-signer
You can load new validators without restarting Teku if you specify a URL from which to load the public keys.
Ensure the external signer is running before starting Teku.
validators-external-signer-slashing-protection-enabled
Syntax
--validators-external-signer-slashing-protection-enabled[=<BOOLEAN>]
Example
--validators-external-signer-slashing-protection-enabled=false
Environment variable
TEKU_VALIDATORS_EXTERNAL_SIGNER_SLASHING_PROTECTION_ENABLED=false
Configuration file
validators-external-signer-slashing-protection-enabled: false
Specify whether to use Teku's built-in slashing protection when using an external signer such as Web3Signer. The default is true
.
Set this option to false
if using the slashing protection implemented by an external signer.
Ensure the external signer has slashing protection enabled before disabling Teku slashing protection, otherwise a validator may get slashed.
Built-in slashing protection can only be disabled for validators using external signers. Validators using Teku to sign blocks and attestations always uses its built-in slashing protection.
validators-external-signer-timeout
Syntax
--validators-external-signer-timeout=<INTEGER>
Example
--validators-external-signer-timeout=2000
Environment variable
TEKU_VALIDATORS_EXTERNAL_SIGNER_TIMEOUT=2000
Configuration file
validators-external-signer-timeout: 2000
Timeout in milliseconds for requests to the external signer. The default is 5000.
validators-external-signer-truststore
Syntax
--validators-external-signer-truststore=<FILE>
Example
--validators-external-signer-truststore=websigner_truststore.p12
Environment variable
TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE=websigner_truststore.p12
Configuration file
validators-external-signer-truststore: "websigner_truststore.p12"
PKCS12 or JKS keystore used to trust external signer's self-signed certificate or CA certificate which signs the external signer's certificate.
validators-external-signer-truststore-password-file
Syntax
--validators-external-signer-truststore-password-file=<FILE>
Example
--validators-external-signer-truststore-password-file=truststore_pass.txt
Environment variable
TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE_PASSWORD_FILE=truststore_pass.txt
Configuration file
validators-external-signer-truststore-password-file: "truststore_pass.txt"
Password file used to decrypt the keystore.
validators-external-signer-url
Syntax
--validators-external-signer-url=<URL>
Example
--validators-external-signer-url=http://localhost:9000
Environment variable
TEKU_VALIDATORS_EXTERNAL_SIGNER_URL=http://localhost:9000
Configuration file
validators-external-signer-url: "http://localhost:9000"
URL on which the external signer (for example, Web3Signer) is running.
validators-graffiti
Syntax
--validators-graffiti=<STRING>
Example
--validators-graffiti="Teku validator"
Environment variable
TEKU_VALIDATORS_GRAFFITI="Teku validator"
Configuration file
validators-graffiti: "Teku validator"
Graffiti to add when creating a block. Gets converted to bytes and padded to Bytes32.
The same graffiti is used for all validators started with this beacon node.
--validators-graffiti-file
takes precedence if both options are set.
validators-graffiti-file
Syntax
--validators-graffiti-file=<FILE>
Example
--validators-graffiti-file=/Users/me/mynode/graffiti.txt
Environment variable
TEKU_VALIDATORS_GRAFFITI_FILE=/Users/me/mynode/graffiti.txt
Configuration file
validators-graffiti-file: "/Users/me/mynode/graffiti.txt"
File containing the validator graffiti to add when creating a block. The file contents is converted to bytes
and padded to Bytes32
. The same graffiti is used for all validators started with this beacon node.
You can overwrite the file while Teku is running to update the graffiti.
This option takes precedence over --validators-graffiti
.
validators-keystore-locking-enabled
Syntax
--validators-keystore-locking-enabled=<BOOLEAN>
Example
--validators-keystore-locking-enabled=true
Environment variable
TEKU_VALIDATORS_KEYSTORE_LOCKING_ENABLED=true
Configuration file
validators-keystore-locking-enabled: true
Locks the keystore files listed in --validator-keys
. The default is true
.
Attempts to lock all keystores in a directory if a directory is specified in --validator-keys
.
validators-performance-tracking-mode
Syntax
--validators-performance-tracking-mode=<STRING>
Example
--validators-performance-tracking-mode=LOGGING
Environment variable
TEKU_VALIDATORS_PERFORMANCE_TRACKING_MODE=LOGGING
Configuration file
validators-performance-tracking-mode: LOGGING
Set the validator performance tracking strategy. Valid options are LOGGING
, METRICS
, ALL
, and NONE
. The default is ALL
.
When LOGGING
is enabled, attestation and block performance is reported as log messages. When METRICS
is enabled, attestation and block performance is reported using metrics in the VALIDATOR_PERFORMANCE
metrics category.
validators-proposer-blinded-blocks-enabled
Syntax
--validators-proposer-blinded-blocks-enabled[=<BOOLEAN>]
Example
--validators-proposer-blinded-blocks-enabled=true
Environment variable
TEKU_VALIDATORS_PROPOSER_BLINDED_BLOCKS_ENABLED=true
Configuration file
validators-proposer-blinded-blocks-enabled: true
Set to true
to enable blinded blocks production, a prerequisite for the builder network. When --validators-builder-registration-default-enabled
is enabled this option is enabled automatically. The default is false
.
validators-proposer-config
Syntax
--validators-proposer-config=<STRING>
Example
--validators-proposer-config=/home/me/node/proposerConfig.json
Environment variable
TEKU_VALIDATORS_PROPOSER_CONFIG=/home/me/node/proposerConfig.json
Configuration file
validators-proposer-config: "/home/me/node/proposerConfig.json"
Remote URL or local file path to the proposer configuration file.
validators-proposer-config-refresh-enabled
Syntax
--validators-proposer-config-refresh-enabled[=<BOOLEAN>]
Example
--validators-proposer-config-refresh-enabled=true
Environment variable
TEKU_VALIDATORS_PROPOSER_CONFIG_REFRESH_ENABLED=true
Configuration file
validators-proposer-config-refresh-enabled: true
Set to true
to enable reloading the proposer configuration on every proposer preparation (once per epoch). The default is false
.
validators-proposer-default-fee-recipient
Syntax
--validators-proposer-default-fee-recipient=<ADDRESS>
Example
--validators-proposer-default-fee-recipient=0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73
Environment variable
TEKU_VALIDATORS_PROPOSER_DEFAULT_FEE_RECIPIENT=0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73
Configuration file
validators-proposer-default-fee-recipient: "0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"
Default recipient of transaction fees for all validator keys. When running a validator, this is an alternative to the fee_recipient
in the default proposer configuration.
We recommend using this option when running a beacon node serving APIs to other validator clients.
The specified fee recipient is used in rare cases when a validator requests a block production but its fee recipient is still unknown for the beacon node.
ws-checkpoint
Syntax
--ws-checkpoint=<BLOCK_ROOT>:<EPOCH_NUMBER>
Example
--ws-checkpoint=0x5a642bb8f367e98c0d11426d98d28c465f8988fc960500886cb49faf0372883a:3600
Environment variable
TEKU_WS_CHECKPOINT=0x5a642bb8f367e98c0d11426d98d28c465f8988fc960500886cb49faf0372883a:3600
Configuration file
ws-checkpoint: "0x5a642bb8f367e98c0d11426d98d28c465f8988fc960500886cb49faf0372883a:3600"
A recent checkpoint within the weak subjectivity period. Accepts the checkpoint using <blockRoot>:<epochNumber>
, where <blockRoot>
must start with 0x
.
The weak subjectivity checkpoint is a recent, finalized checkpoint on the correct chain. By supplying a weak subjectivity checkpoint, you ensure that nodes that have been offline for a long period follow the correct chain. It protects the node from long-range attacks by malicious actors.
Use the admin weak-subjectivity
subcommand to display or clear your weak subjectivity settings.