sbin/geom/class/journal/gjournal.8

   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
  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 recommended minimum is twice the size of the physical memory installed.
 167 It is not recommended to use
 168 .Nm
 169 for small file systems (e.g.: only few gigabytes big).
 170 .El
 171 .It Cm clear
 172 Clear metadata on the given providers.
 173 .It Cm stop
 174 Stop the given provider.
 175 .Pp
 176 Additional options include:
 177 .Bl -tag -width ".Fl f"
 178 .It Fl f
 179 Stop the given provider even if it is opened.
 180 .El
 181 .It Cm sync
 182 Trigger journal switch and enforce sending data to the data provider.
 183 .It Cm dump
 184 Dump metadata stored on the given providers.
 185 .It Cm list
 186 See
 187 .Xr geom 8 .
 188 .It Cm status
 189 See
 190 .Xr geom 8 .
 191 .It Cm load
 192 See
 193 .Xr geom 8 .
 194 .It Cm unload
 195 See
 196 .Xr geom 8 .
 197 .El
 198 .Pp
 199 Additional options include:
 200 .Bl -tag -width ".Fl v"
 201 .It Fl v
 202 Be more verbose.
 203 .El
 204 .Sh EXIT STATUS
 205 Exit status is 0 on success, and 1 if the command fails.
 206 .Sh EXAMPLES
 207 Create a
 208 .Nm
 209 based UFS file system and mount it:
 210 .Bd -literal -offset indent
 211 gjournal load
 212 gjournal label da0
 213 newfs -J /dev/da0.journal
 214 mount -o async /dev/da0.journal /mnt
 215 .Ed
 216 .Pp
 217 Configure journaling on an existing file system, but only if
 218 .Nm
 219 allows this (i.e., if the last sector is not already used by the file system):
 220 .Bd -literal -offset indent
 221 umount /dev/da0s1d
 222 gjournal 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
 228 Gjournal adds the sysctl level kern.geom.journal.
 229 The string and integer information available is detailed below.
 230 The changeable column shows whether a process with appropriate privilege may
 231 change 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
 245 Setting a non-zero value enables debugging at various levels.
 246 Debug level 1 will record actions at a journal level, relating to journal
 247 switches, metadata updates, etc.
 248 Debug level 2 will record actions at a higher level, relating to the numbers of
 249 entries in journals, access requests, etc.
 250 Debug level 3 will record verbose detail, including insertion of I/Os to the
 251 journal.
 252 .It Li switch_time
 253 The maximum number of seconds a journal is allowed to remain open before
 254 switching to a new journal.
 255 .It Li force_switch
 256 Force a journal switch when the journal uses more than N% of the free journal
 257 space.
 258 .It Li parallel_flushes
 259 The number of flush I/O requests to be sent in parallel when flushing the
 260 journal to the data provider.
 261 .It Li accept_immediately
 262 The maximum number of I/O requests accepted at the same time.
 263 .It Li parallel_copies
 264 The number of copy I/O requests to send in parallel.
 265 .It Li record_entries
 266 The maximum number of record entries to allow in a single journal.
 267 .It Li optimize
 268 Controls whether entries in a journal will be optimized by combining overlapping
 269 I/Os into a single I/O and reordering the entries in a journal.
 270 This can be disabled by setting the sysctl to 0.
 271 .El
 272 .Ss cache
 273 The string and integer information available for the cache level
 274 is detailed below.
 275 The changeable column shows whether a process with appropriate
 276 privilege 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
 288 The number of bytes currently allocated to the cache.
 289 .It Li limit
 290 The maximum number of bytes to be allocated to the cache.
 291 .It Li divisor
 292 Sets the cache size to be used as a proportion of kmem_size.
 293 A value of 2 (the default) will cause the cache size to be set to 1/2 of the
 294 kmem_size.
 295 .It Li switch
 296 Force a journal switch when this percentage of cache has been used.
 297 .It Li misses
 298 The number of cache misses, when data has been read, but was not found in the
 299 cache.
 300 .It Li alloc_failures
 301 The number of times memory failed to be allocated to the cache because the cache
 302 limit was hit.
 303 .El
 304 .Ss stats
 305 The string and integer information available for the statistics level
 306 is detailed below.
 307 The changeable column shows whether a process with appropriate
 308 privilege 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
 320 The number of bytes skipped.
 321 .It Li combined_ios
 322 The number of I/Os which were combined by journal optimization.
 323 .It Li switches
 324 The number of journal switches.
 325 .It Li wait_for_copy
 326 The number of times the journal switch process had to wait for the previous
 327 journal copy to complete.
 328 .It Li journal_full
 329 The number of times the journal was almost full, forcing a journal switch.
 330 .It Li low_mem
 331 The 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
 341 The
 342 .Nm
 343 utility appeared in
 344 .Fx 7.0 .
 345 .Sh AUTHORS
 346 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org