TuxOnIce

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 its 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 or. Extra is where related, optional information is kept that can be handy.

Installation
The installation of TuxOnIce consists of getting a kernel with the correct patches. You only need to install. While not strictly necessary, should be pulled in as a dependency. Don't forget your symbolic link to if the use flag isn't set!

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. users should run genkernel --menuconfig all to double check these settings.

If you use an older kernel ( pre 2.6.25 ) select the : LZF compression algorithm
 * With kernel 2.6.25 and above LZO is used and not LZF.


 * 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 . 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) LZO compression support may speed up the hibernation process if you have a fast CPU. Do not compile LZO 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  package.
 * 5) Default userui program location should be set to  if you're not going to do anything fancy and want a basic UI during suspend. This can also be set to  if the  use flag was set when installing.
 * 6) Replace swsusp by default should be set if you want  and  to use TuxOnIce by default.  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
The tuxonice_resume parameter is used in place of resume. Like the resume parameter, 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?

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, run:

Append to the kernel line in the resume argument as shown in the example below except with your own information.

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

To verify TuxOnIce loads correctly after bootup, check the output of:

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.

The first step is to create the file. The file we use here will be at the location and 600MB in size (make sure this is larger than your installed RAM). To do this, run:

What we have now is a 600MB contiguous file containing only zeros. To apply a swap filesystem, we use the mkswap command on our swap file:

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:

Now we ask TuxOnIce for the location by using. 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.

For swap partitions, simply use the format:

For swapfile `/swapfile`, use:

Since the swapfile line has the exact information we need, we just have to copy and paste the required section into our bootloader configuration file. It should be appended to the end of the kernel line as the value for the resume parameter.

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

Reboot and use check for any problems using:

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.

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 :

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.

600+0 records in 600+0 records out 629145600 bytes (629 MB) copied, 26.7159 s, 23.5 MB/s

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 :

Next, TuxOnIce will tell us the location of the file is by using : file:/dev/sda2:0xdc008

The line that is output is the exact information we need for our bootloader. It should be appended to the end of the kernel line in with the resume parameter.

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

Reboot and use check for problems using:

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!

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 and. Although configuration syntax differs somewhat, they really are about equivalent.

Hibernate-script is written by the TuxOnIce developers and is the default Gentoo hibernate script. The script execution is modified through a configuration file that is detailed in the hibernate.conf man page. Hibernate-script by far has better documentation and is much more mature than its 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. 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 harder 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.

Extra
You have completed the main setup of TuxOnIce. 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.


 * - Abort a hibernation cycle and restore the machine back to the previous state.
 * - Toggles rebooting at the end of hibernating.
 * - Toggles pausing between major steps when log level > 1.
 * - Toggles pausing between minor steps.
 * - Toggles slowing down the hibernate process.
 * - Continue when paused.
 * - Toggles logging all messages to syslog.
 * - - Sets the console log level during hibernation and resume.

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.

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

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

 * Swap on LVM/dm-crypt

Initrd/initramfs with TuxOnIce
Genkernel does a lot of this work automatically and is integrated with this article in the Bootloader Configuration section. This hack is not recommended and only still exists for academic purposes.

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, but before the script mounts your filesystem. The TuxOnIce website has additional documentation on using an initrd/initramfs with TuxOnIce.

Troubleshooting
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 articles 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
If you are sure there is enough memory for suspend, it's likely the format of your swap partition is wrong. For swap suspend, your swap partition must be of type "82". Please review the Default: Using a Swap Partition section for more information.

If you think it actually is a lack of memory problem, check out the Suspend to More than One Swap Partition/File section.

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 or Pm-utils articles for more information.

Links

 * TuxOnIce for Linux:
 * Official homepage
 * Hardware Compatibility List
 * Running TuxOnIce with nvidia
 * Gentoo Forums:
 * howto: get swsusp2 (hibernate, suspend to disk) working
 * gentoo-dev-sources-2.6.7 and swsusp2
 * AGP Nvidia Card with Software Suspend 2
 * Ati (mobility radeon) and software suspend 2
 * Gentoo Bug 220913
 * Others:
 * Power Management Guide
 * Lvm and dm-crypt HOWTO for Software Suspend 2

TuxOnIce