Difference between revisions of "Hibernate-script"

From ArchWiki
Jump to: navigation, search
(Using userui - a user interface for tuxonice)
(Take action on lid close / power button)
Line 339: Line 339:
For this to work, your computer must be able to use suspend to RAM also without s2ram.
For this to work, your computer must be able to use suspend to RAM also without s2ram.
=Take Action Based on Events=
==After Pressing Power Button==
Edit the following file <code>/etc/acpi/events/power</code>
  # This is called when the user presses the power button 
  event=button/power (PWR.||PBTN) 
  # To Hibernate uncomment the following line
  # To Suspend uncomment the following line
==After Closing Lid==
Edit the following file <code>/etc/acpi/events/lid</code>
  # This is called when the user closes the lid
  # To Hibernate uncomment the following line
  # To Suspend uncomment the following line

Revision as of 01:23, 28 July 2008

This article describes how to suspend a computer (usually a laptop) to disk. This means that all the running processes are saved to the hard drive and the power is completely shut down. The article discusses the two main methods to accomplish this task, that is userspace suspension (uswsusp) and tuxonice (formerly known as suspend2). See the ususpend website and the tuxonice website for complete documentation. There is a third method: using the kernelspace functionalities of the vanilla kernel. However, this method is the least developed, the slowest and the less reliable. On the contrary, tuxonice and ususpend are competing in features and stability. The only method to decide which method is better for you is to try both of them. From a general point of view, we can say that uswsusp does not force you to patch, configure and compile a kernel, while tuxonice does. However, tuxonice can be used without an initrd/initramfs, while using ususpend without an initrd/initramfs is discouraged; moreover, tuxonice allows you to suspend on a regular file if you have not a swap partition, while uswsusp give this possibility only if you run an experimental and unstable mm kernel.

It is important to distinguish the core method of suspension to disk from the userspace application which you use to hibernate your machine to disk. A userspace application is required because the large majority of the laptops require some quirks in order to accomplish a proficient, successful hibernation cycle: unloading modules, restarting services, unmount windows partitions and usb keys, and so on.

There are two widely used userspace applications for this purpose: pm-utils and hibernate-script. You can find both of them in the extra repo. However, since in this guide we need to describe two different, competing core methods, we will focus on the hibernate-script, since only this script allows the user to choose the core method he prefers. On the contrary, pm-utils, at least in the version actually distributed by arch, forces you silently to use the old vanilla method. On the other side, the script, developed by the tuxonice development team, can be used nonetheless also to hibernate your machine with the ususpend method, and even to suspend the machine to ram (actually it is an excellent tool also for this task, but we are not going to discuss this aspect in this document, see Suspend to RAM).

If you prefer to use pm-utils, refer to the specific wiki article. You should note that the pm-utils-opensuse package includes some patches from opensuse which allow the user to choose uswsusp as a core method. In the web you can find other patches which allow you to use tuxonice as a method. The upcoming release of pm-utils will include all these patches and pm-utils will be a serious competitor of the hibernate-script. Nonetheless, the hibernate-script is still much more configurable and documented, so this guide still assumes that you are using it (although it is very easy to translate each info for pm-utils).


# pacman -S hibernate-script

The discussion will be articulated in four parts. First of all, we will discuss the userspace method, secondly the tuxonice one, thirdly we will see how to use the power of the hibernate-script in order to circumvent some problems which could impair your ability to accomplish successful suspend/resume cycles. These last tips can be used with both methods. On the contrary, the first two parts will include instructions to use the hibernate-script in order to accomplish the basic operations with the two methods. In the fourth and last part, we will see how to combine suspension to disk and Suspend to RAM .

When there is the need to modify the configuration of the bootloader, we will be always under the assumption that you use grub, but it should not be difficult to act analogously on the configuration of lilo.

Uswsusp method

The userspace method lets you resort to some advanced suspension abilities included in vanilla kernels > 2.6.17. You need two userspace tools, called s2disk and resume, which do what their names say. They are both included in the uswsusp package (which includes also s2ram, see Suspend to RAM ). You can find uswsusp in the AUR. The package in the AUR includes also an initramfs hook which allows you to resume properly using an initramfs.

