Skip to main content

Upgrading a Node

🎉 Introduction​

Input-Output (IOHK) regularly releases new versions of Cardano Node via the official 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.

note

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 instance to the latest version. Complete the following procedures on each block producer and relay node comprising your stake pool configuration as needed to complete the upgrade.

Setting GHC and Cabal Versions ​

For each Cardano Node release, Input-Output recommends compiling binaries using specific versions of GHC and Cabal. Table 1 lists GHC and Cabal version requirements for the current Cardano Node release.

Table 1 Current Cardano Node Version Requirements

Release DateCardano Node VersionCardano CLI VersionCardano Tracer VersionGHC VersionCabal Version
September 202611.1.311.2.3.00.5.09.6.73.12.1.0

To set GHCup, GHC and Cabal versions using a graphical user interface, type the following command using a terminal window:

ghcup tui

To upgrade the GHCup installer for GHC and Cabal to the latest version using the command line, type:

ghcup upgrade
ghcup --version

To install other GHC versions using the command line:

  • 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 using the command line:

  • 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

Upgrading Shared Libraries​

Compare the versions of shared libraries appearing in the Installing Shared Libraries topic with the versions installed on each computer hosting a Cardano Node instance in your stake pool configuration. If the versions installed on computers in your stake pool configuration are different, then follow the procedures as needed to upgrade shared libraries.

Updating Configuration Files​

A new Cardano Node release may revise existing configuration files and/or introduce additional configuration files. If configuration files are revised or new configuration files are introduced, then you need to download and implement the latest configuration files when upgrading a node.

To download and install the latest Cardano Node configuration files:

  1. To stop an instance of Cardano Node, type the following command using a terminal window where <CardanoServiceName> is the name of the systemd service running Cardano Node:
sudo systemctl stop <CardanoServiceName>.service
info

If you follow the CoinCashew instructions for Automating Cardano Node Startup, 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 and <ConfigFileName> is config-bp on your block-producing node and config on all your relay nodes:

cd <ConfigurationFileFolder>
mv <ConfigFileName>.json <ConfigFileName>.bak
mv tracer-config.json tracer-config.bak
mv topology.json topology.bak
mv peer-snapshot.json peer-snapshot.bak
mv checkpoints.json checkpoints.bak
info

If you follow the CoinCashew instructions for Downloading Configuration Files, then <ConfigurationFileFolder> is $NODE_HOME If needed, you can also use the environment variable $NODE_CONFIG to indicate the mainnet environment 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. In The Cardano Operations Book, in the left navigation click the name of the environment that the node you are upgrading uses. Click the links to download the following configuration files to the folder where you created backups of your current configuration files in step 2:

  • config.json
  • tracer-config.json
  • topology.json
  • peer-snapshot.json
  • checkpoints.json
info

If you want to download 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. If you are upgrading the Cardano Node instance running on the block-producing node in your stake pool configuration, then type the following commands using a terminal window on the block producer to rename the node configuration file:

cd ${NODE_HOME}
mv config.json config-bp.json

6. Using diff or a similar file comparison utility, identify and copy customizations as needed from the config*.bak, tracer-config.bak and topology.bak configuration file backups that you created in step 2 to the respective configuration file that you downloaded in step 4.

warning

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

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

3. To download the binaries, type the following commands where <BinaryURL> is the link that you copied in step 2:

wget <BinaryURL>

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

tar -xvf ./cardano*.gz

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

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

6. To delete the temporary folder, type:

cd ..
rm -rf ~/tmp2

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

# Ensure that development headers for the libsodium cryptographic library are NOT installed on the local computer
sudo apt remove libsodium-dev
# Install new packages required for Cardano Node 10.7.1 and above
sudo apt-get install libsnappy-dev protobuf-compiler liburing-dev -y
# 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-9.6.7
# Compile the cardano-node, cardano-cli and cardano-tracer packages found in the current directory
cabal build all
cabal build cardano-cli
cabal build cardano-tracer

The time required to compile the cardano-node, cardano-cli and cardano-tracer 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, cardano-cli and cardano-tracer binaries type:

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

To install the binaries that you compiled:

  1. If 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, cardano-cli and cardano-tracer 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
sudo cp -p "$(./scripts/bin-path.sh cardano-tracer)" <DestinationPath>/cardano-tracer
info

If you follow the CoinCashew instructions for Compiling Cardano Node, then <DestinationPath> is /usr/local/bin

Implementing Cardano Tracer​

Cardano Tracer provides flexible and efficient monitoring of Cardano Node instances in your stake pool configuration using a modular configuration, ensuring that Cardano Node focuses on core operations while Tracer manages logging, monitoring and external communication.

By default, Cardano Node 10.6.2 and above enable Cardano Tracer.

Important
Important

The old tracing mechanism is deprecated. Implementing Cardano Tracer is required.

To implement Cardano Tracer:

1. On the computer hosting the block-producing node in your stake pool configuration, follow the procedure for Running Cardano Tracer Automatically.

2. In the $NODE_HOME/startCardanoNode.sh file on the block-producing node, add the --tracer-socket-path-connect option to the cardano-node run command. For more details, refer to the topic Automating Cardano Node Startup.

3. To open the cardano-node.service file on the block-producing node using a text editor, type:

sudo nano /etc/systemd/system/cardano-node.service

4. In the cardano-node.service file, edit the following lines in the [Unit] block:

Wants = network-online.target cardano-tracer.service
After = network-online.target cardano-tracer.service

4. To save and close the cardano-node.service file, press CTRL+X and then follow the prompts.

5. To apply the configuration changes, type:

sudo systemctl daemon-reload

6. Repeat steps 1 to 5 on each computer hosting a relay node in your stake pool configuration.

7. On each computer in your stake pool configuration, update scripts as needed to use Cardano Tracer endpoints and metric names. For more details, see the topic Monitoring Metrics.

Completing the Upgrade​

To finish upgrading Cardano Node binaries:

1. On the computer hosting the block-producing node in your stake pool configuration, to verify that you installed the new Cardano Node binaries successfully, type:

cardano-node --version
cardano-cli --version
cardano-tracer --version

2. To finish the upgrade process, start the Cardano Node systemd service.

sudo systemctl start 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

4. Repeat steps 1 to 3 on each computer hosting a relay node in your stake pool configuration.

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

Upgrading to a new Cardano Node version may require replaying the copy of the blockchain ledger residing on the local computer. Here is an example of Cardano Node log entries showing progress when replaying the blockchain ledger:

...

[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3368857 out of 104785521. Progress: 3.22%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3389817 out of 104785521. Progress: 3.24%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3410780 out of 104785521. Progress: 3.26%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3421288 out of 104785521. Progress: 3.27%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3442207 out of 104785521. Progress: 3.29%

...

[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3609875 out of 104785521. Progress: 3.45%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3630832 out of 104785521. Progress: 3.47%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3651780 out of 104785521. Progress: 3.49%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3672859 out of 104785521. Progress: 3.51%
[ChainDB.ReplayBlock.LedgerReplay](Info,5) Replayed block: slot 3683233 out of 104785521. Progress: 3.52%

...

The task of replaying the ledger may require hours to complete.

Verifying the Upgrade​

To verify that the upgrade is successful, on each computer hosting an instance of Cardano Node in your stake pool configuration open a dashboard, or type the following command using a terminal window to follow the Cardano Node log:

journalctl -fu cardano-node
info

For more details, see the section Monitoring the Cardano Node Log.

Congratulations on completing the upgrade! ✨

Troubleshooting​

If your upgrade is unsuccessful, then refer to the topics Deleting the Blockchain Ledger and Resetting a Cardano Node Installation, as needed.