Teku client guides and options

One-page interactive complete guide to configurate and operate Teku client.

Disclaimer

This guide is for informational purposes only. The author nor website owner does not guarantee accuracy of the information in this guide and is not responsible for any damages or losses incurred by following the guide.

Individual guides

Install Teku client Update Teku client Emergency for Teku client Add Teku validator Exit Teku validator

Chains support

Supported Ethereum
Supported Gnosis

On-page actions for Teku client

Teku client can be used for staking on various supported chains. Client installation is always only one, used by services with an individual configuration (different service name, data path and ports in use).

Install Teku client

  1. Install Java

    cd ~/downloads && wget https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.deb
sudo apt install ./jdk-21_linux-x64_bin.deb
    java --version

  2. Find the latest stable version of Teku on Github

    Find latest Teku version at Github: https://github.com/Consensys/teku/releases
    Write latest stable Teku version:

    This will update the url links in the guide below.

  3. Download the latest Teku version

    cd ~/downloads && curl -LO https://artifacts.consensys.net/public/teku/raw/names/teku.tar.gz/versions/24.10.3/teku-24.10.3.tar.gz

  4. Unpack the downloaded Teku version

    $ tar xvf teku-24.10.3.tar.gz

  5. Copy the Teku Library

    sudo cp -a ~/downloads/teku-24.10.3 /usr/local/bin/teku

  6. Remove downloaded files

    cd ~/downloads && rm teku-24.10.3.tar.gz && rm -r teku-24.10.3

Configurate service

  • Create a user

    : 
    sudo useradd --system --no-create-home --shell /bin/false tekubeacon

  • Create a folder for Tekubeacon data

    : 
    sudo mkdir -p /var/lib/tekubeacon

  • Set access permission and ownership for the Nethermind data folder

    sudo chown -R tekubeacon:tekubeacon /var/lib/tekubeacon

Configurate & Run Tekubeacon service

  • Communication ports selection

    Each service on the server needs a custom port for communication. Through ports, consensus client communicates with other peers in the network as well as other services running on the server, such as validator clients. There is an IPv4 and IPv6 variant, depending on the ISP support / preference. Each protocol version needs custom port. If you are not sure what to select, continue with default IPv4 port.

    1. Configurate public IPv4 port for P2P communication with other peers

      • :
      • Verify availability of selected port 9000 
        ss -tuln | grep ':9000'

        If it returns empty response, the port 9000 is free and can be used.

      • Enable traffic on the port through UFW 
        $ sudo ufw allow 9000
      • Disable IPv6 traffic on the port
        • List allowed ports 
          sudo ufw status numbered
        • Find order number for V6, see 9000 (V6) and remove it with the following line 
          sudo ufw delete <Number>

    2. QUIC IPv4 port

      • :
      • Verify availability of selected port 9001 
        ss -tuln | grep ':9001'

        If it returns empty response, the port 9001 is free and can be used.

    3. Beacon API port for internal communication

      • :
      • Verify availability of selected port 5052 
        ss -tuln | grep ':5052'

        If it returns empty response, the port 5052 is free and can be used.

    1. Configurate public IPv6 port for P2P communication with other peers

      • :
      • Verify availability of selected port 9090 
        ss -tuln | grep ':9090'

        If it returns empty response, the port 9090 is free and can be used.

      • Enable traffic on the port through UFW 
        $ sudo ufw allow 9090
      • Disable IPv6 traffic on the port
        • List allowed ports 
          sudo ufw status numbered
        • Find order number for V6, see 9090 and remove it with the following line 
          sudo ufw delete <Number>

    2. QUIC IPv6 port

      • :
      • Verify availability of selected port 9091 
        ss -tuln | grep ':9091'

        If it returns empty response, the port 9091 is free and can be used.

  • Create configuration file for Tekubeacon service

    1. Open Tekubeacon configuration file

      sudo nano /etc/systemd/system/tekubeacon.service

    2. Copy configuration

      [Unit]
