share/man/man9/memguard.9

   1 .\" Copyright (c) 2005 Christian Brueffer
   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 AUTHOR 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 AUTHOR 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 October 21, 2011
  28 .Dt MEMGUARD 9
  29 .Os
  30 .Sh NAME
  31 .Nm MemGuard
  32 .Nd "memory allocator for debugging purposes"
  33 .Sh SYNOPSIS
  34 .Cd "options DEBUG_MEMGUARD"
  35 .Sh DESCRIPTION
  36 .Nm
  37 is a simple and small replacement memory allocator designed
  38 to help detect tamper-after-free scenarios.
  39 These problems are more and more common and likely with
  40 multithreaded kernels where race conditions are more prevalent.
  41 .Pp
  42 .Nm
  43 can take over
  44 .Fn malloc ,
  45 .Fn realloc
  46 and
  47 .Fn free
  48 for a single malloc type.
  49 Alternatively
  50 .Nm
  51 can take over
  52 .Fn uma_zalloc ,
  53 .Fn uma_zalloc_arg
  54 and
  55 .Fn uma_free
  56 for a single
  57 .Xr uma
  58 zone.
  59 Also
  60 .Nm
  61 can guard all allocations larger than
  62 .Dv PAGE_SIZE ,
  63 and can guard a random fraction of all allocations.
  64 There is also a knob to prevent allocations smaller than a specified
  65 size from being guarded, to limit memory waste.
  66 .Sh EXAMPLES
  67 To use
  68 .Nm
  69 for a memory type, either add an entry to
  70 .Pa /boot/loader.conf :
  71 .Bd -literal -offset indent
  72 vm.memguard.desc=<memory_type>
  73 .Ed
  74 .Pp
  75 Or set the
  76 .Va vm.memguard.desc
  77 .Xr sysctl 8
  78 variable at run-time:
  79 .Bd -literal -offset indent
  80 sysctl vm.memguard.desc=<memory_type>
  81 .Ed
  82 .Pp
  83 Where
  84 .Ar memory_type
  85 can be either a short description of the memory type to monitor,
  86 either name of
  87 .Xr uma 9
  88 zone.
  89 Only allocations from that
  90 .Ar memory_type
  91 made after
  92 .Va vm.memguard.desc
  93 is set will potentially be guarded.
  94 If
  95 .Va vm.memguard.desc
  96 is modified at run-time then only allocations of the new
  97 .Ar memory_type
  98 will potentially be guarded once the
  99 .Xr sysctl 8
 100 is set.
 101 Existing guarded allocations will still be properly released by
 102 either
 103 .Xr free 9
 104 or
 105 .Xr uma_zfree 9 ,
 106 depending on what kind of allocation was taken over.
 107 .Pp
 108 To determine short description of a
 109 .Xr malloc 9
 110 type one can either take it from the first column of
 111 .Xr vmstat 8 Fl m
 112 output, or to find it in the kernel source.
 113 It is the second argument to
 114 .Xr MALLOC_DEFINE 9
 115 macro.
 116 To determine name of
 117 .Xr uma 9
 118 zone one can either take it from the first column of
 119 .Xr vmstat 8 Fl z
 120 output, or to find it in the kernel source.
 121 It is the first argument to the
 122 .Xr uma_zcreate 9
 123 function.
 124 .Pp
 125 The
 126 .Va vm.memguard.divisor
 127 boot-time tunable is used to scale how much of the system's physical
 128 memory
 129 .Nm
 130 is allowed to consume.
 131 The default is 10, so up to
 132 .Va cnt.v_page_count Ns /10
 133 pages can be used.
 134 .Nm
 135 will reserve
 136 .Va vm_kmem_max
 137 /
 138 .Va vm.memguard.divisor
 139 bytes of virtual address space, limited by twice the physical memory
 140 size.
 141 The physical limit is reported as
 142 .Va vm.memguard.phys_limit
 143 and the virtual space reserved for
 144 .Nm
 145 is reported as
 146 .Va vm.memguard.mapsize .
 147 .Pp
 148 .Nm
 149 will not do page promotions for any allocation smaller than
 150 .Va vm.memguard.minsize
 151 bytes.
 152 The default is 0, meaning all allocations can potentially be guarded.
 153 .Nm
 154 can guard sufficiently large allocations randomly, with average
 155 frequency of every one in 100000 /
 156 .Va vm.memguard.frequency
 157 allocations.
 158 The default is 0, meaning no allocations are randomly guarded.
 159 .Pp
 160 .Nm
 161 can optionally add unmapped guard pages around each allocation to
 162 detect overflow and underflow, if
 163 .Va vm.memguard.options
 164 has the 1 bit set.
 165 This option is enabled by default.
 166 .Nm
 167 will optionally guard all allocations of
 168 .Dv PAGE_SIZE
 169 or larger if
 170 .Va vm.memguard.options
 171 has the 2 bit set.
 172 This option is off by default.
 173 By default
 174 .Nm
 175 doesn't guard those
 176 .Xr uma 9
 177 zones that have been initialized with the
 178 .Dv UMA_ZONE_NOFREE
 179 flag set, since it can produce false positives on them.
 180 However, this safety measure can be turned off by setting bit 3
 181 of the
 182 .Va vm.memguard.options
 183 tunable.
 184 .Sh SEE ALSO
 185 .Xr sysctl 8 ,
 186 .Xr vmstat 8 ,
 187 .Xr contigmalloc 9 ,
 188 .Xr malloc 9 ,
 189 .Xr redzone 9 ,
 190 .Xr uma 9
 191 .Sh HISTORY
 192 .Nm
 193 first appeared in
 194 .Fx 6.0 .
 195 .Sh AUTHORS
 196 .An -nosplit
 197 .Nm
 198 was originally written by
 199 .An Bosko Milekic Aq bmilekic@FreeBSD.org .
 200 This manual page was originally written by
 201 .An Christian Brueffer Aq brueffer@FreeBSD.org .
 202 Additions have been made by
 203 .An Matthew Fleming Aq mdf@FreeBSD.org
 204 and
 205 .An Gleb Smirnoff Aq glebius@FreeBSD.org
 206 to both the implementation and the documentation.
 207 .Sh BUGS
 208 It is not possible to guard allocations that really expect themselves to be
 209 allocated from
 210 .Xr uma 9 ,
 211 utilizing additional interfaces apart from
 212 .Fn uma_zalloc
 213 and
 214 .Fn uma_free ,
 215 for example
 216 .Fn uma_find_refcnt .
 217 For the moment of writing only
 218 .Xr mbuf 9
 219 cluster zones belong to that kind of allocations.
 220 Attempt to guard them would lead to kernel panic.