File: HOWTO

package info (click to toggle)
uswsusp 0.7-1.2
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 1,000 kB
  • ctags: 962
  • sloc: ansic: 6,060; xml: 755; sh: 425; makefile: 176
file content (580 lines) | stat: -rw-r--r-- 23,852 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
Suspend to disk HOWTO
~~~~~~~~~~~~~~~~~~~~~
Copyright (C) 2006 Pavel Machek <pavel@suse.cz>
Copyright (C) 2006 Rafael J. Wysocki <rjw@sisk.pl>


I. Quick start

1) Necessary items

(a) This package
(b) Linux kernel supporting the swsusp userland interface (2.6.17 or above)
(c) Swap partition or a swap file, approximately as big as 1/2 of RAM
(d) Special device file for the snapshot device (character, 10, 231), e.g.

crw-r--r--  1 root root 10, 231 Jan 13 21:21 /dev/snapshot

(e) libx86, a hardware-independent library for executing real-mode x86 code
(f) [optionally] Markus F.X.J. Oberhumer's lzo library (for lzo image compression)
(g) [optionally] libgcrypt (for image encryption)
(h) [optionally] libsplashy (for user space splash)

2) Basic steps

(a) Configure, build and install the kernel

The kernel has to be configured to support software suspend.  It is also
highly recommended to configure it to support RAM disks, initial RAM disks,
loopback block devices, and the ext2 filesystem, at least for initial testing.
Later on, you can use initramfs instead of initrd (please see Section II of
this document for details).

If you already use initrd or initramfs, you'll need to integrate the resume
binary with it eventually.  However, it's better to postpone this until you
have verified that the suspend utilities work on your system.  Thus it is
recommended to initially build the kernel with all of the drivers needed to
mount the root filesystem (most importantly the drivers needed to access
your hard disk drive) compiled in.  Then, you will only need the initrd to run
the resume binary itself and you will be able to use the resume initrd
installation script provided in this package.

The kernel installation procedure will depend on what Linux distribution
you use and should be documented elsewhere.

(b) Install libx86 developement packages

If libx86 is not installed on your system (Debian: libx86-dev) you can download
the tarball from http://www.codon.org.uk/~mjg59/libx86/downloads/. Unpack it,
change into the resulting directory. Then run

$ make

or if you're building for an x86_64 

$ make BACKEND=x86emu

Next, become root and run

# make install DESTDIR=/usr/local

(c) [optionally] Install the Markus F.X.J. Oberhumer's lzo library

If you want to use the image lzo compression functionality and lzo it's not
installed on your system, download the tarball from
http://www.oberhumer.com/opensource/lzo, unpack it, go to the directory
containing the source and run

$ ./configure
$ make

Next, become root and run

# make install

[This will put the lzo files into /usr/local/include/lzo, the library
into /usr/local/lib.]

(d) [optionally] Install libgrypt

If you want to use the image encryption functionality of the suspend
tools, you'll need libgcrypt to build them.  If you have installed
GnuPG, libgcrypt is present on your system, but you'll also need
the development package for it.

On a SUSE system you can verify if the package has been installed by running

$ rpm -q libgcrypt-devel

and it should give you the version of the package if so (there are similar
methods for any other distribution).  If not, you'll need to install it.

The majority of modern Linux distributions provide a binary package with it
and you should install it in a way that's appropriate for your distribution.
Still, if your distribution doesn't provide the binary package, you can refer
to the documentation at http://www.gnupg.org/ for installation instructions.

(d) [optionally] install libsplashy-dev (for user space splash screens)

For now you need the experimental version of splashy, which can be 
found at svn://svn.debian.org/svn/splashy/branches/0.3 . 

(e) Configure, build and install the suspend utilities

- Edit Makefile and the conf/uswsusp.conf file to reflect the configuration
of your system (please refer to Section II of this document for details).  The
value of the RESUME_DEVICE constant in Makefile must be the same as the value
of the "resume device" parameter in the configuration file and it must be the
full path of a swap partition device file (eg. /dev/hda3).

[There should be just one resume partition, for now. You'll need at most 1/2
of your RAM of free space on it, but in some cases it may be smaller, too.
The s2disk tool may be configured to create quite small snapshot images but
then some contents of the RAM will have to be swapped out before suspend.

It also is possible to use a swap file for suspending, but this only works with
the 2.6.18-mm3 kernel (or later).  In such a case the resume partition is the
partition that holds the swap file, and there is an additional configuration
parameter "resume offset" that has to be set, as described below.]

