man/man8/zfs-mount-generator.8.in

   1 .\"
   2 .\" Copyright 2018 Antonio Russo <antonio.e.russo@gmail.com>
   3 .\" Copyright 2019 Kjeld Schouten-Lebbing <kjeld@schouten-lebbing.nl>
   4 .\" Copyright 2020 InsanePrawn <insane.prawny@gmail.com>
   5 .\"
   6 .\" Permission is hereby granted, free of charge, to any person obtaining
   7 .\" a copy of this software and associated documentation files (the
   8 .\" "Software"), to deal in the Software without restriction, including
   9 .\" without limitation the rights to use, copy, modify, merge, publish,
  10 .\" distribute, sublicense, and/or sell copies of the Software, and to
  11 .\" permit persons to whom the Software is furnished to do so, subject to
  12 .\" the following conditions:
  13 .\"
  14 .\" The above copyright notice and this permission notice shall be
  15 .\" included in all copies or substantial portions of the Software.
  16 .\"
  17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  18 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  20 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  21 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  22 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  23 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  24
  25 .TH "ZFS\-MOUNT\-GENERATOR" "8" "2020-01-19" "ZFS" "zfs-mount-generator" "\""
  26
  27 .SH "NAME"
  28 zfs\-mount\-generator \- generates systemd mount units for ZFS
  29 .SH SYNOPSIS
  30 .B @systemdgeneratordir@/zfs\-mount\-generator
  31 .sp
  32 .SH DESCRIPTION
  33 zfs\-mount\-generator implements the \fBGenerators Specification\fP
  34 of
  35 .BR systemd (1),
  36 and is called during early boot to generate
  37 .BR systemd.mount (5)
  38 units for automatically mounted datasets. Mount ordering and dependencies
  39 are created for all tracked pools (see below).
  40
  41 .SS ENCRYPTION KEYS
  42 If the dataset is an encryption root, a service that loads the associated key (either from file or through a
  43 .BR systemd\-ask\-password (1)
  44 prompt) will be created. This service
  45 . BR RequiresMountsFor
  46 the path of the key (if file-based) and also copies the mount unit's
  47 .BR After ,
  48 .BR Before
  49 and
  50 .BR Requires .
  51 All mount units of encrypted datasets add the key\-load service for their encryption root to their
  52 .BR Wants
  53 and
  54 .BR After .
  55 The service will not be
  56 .BR Want ed
  57 or
  58 .BR Require d
  59 by
  60 .BR local-fs.target
  61 directly, and so will only be started manually or as a dependency of a started mount unit.
  62
  63 .SS UNIT ORDERING AND DEPENDENCIES
  64 mount unit's
  65 .BR Before
  66 \->
  67 key\-load service (if any)
  68 \->
  69 mount unit
  70 \->
  71 mount unit's
  72 .BR After
  73
  74 It is worth nothing that when a mount unit is activated, it activates all available mount units for parent paths to its mountpoint, i.e. activating the mount unit for /tmp/foo/1/2/3 automatically activates all available mount units for /tmp, /tmp/foo, /tmp/foo/1, and /tmp/foo/1/2. This is true for any combination of mount units from any sources, not just ZFS.
  75
  76 .SS CACHE FILE
  77 Because ZFS pools may not be available very early in the boot process,
  78 information on ZFS mountpoints must be stored separately. The output of the command
  79 .PP
  80 .RS 4
  81 zfs list -H -o name,mountpoint,canmount,atime,relatime,devices,exec,readonly,setuid,nbmand,encroot,keylocation,org.openzfs.systemd:requires,org.openzfs.systemd:requires-mounts-for,org.openzfs.systemd:before,org.openzfs.systemd:after,org.openzfs.systemd:wanted-by,org.openzfs.systemd:required-by,org.openzfs.systemd:nofail,org.openzfs.systemd:ignore
  82
  83 .RE
  84 .PP
  85 for datasets that should be mounted by systemd, should be kept
  86 separate from the pool, at
  87 .PP
  88 .RS 4
  89 .RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME
  90 .
  91 .RE
  92 .PP
  93 The cache file, if writeable, will be kept synchronized with the pool
  94 state by the ZEDLET
  95 .PP
  96 .RS 4
  97 history_event-zfs-list-cacher.sh .
  98 .RE
  99 .PP
 100 .sp
 101 .SS PROPERTIES
 102 The behavior of the generator script can be influenced by the following dataset properties:
 103 .sp
 104 .TP 4
 105 .BR canmount = on | off | noauto
 106 If a dataset has
 107 .BR mountpoint
 108 set and
 109 .BR canmount
 110 is not
 111 .BR off ,
 112 a mount unit will be generated.
 113 Additionally, if
 114 .BR canmount
 115 is
 116 .BR on ,
 117 .BR local-fs.target
 118 will gain a dependency on the mount unit.
 119
 120 This behavior is equal to the
 121 .BR auto
 122 and
 123 .BR noauto
 124 legacy mount options, see
 125 .BR systemd.mount (5).
 126
 127 Encryption roots always generate a key-load service, even for
 128 .BR canmount=off .
 129 .TP 4
 130 .BR org.openzfs.systemd:requires\-mounts\-for = \fIpath\fR...
 131 Space\-separated list of mountpoints to require to be mounted for this mount unit
 132 .TP 4
 133 .BR org.openzfs.systemd:before = \fIunit\fR...
 134 The mount unit and associated key\-load service will be ordered before this space\-separated list of units.
 135 .TP 4
 136 .BR org.openzfs.systemd:after = \fIunit\fR...
 137 The mount unit and associated key\-load service will be ordered after this space\-separated list of units.
 138 .TP 4
 139 .BR org.openzfs.systemd:wanted\-by = \fIunit\fR...
 140 Space-separated list of units that will gain a
 141 .BR Wants
 142 dependency on this mount unit.
 143 Setting this property implies
 144 .BR noauto .
 145 .TP 4
 146 .BR org.openzfs.systemd:required\-by = \fIunit\fR...
 147 Space-separated list of units that will gain a
 148 .BR Requires
 149 dependency on this mount unit.
 150 Setting this property implies
 151 .BR noauto .
 152 .TP 4
 153 .BR org.openzfs.systemd:nofail = unset | on | off
 154 Toggles between a
 155 .BR Wants
 156 and
 157 .BR Requires
 158 type of dependency between the mount unit and
 159 .BR local-fs.target ,
 160 if
 161 .BR noauto
 162 isn't set or implied.
 163
 164 .BR on :
 165 Mount will be
 166 .BR WantedBy
 167 local-fs.target
 168
 169 .BR off :
 170 Mount will be
 171 .BR Before
 172 and
 173 .BR RequiredBy
 174 local-fs.target
 175
 176 .BR unset :
 177 Mount will be
 178 .BR Before
 179 and
 180 .BR WantedBy
 181 local-fs.target
 182 .TP 4
 183 .BR org.openzfs.systemd:ignore = on | off
 184 If set to
 185 .BR on ,
 186 do not generate a mount unit for this dataset.
 187
 188 .RE
 189 See also
 190 .BR systemd.mount (5)
 191
 192 .PP
 193 .SH EXAMPLE
 194 To begin, enable tracking for the pool:
 195 .PP
 196 .RS 4
 197 touch
 198 .RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME
 199 .RE
 200 .PP
 201 Then, enable the tracking ZEDLET:
 202 .PP
 203 .RS 4
 204 ln -s "@zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh" "@sysconfdir@/zfs/zed.d"
 205
 206 systemctl enable zfs-zed.service
 207
 208 systemctl restart zfs-zed.service
 209 .RE
 210 .PP
 211 Force the running of the ZEDLET by setting a monitored property, e.g.
 212 .BR canmount ,
 213 for at least one dataset in the pool:
 214 .PP
 215 .RS 4
 216 zfs set canmount=on
 217 .I DATASET
 218 .RE
 219 .PP
 220 This forces an update to the stale cache file.
 221
 222 To test the generator output, run
 223 .PP
 224 .RS 4
 225 @systemdgeneratordir@/zfs-mount-generator /tmp/zfs-mount-generator . .
 226 .RE
 227 .PP
 228 This will generate units and dependencies in
 229 .I /tmp/zfs-mount-generator
 230 for you to inspect them. The second and third argument are ignored.
 231
 232 If you're satisfied with the generated units, instruct systemd to re-run all generators:
 233 .PP
 234 .RS 4
 235 systemctl daemon-reload
 236 .RE
 237 .PP
 238
 239 .sp
 240 .SH SEE ALSO
 241 .BR zfs (5)
 242 .BR zfs-events (5)
 243 .BR zed (8)
 244 .BR zpool (5)
 245 .BR systemd (1)
 246 .BR systemd.target (5)
 247 .BR systemd.special (7)
 248 .BR systemd.mount (7)