Thread

🛡️
Article header

How to upgrade Fulcrum v1.x to v2.0 on MiniBolt

A detailed step-by-step guide to upgrading Fulcrum to the new major version 2.0 on MiniBolt.

Published:

What's New in Fulcrum 2.0

  • Database Reliability - one of the main weaknesses of Fulcrum 1.x was that should the process be killed at an inopportune time, or should abrupt powerloss or kernel-level crash occur at an inopportune time, there was always a risk that the datadir would get corrupted and the admin would be forced to do a full database resynch. This is no longer the case!

  • Platform Neutrality - database format is now 100% platform-neutral. This means it should be possible to always copy datadirs around regardless if transferring them from Windows, Linux, BSD, macOS, and regardless of platform architecture (including big endian platforms).

  • Improved database performance.

  • utxo-cache option has been removed, but it is still possible to use db_mem to help with initial synchronization speed.

Source: https://github.com/cculianu/Fulcrum/releases/tag/v2.0.0

Upgrading from the Fulcrum 1.x Series on a MiniBolt guided-node

~> Note 1: If you don't know if you'll have enough resources on the machine to handle the migration, it's advisable to free up resources by stopping all possible services running on the machine that aren't critical.

~> Note 2: During the migration, you will need additional and temporary disk space (approximately 84 GB). Make sure you have enough disk space; otherwise, the migration will fail, and you will need to start the synchronization from scratch, deleting the database and recreating it.

  • With the user admin, stop all non-critical services you can (Fulcrum included) with sudo systemctl stop X
sudo systemctl stop btcrpcexplorer fulcrum

~> In this case, we only stopped the essential services that depend on Fulcrum (currently BTC RPC Explorer) along with Fulcrum itself.

Upgrade binaries

Download binaries

  • Login as the admin user and change to a temporary directory, which is cleared on reboot
cd /tmp
  • Set a temporary version environment variable for the installation
VERSION=2.0.0
  • Download the application, checksums, and signature
wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-x86_64-linux.tar.gz

wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-shasums.txt.asc

wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-shasums.txt

Signature check

  • Get the public key from the Fulcrum developer
curl https://raw.githubusercontent.com/Electron-Cash/keys-n-hashes/master/pubkeys/calinkey.txt | gpg --import

Expected output:

[...]
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2328  100  2328    0     0   8449      0 --:--:-- --:--:-- --:--:--  8434
gpg: key 21810A542031C02C: "Calin Culianu (NilacTheGrim) <calin.culianu@gmail.com>" imported
gpg: Total number processed: 1
gpg:              unchanged: 1
[...]
  • Verify the signature of the text file containing the checksums for the application
gpg --verify Fulcrum-$VERSION-shasums.txt.asc Fulcrum-$VERSION-shasums.txt

Expected output:

[...]
gpg: Good signature from "Calin Culianu (NilacTheGrim) <calin.culianu@gmail.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: D465 135F 97D0 047E 18E9  9DC3 2181 0A54 2031 C02C
[...]

Checksum check

  • Verify the signed checksum against the actual checksum of your download
grep 'x86_64-linux.tar.gz' Fulcrum-$VERSION-shasums.txt | sha256sum --check

Example of expected output:

Fulcrum-1.9.4-x86_64-linux.tar.gz: OK
  • Extract it
tar -xzvf Fulcrum-$VERSION-x86_64-linux.tar.gz

Example of expected output:

Fulcrum-1.11.1-amd64-linux/
Fulcrum-1.11.1-amd64-linux/man/
Fulcrum-1.11.1-amd64-linux/man/Fulcrum.1
Fulcrum-1.11.1-amd64-linux/FulcrumAdmin
Fulcrum-1.11.1-amd64-linux/fulcrum-example-config.conf
Fulcrum-1.11.1-amd64-linux/LICENSE.txt
Fulcrum-1.11.1-amd64-linux/Fulcrum
Fulcrum-1.11.1-amd64-linux/unix-man-page.md
Fulcrum-1.11.1-amd64-linux/fulcrum-quick-config.conf

Binaries installation

  • Install it
sudo install -m 0755 -o root -g root -t /usr/local/bin Fulcrum-$VERSION-x86_64-linux/Fulcrum
  • Check the correct installation, requesting the version
Fulcrum --version

Example of expected output:

Fulcrum 2.0 (Release df51b8a)
Protocol: version min: 1.4, version max: 1.5.3
compiled: gcc 13.1.0
[...]
  • (Optional) Delete the installation files of the tmp folder
sudo rm -r Fulcrum-$VERSION-x86_64-linux Fulcrum-$VERSION-x86_64-linux.tar.gz Fulcrum-$VERSION-shasums.txt Fulcrum-$VERSION-shasums.txt.asc

Update the configuration file