- Build the suspend tools in the usual way:

$ make s2disk
$ make resume

- To install the s2disk tool, become root and run:

# make install-minimal

This will also create the snapshot device file in /dev/, if needed.

- To create and install an initrd image containing the resume binary, become
root and run:

# make install-resume-new-initrd

This will place the file resume-initrd in the /boot directory.

[If you already use an initrd or initramfs, the resume binary will need to be
integrated with it, but initially it's better to use a separate "resume"
initrd image.  Unfortunately the procedure of installing the resume binary
in the exsiting initrd or initramfs image depends on the Linux distribution
used, but one exaple is given at the end of Section II.]

You will also need to make the kernel use the resume initrd image.
Unfortunately this depends on the Linux distribution too, but if you
use GRUB and the entry in the GRUB configuration file (usually
/boot/grub/menu.lst) corresponding to your newly installed kernel is similar
to following one:

title Linux (2.6.18-rc2)
	root (hd0,0)
	kernel /vmlinuz-2.6.18-rc2 root=/dev/md1 vga=792 ...

where "..." represents some additional kernel command line options, you will
only need to add the line:

	initrd /resume-initrd

right next to the "kernel" line.

[The paths in the above example correspond to the situation in which there is
a separate boot partition.  However, if the /boot directory is located in the
root partition, the only difference will be the appearance of /boot in the
paths, e.g.

title Linux (2.6.18-rc2)
	root (hd0,0)
	kernel /boot/vmlinuz-2.6.18-rc2 root=/dev/md1 vga=792 ...
	initrd /boot/resume-initrd

where we have shown the complete configuration.  The (hd0,0) identifies the
partition that GRUB will use to read the kernel and the initrd image from,
but please refer to the GRUB documentation for more details.]

(e) To suspend to disk, run

# s2disk

NOTE: For this to work you must be running _exactly_ the same kernel that
will be used for resuming.  Otherwise the kernel will refuse to accept the
suspend image.

To resume, just boot the kernel you were running when the image was created
and if the initrd is properly installed, the resume tool will be run
automatically out of it.


II. Installation of suspend tools

1) Kernel configuration

(a) The kernel must support the swsusp userland interface, so it's most
recommended to use the 2.6.17 kernel or above.

(b) The kernel has to be configured to support software suspend, i.e.
the kernel configuration file (.config) has to contain
CONFIG_SOFTWARE_SUSPEND=y

(c) The kernel should be configured with CONFIG_BLK_DEV_INITRD=y, which will
allow you to run the resume binary out of an iniramfs/initrd image.
[It is possible to use the suspend tools without any initramfs/initrd
images, but it's dangerous and will not be documented here.]

(d) It is recommended to configure the kernel with CONFIG_BLK_DEV_RAM=y and
set CONFIG_BLK_DEV_RAM_SIZE to at lease 2048 Kbytes.  [This will make it
possible to use initrd images.]

(e) It is recommended to configure the kernel with CONFIG_BLK_DEV_LOOP=y, or
the resume initrd installation script provided in this package will not work.
Also the loopback device support may be needed for manual configuration
of the initrd image.

(f) The automatic resume initrd installation script provided in this package
installs an ext2 filesystem in the initrd image, so the kernel has to be
configure with CONFIG_EXT2_FS=y for it to work.

(g) For initial testing it's better to compile all of the drivers needed to
mount the root filesystem into the kernel, install the kernel without
an initrd/initramfs, and use the automatically-generated resume initrd
(see below) with it.

2) Installation of optional packages

If you want to use the compression and/or encryption capabilities of the
suspend tools, you'll need the Marc Lehmann's libLZF and/or libgcrypt,
respectively.  Short instructions related to these packages have been
given in Secion I above.

If you want a user space splash screen you will need a splashy theme,
you also have to copy the theme files to your initramfs/initrd.

3) Configuration and compilation of suspend tools

(a) [optional] If you want to use the compression, encryption and/or
user space splash capabilities of the suspend tools and you have installed 
the necessary packages referred to in subsection 2), you need to set
CONFIG_COMPRESS, CONFIG_ENCRYPT and/or CONFIG_SPLASHY in the Makefile to "yes".

(b) Compile the s2disk and resume binaries by running:

$ make s2disk
$ make resume

in the directory where you have placed the sources.

