HAST.CONF(5)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

🌸 NAME 🌸

hast.conf — it's the config file for the hastd(8) daemon and the hastctl(8) utility, bestie 💖

✨ DESCRIPTION ✨

Okay so, hast.conf is the one file that both the hastd(8) daemon and the hastctl(8) control utility read. And here's the iconic part: the config file is designed so that exactly the same file can be — and honestly should be — used on both HAST nodes. One file, two nodes, no cap 🫶

And any line that starts with #? That's a comment. Ignored. Not read. A little vibe text for you and you only 😌

🎀 CONFIGURATION FILE SYNTAX 🎀

The general layout of the hast.conf file goes like this, literally:

# Global section
control <addr>
listen <addr>
replication <mode>
checksum <algorithm>
compression <algorithm>
timeout <seconds>
exec <path>
metaflush on | off
pidfile <path>

on <node> {
        # Node section
        control <addr>
        listen <addr>
        pidfile <path>
}

on <node> {
        # Node section
        control <addr>
        listen <addr>
        pidfile <path>
}

resource <name> {
        # Resource section
        replication <mode>
        checksum <algorithm>
        compression <algorithm>
        name <name>
        local <path>
        timeout <seconds>
        exec <path>
        metaflush on | off

        on <node> {
                # Resource-node section
                name <name>
                # Required
                local <path>
                metaflush on | off
                # Required
                remote <addr>
                source <addr>
        }
        on <node> {
                # Resource-node section
                name <name>
                # Required
                local <path>
                metaflush on | off
                # Required
                remote <addr>
                source <addr>
        }
}

So most of these parameters are optional — lowkey chill of them 💅 If a parameter isn't defined in a particular section, it gets inherited from the parent section. Example: if listen isn't defined in the node section, it'll be inherited from the global section. And if the global section doesn't define listen at all? Then the default value gets used. Iconic inheritance behaviour, fr fr ✨

🦋 CONFIGURATION FILE DESCRIPTION 🦋

The ⟨node⟩ argument can be replaced by any of these, bestie:

  • a full hostname as obtained by gethostname(3)
  • only the first part of the hostname
  • the node's UUID as found in the kern.hostuuid sysctl(8) variable
  • the node's hostid as found in the kern.hostid sysctl(8) variable

Here are the statements you can use 👇

🌟 control ⟨addr⟩

The address for communication with hastctl(8). Every one of these examples defines the same control address, no cap:

uds:///var/run/hastctl
unix:///var/run/hastctl
/var/run/hastctl

The default value is uds:///var/run/hastctl.

🌟 pidfile ⟨path⟩

The file where we store the process ID of the main hastd(8) process.

The default value is /var/run/hastd.pid.

🌟 listen ⟨addr⟩

The address to listen on, written in the form of:

protocol://protocol-specific-address

And each of these examples defines the same listen address:

0.0.0.0
0.0.0.0:8457
tcp://0.0.0.0
tcp://0.0.0.0:8457
tcp4://0.0.0.0
tcp4://0.0.0.0:8457

You can specify multiple listen addresses, bestie, stack 'em up 🎀 By default hastd listens on tcp4://0.0.0.0:8457 and tcp6://[::]:8457 if the kernel supports IPv4 and IPv6 respectively.

🌟 replication ⟨mode⟩

The replication mode should be one of these three, and the vibes are very different:

  • memsync — reports the write operation as completed when the local write completes and when the remote node acknowledges the data receipt, but before it actually stores the data. The data on the remote node will be stored directly after sending the acknowledgement. This mode is intended to reduce latency, but still provides a very good reliability. The only situation where some small amount of data could be lost is when the data is stored on the primary node and sent to the secondary. The secondary node then acknowledges data receipt and the primary reports success to an application. However, it may happen that the secondary goes down before the received data is really stored locally. Before the secondary node returns, the primary node dies entirely. When the secondary node comes back to life it becomes the new primary. Unfortunately some small amount of data which was confirmed to be stored to the application was lost. The risk of such a situation is very small. The memsync replication mode is the default. 😭 (a whole tragedy arc in one paragraph, but like — tiny risk, ok?)
  • fullsync — marks the write operation as completed when local as well as remote write completes. This is the safest and the slowest replication mode. 🐢👑
  • async — the write operation is reported as complete right after the local write completes. This is the fastest and the most dangerous replication mode 💀 This mode should be used when replicating to a distant node where latency is too high for other modes.
⚠️ bestie please note: async is genuinely the most dangerous one. Fast, yes. Safe, no. Choose accordingly 🙈

🌟 checksum ⟨algorithm⟩

The checksum algorithm should be one of these:

  • none — no checksum will be calculated for the data being send over the network. This is the default setting.
  • crc32 — CRC32 checksum will be calculated.
  • sha256 — SHA256 checksum will be calculated.

🌟 compression ⟨algorithm⟩

