Skip to main content

🚄 Setup and run a Collator

Installation > Configuration > Running > Sync > Session keys > Bond

📝 Configuration​

some extra command line parameters are required or helpful for collating.

edit the manta service unit file to include collation parameters in the ExecStart command.

/usr/lib/systemd/system/manta.service

for version >= v4.6.0 (inclusive)

ExecStart=/usr/bin/manta \
    --collator \
    --name 'my parachain collator node name' \
    --chain /usr/share/substrate/manta.json \
    --base-path /var/lib/substrate \
    --port 31333 \
    --rpc-max-connections 100 \
    --rpc-port 9144 \
    --rpc-cors all \
    --rpc-methods auto \
    --prometheus-port 9615 \
    --prometheus-external \
    --state-cache-size 0 \
    --bootnodes \
      /dns/a1.manta.systems/tcp/30333/p2p/12D3KooWCpnkG834s9ETesFTWtGqRDjs6Te1UCXHib3iD8GEmXLU \
      /dns/a4.manta.systems/tcp/30333/p2p/12D3KooWN9Zud842idiiUypJF9nzQfNrSsuWQRdtRA8D6sqsPXMb \
      /dns/a5.manta.systems/tcp/30333/p2p/12D3KooWM6Txo8orkxGsSTPByzzWhtTSfdFi2u9KJtd9eWCkry3k \
      /dns/a7.manta.systems/tcp/30333/p2p/12D3KooWFKMcE12XRLZfktX3crfkZyyBetpHsffDjPopYVhQLXwP \
      /dns/c1.manta.systems/tcp/30333/p2p/12D3KooWSNwD7tJkqKGdMfCVTJbbzrGFTGbXoeMFZCTwEytpFCM4 \
    -- \
    --name 'my embedded relay node name' \
    --chain /usr/share/substrate/polkadot.json \
    --port 31334 \
    --rpc-port 9145 \
    --prometheus-port 9616 \
    --prometheus-external \
    --telemetry-url 'wss://api.telemetry.manta.systems/submit/ 0'

for version < v4.6.0 (exclusive)

ExecStart=/usr/bin/manta \
    --collator \
    --name 'my parachain collator node name' \
    --chain /usr/share/substrate/manta.json \
    --base-path /var/lib/substrate \
    --port 31333 \
    --ws-port 9144 \
    --ws-max-connections 100 \
    --rpc-port 9133 \
    --rpc-cors all \
    --rpc-methods auto \
    --prometheus-port 9615 \
    --prometheus-external \
    --state-cache-size 0 \
    --bootnodes \
      /dns/a1.manta.systems/tcp/30333/p2p/12D3KooWCpnkG834s9ETesFTWtGqRDjs6Te1UCXHib3iD8GEmXLU \
      /dns/a4.manta.systems/tcp/30333/p2p/12D3KooWN9Zud842idiiUypJF9nzQfNrSsuWQRdtRA8D6sqsPXMb \
      /dns/a5.manta.systems/tcp/30333/p2p/12D3KooWM6Txo8orkxGsSTPByzzWhtTSfdFi2u9KJtd9eWCkry3k \
      /dns/a7.manta.systems/tcp/30333/p2p/12D3KooWFKMcE12XRLZfktX3crfkZyyBetpHsffDjPopYVhQLXwP \
      /dns/c1.manta.systems/tcp/30333/p2p/12D3KooWSNwD7tJkqKGdMfCVTJbbzrGFTGbXoeMFZCTwEytpFCM4 \
    -- \
    --name 'my embedded relay node name' \
    --chain /usr/share/substrate/polkadot.json \
    --port 31334 \
    --ws-port 9145 \
    --rpc-port 9134 \
    --prometheus-port 9616 \
    --prometheus-external \
    --telemetry-url 'wss://api.telemetry.manta.systems/submit/ 0'

note passing --relay-chain-rpc-urls <rpc_url> to the parachain parameter section in the startup command will delegate relay chain data to remote relaychain rpc, it's recommanded to not do this, however this can be handy at times when local relay chain data fails to sync (related artcle https://mantanetwork.notion.site/Manta-Atlantic-Block-Production-Accident-Report-9a3742c6e0844d78a32e76fc47cf0cc0), below is an example

