Upgrading a Node
🎉 Introduction
If you want to support this free educational Cardano content or found the content helpful, visit cointr.ee to find our donation addresses. Much appreciated in advance. 🙏
📒Technical writing by Change Pool (ticker CHG)
Input-Output (IOHK) regularly releases new versions of Cardano Node via the cardano-node
GitHub repository. Carefully review release notes available in the repository for new features, configurations, known issues, technical specifications, related downloads, documentation, changelogs, assets and other details of each new release.
The Upgrading a Node topic describes how to upgrade a Cardano node to the latest version. Complete the following procedures on each block producer and relay node comprising your stake pool as needed to complete the upgrade.
💞 Upgrading Third-party Software
CNCLI
If you use CNCLI command line utilities developed by the Cardano Community, then upgrade to the latest version if a newer version is available.
Do not confuse the Cardano Community's CNCLI utilities with the cncli.sh
companion script for stake pool operators maintained by Guild Operators.
To upgrade the Cardano Community's CNCLI binary:
In a terminal window, type the following commands:
RELEASETAG=$(curl -s https://api.github.com/repos/cardano-community/cncli/releases/latest | jq -r .tag_name)
VERSION=$(echo ${RELEASETAG} | cut -c 2-)
echo "Installing release ${RELEASETAG}"
curl -sLJ https://github.com/cardano-community/cncli/releases/download/${RELEASETAG}/cncli-${VERSION}-ubuntu22-x86_64-unknown-linux-gnu.tar.gz -o /tmp/cncli-${VERSION}-ubuntu22-x86_64-unknown-linux-gnu.tar.gz
sudo tar xzvf /tmp/cncli-${VERSION}-ubuntu22-x86_64-unknown-linux-gnu.tar.gz -C /usr/local/bin/
2. To confirm that the new version of the CNCLI binary is installed, type:
cncli -V
If the command displays the latest version number, then the upgrade is successful.
Guild LiveView
Guild Operators maintains a set of tools to simplify operating a Cardano stake pool, including Guild LiveView. If you use the gLiveView script, then ensure that you are using the latest version prior to upgrading your Cardano node.
To upgrade the Guild LiveView tool manually:
To back up existing Guild LiveView script files, type the following commands where
<gLiveViewFolder>
is the folder where thegLiveView.sh
script is located on your computer:
cd <gLiveViewFolder>
mv gLiveView.sh gLiveView.sh.bak
mv env env.bak
2. To download the latest Guild LiveView script files, type:
curl -s -o gLiveView.sh https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/gLiveView.sh
curl -s -o env https://raw.githubusercontent.com/cardano-community/guild-operators/master/scripts/cnode-helper-scripts/env
3. To set file permissions on the gLiveView.sh
file that you downloaded in step 2, type:
chmod 755 gLiveView.sh
4. To set the CONFIG
and SOCKET
user variables in the env
file that you downloaded in step 2, type:
sed -i env \
-e "s/\#CONFIG=\"\${CNODE_HOME}\/files\/config.json\"/CONFIG=\"\${NODE_HOME}\/mainnet-config.json\"/g" \
-e "s/\#SOCKET=\"\${CNODE_HOME}\/sockets\/node0.socket\"/SOCKET=\"\${NODE_HOME}\/db\/socket\"/g"
5. As needed to configure Guild LiveView for your stake pool, use a text editor to transfer additional user variable definitions from the env.bak
file that you created in step 1 to the env
file that you downloaded in step 2.
6. To test the upgrade, type:
gLiveView.sh
If the upgrade is successful, then the terminal window displays the Guild LiveView dashboard having the version number of the latest release.
🔩Setting GHC and Cabal Versions
For each Cardano Node release, Input-Output recommends compiling binaries using specific versions of GHC and Cabal. For example, refer to Installing cardano-node and cardano-cli from source in the Cardano Developer Portal to determine the GHC and Cabal versions required for the current Cardano Node release. Table 1 lists GHC and Cabal version requirements for the current Cardano Node release.
Table 1 Current Cardano Node Version Requirements
March 25, 2024
8.9.1
8.10.7
3.8.1.0
To upgrade the GHCup installer for GHC and Cabal to the latest version:
In a terminal window, type:
ghcup upgrade
ghcup --version
To install other GHC versions:
In a terminal window, type the following commands where
<GHCVersionNumber>
is the GHC version that you want to install and use:
ghcup install ghc <GHCVersionNumber>
ghcup set ghc <GHCVersionNumber>
ghc --version
To install other Cabal versions:
In a terminal window, type the following commands where
<CabalVersionNumber>
is the Cabal version that you want to install and use:
ghcup install cabal <CabalVersionNumber>
ghcup set cabal <CabalVersionNumber>
cabal --version
To update Libsodium:
As of version 8.0.0, a new version of libsodium
is required.
cd $HOME/git
git clone https://github.com/input-output-hk/libsodium
cd libsodium
git checkout dbb48cc
./autogen.sh
./configure
make
make check
sudo make install
To update secp256k1:
As of version 8.9.0, a new version of libsecp256k1
is required
cd $HOME/git
git clone https://github.com/bitcoin-core/secp256k1
cd secp256k1
git checkout v0.3.2
./autogen.sh
./configure --enable-module-schnorrsig --enable-experimental
make
make check
sudo make install
sudo ldconfig
To install the blst library:
As of version 8.9.0, a new version of blst
is required.
cd $HOME/git
git clone https://github.com/supranational/blst
cd blst
git checkout v0.3.11
./build.sh
cat > libblst.pc << EOF
prefix=/usr/local
exec_prefix=\${prefix}
libdir=\${exec_prefix}/lib
includedir=\${prefix}/include
Name: libblst
Description: Multilingual BLS12-381 signature library
URL: https://github.com/supranational/blst
Version: 0.3.11
Cflags: -I\${includedir}
Libs: -L\${libdir} -lblst
EOF
sudo cp libblst.pc /usr/local/lib/pkgconfig/
sudo cp bindings/blst_aux.h bindings/blst.h bindings/blst.hpp /usr/local/include/
sudo cp libblst.a /usr/local/lib
sudo chmod u=rw,go=r /usr/local/{lib/{libblst.a,pkgconfig/libblst.pc},include/{blst.{h,hpp},blst_aux.h}}
📥Downloading New Configuration Files
A new Cardano Node release may include updated configuration files. If configuration files are updated for a release, then you need to download and install the new configuration files when you upgrade a node.
To download and install new Cardano Node configuration files:
To stop your Cardano node, type the following command in a terminal window where
<CardanoServiceName>
is the name of the systemd service running your Cardano node:
sudo systemctl stop <CardanoServiceName>.service
2. To back up the configuration files that your node currently uses, type the following commands as appropriate where <ConfigurationFileFolder>
is the path to the folder where the configuration files are located:
cd <ConfigurationFileFolder>
mv config.json config.bak
mv byron-genesis.json byron-genesis.bak
mv shelley-genesis.json shelley-genesis.bak
mv alonzo-genesis.json alonzo-genesis.bak
mv conway-genesis.json conway-genesis.bak
mv topology.json topology.bak
mv topology-legacy.json topology-legacy.bak
3. Using a Web browser, navigate to the Cardano Node GitHub repository, then browse to the latest release, then click to expand the Downloads dropdown list in the Technical Specification section of the release notes, and then click the Configuration Files link.
4. On the Cardano Configurations page, click the following links to download configuration files for the mainnet
cluster to the folder where you created backups of your current configuration files in step 2: config
, byronGenesis
, shelleyGenesis
, alonzoGenesis, conwayGenesis
and topology
As of version 8.9.0, you need to download a new config file, conway-genesis.json
cd <ConfigurationFileFolder>
wget https://book.world.dev.cardano.org/environments/mainnet/conway-genesis.json
Then, verify config.json
contains the following two lines:
"ConwayGenesisFile": "conway-genesis.json",
"ConwayGenesisHash": "de609b281cb3d8ae91a9d63a00c87092975612d603aa54c0f1c6a781e33d6e1e",
5. Using diff
or a similar file comparison utility, identify and copy customizations as needed from the backup configuration files that you created in step 2 to each new configuration file that you downloaded in step 4.
The config.json
file contains hashes for the byron-genesis.json
, shelley-genesis.json
, alonzo-genesis.json
and conway-genesis.json
files using the ByronGenesisHash
, ShelleyGenesisHash
, AlonzoGenesisHash
and ConwayGenesisHash
keys, respectively. Therefore, do NOT manually edit the *genesis.json
files.
⚡Installing New Cardano Binaries
Either build the latest binaries or download pre-built binaries that may be available from IOHK
2. To verify that you installed the new Cardano Node binaries successfully, type:
cardano-node version
cardano-cli version
3. Restart your Cardano node systemd service to finish the upgrade process.
sudo systemctl restart cardano-node
4. Optionally, to install the latest versions of all previously installed packages on your computer, and then reboot the computer, type:
sudo apt-get update && sudo apt-get upgrade -y && sudo reboot
6. Copy the new cardano-cli
binary to the air-gapped, offline computer that you use to sign transactions for your stake pool.
7. On your air-gapped, offline computer, ensure that libsecp256k1 and blst are installed and up to date.
🏁Verifying the Upgrade
To verify that the upgrade is successful, open gLiveView, journalctl logs or Grafana dashboard.
cd ${NODE_HOME}
./gLiveView.sh
After an upgrade, starting a node may take up to a few hours. Be patient.
Congrats on completing the update. ✨
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 our stake pool community on Telegram @ https://t.me/coincashew
🚨Troubleshooting
If your upgrade is unsuccessful, then try Fixing a Corrupt Blockchain and Resetting an Installation, as needed.