1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<table class="head">
<tr>
<td class="head-ltitle">MEMGUARD(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">MEMGUARD(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">MemGuard</code> — <span class="Nd">memory
allocator for debugging purposes</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">options DEBUG_MEMGUARD</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp"><code class="Nm">MemGuard</code> is a simple and small replacement
memory allocator designed to help detect tamper-after-free scenarios. These
problems are more and more common and likely with multithreaded kernels
where race conditions are more prevalent.</p>
<p class="Pp" id="malloc"><code class="Nm">MemGuard</code> can take over
<a class="permalink" href="#malloc"><code class="Fn">malloc</code></a>(),
<a class="permalink" href="#realloc"><code class="Fn" id="realloc">realloc</code></a>()
and
<a class="permalink" href="#free"><code class="Fn" id="free">free</code></a>()
for a single malloc type. Alternatively <code class="Nm">MemGuard</code> can
take over
<a class="permalink" href="#uma_zalloc"><code class="Fn" id="uma_zalloc">uma_zalloc</code></a>(),
<a class="permalink" href="#uma_zalloc_arg"><code class="Fn" id="uma_zalloc_arg">uma_zalloc_arg</code></a>()
and
<a class="permalink" href="#uma_free"><code class="Fn" id="uma_free">uma_free</code></a>()
for a single <a class="Xr">uma(9)</a> zone. Also
<code class="Nm">MemGuard</code> can guard all allocations larger than
<code class="Dv">PAGE_SIZE</code>, and can guard a random fraction of all
allocations. There is also a knob to prevent allocations smaller than a
specified size from being guarded, to limit memory waste.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">To use <code class="Nm">MemGuard</code> for a memory type, either
add an entry to <span class="Pa">/boot/loader.conf</span>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>vm.memguard.desc=<memory_type></pre>
</div>
<p class="Pp">Or set the <var class="Va">vm.memguard.desc</var>
<a class="Xr">sysctl(8)</a> variable at run-time:</p>
<div class="Bd Pp Bd-indent Li">
<pre>sysctl vm.memguard.desc=<memory_type></pre>
</div>
<p class="Pp">Where <var class="Ar">memory_type</var> can be either a short
description of the memory type to monitor, either name of
<a class="Xr">uma(9)</a> zone. Only allocations from that
<var class="Ar">memory_type</var> made after
<var class="Va">vm.memguard.desc</var> is set will potentially be guarded.
If <var class="Va">vm.memguard.desc</var> is modified at run-time then only
allocations of the new <var class="Ar">memory_type</var> will potentially be
guarded once the <a class="Xr">sysctl(8)</a> is set. Existing guarded
allocations will still be properly released by either
<a class="Xr">free(9)</a> or <a class="Xr">uma_zfree(9)</a>, depending on
what kind of allocation was taken over.</p>
<p class="Pp">To determine short description of a <a class="Xr">malloc(9)</a>
type one can either take it from the first column of
<a class="Xr">vmstat(8)</a> <code class="Fl">-m</code> output, or to find it
in the kernel source. It is the second argument to
<a class="Xr">MALLOC_DEFINE(9)</a> macro. To determine name of
<a class="Xr">uma(9)</a> zone one can either take it from the first column
of <a class="Xr">vmstat(8)</a> <code class="Fl">-z</code> output, or to find
it in the kernel source. It is the first argument to the
<a class="Xr">uma_zcreate(9)</a> function.</p>
<p class="Pp">The <var class="Va">vm.memguard.divisor</var> boot-time tunable is
used to scale how much of the system's physical memory
<code class="Nm">MemGuard</code> is allowed to consume. The default is 10,
so up to <var class="Va">vm_cnt.v_page_count</var>/10 pages can be used.
<code class="Nm">MemGuard</code> will reserve
<var class="Va">vm_kmem_max</var> /
<var class="Va">vm.memguard.divisor</var> bytes of virtual address space,
limited by twice the physical memory size. The physical limit is reported as
<var class="Va">vm.memguard.phys_limit</var> and the virtual space reserved
for <code class="Nm">MemGuard</code> is reported as
<var class="Va">vm.memguard.mapsize</var>.</p>
<p class="Pp"><code class="Nm">MemGuard</code> will not do page promotions for
any allocation smaller than <var class="Va">vm.memguard.minsize</var> bytes.
The default is 0, meaning all allocations can potentially be guarded.
<code class="Nm">MemGuard</code> can guard sufficiently large allocations
randomly, with average frequency of every one in 100000 /
<var class="Va">vm.memguard.frequency</var> allocations. The default is 0,
meaning no allocations are randomly guarded.</p>
<p class="Pp"><code class="Nm">MemGuard</code> can optionally add unmapped guard
pages around each allocation to detect overflow and underflow, if
<var class="Va">vm.memguard.options</var> has the 1 bit set. This option is
enabled by default. <code class="Nm">MemGuard</code> will optionally guard
all allocations of <code class="Dv">PAGE_SIZE</code> or larger if
<var class="Va">vm.memguard.options</var> has the 2 bit set. This option is
off by default. By default <code class="Nm">MemGuard</code> does not guard
<a class="Xr">uma(9)</a> zones that have been initialized with the
<code class="Dv">UMA_ZONE_NOFREE</code> flag set, since it can produce false
positives on them. However, this safety measure can be turned off by setting
bit 3 of the <var class="Va">vm.memguard.options</var> tunable.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">sysctl(8)</a>, <a class="Xr">vmstat(8)</a>,
<a class="Xr">contigmalloc(9)</a>, <a class="Xr">malloc(9)</a>,
<a class="Xr">redzone(9)</a>, <a class="Xr">uma(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp"><code class="Nm">MemGuard</code> first appeared in
<span class="Ux">FreeBSD 6.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><code class="Nm">MemGuard</code> was originally written by
<span class="An">Bosko Milekic</span>
<<a class="Mt" href="mailto:bmilekic@FreeBSD.org">bmilekic@FreeBSD.org</a>>.
This manual page was originally written by <span class="An">Christian
Brueffer</span>
<<a class="Mt" href="mailto:brueffer@FreeBSD.org">brueffer@FreeBSD.org</a>>.
Additions have been made by <span class="An">Matthew Fleming</span>
<<a class="Mt" href="mailto:mdf@FreeBSD.org">mdf@FreeBSD.org</a>> and
<span class="An">Gleb Smirnoff</span>
<<a class="Mt" href="mailto:glebius@FreeBSD.org">glebius@FreeBSD.org</a>>
to both the implementation and the documentation.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 22, 2017</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
