1.\" $NetBSD: swapctl.8,v 1.24 2002/10/01 14:53:58 wiz 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.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd March 5, 2000 30.Dt SWAPCTL 8 31.Os 32.Sh NAME 33.Nm swapctl , 34.Nm swapon 35.Nd system swap management tool 36.Sh SYNOPSIS 37.Nm 38.Fl A 39.Op Fl p Ar priority 40.Op Fl t Ar blk|noblk 41.Nm "" 42.Fl D Ar dumpdev 43.Nm "" 44.Fl U 45.Op Fl t Ar blk|noblk 46.Nm "" 47.Fl a 48.Op Fl p Ar priority 49.Ar path 50.Nm "" 51.Fl c 52.Fl p Ar priority 53.Ar path 54.Nm "" 55.Fl d 56.Ar path 57.Nm "" 58.Fl l | Fl s 59.Op Fl k 60.Nm "" 61.Fl z 62.Nm swapon 63.Fl a | Ar path 64.Sh DESCRIPTION 65The 66.Nm 67program adds, removes, 68lists and prioritizes swap devices and files for the system. 69The 70.Nm swapon 71program acts the same as the 72.Nm 73program, as if called with the 74.Fl a 75option, except if 76.Nm swapon 77itself is called with 78.Fl a 79in which case, 80.Nm swapon 81acts as 82.Nm 83with the 84.Fl A 85option. 86.Pp 87The following options are available: 88.Bl -tag -width 123456 89.It Fl A 90This option causes 91.Nm 92to read the 93.Pa /etc/fstab 94file for devices and files with a 95.Dq sw 96and 97.Dq dp 98type, and adds all these entries 99as swap devices, or for a dump device in the case of a 100.Dq dp 101type. 102If no swap devices are configured, 103.Nm 104will exit with an error code. 105.It Fl D 106The 107.Fl D 108option requires that a 109.Ar dumpdev 110also be in the argument list. 111The kernel dump device is set to 112.Ar dumpdev . 113This changed is made via the 114.Xr swapctl 2 115system call. 116The dump device is used when the system crashes 117to write a current snapshot of real memory, to be saved later with 118.Xr savecore 8 119at system reboot, and analyzed to determine the problem. 120.It Fl U 121This option causes 122.Nm 123to read the 124.Pa /etc/fstab 125file for devices and files with a 126.Dq sw 127type, and remove all these entries as swap devices. 128If no swap devices are unconfigured, 129.Nm 130will exit with an error code. 131.It Fl a 132The 133.Fl a 134option requires that a 135.Ar path 136also be in the argument list. 137The 138.Ar path 139is added to the kernel's list of swap devices using the 140.Xr swapctl 2 141system call. 142When using the 143.Nm swapon 144form of this command, the 145.Fl a 146option is treated the same as the 147.Fl A 148option, for backwards compatibility. 149.It Fl c 150The 151.Fl c 152option changes the priority of the listed swap device or file. 153.It Fl d 154The 155.Fl d 156option removes the listed 157.Ar path 158from the kernel's list of swap devices or files. 159.It Fl l 160The 161.Fl l 162option lists the current swap devices and files, and their usage statistics. 163.It Fl s 164The 165.Fl s 166option displays a single line summary of current swap statistics. 167.It Fl p 168The 169.Fl p 170option sets the priority of swap devices or files to the 171.Ar priority 172argument. 173This works with the 174.\" .Fl d , 175.Fl a , 176.Fl c , 177and 178.Fl l 179options. 180.It Fl k 181The 182.Fl k 183option uses 1024 byte blocks instead of the default 512 byte. 184.It Fl t 185This flag modifies the function of the 186.Fl A 187and 188.Fl U 189options. 190The 191.Fl t 192option allows the type of device to add to be specified. 193An argument of 194.Ar blk 195causes all block devices in 196.Pa /etc/fstab 197to be added. 198An argument of 199.Ar noblk 200causes all non-block devices in 201.Pa /etc/fstab 202to be added. 203This option is useful in early system startup, where swapping 204may be needed before all file systems are available, such as during 205disk checks of large file systems. 206.It Fl z 207The 208.Fl z 209option displays the current dump device. 210.El 211.Sh SWAP PRIORITY 212The 213.Nx 214swap system allows different swap devices and files to be assigned different 215priorities, to allow the faster resources to be used first. 216Swap devices at the same priority are used in a round-robin fashion until 217there is no more space available at this priority, when the next priority 218level will be used. 219The default priority is 0, the highest. 220This value can be any valid integer, 221with higher values receiving less priority. 222.Sh SWAP OPTIONS 223When parsing the 224.Pa /etc/fstab 225file for swap devices, the following options are recognized: 226.Pp 227.Bl -tag -width nfsmntpt=/path -compact 228.It priority=N 229This option sets the priority of the specified swap device to N. 230.It nfsmntpt=/path 231This option is useful for swapping to NFS files. 232It specifies the local mount point to mount an NFS filesystem. 233Typically, once this mount has succeeded, the file to be used for swapping 234on will be available under this point mount. 235For example: 236.Bd -literal 237server:/export/swap/client none swap sw,nfsmntpt=/swap 238.Ed 239.El 240.Sh SEE ALSO 241.Xr swapctl 2 , 242.Xr fstab 5 , 243.Xr mount_nfs 8 244.Sh HISTORY 245The 246.Nm 247program was first made available in 248.Nx 1.3 . 249The original 250.Nm swapon 251program, provided for backwards compatibility, appeared in 252.Bx 4.0 . 253.Sh AUTHORS 254The 255.Nm 256program was written by 257.An Matthew R. Green Aq mrg@eterna.com.au . 258.Sh BUGS 259If no swap information is specified in 260.Pa /etc/fstab , 261the system startup scripts (see 262.Xr rc 8 ) 263will configure no swap space and your machine will behave very badly 264if (more likely when) it runs out of real memory. 265.Pp 266Local and remote swap files cannot be configured until after the file 267systems they reside on are mounted read/write. 268The system startup scripts need to 269.Xr fsck 8 270all local file systems before this can happen. 271This process requires substantial amounts of memory on some systems. 272If you configure no local block swap devices on a machine that has local 273file systems to check and rely only on swap files, the machine will have 274no swap space at all during system 275.Xr fsck 8 276and may run out of real memory, causing fsck to abnormally exit and 277startup scripts to fail. 278