##(see the SpecSpec for an explanation)

 * '''Launchpad Entry''': UbuntuSpec:foundations-karmic-swapfile
 * '''Created''': 2009-06-15
 * '''Contributors''': ScottJamesRemnant
 * '''Packages affected''':

== Summary ==

This specification proposes using swap files on new installations in lieu of swap partitions, as currently used.

== Release Note ==

Ubuntu now uses swap files instead of swap partitions, making the partitioning stage of installation easier and allowing more dynamic virtual memory usage.

== Rationale ==

Swap partitions are of a fixed size created when you install the operating system.  This makes it difficult to adjust the size later, and adds increased complexity to the installation process since Ubuntu requires two (or three) partitions instead of just one or two.

The kernel is able to handle swap files just as efficiently, so there is little need for it to be a separate partition.  Swap files are easier to manage, can be resized, need not be contiguous on disk, etc.

== Design ==

=== Installer ===

Using a swap file instead of a swap partition is largely an installer concern:

 * an appropriately named file of the expected size should be created on the root filesystem:
  {{{
dd if=/dev/zero of=/swapfile bs=1K count=1M
mkswap /swapfile
}}}
 * the location of this file is placed into `/etc/fstab` instead of a device name

The installer simply then needs to drop swap partition creation from the auto-partitioning stage.

=== Boot ===

The current initscripts support swap files.  As we transition from the initscripts to a udev-based mounting solution, we should ensure that swap files remain supported and well tested.

=== Hibernate ===

The only minor gotcha with swap files is issues with regard to hibernation, the kernel cannot see the swap file unless the filesystem is mounted - and mounting a journalled filesystem (such as ext3/ext4) changes the filesystem in a way that can affected the resumed system.

There's a solution to this though, as documented in `Documentation/power/userland-swsusp.txt` in the kernel source:
{{{
SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
        units) from the beginning of the partition at which the swap header is
        located (the last ioctl() argument should point to a struct
        resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
        containing the resume device specification and the offset); for swap
        partitions the offset is always 0, but it is different from zero for
        swap files (see Documentation/swsusp-and-swap-files.txt for details).
}}}

The arguments for this ioctl() can be obtained from the `FIBMAP` ioctl().

A small utility will need to be found or written to do this task on hibernation.

== Migration ==

Swap partitions will remain supported.

We will not migrate existing installations, instead a Wiki page will be created to describe how to make the change manually.  The steps to do that are:

 * create the swap file
  {{{
dd if=/dev/zero of=/swapfile bs=1K count=1M
mkswap /swapfile
}}}
 * replace the existing `/etc/fstab` entry for the swap device with the location of this file
 * reboot

== Test/Demo Plan ==

The test plan will be to check that `/proc/swaps` lists the swap file after booting, and to check that hibernation and resume still works.

----
CategorySpec