Install Nimbus client

One-page interactive guide to install Nimbus 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.

Nimbus 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 Nimbus client

  1. Find the latest stable version of Nimbus on Github

    Find latest Nimbus version at Github: https://github.com/status-im/nimbus-eth2/releases
    Write latest stable Nimbus version:

    This will update the url links in the guide below.

  2. Download the latest Nimbus client

    cd ~/downloads && curl -LO https://github.com/status-im/nimbus-eth2/releases/download/v25.2.0/nimbus-eth2_Linux_amd64_25.2.0_c6688004.tar.gz

  3. Extract the downloaded package

    tar xvf nimbus-eth2_Linux_amd64_25.2.0_c6688004.tar.gz

  4. Copy Nimbus clients to /usr/local/bin

    sudo cp -a nimbus-eth2_Linux_amd64_25.2.0_c6688004/build /usr/local/bin/nimbus

  5. Remove downloaded files

    rm nimbus-eth2_Linux_amd64_25.2.0_c6688004.tar.gz && rm -r nimbus-eth2_Linux_amd64_25.2.0_c6688004

  1. Install Nimbus' dependencies

    sudo apt-get install build-essential git-lfs cmake

  2. Download the latest Nimbus client

    cd ~/downloads && git clone -b stable https://github.com/status-im/nimbus-eth2.git

  3. Move update

    cd nimbus-eth2 && make update

  4. Build Nimbus

    make gnosis-build
    make gnosis-vc-build

  5. Copy Nimbus clients to /usr/local/bin

    sudo cp -a build /usr/local/bin/nimbus

Configurate the service

  • Create a user

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

  • Create a folder for Nimbus beacon data

    : 
    sudo mkdir -p /var/lib/nimbus/beacon

  • Set access permission and ownership for the Nimbus Beacon data folder

    sudo chown -R nimbusbeacon:nimbusbeacon /var/lib/nimbus/beacon

Configurate & Run Nimbus Beacon 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.

  • Creating a checkpoint

    sudo /usr/local/bin/nimbus/nimbus_beacon_node trustedNodeSync \
  --network:mainnet  \
  --data-dir=/var/lib/nimbus/beacon \
  --trusted-node-url=https://beaconstate.info
    sudo /usr/local/bin/nimbus/nimbus_beacon_node_gnosis trustedNodeSync \
      --network:gnosis \
      --data-dir=/var/lib/nimbus/beacon \
      --trusted-node-url=https://checkpoint.gnosischain.com/
    *Note: Update jwt-secret-file, if you use different

  • Create configuration file for Tekubeacon service

    1. Open Nimbus Beacon configuration file

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

    2. Copy configuration

      [Unit]
Description=Nimbus Beacon Consensus Client (Mainnet)
Wants=network-online.target
After=network-online.target

[Service]
User=nimbusbeacon
Group=nimbusbeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/nimbus/nimbus_beacon_node \
  --network=mainnet \
  --data-dir=/var/lib/nimbus/beacon \
  --web3-url=http://127.0.0.1:8551 \
  --rest \
  --rest-port=5052 \
  --tcp-port=9000 \
  --udp-port=9000 \
  #--trusted-node-url=https://beaconstate.info \
  --jwt-secret=/var/lib/jwtsecret/ethereum.hex

[Install]
WantedBy=multi-user.target

      See more flags at https://nimbus.guide/options.html

      [Unit]
Description=Nimbus Beacon Consensus Client (Gnosis)
Wants=network-online.target
After=network-online.target

[Service]
User=nimbusbeacon
Group=nimbusbeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/nimbus/nimbus_beacon_node_gnosis \
  --network=gnosis \
  --data-dir=/var/lib/nimbus/beacon \
  --web3-url=http://127.0.0.1:8551 \
  --rest \
  --rest-port=5052 \
  --tcp-port=9000 \
  --udp-port=9000 \
  #--trusted-node-url=https://checkpoint.gnosischain.com/ \
  --jwt-secret=/var/lib/jwtsecret/gnosis.hex

[Install]
WantedBy=multi-user.target

      See more flags at https://nimbus.guide/options.html

      For an option to start syncing from a snapshot, check checkpoint-sync-url for a quick synchronization from a checpoint. After enabling it, verify, that you are on on the expected chain, see https://checkpoint.gnosischain.com/ → Get started → Nimbus

      *Note: Update 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 nimbusbeacon

  • Check the service

    systemctl status nimbusbeacon
