1.\" Copyright (c) 2006-2009 Pawel Jakub Dawidek <pjd@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 17, 2009 28.Dt GJOURNAL 8 29.Os 30.Sh NAME 31.Nm gjournal 32.Nd "control utility for journaled devices" 33.Sh SYNOPSIS 34.Nm 35.Cm label 36.Op Fl cfhv 37.Op Fl s Ar jsize 38.Ar dataprov 39.Op Ar jprov 40.Nm 41.Cm stop 42.Op Fl fv 43.Ar name ... 44.Nm 45.Cm sync 46.Op Fl v 47.Nm 48.Cm clear 49.Op Fl v 50.Ar prov ... 51.Nm 52.Cm dump 53.Ar prov ... 54.Nm 55.Cm list 56.Nm 57.Cm status 58.Nm 59.Cm load 60.Nm 61.Cm unload 62.Sh DESCRIPTION 63The 64.Nm 65utility is used for journal configuration on the given GEOM provider. 66The Journal and data may be stored on the same provider or on two separate 67providers. 68This is block level journaling, not file system level journaling, which means 69everything gets logged, e.g.\& for file systems, it journals both data and 70metadata. 71The 72.Nm 73GEOM class can talk to file systems, which allows the use of 74.Nm 75for file system journaling and to keep file systems in a consistent state. 76At this time, only UFS file system is supported. 77.Pp 78To configure journaling on the UFS file system using 79.Nm , 80one should first create a 81.Nm 82provider using the 83.Nm 84utility, then run 85.Xr newfs 8 86or 87.Xr tunefs 8 88on it with the 89.Fl J 90flag which instructs UFS to cooperate with the 91.Nm 92provider below. 93There are important differences in how journaled UFS works. 94The most important one is that 95.Xr sync 2 96and 97.Xr fsync 2 98system calls do not work as expected anymore. 99To ensure that data is stored on the data provider, the 100.Nm Cm sync 101command should be used after calling 102.Xr sync 2 . 103For the best performance possible, soft-updates should be disabled when 104.Nm 105is used. 106It is also safe and recommended to use the 107.Cm async 108.Xr mount 8 109option. 110.Pp 111When 112.Nm 113is configured on top of 114.Xr gmirror 8 115or 116.Xr graid3 8 117providers, it also keeps them in a consistent state, thus 118automatic synchronization on power failure or system crash may be disabled 119on those providers. 120.Pp 121The 122.Nm 123utility uses on-disk metadata, stored in the provider's last sector, 124to store all needed information. 125This could be a problem when an existing file system is converted to use 126.Nm . 127.Pp 128The first argument to 129.Nm 130indicates an action to be performed: 131.Bl -tag -width ".Cm status" 132.It Cm label 133Configures 134.Nm 135on the given provider(s). 136If only one provider is given, both data and journal are stored on the same 137provider. 138If two providers are given, the first one will be used as data provider and the 139second will be used as the journal provider. 140.Pp 141Additional options include: 142.Bl -tag -width ".Fl s Ar jsize" 143.It Fl c 144Checksum journal records. 145.It Fl f 146May be used to convert an existing file system to use 147.Nm , 148but only if the journal will be configured on a separate provider and if the 149last sector in the data provider is not used by the existing file system. 150If 151.Nm 152detects that the last sector is used, it will refuse to overwrite it 153and return an error. 154This behavior may be forced by using the 155.Fl f 156flag, which will force 157.Nm 158to overwrite the last sector. 159.It Fl h 160Hardcode provider names in metadata. 161.It Fl s Ar jsize 162Specifies size of the journal if only one provider is used for both data and 163journal. 164The default is one gigabyte. 165Size should be chosen based on provider's load, and not on its size; 166recommended minimum is twice the size of the physical memory installed. 167It is not recommended to use 168.Nm 169for small file systems (e.g.: only few gigabytes big). 170.El 171.It Cm clear 172Clear metadata on the given providers. 173.It Cm stop 174Stop the given provider. 175.Pp 176Additional options include: 177.Bl -tag -width ".Fl f" 178.It Fl f 179Stop the given provider even if it is opened. 180.El 181.It Cm sync 182Trigger journal switch and enforce sending data to the data provider. 183.It Cm dump 184Dump metadata stored on the given providers. 185.It Cm list 186See 187.Xr geom 8 . 188.It Cm status 189See 190.Xr geom 8 . 191.It Cm load 192See 193.Xr geom 8 . 194.It Cm unload 195See 196.Xr geom 8 . 197.El 198.Pp 199Additional options include: 200.Bl -tag -width ".Fl v" 201.It Fl v 202Be more verbose. 203.El 204.Sh EXIT STATUS 205Exit status is 0 on success, and 1 if the command fails. 206.Sh EXAMPLES 207Create a 208.Nm 209based UFS file system and mount it: 210.Bd -literal -offset indent 211gjournal load 212gjournal label da0 213newfs -J /dev/da0.journal 214mount -o async /dev/da0.journal /mnt 215.Ed 216.Pp 217Configure journaling on an existing file system, but only if 218.Nm 219allows this (i.e., if the last sector is not already used by the file system): 220.Bd -literal -offset indent 221umount /dev/da0s1d 222gjournal label da0s1d da0s1e && \e 223 tunefs -J enable -n disable da0s1d.journal && \e 224 mount -o async /dev/da0s1d.journal /mnt || \e 225 mount /dev/da0s1d /mnt 226.Ed 227.Sh SYSCTLS 228Gjournal adds the sysctl level kern.geom.journal. 229The string and integer information available is detailed below. 230The changeable column shows whether a process with appropriate privilege may 231change the value. 232.Bl -column "accept_immediatelyXXXXXX" integerXXX -offset indent 233.It Sy "sysctl name Type Changeable" 234.It "debug integer yes" 235.It "switch_time integer yes" 236.It "force_switch integer yes" 237.It "parallel_flushes integer yes" 238.It "accept_immediately integer yes" 239.It "parallel_copies integer yes" 240.It "record_entries integer yes" 241.It "optimize integer yes" 242.El 243.Bl -tag -width 6n 244.It Li debug 245Setting a non-zero value enables debugging at various levels. 246Debug level 1 will record actions at a journal level, relating to journal 247switches, metadata updates, etc. 248Debug level 2 will record actions at a higher level, relating to the numbers of 249entries in journals, access requests, etc. 250Debug level 3 will record verbose detail, including insertion of I/Os to the 251journal. 252.It Li switch_time 253The maximum number of seconds a journal is allowed to remain open before 254switching to a new journal. 255.It Li force_switch 256Force a journal switch when the journal uses more than N% of the free journal 257space. 258.It Li parallel_flushes 259The number of flush I/O requests to be sent in parallel when flushing the 260journal to the data provider. 261.It Li accept_immediately 262The maximum number of I/O requests accepted at the same time. 263.It Li parallel_copies 264The number of copy I/O requests to send in parallel. 265.It Li record_entries 266The maximum number of record entries to allow in a single journal. 267.It Li optimize 268Controls whether entries in a journal will be optimized by combining overlapping 269I/Os into a single I/O and reordering the entries in a journal. 270This can be disabled by setting the sysctl to 0. 271.El 272.Ss cache 273The string and integer information available for the cache level 274is detailed below. 275The changeable column shows whether a process with appropriate 276privilege may change the value. 277.Bl -column "alloc_failuresXXXXXX" integerXXX -offset indent 278.It Sy "sysctl name Type Changeable" 279.It "used integer no" 280.It "limit integer yes" 281.It "divisor integer no" 282.It "switch integer yes" 283.It "misses integer yes" 284.It "alloc_failures integer yes" 285.El 286.Bl -tag -width 6n 287.It Li used 288The number of bytes currently allocated to the cache. 289.It Li limit 290The maximum number of bytes to be allocated to the cache. 291.It Li divisor 292Sets the cache size to be used as a proportion of kmem_size. 293A value of 2 (the default) will cause the cache size to be set to 1/2 of the 294kmem_size. 295.It Li switch 296Force a journal switch when this percentage of cache has been used. 297.It Li misses 298The number of cache misses, when data has been read, but was not found in the 299cache. 300.It Li alloc_failures 301The number of times memory failed to be allocated to the cache because the cache 302limit was hit. 303.El 304.Ss stats 305The string and integer information available for the statistics level 306is detailed below. 307The changeable column shows whether a process with appropriate 308privilege may change the value. 309.Bl -column "skipped_bytesXXXXXX" integerXXX -offset indent 310.It Sy "sysctl name Type Changeable" 311.It "skipped_bytes integer yes" 312.It "combined_ios integer yes" 313.It "switches integer yes" 314.It "wait_for_copy integer yes" 315.It "journal_full integer yes" 316.It "low_mem integer yes" 317.El 318.Bl -tag -width 6n 319.It Li skipped_bytes 320The number of bytes skipped. 321.It Li combined_ios 322The number of I/Os which were combined by journal optimization. 323.It Li switches 324The number of journal switches. 325.It Li wait_for_copy 326The number of times the journal switch process had to wait for the previous 327journal copy to complete. 328.It Li journal_full 329The number of times the journal was almost full, forcing a journal switch. 330.It Li low_mem 331The number of times the low_mem hook was called. 332.El 333.Sh SEE ALSO 334.Xr geom 4 , 335.Xr geom 8 , 336.Xr mount 8 , 337.Xr newfs 8 , 338.Xr tunefs 8 , 339.Xr umount 8 340.Sh HISTORY 341The 342.Nm 343utility appeared in 344.Fx 7.0 . 345.Sh AUTHORS 346.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org 347