StorMagic Witness service on Raspberry Pi Debian 12--Bookworm.

Steve LaPelle
  • Updated

This article outlines the complete process to configure a Raspberry Pi running Raspberry Pi OS Bookworm (Debian 12) as a StorMagic NSH witness service node. It covers OS installation, networking using NetworkManager, VNC setup (optional), NSH installation, ELF interpreter patching, and service startup.

Note:  All images are clickable for enlarging, or can be opened in a new tab

Resolution/Information:

Table of Contents

  1. Install Raspberry Pi OS (Bookworm).
  2. Configure Hostname and DNS.
  3. Configure Networking with NetworkManager.
  4. Enable VNC (Optional).
  5. Install the StorMagic Witness Service.
  6. Patch the ELF Interpreter Paths.
  7. Start and Enable the Service.
  8. Verify Service.
  9. Utilize Witness.

Raspberry Pi OS Timeline Summary:

Raspberry Pi OS started using a 64-bit kernel with a 32-bit userland as a transitional step around the late Raspberry Pi OS Buster and early Bullseye era — specifically:

  •  Before 2020 All Raspberry Pi OS builds used a 32-bit kernel and 32-bit userland (armhf).

This ensured full compatibility with all models of the Pi, including early ones like the Pi 1 and Zero.

  •  2020 – 2021 (Late Buster → Bullseye Era)
    Raspberry Pi Foundation introduced a hybrid build.
  • 64-bit kernel (aarch64).
  • 32-bit userland (armhf).

This allowed:

  • Better performance on Pi 3 and Pi 4.
  • Use of more memory (>3 GB) with newer boards.
  • Compatibility with 32-bit-only applications.

This hybrid mode became the default in many Bullseye images unless you explicitly chose the full 64-bit image.

  • 2022 Onward (Full 64-bit available) Full 64-bit Raspberry Pi OS was released for general use (kernel + userland both 64-bit).

But hybrid 64-bit kernel + 32-bit userland remained common, especially for legacy support.

key System-level changes made in Debian 12 (Bookworm).

/lib/ld-linux.so.3 removed in Debian 11 (Bullseye) and prior, 32-bit ARM armhf binaries compiled with: /lib/ld-linux.so.3 could still run because that path existed as a legacy symlink (usually pointing to /lib/ld-linux-armhf.so.3).

Note: In Debian 12 (Bookworm), that legacy interpreter path was completely removed for standards compliance (FHS + multiarch cleanup).

As a result:

  • Older statically compiled binaries fail with "cannot execute: required file not found."

Options for fixing the break in path:

  • Rebuilding against /lib/ld-linux-armhf.so.3
  • Manually adding a symlink (ln -s /lib/ld-linux-armhf.so.3 /lib/ld-linux.so.3)
  • Using patchelf to rewrite the interpreter path in ELF headers

Networking Stack: dhcpcd replaced by NetworkManager.

In Debian 12, the default Raspberry Pi OS now uses NetworkManager instead of dhcpcd.

Differences:

  • Feature dhcpcd (Bullseye & earlier) vs. NetworkManager (Bookworm).
  • Simplicity Lightweight, config-driven vs. D-Bus/GUI-integrated, policy-based.
  • Config files /etc/dhcpcd.conf /etc/NetworkManager/.
  • Wi-Fi & eth management Manual/static easier to script GUI-friendly, but needs profiles.
  • Autostart behavior dhcpcd controlled directly systemd-networkd & NM now take over.
  • Compatibility Works well with headless Pi Needs adjustment for CLI/headless.

Note: Migration to NetworkManager may break existing headless configs if dhcpcd.conf was previously used to define static IPs or DNS settings.

Note:  The arm package will use terms like 'NSH' meaning neutral storage host versus 'Witness'.

1. Install Raspberry Pi OS (Bookworm)

Use the official Raspberry Pi Imager tool to write the operating system to a microSD card.

  • Download Raspberry Pi Imager: https://www.raspberrypi.com/software.
  • If you scroll down to all options.
  • Select “Raspberry Pi OS Lite (32-bit)” from the “Other” section.
selclip1.png
selclip2.png

 

selclip3.png

You want to ensure you select the 32 bit option: 

This will be a 64 bit kernel with what is referred to as a 32 bit Userland for running 32 bit applications, while being able to utilze the capabilities of a 64 bit Kernel. 

selclip4.png
    • Click the gear icon for advanced options:
      • Set hostname (e.g. smwitness.yourdomain).
      • Enable SSH.
      • Set username and password.
      • Optionally configure Wi-Fi credentials.
    • Write the image to the microSD card.
    • Insert the card into the Raspberry Pi and boot.

2. Configure Hostname and DNS

Set a unique hostname and ensure it resolves properly on the network.

  • To set the hostname:
