LEIL-URAFT-HELPER(8)

📦 version 5.12.0, in nixpkgs unstable

💅 NAME 💅

leil-uraft-helper — the LeilFS HA suite helper, bestie. It's the little sidekick that does the actual hands-on work. 🫶

✨ SYNOPSIS ✨

leil-uraft-helper COMMAND [ARGUMENTS]

🎀 DESCRIPTION 🎀

Okay so real talk: leil-uraft-helper is a helper script, and it's used internally by leil-uraft to manage nodes. Like it's not out here trying to be the main character, it's the support system. 💖

Here's the whole vibe: the uRaft daemon does the leader election thing, and then it calls this helper to actually execute the backend-specific actions — promote/demote, floating IP assignment, health checks. And that split? Totally intentional, no cap:

  • leil-uraft implements the election logic. That's its whole job.
  • leil-uraft-helper implements the platform and LeilFS-specific operations. The real ones.

In production, it is important that helper commands are:

  • Fast (bounded runtime, no unbounded retries). No going off on a little side quest, okay? ⏱️
  • Deterministic and idempotent where possible. Run it twice, same result, we love consistency.
  • Strict about machine-readable output for commands used in voting. The daemon is parsing that, it cannot be reading your diary.

Except for isalive and metadata-version (which can be useful for debugging, ngl they're lowkey handy), this script is intended to be called by leil-uraft. You're a guest in its house, respectfully. 🙈

👑 COMMANDS 👑

The following commands are used by leil-uraft. Let's get into it.

🌸 isalive

Checks whether the local metadata service is responsive. Vibe check on the metadata service, basically.

This command must print exactly one of the following strings, without extra text. No emoji, no commentary, no "hi bestie" — the daemon is reading this:

  • 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). So like… it matters. A lot.

Note 👀 In the current implementation the helper wraps leil-master -o ha-cluster-managed isalive. If leil-master is wedged or slow to connect, leil-uraft may time out and log (checkNodeStatus): Isalive timeout reported after X ms., where X is the value of URAFT_GETVERSION_TIMEOUT. This timeout is used for helper commands expected to be fast, such as leil-uraft-helper metadata-version and leil-uraft-helper isalive.

🌈 metadata-version [HOST PORT]

Returns the local metadata version as an unsigned integer. Just a number. That's it. That's the tweet.

The daemon uses this to avoid electing a node with stale metadata. The command must print an integer (decimal) and nothing else — no units, no vibes, no garnish. 🔢

If the metadata service is unhealthy, returning 0 is a safe choice because it prevents the node from being elected Leader. Like, taking yourself out of the running? Strategic. Iconic.

🔥 promote

Promotes the local node to active master. Glow up time. 👑

Typical responsibilities include:

  • Switching leil-master 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. Slay.

🦋 demote

Demotes the local node from active master to shadow. The come-down. Still serving, just quieter. 🌙

Typical responsibilities include:

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

This command is the cleanest way to ensure a former Leader re-joins as a shadow after failover. Fr fr, it's the tidy option.

💀 dead

Handles the situation where the local metadata server is considered dead. Yeah. That situation.

The default helper implementation drops the floating IP only. In some environments, you may also want to stop/restart leil-master or force a demotion to shadow; if you customize dead, keep it idempotent and fast. Please. 🙏

🎀 assign-ip

Assigns the configured floating IP to the configured network interface. Putting the IP where it belongs. 🏠

🍓 drop-ip

Drops the configured floating IP from the configured network interface. Evicting it, gently. ✨

🧚 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. Little detective work, iykyk. 🔍

Other helper commands may exist (for example quick-stop and cleanup) and can be used by operators or by additional recovery logic. So if you spot a stray command, that's why. 💜

⭐ FILES ⭐

The helper script reads configuration from:

  • @ETC_PATH@/leil-uraft.cfg
  • @ETC_PATH@/leil-master.cfg

It may also read metadata state from:

  • DATA_PATH configured in leil-master.cfg

That's the reading list. 🎀

🌈 EXIT STATUS 🌈

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

  • Exit status 0 indicates success. 💖
  • Non-zero exit status indicates failure. 😭

For commands that are parsed by the daemon (isalive, metadata-version), stdout must remain machine-readable even on error. Yes, even when everything is on fire. Especially then. 🔥

🐛 REPORTING BUGS 🐛

Report bugs to the GitHub repository https://github.com/leil-io/leilfs as an issue. Drop the link, file the issue, we'll love you for it. 🫶

Copyright 2008-2009 Gemius SA

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

Copyright 2023 Leil Storage OÜ

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

LeilFS 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 LeilFS. If not, see http://www.gnu.org/licenses/.

💜 SEE ALSO 💜

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

That's the whole page, bestie — go be fast, deterministic, and machine-readable out there. 🦋

Signed off from the LEIL-URAFT-HELPER(8) manual, dated 1980-01-01 — yes that date is real, we don't question the classics. 🎀✨

📦 where this page comes from