Using Packages

This guide will walk you through running a Polygon validator node from packages.

For system requirements, follow the Validator Node System Requirements guide.

tip

Steps in this guide involve waiting for the Heimdall and Bor services to fully sync. This process takes several days to complete. Alternatively, you can use a maintained snapshot, which will reduce the sync time to a few hours. For detailed instructions, see Snapshot Instructions for Heimdall and Bor.

For snapshot download links, see Polygon Chains Snapshots.

Overview

To get to a running validator node, conduct the following in this exact sequence of steps:

You will run into configuration issues if these steps are performed out of sequence. It is important to keep in mind that a sentry node must always be set up before the validator node.

Prepare two machines, one for the sentry node and one for the validator node.
Install the Heimdall and Bor binaries on the sentry and validator machines.
Set up the Heimdall and Bor service files on the sentry and validator machines.
Set up the Heimdall and Bor services on the sentry and validator machines.
Configure the sentry node.
Start the sentry node.
Configure the validator node.
Set the owner and signer keys.
Start the validator node.
Check node health with the community.

Installing package

Prerequisites

Two machines — one sentry and one validator.
Bash is installed on both the sentry and the validator machines.
RabbitMQ installed on both the sentry and the validator machines. See Downloading and Installing RabbitMQ.

Heimdall

Install the default latest version of sentry for the Polygon Mainnet:

curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash

or install a specific version, node type (sentry or validator), and network (mainnet or testnet). All release versions can be found on Heimdall GitHub repository.

curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- <version> <network> <node_type>
# Example:
# curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- v0.3.0 mainnet sentry

Bor

Install the default latest version of sentry for Mainnet:

curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash

or install a specific version, node type (sentry or validator), and network (mainnet or testnet). All release versions could be found on Bor Github repository.

curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- <version> <network> <node_type>

# Example:
# curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- v0.3.3 mainnet sentry

Check installation

Check Heimdall installation
```
heimdalld version --long
```
Check Bor installation
```
bor version
```

note

Before proceeding, Bor should be installed on both the sentry and validator machines.

Configuration

In this section, we will go through steps to initialize and customize configurations nodes.

caution

Bor and Heimdall 0.3.0 uses standardized paths for configuration files and chain data. If you have existing config files and chain data on your node, please skip this section and jump directly to Migration section to learn about migrating configs and data to standardized file locations.

Configure Heimdall

Initialize Heimdall configs

# For mainnet
sudo -u heimdall heimdalld init --chain=mainnet --home /var/lib/heimdall

# For testnet
sudo -u heimdall heimdalld init --chain=mumbai --home /var/lib/heimdall

Open the Heimdall configuration file for editing:

vi /var/lib/heimdall/config/config.toml

In config.toml, change the following parameters:

moniker — any name. Example: moniker = "my-sentry-node".

seeds — the seed node addresses consisting of a node ID, an IP address, and a port.

Use the following values:

seeds="[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656"

pex — set the value to true to enable the peer exchange. Example: pex = true.
private_peer_ids — the node ID of Heimdall set up on the validator machine.
To get the node ID of Heimdall on the validator machine:
1. Log in to the validator machine.
2. Run:
```
heimdalld tendermint show-node-id
```
Example: private_peer_ids = "0ee1de0515f577700a6a4b6ad882eff1eb15f066".
prometheus — set the value to true to enable the Prometheus metrics. Example: prometheus = true.
max_open_connections — set the value to 100. Example: max_open_connections = 100.

Save the changes in config.toml.

Configure Bor

In /var/lib/bor/config.toml, add the following:

[p2p]
    [p2p.discovery]
        static-nodes = ["<replace with enode://[email protected]_machine_ip:30303>"]

To get the node ID of Bor on the validator machine:

Log into the validator machine.
Run bor bootnode -node-key /var/lib/bor/data/bor/nodekey -dry-run.

Example output: "enode://410e359736bcd3a58181cf55d54d4e0bbd6db2939c5f548426be7d18b8fd755a0[email protected]134.209.100.175:30303".

Example content of static node field in /var/lib/bor/config.toml:

[p2p]
    [p2p.discovery]
        static-nodes = ["enode://410e359736bcd3a58181cf55d54d4e0bbd6db2939c5f548426be7d18b8fd755a0[email protected]134.209.100.175:30303"]

Save the changes in /var/lib/bor/config.toml.

Configuring a firewall

The sentry machine must have the following ports open to the world 0.0.0.0/0:

