xref: /freebsd/sys/contrib/openzfs/man/man7/dracut.zfs.7 (revision 3e8eb5c7f4909209c042403ddee340b2ee7003a5)
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.service56                                                |
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 dataset") and at the very least either the
75.Sy bootfs
76property to be set to that dataset, or the
77.Sy root=
78kernel cmdline (or dracut drop-in) argument to specify it.
79.Pp
80All children of the boot dataset with
81.Sy canmount Ns = Ns Sy on
82with
83.Sy mountpoint Ns s
84matching
85.Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr
86globs are deemed essential and will be mounted as well.
87.Pp
88.Xr zfs-mount-generator 8
89is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.).
90.
91.Sh CMDLINE
92.Ss Standard
93.Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root="
94.It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset
95Use
96.Ar dataset
97as the boot dataset.
98All pluses
99.Pq Sq +
100are replaced with spaces
101.Pq Sq \  .
102.
103.It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root=
104After import, search for the first pool with the
105.Sy bootfs
106property set, use its value as-if specified as the
107.Ar dataset
108above.
109.
110.It Sy rootfstype=zfs root= Ns Ar dataset
111Equivalent to
112.Sy root=zfs:\& Ns Ar dataset .
113.
114.It Sy rootfstype=zfs Op Sy root=
115Equivalent to
116.Sy root=zfs:AUTO .
117.
118.It Sy rootflags= Ns Ar flags
119Mount the boot dataset with
120.Fl o Ar flags ;
121cf.\&
122.Sx Temporary Mount Point Properties
123in
124.Xr zfsprops 7 .
125These properties will not last, since all filesystems will be re-mounted from the real root.
126.
127.It Sy debug
128If specified,
129.Nm dracut-zfs-generator
130logs to the journal.
131.El
132.Pp
133Be careful about setting neither
134.Sy rootfstype=zfs
135nor
136.Sy root=zfs:\& Ns Ar dataset
137\(em other automatic boot selection methods, like
138.Nm systemd-gpt-auto-generator
139and
140.Nm systemd-fstab-generator
141might take precedent.
142.
143.Ss ZFS-specific
144.Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name"
145.It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name
146Execute
147.Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
148before pivoting to the real root.
149.Ar snapshot-name
150defaults to the current kernel release.
151.
152.It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name
153Execute
154.Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
155before pivoting to the real root.
156.Ar snapshot-name
157defaults to the current kernel release.
158.
159.It Sy spl_hostid= Ns Ar host-id
160Use
161.Xr zgenhostid 8
162to set the host ID to
163.Ar host-id ;
164otherwise,
165.Pa /etc/hostid
166inherited from the real root is used.
167.
168.It Sy zfs_force , zfs.force , zfsforce
169Appends
170.Fl f
171to all
172.Nm zpool Cm import
173invocations; primarily useful in conjunction with
174.Sy spl_hostid= ,
175or if no host ID was inherited.
176.El
177.
178.Sh FILES
179.Bl -tag -width 0
180.It Pa parse-zfs.sh Pq Sy cmdline
181Processes
182.Sy spl_hostid= .
183If
184.Sy root=
185matches a known pattern, above, provides
186.Pa /dev/root
187and delays the initqueue until
188.Xr zfs 4
189is loaded,
190.
191.It Pa zfs-import-opts.sh Pq Nm systemd No environment generator
192Turns
193.Sy zfs_force , zfs.force , No or Sy zfsforce
194into
195.Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f
196for
197.Pa zfs-import-scan.service
198or
199.Pa zfs-import-cache.service .
200.
201.It Pa zfs-load-key.sh Pq Sy pre-mount
202Loads encryption keys for the boot dataset and its essential descendants.
203.Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL"
204.It Sy keylocation Ns = Ns Sy prompt
205Is prompted for via
206.Nm systemd-ask-password
207thrice.
208.
209.It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL
210.Pa network-online.target
211is started before loading.
212.
213.It Sy keylocation Ns = Ns Sy file:// Ns Ar path
214If
215.Ar path
216doesn't exist,
217.Nm udevadm No is Cm settle Ns d .
218If it still doesn't, it's waited for for up to
219.Sy 10 Ns s .
220.El
221.
222.It Pa zfs-env-bootfs.service Pq Nm systemd No service
223After pool import, sets
224.Ev BOOTFS Ns =
225in the systemd environment to the first non-null
226.Sy bootfs
227value in iteration order.
228.
229.It Pa dracut-zfs-generator Pq Nm systemd No generator
230Generates
231.Pa sysroot.mount Pq using Sy rootflags= , No if any .
232If an explicit boot dataset was specified, also generates essential mountpoints
233.Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& ,
234otherwise generates
235.Pa zfs-nonroot-necessities.service
236which mounts them explicitly after
237.Pa /sysroot
238using
239.Ev BOOTFS Ns = .
240.
241.It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services
242Consume
243.Sy bootfs.snapshot
244and
245.Sy bootfs.rollback
246as described in
247.Sx CMDLINE  .
248Use
249.Ev BOOTFS Ns =
250if no explicit boot dataset was specified.
251.
252.It Pa zfs-needshutdown.sh Pq Sy cleanup
253If any pools were imported, signals that shutdown hooks are required.
254.
255.It Pa export-zfs.sh Pq Sy shutdown
256Forcibly exports all pools.
257.
258.It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files
259Included verbatim, hostonly.
260.
261.It Pa mount-zfs.sh Pq Sy mount
262Does nothing on
263.Nm systemd
264systems
265.Pq if Pa dracut-zfs-generator No succeeded .
266Otherwise, loads encryption key for the boot dataset from the console or via plymouth.
267It may not work at all!
268.El
269.
270.Sh SEE ALSO
271.Xr dracut.bootup 7 ,
272.Xr zfsprops 7 ,
273.Xr zpoolprops 7 ,
274.Xr dracut-shutdown.service 8 ,
275.Xr systemd-fstab-generator 8 ,
276.Xr systemd-gpt-auto-generator 8 ,
277.Xr zfs-mount-generator 8 ,
278.Xr zgenhostid 8
279