Copyright (c) 2008 The NetBSD Foundation, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd July 21, 2008 .Dt WAPBL 4 .Os .Sh NAME .Nm WAPBL .Nd Write Ahead Physical Block Logging file system journalling .Sh SYNOPSIS .Cd options WAPBL .Cd options WAPBL_DEBUG .Cd options WAPBL_DEBUG_SERIALIZE .Sh DESCRIPTION The .Nm driver provides meta-data journalling for file systems. In particular, it is used with the fast file system (FFS) to provide rapid file system consistency checking after a system outage. It also provides better general-use performance over regular FFS.
p WAPBL currently maintains its journal in one of two locations: l -tag -width indent t - After the file system The journal is placed in the same partition as the file system, but between the filesystem and the end of the partition. t - Within the file system The journal is allocated as a special contiguous file within the filesystem. The journal file is not visible via normal file system access. .El
p A new journal is created automatically when a file system is mounted via .Xr mount 8 with the
a -o log option. If no journal size has been specified with .Xr 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.
p If there is adequate space between the end of the the file system and the end of the partition, then unless the journal size has been specified with .Xr 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 .Xr 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.
p For a new file system, d -literal -offset indent newfs -s -64m /dev/rwd0a .Ed
p can be used to leave space for a 64MB journal at the end of
p To specify the size of the journal within the file system .Xr tunefs 8 can be used as follows: d -literal -offset indent tunefs -l 64m /dev/rwd0a .Ed
p to indicate that a journal of size 64MB on the file system on
a /dev/rwd0a should be created the next time that file system is mounted. This must be done before the file system is mounted with the .Dq -o log option. For existing file systems and general use, however, simply using d -literal -offset indent mount -o log /dev/rwd0a /mnt .Ed
p will be sufficient to create an appropriate journal within the file system. Running d -literal -offset indent tunefs -l 0 /dev/rwd0a .Ed
p will schedule the log for removal on the next read-write mount, and running d -literal -offset indent tunefs -l 0 /dev/rwd0a .Ed
p followed by d -literal -offset indent mount -o log /dev/rwd0a /mnt .Ed
p 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.
p With the journal, .Xr 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. .Xr fsck 8 can still be used to force a consistency check of the file system should that be desired. .Xr WAPBL 8 has a number of debugging options. The option d -unfilled -offset indent options WAPBL_DEBUG .Ed
p turns on general debugging. The option d -unfilled -offset indent options WAPBL_DEBUG_SERIALIZE .Ed
p forces the serialization of all IO. This is currently be used to help alleviate a performance issue seen on multi-core machines, where multiple simultaneous extractions of tar-files can cause degenerate performance.
p .Sh SEE ALSO .Xr config 1 , .Xr fsck 8 , .Xr newfs 8 , .Xr mount 8 , .Xr umount 8 .Sh CAVEATS .Xr fsync 2 causes the journal to be committed to disk, resulting in non-negligible performance issues.
p There are also some pending issues with multiple simultaneous tar-file extractions resulting in degenerate file system behavior. The current work-around is to use d -unfilled -offset indent options WAPBL_DEBUG_SERIALIZE .Ed
p as mentioned above.
p In-file system log allocation should be done on a relatively quiet file system. The error path for the log allocation could result in a .Dq dangling inode issue.
p If the file system is full then making a journal can fail. .Sh HISTORY .Nm was originally written by Darrin B. Jewell while at Wasabi Systems Inc. Wasabi Systems contributed the code to .Nx and it first appeared in .Nx 5.0 .