Gentoo Wiki


Wikipedia has an article on:

TuxOnIce, also known as Suspend2 and swsusp2, is an alternative implementation of hibernation technology for the Linux kernel, providing the backbone for the suspend and hibernate commands. Despite not being included in the vanilla version of the kernel, TuxOnIce is very popular because of it's additional features and good hardware compatibility. The Gentoo Power Management Guide touches on many of the topics written here and should also be used as a reference.

The main sections of this wiki are Installation, Kernel Configuration, Boot Loader Configuration, Userland Script Installation and Configuration, and Extra. Installation is where you get a kernel installed that has the proper TuxOnIce patches. Kernel Configuration is where you make sure the correct variables are set to have a kernel compile with TuxOnIce working. Userland Script Installation and Configuration is where you choose and set up the user-land hibernation scripts that interface with the kernel for you, such as hibernate-script or pm-utils. Extra is where related, optional information is kept that can be handy.



The installation of TuxOnIce consists of getting a kernel with the correct patches. While you can do it manually yourself, a pre-patched kernel is recommended because it is not only easier to install, it is easier to keep up to date. If you want install a pre-patched kernel, continue with Default: Pre-patched Kernel. If you want to patch a vanilla kernel yourself, continue with Alternative: Patch a Vanilla Kernel.

Default: Pre-patched Kernel

You only need to install sys-kernel/tuxonice-sources. While not strictly necessary, sys-apps/tuxonice-userui should be pulled in as a dependency. Don't forget your symbolic link to /usr/src/linux if the use flag isn't set!

# emerge tuxonice-sources

Now continue to Kernel Configuration

Alternative: Patch a Vanilla Kernel

Don't worry, it's not as scary as you may think. Keep in mind the TuxOnIce patches will only work with the vanilla sources and don't forget your symbolic link to /usr/src/linux if the use flag isn't set!

  1. Install sys-kernel/vanilla-sources.
      # emerge vanilla-sources
  2. Download the stable TuxOnIce patch that matches your kernel version from the TuxOnIce download page.
  3. Assuming the patches were downloaded to /usr/src/, apply the patch with the following commands.
      # cd /usr/src/linux 
      # bzcat /usr/src/patch.bz2 | patch -p1
  4. Optional: Install sys-apps/tuxonice-userui for some gui functionality during resume/suspend.
      # emerge tuxonice-userui

Now continue to Kernel Configuration

Kernel Configuration

You may wish to review kernel configuration from the gentoo handbook before proceeding. If the kernel was patched correctly, the following settings should be available when running make menuconfig. genkernel users should run genkernel --menuconfig all to double check these settings.

Linux Kernel Configuration: Enable TuxOnIce features
Processor type and features  --->
  [*] Support for suspend on SMP and hot-pluggable CPUs

Power management options (ACPI, APM)  --->
  [*] Hibernation (aka 'suspend to disk')
  (/dev/<swap-partition>) Default resume partition
  <*>   Enhanced Hibernation (TuxOnIce)  ---> 
          *** Image Storage (you need at least one allocator)
    <*>   File Allocator
    <*>   Swap Allocator
          *** General Options
    ()    Default pre-hibernate command
    ()    Default post-resume command
    <*>   Compression support
    <*>   Userspace User Interface support
    (/sbin/tuxoniceui_text) Default userui program location 
    [ ]   Allow Keep Image Mode
    [*]   Replace swsusp by default
    < >   Cluster support  --->
    [*]   Checksum pageset2
    (25)  Default waiting time for emergency boot messages
    < >   Test pageflags

