CoinCashew
Spanish
Spanish
  • Home
  • About Us
  • Donations
  • Contributing
    • Contributor Covenant Code of Conduct
    • Style Guide
  • Disclaimer
  • Wallets
    • Guide: Crypto Wallet Tips 101 - Do's and Don'ts
      • Review: Metal Bitcoin Seed Storage by jlopp
  • Coins
    • Ethereum: ETH
      • 🛡️EthPillar: one-liner setup tool and node management TUI
      • 🥩Guide | How to setup a validator for Ethereum staking on mainnet
        • Overview - Manual Installation
        • PART I - INSTALLATION
          • Step 1: Prerequisites
          • Step 2: Configuring Node
          • Step 3: Installing execution client
            • Nethermind
            • Besu
            • Geth
            • Erigon
            • Reth
          • Step 4: Installing consensus client
            • Lighthouse
            • Lodestar
            • Teku
            • Nimbus
            • Prysm
          • Step 5: Installing Validator
            • Setting up Validator Keys
            • Installing Validator
              • Lighthouse
              • Lodestar
              • Teku
              • Nimbus
              • Prysm
            • Next Steps
          • Monitoring your validator with Grafana and Prometheus
          • Mobile App Node Monitoring by beaconcha.in
          • Monitoring with Uptime Check by Google Cloud
        • PART II - MAINTENANCE
          • Updating Execution Client
          • Updating Consensus Client
          • Backups Checklist: Critical Staking Node Data
          • Uninstalling Staking Node
          • Finding the longest attestation slot gap
          • Checking my eth validator's sync committee duties
          • Checklist | Confirming a healthy functional ETH staking node
        • PART III - TIPS
          • Voluntary Exiting a Validator
          • Verifying Your Mnemonic Phrase
          • Adding a New Validator to an Existing Setup with Existing Seed Words
          • Switching / Migrating Consensus Client
          • 🛡️Switching / Migrating Execution Client
          • ⚡Using Node as RPC URL endpoint
          • Using All Available LVM Disk Space
          • Reducing Network Bandwidth Usage
          • How to re-sync using checkpoint sync
          • Important Directory Locations
          • Improving Validator Attestation Effectiveness
          • EIP2333 Key Generator by iancoleman.io
          • 😁Geth - Enabling path-based state storage
          • Disk Usage by Execution / Consensus Client
          • Dealing with Storage Issues on the Execution Client
        • Join the Community
        • Credits
        • See Also
        • Changelog
      • ⛓️Guide | How to setup a validator for Ethereum staking on testnet HOLESKY
        • Overview - Manual Installation
        • Step 1: Prerequisites
        • Step 2: Configuring Node
        • Step 3: Installing execution client
          • Nethermind
          • Besu
          • Geth
          • Erigon
          • Reth
        • Step 4: Installing consensus client
          • Lighthouse
          • Lodestar
          • Teku
          • Nimbus
          • Prysm
        • Step 5: Installing Validator
          • Setting up Validator Keys
          • Installing Validator
            • Lighthouse
            • Lodestar
            • Teku
            • Nimbus
            • Prysm
          • Next Steps
        • Maintenance
          • Updating Execution Client
          • Updating Consensus Client
          • Backups Checklist: Critical Staking Node Data
          • Uninstalling Staking Node
      • 💰Guide | MEV-boost for Ethereum Staking
        • MEV Relay List
      • 🔎Guide | Recover Ethereum Validator Mnemonic Seed
      • 🦉Update Withdrawal Keys for Ethereum Validator (BLS to Execution Change or 0x00 to 0x01) with ETHDO
      • 📜Archived Guides
        • Guide Version 1 | How to setup a validator for Ethereum staking on MAINNET
          • PART I - INSTALLATION
            • Step 1: Prerequisites
            • Step 2: Configuring Node
            • Step 3: Setting up Validator Keys
            • Step 4: Installing execution client
            • Step 5: Installing consensus client
            • Monitoring your validator with Grafana and Prometheus
            • Mobile App Node Monitoring by beaconcha.in
            • Security Best Practices for your ETH staking validator node
            • Synchronizing time with Chrony
            • Monitoring with Uptime Check by Google Cloud
          • PART II - MAINTENANCE
            • Updating your consensus client
            • Updating your execution client
            • Uninstalling V1 Staking Node
            • Finding the longest attestation slot gap
            • Checking my eth validator's sync committee duties
            • Pruning the execution client to free up disk space
            • Checklist | Confirming a healthy functional ETH staking node
          • PART III - TIPS
            • 🛡️Switching / Migrating Execution Client
            • Voluntary Exiting a Validator
            • Verifying Your Mnemonic Phrase
            • Adding a New Validator to an Existing Setup with Existing Seed Words
            • Switching / Migrating Consensus Client
            • Using All Available LVM Disk Space
            • Reducing Network Bandwidth Usage
            • How to re-sync using checkpoint sync
            • Important Directory Locations
            • Hosting Execution client on a Different Machine
            • Adding or Changing Graffiti flag
            • Improving Validator Attestation Effectiveness
            • EIP2333 Key Generator by iancoleman.io
            • Disk Usage by Execution / Consensus Client
            • Dealing with Storage Issues on the Execution Client
          • Join the Community
          • Credits
          • See Also
          • Changelog
        • Guide Version 1 | How to setup a validator for Ethereum staking on testnet GOERLI
          • Step 1: Prerequisites
          • Step 2: Configuring Node
          • Step 3: Setting up Validator Keys
          • Step 4: Installing execution client
          • Step 5: Installing consensus client
        • Guide Version 2 | How to setup a validator for Ethereum staking on testnet GOERLI
          • Step 1: Prerequisites
          • Step 2: Configuring Node
          • Step 3: Installing execution client
            • Nethermind
            • Besu
            • Geth
            • Erigon
          • Step 4: Installing consensus client
            • Lighthouse
            • Lodestar
            • Teku
            • Nimbus
            • Prysm
          • Step 5: Installing Validator
            • Setting up Validator Keys
            • Installing Validator
              • Lighthouse
              • Lodestar
              • Teku
              • Nimbus
              • Prysm
            • Next Steps
          • Maintenance
            • Updating Execution Client
            • Updating Consensus Client
            • Backups Checklist: Critical Staking Node Data
            • Uninstalling Staking Node
        • Guide | Ethereum Staking on Zhejiang Testnet
        • Guide | Besu + Lodestar | Most Viable Diverse Client | Staking Ethereum on Kiln testnet
        • Guide | How to setup a validator for Ethereum staking on Pithos testnet in 10 minutes or less
        • Ethereum Merge Upgrade Checklist for Home Stakers and Validators
        • Guide | Operation Client Diversity: Migrate Prysm to Teku
      • Guide: How to buy ETH
    • Cardano: ADA
      • Guide: How to Set Up a Cardano Stake Pool
        • PART I - INSTALLATION
          • Prerequisites
          • Hardening an Ubuntu Server
          • Setting Up chrony
          • Installing the Glasgow Haskell Compiler and Cabal
          • Compiling Cardano Node
        • PART II - CONFIGURATION
          • Downloading Configuration Files
          • Configuring Legacy Stake Pool Topology
          • Configuring an Air-gapped, Offline Computer
          • Creating Startup Scripts and Services
        • PART III - OPERATION
          • Starting the Nodes
          • Accessing Built-in Help
          • Generating Keys for the Block-producing Node
          • Setting Up Payment and Stake Keys
          • Registering Your Stake Address
          • Registering Your Stake Pool
          • Verifying Stake Pool Operation
          • Configuring Legacy Network Topology
          • Setting Up Dashboards
          • Configuring Slot Leader Calculations
          • Securing Your Stake Pool Using a Hardware Wallet
        • PART IV - ADMINISTRATION & MAINTENANCE
          • Checking Stake Pool Rewards
          • Claiming Stake Pool Rewards
          • Delegating to a Stake Pool
          • Issuing a New Operational Certificate
          • Updating Stake Pool Information
          • Upgrading a Node
          • Retiring Your Stake Pool
          • Auditing Your nodes configuration
          • KES Key Rotation / Operational Certificate Companion Script
        • PART V - TIPS
          • Submitting a Simple Transaction
          • Transferring Files Using SSH
          • Updating Configuration Files
          • Enabling Peer-to-peer Network Topology
          • Uploading Pool Metadata to GitHub Pages
          • Obtaining a PoolTool API Key
          • Configuring Glasgow Haskell Compiler Runtime System Options
          • Reducing Missed Slot Leader Checks and Improving Cardano Node Performance
          • Increasing Swap File Size
          • Setting Up an External Passive Relay Node
          • Setting Up WireGuard
          • Monitoring Node Security Using OSSEC Server and Slack
          • Resetting an Installation
          • Fixing a Corrupt Blockchain
          • Verifying an ITN Stake Pool
          • Fixing the Mnemonic Staking Balance Bug
        • Appendix A - Best Practices Checklist
        • Appendix B - Cardano Resource Index
        • Telegram Chat Channel
        • See Also
        • Credits
      • Guide: How to buy ADA
      • Guide: How to stake ADA
    • Monero: XMR
      • Guide | How to run your own Monero node
      • Guide: How to mine Monero
      • Create a XMR paper wallet
      • External Reading Material
        • Movie: Monero Means Money
        • Guide: Zero to Monero
        • Book: Mastering Monero
