Debian Codegraph @

upstream/debian-unstable/man7/nfs.systemd.7

raw
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).