4. Tweaking

4.1 Hibernate script configuration

The hibernate.conf file has several options that may help you to get hibernation to work correctly on your specific hardware. Most of them are fairly self-explanatory. Some often used ones are mentioned below. Running hibernate -h will give you the full list of options and help.

SwitchToTextMode

On some hardware, the graphic chipset isn't properly restored by BIOS upon resume and the state memorized by the resumed kernel becomes inconsistent with that of the hardware. In this case, it may help to switch to a text console before hibernating and switch back to X only after resume.

UseDummyXServer

This option may also help if you experience strange things such as 3D not working upon resume. It launches a fake xserver that should cause proper initialization of the chipset.

Services (RestartServices/StopServices/StartServices)

It is wise to stop before suspension all services that could be resumed in a different environment. This includes usb, pcmcia and also network services. If your suspension is aborted because a task cannot be stopped by TuxOnIce and this task corresponds to a service, you can tell the hibernate script to stop and start these services.

Modules (UnloadModules/UnloadAllModules/LoadModules)

In the same spirit it is wise to unload before suspension all modules that are unused. You can also force the insertion of specific modules upon resume but usually the kernel knows upon resume the modules it needs to reload.

Unmounting Filesystems (Unmount)

Hibernating while network filesystems or removable devices are mounted may lead to unpredictible results. For NFS, if the mount should disappear and you mounted with the "hard" option, processes attempting to access files on the mount will hang until it can find the mount again. If you mounted with "soft", you risk losing data when a mount unexpectedly disappears. Hence you should unmount any kind of remote shares before hibernating (this includes NFS, CIFS/smbfs, etc).

You can specify the mount points that must be unused before suspension. If these can not be unmounted successfully, the hibernate script will abort unless the --force and/or --kill option is used. The --force option will simply ignore those mount points. The --kill option will try to kill the processes that use these mountpoints.

Network interfaces (DownInterfaces/UpInterfaces)

In the same spirit you can specify the network interfaces that must be shut down before suspension. Upon resume, you can ask the hibernate script to set some interfaces up. You can also use the keyword auto to let the network interfaces be restarted in reverse order (the default).

Check for incompatible programs (IncompatiblePrograms)

Some programs may be incompatible with TuxOnIce because, for instance, they directly access some hardware that ignores power management events. You may ask the hibernate script to abort hibernating if specified processes are running.

Save clock on hibernate (SaveClock)

It is a feature that the resumed kernel recovers its entire memory image, including the system date which therefore appears incorrect. The hibernate script calls hwclock on resume to reset the date according to the CMOS clock. You can ask the script to also save the system date to CMOS just before hibernating. Most of the time this is useless and will lead your clock becoming increasingly wrong.

4.2 Enabling debugging and tuning the system (the sysfs interface)

TuxOnIce includes a /sys/power/tuxonice/ interface which allows you to tune & configure TuxOnIce according to your needs.

sysfs entry descriptions

The entries within /sys/power/tuxonice/ are:

debug_info

(Requires debug enabled) Debug information that should be included with any debugging reports.

user_interface/debug_sections

Which sections to show when viewing debug info. Only available if debugging is compiled in (see include/linux/suspend-debug.h in the kernel source for what each bit controls).

user_interface/default_console_level

What to use as an initial console log level. (see Obtaining debugging information below)

compression/enabled

Disables compression if it was compiled into the kernel (LZF compression is on by default when compiled in).

do_hibernate

Echo anything into this to start a hibernation cycle.

do_resume

Echo anything into this to start resuming.

user_interface/enable_escape

Enables the possibility of aborting a hibernation cycle by pressing the Escape key during hibernation. (Note: some people consider this a security breach if, for example, you activate a hibernation, walk away and a malicious person aborts the hibernation).

compression/expected_compression

A guesstimate of the compression achieved by the LZF compressor, in order to hibernate when there is less swap available than memory to be written.

swap/headerlocations

