Advanced Setup: The config.txt File

Overview

Web3 Pi utilizes a central configuration file, /boot/firmware/config.txt, to manage both its own settings (like which clients to run and network selection) and the underlying Raspberry Pi hardware configuration (like boot options, hardware interfaces, and overclocking).

This file is read by the Raspberry Pi firmware during the early boot process.

For most users, the default settings generated by the Web3 Pi Imager are sufficient and should not need modification. This page is intended for advanced users who understand the implications of changing these parameters.

⚠️ WARNING: Incorrectly editing /boot/firmware/config.txt can prevent your Raspberry Pi from booting correctly or cause your Ethereum node clients to malfunction. Always back up the file before making changes.

Location and Editing

The configuration file is located at:

/boot/firmware/config.txt

You will need root privileges to edit this file. Connect via SSH and use a text editor like nano:

# First, create a backup
sudo cp /boot/firmware/config.txt /boot/firmware/config.txt.backup

# Then, edit the file
sudo nano /boot/firmware/config.txt

After saving changes, you must reboot your Raspberry Pi for them to take effect:

sudo reboot

Web3 Pi Specific Sections

These sections control the behavior of the Web3 Pi software suite.

[web3pi] Section

geth=true|false: Enables or disables the Geth execution client service (w3p_geth).
nimbus=true|false: Enables or disables the Nimbus consensus client service (w3p_nimbus-beacon).
lighthouse=true|false: Enables or disables the Lighthouse consensus client service (w3p_lighthouse-beacon). (Note: Typically, only one consensus client should be enabled).
influxdb=true|false: Enables or disables the InfluxDB time-series database service (for monitoring).
grafana=true|false: Enables or disables the Grafana dashboard service (for monitoring).
bsm=true|false: Enables or disables the Basic System Monitor service.
bnm=true|false: Enables or disables the Basic Eth2 Node Monitor service.
exec_url=http://localhost:8551: Specifies the URL the consensus client uses to connect to the execution client's Engine API. The default assumes both clients are on the same machine.
eth_network=mainnet|sepolia|hoodi|...: Crucially, sets the target Ethereum network for all clients. Must match the network you intend to sync.

Client Port Sections ([geth], [nimbus], [lighthouse]):

geth_port=30303: Sets the P2P port Geth uses for peer discovery and communication.
nimbus_port=9000: Sets the P2P port Nimbus uses.
lighthouse_port=9000: Sets the P2P port Lighthouse uses.

Make sure to update the UFW Firewall after changing these ports.

Standard Raspberry Pi Sections

The rest of the config.txt file contains standard Raspberry Pi configuration directives, grouped under conditional filters like [all], [pi4], [pi5], [cm4], etc. These control hardware aspects:

Boot Options: (kernel, cmdline, initramfs) Defines how the Linux kernel is loaded.
Hardware Interfaces: (dtparam=audio, i2c_arm, spi, enable_uart) Enables or disables onboard hardware like audio, I2C, SPI, and serial ports.
Display Settings: (disable_overscan, hdmi_drive, hdmi_force_hotplug, display_auto_detect) Configures HDMI output behavior.
Graphics: (dtoverlay=vc4-kms-v3d) Configures the graphics driver.
Camera: (camera_auto_detect) Auto-detects connected cameras.
USB: (dtoverlay=dwc2, usb_max_current_enable) Configures USB ports, including enabling higher current output on Pi 5.
PCIe (Pi 5 / CM4): (dtparam=pciex1, dtparam=pciex1_gen=3) Important for NVMe drives. Enables the PCIe interface and sets its speed (Gen 2 or Gen 3). Web3 Pi typically enables Gen 3 for better NVMe performance.
Overclocking: (Lines often starting with # over_voltage, # arm_freq) These settings (commented out by default) allow advanced users to potentially increase CPU performance. Requires active cooling and carries risks of instability or hardware damage if done improperly.