Cryptographic options  --->
  <*>   LZF compression algorithm
  1. Activate CPU hot-plugging on SMP systems should be enabled only on multi-core and/or multi-processor systems to enable suspend functionality in the kernel. If left unselected, none of the TuxOnIce options will appear for those computers.
  2. Default resume partition is usually the same as the swap partition listed in /etc/fstab. The format must be type 82 Linux swap for it to work which can be verified with fdisk -l. If unsure about this setting, wait until the bootloader section where we will set it with the resume variable (tuxonice_resume for genkernel users.) Using a swapfile or dedicated file is also explained in detail there.
  3. LZF compression support may speed up the hibernation process if you have a fast CPU. Do not compile LZF compression algorithm as a module. You will likely not be able to resume from the image on boot up.
  4. Userspace User Interface support is required in order to use the tuxonice-userui package.
  5. Default userui program location should be set to /sbin/tuxoniceui_text if you're not going to do anything fancy and want a basic UI during suspend. This can also be set to /sbin/tuxoniceui_fbsplash if the fbsplash USE variable was set when installing tuxonice_userui.
  6. Replace swsusp by default should be set if you want hal and pm-utils to use TuxOnIce by default. hiberante-script should be fine either way.
  7. Some non-related settings may cause problems for some users, though very rare. Beware of Local APIC support on uniprocessors which can cause freezes during atomic copying along with [*] kexec system call. Usually your system should be fine if these are left in their default settings.

Now compile and install it as you usually would! If you didn't set the default resume device name here or are a genkernel user, continue to Boot Loader Configuration. Otherwise, skip to the Userland Script Installation and Configuration section.

Boot Loader Configuration

The resume parameter must be passed to the kernel at boot time by adding it to the boot loader config file if you didn't set it in the kernel. resume tells TuxOnIce where to find the headers that store the information about the images that it loads and writes.

Genkernel users, tuxonice_resume is used in place of resume. Like the resume variable, if set in the kernel, it is unneeded in the bootloader. The real_resume parameter is required regardless. It presently doesn't matter what value you pass to real_resume, but it would be prudent to use the same value as set for tuxonice_resume. All examples in the section for genkernel will include both parameters for simplicity.

If you set up a proper Linux swap partition that is large enough, Default: Using a Swap Partition is likely the best choice from here. If you have no swap partition and are an advanced user, try out Alternative: Using a Swapfile or Alternative: Using a Dedicated File. You may want to review configuring the boot loader from the Gentoo Handbook before continuing.

Default: Using a Swap Partition

It is much easier to set up TuxOnIce to hibernate to the system's swap partition instead of using a dedicated file or swapfile. Since so many systems have a large swap partition already set up and just sitting there, why not use it?

  1. First of all, the partition must be type 82 standard linux swap. If the swap partition type is wrong, you will likely get a confusing error complaining about TuxOnIce being unable to free enough memory when hibernating. It also should be at least large enough to hold an image of the RAM uncompressed. To get a list the formats of the partitions on all drives with fdisk -l.
  2. Append to the kernel line in grub.conf the resume argument like shown in the example below except with your own information. To check the location of the swap partition, fdisk -l works well.
    File: /boot/grub/grub.conf
    kernel /boot/vmlinuz root=/dev/sda3 resume=swap:/dev/sda1

    Genkernel users will have their kernel line look more like this:

    File: /boot/grub/grub.conf
    kernel /boot/kernel root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/sda3 real_resume=/dev/sda1 tuxonice_resume=/dev/sda1
  3. To verify TuxOnIce loads correctly after bootup, check the output of dmesg | grep TuxOnIce. It should have a line somewhere similar to below.

    TuxOnIce: Normal swapspace found.

Continue to Userland Script Installation and Configuration when done here.

Alternative: Using a Swapfile

