sbin/geom/class/journal/gjournal.8

   1 .\" Copyright (c) 2006-2007 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 April 13, 2008
  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
  63 The
  64 .Nm
  65 utility is used for journal configuration on the given GEOM provider.
  66 The Journal and data may be stored on the same provider or on two separate
  67 providers.
  68 This is block level journaling, not file system level journaling, which means
  69 everything gets logged, e.g.\& for file systems, it journals both data and
  70 metadata.
  71 The
  72 .Nm
  73 GEOM class can talk to file systems, which allows the use of
  74 .Nm
  75 for file system journaling and to keep file systems in a consistent state.
  76 At this time, only UFS file system is supported.
  77 .Pp
  78 To configure journaling on the UFS file system using
  79 .Nm ,
  80 one should first create a
  81 .Nm
  82 provider using the
  83 .Nm
  84 utility, then run
  85 .Xr newfs 8
  86 or
  87 .Xr tunefs 8
  88 on it with the
  89 .Fl J
  90 flag which instructs UFS to cooperate with the
  91 .Nm
  92 provider below.
  93 There are important differences in how journaled UFS works.
  94 The most important one is that
  95 .Xr sync 2
  96 and
  97 .Xr fsync 2
  98 system calls do not work as expected anymore.
  99 To ensure that data is stored on the data provider, the
 100 .Nm Cm sync
 101 command should be used after calling
 102 .Xr sync 2 .
 103 For the best performance possible, soft-updates should be disabled when
 104 .Nm
 105 is used.
 106 It is also safe and recommended to use the
 107 .Cm async
 108 .Xr mount 8
 109 option.
 110 .Pp
 111 When
 112 .Nm
 113 is configured on top of
 114 .Xr gmirror 8
 115 or
 116 .Xr graid3 8
 117 providers, it also keeps them in a consistent state, thus
 118 automatic synchronization on power failure or system crash may be disabled
 119 on those providers.
 120 .Pp
 121 The
 122 .Nm
 123 utility uses on-disk metadata, stored in the provider's last sector,
 124 to store all needed information.
 125 This could be a problem when an existing file system is converted to use
 126 .Nm .
 127 .Pp
 128 The first argument to
 129 .Nm
 130 indicates an action to be performed:
 131 .Bl -tag -width ".Cm status"
 132 .It Cm label
 133 Configures
 134 .Nm
 135 on the given provider(s).
 136 If only one provider is given, both data and journal are stored on the same
 137 provider.
 138 If two providers are given, the first one will be used as data provider and the
 139 second will be used as the journal provider.
 140 .Pp
 141 Additional options include:
 142 .Bl -tag -width ".Fl s Ar jsize"
 143 .It Fl c
 144 Checksum journal records.
 145 .It Fl f
 146 May be used to convert an existing file system to use
 147 .Nm ,
 148 but only if the journal will be configured on a separate provider and if the
 149 last sector in the data provider is not used by the existing file system.
 150 If
 151 .Nm
 152 detects that the last sector is used, it will refuse to overwrite it
 153 and return an error.
 154 This behavior may be forced by using the
 155 .Fl f
 156 flag, which will force
 157 .Nm
 158 to overwrite the last sector.
 159 .It Fl h
 160 Hardcode provider names in metadata.
 161 .It Fl s Ar jsize
 162 Specifies size of the journal if only one provider is used for both data and
 163 journal.
 164 The default is one gigabyte.
 165 Size should be chosen based on provider's load, and not on its size.
 166 It is not recommended to use
 167 .Nm
 168 for small file systems (e.g.: only few gigabytes big).
 169 .El
 170 .It Cm clear
 171 Clear metadata on the given providers.
 172 .It Cm stop
 173 Stop the given provider.
 174 .Pp
 175 Additional options include:
 176 .Bl -tag -width ".Fl f"
 177 .It Fl f
 178 Stop the given provider even if it is opened.
 179 .El
 180 .It Cm sync
 181 Trigger journal switch and enforce sending data to the data provider.
 182 .It Cm dump
 183 Dump metadata stored on the given providers.
 184 .It Cm list
 185 See
 186 .Xr geom 8 .
 187 .It Cm status
 188 See
 189 .Xr geom 8 .
 190 .It Cm load
 191 See
 192 .Xr geom 8 .
 193 .It Cm unload
 194 See
 195 .Xr geom 8 .
 196 .El
 197 .Pp
 198 Additional options include:
 199 .Bl -tag -width ".Fl v"
 200 .It Fl v
 201 Be more verbose.
 202 .El
 203 .Sh EXIT STATUS
 204 Exit status is 0 on success, and 1 if the command fails.
 205 .Sh EXAMPLES
 206 Create a
 207 .Nm
 208 based UFS file system and mount it:
 209 .Bd -literal -offset indent
 210 gjournal load
 211 gjournal label da0
 212 newfs -J /dev/da0.journal
 213 mount -o async /dev/da0.journal /mnt
 214 .Ed
 215 .Pp
 216 Configure journaling on an existing file system, but only if
 217 .Nm
 218 allows this (i.e., if the last sector is not already used by the file system):
 219 .Bd -literal -offset indent
 220 umount /dev/da0s1d
 221 gjournal label da0s1d da0s1e && \e
 222     tunefs -J enable -n disable da01sd.journal && \e
 223     mount -o async /dev/da0s1d.journal /mnt || \e
 224     mount /dev/da0s1d /mnt
 225 .Ed
 226 .Sh SEE ALSO
 227 .Xr geom 4 ,
 228 .Xr geom 8 ,
 229 .Xr mount 8 ,
 230 .Xr newfs 8 ,
 231 .Xr tunefs 8 ,
 232 .Xr umount 8
 233 .Sh HISTORY
 234 The
 235 .Nm
 236 utility appeared in
 237 .Fx 7.0 .
 238 .Sh AUTHORS
 239 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
 240 .Sh BUGS
 241 Documentation for sysctls
 242 .Va kern.geom.journal.*
 243 is missing.