26656- Your Heimdall service will connect your node to other nodes Heimdall service.
30303- Your Bor service will connect your node to other nodes Bor service.
22- For the validator to be able to ssh from wherever they are.

Upgrade from 0.2.x to 0.3.x

Bor 0.3.0 and Heimdall 0.3.0 uses new CLIs and path standards. It is recommended to set up everything from a new machine. However, if you still want to perform an upgrade on existing node, you need to follow the one-time migration steps outlined below. If you are installing everything from a new machine, you can skip this section and continue to Configure service files.

Stop existing Heimdall and Bor services

sudo service bor stop
sudo service heimdalld stop
sudo service heimdalld-rest-server stop
sudo service heimdalld-bridge stop

Create a backup folder in case something went wrong

mkdir ./backup
mkdir ./backup/bin
mkdir -p ./backup/go/bin

Move old binaries

sudo mv /usr/bin/bor ./backup/bin
sudo mv /usr/bin/heimdalld ./backup/bin
sudo mv /usr/bin/heimdallcli ./backup/bin
sudo mv /usr/bin/bridge ./backup/bin
sudo mv $(go env GOPATH)/bin/bor ./backup/go/bin
sudo mv $(go env GOPATH)/bin/heimdalld ./backup/go/bin
sudo mv $(go env GOPATH)/bin/heimdallcli ./backup/go/bin
sudo mv $(go env GOPATH)/bin/bridge ./backup/go/bin

Move old service files

sudo mv /etc/systemd/system/bor.service ./backup
sudo mv /etc/systemd/system/heimdalld.service ./backup
sudo mv /etc/systemd/system/heimdalld-rest-server.service ./backup
sudo mv /etc/systemd/system/heimdalld-bridge.service ./backup

Migrate the Heimdall and Bor directory to /var/lib and change ownership:

sudo mv ~/.heimdalld /var/lib/heimdall
sudo mv ~/.bor /var/lib/bor
sudo chown -R heimdall /var/lib/heimdall
sudo chown -R bor /var/lib/bor

In case data copying is too slow or original data folder is mounted on a different device, you can create symlinks

sudo chown -R heimdall ~/.bor
sudo chown -R bor ~/.heimdalld
sudo rm -rf /var/lib/heimdall
sudo ln -nfs ~/.heimdalld /var/lib/heimdall
sudo ln -nfs ~/.bor /var/lib/bor
sudo chown -R heimdall /var/lib/heimdall
sudo chown -R bor /var/lib/bor

Copy configurations in node/bor/start.sh to Bor configuration file /var/lib/bor/config.toml. Note that some flags are renamed in the new CLI, you can find the documentation for new CLI here and sample configuration file in launch repository.

You can use this util script to convert start.sh to a config.toml file on your host. Example usage:

$ git clone https://github.com/maticnetwork/bor.git
$ cd bor/scripts
$ BOR_DIR=/var/lib/bor ./getconfig.sh
* Path to start.sh: /home/ubuntu/node/bor/start.sh
* Your validator address (e.g. 0xca67a8D767e45056DC92384b488E9Af654d78DE2), or press Enter to skip if running a sentry node: 0xca67a8D767e45056DC92384b488E9Af654d78DE2
Thank you, your inputs are:
Path to start.sh: /home/ubuntu/node/bor/start.sh
Address: 0xca67a8D767e45056DC92384b488E9Af654d78DE2
Path to the config file: /home/ubuntu/node/bor/start-config.toml
...

$ sudo cp /home/ubuntu/node/bor/start-config.toml /var/lib/bor/config.toml
$ sudo chown bor /var/lib/bor/config.toml

Configure service files for Bor and Heimdall

After successfully installing Bor and Heimdall through packages, their service file could be found under /lib/systemd/system, and Bor's config file could be found under /var/lib/bor/config.toml. You will need to check and modify these files accordingly.

- In the service file, set `--chain` to `mainnet` or `mumbai` accordingly

Save the changes in /lib/systemd/system/heimdalld.service.

Make sure the chain is set correctly in /var/lib/bor/config.toml file. Open the file with following command sudo vi /var/lib/bor/config.toml
- In the config file, set chain to mainnet or mumbai accordingly.
- To enable Archive mode, you can optionally enable the following flags:
```
gcmode "archive"

[jsonrpc]
  [jsonrpc.ws]
    enabled = true
    port = 8546
    corsdomain = ["*"]
```
Save the changes in /var/lib/bor/config.toml.

