share/man/man4/wapbl.4

   1 .\"     $NetBSD: wapbl.4,v 1.11 2009/11/22 18:40:26 mbalmer Exp $
   2 .\"
   3 .\" Copyright (c) 2008, 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd November 23, 2009
  28 .Dt WAPBL 4
  29 .Os
  30 .Sh NAME
  31 .Nm WAPBL
  32 .Nd Write Ahead Physical Block Logging file system journaling
  33 .Sh SYNOPSIS
  34 .Cd options WAPBL
  35 .Cd options WAPBL_DEBUG
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 driver provides meta-data journaling for file systems.
  40 In particular, it is used with the fast file system (FFS) to provide
  41 rapid file system consistency checking after a system outage.
  42 It also provides better general-use performance over regular FFS.
  43 .Pp
  44 WAPBL currently maintains its journal in one of two locations:
  45 .Bl -tag -width indent
  46 .It - After the file system
  47 The journal is placed in the same partition as the file system, but
  48 between the file system and the end of the partition.
  49 .It - Within the file system
  50 The journal is allocated as a special contiguous file within the
  51 file system.
  52 The journal file is not visible via normal file system access.
  53 .El
  54 .Pp
  55 A new journal is created automatically when a file system is mounted
  56 via
  57 .Xr mount 8
  58 with the
  59 .Fl o Ar log
  60 option.
  61 If no journal size has been specified with
  62 .Xr tunefs 8 ,
  63 then the size of the journal
  64 will be based on 1MB of journal per 1GB of file system, to a maximum
  65 journal size of 64MB.
  66 .Pp
  67 If there is adequate space between the end of the file system and
  68 the end of the partition, then unless the journal size has been
  69 specified with
  70 .Xr tunefs 8
  71 then the journal will be created after the file system.
  72 To obtain space between the file system and the end of the partition
  73 the size of the partition can be adjusted using
  74 .Xr disklabel 8 .
  75 Care must be taken not to damage existing data on existing partitions,
  76 but this method will work well if, for example, a swap partition can
  77 be shrunk in order to accommodate the journal after the file system on
  78 a partition before the swap partition.
  79 .Pp
  80 For a new file system,
  81 .Bd -literal -offset indent
  82 newfs -s -64m wd0a
  83 .Ed
  84 .Pp
  85 can be used to leave space for a 64MB journal at the end of
  86 .Pa /dev/wd0a .
  87 .Pp
  88 To specify the size of the journal within the file system
  89 .Xr tunefs 8
  90 can be used as follows:
  91 .Bd -literal -offset indent
  92 tunefs -l 64m wd0a
  93 .Ed
  94 .Pp
  95 to indicate that a journal of size 64MB on the file system on
  96 .Pa /dev/wd0a
  97 should be created the next time that file system is mounted.
  98 This must be done before the file system is mounted with the
  99 .Dq -o log
 100 option.
 101 For existing file systems and general use, however, simply using
 102 .Bd -literal -offset indent
 103 mount -o log /dev/wd0a /mnt
 104 .Ed
 105 .Pp
 106 will be sufficient to create an appropriate journal within the file
 107 system.
 108 Running
 109 .Bd -literal -offset indent
 110 tunefs -l 0 wd0a
 111 .Ed
 112 .Pp
 113 will schedule the log for removal on the next read-write mount, and
 114 running
 115 .Bd -literal -offset indent
 116 tunefs -l 0 wd0a
 117 .Ed
 118 .Pp
 119 followed by
 120 .Bd -literal -offset indent
 121 mount -o log /dev/wd0a /mnt
 122 .Ed
 123 .Pp
 124 will remove the log and then re-create it with the default size.
 125 This method can also be used to grow or shrink the size of the journal.
 126 .Pp
 127 With the journal,
 128 .Xr fsck 8
 129 is no longer required at system boot.
 130 If the system has been shutdown in an unclean fashion then the journal
 131 will be replayed when the file system is mounted.
 132 .Xr fsck 8
 133 can still be used to force a consistency check of the file system
 134 should that be desired.
 135 .Pp
 136 For kernel developers, the compile time option
 137 .Dv WAPBL_DEBUG
 138 turns on debugging.
 139 .Sh SEE ALSO
 140 .Xr config 1 ,
 141 .Xr fsck 8 ,
 142 .Xr mount 8 ,
 143 .Xr newfs 8 ,
 144 .Xr umount 8
 145 .Sh HISTORY
 146 .An -nosplit
 147 .Nm
 148 was originally written by
 149 .An Darrin B. Jewell
 150 while at Wasabi Systems Inc.
 151 Wasabi Systems contributed the code to
 152 .Nx
 153 and was integrated by
 154 .An Simon Burge ,
 155 .An Antti Kantee ,
 156 .An Andy Doran ,
 157 and
 158 .An Greg Oster .
 159 .Pp
 160 .Nm
 161 first appeared in
 162 .Nx 5.0 .
 163 .Sh CAVEATS
 164 Older releases of the system, and other systems that support the
 165 .Dv UFS
 166 format should only access
 167 .Nm
 168 file systems in read-only mode.
 169 Additionally, the
 170 .Xr fsck 8
 171 command from such systems should not be run against
 172 .Nm
 173 file systems.
 174 Failure to observe these guidelines may damage the file system.
 175 .Pp
 176 .Nm
 177 requires the super block to be in the UFS2 format.
 178 The super block format can be checked using the
 179 .Fl s
 180 option with
 181 .Xr dumpfs 8 ,
 182 and older FFSv1 file systems will need to be updated to the newer
 183 super block layout with the
 184 .Fl c
 185 option to
 186 .Xr fsck_ffs 8 .
 187 .Pp
 188 .Xr fsync 2
 189 causes all outstanding metadata transactions to be committed to disk,
 190 introducing additional latency.
 191 This can have an impact on database software and other software
 192 that calls
 193 .Xr fsync 2
 194 often.
 195 .Pp
 196 File system snapshots
 197 .Pq Xr fss 4
 198 and quotas do not yet work with
 199 .Nm .
 200 .Pp
 201 In-file system log allocation should be done on a relatively quiet
 202 file system.
 203 The error path for log allocation failures could result in a
 204 .Dq dangling inode
 205 issue, requiring an
 206 .Xr fsck 8
 207 to fix.