399 lines
9.1 KiB
Groff
399 lines
9.1 KiB
Groff
.\" $NetBSD: swapctl.8,v 1.44 2014/03/18 18:20:39 riastradh Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997 Matthew R. Green
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd June 1, 2011
|
|
.Dt SWAPCTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm swapctl ,
|
|
.Nm swapon
|
|
.Nd system swap management tool
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl A
|
|
.Op Fl f | Fl o
|
|
.Op Fl n
|
|
.Op Fl p Ar priority
|
|
.Op Fl t Ar blk|noblk|auto
|
|
.Nm
|
|
.Fl D Ar dumpdev|none
|
|
.Nm
|
|
.Fl U
|
|
.Op Fl n
|
|
.Op Fl t Ar blk|noblk|auto
|
|
.Nm
|
|
.Fl a
|
|
.Op Fl p Ar priority
|
|
.Ar path
|
|
.Nm
|
|
.Fl c
|
|
.Fl p Ar priority
|
|
.Ar path
|
|
.Nm
|
|
.Fl d
|
|
.Ar path
|
|
.Nm
|
|
.Fl l | Fl s
|
|
.Op Fl k | Fl m | Fl g | Fl h
|
|
.Nm
|
|
.Fl q
|
|
.Nm
|
|
.Fl z
|
|
.Nm swapon
|
|
.Fl a
|
|
.Op Fl t Ar blk|noblk
|
|
.Nm swapon
|
|
.Ar path
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
program adds, removes,
|
|
lists, and prioritizes swap devices and files for the system.
|
|
The
|
|
.Nm swapon
|
|
program acts the same as the
|
|
.Nm
|
|
program as if called with the
|
|
.Fl a
|
|
option, except if
|
|
.Nm swapon
|
|
itself is called with
|
|
.Fl a
|
|
in which case
|
|
.Nm swapon
|
|
acts as
|
|
.Nm
|
|
with the
|
|
.Fl A
|
|
option.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width 123456
|
|
.It Fl A
|
|
This option causes
|
|
.Nm
|
|
to read the
|
|
.Pa /etc/fstab
|
|
file for devices and files with a
|
|
.Dq sw
|
|
or
|
|
.Dq dp
|
|
type, and adds all
|
|
.Dq sw
|
|
type entries as swap devices and sets the last
|
|
.Dq dp
|
|
type entry as the dump device.
|
|
If no swap devices are configured,
|
|
.Nm
|
|
will exit with an error code.
|
|
If used together with
|
|
.Fl t Ar auto
|
|
this option will not read
|
|
.Pa /etc/fstab
|
|
but query the kernel for all swap partitions on local hard disks.
|
|
.It Fl a
|
|
The
|
|
.Fl a
|
|
option requires that a
|
|
.Ar path
|
|
also be in the argument list.
|
|
The
|
|
.Ar path
|
|
is added to the kernel's list of swap devices using the
|
|
.Xr swapctl 2
|
|
system call.
|
|
When using the
|
|
.Nm swapon
|
|
form of this command, the
|
|
.Fl a
|
|
option is treated the same as the
|
|
.Fl A
|
|
option, for backwards compatibility.
|
|
.It Fl c
|
|
The
|
|
.Fl c
|
|
option changes the priority of the listed swap device or file.
|
|
.It Fl D
|
|
The
|
|
.Fl D
|
|
option requires that a
|
|
.Ar dumpdev
|
|
also be in the argument list.
|
|
The kernel dump device is set to
|
|
.Ar dumpdev .
|
|
The word
|
|
.Dq none
|
|
can be used instead of a
|
|
.Ar dumpdev
|
|
to disable the currently set dump device.
|
|
This change is made via the
|
|
.Xr swapctl 2
|
|
system call.
|
|
The dump device is used when the system crashes
|
|
to write a current snapshot of real memory, to be saved later with
|
|
.Xr savecore 8
|
|
at system reboot, and analyzed to determine the problem.
|
|
.It Fl d
|
|
The
|
|
.Fl d
|
|
option removes the listed
|
|
.Ar path
|
|
from the kernel's list of swap devices or files.
|
|
.It Fl f
|
|
Used in combination with the
|
|
.Fl A
|
|
command and
|
|
.Fl t Ar auto
|
|
flag this option makes
|
|
.Nm
|
|
use the first discovered swap device to also become the dump device.
|
|
The
|
|
.Fl f
|
|
option is mutually exclusive with the
|
|
.Fl o
|
|
option.
|
|
.It Fl g
|
|
The
|
|
.Fl g
|
|
option uses (1024 * 1024 * 1024) byte blocks instead of the default 512 byte.
|
|
.It Fl h
|
|
The
|
|
.Fl h
|
|
option uses
|
|
.Xr humanize_number 3
|
|
to display the sizes.
|
|
.It Fl k
|
|
The
|
|
.Fl k
|
|
option uses 1024 byte blocks instead of the default 512 byte.
|
|
.It Fl l
|
|
The
|
|
.Fl l
|
|
option lists the current swap devices and files, and their usage statistics.
|
|
.It Fl m
|
|
The
|
|
.Fl m
|
|
option uses (1024 * 1024) byte blocks instead of the default 512 byte.
|
|
.It Fl n
|
|
Used with the
|
|
.Fl A
|
|
or
|
|
.Fl U
|
|
command, the
|
|
.Fl n
|
|
option makes
|
|
.Nm
|
|
print the action it would take, but not actually change any swap or
|
|
dump devices.
|
|
.It Fl o
|
|
Similar to the
|
|
.Fl f
|
|
flag, this
|
|
.Dq Dump Only
|
|
option makes
|
|
.Nm
|
|
find the first swap device and configure it as dump device.
|
|
No swap device is changed.
|
|
This option needs to be used in combination with
|
|
.Fl A Fl t Ar auto
|
|
and is mutually exclusive with
|
|
.Fl f .
|
|
.It Fl p
|
|
The
|
|
.Fl p
|
|
option sets the priority of swap devices or files to the
|
|
.Ar priority
|
|
argument.
|
|
This works with the
|
|
.\" .Fl d ,
|
|
.Fl a ,
|
|
.Fl c ,
|
|
and
|
|
.Fl l
|
|
options.
|
|
.It Fl q
|
|
Query
|
|
.Pa /etc/fstab ,
|
|
checking for any defined swap or dump devices.
|
|
If any are found,
|
|
.Nm
|
|
returns with an exit status of 0, if none are found the exit status will
|
|
be 1.
|
|
.It Fl s
|
|
The
|
|
.Fl s
|
|
option displays a single line summary of current swap statistics.
|
|
.It Fl t
|
|
This flag modifies the function of the
|
|
.Fl A
|
|
and
|
|
.Fl U
|
|
options.
|
|
The
|
|
.Fl t
|
|
option allows the type of device to add to be specified.
|
|
An argument of
|
|
.Ar blk
|
|
causes all block devices in
|
|
.Pa /etc/fstab
|
|
to be added.
|
|
An argument of
|
|
.Ar noblk
|
|
causes all non-block devices in
|
|
.Pa /etc/fstab
|
|
to be added.
|
|
An argument of
|
|
.Ar auto
|
|
causes all swap partitions on local hard disks to be used.
|
|
This option is useful in early system startup, where swapping
|
|
may be needed before all file systems are available, such as during
|
|
disk checks of large file systems.
|
|
.It Fl U
|
|
This option causes
|
|
.Nm
|
|
to read the
|
|
.Pa /etc/fstab
|
|
file for devices and files with a
|
|
.Dq sw
|
|
type, and remove all these entries as swap devices.
|
|
If no swap devices are unconfigured,
|
|
.Nm
|
|
will exit with an error code.
|
|
If used together with
|
|
.Fl t Ar auto
|
|
this option will not read
|
|
.Pa /etc/fstab
|
|
but unconfigure all local swap partitions.
|
|
.It Fl z
|
|
The
|
|
.Fl z
|
|
option displays the current dump device.
|
|
.El
|
|
.Sh SWAP PRIORITY
|
|
The
|
|
.Nx
|
|
swap system allows different swap devices and files to be assigned different
|
|
priorities, to allow the faster resources to be used first.
|
|
Swap devices at the same priority are used in a round-robin fashion until
|
|
there is no more space available at this priority, when the next priority
|
|
level will be used.
|
|
The default priority is 0, the highest.
|
|
This value can be any valid integer,
|
|
with higher values receiving less priority.
|
|
.Sh SWAP OPTIONS
|
|
When parsing the
|
|
.Pa /etc/fstab
|
|
file for swap devices, the following options are recognized:
|
|
.Pp
|
|
.Bl -tag -width nfsmntpt=/path -compact
|
|
.It priority=N
|
|
This option sets the priority of the specified swap device to N.
|
|
.It nfsmntpt=/path
|
|
This option is useful for swapping to NFS files.
|
|
It specifies the local mount point to mount an NFS filesystem.
|
|
The mount point must exist as a directory.
|
|
Typically, once this mount has succeeded, the file to be used for swapping
|
|
on will be available under this point mount.
|
|
For example:
|
|
.Bd -literal
|
|
server:/export/swap/client none swap sw,nfsmntpt=/swap
|
|
.Ed
|
|
.El
|
|
.Sh EXIT STATUS
|
|
If the requested operation was successful, the
|
|
.Nm
|
|
utility exits with status 0.
|
|
If an error occurred, the exit status is 1.
|
|
.Pp
|
|
The
|
|
.Fl A
|
|
and
|
|
.Fl U
|
|
operations (add or remove swap devices listed in
|
|
.Xr fstab 5 )
|
|
return an exit status of 2
|
|
to report that no suitable swap devices were found.
|
|
.Pp
|
|
The
|
|
.Fl z
|
|
operation (query dump device) and
|
|
.Fl l
|
|
(list swap partitions) return an exit status of 1 if no dump device or
|
|
swap partition has been configured.
|
|
If any swap partition is available or
|
|
a dump device is set, the respective query returns 0.
|
|
.Sh SEE ALSO
|
|
.Xr swapctl 2 ,
|
|
.Xr fstab 5 ,
|
|
.Xr mount_nfs 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
program was first made available in
|
|
.Nx 1.3 .
|
|
The original
|
|
.Nm swapon
|
|
program, provided for backwards compatibility, appeared in
|
|
.Bx 4.0 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
program was written by
|
|
.An Matthew R. Green Aq Mt mrg@eterna.com.au .
|
|
.Sh CAVEATS
|
|
Using the automatic swap partition detection done by the
|
|
.Fl A Fl t Ar auto
|
|
option may be dangereous.
|
|
Depending on the on-disk partitioning scheme used, the type of a partition
|
|
may not be accurately recognizable as a swap partition.
|
|
The autodetection might recognize and use partitions on
|
|
removable media like USB sticks.
|
|
An easy way to test the autoconfiguration is to use
|
|
.Nm
|
|
with the
|
|
.Fl n
|
|
option.
|
|
.Sh BUGS
|
|
If no swap information is specified in
|
|
.Pa /etc/fstab ,
|
|
the system startup scripts (see
|
|
.Xr rc 8 )
|
|
will configure no swap space and your machine will behave very badly
|
|
if (more likely when) it runs out of real memory.
|
|
.Pp
|
|
Local and remote swap files cannot be configured until after the file
|
|
systems they reside on are mounted read/write.
|
|
The system startup scripts need to
|
|
.Xr fsck 8
|
|
all local file systems before this can happen.
|
|
This process requires substantial amounts of memory on some systems.
|
|
If you configure no local block swap devices on a machine that has local
|
|
file systems to check and rely only on swap files, the machine will have
|
|
no swap space at all during system
|
|
.Xr fsck 8
|
|
and may run out of real memory, causing fsck to abnormally exit and
|
|
startup scripts to fail.
|