1.\" SPDX-License-Identifier: 0BSD
2.\"
3.Dd April 4, 2022
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
22zfs-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\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em dracut-zfs-generator
34                        |                       |                                        \(da   |
35                        |                       \(da            sysroot-{usr,etc,lib,&c.}.mount |
36                        |             initrd-root-fs.target \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em or                 \(da
37                        |                       |              zfs-nonroot-necessities.service
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.mount \(<-\(em\(em\(em\(em\(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
61Compare
62.Xr dracut.bootup 7
63for the full flowchart.
64.
65.Sh DESCRIPTION
66Under dracut, booting with
67.No ZFS-on- Ns Pa /
68is facilitated by a number of hooks in the
69.Nm 90zfs
70module.
71.Pp
72Booting into a ZFS dataset requires
73.Sy mountpoint Ns = Ns Pa /
74to be set on the dataset containing the root filesystem (henceforth "the boot
75dataset") and at the very least either the
76.Sy bootfs
77property to be set to that dataset, or the
78.Sy root=
79kernel cmdline (or dracut drop-in) argument to specify it.
80.Pp
81All children of the boot dataset with
82.Sy canmount Ns = Ns Sy on
83with
84.Sy mountpoint Ns s
85matching
86.Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr
87globs are deemed essential and will be mounted as well.
88.Pp
89.Xr zfs-mount-generator 8
90is recommended for proper functioning of the system afterward (correct mount
91properties, 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
97Use
98.Ar dataset
99as the boot dataset.
100All pluses
101.Pq Sq +
102are replaced with spaces
103.Pq Sq \  .
104.
105.It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root=
106After import, search for the first pool with the
107.Sy bootfs
108property set, use its value as-if specified as the
109.Ar dataset
110above.
111.
112.It Sy rootfstype=zfs root= Ns Ar dataset
113Equivalent to
114.Sy root=zfs:\& Ns Ar dataset .
115.
116.It Sy rootfstype=zfs Op Sy root=
117Equivalent to
118.Sy root=zfs:AUTO .
119.
120.It Sy rootflags= Ns Ar flags
121Mount the boot dataset with
122.Fl o Ar flags ;
123cf.\&
124.Sx Temporary Mount Point Properties
125in
126.Xr zfsprops 7 .
127These properties will not last, since all filesystems will be re-mounted from
128the real root.
129.
130.It Sy debug
131If specified,
132.Nm dracut-zfs-generator
133logs to the journal.
134.El
135.Pp
136Be careful about setting neither
137.Sy rootfstype=zfs
138nor
139.Sy root=zfs:\& Ns Ar dataset
140\(em other automatic boot selection methods, like
141.Nm systemd-gpt-auto-generator
142and
143.Nm systemd-fstab-generator
144might 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
149Execute
150.Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
151before pivoting to the real root.
152.Ar snapshot-name
153defaults to the current kernel release.
154.
155.It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name
156Execute
157.Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
158before pivoting to the real root.
159.Ar snapshot-name
160defaults to the current kernel release.
161.
162.It Sy spl_hostid= Ns Ar host-id
163Use
164.Xr zgenhostid 8
165to set the host ID to
166.Ar host-id ;
167otherwise,
168.Pa /etc/hostid
169inherited from the real root is used.
170.
171.It Sy zfs_force , zfs.force , zfsforce
172Appends
173.Fl f
174to all
175.Nm zpool Cm import
176invocations; primarily useful in conjunction with
177.Sy spl_hostid= ,
178or 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
184Processes
185.Sy spl_hostid= .
186If
187.Sy root=
188matches a known pattern, above, provides
189.Pa /dev/root
190and delays the initqueue until
191.Xr zfs 4
192is loaded,
193.
194.It Pa zfs-import-opts.sh Pq Nm systemd No environment generator
195Turns
196.Sy zfs_force , zfs.force , No or Sy zfsforce
197into
198.Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f
199for
200.Pa zfs-import-scan.service
201or
202.Pa zfs-import-cache.service .
203.
204.It Pa zfs-load-key.sh Pq Sy pre-mount
205Loads 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
208Is prompted for via
209.Nm systemd-ask-password
210thrice.
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
214is started before loading.
215.
216.It Sy keylocation Ns = Ns Sy file:// Ns Ar path
217If
218.Ar path
219doesn't exist,
220.Nm udevadm No is Cm settle Ns d .
221If 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
226After pool import, sets
227.Ev BOOTFS Ns =
228in the systemd environment to the first non-null
229.Sy bootfs
230value in iteration order.
231.
232.It Pa dracut-zfs-generator Pq Nm systemd No generator
233Generates
234.Pa sysroot.mount Pq using Sy rootflags= , No if any .
235If an explicit boot dataset was specified, also generates essential mountpoints
236.Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& ,
237otherwise generates
238.Pa zfs-nonroot-necessities.service
239which mounts them explicitly after
240.Pa /sysroot
241using
242.Ev BOOTFS Ns = .
243.
244.It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services
245Consume
246.Sy bootfs.snapshot
247and
248.Sy bootfs.rollback
249as described in
250.Sx CMDLINE  .
251Use
252.Ev BOOTFS Ns =
253if no explicit boot dataset was specified.
254.
255.It Pa zfs-needshutdown.sh Pq Sy cleanup
256If any pools were imported, signals that shutdown hooks are required.
257.
258.It Pa export-zfs.sh Pq Sy shutdown
259Forcibly exports all pools.
260.
261.It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files
262Included verbatim, hostonly.
263.
264.It Pa mount-zfs.sh Pq Sy mount
265Does nothing on
266.Nm systemd
267systems
268.Pq if Pa dracut-zfs-generator No succeeded .
269Otherwise, loads encryption key for the boot dataset from the console or via
270plymouth.
271It 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
283