Lighthouse client guides and options

One-page interactive complete guide to configurate and operate Lighthouse 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 Lighthouse client Update Lighthouse client Emergency for Lighthouse client Add Lighthouse validator Exit Lighthouse validator

Chains support

Supported Ethereum
Supported Gnosis

On-page actions for Lighthouse client

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

  1. Find the latest stable version of Lighthouse on Github

  2. Download Lighthouse version 5.3.0 to your node

    cd ~/downloads && curl -LO https://github.com/sigp/lighthouse/releases/download/v5.3.0/lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz

    Extract downloaded file

    $ tar xvf lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz
  3. Replace old Lighthouse client for new 
    $ sudo cp ~/downloads/lighthouse /usr/local/bin
  4. Remove downloaded files 
    $ cd ~/downloads && rm lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz && rm -r lighthouse

Configurate service

  1. Create a user for lighthouse beacon : 
    $ sudo useradd --system --no-create-home --shell /bin/false lighthousebeacon
  2. Create a directory for data : 
    $ sudo mkdir -p /var/lib/lighthouse/beacon
  3. Set permission for accessing the directory 
    $ sudo chown -R lighthousebeacon:lighthousebeacon /var/lib/lighthouse/beacon

  • 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 Lighthouse Beacon service

    Open Lighthouse Beacon configuration file

    $ sudo nano /etc/systemd/system/lighthousebeacon.service

    Copy the configuration below into the file. If needed, check flags documentation.

    [Unit]
