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 PERMISSIONS
18 These options are all "export permissions" options, and are available
19 in EXPORT_DEFAULTS {}, EXPORT {} and 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 NFS_Commit(bool, default false)
58 Delegations(enum, default None)
60 Possible values:
62 None, read, write, readwrite, r, w, rw
63 CLIENT {}
65 CLIENT blocks are used in EXPORT_DEFAULTS {}, EXPORT {}, and PSEUDOFS
66 {} blocks.
67 Each CLIENT block provides a list of clients and the permissions
69 granted those clients. These blocks form an ordered "access control
70 list" for the export. If no client block matches for a particular
71 client, then the permissions in the EXPORT {} block will be used (and
72 if any permissions are not set between the CLIENT and the EXPORT, then
73 the permissions set in EXPORT_DEFAULTS will be used and if still not
74 set, then the code default will be used.
75 If an EXPORT does not have any CLIENT blocks then the list of CLIENT
77 blocks in EXPORT_DEFAULTS (if any) will be used. No matter the source
78 of the CLIENT blocks, if the client matches none, then the permissions
79 in the EXPORT will be applied next.
80 To override a restrictive default client list with "everyone" a
82 non-empty client list would have to be specified. Clients = "*" would
83 do the trick.
84 Even when a CLIENT block matches a client, if a particular export per‐
86 mission is not explicit in that CLIENT block, the permission specified
87 in the EXPORT block will be used, or if not specified there, from the
88 EXPORT_DEFAULTS block, and if not specified there, the permission will
89 default to the default code value noted in the permission option de‐
90 scriptions above.
91 Note that when the CLIENT blocks are processed on config reload, a new
93 client access list is constructed and atomically swapped in. This al‐
94 lows adding, removing, and re-arranging clients as well as changing the
95 access for any give client.
96 CLIENT blocks use all the EXPORT PERMISSIONS options (except PSEUDOFS
98 CLIENT blocks which are limited to the same options the PSEUDOFS block
99 is allowed) plus:
100 Clients(client list, empty)
102 Client list entries can take on one of the following forms. This
103 parameter may be repeated to extend the list.
104 * Match any client @name Netgroup name
105 x.x.x.x/y IPv4 network address, IPv6 addresses are also al‐
106 lowed
107 but the format is too complex to show here
108 wildcarded If the string contains at least one ? or *
110 character (and is not simply "*"), the string is used
111 to pattern match host names. Note that [] may also be
112 used, but the pattern MUST have at least one ? or *
113 hostname Match a single client (match is by IP address, all
115 addresses returned by getaddrinfo will match, the
116 getaddrinfo call is made at config parsing time)
117 IP address Match a single client
119 EXPORT_DEFAULTS {}
121 All the EXPORT PERMISSIONS options plus:
122 Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)
124 CLIENT (optional)
126 See the CLIENT {} block description. There may be any number
127 of these.
128 EXPORT_DEFAULTS { CLIENT {} }
130 See the CLIENT {} block description.
131 EXPORT {}
133 All options below are dynamically changeable with config update unless
134 specified below. This block may be repeated to define multiple exports.
135 All the EXPORT_PERMISSIONS plus:
137 Export_id (required):
139 An identifier for the export, must be unique and between 0 and
140 65535. If Export_Id 0 is specified, Pseudo must be the root
141 path (/).
142 Export_id is not dynamic per se, changing it essentially removes
144 the old export and introduces a new export.
145 Path (required)
147 The directory in the exported file system this export is rooted
148 on (may be ignored for some FSALs). It need not be unique if
149 Pseudo and/or Tag are specified.
150 Note that if it is not unique, and the core option
152 mount_path_pseudo is not set true, a v3 mount using the path
153 will ONLY be able to access the first export configured. To ac‐
154 cess other exports the Tag option would need to be used.
155 This option is NOT dynamically updateable since it fundamentally
157 changes the export. To change the path exported, export_id
158 should be changed also.
159 Pseudo (required v4)
161 This option specifies the position in the Pseudo Filesystem this
162 export occupies if this is an NFS v4 export. It must be unique.
163 By using different Pseudo options, the same Path may be exported
164 multiple times.
165 This option is used to place the export within the NFS v4 Pseudo
167 Filesystem. This creates a single name space for NFS v4. Clients
168 may mount the root of the Pseudo Filesystem and navigate to ex‐
169 ports. Note that the Path and Tag options are not at all visi‐
170 ble to NFS v4 clients.
171 Export id 0 is automatically created to provide the root and any
173 directories necessary to navigate to exports if there is no
174 other export specified with Pseudo = /;. Note that if an export
175 is specified with Pseudo = /;, it need not be export id 0. Spec‐
176 ifying such an export with FSAL { name = PSEUDO; } may be used
177 to create a Pseudo Filesystem with specific options. Such an ex‐
178 port may also use other FSALs (though directories to reach ex‐
179 ports will ONLY be automatically created on FSAL PSEUDO ex‐
180 ports).
181 This option is dynamically changeable and changing it will move
183 the export within the pseudo filesystem. This may be disruptive
184 to clients. Note that if the mount_path_pseudo NFS_CORE_PARAM
185 option is true, the NFSv3 mount path will also change (that
186 should not be disruptive to clients that have the export
187 mounted).
188 Tag (no default)
190 This option allows an alternative access for NFS v3 mounts. The
191 option MUST not have a leading /. Clients may not mount subdi‐
192 rectories (i.e. if Tag = foo, the client may not mount foo/baz).
193 By using different Tag options, the same Path may be exported
194 multiple times.
195 This option is not dynamically updatable.
197 Filesystem_id(fsid, format is uint64.uint64, default unused)
199 This option allows overriding the filesystem ID provided by the
200 underlying filesystem. Use of this option is discouraged, It
201 will not work if VFS or GPFS is exporting a filesystem that has
202 other filesystems mounted on sub-directories and exported with
203 the same export.
204 This option is not dynamically updateable.
206 MaxRead (64*1024*1024)
208 The maximum read size on this export
209 MaxWrite (64*1024*1024)
211 The maximum write size on this export
212 PrefRead (64*1024*1024)
214 The preferred read size on this export. Note that some older nfs
215 client (e.g. libnfs 1.x) would not handle well for large pre‐
216 ferred read size. If so, please try to decrease this size (usu‐
217 ally less than 1M is suitable for older nfs client).
218 PrefWrite (64*1024*1024)
220 The preferred write size on this export. Note that some older
221 nfs client (e.g. libnfs 1.x) would not handle well for large
222 preferred write size. If so, please try to decrease this size
223 (usually less than 1M is suitable for older nfs client).
224 PrefReaddir (16384)
226 The preferred readdir size on this export
227 MaxOffsetWrite (INT64_MAX)
229 Maximum file offset that may be written Range is 512 to
230 UINT64_MAX
231 MaxOffsetRead (INT64_MAX)
233 Maximum file offset that may be read Range is 512 to UINT64_MAX
234 DisableReaddirPlus(bool, default false)
236 Trust_Readdir_Negative_Cache(bool, default false)
238 The following options may have limits on dynamic effect
240 UseCookieVerifier(bool, default true)
242 Updating UseCookieVerifier while a readdir is in progress may
243 result in unexpected behavior.
244 Disable_ACL(bool, default false)
246 Disable_ACL is processed at create_export time currently which
247 makes it effectively a static option.
248 Security_Label(bool, default false)
250 Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)
252 Attr_Expiration_Time is evaluated when an MDCACHE entry is cre‐
253 ated, so the dynamic effect of this option may be constrained to
254 new entries.
255 CLIENT (optional)
257 See the CLIENT {} block description. There may be any number
258 of these.
259 FSAL (required)
261 See the EXPORT { FSAL {} } block.
262 The FSAL for an export can not be changed dynamically. In order
264 to change the FSAL, a new export must be created.
265 At this time, no FSAL actually supports any updatable options.
267 EXPORT { CLIENT {} }
269 See the CLIENT {} block description.
270 EXPORT { FSAL {} }
272 NFS-Ganesha supports the following FSALs: Ceph Gluster GPFS PROXY_V3
273 PROXY_V4 RGW VFS XFS LUSTRE LIzardFS KVSFS
274 Refer to individual FSAL config file for list of config options.
276 The FSAL blocks generally are less updatable
278 PSEUDOFS {}
280 This block allows specifying some options for the pseudofs root export.
281 It is very similar to an EXPORT block, except only the following op‐
282 tions may be specified. CLIENT blocks may be used just like an EXPORT
283 block, however, they are also limited to the same options.
284 This is basically a shortcut rather than having to fill out options in
286 an EXPORT block. Note that Path, Pseudo, and Export_Id are not included
287 as those values will be fixed ("/" for the paths, and 0 for Export_Id).
288 Other options that don't make sense for the pseudofs root are also not
289 allowed.
290 An empty PSEUDOFS {} block will produce the same default pseudofs root
292 export as generated if no pseudofs root export is otherwise specified.
293 This block is most useful to override a restrictive CLIENT list in EX‐
295 PORT_DEFAULTS {}.
296 These options will all be dynamically updateable.
298 Access_Type(enum, default MDONLY_RO)
300 Possible values:
302 None, MDONLY_RO
303 Transports(enum list, values [UDP, TCP, RDMA], default [TCP])
305 SecType(enum list, default [none, sys, krb5, krb5i, krb5p])
307 Possible values:
309 none, sys, krb5, krb5i, krb5p
310 PrivilegedPort(bool, default false)
312 Export_id(uint16, range 0 to UINT16_MAX, default 0)
314 An identifier for the export, must be unique and between 0 and
315 65535.
316 Export_id is not dynamic per se, changing it essentially removes
318 the old export and introduces a new export.
319 Filesystem_id(fsid, format is uint64.uint64, default 152.152)
321 Unlike standard exports, there is no underlying filesystem to
322 get an ID from, so this option is important, however the default
323 value may be used so it need not be specified.
324 This option is not dynamically updateable.
326 DisableReaddirPlus(bool, default false)
328 Trust_Readdir_Negative_Cache(bool, default false)
330 The following options may have limits on dynamic effect
332 UseCookieVerifier(bool, default true)
334 Updating UseCookieVerifier while a readdir is in progress may
335 result in unexpected behavior.
336 PSEUDOFS { CLIENT {} }
338 See the CLIENT {} block description but note that beyond the Clients
339 options that works as described, the other options available are as for
340 the PSEUDOFS {} block.
341 If it is desired to override a restrictive CLIENT list in EXPORT_DE‐
343 FAULTS, the following PSEUDOFS could be defined that will give all
344 clients the default access to the pseudofs root that otherwise would
345 have been granted if EXPORT_DEFAULTS was not used.
346 PSEUDOFS {
348 CLIENT {
350 Clients =
351 *
352 ;
353 }
355 }
357
359 The EXPORT blocks define the file namespaces that are served by
360 NFS-Ganesha.
361 In best practice, each underlying filesystem has a single EXPORT defin‐
363 ing how that filesystem is to be shared, however, in some cases, it is
364 desirable to sub-divide a filesystem into multiple exports. The danger
365 when this is done is that rogue clients may be able to spoof file han‐
366 dles and access portions of the filesystem not intended to be accessi‐
367 ble to that client.
368 Some FSALs (currently FSAL_VFS, FSAL_GPFS, FSAL_XFS, and FSAL_LUSTRE)
370 are built to support nested filesystems, for example:
371 /export/fs1 /export/fs1/some/path/fs2
372 In this case, it is possible to create a single export that exports
374 both filesystems. There is a lot of complexity of what can be done
375 there.
376 In discussions of filesystems, btrfs filesystems exported by FSAL_VFS
378 may have subvolumes. Starting in NFS-Ganesha V4.0 FSAL_VFS treats these
379 as separate filesystems that are integrated with all the richness of
380 FSAL_VFS exports.
381 Another significant FSAL from an export point of view is FSAL_PSEUDO.
383 This is used to build glue exports to build the unified NFSv4 name
384 space. This name space may also be used by NFSv3 by setting the
385 NFS_CORE_PARAM option:
386 mount_path_pseudo = TRUE;
387 If no FSAL_PSEUDO export is explicitly defined, and there is no EXPORT
389 with:
390 Pseudo = "/";
391 NFS-Ganesha will build a FSAL_PSEUDO EXPORT with this Pseudo Path using
393 Export_Id = 0. This automatic EXPORT may be replaced with an explicit
394 EXPORT which need not have Export_Id = 0, it just must have Pseudo =
395 "/" and Protocols = 4.
396 In building the Pseudo Filesystem, there is a subtle gotcha. Since
398 NFSv4 clients actually moount the root of the Pseudo Filesystem and
399 then use LOOKUP to traverse into the actual directory the sysadmin has
400 mounted from the client, any EXPORTs from "/" to the desired EXPORT
401 MUST have Protocols = 4 specified either in EXPORT_DEFAULTS {}, EXPORT
402 {}, or EXPORT { CLIENT {} }. This is to assure that the client is al‐
403 lowed to traverse each EXPORT.
404 If Mount_Path_Pseudo = TRUE is being used and an export is desired to
406 be NFSv3 only, Protocols = 3 MUST be specified in the EXPORT {} block.
407 If Protocols is not specified in the EXPORT {} block and is only speci‐
408 fied in an EXPORT { CLIENT {} } block, then that export will still be
409 mounted in the Pseudo Filesystem but might not be traversable. Thus if
410 the following two filesystems are exported:
411 /export/fs1 /export/fs1/some/path/fs2
412 And the EXPORTs look something like this:
414 EXPORT {
415 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1;
416 FSAL {
418 Name = VFS;
419 }
421 CLIENT {
423 Clients="*"; Protocols=3;
424 }
426 }
428 EXPORT {
430 Export_Id = 1; Path = /export/fs1/some/path/fs2; Peudo = /ex‐
431 port/fs1/some/path/fs2;
432 FSAL {
434 Name = VFS;
435 }
437 CLIENT {
439 Clients="*"; Protocols=3,4;
440 }
442 }
444 NFSv4 clients will not be able to access /export/fs1/some/path/fs2. The
446 correct way to accomplish this is:
447 EXPORT {
448 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1; Pro‐
449 tocols=3;
450 FSAL
452 { Name = VFS;
454 }
456 }
458 Note that an EXPORT { CLIENT {} } block is not necessary if the default
460 export permissions are workable.
461 Note that in order for an EXPORT to be usable with NSFv4 it MUST either
463 have Protocols = 4 specified in the EXPORT block, or the EXPORT block
464 must not have the Protocols option at all such that it defaults to
465 3,4,9P. Note though that if it is not set and EXPORT_DEFAULTS just has
466 Protocols = 3; then even though the export is mounted in the Pseudo
467 Filesystem, it will not be accessible and the gotcha discussed above
468 may be in play.
469
471 In addition to the LOG {} configuration, EXPORT {} config is the main
472 configuration that can be updated while NFS-Ganesha is running by issu‐
473 ing a SIGHUP.
474 This causes all EXPORT and EXPORT_DEFAULTS blocks to be reloaded.
476 NFS-Ganesha V4.0 and later have some significant improvements to this
477 since it was introduced in NFS-Ganesha V2.4.0. V2.8.0 introduced the
478 ability to remove EXPORTs via SIGHUP configuration reload.
479 Significantly how things work now is:
481 On SIGHUP all the EXPORT and EXPORT_DEFAULTS blocks are re-read. There
483 are three conditions that may occur:
484 An export may be added An export may be removed An export may be up‐
485 dated
486 A note on Export_Id and Path. These are the primary options that define
488 an export. If Export_Id is changed, the change is treated as a remove
489 of the old Export_Id and an addition of the new Export_Id. Path can not
490 be changed without also changing Export_Id. The Tag and Pseudo options
491 that also contribute to the uniqueness of an EXPORT may be changed.
492 Any removed exports are removed from the internal tables and if they
494 are NFSv4 exports, unmounted from the Pseudo Filesystem, which will
495 then be re-built as if those exports had not been present.
496 Any new exports are added to the internal tables, and if the export is
498 an NFSv4 export, they are mounted into the Pseudo Filesystem.
499 Any updated exports will be modified with the least disruption possi‐
501 ble. If the Pseduo option is changed, the export is unmounted from the
502 Pseduo Filesystem in it's original location, and re-mounted in it's new
503 location. Other options are updated atomically, though serially, so for
504 a short period of time, the options may be mixed between old and new.
505 In most cases this should not cause problems. Notably though, the
506 CLIENT blocks are processed to form a new access control list and that
507 list is atomically swapped with the old list. If the Protocols for an
508 EXPORT are changed to include or remove NFSv4, the Pseduo Filesystem
509 will also be updated.
510 Note that there is no pause in operations other than a lock being taken
512 when the client list is being swapped out, however the export permis‐
513 sions are applied to an operation once. Notably for NFSv4, this is on a
514 PUTFH or LOOKUP which changes the Current File Handle. As an example,
515 if a write is in progress, having passed the permission check with the
516 previous export permissions, the write will complete without interrup‐
517 tion. If the write is part of an NFSv4 COMPOUND, the other operations
518 in that COMPOUND that operate on the same file handle will also com‐
519 plete with the previous export permissions.
520 An update of EXPORT_DEFAULTS changes the export options atomically.
522 These options are only used for those options not otherwise set in an
523 EXPORT {} or CLIENT {} block and are applied when export permissions
524 are evaluated when a new file handle is encountered.
525 The FSAL { Name } may not be changed and FSALs offer limited support
527 for changing any options in the FSAL block. Some FSALs may validate and
528 warn if any options in the FSAL block are changed when such a change is
529 not supported.
530
532 ganesha-config(8) ganesha-rgw-config(8) ganesha-vfs-config(8)
533 ganesha-lustre-config(8) ganesha-xfs-config(8) ganesha-gpfs-config(8)
534 ganesha-9p-config(8) ganesha-proxy-config(8) ganesha-ceph-config(8)
535 Nov 03, 2023 GANESHA-EXPORT-CONFIG(8)