treewide: remove redundant IS_ERR() before error code check
[linux/fpc-iii.git] / Documentation / power / swsusp-dmcrypt.rst
blob426df59172cdab6fab7036ca7098396c113354c3
1 =======================================
2 How to use dm-crypt and swsusp together
3 =======================================
5 Author: Andreas Steinmetz <ast@domdv.de>
9 Some prerequisites:
10 You know how dm-crypt works. If not, visit the following web page:
11 http://www.saout.de/misc/dm-crypt/
12 You have read Documentation/power/swsusp.rst and understand it.
13 You did read Documentation/admin-guide/initrd.rst and know how an initrd works.
14 You know how to create or how to modify an initrd.
16 Now your system is properly set up, your disk is encrypted except for
17 the swap device(s) and the boot partition which may contain a mini
18 system for crypto setup and/or rescue purposes. You may even have
19 an initrd that does your current crypto setup already.
21 At this point you want to encrypt your swap, too. Still you want to
22 be able to suspend using swsusp. This, however, means that you
23 have to be able to either enter a passphrase or that you read
24 the key(s) from an external device like a pcmcia flash disk
25 or an usb stick prior to resume. So you need an initrd, that sets
26 up dm-crypt and then asks swsusp to resume from the encrypted
27 swap device.
29 The most important thing is that you set up dm-crypt in such
30 a way that the swap device you suspend to/resume from has
31 always the same major/minor within the initrd as well as
32 within your running system. The easiest way to achieve this is
33 to always set up this swap device first with dmsetup, so that
34 it will always look like the following::
36   brw-------  1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
38 Now set up your kernel to use /dev/mapper/swap0 as the default
39 resume partition, so your kernel .config contains::
41   CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
43 Prepare your boot loader to use the initrd you will create or
44 modify. For lilo the simplest setup looks like the following
45 lines::
47   image=/boot/vmlinuz
48   initrd=/boot/initrd.gz
49   label=linux
50   append="root=/dev/ram0 init=/linuxrc rw"
52 Finally you need to create or modify your initrd. Lets assume
53 you create an initrd that reads the required dm-crypt setup
54 from a pcmcia flash disk card. The card is formatted with an ext2
55 fs which resides on /dev/hde1 when the card is inserted. The
56 card contains at least the encrypted swap setup in a file
57 named "swapkey". /etc/fstab of your initrd contains something
58 like the following::
60   /dev/hda1   /mnt    ext3      ro                            0 0
61   none        /proc   proc      defaults,noatime,nodiratime   0 0
62   none        /sys    sysfs     defaults,noatime,nodiratime   0 0
64 /dev/hda1 contains an unencrypted mini system that sets up all
65 of your crypto devices, again by reading the setup from the
66 pcmcia flash disk. What follows now is a /linuxrc for your
67 initrd that allows you to resume from encrypted swap and that
68 continues boot with your mini system on /dev/hda1 if resume
69 does not happen::
71   #!/bin/sh
72   PATH=/sbin:/bin:/usr/sbin:/usr/bin
73   mount /proc
74   mount /sys
75   mapped=0
76   noresume=`grep -c noresume /proc/cmdline`
77   if [ "$*" != "" ]
78   then
79     noresume=1
80   fi
81   dmesg -n 1
82   /sbin/cardmgr -q
83   for i in 1 2 3 4 5 6 7 8 9 0
84   do
85     if [ -f /proc/ide/hde/media ]
86     then
87       usleep 500000
88       mount -t ext2 -o ro /dev/hde1 /mnt
89       if [ -f /mnt/swapkey ]
90       then
91         dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
92       fi
93       umount /mnt
94       break
95     fi
96     usleep 500000
97   done
98   killproc /sbin/cardmgr
99   dmesg -n 6
100   if [ $mapped = 1 ]
101   then
102     if [ $noresume != 0 ]
103     then
104       mkswap /dev/mapper/swap0 > /dev/null 2>&1
105     fi
106     echo 254:0 > /sys/power/resume
107     dmsetup remove swap0
108   fi
109   umount /sys
110   mount /mnt
111   umount /proc
112   cd /mnt
113   pivot_root . mnt
114   mount /proc
115   umount -l /mnt
116   umount /proc
117   exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
119 Please don't mind the weird loop above, busybox's msh doesn't know
120 the let statement. Now, what is happening in the script?
121 First we have to decide if we want to try to resume, or not.
122 We will not resume if booting with "noresume" or any parameters
123 for init like "single" or "emergency" as boot parameters.
125 Then we need to set up dmcrypt with the setup data from the
126 pcmcia flash disk. If this succeeds we need to reset the swap
127 device if we don't want to resume. The line "echo 254:0 > /sys/power/resume"
128 then attempts to resume from the first device mapper device.
129 Note that it is important to set the device in /sys/power/resume,
130 regardless if resuming or not, otherwise later suspend will fail.
131 If resume starts, script execution terminates here.
133 Otherwise we just remove the encrypted swap device and leave it to the
134 mini system on /dev/hda1 to set the whole crypto up (it is up to
135 you to modify this to your taste).
137 What then follows is the well known process to change the root
138 file system and continue booting from there. I prefer to unmount
139 the initrd prior to continue booting but it is up to you to modify
140 this.