Starting the Sentry Node

You will first start the Heimdall service. Once the Heimdall service syncs, you will start the Bor service.

Reload service files

Reloading service files to make sure all changes to service files are loaded correctly.

sudo systemctl daemon-reload

Starting the Heimdall service

Start the Heimdall services:

sudo service heimdalld start

Check the Heimdall service logs:

journalctl -u heimdalld.service -f

note

In the logs, you may see the following errors:

Stopping peer for error
MConnection flush failed
use of closed network connection

These logs mean that one of the nodes on the network refused a connection to your node. Wait for your node to crawl more nodes on the network; you do not need to do anything to address these errors.

Check the Heimdalld logs:

journalctl -u heimdalld.service -f

Check the sync status of Heimdall:

curl localhost:26657/status

In the output, the catching_up value is:

true — the Heimdall service is syncing.
false — the Heimdall service is fully synced.

Wait for the Heimdall service to sync fully.

Starting the Bor service

Once the Heimdall service syncs, start the Bor service.

Start the Bor service:

sudo service bor start

Check the Bor service logs:

journalctl -u bor.service -f

Installing packages on the Validator Node

Follow the same installation steps on validator node.

Configuring the Validator Node

note

To complete this section, you must have an RPC endpoint of your fully synced Ethereum mainnet node ready.

caution

Bor and Heimdall 0.3.0 uses standardized paths for configuration files and chain data. If you have existing config files and chain data on your node, please jump directly to Migration section to learn about migrating configs and data to standardized file locations.

Configure Heimdall

Initialize heimdall configs

# For mainnet
sudo -u heimdall heimdalld init --chain=mainnet --home /var/lib/heimdall

# For testnet
sudo -u heimdall heimdalld init --chain=mumbai --home /var/lib/heimdall

Open the Heimdall configuration file for editing:

vi /var/lib/heimdall/config/config.toml

In config.toml, change the following:

moniker — any name. Example: moniker = "my-validator-node".
pex — set the value to false to disable the peer exchange. Example: pex = false.
private_peer_ids — comment out the value to disable it. Example: # private_peer_ids = "".
To get the node ID of Heimdall on the sentry machine:
1. Log in to the sentry machine.
2. Run heimdalld tendermint show-node-id.

Example: persistent_peers = "[email protected]_instance_ip:26656"

prometheus — set the value to true to enable the Prometheus metrics. Example: prometheus = true.

Save the changes in config.toml.

Open for editing vi /var/lib/heimdall/config/heimdall-config.toml.

In heimdall-config.toml, change the following:

eth_rpc_url — an RPC endpoint for a fully synced Ethereum mainnet node or testnet node, i.e Infura. eth_rpc_url =<insert Infura or any full node RPC URL to Ethereum>

Example: eth_rpc_url = "https://nd-123-456-789.p2pify.com/60f2a23810ba11c827d3da642802412a"

Save the changes in heimdall-config.toml.

Configuring Bor

In /var/lib/bor/config.toml, add the following:

[p2p]
    [p2p.discovery]
        static-nodes = ["<replace with enode://[email protected]_machine_ip:30303>"]

To get the node ID of Bor on the sentry machine:

Log into the sentry machine.
Run bor bootnode -node-key /var/lib/bor/data/bor/nodekey -dry-run.

Example output: "enode://410e359736bcd3a58181cf55d54d4e0bbd6db2939c5f548426be7d18b8fd755a0[email protected]134.209.100.175:30303".

Example content of static node field in /var/lib/bor/config.toml:

[p2p]
    [p2p.discovery]
        static-nodes = ["enode://410e359736bcd3a58181cf55d54d4e0bbd6db2939c5f548426be7d18b8fd755a0[email protected]134.209.100.175:30303"]

Save the changes in /var/lib/bor/config.toml.

Setting the Owner and Signer Key

On Polygon, it is recommended that you keep the owner and signer keys different.

Signer — the address that signs the checkpoint transactions. The recommendation is to keep at least 1 ETH on the signer address.
Owner — the address that does the staking transactions. The recommendation is to keep the MATIC tokens on the owner address.

Generating a Heimdall private key

You must generate a Heimdall private key only on the validator machine. Do not generate a Heimdall private key on the sentry machine.

To generate the private key, run:

heimdallcli generate-validatorkey ETHEREUM_PRIVATE_KEY

where

ETHEREUM_PRIVATE_KEY — your Ethereum wallet address.

