| 1 |
.TH NFS.SYSTEMD 7 |
| 2 |
.SH NAME |
| 3 |
nfs.systemd \- managing NFS services through systemd. |
| 4 |
.SH SYNOPSIS |
| 5 |
nfs-utils.service |
| 6 |
.br |
| 7 |
nfs-server.service |
| 8 |
.br |
| 9 |
nfs-client.target |
| 10 |
.br |
| 11 |
.I etc |
| 12 |
.SH DESCRIPTION |
| 13 |
The |
| 14 |
.I nfs-utils |
| 15 |
package provides a suite of |
| 16 |
.I systemd |
| 17 |
unit files and generators which allow the various services to be |
| 18 |
started and managed. These unit files and generators ensure that the |
| 19 |
services are started in the correct order, and the prerequisites are |
| 20 |
active before dependant services start. As there are quite a few unit |
| 21 |
files and generators, it is not immediately obvious how best to achieve |
| 22 |
certain results. The following subsections attempt to cover the issues |
| 23 |
that are most likely to come up. |
| 24 |
.SS Configuration |
| 25 |
The standard systemd unit files do not provide any easy way to pass |
| 26 |
any command line arguments to daemons so as to configure their |
| 27 |
behavior. In many case such configuration can be performed by making |
| 28 |
changes to |
| 29 |
.I /etc/nfs.conf |
| 30 |
or other configuration files (see |
| 31 |
.BR nfs.conf (5)). |
| 32 |
When that is not convenient, a |
| 33 |
distribution might provide systemd "drop-in" files which replace the |
| 34 |
.B ExecStart= |
| 35 |
setting to start the program with different arguments. For example a |
| 36 |
drop-in file |
| 37 |
.B systemd/system/nfs-mountd.service.d/local.conf |
| 38 |
containing |
| 39 |
.RS |
| 40 |
.nf |
| 41 |
[Service] |
| 42 |
EnvironmentFile=/etc/sysconfig/nfs |
| 43 |
ExecStart= |
| 44 |
ExecStart= /usr/sbin/rpc.mountd $RPCMOUNTDOPTS |
| 45 |
.fi |
| 46 |
.RE |
| 47 |
would cause the |
| 48 |
.B nfs-mountd.service |
| 49 |
unit to run the |
| 50 |
.I rpc.mountd |
| 51 |
program using, for arguments, the value given for |
| 52 |
.B RPCMOUNTDOPTS |
| 53 |
in |
| 54 |
.IR /etc/sysconfig/nfs . |
| 55 |
This allows for seamless integration with existing configuration |
| 56 |
tools. |
| 57 |
.SS Enabling unit files |
| 58 |
There are three unit files which are designed to be manually enabled. |
| 59 |
All others are automatically run as required. The three are: |
| 60 |
.TP |
| 61 |
.B nfs-client.target |
| 62 |
This should be enabled on any host which ever serves as an NFS client. |
| 63 |
There is little cost in transparently enabling it whenever NFS client |
| 64 |
software is installed. |
| 65 |
.TP |
| 66 |
.B nfs-server.service |
| 67 |
This must be enabled to provide NFS service to clients. It starts and |
| 68 |
configures the required daemons in the required order. |
| 69 |
.TP |
| 70 |
.B nfs-blkmap.service |
| 71 |
The |
| 72 |
.B blkmapd |
| 73 |
daemon is only required on NFS clients which are using pNFS (parallel |
| 74 |
NFS), and particularly using the |
| 75 |
.B blocklayout |
| 76 |
layout protocol. If you might use this particular extension to NFS, |
| 77 |
the |
| 78 |
.B nfs-blkmap.service |
| 79 |
unit should be enabled. |
| 80 |
.PP |
| 81 |
Several other units which might be considered to be optional, such as |
| 82 |
.I rpc-gssd.service |
| 83 |
are careful to only start if the required configuration file exists. |
| 84 |
.I rpc-gssd.service |
| 85 |
will not start if the |
| 86 |
.I krb5.keytab |
| 87 |
file does not exist (typically in |
| 88 |
.IR /etc ). |
| 89 |
.SS Restarting NFS services |
| 90 |
Most NFS daemons can be restarted at any time. They will reload any |
| 91 |
state that they need, and continue servicing requests. This is rarely |
| 92 |
necessary though. |
| 93 |
.PP |
| 94 |
When configuration changes are made, it can be hard to know exactly |
| 95 |
which services need to be restarted to ensure that the configuration |
| 96 |
takes effect. The simplest approach, which is often the best, is to |
| 97 |
restart everything. To help with this, the |
| 98 |
.B nfs-utils.service |
| 99 |
unit is provided. It declares appropriate dependencies with other |
| 100 |
unit files so that |
| 101 |
.RS |
| 102 |
.B systemctl restart nfs-utils |
| 103 |
.RE |
| 104 |
will restart all NFS daemons that are running. This will cause all |
| 105 |
configuration changes to take effect |
| 106 |
.I except |
| 107 |
for changes to mount options lists in |
| 108 |
.I /etc/fstab |
| 109 |
or |
| 110 |
.IR /etc/nfsmount.conf . |
| 111 |
Mount options can only be changed by unmounting and remounting |
| 112 |
filesystem. This can be a disruptive operation so it should only be |
| 113 |
done when the value justifies the cost. The command |
| 114 |
.RS |
| 115 |
.B umount -a -t nfs; mount -a -t nfs |
| 116 |
.RE |
| 117 |
should unmount and remount all NFS filesystems. |
| 118 |
.SS Masking unwanted services |
| 119 |
Rarely there may be a desire to prohibit some services from running |
| 120 |
even though there are normally part of a working NFS system. This may |
| 121 |
be needed to reduce system load to an absolute minimum, or to reduce |
| 122 |
attack surface by not running daemons that are not absolutely |
| 123 |
required. |
| 124 |
.PP |
| 125 |
Three particular services which this can apply to are |
| 126 |
.IR rpcbind , |
| 127 |
.IR idmapd , |
| 128 |
and |
| 129 |
.IR rpc-gssd . |
| 130 |
.I rpcbind |
| 131 |
is not part of the |
| 132 |
.I nfs-utils |
| 133 |
package, but it used by several NFS services. However it is |
| 134 |
.B not |
| 135 |
needed when only NFSv4 is in use. If a site will never use NFSv3 (or |
| 136 |
NFSv2) and does not want |
| 137 |
.I rpcbind |
| 138 |
to be running, the correct approach is to run |
| 139 |
.RS |
| 140 |
.B systemctl mask rpcbind |
| 141 |
.RE |
| 142 |
This will disable |
| 143 |
.IR rpcbind , |
| 144 |
and the various NFS services which depend on it (and are only needed |
| 145 |
for NFSv3) will refuse to start, without interfering with the |
| 146 |
operation of NFSv4 services. In particular, |
| 147 |
.I rpc.statd |
| 148 |
will not run when |
| 149 |
.I rpcbind |
| 150 |
is masked. |
| 151 |
.PP |
| 152 |
.I idmapd |
| 153 |
is only needed for NFSv4, and even then is not needed when the client |
| 154 |
and server agree to use user-ids rather than user-names to identify the |
| 155 |
owners of files. If |
| 156 |
.I idmapd |
| 157 |
is not needed and not wanted, it can be masked with |
| 158 |
.RS |
| 159 |
.B systemctl mask idmapd |
| 160 |
.RE |
| 161 |
.I rpc-gssd |
| 162 |
is assumed to be needed if the |
| 163 |
.I krb5.keytab |
| 164 |
file is present. If a site needs this file present but does not want |
| 165 |
.I rpc-gssd |
| 166 |
running, it can be masked with |
| 167 |
.RS |
| 168 |
.B systemctl mask rpc-gssd |
| 169 |
.SS Generators |
| 170 |
systemd unit generators are small executables placed in |
| 171 |
.I /usr/lib/systemd/system-generators/ |
| 172 |
to dynamically extend the unit file hierarchy. The |
| 173 |
.I nfs-utils |
| 174 |
package provides three: |
| 175 |
.TP |
| 176 |
.B nfsroot-generator |
| 177 |
It creates the |
| 178 |
.B sysroot.mount |
| 179 |
unit to mount /sysroot via NFSv4 in the initrd, if it detects one the |
| 180 |
following options in the kernel command line: |
| 181 |
.PP |
| 182 |
.RS |
| 183 |
.B root=/dev/nfs nfsroot=[<server>:]<path>[,<options>] |
| 184 |
.PP |
| 185 |
.RS |
| 186 |
Defined in |
| 187 |
.I <kernel_source>/Documentation/admin-guide/nfs/nfsroot.rst |
| 188 |
.RE |
| 189 |
.RE |
| 190 |
.PP |
| 191 |
.RS |
| 192 |
.B root=nfs[4]:[<server>:]<path>[:<options>] |
| 193 |
.PP |
| 194 |
.RS |
| 195 |
Defined in |
| 196 |
.BR dracut.cmdline (7). |
| 197 |
.PP |
| 198 |
.B NOTE: |
| 199 |
Although "nfs" can be used as type indicator for the mountpoint, the |
| 200 |
mount unit will use always "nfs4". |
| 201 |
.RE |
| 202 |
.RE |
| 203 |
.TP |
| 204 |
.B nfs-server-generator |
| 205 |
It creates ordering dependencies between |
| 206 |
.I nfs-server.service |
| 207 |
and various filesystem mounts: it should start before any "nfs" |
| 208 |
mountpoints are mounted, in case they are loop-back mounts, and after |
| 209 |
all exported filesystems are mounted, so there is no risk of exporting |
| 210 |
the underlying directory. |
| 211 |
.TP |
| 212 |
.B rpc-pipefs-generator |
| 213 |
It creates ordering dependencies between NFS services and the |
| 214 |
rpc_pipefs mountpoint. |
| 215 |
.RE |
| 216 |
.SH FILES |
| 217 |
/etc/nfs.conf |
| 218 |
.br |
| 219 |
/etc/nfsmount.conf |
| 220 |
.br |
| 221 |
/etc/idmapd.conf |
| 222 |
.P |
| 223 |
Also similar files in |
| 224 |
.B /usr/etc |
| 225 |
and in related |
| 226 |
.I conf.d |
| 227 |
drop-in directories. |
| 228 |
.SH SEE ALSO |
| 229 |
.BR bootup (7), |
| 230 |
.BR systemd.generator (7), |
| 231 |
.BR systemd.unit (5), |
| 232 |
.BR nfs.conf (5), |
| 233 |
.BR nfsmount.conf (5). |