Powered by GitBook
On this page
  • Introduction
  • Upgrading Third-party Software
  • CNCLI
  • Guild LiveView
  • Setting GHC and Cabal Versions
  • Downloading New Configuration Files
  • Installing New Cardano Binaries
  • Verifying the Upgrade
  • Troubleshooting
Edit on GitHub
  1. Coins
  2. Cardano: ADA
  3. Guide: How to Set Up a Cardano Stake Pool
  4. PART IV - ADMINISTRATION & MAINTENANCE

Upgrading a Node

PreviousUpdating Stake Pool InformationNextRetiring Your Stake Pool

Introduction

If you want to support this free educational Cardano content or found the content helpful, visit to find our donation addresses. Much appreciated in advance.

Technical writing by

regularly releases new versions of Cardano Node via the cardano-node . 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 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 .

Upgrading Third-party Software

CNCLI

If you use 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 companion script for stake pool operators maintained by .

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

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

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.

Table 1 Current Cardano Node Version Requirements

Release Date
Cardano Node Version
GHC Version
Cabal Version

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 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 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}}

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

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

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>

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.

  1. Either build the latest binaries or download pre-built binaries that may be available from IOHK

Downloading pre-built binaries from IOHK
  1. Create a temporary path to store the pre-built binaries.

mkdir ~/tmp2
cd ~/tmp2
  1. Download the latest static binaries for Linux. Update below URL with the latest link before continuing.