This will generate priv_validator_key.json. Move the generated JSON file to the Heimdall configuration directory:

mv ./priv_validator_key.json /var/lib/heimdall/config

Generating a Bor keystore file

You must generate a Bor keystore file only on the validator machine. Do not generate a Bor keystore file on the sentry machine.

To generate the private key, run:

heimdallcli generate-keystore ETHEREUM_PRIVATE_KEY

where

ETHEREUM_PRIVATE_KEY — your Ethereum private key.

When prompted, set up a password to the keystore file.

This will generate a UTC-<time>-<address> keystore file.

Move the generated keystore file to the Bor configuration directory:

mv ./UTC-<time>-<address> /var/lib/bor/keystore/

Add password.txt

Make sure to create a password.txt file then add the Bor keystore file password right in the /var/lib/bor/password.txt file.

Add your Ethereum address

Open for editing vi /etc/matic/metadata.

In metadata, add your Ethereum address. Example: VALIDATOR_ADDRESS=0xca67a8D767e45056DC92384b488E9Af654d78DE2.

Save the changes in metadata.

Upgrade from 0.2.x to 0.3.x

Bor 0.3.0 and Heimdall 0.3.0 uses new CLIs and path standards. It is recommended to set up everything from a new machine. However, if you still want to perform upgrade on existing node, you need to follow one-time migration steps outlined below. If you are installing everything from a new machine, you can skip this section and continue to Configure service files.

Stop existing Heimdall and Bor services

sudo service bor stop
sudo service heimdalld stop
sudo service heimdalld-rest-server stop
sudo service heimdalld-bridge stop

Create a backup folder in case something went wrong

mkdir ./backup
mkdir ./backup/bin
mkdir -p ./backup/go/bin

Move old binaries

sudo mv /usr/bin/bor ./backup/bin
sudo mv /usr/bin/heimdalld ./backup/bin
sudo mv /usr/bin/heimdallcli ./backup/bin
sudo mv /usr/bin/bridge ./backup/bin
sudo mv $(go env GOPATH)/bin/bor ./backup/go/bin
sudo mv $(go env GOPATH)/bin/heimdalld ./backup/go/bin
sudo mv $(go env GOPATH)/bin/heimdallcli ./backup/go/bin
sudo mv $(go env GOPATH)/bin/bridge ./backup/go/bin

Move old service files

sudo mv /etc/systemd/system/bor.service ./backup
sudo mv /etc/systemd/system/heimdalld.service ./backup
sudo mv /etc/systemd/system/heimdalld-rest-server.service ./backup
sudo mv /etc/systemd/system/heimdalld-bridge.service ./backup

Migrate the Heimdall and Bor directory to /var/lib and change ownership:

sudo mv ~/.heimdalld /var/lib/heimdall
sudo mv ~/.bor /var/lib/bor
sudo chown -R heimdall /var/lib/heimdall
sudo chown -R bor /var/lib/bor

In case data copying is too slow or original data folder is mounted on a different device, you can create symlinks

sudo chown -R heimdall ~/.bor
sudo chown -R bor ~/.heimdalld
sudo rm -rf /var/lib/heimdall
sudo ln -nfs ~/.heimdalld /var/lib/heimdall
sudo ln -nfs ~/.bor /var/lib/bor
sudo chown -R heimdall /var/lib/heimdall
sudo chown -R bor /var/lib/bor

Copy configurations in node/bor/start.sh to bor configuration file /var/lib/bor/config.toml. Note that some flags are renamed in the new CLI, you can find the documentation for new CLI here and sample configuration file in launch repository.

You can use this util script to convert start.sh to a config.toml file on your host. Example usage:

$ git clone https://github.com/maticnetwork/bor.git
$ cd bor/scripts
$ BOR_DIR=/var/lib/bor ./getconfig.sh
* Path to start.sh: /home/ubuntu/node/bor/start.sh
* Your validator address (e.g. 0xca67a8D767e45056DC92384b488E9Af654d78DE2), or press Enter to skip if running a sentry node: 0xca67a8D767e45056DC92384b488E9Af654d78DE2
Thank you, your inputs are:
Path to start.sh: /home/ubuntu/node/bor/start.sh
Address: 0xca67a8D767e45056DC92384b488E9Af654d78DE2
Path to the config file: /home/ubuntu/node/bor/start-config.toml
...

$ sudo cp /home/ubuntu/node/bor/start-config.toml /var/lib/bor/config.toml
$ sudo chown bor /var/lib/bor/config.toml

