HASTD(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 HASTD(8) — the Highly Available Storage daemon, explained by your unix bestie 🎀

ok so real talk: this is the manual page for hastd(8), which lives in the System Manager's Manual, and it's honestly iconic. it's the Highly Available Storage daemon and she's a lot but she's worth it, i promise. let's get into it. ✨

✨ NAME ✨

hastd — the Highly Available Storage daemon. that's her. that's the whole name. 💅

🌸 SYNOPSIS 🌸

hastd [-dFh] [-c config] [-P pidfile]

that's it. that's the vibe check. three flags in the happy little bracket, plus -c and -P which take arguments. slay. 🫶

🦋 DESCRIPTION 🦋

okay so hastd is the daemon that handles highly available GEOM providers. she's the main character of your storage setup, no cap.

the whole point: hastd lets you store data transparently on two physically separated machines that are connected over a TCP/IP network. only one machine (a cluster node) can actively use the storage that hastd provides at any given time. that machine is called the primary. hastd works on the block level, which is why it's completely transparent to your file systems and your applications — they don't even know she's there. lowkey magical. 🧚

there's one main hastd daemon, and it spins up a new worker process as soon as:

  • the role for a given resource is changed to primary, or
  • the role for a given resource is changed to secondary and the remote (primary) node successfully connects to it.

every worker process gets a brand-new process title (see setproctitle(3)) that describes its role and the resource it controls. the exact format is, character for character:

hastd: <resource name> (<role>)

if — and only if — hastd is operating in the primary role for a given resource, a corresponding /dev/hast/<name> disk-like device (GEOM provider) gets created. file systems and applications can use that provider to send I/O requests into. every write, delete and flush operation (BIO_WRITE, BIO_DELETE, BIO_FLUSH) is sent to the local component and replicated on the remote (secondary) node if it's available. read operations (BIO_READ) are handled locally — unless an I/O error happens, or the local version of the data isn't up-to-date yet (like, when synchronization is in progress in the background). 👑

hastd uses the GEOM Gate class to receive I/O requests from the in-kernel GEOM infrastructure. the geom_gate.ko module is loaded automatically if your kernel wasn't compiled with this option:

options GEOM_GATE

the connection between two hastd daemons is always initiated from the one running as primary to the one running as secondary. when the primary hastd can't connect, or the connection drops, it'll try to re-establish the connection every few seconds. once the connection is back up, the primary hastd synchronizes every extent that was modified during the outage over to the secondary hastd. fr fr she does not forget. 😤

⚠️ okay so here's the scary one, bestie. it's possible that during a connection outage between the nodes, the hastd primary role for a given resource ends up configured on both nodes. that leads to incompatible data modifications. this condition is called a split-brain, and it cannot be automatically resolved by the hastd daemon, because trying to resolve it would most likely lead to data corruption or loss of important changes. even though hastd can't fix it herself, she will detect it, and a further connection between the independently modified nodes will not be possible. once an administrator manually resolves the situation, the resource on one of the nodes can be initialized (erasing local data), which makes a connection to the remote node possible again. connecting that freshly initialized component will trigger a full resource synchronization.

a hastd daemon never picks its role automatically. like, she refuses to choose. the role has to be configured with the hastctl(8) control utility, by additional software like ucarp or heartbeat that can reliably manage role separation and switch the secondary node to the primary role if the primary fails. teamwork makes the dream work. 🌈

💅 OPTIONS 💅

the hastd daemon can be started with the following command line arguments:

  • -c config — specify an alternative location for the configuration file. the default location is /etc/hast.conf.
  • -d — print or log debugging information. you can pass this option multiple times to raise the verbosity level. go off, queen of diagnostics.
  • -F — start the hastd daemon in the foreground. by default, hastd starts in the background.
  • -h — print the hastd usage message. help is always free. 🫶
  • -P pidfile — specify an alternative location for the file where the main process PID will be stored. the default location is /var/run/hastd.pid.

🍓 FILES 🍓

  • /etc/hast.conf — the configuration file for hastd and hastctl(8).
  • /var/run/hastctl — the control socket used by the hastctl(8) control utility to communicate with hastd.
  • /var/run/hastd.pid — the default location of the hastd PID file.

⭐ EXIT STATUS ⭐

exit status is 0 on success, or one of the values described in sysexits(3) on failure. simple as that. ✨

🌸 EXAMPLES 🌸

the plan: launch hastd on both nodes. set the role for resource shared to primary on nodeA and to secondary on nodeB. create a file system on the /dev/hast/shared provider and mount it. let's goooo. 🔥

nodeB# hastd
nodeB# hastctl role secondary shared

nodeA# hastd
nodeA# hastctl role primary shared
nodeA# newfs -U /dev/hast/shared
nodeA# mount -o noatime /dev/hast/shared /shared

look at that symmetry. genuinely obsessed. 💜

🧚 SEE ALSO 🧚

sysexits(3), geom(4), hast.conf(5), ggatec(8), ggated(8), ggatel(8), hastctl(8), mount(8), newfs(8), g_bio(9)

the whole friend group. iykyk. 💫

🎀 HISTORY 🎀

the hastd utility appeared in FreeBSD 8.1. a classic, honestly.

👑 AUTHORS 👑

hastd was developed by Pawel Jakub Dawidek <pjd@FreeBSD.org> under sponsorship of the FreeBSD Foundation. we stan a sponsored legend. 💖

and that's the whole page bestie, no crumbs left behind. 🦋 this Debian rendering of the page is dated December 21, 2019 — go forth and keep your storage highly available, and remember: never let a split-brain happen on your watch. periodt. 💅✨🌸
📦 where this page comes from