Having made a swapfile and turned it on, this file will tell you what to place on your kernel command line (eg something along the lines of resume=swap:/dev/hda3:0x560)

image_size_limit

A soft upper limit on the image size. If more than this amount of memory is allocated when TuxOnIce starts, it will attempt to free memory until this constraint is met. If it is unable to free sufficient memory and other constraints are met, it will still hibernate.

last_result

Bit flags indicating the result of the last cycle (there are many more bits than just those given below - see the source code for a complete list).

• 0x1: on if the last hibernate was unsuccessful. Additional bits specify the cause:
• 0x2: hibernation aborted at user's request.
• 0x4: hibernation aborted because there was no swap space enabled.
• 0x8: hibernation aborted because there was insufficient swap available.
• 0x10: hibernation aborted because all processes could not be frozen (dmesg will show which processes couldn't be frozen).

user_interface/log_everything

Set to log output that's not normally logged.

user_interface/pause_between_steps

Pause between the steps of the process (useful for debugging).

powerdown_method

Use your machine's ACPI implementation to put the machine to sleep in one of 3 ways. Entering 3 into here will make the machine enter S3 (suspend-to-RAM) after writing the image to disk. This allows for a faster resume under normal circumstances, but no losses if your battery should run out or for any other reason suspend-to-RAM should not wake up. Entering 4 will use the machine's S4 state - this may result in a faster resume, as many of the usual BIOS checks may be skipped. Entering 5 will powerdown the machine as per usual.

reboot

Set to reboot instead of powering off at the end of saving the image.

resume

Allows you to set what would be on the kernel command line as resume= (saves a reboot if you forget). This tells the kernel where to write the hibernation image. You will still need to add it to your bootloader (LILO or GRUB) in order to resume from the image!

slow

Slows down the hibernate process (for debugging).

swapwriter/swapfilename

Set the name of the swapfile to be automatically enabled and disabled before and after hibernating. See Using a swapfile for more information.

version

Read only. The version of the TuxOnIce patch you are using.

Obtaining debugging information

To get debugging information, you first need to have compiled TuxOnIce with the 'Compile in debugging output' option enabled. You will probably also want to compile in SysRq support (in the 'Kernel Hacking' section). Having done this, during a hibernation cycle, you can press the 0-9 keys to change the console loglevel. As you do so, TuxOnIce varies the amount of output it produces. Level 0 is the normal 'nice' display. Level 1 enables a little more detail. Levels 3+ turn off the nice display and give more detailed information.

You can toggle whether TuxOnIce pauses between each step of the process by pressing the Pause or Break (useful if you have KDB enabled) keys. There are also proc entries to set initial values for these settings. You may not want to view all the information TuxOnIce prints. In this case, you can set the debug_sections parameter to control what portions of output are printed (see include/linux/suspend-debug.h in the kernel source for what each bit controls).

4.3 TuxOnIce hotkeys

When a hibernation cycle is in progress there are a number of keys that can be used to toggle various settings.

• Esc - if the enable_escape entry is set to 1, pressing Escape will abort a hibernation cycle and restore the machine back to the previous state. Perfect for those "Oh, but I just forgot to ..." situations.
• R - toggles rebooting at the end of hibernating (same as the reboot /proc entry).
• P (Requires debug enabled) - toggles pausing between major steps when log level > 1.
• S (Requires debug enabled) - toggles pausing between minor steps.
• ` (Requires debug enabled) - toggles slowing down the hibernate process.
• Space - continue when paused.
• L - toggles logging all messages to syslog (same as the log_everything /proc entry). This requires that debugging be enabled (compiled in).
• 0-7 - sets the console log level during hibernation and resume. This requires that debugging be enabled (compiled in).

4.4 Avoiding data loss

While much care has gone into TuxOnIce to ensure reliability and safety of your data, there are some unusual scenarios which may lead to filesystem corruption and data loss. With a modern journalled filesystem (eg, ext3, reiserfs, xfs, jfs) a failed resume should not cause filesystem corruption, as this is the equivalent of simply losing power which should be dealt with gracefully.

Other more dangerous situations are described below, with ways to workaround and avoid them:

Booting non-TuxOnIce aware kernels

Problem: Booting a second kernel that does not recognise the hibernated image in your swap partition. Or, attempting to resume with the same kernel, but failing to put a resume= parameter in your bootloader, then putting one in and resuming without removing the image first.

This is very dangerous as there is no warning. For example, you have two kernels, Kernel A and Kernel B. Kernel A has TuxOnIce support, and Kernel B does not.

The danger comes when hibernating with Kernel A, you then decide to boot Kernel B, that does not recognize the swap image. It ignores the "bad" swap partition and runs without it as if nothing happened (except it may run low on memory).

The problem to the hibernated Kernel A is that since Kernel B mounted the filesystem r/w, it no longer matches the hibernated kernel and will be corrupted on resume. Thus, severe damage to the filesystem will result once the disk is written to by the resumed kernel.

This problem has bitten unsuspecting users when, for example, a new kernel is released for their distribution and automatically installed, or if you boot a live CD (eg, Knoppix) and try to mount filesystems from there.

Solution: Should this scenario occur, either the hibernated kernel must be prevented from resuming. This can be accomplished by an mkswap of the swap partition from Kernel B, or booting Kernel A with noresume. To make sure this always happens, below is a snippet from SuSE's bootscripts (courtesy of Stefan Seyfried) that you can put into an init script that is started early on boot (before swapspace is enabled). Another alternative is to modify your bootloader upon hibernating to enforce you to boot the same kernel. The hibernate script has configuration options for doing this in both GRUB and LILO.

#!/bin/sh

get_swap_id() {
        local line;
        fdisk -l | while read line; do
                case "$line" in
                        /*Linux\ [sS]wap*) echo "${line%% *}"
                esac
        done
}

check_swap_sig () {
        local part="$(get_swap_id)"
        local where what type rest p c
        while read  where what type rest ; do
                test "$type" = "swap" || continue
                c=continue
                for p in $part ; do
                        test "$p" = "$where" && c=true
                done
                $c
                case "$(dd if=$where bs=1 count=6 skip=4086 2>/dev/null)" in
                S1SUSP|S2SUSP|pmdisk|[zZ]*) mkswap $where
                esac
        done < /etc/fstab
}

check_swap_sig

Windows touches your FAT partitions whilst Linux is hibernated

Problem: Similar to the scenario above, if you have mounted FAT drives or partitions when hibernating and you then boot into Windows, as soon as you boot back into Linux you will probably end up corrupting your FAT drives.

Solution: Unmount your FAT drives before hibernating. If you are using the Hibernate Script, you can use the following line in your hibernate.conf:

UnmountFSTypes vfat fat msdos

An initrd mounts your filesystem before resuming

Problem: An incorrectly setup initrd can corrupt your filesystem if it tries to mount it before resuming.

If your filesystem is touched in any way before resuming, your data will risk serious corruption. This even includes mounting the filesystem in read-only mode as many journalling filesystems (ext3, reiserfs, xfs) will replay the journal.

Solution: Ensure your initrd is setup correctly - attempting to resume should be the first thing it tries to do after mounting /proc. If you are using an initrd, enable the "Warn if possibility of filesystem corruption" in the TuxOnIce kernel configuration. This will throw a BIG FAT WARNING if you try to resume after a filesystem has been mounted read/write. It won't catch all cases, but will probably get the most common ones.

You may find this will throw spurious BIG FAT WARNINGs at your initrd being mounted read-write (which is safe in itself, as it is not linked to the hard disk). To avoid the warning here, you should mount your initrd as read-only whilst trying to resume, by putting the two mount lines below into your linuxrc script:

mount -n -o remount,ro /
echo 1 > /sys/power/tuxonice/do_resume
mount -n -o remount,rw /