sbin/geom/class/cache/gcache.8

   1 .\"-
   2 .\" Copyright (c) 2010 Edward Tomasz Napierala
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 3, 2010
  29 .Dt GCACHE 8
  30 .Os
  31 .Sh NAME
  32 .Nm gcache
  33 .Nd "control utility for CACHE GEOM class"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Cm create
  37 .Op Fl v
  38 .Op Fl b Ar blocksize
  39 .Op Fl s Ar size
  40 .Ar name
  41 .Ar prov
  42 .Nm
  43 .Cm configure
  44 .Op Fl v
  45 .Op Fl b Ar blocksize
  46 .Op Fl s Ar size
  47 .Ar name
  48 .Nm
  49 .Cm destroy
  50 .Op Fl fv
  51 .Ar name
  52 .Nm
  53 .Cm label
  54 .Op Fl v
  55 .Op Fl b Ar blocksize
  56 .Op Fl s Ar size
  57 .Ar name
  58 .Ar prov
  59 .Nm
  60 .Cm stop
  61 .Op Fl fv
  62 .Ar name ...
  63 .Nm
  64 .Cm clear
  65 .Op Fl v
  66 .Ar prov ...
  67 .Nm
  68 .Cm dump
  69 .Ar prov ...
  70 .Nm
  71 .Cm list
  72 .Nm
  73 .Cm status
  74 .Op Fl s Ar name
  75 .Nm
  76 .Cm load
  77 .Op Fl v
  78 .Nm
  79 .Cm unload
  80 .Op Fl v
  81 .Sh DESCRIPTION
  82 The
  83 .Nm
  84 utility is used to control GEOM cache, which can
  85 speed up read performance by sending fixed size
  86 read requests to its consumer.  It has been developed to address
  87 the problem of a horrible read performance of a 64k blocksize FS
  88 residing on a RAID3 array with 8 data components, where a single
  89 disk component would only get 8k read requests, thus effectively
  90 killing disk performance under high load.
  91 .Pp
  92 Caching can be configured using two different methods:
  93 .Dq manual
  94 or
  95 .Dq automatic .
  96 When using the
  97 .Dq manual
  98 method, no metadata are stored on the devices, so the cached
  99 device has to be configured by hand every time it is needed.
 100 The
 101 .Dq automatic
 102 method uses on-disk metadata to detect devices.
 103 Once devices are labeled, they will be automatically detected and
 104 configured.
 105 .Pp
 106 The first argument to
 107 .Nm
 108 indicates an action to be performed:
 109 .Bl -tag -width ".Cm destroy"
 110 .It Cm create
 111 Cache the given devices with specified
 112 .Ar name .
 113 This is the
 114 .Dq manual
 115 method.
 116 The kernel module
 117 .Pa geom_cache.ko
 118 will be loaded if it is not loaded already.
 119 .It Cm label
 120 Cache the given devices with the specified
 121 .Ar name .
 122 This is the
 123 .Dq automatic
 124 method, where metadata are stored in every device's last sector.
 125 The kernel module
 126 .Pa geom_cache.ko
 127 will be loaded if it is not loaded already.
 128 .It Cm stop
 129 Turn off existing cache device by its
 130 .Ar name .
 131 This command does not touch on-disk metadata!
 132 .It Cm destroy
 133 Same as
 134 .Cm stop .
 135 .It Cm clear
 136 Clear metadata on the given devices.
 137 .It Cm dump
 138 Dump metadata stored on the given devices.
 139 .It Cm list
 140 See
 141 .Xr geom 8 .
 142 .It Cm status
 143 See
 144 .Xr geom 8 .
 145 .It Cm load
 146 See
 147 .Xr geom 8 .
 148 .It Cm unload
 149 See
 150 .Xr geom 8 .
 151 .El
 152 .Pp
 153 Additional options:
 154 .Bl -tag -width indent
 155 .It Fl f
 156 Force the removal of the specified cache device.
 157 .It Fl v
 158 Be more verbose.
 159 .El
 160 .Sh SYSCTL VARIABLES
 161 The following
 162 .Xr sysctl 8
 163 variables can be used to control the behavior of the
 164 .Nm CACHE
 165 GEOM class.
 166 The default value is shown next to each variable.
 167 .Bl -tag -width indent
 168 .It Va kern.geom.cache.used_hi : No 20
 169 .It Va kern.geom.cache.used_lo : No 5
 170 .It Va kern.geom.cache.idletime : No 5
 171 .It Va kern.geom.cache.timeout : No 10
 172 .It Va kern.geom.cache.enable : No 1
 173 .It Va kern.geom.cache.debug : No 0
 174 Debug level of the
 175 .Nm CACHE
 176 GEOM class.
 177 This can be set to a number between 0 and 3 inclusive.
 178 If set to 0 minimal debug information is printed, and if set to 3 the
 179 maximum amount of debug information is printed.
 180 .El
 181 .Sh EXIT STATUS
 182 Exit status is 0 on success, and 1 if the command fails.
 183 .Sh SEE ALSO
 184 .Xr geom 4 ,
 185 .Xr geom 8
 186 .Sh HISTORY
 187 The
 188 .Nm
 189 utility appeared in
 190 .Fx 7.0 .
 191 .Sh AUTHORS
 192 .An Ruslan Ermilov Aq ru@FreeBSD.org