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 [3,4])
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 betweem 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 dunamically 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
140 PrefWrite (64*1024*1024)
142 The preferred write size on this export
143 PrefReaddir (16384)
145 The preferred readdir size on this export
146 MaxOffsetWrite (INT64_MAX)
148 Maximum file offset that may be written Range is 512 to
149 UINT64_MAX
150 MaxOffsetRead (INT64_MAX)
152 Maximum file offset that may be read Range is 512 to UINT64_MAX
153 CLIENT (optional)
155 See the EXPORT { CLIENT {} } block.
156 FSAL (required)
158 See the EXPORT { FSAL {} } block.
159 The FSAL for an export can not be changed dynamically. In order
161 to change the FSAL, a new export must be created.
162 At this time, no FSAL actually supports any updatable options.
164 EXPORT { CLIENT {} }
166 Take all the "export permissions" options from EXPORT_DEFAULTS. The
167 client lists are dynamically updateable.
168 These blocks form an ordered "access control list" for the export. If
170 no client block matches for a particular client, then the permissions
171 in the EXPORT {} block will be used.
172 Even when a CLIENT block matches a client, if a particular export per‐
174 mission is not explicit in that CLIENT block, the permission specified
175 in the EXPORT block will be used, or if not specified there, from the
176 EXPORT_DEFAULTS block, and if not specified there, the permission will
177 default to the default code value noted in the permission option de‐
178 scriptions above.
179 Note that when the CLIENT blocks are processed on config reload, a new
181 client access list is constructed and atomically swapped in. This al‐
182 lows adding, removing, and re-arranging clients as well as changing the
183 access for any give client.
184 Clients(client list, empty)
186 Client list entries can take on one of the following forms:
187 Match any client:
188 @name Netgroup name
190 x.x.x.x/y IPv4 network address
191 wildcarded If the string contains at least one ? or *
192 character (and is not simply "*"), the string is
193 used to pattern match host names. Note that [] may
194 also be used, but the pattern MUST have at least one
195 ? or *
196 hostname Match a single client (match is by IP address, all
197 addresses returned by getaddrinfo will match, the
198 getaddrinfo call is made at config parsing time)
199 IP address Match a single client
200 EXPORT { FSAL {} }
202 NFS-Ganesha supports the following FSALs: Ceph Gluster GPFS PROXY_V3
203 PROXY_V4 RGW VFS XFS LUSTRE LIzardFS KVSFS
204 Refer to individual FSAL config file for list of config options.
206 The FSAL blocks generally are less updatable
208
210 The EXPORT blocks define the file namespaces that are served by
211 NFS-Ganesha.
212 In best practice, each underlying filesystem has a single EXPORT defin‐
214 ing how that filesystem is to be shared, however, in some cases, it is
215 desirable to sub-divide a filesystem into multiple exports. The danger
216 when this is done is that rogue clients may be able to spoof file han‐
217 dles and access portions of the filesystem not intended to be accessi‐
218 ble to that client.
219 Some FSALs (currently FSAL_VFS, FSAL_GPFS, FSAL_XFS, and FSAL_LUSTRE)
221 are built to support nested filesystems, for example:
222 /export/fs1 /export/fs1/some/path/fs2
223 In this case, it is possible to create a single export that exports
225 both filesystems. There is a lot of complexity of what can be done
226 there.
227 In discussions of filesystems, btrfs filesystems exported by FSAL_VFS
229 may have subvolumes. Starting in NFS-Ganesha V4.0 FSAL_VFS treats these
230 as separate filesystems that are integrated with all the richness of
231 FSAL_VFS exports.
232 Another significant FSAL from an export point of view is FSAL_PSEUDO.
234 This is used to build glue exports to build the unified NFSv4 name
235 space. This name space may also be used by NFSv3 by setting the
236 NFS_CORE_PARAM option:
237 mount_path_pseudo = TRUE;
238 If no FSAL_PSEUDO export is explicitly defined, and there is no EXPORT
240 with:
241 Pseudo = "/";
242 NFS-Ganesha will build a FSAL_PSEUDO EXPORT with this Pseudo Path using
244 Export_Id = 0. This automatic EXPORT may be replaced with an explicit
245 EXPORT which need not have Export_Id = 0, it just must have Pseudo =
246 "/" and Protocols = 4.
247 In building the Pseudo Filesystem, there is a subtle gotcha. Since
249 NFSv4 clients actually moount the root of the Pseudo Filesystem and
250 then use LOOKUP to traverse into the actual directory the sysadmin has
251 mounted from the client, any EXPORTs from "/" to the desired EXPORT
252 MUST have Protocols = 4 specified either in EXPORT_DEFAULTS {}, EXPORT
253 {}, or EXPORT { CLIENT {} }. This is to assure that the client is al‐
254 lowed to traverse each EXPORT.
255 If Mount_Path_Pseudo = TRUE is being used and an export is desired to
257 be NFSv3 only, Protocols = 3 MUST be specified in the EXPORT {} block.
258 If Protocols is not specified in the EXPORT {} block and is only speci‐
259 fied in an EXPORT { CLIENT {} } block, then that export will still be
260 mounted in the Pseudo Filesystem but might not be traversable. Thus if
261 the following two filesystems are exported:
262 /export/fs1 /export/fs1/some/path/fs2
263 And the EXPORTs look something like this:
265 EXPORT {
266 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1;
267 FSAL {
269 Name = VFS;
270 }
272 CLIENT {
274 Clients="*"; Protocols=3;
275 }
277 }
279 EXPORT {
281 Export_Id = 1; Path = /export/fs1/some/path/fs2; Peudo = /ex‐
282 port/fs1/some/path/fs2;
283 FSAL {
285 Name = VFS;
286 }
288 CLIENT {
290 Clients="*"; Protocols=3,4;
291 }
293 }
295 NFSv4 clients will not be able to access /export/fs1/some/path/fs2. The
297 correct way to accomplish this is:
298 EXPORT {
299 Export_Id = 1; Path = /export/fs1; Peudo = /export/fs1; Pro‐
300 tocols=3;
301 FSAL
303 { Name = VFS;
305 }
307 }
309 Note that an EXPORT { CLIENT {} } block is not necessary if the default
311 export pernmissions are workable.
312 Note that in order for an EXPORT to be usable with NSFv4 it MUST either
314 have Protcols = 4 specified in the EXPORT block, or the EXPORT block
315 must not have the Protocols option at all such that it defaults to
316 3,4,9P. Note though that if it is not set and EXPORT_DEFAULTS just has
317 Protocols = 3; then even though the export is mounted in the Pseudo
318 Filesystem, it will not be accessible and the gotcha discussed above
319 may be in play.
320
322 In addition to the LOG {} configuration, EXPORT {} config is the main
323 configuration that can be updated while NFS-Ganesha is running by issu‐
324 ing a SIGHUP.
325 This causes all EXPORT and EXPORT_DEFAULTS blocks to be reloaded.
327 NFS-Ganesha V4.0 and later have some significant improvements to this
328 since it was introduced in NFS-Ganesha V2.4.0. V2.8.0 introduced the
329 ability to remove EXPORTs via SIGHUP configuration reload.
330 Significantly how things work now is:
332 On SIGHUP all the EXPORT and EXPORT_DEFAULTS blocks are re-read. There
334 are three conditions that may occur:
335 An export may be added An export may be removed An export may be up‐
336 dated
337 A note on Export_Id and Path. These are the primary options that define
339 an export. If Export_Id is changed, the change is treated as a remove
340 of the old Export_Id and an addition of the new Export_Id. Path can not
341 be changed without also changing Export_Id. The Tag and Pseudo options
342 that also contribute to the uniqueness of an EXPORT may be changed.
343 Any removed exports are removed from the internal tables and if they
345 are NFSv4 exports, unmounted from the Pseudo Filesystem, which will
346 then be re-built as if those exports had not been present.
347 Any new exports are added to the internal tables, and if the export is
349 an NFSv4 export, they are mounted into the Pseudo Filesystem.
350 Any updated exports will be modified with the least disruption possi‐
352 ble. If the Pseduo option is changed, the export is unmounted from the
353 Pseduo Filesystem in it's original location, and re-mounted in it's new
354 location. Other options are updated atomically, though serially, so for
355 a short period of time, the options may be mixed between old and new.
356 In most cases this should not cause problems. Notably though, the
357 CLIENT blocks are processed to form a new access control list and that
358 list is atomically swapped with the old list. If the Protocols for an
359 EXPORT are changed to include or remove NFSv4, the Pseduo Filesystem
360 will also be updated.
361 Note that there is no pause in operations other than a lock being taken
363 when the client list is being swapped out, however the export permis‐
364 sions are applied to an operation once. Notably for NFSv4, this is on a
365 PUTFH or LOOKUP which changes the Current File Handle. As an example,
366 if a write is in progress, having passed the permission check with the
367 previous export permissions, the write will complete without interrup‐
368 tion. If the write is part of an NFSv4 COMPOUND, the other operations
369 in that COMPOUND that operate on the same file handle will also com‐
370 plete with the previous export permissions.
371 An update of EXPORT_DEFAULTS changes the export options atomically.
373 These options are only used for those options not otherwise set in an
374 EXPORT {} or CLIENT {} block and are applied when export permissions
375 are evaluated when a new file handle is encountered.
376 The FSAL { Name } may not be changed and FSALs offer limited support
378 for changing any options in the FSAL block. Some FSALs may validate and
379 warn if any options in the FSAL block are changed when such a change is
380 not supported.
381
383 ganesha-config(8) ganesha-rgw-config(8) ganesha-vfs-config(8) gane‐
384 sha-lustre-config(8) ganesha-xfs-config(8) ganesha-gpfs-config(8) gane‐
385 sha-9p-config(8) ganesha-proxy-config(8) ganesha-ceph-config(8)
386 Jan 28, 2023 GANESHA-EXPORT-CONFIG(8)