English
How to setup an external passive relay node
This quick start guide walks through setting up an external relay node with the help of CNTOOLs.
Major credits and appreciation to the fine folks at Cardano Community Guild Operators for creating and maintaining CNtool, a most helpful swiss army knife for pool operators. You MUST be familiar with how ADA staking works and possess fundamental Linux system administration skills before continuing this guide.
Relay nodes do not have any keys, so they cannot produce blocks. Instead, relays act as proxies between the core network nodes and the internet, establishing a security perimeter around the core, block-producing network nodes. Since external nodes cannot communicate with block-producing nodes directly, relay nodes ensure that the integrity of the core nodes and the blockchain remains intact, even if one or more relays become compromised.

โ€‹
๐ŸŒœ
0. Prerequisites

  • A different server/VM (not located on the same machine as your block-producer node)

โ€‹
๐Ÿ›ธ
1. Run prereqs.sh

Installs prerequisite dependencies and creates folder structure.
1
sudo apt-get install curl net-tools
Copied!
1
mkdir "$HOME/tmp";cd "$HOME/tmp"
2
# Install curl
3
# CentOS / RedHat - sudo dnf -y install curl
4
# Ubuntu / Debian - sudo apt -y install curl
5
curl -sS -o prereqs.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/prereqs.sh
6
chmod 755 prereqs.sh
7
โ€‹
8
# Ensure you can run sudo commands with your user before execution
9
# You can check the syntax for prereqs.sh using command below:
10
#
11
# ./prereqs.sh -h
12
# Usage: prereqs.sh [-o] [-s] [-i] [-g] [-p]
13
# Install pre-requisites for building cardano node and using cntools
14
# -o Do *NOT* overwrite existing genesis, topology.json and topology-updater.sh files (Default: will overwrite)
15
# -s Skip installing OS level dependencies (Default: will check and install any missing OS level prerequisites)
16
# -i Interactive mode (Default: silent mode)
17
# -g Connect to guild network instead of public network (Default: connect to public cardano network)
18
# -p Copy Transitional Praos config as default instead of Combinator networks (Default: copies combinator network)
19
โ€‹
20
# You can use one of the options above, if you'd like to defer from defaults (below).
21
# Running without any parameters will run script in silent mode with OS Dependencies, and overwriting existing files.
22
โ€‹
23
./prereqs.sh
Copied!
Reload environment variables.
1
. "${HOME}/.bashrc"
Copied!
Familiarize yourself with the folder structure created by CNtools.

โ€‹
๐Ÿคนโ™€
2. Build Cardano Node and CLI

Clone the git repository.

1
cd ~/git
2
git clone https://github.com/input-output-hk/cardano-node
3
cd cardano-node
Copied!

Build all the binaries. Replace the tag with the desired version.

1
git fetch --tags --all
2
git pull
3
# Replace tag 1.26.2 with the version/branch you'd like to build
4
git checkout 1.26.2
5
โ€‹
6
echo -e "package cardano-crypto-praos\n flags: -external-libsodium-vrf" > cabal.project.local
7
$CNODE_HOME/scripts/cabal-build-all.sh
Copied!

Install binaries to local bin directory.

1
sudo cp $HOME/.cabal/bin/cardano* /usr/local/bin
Copied!

Verify the correct versions were compiled.

1
cardano-cli version
2
cardano-node version
Copied!

โ€‹
โš’
3. Auto-starting with systemd services

โ€‹
๐ŸŽŠ
Benefits of using systemd for your stake pool

  1. 1.
    Auto-start your node when the computer reboots due to maintenance, power outage, etc.
  2. 2.
    Automatically restart crashed node processes.
  3. 3.
    Maximize your stake pool up-time and performance.
1
sudo bash -c "cat << 'EOF' > /etc/systemd/system/cnode.service
2
[Unit]
3
Description=Cardano Node
4
After=network.target
5
โ€‹
6
[Service]
7
Type=simple
8
Restart=on-failure
9
RestartSec=5
10
User=$USER
11
LimitNOFILE=1048576
12
WorkingDirectory=$CNODE_HOME/scripts
13
ExecStart=/bin/bash -l -c \"exec $CNODE_HOME/scripts/cnode.sh\"
14
ExecStop=/bin/bash -l -c \"exec kill -2 \$(ps -ef | grep [c]ardano-node.*.${CNODE_HOME} | tr -s ' ' | cut -d ' ' -f2)\"
15
KillSignal=SIGINT
16
SuccessExitStatus=143
17
StandardOutput=syslog
18
StandardError=syslog
19
SyslogIdentifier=cnode
20
TimeoutStopSec=5
21
KillMode=mixed
22
โ€‹
23
[Install]
24
WantedBy=multi-user.target
25
EOF"
26
โ€‹
27
sudo systemctl daemon-reload
28
sudo systemctl enable cnode.service
Copied!
Nice work. Your node is now managed by the reliability and robustness of systemd. Below are some commands for using systemd.

