----------------------------------------------------------------
HOWTO HIBERNATE
		  Cookbook Hibernation Instructions
				  or
		I Don't Care, I Just Want It To Work!
----------------------------------------------------------------

This file attempts to walk you through the process of setting up your computer
to hibernate ("suspend to disk").  We assume you are running a stock Debian
kernel, and that hibernate will be defaulting to the "swsusp" method.

(In the future it is hoped that even this small amount of configuration will
be automated.)

****************************************************************
**** WHAT YOU NEED TO DO
****************************************************************

**** INSTALL AND REMOVE PACKAGES

The following packages must be installed/removed:

 install: hibernate (version >= 1.91)
 install: initramfs-tools
 remove: yaird
 install: udev (reasonably recent, eg version >= 0.093)
 install: linux-image-XXX-YYY (with XXX >= 2.6.8)


**** IDENTIFY SWAP PARTITION

When awakening from hibernation, the kernel needs to know the location where
the state of the suspended system is stored. This can be either a swap
partition or a file.

You can figure out your swap partition using the command

 egrep swap /etc/fstab

or

 swapon -s

If what you see is of the form

 /dev/ide/hostX/busX/targetX/lunX/partX

you need to translate to the form /dev/hdXX or /dev/sdXX as
appropriate, which can be done by looking for the symbolic link in
/dev/.  Here is a code fragment that shows what this looks like.

 $ ls -l /dev | egrep $(/sbin/swapon -s | sed -rne '0,/^\/dev/s,/dev/([/[:alnum:]]+).*,\1,p')
 lrwxrwxrwx 1 root root       33 Jul  9 10:21 hda3 -> ide/host0/bus0/target0/lun0/part3


**** CONFIGURE INITRAMFS-TOOLS OPTION

The swap partition needs to be listed in
/etc/initramfs-tools/conf.d/resume .  (If you have an old version of
initramfs-tools, the file is /etc/mkinitramfs/conf.d/resume .)  It
should look like this, where /dev/hdXX is your swap partition:

 $ cat /etc/initramfs-tools/conf.d/resume
 RESUME=/dev/hdXX

If the file is already there but has /dev/ide/hostX/busX/... you need
to convert it to the proper form, as above.


**** REBUILD /boot/initrd.img

Rebuild the initrd.img boot ram filesystem images by invoking

 update-initramfs -u -k all


**** REBOOT

You should now reboot into your shiny hibernation-capable system.


**** TEST THAT HIBERNATION WORKS

At this point, you should be able to run

 hibernate

and it should do some crunching and then halt.  When you reboot, the
system should instead magically awaken from its hibernation.



****************************************************************
**** WARNINGS
****************************************************************

Don't suspend your system, then somehow boot using some other
mechanism like a CDROM and play with the filesystems, then try to
unsuspend the system.  This would lead to corruption of your data.


****************************************************************
**** INFORMATION YOU PROBABLY WILL NOT NEED
****************************************************************

***** Booting without resuming

If you hibernate but then need to do a "normal" cold boot, ie not an
unsuspend, you can pass the option resume= to the kernel from the boot
loader.  (This is good to do if you modified the filesystem using some
external mechanism, like booting off a rescue disk.)


***** IDE vs SCSI

Instead of /dev/hdXX, your swap partition might be of the form
/dev/sdXX.  That is okay.


***** USING BOOT LOADER TO PASS OPTION RESUME=

Instead of using initrd, you can pass the resume=/dev/hdXX option
directly to the linux kernel, where /dev/hdXX is your swap partition.
This can be done manually, when the system is booting, or by
reconfiguring your boot loader to do it.

The resume= option is harmless if the machine is not suspended, so you
can modify the boot loader to always pass the option.  How to do this
depends on which boot loader you use: LILO or GRUB.

****** LILO

If you run lilo, add the line

 append="resume=/dev/hdXX"

at the top of the file /etc/lilo.conf and run the command

 lilo

****** GRUB

If you run grub, edit /boot/grub/menu.lst to include the line

 # defoptions=resume=/dev/hda1

immediately following the line

 ## e.g. defoptions=vga=791 resume=/dev/hda5

and run the command

 update-grub


**** CORRUPTION

Some old disk drives fail to write some information sent to them
immediately before the system powers down.  If you have one of these,
you should set DisableWriteCacheOn for the drive in
/etc/hibernate/common.conf.


**** TROUBLESHOOTING: HARDWARE ISSUES AFTER AWAKENING

Some kernel modules need to be unloaded prior to hibernation.  This is
largely preconfigured, but some carelessly built hardware, for
instance many Dell laptops (Dell is notorious for sloppy engineering)
require that particular modules be unloaded.  For example, on my Dell
X200, a particularly worthless piece-of-crap laptop which is also
surprisingly slow, the 1394 (firewire) interface failed after
hibernation.  This was cured by adding the line

 UnloadModules ohci1394 ieee1394

to /etc/hibernate/common.conf immediately following the line

 # UnloadModules snd_via82cxxx usb-ohci


**** AUTHORS

This HOWTO was started by Barak A. Pearlmutter as a "cheat sheet" for
his friends, and grew with help from Martin F. Krafft.

$Id$