ExecStart=/usr/bin/manta \
    --collator \
    --name 'my parachain collator node name' \
    --chain /usr/share/substrate/manta.json \
    --base-path /var/lib/substrate \
    --port 31333 \
...
    --state-cache-size 0 \
    --relay-chain-rpc-urls "wss://1rpc.io/dot" \
    --relay-chain-rpc-urls "wss://polkadot-public-rpc.blockops.network/ws" \
    --relay-chain-rpc-urls "wss://polkadot.api.onfinality.io/public-ws" \
    --relay-chain-rpc-urls "wss://rpc.ibp.network/polkadot" \
    --relay-chain-rpc-urls "wss://polkadot-rpc.dwellir.com" \
    --relay-chain-rpc-urls "wss://polkadot-rpc-tn.dwellir.com" \
    --relay-chain-rpc-urls "wss://rpc.dotters.network/polkadot" \
    --relay-chain-rpc-urls "wss://rpc-polkadot.luckyfriday.io" \
    --relay-chain-rpc-urls "wss://polkadot.public.curie.radiumblock.co/ws" \
    --relay-chain-rpc-urls "wss://rockx-dot.w3node.com/polka-public-dot/ws" \
    --relay-chain-rpc-urls "wss://dot-rpc.stakeworld.io" \
    --bootnodes \
      /dns/a1.manta.systems/tcp/30333/p2p/12D3KooWCpnkG834s9ETesFTWtGqRDjs6Te1UCXHib3iD8GEmXLU \
      /dns/a4.manta.systems/tcp/30333/p2p/12D3KooWN9Zud842idiiUypJF9nzQfNrSsuWQRdtRA8D6sqsPXMb \
...
    -- \
    --name 'my embedded relay node name' \
    --chain /usr/share/substrate/polkadot.json \
    --port 31334 \
...

parameters with special significance for collator maintainers​

two sets of parameters are supplied to the substrate node binary (manta), separated by a double-dash (--). the first set controls the behavior of the parachain node. the second set controls the behaviour of the embedded relay-chain node.

  • significant parachain parameters
    • --collator: run in collator mode. behaves the same as --validator on relay chains. setting this also causes pruning mode to be set to archive (like --pruning archive).
    • --name: parachain node name, displayed on manta telemetry.
    • --port: parachain peer-to-peer port. manta default is 31333. this port must be accessible over the internet to other manta nodes.
    • --prometheus-port: parachain metrics port. manta default is 9615. this port must be accessible to the manta metrics monitor at: 18.156.192.254 (18.156.192.254/32 if you are specifying by subnet)
    • --prometheus-external: if you are not reverse proxying metrics over ssl, you may need to set this parameter to tell the embedded metrics server to listen on the all ips socket (0.0.0.0:9615) rather than localhost only (127.0.0.1:9615)
    • --relay-chain-rpc-urls: list of relay chain full node to communicate with, if this parameter is specified, the node will delegate relay chain data to the relay chain rpc endpoints, local relay chain data won't be used/synced. This parameter is not recommanded, however this can be handy at times when local relay chain data can't sync. (list of official polkadot relay chain rpc endpoints can be found on polkadot rpc endpoints)
  • significant relay-chain parameters
    • --name: relay-chain node name, displayed on polkadot telemetry.
    • --port: relay-chain peer-to-peer port. manta-embedded-polkadot default is 31334. this port must be accessible over the internet to other polkadot nodes.
    • --prometheus-port: relay-chain metrics port. manta-embedded-polkadot default is 9616. this port must be accessible to the manta metrics monitor at: 18.156.192.254 (18.156.192.254/32 if you are specifying by subnet)
    • --prometheus-external: if you are not reverse proxying metrics over ssl, you may need to set this parameter to tell the embedded metrics server to listen on the all ips socket (0.0.0.0:9616) rather than localhost only (127.0.0.1:9616)