โœ…
Check whether the node service is active

1
sudo systemctl is-active cnode
Copied!

โ€‹
๐Ÿ”Ž
View the status of the node service

1
sudo systemctl status cnode
Copied!

โ€‹
๐Ÿ”„
Restarting the node service

1
sudo systemctl reload-or-restart cnode
Copied!

โ€‹
๐Ÿ›‘
Stopping the node service

1
sudo systemctl stop cnode
Copied!

โ€‹
๐Ÿšง
Filtering logs

1
journalctl --unit=cnode --since=yesterday
2
journalctl --unit=cnode --since=today
3
journalctl --unit=cnode --since='2020-07-29 00:00:00' --until='2020-07-29 12:00:00'
Copied!

โ€‹
๐Ÿš€
4. Start the relay node

Pro tip:
๐ŸŽ‡
Speed this step up by copying the db folder from another node you control.
1
sudo systemctl start cnode
Copied!
Install Guild LiveView.
1
cd $CNODE_HOME/scripts
2
curl -s -o gLiveView.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
3
curl -s -o env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env
4
chmod 755 gLiveView.sh
Copied!
Run Guild Liveview.
1
./gLiveView.sh
Copied!
Sample output of Guild Live View
For more information, refer to the official Guild Live View docs.โ€‹

โ€‹
๐Ÿ›‘
5. Configure and review the relay node topology file

Modify the CUSTOM_PEERS section of the topologyUpdater.sh script to configure your relay node's connections to your other relays and block producer node. Refer to the official documentation for more info.โ€‹
1
nano $CNODE_HOME/scripts/topologyUpdater.sh
Copied!
Deploy the scripts with deploy-as-systemd.sh to setup and schedule the execution. This will handle automatically sending updates to the Topology Updater API as well as fetching new peers whenever the node is restarted.
1
$CNODE_HOME/scripts/deploy-as-systemd.sh
Copied!
Review your topology.json and check that it looks correct. Your new relay node's topology should contain your block producer node, your other relay nodes, and other public buddy relay nodes.
1
cat $CNODE_HOME/files/topology.json
Copied!

โ€‹
๐Ÿ”ฅ
6. Configure port-forwarding and/or firewall

Specific to your networking setup or cloud provider settings, ensure your relay node's port 6000 is open and reachable.
โ€‹
โœจ
Port Forwarding Tip: Check that your relay port 6000 is open with https://www.yougetsignal.com/tools/open-ports/ or https://canyouseeme.org/ .
Additionally, if you have node-exporter installed for grafana stats, you will need to open ports 9100 and 12798. Don't forget to update prometheus.yml on your prometheus server (aka relaynode1). Restart prometheus service for the new relay node to appear in your dashboard.

โ€‹
๐Ÿ‘ฉ๐Ÿ’ป
7. Configure existing relay or block producing node's topology

Finally, add your new NEW relay node IP/port information to your EXISTING block producer and/or relay node's topology file. Modify the CUSTOM_PEERS section of the topologyUpdater.sh
For your block producer node, you'll want to manually add the new relay node information to your topology.json file.
Example snippet to add to your block producer's topology file. Add a comma to separate the nodes where appropriate.
1
{
2
"addr": "<relay node public ip address>",
3
"port": 6000,
4
"valency": 1
5
}
Copied!
For relay nodes, use the topologyUpdater process to manage your topology file or modify the CUSTOM_PEERS section of the topologyUpdater.sh.

โ€‹
๐Ÿ”„
8. Restart all relay and block producer nodes for new topology configurations to take effect

โ€‹
๐ŸŽŠ
9. Verify the connection is working

On the Guild LiveView screen, press P to view the peer list. You should see the connection to other node's IP.
โ€‹
โœจ
Congrats on the new relay node.
โ€‹
๐Ÿ”ฅ
Critical Security Reminder: Relay nodes must not contain any operational certifications, vrf, skey or cold keys.
Congrats on completing the guide.
โœจ
Did you find our guide useful? Send us a signal with a tip and we'll keep updating it.
It really energizes us to keep creating the best crypto guides.
Use cointr.ee to find our donation addresses.
๐Ÿ™
Any feedback and all pull requests much appreciated.
๐ŸŒ›
Hang out and chat with fellow stake pool operators on Discord @
Hang out and chat with our stake pool community on Telegram @ https://t.me/coincashewโ€‹
Last modified 8mo ago