Description=Lighthouse Consensus Client BN (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousebeacon
Group=lighthousebeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse bn \
  --network mainnet \
  --datadir /var/lib/lighthouse \
  --http \
  --execution-endpoint http://127.0.0.1:8551 \
  --execution-jwt /var/lib/jwtsecret/ethereum.hex \
#  --checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
  --checkpoint-sync-url=https://beaconstate.info \
  --port 9000 \
  --port6 9090 \
#  --discovery-port 9000 \
  --quic-port 9001 \
  --quic-port6 9091 \
  --http-port 5052

[Install]
WantedBy=multi-user.target
    [Unit]
Description=Lighthouse Consensus Client BN (Gnosis Network)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousebeacon
Group=lighthousebeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse bn \
  --network gnosis \
  --datadir /var/lib/lighthouse \
#  --subscribe-all-subnets \
  --execution-endpoint http://localhost:8551 \
  --execution-jwt /var/lib/jwtsecret/gnosis.hex \
  --target-peers 50 \
  --checkpoint-sync-url https://checkpoint.gnosischain.com/ \
  --http \
  --port 9000 \
  --port6 9090 \
#  --discovery-port 9000 \
  --quic-port 9001 \
  --quic-port6 9091 \
  --http-port 5052

[Install]
WantedBy=multi-user.target
    *Note: Update execution-jwt, if you use different

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

  • Load changes made in config files to the system

    $ sudo systemctl daemon-reload
  • Start the service 
    $ sudo systemctl start lighthousebeacon
  • Check the state 
    $ systemctl status lighthousebeacon
$ journalctl -fu lighthousebeacon
  • Activate service to start automatically 
    $ sudo systemctl enable lighthousebeacon

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

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

      : 
      sudo /usr/local/bin/lighthouse --network mainnet account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
      sudo /usr/local/bin/lighthouse --network gnosis account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
      • Insert keystores encryption password (the one used during keystores generation) on request
      • If there are keystores with different encryption password, repeat the process for each encryption password

    • Create a service user for the validator instance

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

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

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

    • Create configuration service file for lighthouse-vi1 service

      1. Open the configuration file

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

      2. Copy the configuration below into the file.

        [Unit]
Description=Lighthouse Validator Instance (Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=lighthouse-vi1
Group=lighthouse-vi1
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse vc \
  --network mainnet \
  --datadir /var/lib/lighthouse/vi1 \
  --suggested-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --beacon-nodes http://localhost:5052 \
  --graffiti "Nethermind+Lighthouse"
[Install]
WantedBy=multi-user.target
        [Unit]
Description=Lighthouse Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=lighthouse-vi1
Group=lighthouse-vi1
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse vc \
  --network gnosis \
  --datadir /var/lib/lighthouse/vi1 \
  --suggested-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --beacon-nodes http://localhost:5052 \
  --graffiti "Nethermind+Lighthouse"
[Install]
WantedBy=multi-user.target
      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 lighthouse-vi1 into clients.conf file that is used by Staking Manager. 
        sudo nano /usr/local/etc/staking/config/clients.conf

    • Stop running validator instance lighthouse-vi1

      sudo systemctl stop lighthouse-vi1

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

      sudo /usr/local/bin/lighthouse --network mainnet account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
      sudo /usr/local/bin/lighthouse --network gnosis account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
      • You will be requested to insert keystores encryption password (the one used during keystores generation)
      • If there are keystores with different encryption password, repeat the process for each encryption password
      • Already existing keystores in the directory will be skipped

  2. Load processed changes to the system

    sudo systemctl daemon-reload

  3. Start the validator instance

    sudo systemctl start lighthouse-vi1

  4. Check the running validator instance

    systemctl status lighthouse-vi1
    journalctl -fu lighthouse-vi1

  5. Activate service to start automatically on OS startup

    $ sudo systemctl enable lighthouse-vi1

Exit validator instance / validator(s)

A validator can be exited with following command: 
lighthouse --network "$chain" account validator exit --keystore /path/to/keystore --password-file "$HOME/exit/keystore-password.txt" --beacon-node http://localhost:5052
Where:
  • --network is mainnet for Ethereum chain and gnosis for Gnosis chain
  • --keystore is a path to the keystore file of specific validator
  • --password-file is a file with exit passowrd placed in
  • --beacon-node is a beaconnode url

Example request can look as below:

/usr/local/bin/lighthouse --network mainnet account validator exit --keystore /var/lib/lighthouse/vi1/validators/keystore... --beacon-node http://localhost:5052
/usr/local/bin/lighthouse --network gnosis account validator exit --keystore /var/lib/lighthouse/vi1/validators/keystore... --beacon-node http://localhost:5052

For confirmation, place exit phrase Exit my validator

Follow instructions from Exit Lighthouse validators on Github.
  1. Install a script for bulk exit
  2. Create ~/exit/keystore-password.txt file with keystores password. It's the passowrd selected during validator keys generation. The passowrd can be also found at validator_definitions.yml file, see 
    sudo nano /var/lib/lighthouse-validatorInstance/validator_definitions.yml
  3. Perform the exit all validators in selected instance request 
    /usr/local/bin/lighthouse_exit_validators.sh mainnet /var/lib/ethereum/lighthouse/vi1/validators http://localhost:5052
    /usr/local/bin/lighthouse_exit_validators.sh gnosis /var/lib/gnosis/lighthouse/vi1/validators http://localhost:5052
    • Replace chain for ethereum / gnosis
    • Replace /var/lib/gnosis/lighthouse/vi1/validators/ for a path to your instance keystores
  4. Remove the password from ~/exit/keystore-password.txt

See more at official documentation, if needed.

Update Lighthouse client

Check current version of Lighthouse running on the server:

lighthouse --version
curl "http://127.0.0.1:5052/eth/v1/node/version"

  1. Find the latest stable version of Lighthouse on Github

  2. Download Lighthouse version 5.3.0 to your node

    cd ~/downloads && curl -LO https://github.com/sigp/lighthouse/releases/download/v5.3.0/lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz

    Extract downloaded file

    $ tar xvf lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz

  3. Stop Lighthouuse services

    Stop Lighthouse Beacon service and all validators-based services

    sudo systemctl stop lighthousebeacon
sudo systemctl stop lighthouse-vi...
sudo systemctl stop lighthouse-vi...
...

    Stop cosnsensus services

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

    Check cosnsensus services status

    /usr/local/bin/staking.sh check consensus
  4. Replace old Lighthouse client for new 
    $ sudo cp ~/downloads/lighthouse /usr/local/bin

  5. Start the Lighthouse services

    Start Lighthouse Beacon service and all validators-based services

    sudo systemctl start lighthousebeacon
sudo systemctl start lighthouse-vi...
sudo systemctl start lighthouse-vi...
...
    /usr/local/bin/staking.sh start consensus

  6. Monitor

    • systemctl status lighthousebeacon lighthouse-vi.. lighthouse-vi..
    • journalctl -fu lighthousebeacon
    • journalctl -f -u lighthouse-vi.. -u lighthouse-vi...
    /usr/local/bin/staking.sh check consensus
    /usr/local/bin/staking.sh monitor consensus
  7. Remove downloaded files 
    $ cd ~/downloads && rm lighthouse-v5.3.0-x86_64-unknown-linux-gnu.tar.gz && rm -r lighthouse