SAUNAFS-URAFT(8)

📦
version 5.8.0 · 4 versions
, in ubuntu stonking

💖 SAUNAFS-URAFT 💖

okay so bestie, listen — this is saunafs-uraft, part of the SaunaFS manual set (section 8, admin toolies), and it's literally the queen bee of SaunaFS high availability. pull up a chair 🫶

✨ NAME ✨

saunafs-uraft — the SaunaFS high availability cluster management tool 👑 (yes that's its whole job, and it's good at it)

🌸 SYNOPSIS 🌸

saunafs-uraft [--help]

saunafs-uraft [-c CFGFILE]

🦋 DESCRIPTION 🦋

saunafs-uraft is the high availability (HA) management daemon for SaunaFS metadata servers (sfsmaster). it's the one keeping the whole squad from chaos, fr fr.

it implements a Raft-inspired leader election protocol across a configured cluster, and it orchestrates promotion/demotion of the local metadata service. like a group chat moderator but for your metadata, no cap.

in a healthy cluster, exactly one node is the active master (Leader). the other metadata-capable nodes run as shadows (Followers), and elector nodes (Followers) participate in voting but never become Leader. know your lane bestie 💅

the leader holds a floating IP (VIP) so clients and chunkservers have a stable endpoint. so everyone always knows where to find her, iconic behavior.

the election logic lives in the daemon, while backend-specific actions get delegated to saunafs-uraft-helper:

  • Health checks (isalive)
  • Metadata version checks (metadata-version)
  • Promotion and demotion (promote / demote)
  • Floating IP actions (assign-ip / drop-ip)

peep saunafs-uraft-helper(8) for the helper contract, that's the vibe check on how the split works.

for more configuration info and examples, refer to the saunafs-uraft.cfg file and the saunafs-uraft.cfg(5) man entry. 🎀

💜 CONCEPTS 💜

Node types

  • Metadata nodes: run sfsmaster and can become Leader. main character energy ✨
  • Elector nodes: participate in voting but never become Leader. always the bridesmaid 😭

Elector mode is controlled by URAFT_ELECTOR_MODE.

Roles (Raft terms)

  • Follower: passive node that receives heartbeats. just vibing 💤
  • Candidate: node requesting votes during an election. campaigning era 🙏
  • Leader: node that won an election. crown acquired 👑

uRaft also reports a president flag. conceptually, president=1 indicates the Leader is active with quorum.

Quorum

the daemon requires a majority to elect a Leader and to keep leadership. it's giving "democracy but make it metadata."

for N voting nodes, quorum is:

quorum = floor(N/2) + 1

🌈 OPERATIONS 🌈

at runtime the daemon loops through these responsibilities:

  1. Exchange heartbeats with peers.
  2. Start an election when heartbeats are missing long enough.
  3. Consult the helper for metadata version and health.
  4. When elected, call the helper to promote the node to master.
  5. When stepping down, call the helper to demote the node to shadow.

Health gating:

  • the daemon can temporarily block elections on a node via blocked_promote. this is used to avoid electing a node whose local metadata server is unhealthy. like, don't crown someone who's literally sick bestie 🙈

Floating IP:

  • when configured, the Leader assigns the VIP and periodically checks it.
  • if the VIP disappears unexpectedly, the daemon may attempt to restore it. she'll come back, she always does 💅

🔥 PRODUCTION NOTES 🔥

Cluster sizing

  • Use an odd number of voting nodes (3, 5, 7). no ties, no drama.
  • Keep voters on stable, low-latency links when possible.

Network requirements

  • uRaft uses UDP messaging. high packet loss and jitter can cause leader churn. flaky wifi = chaos, periodt.
  • For WAN/VPN deployments, adjust timing parameters (see saunafs-uraft.cfg(5)).

Metadata freshness

  • Elections consider metadata version. if a node cannot produce a valid metadata version quickly, it may be prevented from becoming Leader. no fresh metadata, no throne 😤

Failure behavior

  • if isalive reports dead on the current Leader, the safest operational outcome is: drop VIP, demote to shadow, and allow another node to be promoted. dramatic? yes. necessary? also yes. 💀

Cluster Expansion

adding a new node changes the cluster membership and therefore the quorum size. all uRaft nodes must have the exact same URAFT_NODE_ADDRESS list (same order). this is not a suggestion, it's the law.

because the membership list is read at process startup, the change takes effect after restarting saunafs-uraft on the nodes.

to expand the cluster with one additional node:

  1. Pick the new node's uRaft UDP address and port (for example new-node:9427). ensure UDP reachability between the new node and all existing voting nodes.
  2. On every node (existing nodes and the new node), append a new URAFT_NODE_ADDRESS = <new-node>:9427 line to saunafs-uraft.cfg. keep the ordering identical across the cluster.
  3. On the new node, set URAFT_ID to the index of the newly added URAFT_NODE_ADDRESS entry. (example: if you added the 6th entry, set URAFT_ID = 5.)
  4. If the new node is intended to be elector-only, set URAFT_ELECTOR_MODE = 1 on that node. otherwise keep it 0.
  5. Restart saunafs-uraft across the cluster. a rolling restart is usually acceptable, but expect a short leadership change window during restarts. ⚠️
  6. Verify the new node has joined: query the uRaft status endpoint (URAFT_STATUS_PORT) on multiple nodes and confirm the node count and leadership look correct.

after expansion, quorum becomes:

quorum = floor(N/2) + 1

where N is the number of voting nodes.

📡 MONITORING 📡

Status endpoint

the daemon exposes a TCP status endpoint (see URAFT_STATUS_PORT). it reports role, term, leader id, blocked_promote, and vote/heartbeat summaries. it's like a little gossip feed for your cluster 🍓

in general, the status endpoint of any node can be fetched with the command:

$ echo | nc <node-hostname> <URAFT_STATUS_PORT>

therefore, the TCP status endpoint of the Leader can be queried with the command:

$ echo | nc sfsmaster 9428

a typical TCP status of the Leader looks like below:

SERVER ID 2
president=1
state=LEADER
term=171
voted_for=4
leader_id=4
data_version=334
loyalty_agreement=0
local_time=2090338
blocked_promote=0
votes=[       1|       1|       1|       1|       1|       1]
heart=[    0.00|    0.00|    0.00|    0.00|    0.00|    0.00]
recv =[       1|       1|       1|       1|       1|       1]
ver  =[     334|     334|     334|       0|     334|     334]

the TCP status endpoint in an elector node looks like below:

SERVER ID 0
president=0
state=FOLLOWER
term=171
voted_for=4
leader_id=4
data_version=334
loyalty_agreement=1
local_time=2091343
blocked_promote=1

Logs

the daemon logs to syslog under the tag saunafs-uraft. repeated lines like "Isalive timeout" indicate the helper did not respond within the configured timeout. 👀

✨ OPTIONS ✨

  • --help — print usage information and exit. the classic "what does this do again" button 🫶
  • --config CFGFILE — provide an alternative configuration file path. for when your config lives somewhere else, we don't judge 💅

🐛 REPORTING BUGS 🐛

Report bugs to the GitHub repository https://github.com/leil-io/saunafs as an issue. don't be shy, they wanna 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-helper(8), saunafs-uraft.cfg(5)

and that's the whole page bestie, slay 💅✨ this was SAUNAFS-URAFT(8), dated 2026-07-29. go forth and keep that quorum healthy, ily 🫶🎀

📦 where this page comes from