sudo hostnamectl set-hostname smwitness.yourdomain
  • Add it to the hostfile: /etc/hosts
  • Example 10.x.x.x hostname.FQDN (Long name) "Space" hostname (Shortname).
  • This ensures local resolution of the hostname for services that rely on FQDN.

3. Configure Networking with NetworkManager.

  • Debian 12 and Bookworm Raspberry Pi OS now use NetworkManager by default instead of dhcpcd.
  • Enable / Activate NetworkManager:
sudo systemctl enable NetworkManager
sudo systemctl start NetworkManager
  • Set a static IP address:
nmcli connection modify eth0 ipv4.addresses 10.10.10.100/24
nmcli connection modify eth0 ipv4.gateway 10.10.10.1
nmcli connection modify eth0 ipv4.dns "10.10.10.5"
nmcli connection modify eth0 ipv4.method manual nmcli connection up eth0

These settings persist across reboots and support policy-based configuration.

4. Enable VNC (Optional). 

  • To enable GUI access over VNC: 
  • For steps on setting up Realvnc please see the below link.

Raspberry Pi VNC: how to set up a remote desktop | RealVNC

 

selclip5.png
  • Install the UI components and VNC server:
sudo apt update
sudo apt install raspberrypi-ui-mods realvnc-vnc-server
  • Enable VNC via raspi-config:
sudo raspi-config
  • Navigate to: Interface Options > VNC > Enable
selclip8.png
selclip6.png

You can now connect via VNC using a VNC viewer pointed to the Pi’s IP address.

5. Install the StorMagic Witness Service.

Options: Either download and unzip from the GUI or transfer it via SCP if not using the GUI.

selclip7.png
  • If using the automation toolkit, extract the provided bundle:
mkdir ~/svsan cd ~/svsan unzip ~/Downloads/SvSAN_Automation_Toolkit.zip
cd SvSAN-Automation-Toolkit python3 nsh_gui_installer.py
selclip9.png

6. Patch the ELF Interpreter Paths.

*This step is for if something doesn't complete successfully or you prefer to do it manually. *

In Debian 12, /lib/ld-linux.so.3 has been removed. Legacy binaries compiled against that path will fail unless corrected.

Install patchelf:

sudo apt install patchelf

Patch the binaries:

sudo patchelf --set-interpreter /lib/ld-linux-armhf.so.3
sudo patchelf --set-interpreter /lib/ld-linux-armhf.so.3 /opt/stormagic/bin/smdiscod
sudo patchelf --set-interpreter /lib/ld-linux-armhf.so.3 /opt/stormagic/bin/smclusterd
sudo patchelf --set-interpreter /lib/ld-linux-armhf.so.3 /opt/stormagic/bin/exlog
sudo patchelf --set-interpreter /lib/ld-linux-armhf.so.3 /opt/stormagic/bin/smc_state
Alternatively, use the provided script in the toolkit:
sudo bash scripts/fix_interpreter.sh

This restores compatibility with the new dynamic linker location in Bookworm.

7. Start and Enable the Service.

*This step is for if something doesn't complete successfully or you prefer to do it manually. *

Start and enable the witness service:

sudo systemctl restart StorMagicNSH

Check the service status:

sudo systemctl status StorMagicNSH

You should now see smdisco and smclusterd running. 

selclip10.png

8. Verify Operation.

Check that the service is listening on UDP ports:

sudo ss -ulpn | grep smdisc

Expected output includes lines like:

selclip11.png

9. Utilize Witness.

From the SvHCI interface, confirm that the witness shows up under the discovery tab or can be manually added by IP or FQDN.

 

If you do not see it there already you will need to add it as an entry on both hosts in order to use it in the cluster. Select to add an entry and apply the devices information and click apply. 

selclip17.png
selclip12.png

On the Discovery tab select to edit the cluster. Apply any notes and using the drop down select the new witness and click apply. 

selclip13.png

Staying on the discovery tab you will now see the cluster witness is the new Rasberry Pi.

selclip14.png

Within the targets tab you now will see the targets being monitored by this witness. 

selclip15.png

Notes:

  • If DNS resolution is unavailable, use static IP discovery.

  • Ensure firewalls or VLAN restrictions do not block UDP traffic to/from the witness. SvSAN 6.3.x - Port Numbers – StorMagic

  • If the interpreter path patching is skipped, the daemons will fail silently or show "cannot execute: required file not found".

selclip16.png

For further information or queries please contact support@stormagic.com

See Also

https://stormagic.com/manual/

Installing an SvSAN witness on Raspberry Pi (Raspbian 32bit) – StorMagic (pre-Bookworm).

StorMagic Witness - Supporting SpSAN, SvSAN & SvHCI: Deploy, Install, Upgrade and Migrate – StorMagic

 

 

Related articles

Comments

0 comments

Article is closed for comments.