expose node metrics for monitoring​

you should monitor your own collator using the techniques described on the polkadot wiki. the metrics exposed on ports 9615 and 9616 facilitate this, so these ports (or port 443, if ssl proxied) should be accessible both from your own prometheus/alertmanager server (which you should configure to alert you, using alertmanager) and manta's pulse server at 18.156.192.254 (which is monitored by manta devops).

firewall configuration​

several ports are required to be accessible from outside of the node host in order for the collator to function well. for simplicity, the settings documented below use the default ports, however feel free to use alternative ports as required by your infrastructure and network topology.

30333: default manta peer-to-peer port
30334: default (embedded-relay) polkadot peer-to-peer port
9615: default manta metrics port
9616: default (embedded-relay) polkadot metrics port

reverse proxy metrics over ssl with letsencrypt and nginx​

it is good practice to serve your metrics over:

  • ssl, so that their authenticity and provenance can be verified
  • dns, so that changes to your ip address don't require a pulse server update

it also makes it much easier for an alert observer to work out which collators are performing well (or poorly) when they are looking at domain names like manta.awesome-host.awesome-collators.com versus ip addresses and port combinations like 123.123.123.123:987 which may not make it obvious wich collator is being observed and wether the metric in question refers to the relay-chain or parachain.

an easy way to accomplish this is to install certbot and nginx and configure a reverse proxy listening on port 443 and which proxies ssl requests to the local metrics ports.

the example below assumes:

  • you administer the domain example.com
  • its dns is managed by cloudflare or route53
  • your nodes hostname is bob
  • your manta node uses default ports
  • your internet gateway (router) port forwards 443/ssl traffic arriving on the routers wan interface to your collator node
  • you have certbot installed
note

cloudflare and route53 examples follow. google python3-certbot-dns-${your_dns_provider} for other examples

  • install certbot and a dns validation plugin

    #!/bin/bash

    sudo dnf install \
      certbot \
      python3-certbot-dns-cloudflare \
      python3-certbot-dns-route53

  • request a cert using a dns plugin so that certbot is able to automatically renew the cert near the expiry date. manually requested certs must be manually updated to keep ssl certs valid, so they should be avoided.

    #!/bin/bash

    sudo certbot certonly \
      --dns-cloudflare \
      --dns-cloudflare-credentials .cloudflare-credentials \
      -d bob.example.com \
      -d manta.metrics.bob.example.com \
      -d polkadot.metrics.bob.example.com

  • configure nginx /etc/nginx/sites-enabled/example.com.conf to reverse proxy dns subdomains to local metrics ports.

    server {
      server_name manta.metrics.bob.example.com;
      listen 443 ssl;
      gzip off;
      location / {
        proxy_pass http://127.0.0.1:9615;
        proxy_http_version 1.1;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
      }
      ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
      include /etc/letsencrypt/options-ssl-nginx.conf;
      ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    }

    server {
      server_name polkadot.metrics.bob.example.com;
      listen 443 ssl;
      gzip off;
      location / {
        proxy_pass http://127.0.0.1:9616;
        proxy_http_version 1.1;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
      }
      ssl_certificate /etc/letsencrypt/live/bob.example.com/fullchain.pem;
      ssl_certificate_key /etc/letsencrypt/live/bob.example.com/privkey.pem;
      include /etc/letsencrypt/options-ssl-nginx.conf;
      ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    }
#!/bin/bash

default_zone=$(sudo firewall-cmd --get-default-zone)

# manta p2p
sudo firewall-cmd \
  --zone=${default_zone} \
  --add-port=31333/tcp \
  --permanent

# polkadot p2p
sudo firewall-cmd \
  --zone=${default_zone} \
  --add-port=31334/tcp \
  --permanent

# manta metrics
sudo firewall-cmd \
  --zone=${default_zone} \
  --add-port=9615/tcp \
  --permanent

# polkadot metrics
sudo firewall-cmd \
  --zone=${default_zone} \
  --add-port=9616/tcp \
  --permanent

sudo firewall-cmd --reload