Obtaining uswsusp

The first thing to do is to download the tarball from the AUR page. Compile the source and create the package with makepkg and install it with pacman -U.

Editing /etc/suspend.conf

On the contrary, you need to edit the s2disk configuration file, called /etc/suspend.conf. It is essential that you modify the resume device parameter:

resume device = /dev/sda3

It needs to point to your swap partition: in this case, the third partition of a primary pata-sata drive. It is also a good thing to enable compression, because this speeds up greatly your suspension/resume routine.

Note that it is important that this configuration file be edited *before* recreating the initramfs (done below). Presently, the initramfs build process reads this configuration file, and embeds the current resume parameter. If not changed from the default '<path_to_resume_device_file>', this causes problems such as seeing, on bootup:

# Could not stat the resume device file '<path_to_resume_device_file>'
# Please type in the full path name to try again or press ENTER to boot the system.

If you have experiencing this problem, simply edit the file as appropriate, and then rebuild the initramfs.

Recreate the intramfs

Now you need to recreate an initramfs with the new hook. So edit the /etc/mkinitcpio.conf file. In the HOOKS list add the uresume hook (it is different from the resume hook, which is on the contrary required by the tuxonice method). You should put it immediately before the filesystem hook. When the hook is executed the device file for the swap partition (which you have defined in /etc/suspend.conf) needs to exist (the standard udev hook will take care of this). Now proceed to regenerate your initramfs :

# mkinitcpio -k `uname -r` -g /boot/kernel26.img

You need to adjust this command according to the kernel you plan to use and the name of the initramfs in the grub configuration. Anyway you should not need to modify anything in the grub configuration.

Support for encryption

The package in the AUR does already support encryption. You need to:

  • generate a key with the suspend-keygen utility included in the uswsusp package;
  • write the name of the key in /etc/suspend.conf;
  • uncomment or add the following line in /etc/suspend.conf
encrypt = y
RSA key file = <path_to_keyfile>
  • build a new initramfs with the uresume hook just before the filesystem one.

Support for splash screens and suspension to file

The AUR package does not provide support for splash screens: uswsusp would support splashy and fbsplash, but you need to modify the PKGBUILD in order to recompile uswsusp with libsplashy or fbsplash support: see the HOWTO and README in the source tarball for details.

Please note that uswsusp can also suspend to a file, but only if you use an experimental mm-patched kernel. If you want to suspend to file, tuxonice is probably the way to go. In the case you like experimental things, see the instructions in the HOWTO of the uswsusp source tarball.


Now you could try to suspend directly calling s2disk from the command line:

# s2disk

However, this is highly likely to fail, because some services could need to be stopped, some modules unloaded, etc. Thus it is probably necessary to resort to a userspace tool which calls internally s2disk, like Pm-utils since version 1.1 (which is now in core) or hibernate-script. See below about details for defining the ususpend-disk method as default in /etc/hibernate/hibernate.conf. For the moment being, remember that you can define specific options in /etc/hibernate/ususpend-disk.conf and, after having configured also /etc/hibernate/common.conf, you can suspend to disk with the uswsusp method with the following command:

# hibernate -F /etc/hibernate/ususpend-disk.conf

Tuxonice method

Obtaining tuxonice

Tuxonice consists of a kernel patch, plus a user interface. Only the kernel patch is necessary, the user interface provides merely a semi-graphical interface displayed during the hibernation/resume cycle.

Archlinux used to deliver a binary tuxonice-patched kernel, but none of the devs want currently to maintain it.

However you can use the kernel26-ice in AUR unsupported. It automatizes all the patch routine, the compilation and installation of the kernel, the regeneration of the initramfs with an appropriate hook.