Configure service files for bor and heimdall

Make sure the chain is set correctly in /lib/systemd/system/heimdalld.service file. Open the file with following command sudo vi /lib/systemd/system/heimdalld.service
- In the service file, set --chain to mainnet or mumbai accordingly
- Add --bridge --all to the heimdall command line for validator, example:
```
  ExecStart=/usr/local/bin/heimdalld start --home /var/lib/heimdall \
    --chain=mainnet \
    --bridge --all \
    --rest-server
```
Save the changes in /lib/systemd/system/heimdalld.service.
Make sure the chain is set correctly in /var/lib/bor/config.toml file. Open the file with following command sudo vi /var/lib/bor/config.toml
- In the config file, set chain to mainnet or mumbai accordingly.
- Enable validator flags, example:
```
[miner]
  mine = true
  gaslimit = 20000000
  gasprice = "30000000000"
  etherbase = "VALIDATOR ADDRESS"
  
[accounts]
  allow-insecure-unlock = true
  password = "/var/lib/bor/password.txt"
  unlock = ["VALIDATOR ADDRESS"]
```
Save the changes in /var/lib/bor/config.toml.

Starting the Validator Node

At this point, you must have:

The Heimdall service on the sentry machine syncs and is running.
The Bor service on the sentry machine running.
The Heimdall service and the Bor service on the validator machine configured.
Your owner and signer keys configured.

Reload service files

Reloading service files to make sure all changes to service files are loaded correctly.

sudo systemctl daemon-reload

Starting the Heimdall service

You will now start the Heimdall service on the validator machine. Once the Heimdall service syncs, you will start the Bor service on the validator machine.

note

The Heimdall service takes several days to sync from scratch fully.

Alternatively, you can use a maintained snapshot, which will reduce the sync time to a few hours. For detailed instructions, see Snapshot Instructions for Heimdall and Bor.

For snapshot download links, see Polygon Chains Snapshots.

Start the Heimdall services:

sudo service heimdalld start

Check the Heimdall service logs:

journalctl -u heimdalld.service -f

Check the sync status of Heimdall:

curl localhost:26657/status

In the output, the catching_up value is:

true — the Heimdall service is syncing.
false — the Heimdall service is synced.

Wait for the Heimdall service to fully sync.

Starting the Bor service

Once the Heimdall service on the validator machine syncs, start the Bor service on the validator machine.

Start the Bor service:

sudo service bor start

Check the Bor service logs:

journalctl -u bor.service -f

Health Checks with the Community

Now that your sentry and validator nodes are in sync and running, head over to Discord and ask the community to health-check your nodes.

Next Steps: Staking

Now that you have your sentry and validator nodes are health-checked, proceed to the Staking guide to start backing the network.

Overview​

Installing package​

Prerequisites​

Heimdall​

Bor​

Check installation​

Configuration​

Configure Heimdall​

Configure Bor​

Configuring a firewall​

Upgrade from 0.2.x to 0.3.x​

Configure service files for Bor and Heimdall​

Starting the Sentry Node​

Reload service files​

Starting the Heimdall service​

Starting the Bor service​

Installing packages on the Validator Node​

Configuring the Validator Node​

Configure Heimdall​

Configuring Bor​

Setting the Owner and Signer Key​

Generating a Heimdall private key​

Generating a Bor keystore file​

Add password.txt​

Add your Ethereum address​

Upgrade from 0.2.x to 0.3.x​

Configure service files for bor and heimdall​

Starting the Validator Node​

Reload service files​

Starting the Heimdall service​

Starting the Bor service​

Health Checks with the Community​

Next Steps: Staking​

Overview

Installing package

Prerequisites

Heimdall

Bor

Check installation

Configuration

Configure Heimdall

Configure Bor

Configuring a firewall

Upgrade from 0.2.x to 0.3.x

Configure service files for Bor and Heimdall

Starting the Sentry Node

Reload service files

Starting the Heimdall service

Starting the Bor service

Installing packages on the Validator Node

Configuring the Validator Node

Configure Heimdall

Configuring Bor

Setting the Owner and Signer Key

Generating a Heimdall private key

Generating a Bor keystore file

Add password.txt

Add your Ethereum address

Upgrade from 0.2.x to 0.3.x

Configure service files for bor and heimdall

Starting the Validator Node

Reload service files

Starting the Heimdall service

Starting the Bor service

Health Checks with the Community

Next Steps: Staking