226 lines
6.7 KiB
Groff
226 lines
6.7 KiB
Groff
.\" $NetBSD: wapbl.4,v 1.6 2008/08/02 14:29:12 simonb Exp $
|
|
.\"
|
|
.\" 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 journaling
|
|
.Sh SYNOPSIS
|
|
.Cd options WAPBL
|
|
.Cd options WAPBL_DEBUG
|
|
.Cd options WAPBL_DEBUG_SERIALIZE
|
|
.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
|
|
.Pa -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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
For a new file system,
|
|
.Bd -literal -offset indent
|
|
newfs -s -64m /dev/rwd0a
|
|
.Ed
|
|
.Pp
|
|
can be used to leave space for a 64MB journal at the end of
|
|
.Pa /dev/rwd0a .
|
|
.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 /dev/rwd0a
|
|
.Ed
|
|
.Pp
|
|
to indicate that a journal of size 64MB on the file system on
|
|
.Pa /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
|
|
.Bd -literal -offset indent
|
|
mount -o log /dev/rwd0a /mnt
|
|
.Ed
|
|
.Pp
|
|
will be sufficient to create an appropriate journal within the file
|
|
system.
|
|
Running
|
|
.Bd -literal -offset indent
|
|
tunefs -l 0 /dev/rwd0a
|
|
.Ed
|
|
.Pp
|
|
will schedule the log for removal on the next read-write mount, and
|
|
running
|
|
.Bd -literal -offset indent
|
|
tunefs -l 0 /dev/rwd0a
|
|
.Ed
|
|
.Pp
|
|
followed by
|
|
.Bd -literal -offset indent
|
|
mount -o log /dev/rwd0a /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.
|
|
.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
|
|
.Xr WAPBL 8
|
|
has a number of debugging options.
|
|
The option
|
|
.Bd -unfilled -offset indent
|
|
options WAPBL_DEBUG
|
|
.Ed
|
|
.Pp
|
|
turns on general debugging.
|
|
The option
|
|
.Bd -unfilled -offset indent
|
|
options WAPBL_DEBUG_SERIALIZE
|
|
.Ed
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr config 1 ,
|
|
.Xr fsck 8 ,
|
|
.Xr newfs 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr umount 8
|
|
.Sh CAVEATS
|
|
An unreplayed
|
|
.Nm
|
|
journal (eg after a crash or power failure) may cause problems if the
|
|
file system is then used with an older kernel or userland what isn't
|
|
.Nm
|
|
aware.
|
|
.Pp
|
|
An older
|
|
.Xr fsck 8
|
|
that isn't
|
|
.Nm
|
|
aware will not be able to deal with an in-filesystem log.
|
|
.Pp
|
|
.Nm
|
|
requires the super block to be in the UFS2 format.
|
|
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 the journal to be committed to disk, resulting in
|
|
non-negligible performance issues.
|
|
This can have an impact on database software and other software
|
|
that calls
|
|
.Xr fsync 2
|
|
often.
|
|
.Pp
|
|
File system snapshots
|
|
.Xr ( fss 4 )
|
|
currently do not work with
|
|
.Nm .
|
|
.Pp
|
|
There are some pending issues with high metadata-rate workloads (like
|
|
multiple simultaneous tar-file extractions) resulting in degenerate file
|
|
system performance.
|
|
The current work-around is to use
|
|
.Bd -unfilled -offset indent
|
|
options WAPBL_DEBUG_SERIALIZE
|
|
.Ed
|
|
.Pp
|
|
as mentioned above.
|
|
.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.
|
|
.Pp
|
|
If the file system is full or close to 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 was integrated by Simon Burge, Antti Kantee, Andy Doran, and
|
|
Greg Oster.
|
|
.Pp
|
|
.Nm
|
|
first appeared in
|
|
.Nx 5.0 .
|