| .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| .\" 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. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. |
| .\" |
| .\" @(#)swapon.8 6.3 (Berkeley) 3/16/91 |
| .\" |
| .TH SWAPON 8 "October 2014" "util-linux" "System Administration" |
| .SH NAME |
| swapon, swapoff \- enable/disable devices and files for paging and swapping |
| .SH SYNOPSIS |
| .BR swapon |
| [options] |
| .RI [ specialfile ...] |
| .br |
| .B swapoff |
| .RB [ \-va ] |
| .RI [ specialfile ...] |
| .SH DESCRIPTION |
| .B swapon |
| is used to specify devices on which paging and swapping are to take place. |
| |
| The device or file used is given by the |
| .I specialfile |
| parameter. It may be of the form |
| .BI \-L " label" |
| or |
| .BI \-U " uuid" |
| to indicate a device by label or uuid. |
| |
| Calls to |
| .B swapon |
| normally occur in the system boot scripts making all swap devices available, so |
| that the paging and swapping activity is interleaved across several devices and |
| files. |
| |
| .B swapoff |
| disables swapping on the specified devices and files. |
| When the |
| .B \-a |
| flag is given, swapping is disabled on all known swap devices and files |
| (as found in |
| .I /proc/swaps |
| or |
| .IR /etc/fstab ). |
| |
| .SH OPTIONS |
| .TP |
| .BR \-a , " \-\-all" |
| All devices marked as ``swap'' in |
| .I /etc/fstab |
| are made available, except for those with the ``noauto'' option. |
| Devices that are already being used as swap are silently skipped. |
| .TP |
| .BR \-d , " \-\-discard" [ =\fIpolicy\fR] |
| Enable swap discards, if the swap backing device supports the discard or |
| trim operation. This may improve performance on some Solid State Devices, |
| but often it does not. The option allows one to select between two |
| available swap discard policies: |
| .BI \-\-discard=once |
| to perform a single-time discard operation for the whole swap area at swapon; |
| or |
| .BI \-\-discard=pages |
| to discard freed swap pages before they are reused, while swapping. |
| If no policy is selected, the default behavior is to enable both discard types. |
| The |
| .I /etc/fstab |
| mount options |
| .BR discard , |
| .BR discard=once , |
| or |
| .B discard=pages |
| may also be used to enable discard flags. |
| .TP |
| .BR \-e , " \-\-ifexists" |
| Silently skip devices that do not exist. |
| The |
| .I /etc/fstab |
| mount option |
| .B nofail |
| may also be used to skip non-existing device. |
| |
| .TP |
| .BR \-f , " \-\-fixpgsz" |
| Reinitialize (exec /sbin/mkswap) the swap space if its page size does not |
| match that of the current running kernel. |
| .BR mkswap (2) |
| initializes the whole device and does not check for bad blocks. |
| .TP |
| .BR \-h , " \-\-help" |
| Display help text and exit. |
| .TP |
| .BI \-L " label" |
| Use the partition that has the specified |
| .IR label . |
| (For this, access to |
| .I /proc/partitions |
| is needed.) |
| .TP |
| .BR \-o , " \-\-options " \fIopts\fP |
| Specify swap options by an fstab-compatible comma-separated string. |
| For example: |
| .RS |
| .RS |
| .sp |
| .B "swapon -o pri=1,discard=pages,nofail /dev/sda2" |
| .sp |
| .RE |
| The \fIopts\fP string is evaluated last and overrides all other |
| options. |
| .RE |
| .TP |
| .BR \-p , " \-\-priority " \fIpriority\fP |
| Specify the priority of the swap device. |
| .I priority |
| is a value between \-1 and 32767. Higher numbers indicate |
| higher priority. See |
| .BR swapon (2) |
| for a full description of swap priorities. Add |
| .BI pri= value |
| to the option field of |
| .I /etc/fstab |
| for use with |
| .BR "swapon -a" . |
| When no priority is defined, it defaults to \-1. |
| .TP |
| .BR \-s , " \-\-summary" |
| Display swap usage summary by device. Equivalent to "cat /proc/swaps". |
| Not available before Linux 2.1.25. This output format is DEPRECATED in favour |
| of \fB\-\-show\fR that provides better control on output data. |
| .TP |
| .BR \-\-show [ =\fIcolumn\fR ...] |
| Display a definable table of swap areas. See the |
| .B \-\-help |
| output for a list of available columns. |
| .TP |
| .B \-\-noheadings |
| Do not print headings when displaying |
| .B \-\-show |
| output. |
| .TP |
| .B \-\-raw |
| Display |
| .B \-\-show |
| output without aligning table columns. |
| .TP |
| .B \-\-bytes |
| Display swap size in bytes in |
| .B \-\-show |
| output instead of in user-friendly units. |
| .TP |
| .BI \-U " uuid" |
| Use the partition that has the specified |
| .IR uuid . |
| .TP |
| .BR \-v , " \-\-verbose" |
| Be verbose. |
| .TP |
| .BR \-V , " \-\-version" |
| Display version information and exit. |
| .SH NOTES |
| You should not use \fBswapon\fR on a file with holes. |
| This can be seen in the system log as |
| .RS |
| .sp |
| .B "swapon: swapfile has holes." |
| .sp |
| .RE |
| The swap file implementation in the kernel expects to be able to write to the |
| file directly, without the assistance of the filesystem. This is a problem on |
| preallocated files (e.g. |
| .BR fallocate (1)) |
| on filesystems like \fBXFS\fR or \fBext4\fR, and on copy-on-write |
| filesystems like \fBbtrfs\fR. |
| .PP |
| It is recommended to use |
| .BR dd (1) |
| and |
| .I /dev/zero |
| to avoid holes on XFS and ext4. |
| .PP |
| .B swapon |
| may not work correctly when using a swap file with some versions of |
| \fBbtrfs\fR. This is due to btrfs being a copy-on-write filesystem: the |
| file location may not be static and corruption can result. Btrfs actively |
| disallows the use of swap files on its filesystems by refusing to map the file. |
| .PP |
| One possible workaround is to map the swap |
| file to a loopback device. This will allow the filesystem to determine the |
| mapping properly but may come with a performance impact. |
| .PP |
| Swap over \fBNFS\fR may not work. |
| .PP |
| .B swapon |
| automatically detects and rewrites a swap space signature with old software |
| suspend data (e.g S1SUSPEND, S2SUSPEND, ...). The problem is that if we don't |
| do it, then we get data corruption the next time an attempt at unsuspending is |
| made. |
| |
| .SH ENVIRONMENT |
| .IP LIBMOUNT_DEBUG=all |
| enables libmount debug output. |
| .IP LIBBLKID_DEBUG=all |
| enables libblkid debug output. |
| |
| .SH SEE ALSO |
| .BR swapon (2), |
| .BR swapoff (2), |
| .BR fstab (5), |
| .BR init (8), |
| .BR mkswap (8), |
| .BR rc (8), |
| .BR mount (8) |
| .SH FILES |
| .br |
| .I /dev/sd?? |
| standard paging devices |
| .br |
| .I /etc/fstab |
| ascii filesystem description table |
| .SH HISTORY |
| The |
| .B swapon |
| command appeared in 4.0BSD. |
| .SH AVAILABILITY |
| The swapon command is part of the util-linux package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux/. |