1 ================================ 1 ================================
2 Early creation of mapped devices 2 Early creation of mapped devices
3 ================================ 3 ================================
4 4
5 It is possible to configure a device-mapper de 5 It is possible to configure a device-mapper device to act as the root device for
6 your system in two ways. 6 your system in two ways.
7 7
8 The first is to build an initial ramdisk which 8 The first is to build an initial ramdisk which boots to a minimal userspace
9 which configures the device, then pivot_root(8 9 which configures the device, then pivot_root(8) in to it.
10 10
11 The second is to create one or more device-map 11 The second is to create one or more device-mappers using the module parameter
12 "dm-mod.create=" through the kernel boot comma 12 "dm-mod.create=" through the kernel boot command line argument.
13 13
14 The format is specified as a string of data se 14 The format is specified as a string of data separated by commas and optionally
15 semi-colons, where: 15 semi-colons, where:
16 16
17 - a comma is used to separate fields like nam 17 - a comma is used to separate fields like name, uuid, flags and table
18 (specifies one device) 18 (specifies one device)
19 - a semi-colon is used to separate devices. 19 - a semi-colon is used to separate devices.
20 20
21 So the format will look like this:: 21 So the format will look like this::
22 22
23 dm-mod.create=<name>,<uuid>,<minor>,<flags>,< 23 dm-mod.create=<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,<minor>,<flags>,<table>[,<table>+]+]
24 24
25 Where:: 25 Where::
26 26
27 <name> ::= The device name. 27 <name> ::= The device name.
28 <uuid> ::= xxxxxxxx-xxxx-xxxx 28 <uuid> ::= xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | ""
29 <minor> ::= The device minor n 29 <minor> ::= The device minor number | ""
30 <flags> ::= "ro" | "rw" 30 <flags> ::= "ro" | "rw"
31 <table> ::= <start_sector> <nu 31 <table> ::= <start_sector> <num_sectors> <target_type> <target_args>
32 <target_type> ::= "verity" | "linear 32 <target_type> ::= "verity" | "linear" | ... (see list below)
33 33
34 The dm line should be equivalent to the one us 34 The dm line should be equivalent to the one used by the dmsetup tool with the
35 `--concise` argument. 35 `--concise` argument.
36 36
37 Target types 37 Target types
38 ============ 38 ============
39 39
40 Not all target types are available as there ar 40 Not all target types are available as there are serious risks in allowing
41 activation of certain DM targets without first 41 activation of certain DM targets without first using userspace tools to check
42 the validity of associated metadata. 42 the validity of associated metadata.
43 43
44 ======================= ====================== 44 ======================= =======================================================
45 `cache` constrained, userspace 45 `cache` constrained, userspace should verify cache device
46 `crypt` allowed 46 `crypt` allowed
47 `delay` allowed 47 `delay` allowed
48 `era` constrained, userspace 48 `era` constrained, userspace should verify metadata device
49 `flakey` constrained, meant for 49 `flakey` constrained, meant for test
50 `linear` allowed 50 `linear` allowed
51 `log-writes` constrained, userspace 51 `log-writes` constrained, userspace should verify metadata device
52 `mirror` constrained, userspace 52 `mirror` constrained, userspace should verify main/mirror device
53 `raid` constrained, userspace 53 `raid` constrained, userspace should verify metadata device
54 `snapshot` constrained, userspace 54 `snapshot` constrained, userspace should verify src/dst device
55 `snapshot-origin` allowed 55 `snapshot-origin` allowed
56 `snapshot-merge` constrained, userspace 56 `snapshot-merge` constrained, userspace should verify src/dst device
57 `striped` allowed 57 `striped` allowed
58 `switch` constrained, userspace 58 `switch` constrained, userspace should verify dev path
59 `thin` constrained, requires 59 `thin` constrained, requires dm target message from userspace
60 `thin-pool` constrained, requires 60 `thin-pool` constrained, requires dm target message from userspace
61 `verity` allowed 61 `verity` allowed
62 `writecache` constrained, userspace 62 `writecache` constrained, userspace should verify cache device
63 `zero` constrained, not meant 63 `zero` constrained, not meant for rootfs
64 ======================= ====================== 64 ======================= =======================================================
65 65
66 If the target is not listed above, it is const 66 If the target is not listed above, it is constrained by default (not tested).
67 67
68 Examples 68 Examples
69 ======== 69 ========
70 An example of booting to a linear array made u 70 An example of booting to a linear array made up of user-mode linux block
71 devices:: 71 devices::
72 72
73 dm-mod.create="lroot,,,rw, 0 4096 linear 98: 73 dm-mod.create="lroot,,,rw, 0 4096 linear 98:16 0, 4096 4096 linear 98:32 0" root=/dev/dm-0
74 74
75 This will boot to a rw dm-linear target of 819 75 This will boot to a rw dm-linear target of 8192 sectors split across two block
76 devices identified by their major:minor number 76 devices identified by their major:minor numbers. After boot, udev will rename
77 this target to /dev/mapper/lroot (depending on 77 this target to /dev/mapper/lroot (depending on the rules). No uuid was assigned.
78 78
79 An example of multiple device-mappers, with th 79 An example of multiple device-mappers, with the dm-mod.create="..." contents
80 is shown here split on multiple lines for read 80 is shown here split on multiple lines for readability::
81 81
82 dm-linear,,1,rw, 82 dm-linear,,1,rw,
83 0 32768 linear 8:1 0, 83 0 32768 linear 8:1 0,
84 32768 1024000 linear 8:2 0; 84 32768 1024000 linear 8:2 0;
85 dm-verity,,3,ro, 85 dm-verity,,3,ro,
86 0 1638400 verity 1 /dev/sdc1 /dev/sdc2 409 86 0 1638400 verity 1 /dev/sdc1 /dev/sdc2 4096 4096 204800 1 sha256
87 ac87db56303c9c1da433d7209b5a6ef3e4779df141 87 ac87db56303c9c1da433d7209b5a6ef3e4779df141200cbd7c157dcb8dd89c42
88 5ebfe87f7df3235b80a117ebc4078e44f55045487a 88 5ebfe87f7df3235b80a117ebc4078e44f55045487ad4a96581d1adb564615b51
89 89
90 Other examples (per target): 90 Other examples (per target):
91 91
92 "crypt":: 92 "crypt"::
93 93
94 dm-crypt,,8,ro, 94 dm-crypt,,8,ro,
95 0 1048576 crypt aes-xts-plain64 95 0 1048576 crypt aes-xts-plain64
96 babebabebabebabebabebabebabebabebabebabeba 96 babebabebabebabebabebabebabebabebabebabebabebabebabebabebabebabe 0
97 /dev/sda 0 1 allow_discards 97 /dev/sda 0 1 allow_discards
98 98
99 "delay":: 99 "delay"::
100 100
101 dm-delay,,4,ro,0 409600 delay /dev/sda1 0 50 101 dm-delay,,4,ro,0 409600 delay /dev/sda1 0 500
102 102
103 "linear":: 103 "linear"::
104 104
105 dm-linear,,,rw, 105 dm-linear,,,rw,
106 0 32768 linear /dev/sda1 0, 106 0 32768 linear /dev/sda1 0,
107 32768 1024000 linear /dev/sda2 0, 107 32768 1024000 linear /dev/sda2 0,
108 1056768 204800 linear /dev/sda3 0, 108 1056768 204800 linear /dev/sda3 0,
109 1261568 512000 linear /dev/sda4 0 109 1261568 512000 linear /dev/sda4 0
110 110
111 "snapshot-origin":: 111 "snapshot-origin"::
112 112
113 dm-snap-orig,,4,ro,0 409600 snapshot-origin 113 dm-snap-orig,,4,ro,0 409600 snapshot-origin 8:2
114 114
115 "striped":: 115 "striped"::
116 116
117 dm-striped,,4,ro,0 1638400 striped 4 4096 117 dm-striped,,4,ro,0 1638400 striped 4 4096
118 /dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda 118 /dev/sda1 0 /dev/sda2 0 /dev/sda3 0 /dev/sda4 0
119 119
120 "verity":: 120 "verity"::
121 121
122 dm-verity,,4,ro, 122 dm-verity,,4,ro,
123 0 1638400 verity 1 8:1 8:2 4096 4096 20480 123 0 1638400 verity 1 8:1 8:2 4096 4096 204800 1 sha256
124 fb1a5a0f00deb908d8b53cb270858975e76cf64105 124 fb1a5a0f00deb908d8b53cb270858975e76cf64105d412ce764225d53b8f3cfd
125 51934789604d1b92399c52e7cb149d1b3a1b74bbbc 125 51934789604d1b92399c52e7cb149d1b3a1b74bbbcb103b2a0aaacbed5c08584
126 <<
127 For setups using device-mapper on top of async <<
128 devices (MMC, USB, ..), it may be necessary to <<
129 explicitly wait for them to become available b <<
130 device-mapper tables. This can be done with th <<
131 module parameter, which takes a list of device <<
132 <<
133 dm-mod.waitfor=<device1>[,..,<deviceN>] <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.