.\"     $NetBSD: wapbl.4,v 1.16 2013/05/29 14:55:24 wiz Exp $
.\"
.\" Copyright (c) 2008, 2009, 2012 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 December 3, 2012
.Dt WAPBL 4
.Os
.Sh NAME
.Nm WAPBL
.Nd Write Ahead Physical Block Logging file system journaling
.Sh SYNOPSIS
.Cd options WAPBL
.Cd options WAPBL_DEBUG
.Sh DESCRIPTION
The
.Nm
driver provides meta-data journaling 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.
.Pp
WAPBL currently maintains its journal in one of two locations:
.Bl -tag -width indent
.It - 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.
.It - 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.
.El
.Pp
A new journal is created automatically when a file system is mounted
via
.Xr mount 8
with the
.Fl o Ar 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.
.Pp
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
.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.
.Pp
For a new file system,
.Bd -literal -offset indent
newfs -s -64m wd0a
.Ed
.Pp
can be used to leave space for a 64MB journal at the end of
.Pa /dev/wd0a .
.Pp
To specify the size of the journal within the file system
.Xr tunefs 8
can be used as follows:
.Bd -literal -offset indent
tunefs -l 64m wd0a
.Ed
.Pp
to indicate that a journal of size 64MB on the file system on
.Pa /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
.Dq -o log
option.
For existing file systems and general use, however, simply using
.Bd -literal -offset indent
mount -o log /dev/wd0a /mnt
.Ed
.Pp
will be sufficient to create an appropriate journal within the file
system.
Running
.Bd -literal -offset indent
tunefs -l 0 wd0a
.Ed
.Pp
will schedule the log for removal on the next read-write mount, and
running
.Bd -literal -offset indent
tunefs -l 0 wd0a
.Ed
.Pp
followed by
.Bd -literal -offset indent
mount -o log /dev/wd0a /mnt
.Ed
.Pp
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.
.Pp
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.
.Pp
For kernel developers, the compile time option
.Dv WAPBL_DEBUG
turns on debugging.
.Sh SEE ALSO
.Xr config 1 ,
.Xr fsck 8 ,
.Xr mount 8 ,
.Xr newfs 8 ,
.Xr umount 8
.Sh HISTORY
.An -nosplit
.Nm
was originally written by
.An Darrin B. Jewell
while at Wasabi Systems Inc.
Wasabi Systems contributed the code to
.Nx ,
and it was integrated by
.An Simon Burge ,
.An Antti Kantee ,
.An Andy Doran ,
and
.An Greg Oster .
.Pp
.Nm
first appeared in
.Nx 5.0 .
.Sh CAVEATS
Older releases of the system, and other systems that support the
.Dv UFS
format should only access
.Nm
file systems in read-only mode.
Additionally, the
.Xr fsck 8
command from such systems should not be run against
.Nm
file systems.
Failure to observe these guidelines may damage the file system.
.Pp
.Nm
requires the super block to be in the UFS2 format.
The super block format can be checked using the
.Fl s
option with
.Xr dumpfs 8 ,
and older FFSv1 file systems will need to be updated to the newer
super block layout with the
.Fl c
option to
.Xr fsck_ffs 8 .
.Pp
.Xr 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
.Xr fsync 2
often.
.Pp
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
.Dq dangling inode
issue, requiring an
.Xr fsck 8
to fix.