WAPBL(4)

📦 version 11.0, in nixpkgs unstable

💅 WAPBL(4) — a lil' kernel-interfaces-manual moment

okay bestie, pull up a seat because we're talking about wapbl(4) — that's the Write Ahead Physical Block Logging situation, aka the kernel-interfaces-manual girlie who keeps your file system from having a whole meltdown. she's iconic, she's useful, and honestly? she ate. 🎀

✨ NAME ✨

WAPBL — Write Ahead Physical Block Logging file system journaling. yes that's the whole name, and yes she's got main character energy. 💅

🌸 SYNOPSIS 🌸

options WAPBL
options WAPBL_DEBUG

that's it, that's the vibe check. two little lines and you're in. 🦋

💖 DESCRIPTION 💖

the WAPBL driver provides meta-data journaling for file systems. and like, in particular? it's the one hanging out with the fast file system (FFS), giving you rapid file system consistency checking after a system outage. so when your machine decides to be dramatic and just... stop, WAPBL's got you. it also gives better general-use performance than regular FFS, which is lowkey the fun part. slay. ⭐

WAPBL currently maintains its journal in one of two locations, and no we are not picking favorites:

  • After the file system — the journal is placed in the same partition as the file system, but sitting between the file system and the end of the partition. cozy lil' tail-end situation. 🍓
  • Within the file system — the journal is allocated as a special contiguous file within the file system. and ngl, this journal file is not visible via normal file system access, so don't go looking for it in your ls output, she's private. 🙈

a new journal gets created automatically when a file system is mounted via mount(8) with the -o log option. and if no journal size has been specified with tunefs(8)? then the size of the journal is based on 1MB of journal per 1GB of file system, up to a maximum journal size of 64MB. math girlie behavior, honestly. 💜

if there's adequate space between the end of the file system and the end of the partition, then — unless the journal size has been specified with tunefs(8) — the journal will be created after the file system. to obtain that space between the file system and the end of the partition, you can adjust the size of the partition using disklabel(8). ⚠️ care must be taken not to damage existing data on existing partitions, but this method works well if, like, a swap partition can be shrunk to accommodate the journal after the file system on a partition before the swap partition. reorganization era!

for a new file system,

newfs -s -64m wd0a

can be used to leave space for a 64MB journal at the end of /dev/wd0a. cute!

to specify the size of the journal within the file system, tunefs(8) can be used like this:

tunefs -l 64m wd0a

which is you indicating that a journal of size 64MB on the file system on /dev/wd0a should be created the next time that file system is mounted. 🫶 and bestie, listen — this must be done before the file system is mounted with the “-o log” option. no skipping ahead. for existing file systems and general use, though? simply using

mount -o log /dev/wd0a /mnt

will be sufficient to create an appropriate journal within the file system. easy! running

tunefs -l 0 wd0a

will schedule the log for removal on the next read-write mount. and running

tunefs -l 0 wd0a

followed by

mount -o log /dev/wd0a /mnt

will remove the log and then re-create it with the default size. 🔥 this method can also be used to grow or shrink the size of the journal, by:

  1. first scheduling the log for removal,
  2. then mounting read-write, but with logging disabled (so no new log will be created),
  3. then unmounting again,
  4. setting the desired log size, and finally
  5. re-mounting with logging enabled.

a whole little ritual, but she works. 🌈

with the journal, fsck(8) is no longer required at system boot. if the system has been shutdown in an unclean fashion, then the journal will be replayed when the file system is mounted. that said, fsck(8) can still be used to force a consistency check of the file system should that be desired — sometimes you just want the extra validation, and honestly? valid. 💀

for kernel developers, the compile time option WAPBL_DEBUG turns on debugging. have fun, nerds. 👑

🦋 SEE ALSO 🦋

the whole friend group, fr fr. 💖

🎀 HISTORY 🎀

WAPBL was originally written by Darrin B. Jewell while at Wasabi Systems Inc. Wasabi Systems contributed the code to NetBSD, and it was integrated by Simon Burge, Antti Kantee, Andy Doran, and Greg Oster. a whole squad. 👑

WAPBL first appeared in NetBSD 5.0. queen debuted and never left. ✨

💀 CAVEATS 💀

okay paying attention now, this part actually matters:

older releases of the system, and other systems that support the UFS format, should only access WAPBL file systems in read-only mode. additionally, the fsck(8) command from such systems should not be run against WAPBL file systems. failure to observe these guidelines may damage the file system. no cap, that's a real one. 😭

WAPBL requires the super block to be in the UFS2 format. the super block format can be checked using the -s option with dumpfs(8), and older FFSv1 file systems will need to be updated to the newer super block layout with the -c option to fsck_ffs(8). upgrade your girlie. 💅

fsync(2) causes all outstanding metadata transactions to be committed to disk, introducing additional latency. this can have an impact on database software and other software that calls fsync(2) often. so like, known behavior, not a bug, but worth knowing. 🫶

in-file system log allocation should be done on a relatively quiet file system. the error path for log allocation failures could result in a “dangling inode” issue, requiring an fsck(8) to fix. so don't do this while everything's loud and busy, mmkay? 🍓

💖 that's the whole page bestie, go forth and journal 💖

🌸 mwah, this one came from the Debian crew, dated December 3, 2012 — so, like, a vintage icon. WAPBL(4), out. 💜

📦 where this page comes from