Install Teku client

One-page interactive guide to install Teku client and configurate it for running on supported chain.

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.

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

Interactive variables

System:
User:
SSH port:
CPU type:

Execution layer

Client:
Service:
- Data:
- Port:
- P2P:
- RPC:

Consensus layer

Client:
NodeJs version:
jdk ver version:
Beacon service:
- Data:
- Port:
- P2P:
- Quic:

Install Teku client

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

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.

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

Unpack the downloaded Teku version
```
$ tar xvf teku-24.10.3.tar.gz
```

Copy the Teku Library

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

Remove downloaded files

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

Configurate the service

Create a user

Service/User name:

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

Create a folder for Tekubeacon data
Service data directory:
```
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
  - Choose P2P communication port:
  - 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
  - Choose 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
  - Choose Beacon API port:
  - 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
  - P2P communication port:
  - 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
  - Choose QUIC IPv4 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

Open Tekubeacon configuration file

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

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

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)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

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
  Directory with Deposit Data keystores:
  - 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. Whats's the first keystore name? .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.
    
    What's fee recipient wallet?
    
    What's your execution client?
    
    [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
  Directory with Deposit Data keystores:
  - 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. Whats's the first keystore name? .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
```
Load changes made in config files to the system
```
sudo systemctl daemon-reload
```
Start the validator instance
```
sudo systemctl start teku-vi1
```

Check the running validator instance

systemctl status teku-vi1

journalctl -fu teku-vi1

Activate service to start automatically
```
sudo systemctl enable teku-vi1
```

Exit validator instance / validator(s)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

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