share/man/man4/dm_target_flakey.4

   1 .\" Copyright (c) 2015 The DragonFly BSD Project.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The DragonFly BSD Project
   5 .\" by Tomohiro Kusumi <kusumi.tomohiro@gmail.com>
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .Dd November 17, 2015
  28 .Dt DM_TARGET_FLAKEY 4
  29 .Os
  30 .Sh NAME
  31 .Nm dm_target_flakey
  32 .Nd Device-mapper flakey target
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following lines in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device dm"
  39 .Cd "device dm_target_flakey"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a
  43 module at boot time, place the following line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 dm_target_flakey_load="YES"
  47 .Ed
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 target for
  52 .Xr dm 4
  53 provides periodic unreliable I/O behavior to simulate failing devices for testing purposes.
  54 .Dq Nm dmsetup Cm create
  55 takes the following list of parameters for the
  56 .Nm
  57 table.
  58 .Bd -ragged -offset indent
  59 .Cd "<device_path> <offset> <up_interval> <down_interval> [<num_feature_parameters> [<feature_parameters>]]"
  60 .Ed
  61 .Pp
  62 The first four parameters are mandatory.
  63 .Nm
  64 is similar to
  65 .Xr dm_target_linear 4
  66 except that
  67 .Nm
  68 has parameters for periodic unreliable I/O behavior.
  69 .Pp
  70 <device_path> is a path to the underlying device.
  71 <offset> is the starting sector within the device.
  72 <up_interval> is the number of seconds device is available.
  73 <down_interval> is the number of seconds device returns errors.
  74 The device has periodic unreliable I/O behavior for <down_interval>
  75 seconds every other <up_interval> seconds starting from the time
  76 the table is loaded by
  77 .Xr dmsetup 8 .
  78 .Pp
  79 Optional <feature_parameters> are as follows.
  80 <num_feature_parameters> takes the number of parameters for <feature_parameters>.
  81 In other words <num_feature_parameters> is the number of parameters after this.
  82 If <feature_parameters> are not specified, all I/Os return error during <down_interval>.
  83 .Pp
  84 .Dq Nm drop_writes
  85 feature takes no additional parameters.
  86 All write I/Os are silently ignored.
  87 .Bd -ragged -offset indent
  88 .Cd "[drop_writes]"
  89 .Ed
  90 .Pp
  91 .Dq Nm corrupt_bio_byte
  92 feature takes four additional mandatory parameters.
  93 It replaces <Nth_byte> of the
  94 .Dq Nm struct Cm buf
  95 data
  96 whose direction is <direction> with <value> during <down_interval>.
  97 .Bd -ragged -offset indent
  98 .Cd "[corrupt_bio_byte <Nth_byte> <direction> <value> <flags>]"
  99 .Ed
 100 .Pp
 101 <Nth_byte> is the offset of the
 102 .Dq Nm struct Cm buf
 103 data to replace. Counting starts at 1 to replace the first byte of the data.
 104 <direction> is either 'r' for reads or 'w' for writes. Using 'w' is imcompatible with
 105 .Dq Nm drop_writes
 106 feature.
 107 <value> is the value to replace which must be between 0 and 255.
 108 <flags> makes
 109 .Nm
 110 perform the replacement only if
 111 .Dq Nm b_flags
 112 field of
 113 .Dq Nm struct Cm buf
 114 has all the specified flags set.
 115 .Sh SEE ALSO
 116 .Xr dm 4 ,
 117 .Xr dmsetup 8
 118 .Sh HISTORY
 119 The
 120 .Nm
 121 .Xr dm 4
 122 target first appeared in
 123 .Dx 4.3 .
 124 .Sh AUTHORS
 125 .An Tomohiro Kusumi