Configuration

How to configure Geth using command-line flags or a TOML configuration file.

Geth can be configured with command-line flags or a TOML configuration file. The two approaches can be combined: the file sets defaults that individual flags can override.

Configuration file

Pass a TOML configuration file with --config:

geth --config /path/to/config.toml

Generating a config file

The easiest way to produce a valid starting configuration is to export the current defaults with dumpconfig:

# Print defaults to stdout
geth dumpconfig

# Write defaults to a file
geth dumpconfig > config.toml

# Combine with flags to capture a customised baseline
geth --syncmode full --http dumpconfig > config.toml

The output is valid TOML that can be edited and passed back with --config.

Example TOML snippet

[Eth]
SyncMode = "snap"
NetworkId = 1

[Node]
DataDir = "/var/lib/geth"
HTTPHost = "127.0.0.1"
HTTPPort = 8545
HTTPModules = ["eth", "net", "web3"]
WSHost = "127.0.0.1"
WSPort = 8546
WSModules = ["eth", "net", "web3"]

[Node.P2P]
MaxPeers = 50
ListenAddr = ":30303"

[Node.HTTPTimeouts]
ReadTimeout = 30000000000
WriteTimeout = 30000000000
IdleTimeout = 120000000000

---

Flag reference

Node identity

Flag	Default	Description
--identity	(empty)	Custom human-readable name advertised over the p2p network
--datadir	~/.ethereum	Root directory for databases and the keystore
--port	30303	TCP/UDP network listening port
--networkid	0 (auto)	Network ID; 0 means use the chain ID. For testnets use --sepolia, --holesky, or --hoodi

Sync and state

Flag	Default	Description
--syncmode	snap	Blockchain sync mode — snap or full
--gcmode	full	Garbage-collection mode — full (prune old state) or archive (retain all state)
--state.scheme	(auto)	State storage scheme — hash or path
--history.state	90000	Number of recent blocks for which state history is kept (path scheme only, 0 = entire chain)
--history.transactions	2350000	Number of recent blocks with a transaction index (0 = entire chain)
--snapshot	true	Enable snapshot-database mode

Networking

Flag	Default	Description
--bootnodes	(network default)	Comma-separated enode URLs for P2P discovery bootstrap
--maxpeers	50	Maximum number of network peers (0 disables networking)
--nat	any	NAT port mapping mechanism (any, none, upnp, pmp, extip:<IP>, stun:<IP:PORT>)
--nodiscover	false	Disable automatic peer discovery (add peers manually)
--netrestrict	(empty)	Restrict peer communication to specific IP ranges (CIDR)
--discovery.dns	(network default)	DNS discovery entry points
--discovery.port	30303	UDP port for P2P discovery

Transaction pool

Flag	Default	Description
--txpool.pricelimit	1	Minimum gas price tip (in wei) for acceptance into the pool
--txpool.pricebump	10	Price bump percentage required to replace an existing transaction
--txpool.accountslots	16	Minimum executable transaction slots guaranteed per account
--txpool.globalslots	5120	Maximum executable transaction slots across all accounts
--txpool.accountqueue	64	Maximum queued (non-executable) slots per account
--txpool.globalqueue	1024	Maximum queued (non-executable) slots across all accounts
--txpool.lifetime	3h0m0s	Maximum time a non-executable transaction stays queued
--txpool.journal	transactions.rlp	Disk journal file for local transactions
--txpool.nolocals	false	Disable priority treatment for locally submitted transactions

HTTP JSON-RPC

Flag	Default	Description
--http	false	Enable the HTTP-RPC server
--http.addr	localhost	HTTP-RPC listening interface
--http.port	8545	HTTP-RPC listening port
--http.api	eth,net,web3	APIs exposed over HTTP
--http.corsdomain	(empty)	Comma-separated domains allowed to make cross-origin requests
--http.vhosts	localhost	Comma-separated virtual hostnames accepted by the server
--http.rpcprefix	(empty)	HTTP path prefix for JSON-RPC (use / to serve on all paths)

WebSocket JSON-RPC

Flag	Default	Description
--ws	false	Enable the WebSocket-RPC server
--ws.addr	localhost	WebSocket-RPC listening interface
--ws.port	8546	WebSocket-RPC listening port
--ws.api	eth,net,web3	APIs exposed over WebSocket
--ws.origins	(empty)	Origins from which WebSocket requests are accepted
--ws.rpcprefix	(empty)	HTTP path prefix for WebSocket JSON-RPC

IPC

Flag	Default	Description
--ipcdisable	false	Disable the IPC-RPC server
--ipcpath	geth.ipc	Filename for the IPC socket/pipe inside the datadir

Authenticated RPC (Engine API)

Flag	Default	Description
--authrpc.addr	localhost	Listening address for the authenticated Engine API
--authrpc.port	8551	Listening port for the authenticated Engine API
--authrpc.jwtsecret	(required)	Path to the JWT secret file used to authenticate consensus-layer connections
--authrpc.vhosts	localhost	Virtual hostnames accepted by the authenticated API server

Logging

Flag	Default	Description
--verbosity	3	Log verbosity level: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail
--log.format	terminal	Log output format: terminal, json, or logfmt
--log.file	(stderr)	Write logs to a file instead of (or in addition to) stderr
--log.rotate	false	Enable automatic log file rotation
--log.vmodule	(empty)	Per-package verbosity overrides, e.g. eth/*=5,p2p=4

---

Common configuration patterns

1. Generate a baseline config

   Export the current defaults so you have a complete starting point:

   geth dumpconfig > /etc/geth/config.toml
   
2. Edit the config file

   Open the file and adjust the sections relevant to your deployment. At minimum you will probably want to set DataDir, the HTTP/WS endpoints, and the SyncMode.

3. Start Geth with the config

   geth --config /etc/geth/config.toml
   

   Flags passed on the command line override values in the file.