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