SWAPCTL(8) | System Manager's Manual | SWAPCTL(8)

# NAME

`swapctl`, `swapon` — system swap management tool

# SYNOPSIS

`swapctl` | `-A` [`-f`|`-o`] [`-n`] [`-p` priority] [`-t` `blk`|`noblk`|`auto`]

`swapctl` | `-D` dumpdev|`none`

`swapctl` | `-U` [`-n`] [`-t` `blk`|`noblk`|`auto`]

`swapctl` | `-a` [`-p` priority] path

`swapctl` | `-c` `-p` priority path

`swapctl` | `-d` path

`swapctl` | `-l`|`-s` [`-k`|`-m`|`-g`|`-h`] [`-p` priority]

`swapctl` | `-q`

`swapctl` | `-z`

`swapon` | `-a` [`-t` `blk`|`noblk`]

`swapon` | path

# DESCRIPTION

The `swapctl` program adds, removes, lists, and prioritizes swap devices and files for the system.

The historic `swapon` program, with `-a` acts the same as `swapctl` `-A` (“all”), otherwise, `swapon` path acts the same as `swapctl` `-a` path (“add”).

The following options are available for `swapctl`:

`-A`
  Read the /etc/fstab file for devices and files with a ‘`sw`’ or ‘`dp`’ type, and add all ‘`sw`’ type entries as swap devices and set the last ‘`dp`’ type entry as the dump device. If no swap devices are configured, `swapctl` will exit with an error code. If used together with `-t` `auto` this option will not read /etc/fstab but query the kernel for all swap partitions on local hard disks.
`-a`
  Add path to the kernel's list of swap devices.
`-c`
  Change the priority of the path swap device or file.
`-D`
  The kernel dump device is set to dumpdev, which must be a local block device, not a file. The word `none` can be used instead to disable the currently set dump device. The dump device is used when the system crashes to write a current snapshot of real memory, to be saved later with savecore(8) at system reboot, and analyzed to determine the problem.
`-d`
  Remove path from the kernel's list of swap devices or files.
`-f`
  Used in combination with `-A` `-t` `auto`, `-f` causes `swapctl` to use the first discovered swap device as the dump device. The `-f` option is mutually exclusive with `-o`.
`-g`
  Report sizes in GB (1024 * 1024 * 1024) blocks instead of the default 512 byte.
`-h`
  Use humanize_number(3) to display the sizes.
`-k`
  Report sizes in KB (1024) blocks instead of the default 512 byte.
`-l`
  List the current swap devices and files, and their usage statistics.
`-m`
  Report sizes in MB (1024 * 1024) blocks instead of the default 512 byte.
`-n`
  Dry run. With the `-A` or `-U` options, print the action `swapctl` would take, but don't actually change any swap or dump devices.
`-o`
  Similar to the `-f` option, this “dump only” option makes `swapctl` find the first swap device and configure it as the dump device. No swap device is changed. This option needs to be used in combination with `-A` `-t` `auto` and is mutually exclusive with `-f`.
`-p`
  Specify the priority of swap devices or files. With `-a` and `-c` set the priority of the specified path. With `-A` the priority becomes the default for /etc/fstab entries that do not specify a priority. With the `-l` and `-s` the output is limited to only devices (or files) with the given priority.
`-q`
  Query /etc/fstab, checking for any defined swap or dump devices. If any are found, `swapctl` returns with an exit status of 0, if none are found the exit status will be 1.
`-s`
  Display a single line summary of current swap statistics.
`-t`
  Specify the type of device to add or remove. An argument of `blk` causes all block devices in /etc/fstab to be added (or removed). An argument of `noblk` operates on all non-block devices in /etc/fstab. An argument of `auto` causes all swap partitions on local hard disks to be used. The latter 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.
`-U`
  Read the /etc/fstab file for devices and files with an ‘`sw`’ type, and remove all these entries as swap devices. If no swap devices are unconfigured, `swapctl` will exit with an error code. If used together with `-t` `auto` this option will not read /etc/fstab but unconfigure all local swap partitions.
`-z`
  Display the current dump device.

## Swap Priority

The NetBSD 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.

## Swap Options

When parsing the /etc/fstab file for swap devices, the following options are recognized:

`priority=`N
  Set the priority of the specified swap device to N.
`nfsmntpt=`/path
  Specify the local mount point when swapping to an NFS file. 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 mount point. For example:

      server:/export/swap/client none swap sw,nfsmntpt=/swap

# EXIT STATUS

If the requested operation was successful, the `swapctl` utility exits with status 0. If an error occurred, the exit status is 1.

The `-A` and `-U` operations (add or remove swap devices listed in fstab(5)) return an exit status of 2 to report that no suitable swap devices were found.

The `-z` operation (query dump device) and `-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.

# SEE ALSO

swapctl(2), fstab(5), mount_nfs(8)

# HISTORY

The `swapctl` program was first made available in NetBSD 1.3. The original `swapon` program, provided for backwards compatibility, appeared in 4.0BSD.

# AUTHORS

The `swapctl` program was written by Matthew R. Green <mrg@eterna23.net>.

# CAVEATS

Using the automatic swap partition detection done by the `-A` `-t` `auto` option may be dangerous. 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 `swapctl` with the `-n` option.

# BUGS

If no swap information is specified in /etc/fstab, the system startup scripts (see rc(8)) will configure no swap space and the system will behave very badly if (more likely when) it runs out of real memory.

Local and remote swap files cannot be configured until after the file systems they reside upon are mounted read/write. The system startup scripts need to fsck(8) all local file systems before this can happen. This process requires substantial amounts of memory on some systems. If no local block swap devices are configured on a machine that has local file systems to check, and relies only on swap files, the machine will have no swap space at all during system fsck(8) and may run out of real memory, causing fsck to abnormally exit and the startup scripts to fail.

Which device is “first” for the purposes of `-Aft` `auto` or `-Aot` `auto` is not specified, and depends upon system configuration behavior.

February 16, 2026 | NetBSD 11.99