journalctl -fu nimbusbeacon

  • Start the service automatically on system startup

    sudo systemctl enable nimbusbeacon
    • Open Delayed Start shell 
      sudo nano /usr/local/bin/delayed-start.sh

      Configurate service start inside it

      systemctl start nimbusbeacon.service
    • Be sure, delayed-start.service service controlling delayed-start.sh is enabled for auto start with system startup 
      sudo systemctl enable delayed-start.service

    1. Configurate Staking Manager util

      • Open the configuration file 
        sudo nano /usr/local/etc/staking/config/clients.conf

        If the file is empty, generate it with command sudo /usr/local/bin/staking.sh init

      • Set link to proper services. It should be as follow: 
        beaconServices="nimbusbeacon.service"

    2. Activate service to start automatically on OS startup

      • Open Start with delay util 
        sudo nano /usr/local/bin/delayed-start.sh
      • Place or uncomment a command to start the Beacon client(s) 
        /usr/local/bin/staking.sh start beacon
      • Verify, that a service `delayed-start.service` exists and is automatically launched on system start. 
        sudo systemctl enable delayed-start.service

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/nimbus/vi1

    • Load keystores to /var/lib/nimbus/vi1

      : 
      sudo /usr/local/bin/nimbus-validator import data-dir=/var/lib/nimbus/vi1 $HOME/keystores/ddk_i1

      NOTE: If you have used different passwords for each of your validators you will get an error. Run the process multiple times, providing each of the different passwords until they are all imported. Use the accounts list command to verify.

    • Create a service user for the validator instance

      sudo useradd --system --no-create-home --shell /bin/false nimbus-vi1

    • Set ownership of /var/lib/nimbus/vi1 to validators-i1 user

      sudo chown -R nimbus-vi1:nimbus-vi1 /var/lib/nimbus/vi1

    • Create configuration service file for nimbus-vi1 service

      1. Open the configuration file

        sudo nano /etc/systemd/system/nimbus-vi1.service

      2. Copy the configuration below into the file.

        [Unit]
Description=Nimbus 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
ExecStart=/usr/local/bin/nimbus/nimbus_validator_client \
  --network=mainnet \
  --data-dir=/var/lib/nimbus/vi1 \
  --beacon-node=http://127.0.0.1:5052 \
  --suggested-fee-recipient=0xXXXXXXXXXXXXXXXX \
  --graffiti="Nethermind+Nimbus"
  # --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/
 
[Install]
WantedBy=multi-user.target

        See more flags at https://nimbus.guide/options.html

        [Unit]
Description=Nimbus Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=nimbus-vi1
Group=nimbus-vi1
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/nimbus/nimbus_validator_client \
  --network=gnosis \
  --data-dir=/var/lib/nimbus/vi1 \
  --beacon-node=http://127.0.0.1:5052 \
  --suggested-fee-recipient=0xXXXXXXXXXXXXXXXX \
  --graffiti="Nethermind+Nimbus"
  
[Install]
WantedBy=multi-user.target

        See more flags at https://nimbus.guide/options.html

      3. Press CTRL + X then Y then ENTER to save and exit the config file.

    • Other configurations

      Nothing to do. You are ok.

      • Extend Staking manager clients.conf

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

    • Stop running validator instance nimbus-vi1

      sudo systemctl stop nimbus-vi1

    • Extend /var/lib/nimbus/vi1 for new keystores

      sudo /usr/local/bin/nimbus-validator import data-dir=/var/lib/nimbus/vi1 $HOME/keystores/ddk_i1

      NOTE: If you have used different passwords for each of your validators you will get an error. Run the process multiple times, providing each of the different passwords until they are all imported. Use the accounts list command to verify.

  2. Load processed changes to the system

    sudo systemctl daemon-reload

  3. Start the validator instance

    sudo systemctl start nimbus-vi1

  4. Check the running validator instance

    systemctl status nimbus-vi1
    journalctl -fu nimbus-vi1

  5. Activate service to start automatically on OS startup

    $ sudo systemctl enable nimbus-vi1

Exit validator instance / validator(s)

sudo /usr/local/bin/nimbus-beacon deposits exit --validator=/var/lib/nimbus/vi1

See more at https://nimbus.guide/voluntary-exit.html