1.\" $NetBSD: swapctl.8,v 1.23 2002/02/08 01:30:47 ross 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. If no swap devices are configured, 102.Nm 103will exit with an error code. 104.It Fl D 105The 106.Fl D 107option requires that a 108.Ar dumpdev 109also be in the argument list. The kernel dump device is set to 110.Ar dumpdev . 111This changed is made via the 112.Xr swapctl 2 113system call. The dump device is used when the system crashes 114to write a current snapshot of real memory, to be saved later with 115.Xr savecore 8 116at system reboot, and analyzed to determine the problem. 117.It Fl U 118This option causes 119.Nm 120to read the 121.Pa /etc/fstab 122file for devices and files with a 123.Dq sw 124type, and remove all these entries 125as swap devices. 126If no swap devices are unconfigured, 127.Nm 128will exit with an error code. 129.It Fl a 130The 131.Fl a 132option requires that a 133.Ar path 134also be in the argument list. The 135.Ar path 136is added to the kernel's list of swap devices using the 137.Xr swapctl 2 138system call. When using the 139.Nm swapon 140form of this command, the 141.Fl a 142option is treated the same as the 143.Fl A 144option, for backwards compatibility. 145.It Fl c 146The 147.Fl c 148option changes the priority of the listed swap device or file. 149.It Fl d 150The 151.Fl d 152option removes the listed 153.Ar path 154from the kernel's list of swap devices or files. 155.It Fl l 156The 157.Fl l 158option lists the current swap devices and files, and their usage statistics. 159.It Fl s 160The 161.Fl s 162option displays a single line summary of current swap statistics. 163.It Fl p 164The 165.Fl p 166option sets the priority of swap devices or files to the 167.Ar priority 168argument. This works with the 169.\" .Fl d , 170.Fl a , 171.Fl c 172and 173.Fl l 174options. 175.It Fl k 176The 177.Fl k 178option uses 1024 byte blocks instead of the default 512 byte. 179.It Fl t 180This flag modifies the function of the 181.Fl A 182and 183.Fl U 184options. 185The 186.Fl t 187option allows the type of device to add to be specified. An argument of 188.Ar blk 189causes all block devices in 190.Pa /etc/fstab 191to be added. An argument of 192.Ar noblk 193causes all non-block devices in 194.Pa /etc/fstab 195to be added. This option is useful in early system startup, where swapping 196may be needed before all file systems are available, such as during 197disk checks of large file systems. 198.It Fl z 199The 200.Fl z 201option displays the current dump device. 202.El 203.Sh SWAP PRIORITY 204The 205.Nx 206swap system allows different swap devices and files to be assigned different 207priorities, to allow the faster resources to be used first. 208Swap devices at the same priority are used in a round-robin fashion until 209there is no more space available at this priority, when the next priority 210level will be used. 211The default priority is 0, the highest. This value can be any valid integer, 212with higher values receiving less priority. 213.Sh SWAP OPTIONS 214When parsing the 215.Pa /etc/fstab 216file for swap devices, the following options are recognized: 217.Pp 218.Bl -tag -width nfsmntpt=/path -compact 219.It priority=N 220This option sets the priority of the specified swap device to N. 221.It nfsmntpt=/path 222This option is useful for swapping to NFS files. It specifies 223the local mount point to mount an NFS filesystem. Typically, once 224this mount has succeeded, the file to be used for swapping on will 225be available under this point mount. For example: 226.Bd -literal 227server:/export/swap/client none swap sw,nfsmntpt=/swap 228.Ed 229.El 230.Sh SEE ALSO 231.Xr swapctl 2 , 232.Xr fstab 5 , 233.Xr mount_nfs 8 234.Sh HISTORY 235The 236.Nm 237program was first made available in 238.Nx 1.3 . 239The original 240.Nm swapon 241program, provided for backwards compatibility, appeared in 242.Bx 4.0 . 243.Sh AUTHORS 244The 245.Nm 246program was written by Matthew R. Green \*[Lt]mrg@eterna.com.au\*[Gt]. 247.Sh BUGS 248If no swap information is specified in 249.Pa /etc/fstab , 250the system startup scripts (see 251.Xr rc 8 ) 252will configure no swap space and your machine will behave very badly 253if (more likely when) it runs out of real memory. 254.Pp 255Local and remote swap files cannot be configured until after the file 256systems they reside on are mounted read/write. The system startup 257scripts need to 258.Xr fsck 8 259all local file systems before this can happen. This process requires 260substantial amounts of memory on some systems. If you configure no 261local block swap devices on a machine that has local file systems to 262check and rely only on swap files, the machine will have no swap space 263at all during system 264.Xr fsck 8 265and may run out of real memory, causing fsck to abnormally exit and 266startup scripts to fail. 267