4) Create the configuration file for the s2disk tool.  Its default name
is /etc/uswsusp.conf, but this can be customized by changing CONFIG_FILE
in config.h.  It is also possible to specify the configuration file name
from the command line, by using the -f option, eg.

# s2disk -f <config_file>

The configuration file must contain the resume device specification, eg.

resume device = /dev/<your_swap_partition>

Optionally, it can contain the snapshot device specification, eg.

snapshot device = /dev/snapshot

and the following parameters:

resume offset = <offset_of_the_swap_header>
image size = <preferred_suspend_image_size_in_bytes>
shutdown method = <reboot, platform>
suspend loglevel = <kernel_console_loglevel_during_suspend>
compute checksum = <y/n>
compress = <y/n>
encrypt = <y/n>
RSA key file = <path>
max loglevel = <ignored>
early writeout = <y/n>
splash = <y/n>

The "resume offset" parameter is necessary if a swap file is used for
suspending.  In such a case the device identified by the "resume device"
parameter is regarded as the partition that contains the swap file, and
"resume offset" must be equal to the offset from the beginning of this
partition at which the swap file's header is located, in <PAGE_SIZE> units.
The value of this parameter for given swap file can be determined by the
swap-offset program (has to be run as root) included in this package.  [For
this feature to work, you will need an -mm kernel, 2.6.18-mm3 or newer.]

The "image size" parameter may be used to limit the size of the system
snapshot image created by the s2disk tool, but it's not mandatory. Namely,
the s2disk tool will do its best to limit the image size as required by
this parameter, but if that's not possible, it will suspend the system anyway,
with a bigger image. If "image size" is set to 0, the snapshot image will be
as small as possible.

The "shutdown method" parameter defines the operation that will be carried out
after the suspend image has been created and the machine is ready to be powered
off.  If it is set to "reboot", the machine will be rebooted immediately.
If it is set to "platform", the machine will be shut down using special
power management operations available from the kernel that may be necessary
for the hardware to be properly reinitialized after the resume, and may cause
the system to resume faster (this is the recommended shutdown method on the
majority of systems).  For any other value the machine will be powered off.
The default is to use the "platform" method.  [For this feature to work,
you will need an -mm kernel, 2.6.18-mm3 or newer.]

If the "compute checksum" parameter is set to 'y', the s2disk and resume
tools will use the MD5 algorithm to verify the image integrity.

If the "compress" parameter is set to 'y', the s2disk and resume tools will
use the LZF compression algorithm to compress/decompress the image.

If the "encrypt" parameter is set to 'y', the s2disk and resume tools will
use the AES encryption algorithm to encrypt/decrypt the image.  If the
"RSA key file" option is also used, the s2disk tool will generate a random
key for the AES encryption that will be passed to the resume tool
within the image header with the help of the RSA cipher.  However, for this
purpose you will need an additional RSA key file the path to which should
be the value of "RSA key file" parameter.  For more details refer to Section
IV ("Advanced encryption") of this document.

If the "early writeout" parameter is set to 'y', the s2disk
utility will start syncing the resume device early in the process of writing
the image to it.  [This has been reported to speed up the suspend on some
boxes and eliminates the "fast progress meter and long fsync wait" effect.]

The "splash" parameter is used to make s2disk and/or resume use a splash system
(when set to 'y').  Currently the bootsplash.org and splashy splash systems
are supported. Note that for both systems your initrd or initramfs will
need additional files. See the documentation of your splash system for
more information.

The resume tool can use the same configuration file that is used by the
s2disk tool, but it will ignore most of the above parameters.  It will use the
value of "suspend loglevel" as the kernel console loglevel during resume.
Additionally it will use the value of "max loglevel" as the kernel console
loglevel to switch to in case the resume fails (this parameter is ignored by
the s2disk tool).

It is not necessary to set "compute checksum = y" and/or "compress = y",
and/or "encrypt = y" for the resume tool.  The appropriate information related
to these options will be passed to it in the image header by the s2disk tool.
However, the resume tool will only use the splash system if "splash = y" is set
for it explicitly.

In order to create the configuration file for s2disk and/or resume, it is
recommended to edit the file uswsusp.conf in the conf/ subdirectory of the
package source.  Then this file will be automatically placed in /etc and
in the resume initrd file by scripts provided in this package.

5) Install s2disk

To install the s2disk tool, run:

# make install-minimal

