1GANESHA-EXPORT-CONFIG(8) NFS-Ganesha GANESHA-EXPORT-CONFIG(8)
2
6 ganesha-export-config - NFS Ganesha Export Configuration File
7
9 /etc/ganesha/ganesha.conf
10
12 NFS-Ganesha obtains configuration data from the configuration file:
13 /etc/ganesha/ganesha.conf
14 This file lists NFS-Ganesha Export block config options.
16 EXPORT_DEFAULTS {}
18 These options are all "export permissions" options, and will be re‐
19 peated in the EXPORT {} and EXPORT { CLIENT {} } blocks.
20 These options will all be dynamically updateable.
22 Access_Type(enum, default None)
24 Possible values:
26 None, RW, RO, MDONLY, MDONLY_RO
27 Protocols(enum list, default none)
29 Possible values:
31 3, 4, NFS3, NFS4, V3, V4, NFSv3, NFSv4, 9P
32 Transports(enum list, values [UDP, TCP, RDMA], default [UDP, TCP])
34 Anonymous_uid(anonid, range INT32_MIN to UINT32_MAX, default -2)
36 Anonymous_gid(anonid, range INT32_MIN to UINT32_MAX, default -2)
38 SecType(enum list, default [none, sys])
40 Possible values:
42 none, sys, krb5, krb5i, krb5p
43 PrivilegedPort(bool, default false)
45 Manage_Gids(bool, default false)
47 Squash(enum, default root_sqaush)
49 Possible values:
51 root, root_squash, rootsquash, rootid, root_id_squash,
52 rootidsquash, all, all_squash, allsquash, all_anomnymous,
53 allanonymous, no_root_squash, none, noidsquash
54 Each line of defaults above are synonyms
56 Security_Label(bool, default false)
58 NFS_Commit(bool, default false)
60 Delegations(enum, default None)
62 Possible values:
64 None, read, write, readwrite, r, w, rw
65 Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)
67 EXPORT {}
69 All options below are dynamically changeable with config update unless
70 specified below.
71 Export_id (required):
73 An identifier for the export, must be unique and between 0 and
74 65535. If Export_Id 0 is specified, Pseudo must be the root
75 path (/).
76 Export_id is not dynamic per se, changing it essentially removes
78 the old export and introduces a new export.
79 Path (required)
81 The directory in the exported file system this export is rooted
82 on (may be ignored for some FSALs). It need not be unique if
83 Pseudo and/or Tag are specified.
84 Note that if it is not unique, and the core option
86 mount_path_pseudo is not set true, a v3 mount using the path
87 will ONLY be able to access the first export configured. To ac‐
88 cess other exports the Tag option would need to be used.
89 This option is NOT dynamically updateable since it fundamentally
91 changes the export. To change the path exported, export_id
92 should be changed also.
93 Pseudo (required v4)
95 This option specifies the position in the Pseudo Filesystem this
96 export occupies if this is an NFS v4 export. It must be unique.
97 By using different Pseudo options, the same Path may be exported
98 multiple times.
99 This option is used to place the export within the NFS v4 Pseudo
101 Filesystem. This creates a single name space for NFS v4. Clients
102 may mount the root of the Pseudo Filesystem and navigate to ex‐
103 ports. Note that the Path and Tag options are not at all visi‐
104 ble to NFS v4 clients.
105 Export id 0 is automatically created to provide the root and any
107 directories necessary to navigate to exports if there is no
108 other export specified with Pseudo = /;. Note that if an export
109 is specified with Pseudo = /;, it need not be export id 0. Spec‐
110 ifying such an export with FSAL { name = PSEUDO; } may be used
111 to create a Pseudo Filesystem with specific options. Such an ex‐
112 port may also use other FSALs (though directories to reach ex‐
113 ports will ONLY be automatically created on FSAL PSEUDO ex‐
114 ports).
115 This option is dynamically changeable and changing it will move
117 the export within the pseudo filesystem. This may be disruptive
118 to clients. Note that if the mount_path_pseudo NFS_CORE_PARAM
119 option is true, the NFSv3 mount path will also change (that
120 should not be disruptive to clients that have the export
121 mounted).
122 Tag (no default)
124 This option allows an alternative access for NFS v3 mounts. The
125 option MUST not have a leading /. Clients may not mount subdi‐
126 rectories (i.e. if Tag = foo, the client may not mount foo/baz).
127 By using different Tag options, the same Path may be exported
128 multiple times.
129 This option is not dynamically updatable.
131 MaxRead (64*1024*1024)
133 The maximum read size on this export
134 MaxWrite (64*1024*1024)
136 The maximum write size on this export
137 PrefRead (64*1024*1024)
139 The preferred read size on this export. Note that some older nfs
140 client (e.g. libnfs 1.x) would not handle well for large pre‐
141 ferred read size. If so, please try to decrease this size (usu‐
142 ally less than 1M is suitable for older nfs client).
143 PrefWrite (64*1024*1024)
145 The preferred write size on this export. Note that some older
146 nfs client (e.g. libnfs 1.x) would not handle well for large
147 preferred write size. If so, please try to decrease this size
148 (usually less than 1M is suitable for older nfs client).
149 PrefReaddir (16384)
151 The preferred readdir size on this export
152 MaxOffsetWrite (INT64_MAX)
154 Maximum file offset that may be written Range is 512 to
155 UINT64_MAX
156 MaxOffsetRead (INT64_MAX)
158 Maximum file offset that may be read Range is 512 to UINT64_MAX
159 CLIENT (optional)
161 See the EXPORT { CLIENT {} } block.
162 FSAL (required)
164 See the EXPORT { FSAL {} } block.
165 The FSAL for an export can not be changed dynamically. In order
167 to change the FSAL, a new export must be created.
168 At this time, no FSAL actually supports any updatable options.
170 EXPORT { CLIENT {} }
172 Take all the "export permissions" options from EXPORT_DEFAULTS. The
173 client lists are dynamically updateable.
174 These blocks form an ordered "access control list" for the export. If
176 no client block matches for a particular client, then the permissions
177 in the EXPORT {} block will be used.
178 Even when a CLIENT block matches a client, if a particular export per‐
180 mission is not explicit in that CLIENT block, the permission specified
181 in the EXPORT block will be used, or if not specified there, from the
182 EXPORT_DEFAULTS block, and if not specified there, the permission will
183 default to the default code value noted in the permission option de‐
184 scriptions above.
185 Note that when the CLIENT blocks are processed on config reload, a new
187 client access list is constructed and atomically swapped in. This al‐
188 lows adding, removing, and re-arranging clients as well as changing the
189 access for any give client.
190 Clients(client list, empty)
192 Client list entries can take on one of the following forms:
193 Match any client:
194 @name Netgroup name
196 x.x.x.x/y IPv4 network address
197 wildcarded If the string contains at least one ? or *
198 character (and is not simply "*"), the string is
199 used to pattern match host names. Note that [] may
200 also be used, but the pattern MUST have at least one
201 ? or *
202 hostname Match a single client (match is by IP address, all
203 addresses returned by getaddrinfo will match, the
204 getaddrinfo call is made at config parsing time)
205 IP address Match a single client
206 EXPORT { FSAL {} }
208 NFS-Ganesha supports the following FSALs: Ceph Gluster GPFS PROXY_V3
209 PROXY_V4 RGW VFS XFS LUSTRE LIzardFS KVSFS
210 Refer to individual FSAL config file for list of config options.
212 The FSAL blocks generally are less updatable
214
216 The EXPORT blocks define the file namespaces that are served by
217 NFS-Ganesha.
218 In best practice, each underlying filesystem has a single EXPORT defin‐
220 ing how that filesystem is to be shared, however, in some cases, it is
221 desirable to sub-divide a filesystem into multiple exports. The danger
222 when this is done is that rogue clients may be able to spoof file han‐
223 dles and access portions of the filesystem not intended to be accessi‐
224 ble to that client.
225 Some FSALs (currently FSAL_VFS, FSAL_GPFS, FSAL_XFS, and FSAL_LUSTRE)
227 are built to support nested filesystems, for example:
228 /export/fs1 /export/fs1/some/path/fs2
229 In this case, it is possible to create a single export that exports
231 both filesystems. There is a lot of complexity of what can be done
232 there.
233 In discussions of filesystems, btrfs filesystems exported by FSAL_VFS
235 may have subvolumes. Starting in NFS-Ganesha V4.0 FSAL_VFS treats these
236 as separate filesystems that are integrated with all the richness of
237 FSAL_VFS exports.
238 Another significant FSAL from an export point of view is FSAL_PSEUDO.
240 This is used to build glue exports to build the unified NFSv4 name
241 space. This name space may also be used by NFSv3 by setting the
242 NFS_CORE_PARAM option:
243 mount_path_pseudo = TRUE;
244 If no FSAL_PSEUDO export is explicitly defined, and there is no EXPORT
246 with:
247 Pseudo = "/";
248 NFS-Ganesha will build a FSAL_PSEUDO EXPORT with this Pseudo Path using
250 Export_Id = 0. This automatic EXPORT may be replaced with an explicit
251 EXPORT which need not have Export_Id = 0, it just must have Pseudo =
252 "/" and Protocols = 4.
253 In building the Pseudo Filesystem, there is a subtle gotcha. Since
255 NFSv4 clients actually moount the root of the Pseudo Filesystem and
256 then use LOOKUP to traverse into the actual directory the sysadmin has
257 mounted from the client, any EXPORTs from "/" to the desired EXPORT
258 MUST have Protocols = 4 specified either in EXPORT_DEFAULTS {}, EXPORT
259 {}, or EXPORT { CLIENT {} }. This is to assure that the client is al‐
260 lowed to traverse each EXPORT.
261 If Mount_Path_Pseudo = TRUE is being used and an export is desired to
263 be NFSv3 only, Protocols = 3 MUST be specified in the EXPORT {} block.
264 If Protocols is not specified in the EXPORT {} block and is only speci‐
265 fied in an EXPORT { CLIENT {} } block, then that export will still be
266 mounted in the Pseudo Filesystem but might not be traversable. Thus if
267 the following two filesystems are exported:
268 /export/fs1 /export/fs1/some/path/fs2
269 And the EXPORTs look something like this:
271 EXPORT {
272 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1;
273 FSAL {
275 Name = VFS;
276 }
278 CLIENT {
280 Clients="*"; Protocols=3;
281 }
283 }
285 EXPORT {
287 Export_Id = 1; Path = /export/fs1/some/path/fs2; Peudo = /ex‐
288 port/fs1/some/path/fs2;
289 FSAL {
291 Name = VFS;
292 }
294 CLIENT {
296 Clients="*"; Protocols=3,4;
297 }
299 }
301 NFSv4 clients will not be able to access /export/fs1/some/path/fs2. The
303 correct way to accomplish this is:
304 EXPORT {
305 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1; Pro‐
306 tocols=3;
307 FSAL
309 { Name = VFS;
311 }
313 }
315 Note that an EXPORT { CLIENT {} } block is not necessary if the default
317 export permissions are workable.
318 Note that in order for an EXPORT to be usable with NSFv4 it MUST either
320 have Protocols = 4 specified in the EXPORT block, or the EXPORT block
321 must not have the Protocols option at all such that it defaults to
322 3,4,9P. Note though that if it is not set and EXPORT_DEFAULTS just has
323 Protocols = 3; then even though the export is mounted in the Pseudo
324 Filesystem, it will not be accessible and the gotcha discussed above
325 may be in play.
326
328 In addition to the LOG {} configuration, EXPORT {} config is the main
329 configuration that can be updated while NFS-Ganesha is running by issu‐
330 ing a SIGHUP.
331 This causes all EXPORT and EXPORT_DEFAULTS blocks to be reloaded.
333 NFS-Ganesha V4.0 and later have some significant improvements to this
334 since it was introduced in NFS-Ganesha V2.4.0. V2.8.0 introduced the
335 ability to remove EXPORTs via SIGHUP configuration reload.
336 Significantly how things work now is:
338 On SIGHUP all the EXPORT and EXPORT_DEFAULTS blocks are re-read. There
340 are three conditions that may occur:
341 An export may be added An export may be removed An export may be up‐
342 dated
343 A note on Export_Id and Path. These are the primary options that define
345 an export. If Export_Id is changed, the change is treated as a remove
346 of the old Export_Id and an addition of the new Export_Id. Path can not
347 be changed without also changing Export_Id. The Tag and Pseudo options
348 that also contribute to the uniqueness of an EXPORT may be changed.
349 Any removed exports are removed from the internal tables and if they
351 are NFSv4 exports, unmounted from the Pseudo Filesystem, which will
352 then be re-built as if those exports had not been present.
353 Any new exports are added to the internal tables, and if the export is
355 an NFSv4 export, they are mounted into the Pseudo Filesystem.
356 Any updated exports will be modified with the least disruption possi‐
358 ble. If the Pseduo option is changed, the export is unmounted from the
359 Pseduo Filesystem in it's original location, and re-mounted in it's new
360 location. Other options are updated atomically, though serially, so for
361 a short period of time, the options may be mixed between old and new.
362 In most cases this should not cause problems. Notably though, the
363 CLIENT blocks are processed to form a new access control list and that
364 list is atomically swapped with the old list. If the Protocols for an
365 EXPORT are changed to include or remove NFSv4, the Pseduo Filesystem
366 will also be updated.
367 Note that there is no pause in operations other than a lock being taken
369 when the client list is being swapped out, however the export permis‐
370 sions are applied to an operation once. Notably for NFSv4, this is on a
371 PUTFH or LOOKUP which changes the Current File Handle. As an example,
372 if a write is in progress, having passed the permission check with the
373 previous export permissions, the write will complete without interrup‐
374 tion. If the write is part of an NFSv4 COMPOUND, the other operations
375 in that COMPOUND that operate on the same file handle will also com‐
376 plete with the previous export permissions.
377 An update of EXPORT_DEFAULTS changes the export options atomically.
379 These options are only used for those options not otherwise set in an
380 EXPORT {} or CLIENT {} block and are applied when export permissions
381 are evaluated when a new file handle is encountered.
382 The FSAL { Name } may not be changed and FSALs offer limited support
384 for changing any options in the FSAL block. Some FSALs may validate and
385 warn if any options in the FSAL block are changed when such a change is
386 not supported.
387
389 ganesha-config(8) ganesha-rgw-config(8) ganesha-vfs-config(8)
390 ganesha-lustre-config(8) ganesha-xfs-config(8) ganesha-gpfs-config(8)
391 ganesha-9p-config(8) ganesha-proxy-config(8) ganesha-ceph-config(8)
392 Jan 20, 2023 GANESHA-EXPORT-CONFIG(8)