Using a swapfile instead of a swap partition is handy because you can change the size and location depending on your needs and whims. The method described here creates a special swap partition that TuxOnIce activates and deactivates as needed. This would be most useful for people who do not have any swap partition at all and want to keep the system from casually using the swapfile. Check out the Suspend to More than One Swap Partition/File section for more information on the alternative.

  1. The first step is to create the file. The file we use here will be at the location /swapfile and 600MB in size.
    # dd if=/dev/zero of=/swapfile bs=1M count=600
  2. What we have now is a 600MB contiguous file containing only zeros. To apply a swap filesystem, we use the mkswap command on our swapfile.
    # mkswap /swapfile
  3. We now need the location of the swap file to feed to the bootloader. One way to do this is to temporarily activate the swapfile for the system and then ask TuxOnIce. To activate the swapfile, we use the swapon command.
    # swapon /swapfile
  4. Now we ask TuxOnIce for the location by using cat on /sys/power/tuxonice/swap/headerlocations. Notice how it outputs the location of all available swapfiles to the system. But be careful of the swap partition line. It is a static string, so don't ever use it for information.
    # cat /sys/power/tuxonice/swap/headerlocations
    For swap partitions, simply use the format: resume=swap:/dev/hda1.
    For swapfile `/swapfile`, use resume=swap:/dev/sda3:0xf7778.
  5. Since the swapfile line has the exact information we need, we just have to copy and past the required section into our bootloader configuration file. It should be appended to the end of the kernel lines in grub.conf with the resume variable.
    File: /boot/grub/grub.conf
    kernel /boot/vmlinuz root=/dev/sda2 resume=file:/dev/sda3:0xf7778

    Genkernel users will have their kernel line look more like this:

    File: /boot/grub/grub.conf
    kernel /boot/kernel root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/sda2 real_resume=file:/dev/sda3:0xf7778 tuxonice_resume=file:/dev/sda3:0xf7778
  6. Reboot and use dmesg | grep TuxOnIce to figure out if TuxOnIce recognizes the swapfile with no problems.

Continue to Userland Script Installation and Configuration when done here.

Alternative: Using a Dedicated File

Using a dedicated file is very similar to using a swapfile with many of the same strengths. It differs in that you can't easily use groups of dedicated files for TuxOnIce storage.

  1. First you need to create your file. The basic layout has a TuxOnIce header with trailing zeros until the file reaches the desired size. So first echo TuxOnIce to your desired location. Here we use /suspend_file.
    # echo TuxOnIce > /suspend_file
  2. Pack Zeros onto the file until it reaches the desired length using the dd command. In this case, the file will be 600mbs. Notice how we are piping the output of dd instead of writing directly to the file. This is to preserve the "TuxOnIce" header. Your screen should look something like below when done with this step.

    # dd if=/dev/zero bs=1M count=600 >> /suspend_file
    600+0 records in
    600+0 records out
    629145600 bytes (629 MB) copied, 26.7159 s, 23.5 MB/s
  3. Now that you have a file with the correct layout, we need to figure out it's exact position on the hard drive for TuxOnIce to be able to use it on bootup. As a handy trick, we can get TuxOnIce to tell us the information we need. First point TuxOnIce at the file by echoing the path to /sys/power/tuxonice/file/target.
    # echo /suspend_file > /sys/power/tuxonice/file/target
  4. Next, TuxOnIce will tell us the location of the file is by using cat on the file at /sys/power/tuxonice/resume.
    # cat /sys/power/tuxonice/resume
  5. Do you see that line that popped out? This is the exact information we need for our bootloader. It should be appended to the end of the kernel lines in grub.conf with the resume variable.
    File: /boot/grub/grub.conf
    kernel /boot/vmlinuz root=/dev/sda2 resume=file:/dev/sda2:0xdc008

    Genkernel users will have their kernel line look more like this:

    File: /boot/grub/grub.conf
    kernel /boot/kernel root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/sda2 real_resume=file:/dev/sda2:0xdc008 tuxonice_resume=file:/dev/sda2:0xdc008
  6. Reboot and use dmesg | grep TuxOnIce to figure out if TuxOnIce recognizes the dedicated file with no problems.

Continue to Userland Script Installation and Configuration when done here.

Userland Script Installation and Configuration

It is now possible to hibernate your computer by echoing commands directly to the kernel!
echo "any text at all" > /sys/power/tuxonice/do_hibernate
echo "any text at all" > /sys/power/tuxonice/do_suspend
But that is the masochistic thing to do, so lets install some scripts that will handle the leg work that needs to be done before and after suspending. There are two main ways that it is done nowadays, namely pm-utils and hibernate-script. Although configuration syntax differs somewhat, they really are about equivalent.