as root.  This will place the s2disk binary in the destination directory
defined in Makefile (/usr/local/sbin by default).  It will also
create the special device file for the suspend device in /dev, if needed,
and copy the configuration file from the conf/ subdirectory of the source
package to /etc (or somewhere else, depending on the settings in Makefile).
If the configuration file already exists, it will not be overwritten and
a new file with the suffix ".new" appended to its name will be created.

If CONFIG_ENCRYPT is set to "yes" in Makefile, the suspend-keygen tool
used for generating RSA keys for s2disk (see Section IV of this document
for details) will also be built and installed in the destination directory
specified in Makefile (/usr/local/sbin by default).

If you don't want to use "make install-minimal", you can copy the s2disk
binary and the configuration file to wherever you like, but you'll also
need to make sure the snapshot device file is present (if you have set
CONFIG_ENCRYPT=yes in Makefile, you may also need to copy the suspend-keygen
binary to its final destination manually).

You can also use a tool called "checkinstall" to prepare a package file
according to the distribution of your choice (checkinstall supports
Slackware, RPM distributions and DEB distributions).

To download it: http://asic-linux.com.mx/~izto/checkinstall/download.php

To create your package, run "make" and then (as root user) simply
type "checkinstall" and answer the questions. This will not install
anything: instead it will create a package file you can install with rpm,
dpkg or whatever tool your distribution provides.


4) Create snapshot device file

If you don't use "make install-minimal", you may need to create the snapshot
device file:

# mknod /dev/snapshot c 10 231

If the name of this file is equal to SNAPSHOT_DEVICE in swsusp.h, it is not
necessary to specify it in the configuration file.

Now you should be able to use the s2disk tool. It is recommended, however,
to put the tool into a directory located directly on the root filesystem,
for safe testing.

5) Install resume

It is recommended to place the resume tool on an initrd/initramfs image.
For the latter, see instructions for yaird under (6) below.  For an initrd,
this  may be done using "make install-resume-new-initrd", but I'll describe the
full procedure in case you want to do something in a different way.  For
simplicity I will only cover the fastest method of setting it up that will
allow you to get the resume tool up and running quickly.  [The described
procedure reflects the actions performed by "make install-resume-new-initrd".]

(a) Configure the kernel to support RAM disks, initial RAM disks, loopback
block devices, and the ext2 filesystem, and install it as described in 1).

(b) Create the /initrd directory if it doesn't exist already.

(c) Create a blank file, as large as to accommodate all files you'll
be placing on the initrd filesystem.  In the simplest case that will be the
resume tool itself, some directories and some device files.

The resume tool is linked statically, so you won't need any libraries to run it.
On my box the size of it was smaller that 2 MB, so I could do:

$ dd if=/dev/zero of=initrd bs=2000k count=1

(d) Run mke2fs on this file, eg.

$ /sbin/mke2fs -F -m0 initrd

(e) Become root and mount the filesystem, eg.

# mount -t ext2 -o loop initrd /mnt

(f) Create the console device, the snapshot device, and the resume device on it, eg.

# mkdir /mnt/dev
# mknod /mnt/dev/console c 5 1
# mknod /mnt/dev/snapshot c 10 231
# mknod /mnt/dev/hda2 b 3 2

[The initrd filesystem will be mounted as the root filesystem, so the paths
with respect to it must be the same as in your "normal" root filesystem.]

(g) [optional] If you want to use the RSA encryption mechanism described in
Section IV, you'll need to create the random and urandom device files on the
resume initrd:

# mknod /dev/random c 1 8
# mknod /dev/urandom c 1 9

(h) Create the proc and etc directories on it (the resume tool will use them), eg.

# mkdir /mnt/proc
# mkdir /mnt/etc

(i) Copy the resume tool to the initrd filesystem and link it to linuxrc, eg.

# cp resume /mnt/
# cd /mnt
# ln -s resume linuxrc

(j) Put the configuration file for the resume tool in the etc directory on
the initrd filesystem, eg.

# cp /etc/uswsusp.conf /mnt/etc/

(k) Unmount the initrd filesystem and move the file containing it to your /boot
directory, eg.

# umount /mnt
# mv initrd /boot/resume-initrd

(l) In the GRUB configuration file add the initrd to the configuration of the
newly installed kernel, eg.

	initrd (hd0,0)/resume-initrd

(if you use LILO, please refer to its documentation).