wget https://update-cardano-mainnet.iohk.io/cardano-node-releases/cardano-node-8.0.0-linux.tar.gz
  1. Un-tar the archive.

tar -xvf cardano*.gz
  1. Install the new node and cli binaries.

sudo mv ~/tmp2/cardano-cli /usr/local/bin/
sudo mv ~/tmp2/cardano-node /usr/local/bin/
  1. Clean up temporary path.

cd
rm -rf ~/tmp2
Building Cardano Node Binaries

To build binaries for a new Cardano Node version:

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

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

$(find ./dist-newstyle/build -type f -name "cardano-node") version
$(find ./dist-newstyle/build -type f -name "cardano-cli") version

To install new cardano-node and cardano-cli binaries:

  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 $(find ./dist-newstyle/build -type f -name "cardano-node") <DestinationPath>/cardano-node
sudo cp $(find ./dist-newstyle/build -type f -name "cardano-cli") <DestinationPath>/cardano-cli

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

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.

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

To verify that the upgrade is successful, open gLiveView, journalctl logs or Grafana dashboard.

cd ${NODE_HOME}
./gLiveView.sh
journalctl -fu cardano-node

After an upgrade, starting a node may take up to a few hours. Be patient.

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.

maintains a set of tools to simplify operating a Cardano stake pool, including . If you use the gLiveView script, then ensure that you are using the latest version prior to upgrading your Cardano node.

In the 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.

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

For details on setting the NODE_HOME environment variable, see the topic

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 in the 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.

Downloading New Configuration Files

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

If you follow the Coin Cashew instructions for , 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 , 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.

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

Installing New Cardano Binaries

Visit the to determine the latest cardano-node linux binaries link, located under Downloads > Static Binaries > Linux.

To create a clone of the Cardano Node , 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:

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 :

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

7. On your air-gapped, offline computer, ensure that and are installed and up to date.

Verifying the Upgrade

Congrats on completing the update.

Use to find our donation addresses.

Any feedback and all pull requests much appreciated.

Hang out and chat with our stake pool community on Telegram @

Troubleshooting

If your upgrade is unsuccessful, then try and , as needed.

🔩
📥
⚡
🏁
✨
🌛
🚨
🎉
🙏
📒
💞
cointr.ee
Change Pool (ticker CHG)
Input-Output (IOHK)
GitHub repository
Watch
archive
CNCLI
cncli.sh
Guild Operators
Guild Operators
Guild LiveView
Common env
Starting the Nodes
Installing Cabal and GHC
Installing cardano-node and cardano-cli from source
Cardano Developer Portal
Creating Startup Scripts
Preparing Configuration Files
GitHub repository
diff
official Github
GitHub repository
Compiling Source Code
🙏
cointr.ee
https://t.me/coincashew
Fixing a Corrupt Blockchain
Resetting an Installation
Setting GHC and Cabal Versions
libsecp256k1
blst