1GANESHA-EXPORT-CONFIG(8) NFS-Ganesha GANESHA-EXPORT-CONFIG(8)
2
3
4
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
15 This file lists NFS-Ganesha Export block config options.
16
17 EXPORT PERMISSIONS
18 These options are all "export permissions" options, and are available
19 in EXPORT_DEFAULTS {}, EXPORT {} and CLIENT {} blocks.
20
21 These options will all be dynamically updateable.
22
23 Access_Type(enum, default None)
24
25 Possible values:
26 None, RW, RO, MDONLY, MDONLY_RO
27
28 Protocols(enum list, default none)
29
30 Possible values:
31 3, 4, NFS3, NFS4, V3, V4, NFSv3, NFSv4, 9P
32
33 Transports(enum list, values [UDP, TCP, RDMA], default [UDP, TCP])
34
35 Anonymous_uid(anonid, range INT32_MIN to UINT32_MAX, default -2)
36
37 Anonymous_gid(anonid, range INT32_MIN to UINT32_MAX, default -2)
38
39 SecType(enum list, default [none, sys])
40
41 Possible values:
42 none, sys, krb5, krb5i, krb5p
43
44 PrivilegedPort(bool, default false)
45
46 Manage_Gids(bool, default false)
47
48 Squash(enum, default root_sqaush)
49
50 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
55 Each line of defaults above are synonyms
56
57 NFS_Commit(bool, default false)
58
59 Delegations(enum, default None)
60
61 Possible values:
62 None, read, write, readwrite, r, w, rw
63
64 CLIENT {}
65 CLIENT blocks are used in EXPORT_DEFAULTS {}, EXPORT {}, and PSEUDOFS
66 {} blocks.
67
68 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
76 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
81 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
85 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
92 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
97 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
101 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
109 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
114 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
118 IP address Match a single client
119
120 EXPORT_DEFAULTS {}
121 All the EXPORT PERMISSIONS options plus:
122
123 Attr_Expiration_Time(int32, range -1 to INT32_MAX, default 60)
124
125 CLIENT (optional)
126 See the CLIENT {} block description. There may be any number
127 of these.
128
129 EXPORT_DEFAULTS { CLIENT {} }
130 See the CLIENT {} block description.
131
132 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
136 All the EXPORT_PERMISSIONS plus:
137
138 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
143 Export_id is not dynamic per se, changing it essentially removes
144 the old export and introduces a new export.
145
146 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
151 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
156 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
160 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
166 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
172 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
182 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
189 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
196 This option is not dynamically updatable.
197
198 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
205 This option is not dynamically updateable.
206
207 MaxRead (64*1024*1024)
208 The maximum read size on this export
209
210 MaxWrite (64*1024*1024)
211 The maximum write size on this export
212
213 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
219 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
225 PrefReaddir (16384)
226 The preferred readdir size on this export
227
228 MaxOffsetWrite (INT64_MAX)
229 Maximum file offset that may be written Range is 512 to
230 UINT64_MAX
231
232 MaxOffsetRead (INT64_MAX)
233 Maximum file offset that may be read Range is 512 to UINT64_MAX
234
235 DisableReaddirPlus(bool, default false)
236
237 Trust_Readdir_Negative_Cache(bool, default false)
238
239 The following options may have limits on dynamic effect
240
241 UseCookieVerifier(bool, default true)
242 Updating UseCookieVerifier while a readdir is in progress may
243 result in unexpected behavior.
244
245 Disable_ACL(bool, default false)
246 Disable_ACL is processed at create_export time currently which
247 makes it effectively a static option.
248
249 Security_Label(bool, default false)
250
251 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
256 CLIENT (optional)
257 See the CLIENT {} block description. There may be any number
258 of these.
259
260 FSAL (required)
261 See the EXPORT { FSAL {} } block.
262
263 The FSAL for an export can not be changed dynamically. In order
264 to change the FSAL, a new export must be created.
265
266 At this time, no FSAL actually supports any updatable options.
267
268 EXPORT { CLIENT {} }
269 See the CLIENT {} block description.
270
271 EXPORT { FSAL {} }
272 NFS-Ganesha supports the following FSALs: Ceph Gluster GPFS PROXY_V3
273 PROXY_V4 RGW VFS XFS LUSTRE LIzardFS KVSFS
274
275 Refer to individual FSAL config file for list of config options.
276
277 The FSAL blocks generally are less updatable
278
279 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
285 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
291 An empty PSEUDOFS {} block will produce the same default pseudofs root
292 export as generated if no pseudofs root export is otherwise specified.
293
294 This block is most useful to override a restrictive CLIENT list in EX‐
295 PORT_DEFAULTS {}.
296
297 These options will all be dynamically updateable.
298
299 Access_Type(enum, default MDONLY_RO)
300
301 Possible values:
302 None, MDONLY_RO
303
304 Transports(enum list, values [UDP, TCP, RDMA], default [TCP])
305
306 SecType(enum list, default [none, sys, krb5, krb5i, krb5p])
307
308 Possible values:
309 none, sys, krb5, krb5i, krb5p
310
311 PrivilegedPort(bool, default false)
312
313 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
317 Export_id is not dynamic per se, changing it essentially removes
318 the old export and introduces a new export.
319
320 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
325 This option is not dynamically updateable.
326
327 DisableReaddirPlus(bool, default false)
328
329 Trust_Readdir_Negative_Cache(bool, default false)
330
331 The following options may have limits on dynamic effect
332
333 UseCookieVerifier(bool, default true)
334 Updating UseCookieVerifier while a readdir is in progress may
335 result in unexpected behavior.
336
337 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
342 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
347 PSEUDOFS {
348
349 CLIENT {
350 Clients =
351 *
352 ;
353
354 }
355
356 }
357
359 The EXPORT blocks define the file namespaces that are served by
360 NFS-Ganesha.
361
362 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
369 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
373 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
377 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
382 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
388 If no FSAL_PSEUDO export is explicitly defined, and there is no EXPORT
389 with:
390 Pseudo = "/";
391
392 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
397 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
405 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
413 And the EXPORTs look something like this:
414 EXPORT {
415 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1;
416
417 FSAL {
418 Name = VFS;
419
420 }
421
422 CLIENT {
423 Clients="*"; Protocols=3;
424
425 }
426
427 }
428
429 EXPORT {
430 Export_Id = 1; Path = /export/fs1/some/path/fs2; Peudo = /ex‐
431 port/fs1/some/path/fs2;
432
433 FSAL {
434 Name = VFS;
435
436 }
437
438 CLIENT {
439 Clients="*"; Protocols=3,4;
440
441 }
442
443 }
444
445 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
451 FSAL
452
453 { Name = VFS;
454
455 }
456
457 }
458
459 Note that an EXPORT { CLIENT {} } block is not necessary if the default
460 export permissions are workable.
461
462 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
475 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
480 Significantly how things work now is:
481
482 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
487 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
493 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
497 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
500 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
511 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
521 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
526 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
536
537
538
539 Nov 03, 2023 GANESHA-EXPORT-CONFIG(8)