207 lines
6.2 KiB
Groff
207 lines
6.2 KiB
Groff
.\" $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.
|