Since the utxo-cache option has been removed, we're replacing it with db_mem to help with initial sync speed.

  • With the user admin, edit the Fulcrum configuration file
sudo nano /data/fulcrum/fulcrum.conf
  • Replace utxo-cache option with db_mem and lines related, check this diff. The next should be the final result. Save and exit

Note: If you will go to set db_mem = 2048.0 is not needed to add the next db_mem related lines because it is the default one, you can simply delete the related lines with utxo-cache and go to the next step.

# MiniBolt: fulcrum configuration
# /data/fulcrum/fulcrum.conf

## Bitcoin Core settings
bitcoind = 127.0.0.1:8332
rpccookie = /data/bitcoin/.cookie

## Fulcrum server general settings
datadir = /data/fulcrum/fulcrum_db
cert = /data/fulcrum/cert.pem
key = /data/fulcrum/key.pem
ssl = 0.0.0.0:50002
tcp = 0.0.0.0:50001
peering = false
zmq_allow_hashtx = true

# Max RocksDB Memory in MiB - DEFAULT: 2048.0
# (this applies in initial synchronization and daily operation)
# recommended: db_mem=1/2 x RAM available, e.g, 4GB RAM -> db_mem = 2048.0
db_mem = 2048.0

# Banner
banner = /data/fulcrum/fulcrum-banner.txt

Migrate database

Since the database format has been completely redone, the database is no longer backward compatible with older Fulcrum versions.

Modify the systemd unit

We are going to upgrade our existing database to the new format using the systemd file and passing the one-time flag --db-upgrade the first time we run Fulcrum 2.0 when upgrading from a 1.x install.

  • With the user admin, edit the systemd unit
sudo nano /etc/systemd/system/fulcrum.service
  • Replace the line ExecStart to add the --db-upgrade flag, see the diff. The next should be the final result. Save and exit
# MiniBolt: systemd unit for Fulcrum
# /etc/systemd/system/fulcrum.service

[Unit]
Description=Fulcrum
Requires=bitcoind.service
After=bitcoind.service

StartLimitBurst=2
StartLimitIntervalSec=20

[Service]
ExecStart=/usr/local/bin/Fulcrum --db-upgrade /data/fulcrum/fulcrum.conf

User=fulcrum
Group=fulcrum

# Process management
####################
Type=simple
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target
  • Reload the systemd daemon to apply changes
sudo systemctl daemon-reload
  • Prepare "fulcrum" monitoring by the systemd journal and check the logging output. You can exit monitoring at any time with Ctrl-C
journalctl -fu fulcrum

Run the database migration

To keep an eye on the software movements, create a new SSH session to the MiniBolt node, and log in as "admin"

  • Start Fulcrum to initiate the database migration
sudo systemctl start fulcrum

Example of expected output on the first terminal with journalctl -fu fulcrum ⬇️

image

~> Note 1: The upgrade process takes seconds to minutes on testnet, and around an hour or more (depending on hardware) on mainnet.

~> Note 2: When you see logs like this SrvMgr: starting 2 services ..., which means that the Fulcrum database is fully migrated:

[...]
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.705] SrvMgr: starting 2 services ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Starting listener service for TcpSrv 0.0.0.0:50001 ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Service started, listening for connections on 0.0.0.0:50001
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Starting listener service for SslSrv 0.0.0.0:50002 ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Service started, listening for connections on 0.0.0.0:50002
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.707] <Controller> Starting ZMQ Notifier (hashtx) ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.707] <Controller> Starting ZMQ Notifier (hashblock) ...
[...]
  • When Fulcrum has finally migrated the database, stop it, to proceed with the systemd file modification revert
sudo systemctl stop fulcrum
  • Revert the systemd file's previous change. Edit the systemd file with
sudo nano /etc/systemd/system/fulcrum.service
  • Delete the --db-upgrade flag on the ExecStart line. See the diff. The next should be the final result. Save and exit
# MiniBolt: systemd unit for Fulcrum
# /etc/systemd/system/fulcrum.service

[Unit]
Description=Fulcrum
Requires=bitcoind.service
After=bitcoind.service

StartLimitBurst=2
StartLimitIntervalSec=20

[Service]
ExecStart=/usr/local/bin/Fulcrum /data/fulcrum/fulcrum.conf

User=fulcrum
Group=fulcrum

# Process management
####################
Type=simple
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target
  • Reload the systemd daemon to apply changes
sudo systemctl daemon-reload
  • Start fulcrum again
sudo systemctl start fulcrum
  • Start dependencies, and any services you may have stopped to perform the Fulcrum migration
sudo systemctl start btcrpcexplorer

~> Monitor the logs with journalctl (journalctl -fu "X") to ensure all is properly running as before.

Enjoy the new shiny and resilient Fulcrum, MiniBolter!💙

Replies (0)

No replies yet. Be the first to leave a comment!