(m) If you already have the resume initrd file which is called resume-initrd
and located in the /boot directory, you can install the resume tool on it
by using "make install-resume-on-initrd".

6) Install resume on initramfs with yaird

For an initramfs made by yaird, you can make yaird load the resume binary.
For this purpose, copy install the resume binary in /usr/local/sbin (for
example) and edit /etc/yaird/Templates.cfg to reflect your configuration.
Namely, find "Template RESUME" in there and make it read as follows:
	TEMPLATE resume
	BEGIN
		FILE "/usr/local/sbin/resume"
		FILE "/etc/uswsusp.conf"
		SCRIPT "/init"
		BEGIN
			!if [ -z "$noresume" ]
			!then
			!  # for suspend2 (>= 2.2-rc8)
			!  if [ -w /proc/suspend2/do_resume ]; then
			!    echo > /proc/suspend2/do_resume
			!  fi
			!  # for suspend2 (< 2.2-rc8)
			!  if [ -w /proc/software_suspend/do_resume ]; then
			!    echo > /proc/software_suspend/do_resume
			!  fi
			!  if [ -x /usr/local/sbin/resume ]
			!  then
			!    mkcdev /dev/snapshot misc/snapshot
			!    /usr/local/sbin/resume
			!  fi
Here, the two "FILE" lines and the last if-then statement are new.

Furthermore, yaird needs to know what the resume partition is.  You can either
edit /etc/yaird/Default.cfg and add that to the RESUME goal, or add an option
"resume" to your swap partition in /etc/fstab, as follows
/dev/hda3	none		swap	sw,resume		0	0

With all the above done, run yaird (or if you are a lazy Debian user, just
reinstall linux-image-2.6.17-...).


III. Testing

Before you start using the s2disk and resume tools for real, you should test
your setup.  For this purpose it is recommended to boot the new kernel with
the "init=/bin/bash" command line argument.  Then, the kernel should run bash
instead of init and you should get a (root) command prompt with the root
filesystem mounted read-only and with no other filesystems.

If this happens, mount the sysfs and proc filesystems and enable swap:

# mount /sys
# mount /proc
# swapon -a

Next, go to the directory where the s2disk tool is and do:

# ./s2disk

If this fails, the tool will return to the command prompt with a (hopefully
instructive) message.  Otherwise you should be able to see some messages
from it on the screen and finally the progress meter, and the box should be
powered off.  If that happens, you can start it again and let the resume
utility run from the initrd.  If everything is fine, it will read the image
and restore the system state from it, and you will get the command prompt
back.  If so, your setup works.  Otherwise there's something wrong and you'll
need to find out what and why.

The next step is to check whether your device drivers suspend and resume
correctly.  To do this, it is reasonable to boot the kernel to the runlevel 2
and run the suspend tool.  If it suspends successfully, the resume tool is
able to restore the system memory state, and you get the command prompt back,
the drivers are most probably fine.  Otherwise please report the problem.

Finally, you can start X and try to suspend from an xterm.  If this works,
you're done.


IV. Advanced encryption

If the s2disk and resume tools are compiled with the encryption support, the
RSA cipher may be used to pass the AES encryption key from the s2disk
tool to the resume tool within the suspend image.  This way the s2disk tool
need not ask the user for a passphrase.

For this purpose you need to generate the RSA key pair using the
suspend-keygen tool provided along with the s2disk and resume tools.  The
output file of suspend-keygen should be saved as /etc/uswsusp.key (or
something else pointed to by the "RSA key file =" configuration  parameter of
s2disk).  This file contains the public modulus (n), public exponent (e), the
AES-encrypted private exponent (d), the AES-encrypted primes (p), (q) and
the (AES-encrypted) component (u) of the RSA key pair.  The components (d),
(p), (q), (u) of the RSA key pair are encrypted with a key derived from a
user-provided passphrase.

Then, the s2disk utility will load the contents of this file, generate a random
session key (k) and initialization vector (i) for the image encryption and use
(n, e) to encrypt these values with RSA.  The encrypted (k, i) as well as the
contents of the RSA key file will be saved in the image header.

The resume utility will read (n, e) and (AES-encrypted) (d, p, q, u) as well
as (RSA-encrypted) (k, i) from the image header.  Then it will ask the user
for the passphrase needed to decrypt (d, p, q, u).  Next, if the user provides
the right passphrase, the resume tool will decrypt (k, i) needed for decrypting
the image.