The compression algorithm should be one of these:

  • none — data send over the network will not be compressed.
  • hole — only blocks that contain all zeros will be compressed. This is very useful for initial synchronization where potentially many blocks are still all zeros. There should be no measurable performance overhead when this algorithm is being used. This is the default setting. 🕳️✨
  • lzf — the LZF algorithm by Marc Alexander Lehmann will be used to compress the data send over the network. LZF is a very fast, general purpose compression algorithm.

🌟 timeout ⟨seconds⟩

Connection timeout in seconds. The default value is 20. ⏱️

🌟 exec ⟨path⟩

Execute the given program on various HAST events. Below is the list of currently implemented events and the arguments the given program is executed with 👇

  • <path> role <resource> <oldrole> <newrole> — executed on both primary and secondary nodes when the resource role is changed.
  • <path> connect <resource> — executed on both primary and secondary nodes when the connection for the given resource between the nodes is established.
  • <path> disconnect <resource> — executed on both primary and secondary nodes when the connection for the given resource between the nodes is lost.
  • <path> syncstart <resource> — executed on the primary node when the synchronization process of the secondary node is started.
  • <path> syncdone <resource> — executed on the primary node when the synchronization process of the secondary node is completed successfully. 🎉
  • <path> syncintr <resource> — executed on the primary node when the synchronization process of the secondary node is interrupted, most likely due to secondary node outage or connection failure between the nodes. 😭
  • <path> split-brain <resource> — executed on both primary and secondary nodes when a split-brain condition is detected. 💀

The ⟨path⟩ argument should contain the full path to the executable program. If the given program exits with a code different than 0, hastd will log it as an error.

The ⟨resource⟩ argument is the resource name from the configuration file.

The ⟨oldrole⟩ argument is the previous resource role (before the change). It can be one of: init, secondary, primary.

The ⟨newrole⟩ argument is the current resource role (after the change). It can be one of: init, secondary, primary.

🌟 metaflush on | off

When set to on, flush the write cache of the local provider after every metadata (activemap) update. Flushing the write cache ensures that the provider will not reorder writes and that metadata will be properly updated before real data is stored. If the local provider does not support flushing write cache (it returns EOPNOTSUPP on the BIO_FLUSH request), hastd will disable metaflush automatically. The default value is on.

🌟 name ⟨name⟩

The GEOM provider name that will appear as /dev/hast/<name>. If name is not defined, the resource name will be used as the provider name.

🌟 local ⟨path⟩

Path to the local component which will be used as the backend provider for the resource. This can be either a GEOM provider or a regular file. 🗂️

🌟 remote ⟨addr⟩

Address of the remote hastd daemon. The format is the same as for the listen statement. When operating as a primary node this address will be used to connect to the secondary node. When operating as a secondary node, only connections from this address will be accepted. 🔒

A special value of none can be used when the remote address is not yet known (eg. the other node is not set up yet). No stress, it happens 💅

🌟 source ⟨addr⟩

Local address to bind to before connecting to the remote hastd daemon. Format is the same as for the listen statement.

🌈 FILES 🌈

  • /etc/hast.conf — the default hastctl(8) and hastd(8) configuration file. 🏠
  • /var/run/hastctl — the control socket used by the hastctl(8) control utility to communicate with the hastd(8) daemon.

🌈 EXAMPLES 🌈

Okay bestie, this is the part where it all comes together — here's what an example configuration file can look like:

listen tcp://0.0.0.0

on hasta {
        listen tcp://2001:db8::1/64
}
on hastb {
        listen tcp://2001:db8::2/64
}

resource shared {
        local /dev/da0

        on hasta {
                remote tcp://10.0.0.2
        }
        on hastb {
                remote tcp://10.0.0.1
        }
}
resource tank {
        on hasta {
                local /dev/mirror/tanka
                source tcp://10.0.0.1
                remote tcp://10.0.0.2
        }
        on hastb {
                local /dev/mirror/tankb
                source tcp://10.0.0.2
                remote tcp://10.0.0.1
        }
}

So like, vibe check on what's happening here 💅 — the global listen tcp://0.0.0.0 is the main character, and then each node (on hasta { ... } and on hastb { ... }) gets its own listen line with its very own address. Then the resource shared { ... } block declares a local /dev/da0 and points each node at the other node's remote address. And resource tank { ... } gives each node its own local device (/dev/mirror/tanka on hasta, /dev/mirror/tankb on hastb) plus a source and a remote — iconic, symmetric, obsessed ✨

👀 SEE ALSO 👀

Go read these next, fr fr:

🫶 AUTHORS 🫶

The hast.conf was written by Pawel Jakub Dawidek <pjd@FreeBSD.org> under sponsorship of the FreeBSD Foundation. Giving credit where credit is due, periodt 👑

And that's the whole page, bestie — you ate that 🎀

This page came from the Debian distribution, dated January 25, 2012, and it's HAST.CONF(5) — section 5, file formats, iykyk 💜

📦 where this page comes from