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.

To receive notifications related to activity in the Cardano Node GitHub repository, configure Watch functionality.

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.

For instructions on upgrading your stake pool to a previous Cardano version, see the archive.

💞 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:

1. 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.

In the Common env file for Guild Operator scripts, by default the UPDATE_CHECK user variable is set to check for updates to scripts when you start gLiveView.sh. If your implementation displays the message Checking for script updates when gLiveView starts and you install available updates when prompted, then you do NOT need to complete the following procedure.

To upgrade the Guild LiveView tool manually:

1. To back up existing Guild LiveView script files, type the following commands where <gLiveViewFolder> is the folder where the gLiveView.sh script is located on your computer:

cd <gLiveViewFolder>
mv gLiveView.sh gLiveView.sh.bak
mv env env.bak

If you follow the Coin Cashew instructions for Starting the Nodes, then you can type $NODE_HOME to replace

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"

For details on setting the NODE_HOME environment variable, see the topic Installing Cabal and GHC

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

Release Date	Cardano Node Version	Cardano CLI Version	GHC Version	Cabal Version
November 2024	10.1.2	10.1.1.0	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 set GHCup, GHC and Cabal versions using a graphical user interface, type ghcup tui in a terminal window.

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 --depth 1 --branch v0.3.2 https://github.com/bitcoin-core/secp256k1
cd secp256k1
./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:

1. 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

If you follow the Coin Cashew instructions for Creating Startup Scripts, then <CardanoServiceName> is cardano-node

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

If you follow the Coin Cashew instructions for Preparing Configuration Files, then <ConfigurationFileFolder> is $HOME/cardano-my-node Alternately, you can type $NODE_HOME If needed, you can also use the environment variable $NODE_CONFIG to indicate the mainnet cluster in configuration file names.

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",

If you want to download new configuration files using the command line, then navigate to the folder where you created backups of your current configuration files in step 2 using a terminal window, and then type the following command where <ConfigurationFileURL> is the URL for the configuration file that you want to download: wget <ConfigurationFileURL>

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

You can install pre-built Cardano Node binaries available for download from the Cardano Node GitHub repository, or you can download the source code and compile the binaries yourself.

Using Pre-built Binaries

To install pre-built Cardano Node binaries:

1. To create a temporary path to store the pre-built binaries, type:

mkdir ~/tmp2
cd ~/tmp2

1. Using a Web browser, visit the Releases page for the Cardano Node GitHub repository, and then scroll down to the Assets section for the Cardano Node release you want to install. Right-click the archive containing the binaries that you want to install, and then click Copy Link

2. To download the binaries, type the following commands where the link that you copied in step 2:

wget <BinaryURL>

1. To extract the archive that you downloaded in step 3, type:

tar -xvf ./cardano*.gz

1. To install the new node and cli binaries, type:

sudo mv ~/tmp2/bin/cardano-cli /usr/local/bin/

sudo mv ~/tmp2/bin/cardano-node /usr/local/bin/

1. To delete the temporary folder, type:

cd ..
rm -rf ~/tmp2

1. Complete the upgrade.

Compiling the Binaries

To build binaries for a new Cardano Node version:

1. To create a clone of the Cardano Node GitHub repository, type the following commands in a terminal window on the computer you want to upgrade where <NewFolderName> is the name of a folder that does not exist:

# Navigate to the folder where you want to clone the repository
cd $HOME/git
# Download the Cardano Node repository to your local computer
git clone https://github.com/IntersectMBO/cardano-node.git ./<NewFolderName>

Cloning the GitHub repository to a new folder allows you to roll back the upgrade, if needed, by re-installing on your computer the cardano-node and cardano-cli binaries from a folder where you compiled a previous version of Cardano Node packages.

2. To build Cardano Node binaries using the source code that you downloaded in step 1, type the following commands where <NewFolderName> is the name of the folder you created in step 1 and <GHCVersionNumber> is the GHC version that you set in the section Setting GHC and Cabal Versions:

# Navigate to the folder where you cloned the Cardano Node repository
cd $HOME/git/<NewFolderName>
# Update the list of available packages
cabal update
# Download all branches and tags from the remote repository
git fetch --all --recurse-submodules --tags
# Switch to the branch of the latest Cardano Node release
git checkout $(curl -s https://api.github.com/repos/IntersectMBO/cardano-node/releases/latest | jq -r .tag_name)
# Adjust the project configuration to disable optimization and use the recommended compiler version
cabal configure -O0 -w ghc-<GHCVersionNumber>
# Compile the cardano-node and cardano-cli packages found in the current directory
cabal build all
cabal build cardano-cli

The time required to compile the cardano-node and cardano-cli packages may be a few minutes to hours, depending on the specifications of your computer.

3. When the compiler finishes, to verify the version numbers of the new cardano-node and cardano-cli binaries type:

$(./scripts/bin-path.sh cardano-node) version
$(./scripts/bin-path.sh cardano-cli) version

To install the binaries that you compiled:

1. If your Cardano node is running, then type the following command to stop the node where <CardanoServiceName> is the name of the systemd service running your node:

sudo systemctl stop <CardanoServiceName>.service

2. To replace the existing cardano-node and cardano-cli binaries, type the following commands where <DestinationPath> is the absolute file path to the folder where you install Cardano Node binaries on your local computer:

sudo cp -p "$(./scripts/bin-path.sh cardano-node)" <DestinationPath>/cardano-node
sudo cp -p "$(./scripts/bin-path.sh cardano-cli)" <DestinationPath>/cardano-cli

If you follow the Coin Cashew instructions for Compiling Source Code, then <DestinationPath> is /usr/local/bin

Completing the Upgrade

To finish upgrading Cardano Node binaries:

1. To verify that you installed the new Cardano Node binaries successfully, type:

cardano-node version
cardano-cli version

2. Restart your Cardano node systemd service to finish the upgrade process.

sudo systemctl restart cardano-node

3. 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

Upgrading to a new Cardano Node version may require replaying the copy of the blockchain residing on the local computer. The task of replaying the blockchain may require hours to complete.

To monitor your node, type the command journalctl -fu cardano-nodein a terminal window.

4. Copy the new cardano-cli binary to the air-gapped, offline computer that you use to sign transactions for your stake pool.

5. 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.

gLiveView

cd ${NODE_HOME}
./gLiveView.sh

journalctl

journalctl -fu cardano-node

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.