| .\" |
| .\" Copyright 2018 Antonio Russo <antonio.e.russo@gmail.com> |
| .\" Copyright 2019 Kjeld Schouten-Lebbing <kjeld@schouten-lebbing.nl> |
| .\" Copyright 2020 InsanePrawn <insane.prawny@gmail.com> |
| .\" |
| .\" Permission is hereby granted, free of charge, to any person obtaining |
| .\" a copy of this software and associated documentation files (the |
| .\" "Software"), to deal in the Software without restriction, including |
| .\" without limitation the rights to use, copy, modify, merge, publish, |
| .\" distribute, sublicense, and/or sell copies of the Software, and to |
| .\" permit persons to whom the Software is furnished to do so, subject to |
| .\" the following conditions: |
| .\" |
| .\" The above copyright notice and this permission notice shall be |
| .\" included in all copies or substantial portions of the Software. |
| .\" |
| .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
| .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
| .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
| .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
| .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| |
| .TH "ZFS\-MOUNT\-GENERATOR" "8" "2020-01-19" "ZFS" "zfs-mount-generator" "\"" |
| |
| .SH "NAME" |
| zfs\-mount\-generator \- generates systemd mount units for ZFS |
| .SH SYNOPSIS |
| .B @systemdgeneratordir@/zfs\-mount\-generator |
| .sp |
| .SH DESCRIPTION |
| zfs\-mount\-generator implements the \fBGenerators Specification\fP |
| of |
| .BR systemd (1), |
| and is called during early boot to generate |
| .BR systemd.mount (5) |
| units for automatically mounted datasets. Mount ordering and dependencies |
| are created for all tracked pools (see below). |
| |
| .SS ENCRYPTION KEYS |
| If the dataset is an encryption root, a service that loads the associated key (either from file or through a |
| .BR systemd\-ask\-password (1) |
| prompt) will be created. This service |
| . BR RequiresMountsFor |
| the path of the key (if file-based) and also copies the mount unit's |
| .BR After , |
| .BR Before |
| and |
| .BR Requires . |
| All mount units of encrypted datasets add the key\-load service for their encryption root to their |
| .BR Wants |
| and |
| .BR After . |
| The service will not be |
| .BR Want ed |
| or |
| .BR Require d |
| by |
| .BR local-fs.target |
| directly, and so will only be started manually or as a dependency of a started mount unit. |
| |
| .SS UNIT ORDERING AND DEPENDENCIES |
| mount unit's |
| .BR Before |
| \-> |
| key\-load service (if any) |
| \-> |
| mount unit |
| \-> |
| mount unit's |
| .BR After |
| |
| 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. |
| |
| .SS CACHE FILE |
| Because ZFS pools may not be available very early in the boot process, |
| information on ZFS mountpoints must be stored separately. The output of the command |
| .PP |
| .RS 4 |
| 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 |
| |
| .RE |
| .PP |
| for datasets that should be mounted by systemd, should be kept |
| separate from the pool, at |
| .PP |
| .RS 4 |
| .RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME |
| . |
| .RE |
| .PP |
| The cache file, if writeable, will be kept synchronized with the pool |
| state by the ZEDLET |
| .PP |
| .RS 4 |
| history_event-zfs-list-cacher.sh . |
| .RE |
| .PP |
| .sp |
| .SS PROPERTIES |
| The behavior of the generator script can be influenced by the following dataset properties: |
| .sp |
| .TP 4 |
| .BR canmount = on | off | noauto |
| If a dataset has |
| .BR mountpoint |
| set and |
| .BR canmount |
| is not |
| .BR off , |
| a mount unit will be generated. |
| Additionally, if |
| .BR canmount |
| is |
| .BR on , |
| .BR local-fs.target |
| will gain a dependency on the mount unit. |
| |
| This behavior is equal to the |
| .BR auto |
| and |
| .BR noauto |
| legacy mount options, see |
| .BR systemd.mount (5). |
| |
| Encryption roots always generate a key-load service, even for |
| .BR canmount=off . |
| .TP 4 |
| .BR org.openzfs.systemd:requires\-mounts\-for = \fIpath\fR... |
| Space\-separated list of mountpoints to require to be mounted for this mount unit |
| .TP 4 |
| .BR org.openzfs.systemd:before = \fIunit\fR... |
| The mount unit and associated key\-load service will be ordered before this space\-separated list of units. |
| .TP 4 |
| .BR org.openzfs.systemd:after = \fIunit\fR... |
| The mount unit and associated key\-load service will be ordered after this space\-separated list of units. |
| .TP 4 |
| .BR org.openzfs.systemd:wanted\-by = \fIunit\fR... |
| Space-separated list of units that will gain a |
| .BR Wants |
| dependency on this mount unit. |
| Setting this property implies |
| .BR noauto . |
| .TP 4 |
| .BR org.openzfs.systemd:required\-by = \fIunit\fR... |
| Space-separated list of units that will gain a |
| .BR Requires |
| dependency on this mount unit. |
| Setting this property implies |
| .BR noauto . |
| .TP 4 |
| .BR org.openzfs.systemd:nofail = unset | on | off |
| Toggles between a |
| .BR Wants |
| and |
| .BR Requires |
| type of dependency between the mount unit and |
| .BR local-fs.target , |
| if |
| .BR noauto |
| isn't set or implied. |
| |
| .BR on : |
| Mount will be |
| .BR WantedBy |
| local-fs.target |
| |
| .BR off : |
| Mount will be |
| .BR Before |
| and |
| .BR RequiredBy |
| local-fs.target |
| |
| .BR unset : |
| Mount will be |
| .BR Before |
| and |
| .BR WantedBy |
| local-fs.target |
| .TP 4 |
| .BR org.openzfs.systemd:ignore = on | off |
| If set to |
| .BR on , |
| do not generate a mount unit for this dataset. |
| |
| .RE |
| See also |
| .BR systemd.mount (5) |
| |
| .PP |
| .SH EXAMPLE |
| To begin, enable tracking for the pool: |
| .PP |
| .RS 4 |
| touch |
| .RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME |
| .RE |
| .PP |
| Then, enable the tracking ZEDLET: |
| .PP |
| .RS 4 |
| ln -s "@zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh" "@sysconfdir@/zfs/zed.d" |
| |
| systemctl enable zfs-zed.service |
| |
| systemctl restart zfs-zed.service |
| .RE |
| .PP |
| Force the running of the ZEDLET by setting a monitored property, e.g. |
| .BR canmount , |
| for at least one dataset in the pool: |
| .PP |
| .RS 4 |
| zfs set canmount=on |
| .I DATASET |
| .RE |
| .PP |
| This forces an update to the stale cache file. |
| |
| To test the generator output, run |
| .PP |
| .RS 4 |
| @systemdgeneratordir@/zfs-mount-generator /tmp/zfs-mount-generator . . |
| .RE |
| .PP |
| This will generate units and dependencies in |
| .I /tmp/zfs-mount-generator |
| for you to inspect them. The second and third argument are ignored. |
| |
| If you're satisfied with the generated units, instruct systemd to re-run all generators: |
| .PP |
| .RS 4 |
| systemctl daemon-reload |
| .RE |
| .PP |
| |
| .sp |
| .SH SEE ALSO |
| .BR zfs (5) |
| .BR zfs-events (5) |
| .BR zed (8) |
| .BR zpool (5) |
| .BR systemd (1) |
| .BR systemd.target (5) |
| .BR systemd.special (7) |
| .BR systemd.mount (7) |