| blob | b67e1cecb24086ac3461a7be08d4660cc09288d8 |
1 .\" SPDX-License-Identifier: 0BSD
2 .\"
3 .Dd March 28, 2023
4 .Dt DRACUT.ZFS 7
5 .Os
6 .
7 .Sh NAME
8 .Nm dracut.zfs
9 .Nd overview of ZFS dracut hooks
10 .
11 .Sh SYNOPSIS
12 .Bd -literal -compact
13 parse-zfs.sh \(-> dracut-cmdline.service
14 | \(da
15 | …
16 | \(da
17 \e\(em\(em\(em\(em\(em\(em\(em\(em\(-> dracut-initqueue.service
18 | zfs-import-opts.sh
19 zfs-load-module.service \(da | |
20 | | sysinit.target \(da |
21 \(da | | zfs-import-scan.service \(da
22 zfs-import-scan.service \(da \(da | zfs-import-cache.service
23 | zfs-import-cache.service basic.target | |
24 \e__________________| | \(da \(da
25 \(da | zfs-load-key.sh
26 zfs-env-bootfs.service | |
27 \(da \(da \(da
28 zfs-import.target \(-> dracut-pre-mount.service
29 | \(ua |
30 | dracut-zfs-generator |
31 | _____________________/|
32 |/ \(da
33 | sysroot.mount \(<-\(em\(em\(em dracut-zfs-generator
34 | |
35 | \(da
36 | initrd-root-fs.target \(<-\(em zfs-nonroot-necessities.service
37 | | |
38 | \(da |
39 \(da dracut-mount.service |
40 zfs-snapshot-bootfs.service | |
41 | \(da |
42 \(da … |
43 zfs-rollback-bootfs.service | |
44 | \(da |
45 | /sysroot/{usr,etc,lib,&c.} \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em/
46 | |
47 | \(da
48 | initrd-fs.target
49 \e______________________ |
50 \e|
51 \(da
52 export-zfs.sh initrd.target
53 | |
54 \(da \(da
55 dracut-shutdown.service …
56 |
57 \(da
58 zfs-needshutdown.sh \(-> initrd-cleanup.service
59 .Ed
60 .Pp
61 Compare
62 .Xr dracut.bootup 7
63 for the full flowchart.
64 .
65 .Sh DESCRIPTION
66 Under dracut, booting with
67 .No ZFS-on- Ns Pa /
68 is facilitated by a number of hooks in the
69 .Nm 90zfs
70 module.
71 .Pp
72 Booting into a ZFS dataset requires
73 .Sy mountpoint Ns = Ns Pa /
74 to be set on the dataset containing the root filesystem (henceforth "the boot
75 dataset") and at the very least either the
76 .Sy bootfs
77 property to be set to that dataset, or the
78 .Sy root=
79 kernel cmdline (or dracut drop-in) argument to specify it.
80 .Pp
81 All children of the boot dataset with
82 .Sy canmount Ns = Ns Sy on
83 with
84 .Sy mountpoint Ns s
85 matching
86 .Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr
87 globs are deemed essential and will be mounted as well.
88 .Pp
89 .Xr zfs-mount-generator 8
90 is recommended for proper functioning of the system afterward (correct mount
91 properties, remounting, &c.).
92 .
93 .Sh CMDLINE
94 .Ss Standard
95 .Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root="
96 .It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset
97 Use
98 .Ar dataset
99 as the boot dataset.
100 All pluses
101 .Pq Sq +
102 are replaced with spaces
103 .Pq Sq \ .
104 .
105 .It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root=
106 After import, search for the first pool with the
107 .Sy bootfs
108 property set, use its value as-if specified as the
109 .Ar dataset
110 above.
111 .
112 .It Sy rootfstype=zfs root= Ns Ar dataset
113 Equivalent to
114 .Sy root=zfs:\& Ns Ar dataset .
115 .
116 .It Sy rootfstype=zfs Op Sy root=
117 Equivalent to
118 .Sy root=zfs:AUTO .
119 .
120 .It Sy rootflags= Ns Ar flags
121 Mount the boot dataset with
122 .Fl o Ar flags ;
123 cf.\&
124 .Sx Temporary Mount Point Properties
125 in
126 .Xr zfsprops 7 .
127 These properties will not last, since all filesystems will be re-mounted from
128 the real root.
129 .
130 .It Sy debug
131 If specified,
132 .Nm dracut-zfs-generator
133 logs to the journal.
134 .El
135 .Pp
136 Be careful about setting neither
137 .Sy rootfstype=zfs
138 nor
139 .Sy root=zfs:\& Ns Ar dataset
140 \(em other automatic boot selection methods, like
141 .Nm systemd-gpt-auto-generator
142 and
143 .Nm systemd-fstab-generator
144 might take precedent.
145 .
146 .Ss ZFS-specific
147 .Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name"
148 .It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name
149 Execute
150 .Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
151 before pivoting to the real root.
152 .Ar snapshot-name
153 defaults to the current kernel release.
154 .
155 .It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name
156 Execute
157 .Nm zfs Cm rollback Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
158 before pivoting to the real root.
159 .Ar snapshot-name
160 defaults to the current kernel release.
161 .
162 .It Sy spl_hostid= Ns Ar host-id
163 Use
164 .Xr zgenhostid 8
165 to set the host ID to
166 .Ar host-id ;
167 otherwise,
168 .Pa /etc/hostid
169 inherited from the real root is used.
170 .
171 .It Sy zfs_force , zfs.force , zfsforce
172 Appends
173 .Fl f
174 to all
175 .Nm zpool Cm import
176 invocations; primarily useful in conjunction with
177 .Sy spl_hostid= ,
178 or if no host ID was inherited.
179 .El
180 .
181 .Sh FILES
182 .Bl -tag -width 0
183 .It Pa parse-zfs.sh Pq Sy cmdline
184 Processes
185 .Sy spl_hostid= .
186 If
187 .Sy root=
188 matches a known pattern, above, provides
189 .Pa /dev/root
190 and delays the initqueue until
191 .Xr zfs 4
192 is loaded,
193 .
194 .It Pa zfs-import-opts.sh Pq Nm systemd No environment generator
195 Turns
196 .Sy zfs_force , zfs.force , No or Sy zfsforce
197 into
198 .Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f
199 for
200 .Pa zfs-import-scan.service
201 or
202 .Pa zfs-import-cache.service .
203 .
204 .It Pa zfs-load-key.sh Pq Sy pre-mount
205 Loads encryption keys for the boot dataset and its essential descendants.
206 .Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL"
207 .It Sy keylocation Ns = Ns Sy prompt
208 Is prompted for via
209 .Nm systemd-ask-password
210 thrice.
211 .
212 .It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL
213 .Pa network-online.target
214 is started before loading.
215 .
216 .It Sy keylocation Ns = Ns Sy file:// Ns Ar path
217 If
218 .Ar path
219 doesn't exist,
220 .Nm udevadm No is Cm settle Ns d .
221 If it still doesn't, it's waited for for up to
222 .Sy 10 Ns s .
223 .El
224 .
225 .It Pa zfs-env-bootfs.service Pq Nm systemd No service
226 After pool import, sets
227 .Ev BOOTFS Ns =
228 in the systemd environment to the first non-null
229 .Sy bootfs
230 value in iteration order.
231 .
232 .It Pa dracut-zfs-generator Pq Nm systemd No generator
233 Generates
234 .Pa sysroot.mount Pq using Sy rootflags= , No if any .
235 If an explicit boot dataset was specified, also generates essential mountpoints
236 .Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& ,
237 otherwise generates
238 .Pa zfs-nonroot-necessities.service
239 which mounts them explicitly after
240 .Pa /sysroot
241 using
242 .Ev BOOTFS Ns = .
243 .
244 .It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services
245 Consume
246 .Sy bootfs.snapshot
247 and
248 .Sy bootfs.rollback
249 as described in
250 .Sx CMDLINE .
251 Use
252 .Ev BOOTFS Ns =
253 if no explicit boot dataset was specified.
254 .
255 .It Pa zfs-needshutdown.sh Pq Sy cleanup
256 If any pools were imported, signals that shutdown hooks are required.
257 .
258 .It Pa export-zfs.sh Pq Sy shutdown
259 Forcibly exports all pools.
260 .
261 .It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files
262 Included verbatim, hostonly.
263 .
264 .It Pa mount-zfs.sh Pq Sy mount
265 Does nothing on
266 .Nm systemd
267 systems
268 .Pq if Pa dracut-zfs-generator No succeeded .
269 Otherwise, loads encryption key for the boot dataset from the console or via
270 plymouth.
271 It may not work at all!
272 .El
273 .
274 .Sh SEE ALSO
275 .Xr dracut.bootup 7 ,
276 .Xr zfsprops 7 ,
277 .Xr zpoolprops 7 ,
278 .Xr dracut-shutdown.service 8 ,
279 .Xr systemd-fstab-generator 8 ,
280 .Xr systemd-gpt-auto-generator 8 ,
281 .Xr zfs-mount-generator 8 ,
282 .Xr zgenhostid 8