| blob | c94189e967f2b97f586b45ef87afeebb2179b87f |
1 .\" $NetBSD: swapctl.8,v 1.40 2008/05/29 14:51:25 mrg Exp $
2 .\"
3 .\" Copyright (c) 1997 Matthew R. Green
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .Dd September 24, 2009
28 .Dt SWAPCTL 8
29 .Os
30 .Sh NAME
31 .Nm swapctl ,
32 .Nm swapon
33 .Nd system swap management tool
34 .Sh SYNOPSIS
35 .Nm
36 .Fl A
37 .Op Fl f | Fl o
38 .Op Fl n
39 .Op Fl p Ar priority
40 .Op Fl t Ar blk|noblk|auto
41 .Nm
42 .Fl D Ar dumpdev|none
43 .Nm
44 .Fl U
45 .Op Fl n
46 .Op Fl t Ar blk|noblk|auto
47 .Nm
48 .Fl a
49 .Op Fl p Ar priority
50 .Ar path
51 .Nm
52 .Fl c
53 .Fl p Ar priority
54 .Ar path
55 .Nm
56 .Fl d
57 .Ar path
58 .Nm
59 .Fl l | Fl s
60 .Op Fl k | Fl m | Fl g | Fl h
61 .Nm
62 .Fl q
63 .Nm
64 .Fl z
65 .Nm swapon
66 .Fl a
67 .Op Fl t Ar blk|noblk
68 .Nm swapon
69 .Ar path
70 .Sh DESCRIPTION
71 The
72 .Nm
73 program adds, removes,
74 lists and prioritizes swap devices and files for the system.
75 The
76 .Nm swapon
77 program acts the same as the
78 .Nm
79 program, as if called with the
80 .Fl a
81 option, except if
82 .Nm swapon
83 itself is called with
84 .Fl a
85 in which case,
86 .Nm swapon
87 acts as
88 .Nm
89 with the
90 .Fl A
91 option.
92 .Pp
93 The following options are available:
94 .Bl -tag -width 123456
95 .It Fl A
96 This option causes
97 .Nm
98 to read the
99 .Pa /etc/fstab
100 file for devices and files with a
101 .Dq sw
102 or
103 .Dq dp
104 type, and adds all
105 .Dq sw
106 type entries as swap devices and sets the last
107 .Dq dp
108 type entry as the dump device.
109 If no swap devices are configured,
110 .Nm
111 will exit with an error code.
112 If used together with
113 .Fl t Ar auto
114 this option will not read
115 .Pa /etc/fstab
116 but query the kernel for all swap partitions on local hard disks.
117 .It Fl a
118 The
119 .Fl a
120 option requires that a
121 .Ar path
122 also be in the argument list.
123 The
124 .Ar path
125 is added to the kernel's list of swap devices using the
126 .Xr swapctl 2
127 system call.
128 When using the
129 .Nm swapon
130 form of this command, the
131 .Fl a
132 option is treated the same as the
133 .Fl A
134 option, for backwards compatibility.
135 .It Fl c
136 The
137 .Fl c
138 option changes the priority of the listed swap device or file.
139 .It Fl D
140 The
141 .Fl D
142 option requires that a
143 .Ar dumpdev
144 also be in the argument list.
145 The kernel dump device is set to
146 .Ar dumpdev .
147 The word
148 .Dq none
149 can be used instead of a
150 .Ar dumpdev
151 to disable the currently set dump device.
152 This change is made via the
153 .Xr swapctl 2
154 system call.
155 The dump device is used when the system crashes
156 to write a current snapshot of real memory, to be saved later with
157 .Xr savecore 8
158 at system reboot, and analyzed to determine the problem.
159 .It Fl d
160 The
161 .Fl d
162 option removes the listed
163 .Ar path
164 from the kernel's list of swap devices or files.
165 .It Fl f
166 Used in combination with the
167 .Fl A
168 command and
169 .Fl t Ar auto
170 flag this option makes
171 .Nm
172 use the first discovered swap device to also become the dump device.
173 The
174 .Fl f
175 option is mutually exclusive with the
176 .Fl o
177 option.
178 .It Fl g
179 The
180 .Fl g
181 option uses (1024 * 1024 * 1024) byte blocks instead of the default 512 byte.
182 .It Fl h
183 The
184 .Fl h
185 option uses
186 .Xr humanize_number 3
187 to display the sizes.
188 .It Fl k
189 The
190 .Fl k
191 option uses 1024 byte blocks instead of the default 512 byte.
192 .It Fl l
193 The
194 .Fl l
195 option lists the current swap devices and files, and their usage statistics.
196 .It Fl m
197 The
198 .Fl m
199 option uses (1024 * 1024) byte blocks instead of the default 512 byte.
200 .It Fl n
201 Used with the
202 .Fl A
203 or
204 .Fl U
205 command, the
206 .Fl n
207 option makes
208 .Nm
209 print the action it would take, but not actually change any swap or
210 dump devices.
211 .It Fl o
212 Similar to the
213 .Fl f
214 flag, this
215 .Dq Dump Only
216 option makes
217 .Nm
218 find the first swap device and configure it as dump device.
219 No swap device is changed.
220 This option needs to be used in combination with
221 .Fl A Fl t Ar auto
222 and is mutually exclusive with
223 .Fl f .
224 .It Fl p
225 The
226 .Fl p
227 option sets the priority of swap devices or files to the
228 .Ar priority
229 argument.
230 This works with the
231 .\" .Fl d ,
232 .Fl a ,
233 .Fl c ,
234 and
235 .Fl l
236 options.
237 .It Fl q
238 Query
239 .Pa /etc/fstab ,
240 checking for any defined swap or dump devices.
241 If any are found,
242 .Nm
243 returns with an exit status of 0, if none are found the exit status will
244 be 1.
245 .It Fl s
246 The
247 .Fl s
248 option displays a single line summary of current swap statistics.
249 .It Fl t
250 This flag modifies the function of the
251 .Fl A
252 and
253 .Fl U
254 options.
255 The
256 .Fl t
257 option allows the type of device to add to be specified.
258 An argument of
259 .Ar blk
260 causes all block devices in
261 .Pa /etc/fstab
262 to be added.
263 An argument of
264 .Ar noblk
265 causes all non-block devices in
266 .Pa /etc/fstab
267 to be added.
268 An argument of
269 .Ar auto
270 causes all swap partitions on local hard disks to be used.
271 This option is useful in early system startup, where swapping
272 may be needed before all file systems are available, such as during
273 disk checks of large file systems.
274 .It Fl U
275 This option causes
276 .Nm
277 to read the
278 .Pa /etc/fstab
279 file for devices and files with a
280 .Dq sw
281 type, and remove all these entries as swap devices.
282 If no swap devices are unconfigured,
283 .Nm
284 will exit with an error code.
285 If used together with
286 .Fl t Ar auto
287 this option will not read
288 .Pa /etc/fstab
289 but unconfigure all local swap partitions.
290 .It Fl z
291 The
292 .Fl z
293 option displays the current dump device.
294 .El
295 .Sh SWAP PRIORITY
296 The
297 .Nx
298 swap system allows different swap devices and files to be assigned different
299 priorities, to allow the faster resources to be used first.
300 Swap devices at the same priority are used in a round-robin fashion until
301 there is no more space available at this priority, when the next priority
302 level will be used.
303 The default priority is 0, the highest.
304 This value can be any valid integer,
305 with higher values receiving less priority.
306 .Sh SWAP OPTIONS
307 When parsing the
308 .Pa /etc/fstab
309 file for swap devices, the following options are recognized:
310 .Pp
311 .Bl -tag -width nfsmntpt=/path -compact
312 .It priority=N
313 This option sets the priority of the specified swap device to N.
314 .It nfsmntpt=/path
315 This option is useful for swapping to NFS files.
316 It specifies the local mount point to mount an NFS filesystem.
317 The mount point must exist as a directory.
318 Typically, once this mount has succeeded, the file to be used for swapping
319 on will be available under this point mount.
320 For example:
321 .Bd -literal
322 server:/export/swap/client none swap sw,nfsmntpt=/swap
323 .Ed
324 .El
325 .Sh EXIT STATUS
326 If the requested operation was successful, the
327 .Nm
328 utility exits with status 0.
329 If an error occurred, the exit status is 1.
330 .Pp
331 The
332 .Fl A
333 and
334 .Fl U
335 operations (add or remove swap devices listed in
336 .Xr fstab 5 )
337 return an exit status of 2
338 to report that no suitable swap devices were found.
339 .Pp
340 The
341 .Fl z
342 operation (query dump device) and
343 .Fl l
344 (list swap partitions) return an exit status of 1 if no dump device or
345 swap partition has been configured.
346 If any swap partition is available or
347 a dump device is set, the respective query returns 0.
348 .Sh SEE ALSO
349 .Xr swapctl 2 ,
350 .Xr fstab 5 ,
351 .Xr mount_nfs 8
352 .Sh HISTORY
353 The
354 .Nm
355 program was first made available in
356 .Nx 1.3 .
357 The original
358 .Nm swapon
359 program, provided for backwards compatibility, appeared in
360 .Bx 4.0 .
361 .Sh AUTHORS
362 The
363 .Nm
364 program was written by
365 .An Matthew R. Green Aq mrg@eterna.com.au .
366 .Sh CAVEATS
367 Using the automatic swap partition detection done by the
368 .Fl A Fl t Ar auto
369 option may be dangereous.
370 Depending on the on-disk partitioning scheme used, the type of a partition
371 may not be accurately recognizable as a swap partition.
372 The autodetection might recognize and use partitions on
373 removable media like USB sticks.
374 An easy way to test the autoconfiguration is to use
375 .Nm
376 with the
377 .Fl n
378 option.
379 .Sh BUGS
380 If no swap information is specified in
381 .Pa /etc/fstab ,
382 the system startup scripts (see
383 .Xr rc 8 )
384 will configure no swap space and your machine will behave very badly
385 if (more likely when) it runs out of real memory.
386 .Pp
387 Local and remote swap files cannot be configured until after the file
388 systems they reside on are mounted read/write.
389 The system startup scripts need to
390 .Xr fsck 8
391 all local file systems before this can happen.
392 This process requires substantial amounts of memory on some systems.
393 If you configure no local block swap devices on a machine that has local
394 file systems to check and rely only on swap files, the machine will have
395 no swap space at all during system
396 .Xr fsck 8
397 and may run out of real memory, causing fsck to abnormally exit and
398 startup scripts to fail.