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 below.
 105 .
 106 .It Sy org.openzfs.systemd:ignore Ns = Ns Sy on Ns | Ns Sy off
 107 .No Skip if Sy on .
 108 .No Defaults to Sy off .
 109 .El
 110 .
 111 .Ss Unit Ordering And Dependencies
 112 Additionally, unless the pool the dataset resides on
 113 is imported at generation time, both units gain
 114 .Sy Wants Ns = Ns Pa zfs-import.target
 115 and
 116 .Sy After Ns = Ns Pa zfs-import.target .
 117 .Pp
 118 Additionally, unless the logical
 119 .Em noauto
 120 flag is set, the mount unit gains a reverse-dependency for
 121 .Pa local-fs.target
 122 of strength
 123 .Bl -tag -compact -offset Ds -width "(unset)"
 124 .It (unset)
 125 .Sy WantedBy Ns = No + Sy Before Ns =
 126 .It Sy on
 127 .Sy WantedBy Ns =
 128 .It Sy off
 129 .Sy RequiredBy Ns = No + Sy Before Ns =
 130 .El
 131 .
 132 .Ss Cache File
 133 Because ZFS pools may not be available very early in the boot process,
 134 information on ZFS mountpoints must be stored separately.
 135 The output of
 136 .Dl Nm zfs Cm list Fl Ho Ar name , Ns Aq every property above in order
 137 for datasets that should be mounted by systemd should be kept at
 138 .Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname ,
 139 and, if writeable, will be kept synchronized for the entire pool by the
 140 .Pa history_event-zfs-list-cacher.sh
 141 ZEDLET, if enabled
 142 .Pq see Xr zed 8 .
 143 .
 144 .Sh ENVIRONMENT
 145 If the
 146 .Sy ZFS_DEBUG
 147 environment variable is nonzero
 148 .Pq or unset and Pa /proc/cmdline No contains Qq Sy debug ,
 149 print summary accounting information at the end.
 150 .
 151 .Sh EXAMPLES
 152 To begin, enable tracking for the pool:
 153 .Dl # Nm touch Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname
 154 Then enable the tracking ZEDLET:
 155 .Dl # Nm ln Fl s Pa @zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh @sysconfdir@/zfs/zed.d
 156 .Dl # Nm systemctl Cm enable Pa zfs-zed.service
 157 .Dl # Nm systemctl Cm restart Pa zfs-zed.service
 158 .Pp
 159 If no history event is in the queue,
 160 inject one to ensure the ZEDLET runs to refresh the cache file
 161 by setting a monitored property somewhere on the pool:
 162 .Dl # Nm zfs Cm set Sy relatime Ns = Ns Sy off Ar poolname/dset
 163 .Dl # Nm zfs Cm inherit Sy relatime Ar poolname/dset
 164 .Pp
 165 To test the generator output:
 166 .Dl $ Nm mkdir Pa /tmp/zfs-mount-generator
 167 .Dl $ Nm @systemdgeneratordir@/zfs-mount-generator Pa /tmp/zfs-mount-generator
 168 .
 169 If the generated units are satisfactory, instruct
 170 .Nm systemd
 171 to re-run all generators:
 172 .Dl # Nm systemctl daemon-reload
 173 .
 174 .Sh SEE ALSO
 175 .Xr systemd.mount 5 ,
 176 .Xr systemd.target 5 ,
 177 .Xr zfs 5 ,
 178 .Xr systemd.generator 7 ,
 179 .Xr systemd.special 7 ,
 180 .Xr zed 8 ,
 181 .Xr zpool-events 8