Description=Teku Consensus Client (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=tekubeacon
Group=tekubeacon
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx5g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku \
  --network=mainnet \
  --data-path=/var/lib/tekubeacon \
  --ee-endpoint=http://127.0.0.1:8551 \
  --ee-jwt-secret-file=/var/lib/jwtsecret/ethereum.hex \
  --metrics-enabled=true \
  --rest-api-enabled=true \
  --validators-proposer-default-fee-recipient= 0x... \
  #--checkpoint-sync-url= \
  --initial-state=https://checkpoint.gnosischain.com/eth/v2/debug/beacon/states/finalized
[Install]
WantedBy=multi-user.target
      [Unit]
Description=Teku Consensus Client (Gnosis chain)
Wants=network-online.target
After=network-online.target
[Service]
User=tekubeacon
Group=tekubeacon
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx5g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku \
  --network=gnosis \
  --data-path=/var/lib/tekubeacon \
  --ee-endpoint=http://127.0.0.1:8551 \
  --ee-jwt-secret-file=/var/lib/jwtsecret/gnosis.hex \
  --metrics-enabled=true \
  --rest-api-enabled=true \
  --validators-proposer-default-fee-recipient= 0x... \
  #--checkpoint-sync-url= \
  --initial-state=https://checkpoint.gnosischain.com/eth/v2/debug/beacon/states/finalized
[Install]
WantedBy=multi-user.target
      *Note: Update ee-jwt-secret-file, if you use different
    3. Press CTRL + X then Y then ENTER to save and exit the config file.

  • Load changes

    sudo systemctl daemon-reload

  • Start the Beacon chain service

    sudo systemctl start tekubeacon

  • Check the service

    systemctl status tekubeacon
journalctl -fu tekubeacon

  • Start the service automatically on system startup

    sudo systemctl enable tekubeacon

Launch validator instance / validator(s)

  1. Do you want to create a new validation instance or extend exisiting instance for more validators?

    • Create a directory for validator instance data

      sudo mkdir -p /var/lib/teku-vi1

    • If exists, remove deposit_data file from keystores folder

      :
      • Display files in the directory 
        cd $HOME/keystores/ddk_i1 && ls -lh
      • If there is deposit_data-XXX....json file, remove it 
        rm deposit_data-XXX....json

    • Copy keystores dedicated for instance into /var/lib/teku-vi1/keystores folder

      sudo mkdir /var/lib/teku-vi1/keystores
      sudo cp -a $HOME/keystores/ddk_i1/* /var/lib/teku-vi1/keystores && cd /var/lib/teku-vi1/keystores

    • Teku requires a .txt file with encryption password for each .json validator file.

      1. Display all keystores in the directory 
        ls -lh

      2. .json

        Vreate a new .txt file for the keystore-m_12381_3600_X_0_0-XXXXXXXXXX.json keystore file

        nano keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

        Insert an encryption password for the validator key (the one used during keystores generation) into that file.

        Press ctrl + x, then y to save and exit

      3. Set readonly permission for that file 
        sudo chmod 400 keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

      Now, you can either repeate the process for all other keystores in the folder, or use an automated solution to duplicate the created password file (with modified name) for all remaining keystores, see Shell Script to generate password files for Teku.

      With automated process, to generate .txt file with a content of /var/lib/teku-vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt for all remaining keystores in the /var/lib/teku-vi1/keystores/ directory, use command 

      $HOME/bashscripts/create-teku-pswfiles.sh /var/lib/teku-vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

    • Create a service user for the validator instance

      sudo useradd --system --no-create-home --shell /bin/false teku-vi1
    • Set ownership of validator instance data directory to validator-instance user 
      sudo chown -R teku-vi1:teku-vi1 /var/lib/teku-vi1

    • Create configuration service file for teku-vi1 service

      1. Open the configuration file 
        sudo nano /etc/systemd/system/teku-vi1.service
      2. Copy the configuration below into the file. 
        [Unit]
Description=Teku Validator Instance (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=teku-vi1
Group=teku-vi1
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx8g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku validator-client \
  --network mainnet \
  --beacon-node-api-endpoint http://127.0.0.1:5052 \
  #--beacon-node-api-endpoint http://127.0.0.1:5051,http://192.10.10.101:5051,http://192.140.110.44:5051 \
  --data-path /var/lib/teku-vi1 \
  --validator-keys /var/lib/teku-vi1/keystores:/var/lib/teku-vi1/keystores \
  --validators-proposer-default-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --validators-graffiti "Nethermind+Teku"
[Install]
WantedBy=multi-user.target
        [Unit]
Description=Teku Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=teku-vi1
Group=teku-vi1
Type=simple
Restart=always
RestartSec=5
Environment="JAVA_OPTS=-Xmx8g"
Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
ExecStart=/usr/local/bin/teku/bin/teku validator-client \
  --network gnosis \
  --beacon-node-api-endpoint http://127.0.0.1:5052 \
  #--beacon-node-api-endpoint http://127.0.0.1:5051,http://192.10.10.101:5051,http://192.140.110.44:5051 \
  --data-path /var/lib/teku-vi1 \
  --validator-keys /var/lib/teku-vi1/keystores:/var/lib/teku-vi1/keystores \
  --validators-proposer-default-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --validators-graffiti "Nethermind+Teku"
[Install]
WantedBy=multi-user.target

    • Other configurations

      Nothing to do. You are ok.

      • Extend Staking manager clients.conf

        Insert teku-vi1 into clients.conf file that is used by Staking Manager. 
        sudo nano /usr/local/etc/staking/config/clients.conf

    • Stop running validator instance teku-vi1

      sudo systemctl stop teku-vi1

    • If exists, remove deposit_data file from keystores folder

      :
      • Display files in the directory 
        cd $HOME/keystores/ddk_i1 && ls -lh
      • If there is deposit_data-XXX....json file, remove it 
        rm deposit_data-XXX....json

    • Copy keystores dedicated for instance into /var/lib/teku-vi1/keystores folder

      sudo mkdir /var/lib/teku-vi1/keystores
      sudo cp -a $HOME/keystores/ddk_i1/* /var/lib/teku-vi1/keystores/keystores  && cd /var/lib/teku-vi1/keystores

    • Teku requires a .txt file with encryption password for each .json validator file.

      1. Display all keystores in the directory 
        ls -lh

      2. .json

        Vreate a new .txt file for the keystore-m_12381_3600_X_0_0-XXXXXXXXXX.json keystore file

        nano keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

        Insert an encryption password for the validator key (the one used during keystores generation) into that file.

        Press ctrl + x, then y to save and exit

      3. Set readonly permission for that file 
        sudo chmod 400 keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

      Now, you can either repeate the process for all other keystores in the folder, or use an automated solution to duplicate the created password file (with modified name) for all remaining keystores, see Shell Script to generate password files for Teku.

      With automated process, to generate .txt file with a content of /var/lib/teku-vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt for all remaining keystores in the /var/lib/teku-vi1/keystores/ directory, use command 

      $HOME/bashscripts/create-teku-pswfiles.sh /var/lib/teku-vi1/keystores/keystore-m_12381_3600_X_0_0-XXXXXXXXXX.txt

  2. Load changes made in config files to the system

    sudo systemctl daemon-reload

  3. Start the validator instance

    sudo systemctl start teku-vi1

  4. Check the running validator instance

    systemctl status teku-vi1
    journalctl -fu teku-vi1

  5. Activate service to start automatically

    sudo systemctl enable teku-vi1

Exit validator instance / validator(s)

Exit Validator(s) guide in progress.

Official documentation at https://docs.teku.consensys.io/reference/cli/subcommands/voluntary-exit

teku voluntary-exit --validator-keys=/var/lib/teku-vi1/keystores_i1:/var/lib/teku-vi1/keystores_i1

Update Teku client

Check current version of Teku running on the server:

/usr/local/bin/teku/bin/teku --version

  1. Find the latest stable version of Teku on Github

    Find latest Teku version at Github: https://github.com/Consensys/teku/releases
    Write latest stable Teku version:

    This will update the url links in the guide below.

  2. Download the latest Teku version

    cd ~/downloads && curl -LO https://artifacts.consensys.net/public/teku/raw/names/teku.tar.gz/versions/24.10.3/teku-24.10.3.tar.gz

  3. Unpack the downloaded Teku version

    $ tar xvf teku-24.10.3.tar.gz

  4. Stop Teku services

    Stop Teku Beacon service and all validators-based services

    sudo systemctl stop tekubeacon
sudo systemctl stop teku-vi...
sudo systemctl stop teku-vi...
...

    Check services status for state

    sudo systemctl status tekubeacon
sudo systemctl status teku-vi...; sudo systemctl status teku-vi...
...

    Stop cosnsensus services

    /usr/local/bin/staking.sh stop consensus

    Check cosnsensus services status

    /usr/local/bin/staking.sh check consensus

  5. Remove Old Teku Library

    sudo rm -r /usr/local/bin/teku

  6. Copy the Teku Library

    sudo cp -a ~/downloads/teku-24.10.3 /usr/local/bin/teku

  7. Start the services again

    Start Teku Beacon service and all validators-based services

    sudo systemctl start tekubeacon
sudo systemctl start teku-vi...
sudo systemctl start teku-vi...
...
    /usr/local/bin/staking.sh start consensus

  8. Monitor

    • systemctl status tekubeacon teku-vi..
    • journalctl -fu tekubeacon
    • journalctl -f -u lodestar-vi.. -u lodestar-vi..
    /usr/local/bin/staking.sh check consensus
    /usr/local/bin/staking.sh monitor consensus

  9. Remove downloaded files

    cd ~/downloads && rm teku-24.10.3.tar.gz && rm -r teku-24.10.3