1.\" $NetBSD: wapbl.4,v 1.16 2013/05/29 14:55:24 wiz Exp $ 2.\" 3.\" Copyright (c) 2008, 2009, 2012 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 December 3, 2012 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 37The 38.Nm 39driver provides meta-data journaling for file systems. 40In particular, it is used with the fast file system (FFS) to provide 41rapid file system consistency checking after a system outage. 42It also provides better general-use performance over regular FFS. 43.Pp 44WAPBL currently maintains its journal in one of two locations: 45.Bl -tag -width indent 46.It - After the file system 47The journal is placed in the same partition as the file system, but 48between the file system and the end of the partition. 49.It - Within the file system 50The journal is allocated as a special contiguous file within the 51file system. 52The journal file is not visible via normal file system access. 53.El 54.Pp 55A new journal is created automatically when a file system is mounted 56via 57.Xr mount 8 58with the 59.Fl o Ar log 60option. 61If no journal size has been specified with 62.Xr tunefs 8 , 63then the size of the journal 64will be based on 1MB of journal per 1GB of file system, to a maximum 65journal size of 64MB. 66.Pp 67If there is adequate space between the end of the file system and 68the end of the partition, then unless the journal size has been 69specified with 70.Xr tunefs 8 71then the journal will be created after the file system. 72To obtain space between the file system and the end of the partition 73the size of the partition can be adjusted using 74.Xr disklabel 8 . 75Care must be taken not to damage existing data on existing partitions, 76but this method will work well if, for example, a swap partition can 77be shrunk in order to accommodate the journal after the file system on 78a partition before the swap partition. 79.Pp 80For a new file system, 81.Bd -literal -offset indent 82newfs -s -64m wd0a 83.Ed 84.Pp 85can be used to leave space for a 64MB journal at the end of 86.Pa /dev/wd0a . 87.Pp 88To specify the size of the journal within the file system 89.Xr tunefs 8 90can be used as follows: 91.Bd -literal -offset indent 92tunefs -l 64m wd0a 93.Ed 94.Pp 95to indicate that a journal of size 64MB on the file system on 96.Pa /dev/wd0a 97should be created the next time that file system is mounted. 98This must be done before the file system is mounted with the 99.Dq -o log 100option. 101For existing file systems and general use, however, simply using 102.Bd -literal -offset indent 103mount -o log /dev/wd0a /mnt 104.Ed 105.Pp 106will be sufficient to create an appropriate journal within the file 107system. 108Running 109.Bd -literal -offset indent 110tunefs -l 0 wd0a 111.Ed 112.Pp 113will schedule the log for removal on the next read-write mount, and 114running 115.Bd -literal -offset indent 116tunefs -l 0 wd0a 117.Ed 118.Pp 119followed by 120.Bd -literal -offset indent 121mount -o log /dev/wd0a /mnt 122.Ed 123.Pp 124will remove the log and then re-create it with the default size. 125This method can also be used to grow or shrink the size of the journal 126by first scheduling the log for removal, then mounting read-write, but 127with logging disabled (so no new log will be created), then unmounting 128again, setting the desired log size and finally re-mounting with logging 129enabled. 130.Pp 131With the journal, 132.Xr fsck 8 133is no longer required at system boot. 134If the system has been shutdown in an unclean fashion then the journal 135will be replayed when the file system is mounted. 136.Xr fsck 8 137can still be used to force a consistency check of the file system 138should that be desired. 139.Pp 140For kernel developers, the compile time option 141.Dv WAPBL_DEBUG 142turns on debugging. 143.Sh SEE ALSO 144.Xr config 1 , 145.Xr fsck 8 , 146.Xr mount 8 , 147.Xr newfs 8 , 148.Xr umount 8 149.Sh HISTORY 150.An -nosplit 151.Nm 152was originally written by 153.An Darrin B. Jewell 154while at Wasabi Systems Inc. 155Wasabi Systems contributed the code to 156.Nx , 157and it was integrated by 158.An Simon Burge , 159.An Antti Kantee , 160.An Andy Doran , 161and 162.An Greg Oster . 163.Pp 164.Nm 165first appeared in 166.Nx 5.0 . 167.Sh CAVEATS 168Older releases of the system, and other systems that support the 169.Dv UFS 170format should only access 171.Nm 172file systems in read-only mode. 173Additionally, the 174.Xr fsck 8 175command from such systems should not be run against 176.Nm 177file systems. 178Failure to observe these guidelines may damage the file system. 179.Pp 180.Nm 181requires the super block to be in the UFS2 format. 182The super block format can be checked using the 183.Fl s 184option with 185.Xr dumpfs 8 , 186and older FFSv1 file systems will need to be updated to the newer 187super block layout with the 188.Fl c 189option to 190.Xr fsck_ffs 8 . 191.Pp 192.Xr fsync 2 193causes all outstanding metadata transactions to be committed to disk, 194introducing additional latency. 195This can have an impact on database software and other software 196that calls 197.Xr fsync 2 198often. 199.Pp 200In-file system log allocation should be done on a relatively quiet 201file system. 202The error path for log allocation failures could result in a 203.Dq dangling inode 204issue, requiring an 205.Xr fsck 8 206to fix. 207