The hibernate-script package offers a utility that performs all the preparatory
steps to suspending your machine, invoking the desired suspend method (either
one of the suspend-to-disk variants, or suspend-to-RAM), and restoring your
machine on resume.

PREREQUISITES
-------------
A kernel with suspend support of some variety. The currently supported options
are:
 - TuxOnIce  - kernel patches are available from http://www.tuxonice.net/
 - swsusp support in vanilla 2.6 kernels (through the UseSysfsPowerState disk
   option).
 - S3 (suspend-to-RAM) support in 2.6 kernels (through the
   UseSysfsPowerState mem option).

INSTALLATION
------------
To install, simply run the install.sh script as root:

# ./install.sh
[...]

By default, this will install the following files and directories:

/usr/local/sbin/hibernate        <--- main executable script
/etc/hibernate/
/etc/hibernate/hibernate.conf    <--- main configuration file
/usr/local/share/hibernate/scriptlets.d/ <--- contains "scriptlets" (or plugins)
  and the various scriptlets that live here
/etc/hibernate/scriptlets.d/     <--- contains any extra scriptlets
/usr/local/man/man8/hibernate.8
/usr/local/man/man5/hibernate.conf.5

If you already have a configuration file at /etc/hibernate/hibernate.conf, the
new configuration file will be installed at /etc/hibernate/hibernate.conf.dist
You will have to merge your changes manually.

AVOIDING DATA LOSS
------------------
If you are using the hibernate script with vanilla swsusp or TuxOnIce, then it
is strongly recommended that you install the script init.d/hibernate-cleanup.sh
into /etc/init.d (or the relevant place on your distribution), and arrange for
it to be run on boot from rcS.d, somewhere before enabling swap or clearing out
/var/run, but after mounting your filesystems (/var in particular).

This script will invalidate any suspend image on a clean boot so that the image
cannot be later resumed from (leading to corruption of your filesystems).

Additionally, the hibernate script will look for a particular file before
suspending (/var/run/tuxonice-new-kernel) and if it is detected, will refuse to
suspend.  The idea is that your installation scripts for new kernels create
this file, which prevents you from hibernating until you have booted your new
kernel (or you remove the file manually if you know what you are doing). For
example, kernel packages compiled with the Debian kernel-patch-tuxonice patches
do this upon installation.

CONFIGURATION
-------------
The default configuration does nothing but save and restore your clock, and
unload some modules that will potentially cause suspending to fail. If you have
other kernel modules that need to be unloaded, filesystems unmounted, network
interfaces brought down, etc, you will want to customise the configuration file
in /etc/hibernate/hibernate.conf. Run hibernate -h for help on the possible
options. There is also a man page for hibernate.conf as well as hibernate
itself.

RUNNING
-------
Simply calling "hibernate" as root will do everything mentioned in the
configuration file to hibernate, and activate your suspend method. Upon
resuming, any tasks for resuming the machine are run and the script exits.

If you want users other than root to be able to run the script, check out the
sudo package.

CALLING FROM ACPID
------------------
You may wish to call this script from acpid to allow you to press a button on
your machine to hibernate, or to activate it on lid closure. For example, you
could modify /etc/acpi/events/powerbtn to run hibernate when you press the
power button, as follows:

  event=button[ /]power PWRF
  action=/usr/local/sbin/hibernate

You can watch ACPI events as they occur by running acpi_listen. If you find that
your machine is hibernating twice, you are probably receiving two events for
each button press. To only trigger on one, you may need to use the line

  event=button[ /]power PWRF.*[02468ace]$

to match only every second event. However, for non-button events (such as
triggering on lid closure), it may be more reliable to check the state of the
lid before suspending. For example, a small script called /etc/acpi/lid.sh :

  #!/bin/sh
  #
  # Initiate suspend when lid is closed

  if grep -q closed /proc/acpi/button/lid/$2/state ; then
      /usr/local/sbin/hibernate
  fi

and in /etc/acpi/events/lid

  event=button[ /]lid
  action=/etc/acpi/lid.sh %e

will trigger only when the lid is closed.

For more details, man acpid. For debugging look into /var/log/acpid.

MORE SCRIPTLETS
---------------
As the hibernate script is very extensible , some users have written their own
scriptlets to control certain applications or hardware at suspend and resume
time. These scriptlets can be found on the TuxOnIce Wiki at
http://wiki.tuxonice.net/HibernateScript . These are not supported by the
hibernate script author, but you should be able to find help either from their
respective authors or the tuxonice-users list.

HELP
----
If you have problems with the hibernate script or TuxOnIce, the best
place to ask is on the mailing list - tuxonice-users@lists.tuxonice.net.  You
will need to subscribe to post. See http://www.tuxonice.net/lists for details.

If the suspend process itself crashes (while "Writing caches", "Reading
caches", or "Copying original kernel back", etc), then the problem lies with
TuxOnIce itself. See the FAQ at http://www.tuxonice.net/ for help on
debugging.

AUTHOR
------
This script was written by Bernard Blackham, with contributions from:
 - Carsten Rietzschel (modules, devices, bootsplash, lock and grub scriptlets.
   many ideas and bugfixes)
 - Cameron Patrick (sysfs_power_state, xscreensaver support for lock, many
   bugfixes and ideas, man pages and Debian packaging)
 - Kevin Fenzi (rpm packaging, ideas)
 - Henrik Brix Andersen (gentoo packaging, hardware_tweaks scriptlet and doing
   lots of debugging)
 - martin f. krafft (bugfixes and ideas, XFS handling, Debian integration and
   packaging)
 - Fedor Karpelevitch (lilo scriptlet idea)
 - And many others! (see changelog for full credits)

LICENSE
-------
Copyright (C) 2004-2006 Bernard Blackham <bernard@blackham.com.au>

The hibernate-script package is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program.  If not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

$Id: README 1220 2009-04-01 02:06:57Z nigel $