.\" /usr/share/man/man8/dphys-swapfile.8(.gz)
.\" author Neil Franklin, last modification 2010.05.05
.\" copyright ETH Zuerich Physics Departement
.\"   use under either modified/non-advertising BSD or GPL license

.TH DPHYS-SWAPFILE 8 "2010.05.05" "D-PHYS Swapfile Tools"

.SH NAME

dphys-swapfile \- set up, mount/unmount, and delete an swap file

.SH SYNOPSIS

.B dphys-swapfile
\fBsetup\fP|\fBinstall\fP|\fBswapon\fP|\fBswapoff\fP|\fBuninstall\fP

.SH DESCRIPTION

dphys-swapfile computes the size for an optimal swap file (and resizes an
existing swap file if necessary), mounts an swap file, unmounts it, and
deletes it it is not wanted any more.

.SH OPTIONS

There is only one parameter, an command, which can be either of these:
.TP
.B setup
and
.B install
Both tell dphys-swapfile to compute the optimal swap file size and
(re-)generate an fitting swap file. Default it 2 times RAM size. This can be
called at boot time, so the file allways stays the right size for current RAM,
or run by hand whenever RAM size has changed.
.TP
.B swapon
and
.B swapoff
These run the \fIswapon \fPand \fIswapoff\fP commands on the swapfile. Note
that direct swapon/off from \fI/etc/fstab\fP is not possible, as that is (at
least on Debian) done in the same script that mounts /var (which is where the
swap file most likely resides). And we need to do our setup between those
actions. So we pass up on \fI/etc/fstab\fP, and do our own swapon/off here.
.TP
.B uninstall
Gets rid of an unwanted swap file, reclaiming its disk space.

.SH CONFIG

The config file \fI/etc/dphys-swapfile\fP allows the user to set up the
working environment for dphys-swapfile.
.PP
This config file is a sh script fragment full of assignments, which is
sourced. Standard sh syntax rules apply. Assignments are:
.TP
.B CONF_SWAPFILE
Set where the swap file should be placed. Defaults to /var/swap. It is unlikely
that you will need to change this, unless you have very strange partitioning,
and then you will most likely be using an swap partition anyway.
.TP
.B CONF_SWAPSIZE
Set size to this absolute value, in MBytes. Leaving this empty (which is the
Default) uses an computed value as size instead. This is unlikely to ever be
needed, unless in some strange diskspace situations. Note, that swap enabled
and size smaller than RAM may causes kernal-internal VM troubles on some
kernels/systems.
.TP
.B CONF_SWAPFACTOR
Set size to computed value. Uses this value times RAM size. It so dynamically
adapts to RAM size, guarantees enough swap on large RAM, without going into
excess diskspace on small RAM (and disk?) systems. Defaults to 2, which gives
swap size = 2 * RAM size.
.TP
.B CONF_MAXDISK_PCT
Sets the maximal percentage of the remaining disk space which may be
used for the swap file. Takes potentially existing dphys-swapfile swap
files into account, i.e. adds their size to the available disk space
before calculating the percentage. Defaults to 50. Set it to the empty
string to disable this check.
.TP
.B CONF_MAXSWAP
Set size restriction of maximal computed and absolute(!) values, in MBytes.
Defaults to 2048 which was a former 32bit kernel limit for the swapfile size
and is now a limit to prevent unusually and senselessly big swap files on
systems with a lot of RAM.

.SH FILES

.TP
.B /etc/dphys-swapfile
user config
.TP
.B $CONF_SWAPFILE
the swap file, target of the whole action (defaults to \fI/var/swap\fP)

.SH EXAMPLES

dphys-swapfile is usually run at system startup and shutdown from an
/etc/init.d (or /etc/rc.d) script, such as this (minimal) one:
.PP
.nf
#!/bin/sh\!
# /etc/init.d/dphys-swapfile \- automatically set up an swapfile\!
# author franklin, last modification 2004.06.04\!
# This script is copyright ETH Zuerich Physics Departement,\!
#   use under either modified/non-advertising BSD or GPL license\!
case "$1" in\!
  start)\!
    /sbin/dphys-swapfile setup\!
    /sbin/dphys-swapfile swapon\!
    ;;\!
  stop)\!
    /sbin/dphys-swapfile swapoff\!
    ;;\!
esac\!
exit 0\!
.fi
.PP
If an sysadmin wants to have the swapfile in another place, say /var/tmp/swap,
he can use:
.PP
In \fI/etc/dphys-swapfile\fP:
.PP
CONF_SWAPFILE=/var/tmp/swap


.SH AUTHOR

neil@franklin.ch, http://neil.franklin.ch/