Version: 23.10.0

Teku command line options

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

caution

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.

note

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

caution

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.

Security considerations

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.

note

If overriding the genesis state in a custom network, you must supply the genesis state file at each restart.

tip

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

Syntax

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

note

If overriding the initial state in a custom network, you must supply the initial state file at each restart.

tip

See this community-maintained list of checkpoint state endpoints.

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.

note

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.

note

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.

tip

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.

tip

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.

0.0.0    	-   10.255.255.255  (10/8 prefix)
16.0.0  	-   172.31.255.255  (172.16/12 prefix)
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.

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.

caution

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.

tip

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.

warning

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.

caution

This option can't be used with --beacon-node-api-endpoint.

version

Syntax

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

tip

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.

warning

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.

tip

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.

note

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.

note

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

tip

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.

warning

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.

tip

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.

Teku command line options

Specify options​

Using autocomplete​

Options​

beacon-liveness-tracking-enabled​

Syntax

Example

Environment variable

Configuration file

builder-bid-compare-factor​

Syntax

Example

Environment variable

Configuration file

builder-endpoint​

Syntax

Example

Environment variable

Configuration file

builder-set-user-agent-header​

Syntax

Example

Environment variable

Configuration file

config-file​

Syntax

Example

Environment variable

data-base-path, data-path​

Syntax

Example

Environment variable

Configuration file

data-beacon-path​

Syntax

Example

Environment variable

Configuration file

data-storage-archive-frequency​

Syntax

Example

Environment variable

Configuration file

data-storage-mode​

Syntax

Example

Environment variable

Configuration file

data-storage-non-canonical-blocks-enabled​

Syntax

Example

Environment variable

Configuration file

data-validator-path​

Syntax

Example

Environment variable

Configuration file

doppelganger-detection-enabled​

Syntax

Example

Environment variable

Configuration file

ee-endpoint​

Syntax

Example

Environment variable

Configuration file

ee-jwt-secret-file​

Syntax

Example

Environment variable

Configuration file

eth1-deposit-contract-address​

Syntax

Example

Environment variable

Configuration file

eth1-deposit-contract-max-request-size​

Syntax

Specify options

Using autocomplete

Options

beacon-liveness-tracking-enabled

builder-bid-compare-factor

builder-endpoint

builder-set-user-agent-header

config-file

data-base-path, data-path

data-beacon-path

data-storage-archive-frequency

data-storage-mode

data-storage-non-canonical-blocks-enabled

data-validator-path

doppelganger-detection-enabled

ee-endpoint

ee-jwt-secret-file

eth1-deposit-contract-address

eth1-deposit-contract-max-request-size

eth1-endpoint, eth1-endpoints

deposit-snapshot-enabled

exchange-capabilities-monitoring-enabled

genesis-state

help

initial-state

logging

log-color-enabled

log-destination

log-file

log-file-name-pattern

log-include-events-enabled

log-include-validator-duties-enabled

metrics-block-timing-tracking-enabled

metrics-enabled