a32cf64d5ad07167abe30adfdbcc5eeed8493058
[dragonfly.git] / sbin / swapon / swapon.8
1 .\" Copyright (c) 1980, 1991, 1993
2 .\"     The Regents of the University of California.  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 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     @(#)swapon.8    8.1 (Berkeley) 6/5/93
29 .\" $FreeBSD: src/sbin/swapon/swapon.8,v 1.15.2.2 2001/12/14 15:17:56 ru Exp $
30 .\"
31 .Dd September 7, 2010
32 .Dt SWAPON 8
33 .Os
34 .Sh NAME
35 .Nm swapon , swapoff , swapctl
36 .Nd "specify devices for paging and swapping"
37 .Sh SYNOPSIS
38 .Nm swapon Fl aceiq | Ar
39 .Nm swapoff Fl aq | Ar
40 .Nm swapctl
41 .Op Fl AeghklmsU
42 .Oo
43 .Fl a Ar
44 |
45 .Fl d Ar
46 .Oc
47 .Sh DESCRIPTION
48 The
49 .Nm swapon , swapoff
50 and
51 .Nm swapctl
52 utilities are used to control swap devices in the system.
53 At boot time all swap entries in
54 .Pa /etc/fstab
55 are added automatically when the system goes multi-user.
56 Swap devices use a fixed interleave; the maximum number of devices
57 is specified by the kernel configuration option
58 .Dv NSWAPDEV ,
59 which is typically set to 4.
60 There is no priority mechanism.
61 .Pp
62 The
63 .Nm swapon
64 utility adds the specified swap devices to the system.
65 If the
66 .Fl a
67 option is used, all swap devices in
68 .Pa /etc/fstab
69 will be added.
70 The following options are supported:
71 .Bl -tag -width indent
72 .It Dq noauto
73 The device is ignored and will not be added or removed with this option.
74 .It Dq crypt
75 Swap will be encrpted with a random key using a /dev/mapper name of
76 swap-<device> ,
77 for example 'swap-da0s1b'.
78 This will also load the dm_target_crypt module if necessary.
79 .It Dq trim
80 Swap will be TRIMed if the device supports it, otherwise this option
81 will be ignored.
82 .El
83 .Pp
84 If the
85 .Fl q
86 option is used informational messages will not be
87 written to standard output when a swap device is added.
88 If the
89 .Fl c
90 option is used, the device will be encrypted with a random
91 key.
92 If the
93 .Fl e
94 option is used, the device will be trimmed if
95 it supports trim and the trim_enabled sysctl is on.
96 The
97 .Fl i
98 option asks user confirmation before adding a swap device.
99 .Pp
100 The
101 .Nm swapoff
102 utility removes the specified swap devices from the system.
103 If the
104 .Fl a
105 option is used, all swap devices in
106 .Pa /etc/fstab
107 will be removed, unless their
108 .Dq noauto
109 option is also set.
110 If the
111 .Fl c
112 option is used the device is mapped to the appropriate crypto device
113 and the crypto device is removed as well.
114 If this option is specified in
115 .Nm swapon
116 then it should also be specified in
117 .Nm swapoff .
118 If the
119 .Fl q
120 option is used informational messages will not be
121 written to standard output when a swap device is removed.
122 Note that
123 .Nm swapoff
124 will fail and refuse to remove a swap device if there is insufficient
125 VM (memory + remaining swap devices) to run the system.
126 The
127 .Nm swapoff
128 utility
129 must move swapped pages out of the device being removed which could
130 lead to high system loads for a period of time, depending on how
131 much data has been swapped out to that device.
132 .Pp
133 The
134 .Nm swapctl
135 utility exists primarily for those familiar with other
136 .Bx Ns s
137 and may be
138 used to add, remove, or list swap devices.
139 Note that the
140 .Fl a
141 option is used differently in
142 .Nm swapctl
143 and indicates that a specific list of devices should be added.
144 The
145 .Fl d
146 option indicates that a specific list should be removed.
147 The
148 .Fl A
149 and
150 .Fl U
151 options to
152 .Nm swapctl
153 operate on all swap entries in
154 .Pa /etc/fstab
155 which do not have their
156 .Dq noauto
157 option set.
158 .Pp
159 Swap information can be generated using the
160 .Xr swapinfo 8
161 utility,
162 .Nm pstat
163 .Fl s ,
164 or
165 .Nm swapctl
166 .Fl l .
167 The
168 .Nm swapctl
169 utility has the following options for listing swap:
170 .Bl -tag -width indent
171 .It Fl h
172 Output values in human-readable form.
173 .It Fl g
174 Output values in gigabytes.
175 .It Fl k
176 Output values in kilobytes.
177 .It Fl m
178 Output values in megabytes.
179 .It Fl l
180 List the devices making up system swap.
181 .It Fl s
182 Print a summary line for system swap.
183 .If Fl c
184 The swap is or should be crypted.
185 .It Fl e
186 Attempts to Trim the device if -[Aa] is used.
187 .It Fl i
188 Asks user confirmation when -a is used.
189 .It Fl q
190 Less noisy output.
191 .Pp
192 The
193 .Ev BLOCKSIZE
194 environment variable is used if not specifically
195 overridden.
196 1K blocks are used by default.
197 .El
198 .Sh FILES
199 .Bl -tag -width ".Pa /dev/{ad,da}?s?b" -compact
200 .It Pa /dev/{ad,da}?s?b
201 standard paging devices
202 .It Pa /dev/vn?s?b
203 vnode disk paging device
204 .It Pa /etc/fstab
205 ASCII filesystem description table
206 .It Pa /etc/vntab
207 ASCII vnode file table
208 .El
209 .Sh DIAGNOSTICS
210 These utilities may fail for the reasons described in
211 .Xr swapon 2 .
212 .Sh SEE ALSO
213 .Xr swapon 2 ,
214 .Xr fstab 5 ,
215 .Xr init 8 ,
216 .Xr pstat 8 ,
217 .Xr rc 8 ,
218 .Xr vnconfig 8
219 .Sh HISTORY
220 The
221 .Nm swapon
222 utility appeared in
223 .Bx 4.0 .
224 The
225 .Nm swapoff
226 and
227 .Nm swapctl
228 utilities appeared in
229 .Fx 5.1
230 and were later ported to
231 .Dx 2.7 .