Hibernate-script is supplied by the TuxOnIce guys and is the default Gentoo hibernate script. The script execution is modified through a configuration file that is detailed in man hibernate.conf. Hibernate-script by far has better documentation and is much more mature than it's competitor. If something goes wrong, this is the one that is easier to fix, but takes slightly more work to set up. Though hibernate-script doesn't have the hal integration of pm-utils, it works very well in a terminal only environment and has less dependencies.

Pm-utils is likely easier for people who hibernate through sys-apps/hal. Gnome users fall in this group. It's generally easier to set up, more likely to work out of the box, better integrates with Gnome, and you are less likely to need the mess with permissions. But when it comes to advanced configuration it can be a bear to deal with since doesn't abstract any of TuxOnIce's features. The execution of pm-utils is modified by creating scripts that "hook" into the main program.

If you're a Gnome user, continue to the Alternative: Pm-utils Installation and Configuration. Otherwise, Default: Hibernation-script Installation and Configuration is likely more fitting. Because these are separate wiki pages, you may want to check out the Extra section before leaving.


You have completed the main setup of TuxOnIce! Congrats! This section has some extra options you might want to use to that aren't purely necessary, but can be handy depending on your setup.

TuxOnIce Hotkeys

One of the features of TuxOnIce are hotkeys that can be used during hibernation to perform specific actions. Some of the hotkeys require debugging to be compiled in to work. For a complete list, check out the official page.

Suspend to More than One Swap Partition/File

First you need a working TuxOnIce setup. It doesn't matter what swap partition/file you use, just choose one. Then use swapon to temporarily add additional swap partitions/files like below.

# swapon /dev/sda1
# swapon /swapfile

It really is this simple. Since swapon is not permanent, it is a lot easier to just add the partitions and files to your fstab file instead.

File: /etc/fstab
/dev/sda2   none   swap   sw 0 0
/swapfile   none   swap   sw 0 0

If you want to learn how to make swapfiles, use the first two steps of the Alternative: Using a Swapfile section.

Swap on LV/dm-crypt

Initrd/initramfs with TuxOnIce

Genkernel does a lot of this work automatically and is integrated with this how-to in the Bootloader Configuration section. This hack is not recommended and only still exists for academic purposes.

If this setup is done incorrectly, you will most likely suffer from filesystem corruption, so be careful. If you are not using genkernel, to use initramfs with TuxOnIce you will need to edit your linuxrc (or init) script to contain:

echo 1 > /sys/power/tuxonice/do_resume

It must be inserted AFTER the script mounts /sys, but BEFORE the script mounts your filesystem. The TuxOnIce website has additional documentation on using an initrd/initramfs with TuxOnIce.


This trouble shooting section is only for TuxOnIce. If the error doesn't have anything to do with the kernel, you should check out the Hibernate-script or Pm-utils wiki pages instead. If you see an error that looks like a kernel error, but is handled by the above scripts, the preferable thing is to link to those pages from this troubleshooting section.

Couldn't Free Enough Memory

Genkernel doesn't work with TuxOnIce

Genkernel since version 3.4.9 has had internal TuxOnIce support. Until bug 220913 is fixed, the real_resume parameter is required to turn on TuxOnIce functionality. The tuxonice_resume parameter is used in place of the standardly used resume parameter. For more information, go to the Boot Loader Configuration section.

Pageset Error

If you get an error similar to

Pageset1 has grown by 4901 
pages. Only 100 growth is allowed for.
Suspend failed, trying to recover...

you are likely using an Ati or nVidia video card with binary drivers. The trick to getting around this problem is by using hibernate-script or pm-utils which are made for this kind of legwork. Please check out the Hibernate-script wiki page or the Pm-utils wiki page for more information


Retrieved from ""

Last modified: Sat, 11 Oct 2008 22:10:00 +0000 Hits: 16,963