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 .Dd May 31, 2021
  26 .Dt ZFS-MOUNT-GENERATOR 8
  27 .Os
  28 .
  29 .Sh NAME
  30 .Nm zfs-mount-generator
  31 .Nd generate systemd mount units for ZFS filesystems
  32 .Sh SYNOPSIS
  33 .Pa @systemdgeneratordir@/zfs-mount-generator
  34 .
  35 .Sh DESCRIPTION
  36 .Nm
  37 is a
  38 .Xr systemd.generator 7
  39 that generates native
  40 .Xr systemd.mount 5
  41 units for configured ZFS datasets.
  42 .
  43 .Ss Properties
  44 .Bl -tag -compact -width "org.openzfs.systemd:required-by=unit[ unit]…"
  45 .It Sy mountpoint Ns =
  46 .No Skipped if Sy legacy No or Sy none .
  47 .
  48 .It Sy canmount Ns =
  49 .No Skipped if Sy off .
  50 .No Skipped if only Sy noauto
  51 datasets exist for a given mountpoint and there's more than one.
  52 .No Datasets with Sy yes No take precedence over ones with Sy noauto No for the same mountpoint .
  53 .No Sets logical Em noauto No flag if Sy noauto .
  54 Encryption roots always generate
  55 .Sy zfs-load-key@ Ns Ar root Ns Sy .service ,
  56 even if
  57 .Sy off .
  58 .
  59 .It Sy atime Ns = , Sy relatime Ns = , Sy devices Ns = , Sy exec Ns = , Sy readonly Ns = , Sy setuid Ns = , Sy nbmand Ns =
  60 Used to generate mount options equivalent to
  61 .Nm zfs Cm mount .
  62 .
  63 .It Sy encroot Ns = , Sy keylocation Ns =
  64 If the dataset is an encryption root, its mount unit will bind to
  65 .Sy zfs-load-key@ Ns Ar root Ns Sy .service ,
  66 with additional dependencies as follows:
  67 .Bl -tag -compact -offset Ds -width "keylocation=https://URL (et al.)"
  68 .It Sy keylocation Ns = Ns Sy prompt
  69 None, uses
  70 .Xr systemd-ask-password 1
  71 .It Sy keylocation Ns = Ns Sy https:// Ns Ar URL Pq et al.\&
  72 .Sy Wants Ns = , Sy After Ns = : Pa network-online.target
  73 .It Sy keylocation Ns = Ns Sy file:// Ns < Ns Ar path Ns >
  74 .Sy RequiresMountsFor Ns = Ns Ar path
  75 .El
  76 .
  77 The service also uses the same
  78 .Sy Wants Ns = ,
  79 .Sy After Ns = ,
  80 .Sy Requires Ns = , No and
  81 .Sy RequiresMountsFor Ns = ,
  82 as the mount unit.
  83 .
  84 .It Sy org.openzfs.systemd:requires Ns = Ns Pa path Ns Oo " " Ns Pa path Oc Ns …
  85 .No Sets Sy Requires Ns = for the mount- and key-loading unit.
  86 .
  87 .It Sy org.openzfs.systemd:requires-mounts-for Ns = Ns Pa path Ns Oo " " Ns Pa path Oc Ns …
  88 .No Sets Sy RequiresMountsFor Ns = for the mount- and key-loading unit.
  89 .
  90 .It Sy org.openzfs.systemd:before Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
  91 .No Sets Sy Before Ns = for the mount unit.
  92 .
  93 .It Sy org.openzfs.systemd:after Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
  94 .No Sets Sy After Ns = for the mount unit.
  95 .
  96 .It Sy org.openzfs.systemd:wanted-by Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
  97 .No Sets logical Em noauto No flag (see below) .
  98 .No If not Sy none , No sets Sy WantedBy Ns = for the mount unit.
  99 .It Sy org.openzfs.systemd:required-by Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
 100 .No Sets logical Em noauto No flag (see below) .
 101 .No If not Sy none , No sets Sy RequiredBy Ns = for the mount unit.
 102 .
 103 .It Sy org.openzfs.systemd:nofail Ns = Ns (unset) Ns | Ns Sy on Ns | Ns Sy off
 104 Waxes or wanes strength of default reverse dependencies of the mount unit, see
 105 below.
 106 .
 107 .It Sy org.openzfs.systemd:ignore Ns = Ns Sy on Ns | Ns Sy off
 108 .No Skip if Sy on .
 109 .No Defaults to Sy off .
 110 .El
 111 .
 112 .Ss Unit Ordering And Dependencies
 113 Additionally, unless the pool the dataset resides on
 114 is imported at generation time, both units gain
 115 .Sy Wants Ns = Ns Pa zfs-import.target
 116 and
 117 .Sy After Ns = Ns Pa zfs-import.target .
 118 .Pp
 119 Additionally, unless the logical
 120 .Em noauto
 121 flag is set, the mount unit gains a reverse-dependency for
 122 .Pa local-fs.target
 123 of strength
 124 .Bl -tag -compact -offset Ds -width "(unset)"
 125 .It (unset)
 126 .Sy WantedBy Ns = No + Sy Before Ns =
 127 .It Sy on
 128 .Sy WantedBy Ns =
 129 .It Sy off
 130 .Sy RequiredBy Ns = No + Sy Before Ns =
 131 .El
 132 .
 133 .Ss Cache File
 134 Because ZFS pools may not be available very early in the boot process,
 135 information on ZFS mountpoints must be stored separately.
 136 The output of
 137 .Dl Nm zfs Cm list Fl Ho Ar name , Ns Aq every property above in order
 138 for datasets that should be mounted by systemd should be kept at
 139 .Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname ,
 140 and, if writeable, will be kept synchronized for the entire pool by the
 141 .Pa history_event-zfs-list-cacher.sh
 142 ZEDLET, if enabled
 143 .Pq see Xr zed 8 .
 144 .
 145 .Sh ENVIRONMENT
 146 If the
 147 .Sy ZFS_DEBUG
 148 environment variable is nonzero
 149 .Pq or unset and Pa /proc/cmdline No contains Qq Sy debug ,
 150 print summary accounting information at the end.
 151 .
 152 .Sh EXAMPLES
 153 To begin, enable tracking for the pool:
 154 .Dl # Nm touch Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname
 155 Then enable the tracking ZEDLET:
 156 .Dl # Nm ln Fl s Pa @zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh @sysconfdir@/zfs/zed.d
 157 .Dl # Nm systemctl Cm enable Pa zfs-zed.service
 158 .Dl # Nm systemctl Cm restart Pa zfs-zed.service
 159 .Pp
 160 If no history event is in the queue,
 161 inject one to ensure the ZEDLET runs to refresh the cache file
 162 by setting a monitored property somewhere on the pool:
 163 .Dl # Nm zfs Cm set Sy relatime Ns = Ns Sy off Ar poolname/dset
 164 .Dl # Nm zfs Cm inherit Sy relatime Ar poolname/dset
 165 .Pp
 166 To test the generator output:
 167 .Dl $ Nm mkdir Pa /tmp/zfs-mount-generator
 168 .Dl $ Nm @systemdgeneratordir@/zfs-mount-generator Pa /tmp/zfs-mount-generator
 169 .
 170 If the generated units are satisfactory, instruct
 171 .Nm systemd
 172 to re-run all generators:
 173 .Dl # Nm systemctl daemon-reload
 174 .
 175 .Sh SEE ALSO
 176 .Xr systemd.mount 5 ,
 177 .Xr systemd.target 5 ,
 178 .Xr zfs 5 ,
 179 .Xr systemd.generator 7 ,
 180 .Xr systemd.special 7 ,
 181 .Xr zed 8 ,
 182 .Xr zpool-events 8