Otherwise, you need to patch, configure and compile your own kernel. You can do this either with the ABS method (starting from the arch default kernel PKGBUILD and adding the tuxonice patchset, or with the plain, old, reliable, venerable routine of

# make menuconfig
# make
# make modules_install
# cp arch/i386/boot/bzImage /boot/kernel-tuxonice-2.6.*

See Kernel Compilation From Source and Kernel Compilation with ABS for instructions. In both cases, you need to configure the options added by the patchset, which you can find in the ACPI section of make menuconfig. Anyway, the defaults should be suitable for the large majority of scenarios. You can also hardcode in the kernel the path of your swap partition. In this case you can skip the below Suspend to Disk#Editing the Grub menu.lst .

Please note that, if you spend the time to reconfigure completely the kernel (and in particular if you compile into the kernel the stuff necessary to boot your machine), you can be dispensed by the necessity to generate and use an initramfs: tuxonice will be able to resume properly also without an initrd/initramfs.

Editing the Grub menu.lst

Before your can use the suspend function, you need to boot your computer with the "resume" parameter, unless you have hardcoded your swap partition during the kernel configuration. The resume parameter points to the swap partition or swap file. The parameter is a kernel boot parameter, that is it should be added, if you use GRUB, to the line of /boot/grub/menu.lst where the location of your kernel is specified. For example:

# tuxonice kernel
title ArchLinux
kernel /boot/vmlinuz26-ice root=/dev/sda2 ro resume=swap:/dev/sda3
initrd /boot/kernel26-ice.img

This assumes that you installed Archlinux onto the second hard drive partition, that your swap partition is the third, that you have not a separate /boot partition and that you are using an initrd with pata/sata enabled. Adjust accordingly to your case.

Recreating the initramfs

If you use an initramfs, you need to add the resume hook (which is the same as used for vanilla kernel suspension) in the HOOKS in the configuration of mkinitcpio. Additionally, if you want to speed things up by using LZF compression, you must add the module lzf to the MODULES in the same file.

/etc/mkinitcpio.conf Example:

HOOKS="base udev autodetect pata scsi sata resume filesystems"

Once you have added the resume hook, and all needed modules you need to regenerate your initramfs, with a command like the following:

# /sbin/mkinitcpio -p kernel26-ice

Using userui - a user interface for tuxonice

Optionally, you can use a text or fbsplash interface with a progress bar with tuxonice. To do this, install the userui package in the extra repo:

# pacman -S userui

In /etc/hibernate/suspend2.conf, configure the user interface:

## Specify a userui like this:
# text interface
ProcSetting user_interface/program /usr/sbin/tuxoniceui_text


## Specify a userui like this:
# fbsplash interface interface
ProcSetting user_interface/program /usr/sbin/tuxoniceui_fbsplash

The fbsplash interface also needs a fbsplash theme in /etc/splash/suspend2/.

The text interface may be good for debugging suspend2, as it displays some messages. You won't see a user interface for the first few seconds of the resume process unless you add the userui hook to your mkinitcpio (before the resume hook) configuration and regenerate your initramfs, but this is also optional. When you use the kernel26tp 2.6.25 (or any other newer kernel versions, I guess), you have to edit /lib/initcpio/hooks/userui so that it searches for tuxonice at the right place, make it look like this:

# vim:set ft=sh:
run_hook ()
   if [ -d "/sys/power/tuxonice" ]; then
   if [ -e ${suspend2ui} ]; then
       echo "/sbin/suspend2ui" > ${suspend2ui}

Then run mkinitcpio -p kernel26tp or similar

Suspending and Resuming

Now you need to tweak the hibernate script. See below for instructions about defining the tuxonice method as the default hibernation method. The specific file is /etc/hibernate/suspend2.conf (the hibernate-script still uses the old name of tuxonice):

Make sure that the following lines are uncommented and appropriately configured:

UseSuspend2 yes
Reboot no
EnableEscape yes
DefaultConsoleLevel 1
Compressor lzf
Encryptor none

Once you have tweaked what you want/need (also in /etc/hibernate/common.conf), you can try tuxonice hibernation with the following method:

# hibernate -F /etc/hibernate/suspend2.conf

You can abort a suspend cycle if you press the escape key. If you press a capital r, you will force the system to reboot after hibernation. If all goes well, you should be able to resume using the same Grub menu selection. If you make that option the default for Grub, you will always default to resuming if a resume image is available. Do never use a different kernel to resume than you used to suspend! If pacman updates your kernel, don't suspend before you have rebooted properly. It is recommended that you test the suspend/hibernate from a text console first and then once you have confirmed that it works try it from within X.

You can make this practice safer adding the hibernate-cleanup service to your SERVICES array in /etc/rc.conf. This script will make sure that any stale image is deleted from your swap partition at boot time. This should make your system safe also in the case that you have chosen the mistaken kernel at the grub prompt. The hibernate-cleanup service is included in the hibernate-script package.


Hibernate tricks with the hibernate.script

WARNING: With kernel26-ice 2.6.25-6 I needed to bump hibernat-script to 1.99 (using ABS) --kujub

/var/abs/local/hibernate-script/PKGBUILD (quick-and-dirty)

 pkgdesc="Scripts needed for software suspend aka hibernate"
 arch=(i686 x86_64)
 backup=('etc/hibernate/hibernate.conf' 'etc/hibernate/suspend2.conf' \
         'etc/hibernate/disk.conf' 'etc/hibernate/ram.conf' \
         'etc/hibernate/common.conf' 'etc/hibernate/blacklisted-modules' \
         'etc/hibernate/ususpend-both.conf' 'etc/hibernate/sysfs-ram.conf' \
         'etc/hibernate/ususpend-ram.conf' 'etc/hibernate/sysfs-disk.conf' \
 source=(http://www.suspend2.net/downloads/all/hibernate-script-$pkgver.tar.gz \
     hibernate-script-1.96-arch.patch hibernate.rc)
 #        hibernate-script-${pkgver}-arch.patch hibernate.rc)
 depends=(bash kbd)
 build() {
   cd $startdir/src/hibernate-script-$pkgver
   # Fix scriptlets to work properly with Archlinux
 #  patch -Np1 -i ../hibernate-script-${pkgver}-arch.patch || return 1
   patch -Np1 -i ../hibernate-script-1.96-arch.patch || return 1
 ## remove stale file (filename with dot breaks eval)
 rm -f scriptlets.d/suspend2.orig
   export BASE_DIR=${startdir}/pkg
   export PREFIX=/usr
   mkdir -p $startdir/pkg/etc/{rc,logrotate}.d
   ./install.sh || return 1
   install -m 755 ../hibernate.rc $startdir/pkg/etc/rc.d/hibernate-cleanup

This is a brief overview of the hibernate script. If you want to tweak it further, examine the common.conf and suspend2.conf files further and read the excellent and exhaustive man pages for hibernate and hibernate.conf.

Editing /etc/hibernate/hibernate.conf

In order to call directly the hibernate command without the -F option, you need to define your preferred hibernation method. This should be done in this file. If you list several methods, the first one will be used. Note that hibernate can also be used with Suspend to RAM or vanilla swsusp, but this is not part of this HOWTO).

Then either:

TryMethod ususpend-disk.conf


TryMethod suspend2.conf

Editing /etc/hibernate/common.conf

The options in this file are used with any hibernation method (actually, the file is sourced by the configuration files of each method) and also by Suspend to RAM when accomplished with the hibernate-script. This file is complex and well commented. The man page hibernate.conf describes adequately all the options. Here, we can only stress the most commonly useful parts.

Uncomment the lines for any filesystems that have the potential to change while your computer is suspended (for example shared partitions with windows like vfat or ntfs ones). They will be remounted upon resume. Otherwise you would risk corrupting the filesystems.

### filesystems
# Unmount /nfsshare /windows /mnt/sambaserver
# UnmountFSTypes smbfs nfs
# UnmountGraceTime 1
# Mount /windows

If you don't explicitly restore the volume levels, ALSA may have the sound channels muted after resuming. If this happens, look for

### services

in /etc/hibernate/common.conf and change the line just below to

RestartServices alsa

The alsa service will be stopped before suspension and restarted after resuming: the sound channels and volumes will be as before. You may want to restart other problematic services here.

A common issue is that some drivers do not support suspension, that is they do not work properly after a suspension cycle or even they prevent the system from suspending or resuming properly. In these cases (which should be reported - at least for modules in the vanilla kernel - to the suspend-devel@lists.sourceforge.net mailing list, so that they can be fixed upstream) you can unload the module before suspension and reload it after resuming: the hibernate-script can automatize this routine with the LoadModules and UnloadModules options. Actually, the hibernate-script already unload some problematic modules, listed in /etc/hibernate/blacklisted-modules, so you can also add the modules in that file.

To re-connect to networks after rebooting, you may want to add

 OnResume 25 netcfg2 -a
 OnResume 20 netcfg-auto-wireless <your-network-interface>

This will disconnect from all networks, then should automatically choose the correct one. If you use another way to connect to a network (such as netcfg2 <profile-name> then of-course, put that there instead.

If you need/want to eject all PcCards before suspending and reinsert them after resuming, change the EjectCards setting in common.conf:

### pcmcia
EjectCards yes

This is necessary on some laptops, if the pccards stop working after resume.

Finally, the most problematic aspect is constituted by the video card: its status needs often to be restored after resuming. In other cases, it is necessary to switch from X to the console. The following options in /etc/hibernate/common.conf will probably fix these issues (whose symptom could be a frozen machine or only a black display after resuming):

### vbetool
#EnableVbetool yes
#RestoreVbeStateFrom /var/lib/vbetool/vbestate
#VbetoolPost yes
# RestoreVCSAData yes
### xhacks
#SwitchToTextMode yes
#UseDummyXServer yes
#DummyXServerConfig xorg-dummy.conf

You can uncomment one or many of them in order to see if the problem is solved. In order to use the first block of options, you need to install the vbetool package from the extra repository. Each of the option is documented in man hibernate.conf. Please note that it is very important to try all the different combinations of these options before than anything else, becaause the problems with the display are the most common source of troubles in a suspension cycle.

NVidia specific settings

If you have an NVidia graphics card and are using the binary driver by NVidia with an AGP card, you have to add the following line to your /etc/X11/xorg.conf:

Option "NvAGP" "1"

NVidia also suggest this setting for the hibernate script:

ProcSetting extra_pages_allowance 0

to the file /etc/hibernate/common.conf. This setting also seems to help with the binary ATI driver. At last, you need to uncomment the nvidia module in /etc/hibernate/blacklisted-modules.

Suspending with fglrx

Following addition to /etc/hibernate/suspend2.conf is required:

# For fglrx
ProcSetting extra_pages_allowance 20000

Dropping Disk Caches

As a way to speed up suspending, you can free the memory used for disk caches. so there will be less to write to the disk. The downside is the risk of crashing your system. but I have had no trouble with it so far, while reducing the size of the suspended image by half. Just run this before hibernating:

  sync; echo 3 > /proc/sys/vm/drop_caches

drop_caches introduction

Combining suspend to disk with suspend to RAM

If your motherboard or laptop supports Suspend to RAM, you can combine it with suspend2. This will result in the following behavior:

  • When you call hibernate, your system will suspend to disk and after that suspend to RAM instead of powering down.
  • When you turn your system back on, it will resume directly from RAM (which only takes a few seconds)
  • If your battery fails in the meantime (and the image in your memory is therefore lost), you will be able to resumes from disk.

This can be done both with uswsusp and with tuxonice.

With uswsusp, you should use s2both. You can also call s2both from the hibernate script (with all its richness of options), resorting to the ususpend-both.conf method. Please note that s2both works only if s2ram (see Suspend to RAM) works in your system. There is no way to force it to work if your laptop model is not whitelisted in s2ram. See Suspend to RAM for instructions about how to whitelist your laptop in the local copy of s2ram and how to report that your laptop suspend to ram properly so that it is whitelisted in the next uswsusp release.

To do it with tuxonice, edit /etc/hibernate/suspend2.conf:

## Powerdown method - 3 for suspend-to-RAM, 4 for ACPI S4 sleep, 5 for poweroff
PowerdownMethod 3

For this to work, your computer must be able to use suspend to RAM also without s2ram.

Take Action Based on Events

After Pressing Power Button

Edit the following file /etc/acpi/events/power

 # This is called when the user presses the power button  
 event=button/power (PWR.||PBTN)  
 # To Hibernate uncomment the following line
 # To Suspend uncomment the following line

After Closing Lid

Edit the following file /etc/acpi/events/lid

 # This is called when the user closes the lid
 # To Hibernate uncomment the following line
 # To Suspend uncomment the following line