wapbl(4) - NetBSD Manual Pages

WAPBL(4)                NetBSD Kernel Interfaces Manual               WAPBL(4)


NAME

     WAPBL -- Write Ahead Physical Block Logging file system journaling


SYNOPSIS

     options WAPBL
     options WAPBL_DEBUG


DESCRIPTION

     The WAPBL driver provides meta-data journaling for file systems.  In par-
     ticular, it is used with the fast file system (FFS) to provide rapid file
     system consistency checking after a system outage.  It also provides bet-
     ter general-use performance over regular FFS.

     WAPBL currently maintains its journal in one of two locations:

     - After the file system
             The journal is placed in the same partition as the file system,
             but between the file system and the end of the partition.

     - Within the file system
             The journal is allocated as a special contiguous file within the
             file system.  The journal file is not visible via normal file
             system access.

     A new journal is created automatically when a file system is mounted via
     mount(8) with the -o log option.  If no journal size has been specified
     with tunefs(8), then the size of the journal will be based on 1MB of
     journal per 1GB of file system, to a maximum journal size of 64MB.

     If there is 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) then the journal will be created after the file system.  To
     obtain space between the file system and the end of the partition the
     size of the partition can be adjusted using disklabel(8).  Care must be
     taken not to damage existing data on existing partitions, but this method
     will work well if, for example, a swap partition can be shrunk in order
     to accommodate the journal after the file system on a partition before
     the swap partition.

     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.

     To specify the size of the journal within the file system tunefs(8) can
     be used as follows:

           tunefs -l 64m wd0a

     to indicate that a journal of size 64MB on the file system on /dev/wd0a
     should be created the next time that file system is mounted.  This must
     be done before the file system is mounted with the ``-o log'' option.
     For existing file systems and general use, however, simply using

           mount -o log /dev/wd0a /mnt

     will be sufficient to create an appropriate journal within the file sys-
     tem.  Running

           tunefs -l 0 wd0a

     will schedule the log for removal on the next read-write mount, and run-
     ning

           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
     first scheduling the log for removal, then mounting read-write, but with
     logging disabled (so no new log will be created), then unmounting again,
     setting the desired log size and finally re-mounting with logging
     enabled.

     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.  fsck(8) can still be used to
     force a consistency check of the file system should that be desired.

     For kernel developers, the compile time option WAPBL_DEBUG turns on
     debugging.


SEE ALSO

     config(1), fsck(8), mount(8), newfs(8), umount(8)


HISTORY

     WAPBL was originally written by Darrin B. Jewell while at Wasabi Systems
     Inc.  Wasabi Systems contributed the code to NetBSD, and it was inte-
     grated by Simon Burge, Antti Kantee, Andy Doran, and Greg Oster.

     WAPBL first appeared in NetBSD 5.0.


CAVEATS

     Older releases of the system, and other systems that support the UFS for-
     mat should only access WAPBL file systems in read-only mode.  Addition-
     ally, 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.

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

     fsync(2) causes all outstanding metadata transactions to be committed to
     disk, introducing additional latency.  This can have an impact on data-
     base software and other software that calls fsync(2) often.

     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.

NetBSD 8.1                     December 3, 2012                     NetBSD 8.1