SAUNAFS-URAFT-HELPER(8)

📦
version 5.8.0 · 4 versions
, in ubuntu stonking

💖 SAUNAFS-URAFT-HELPER(8) 💖

okay bestie, welcome to saunafs-uraft-helper — the SaunaFS HA suite helper. yes she's a helper but she's the main character of the failover arc, no cap. 🌸

✨ NAME ✨

saunafs-uraft-helper — SaunaFS HA suite helper 🫶

🎀 SYNOPSIS 🎀

saunafs-uraft-helper COMMAND [ARGUMENTS]

🦋 DESCRIPTION 🦋

saunafs-uraft-helper is a helper script, used internally by saunafs-uraft to manage nodes. like, she's the backstage crew, but the show literally cannot go on without her. 💅

The uRaft daemon does the leader election thing (the drama, the suspense 👑) and then calls this helper to execute backend-specific actions — promote/demote, floating IP assignment, health checks. and the way the split is intentional, bestie:

  • saunafs-uraft implements the election logic. that's the brain.
  • saunafs-uraft-helper implements the platform and SaunaFS-specific operations. that's the hands. 🤲

In production, it is important that helper commands are:

  • Fast (bounded runtime, no unbounded retries). no one has time for a helper that spirals. 😭
  • Deterministic and idempotent where possible. run it twice, same vibe. 🧚
  • Strict about machine-readable output for commands used in voting. stdout is a whole personality and it must stay legible to the daemon.

Except for isalive and metadata-version (which can be useful for debugging), this script is intended to be called by saunafs-uraft. so if you're just here poking around — hi, that's you, you're debugging, love that for you. 🔥

👑 COMMANDS 👑

The following commands are used by saunafs-uraft. buckle up. 💖

  • isalive — Checks whether the local metadata service is responsive. basically asking your metadata service "hey bestie, you up?" 🫶

This command must print exactly one of the following strings, without extra text:

  • alive (exit status 0)
  • dead (exit status non-zero)

The daemon uses this result to gate leader promotion (see blocked_promote in the uRaft status endpoint). no alive, no crown. 👑

Note In the current implementation the helper wraps sfsmaster -o ha-cluster-managed isalive. If sfsmaster is wedged or slow to connect, saunafs-uraft may time out and log "Isalive timeout". 💀
  • metadata-version [HOST PORT] — Returns the local metadata version as an unsigned integer.

The daemon uses this to avoid electing a node with stale metadata. The command must print an integer (decimal) and nothing else. no prose, no emoji, no side quests. 🙈

If the metadata service is unhealthy, returning 0 is a safe choice because it prevents the node from being elected Leader. zero is giving "not my turn diva" and honestly? valid. 🎀

  • promote — Promotes the local node to active master. glow-up time. ✨

Typical responsibilities include:

  • Switching sfsmaster personality to master.
  • Ensuring metadata is consistent.
  • Assigning the floating IP (VIP) to the configured interface.

On success the command should return exit status 0.

  • demote — Demotes the local node from active master to shadow. it's not a downfall arc, it's a character reset. 🌈

Typical responsibilities include:

  • Dropping the floating IP (VIP).
  • Restarting sfsmaster with initial-personality=shadow.

This command is the cleanest way to ensure a former Leader re-joins as a shadow after failover. iconic behavior, honestly. 💜

  • dead — Handles the situation where the local metadata server is considered dead. rip to her 🪦

The default helper implementation drops the floating IP only. In some environments, you may also want to stop/restart sfsmaster or force a demotion to shadow; if you customize dead, keep it idempotent and fast. like, do the thing, don't do it twice, and don't get weird about it. ⭐

  • assign-ip — Assigns the configured floating IP to the configured network interface. VIP gets a seat at the table. 💅
  • drop-ip — Drops the configured floating IP from the configured network interface. VIP has left the group chat. 😭
  • is-floating-ip-alive — Reports whether the floating IP is present on the local interface.

This is useful for debugging and for VIP watchdog behavior. lowkey one of the most helpful little guys in the whole suite. 🐛

Other helper commands may exist (for example quick-stop and cleanup) and can be used by operators or by additional recovery logic. iykyk. 🤫

🍓 FILES 🍓

The helper script reads configuration from:

  • @ETC_PATH@/saunafs-uraft.cfg
  • @ETC_PATH@/sfsmaster.cfg

It may also read metadata state from:

  • DATA_PATH configured in sfsmaster.cfg

⭐ EXIT STATUS ⭐

The exact semantics depend on the command, but the general contract is:

  • Exit status 0 indicates success. slay. 💖
  • Non-zero exit status indicates failure. not slay. 💀

For commands that are parsed by the daemon (isalive, metadata-version), stdout must remain machine-readable even on error. like, even when everything's on fire, keep your output clean. the daemon is reading it, bestie. 😭

🧚 REPORTING BUGS 🧚

Report bugs to the GitHub repository https://github.com/leil-io/saunafs as an issue. don't be shy, the maintainers want to know. 🫶

Copyright 2008-2009 Gemius SA

Copyright 2013-2019 Skytechnology sp. z o.o.

Copyright 2023 Leil Storage OÜ

SaunaFS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

SaunaFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with SaunaFS. If not, see http://www.gnu.org/licenses/.

🌈 SEE ALSO 🌈

saunafs-uraft(8), saunafs-uraft.cfg(5)

and that's the whole page, bestie 🎀 no notes, she ate. this one came straight from the SAUNAFS-URAFT-HELPER(8) manual, dated 2026-07-29. go forth and fail over responsibly. 💖✨

📦 where this page comes from