source: vendor/current/docs-xml/manpages/vfs_gpfs.8.xml

Last change on this file was 988, checked in by Silvan Scherrer, 9 years ago

Samba Server: update vendor to version 4.4.3
File size: 15.4 KB
Line 
1<?xml version="1.0" encoding="iso-8859-1"?>
2<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3<refentry id="vfs_gpfs.8">
4
5<refmeta>
6 <refentrytitle>vfs_gpfs</refentrytitle>
7 <manvolnum>8</manvolnum>
8 <refmiscinfo class="source">Samba</refmiscinfo>
9 <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10 <refmiscinfo class="version">4.4</refmiscinfo>
11</refmeta>
12
13
14<refnamediv>
15 <refname>vfs_gpfs</refname>
16 <refpurpose>gpfs specific samba extensions like acls and prealloc</refpurpose>
17</refnamediv>
18
19<refsynopsisdiv>
20 <cmdsynopsis>
21 <command>vfs objects = gpfs</command>
22 </cmdsynopsis>
23</refsynopsisdiv>
24
25<refsect1>
26 <title>DESCRIPTION</title>
27
28 <para>This VFS module is part of the
29 <citerefentry><refentrytitle>samba</refentrytitle>
30 <manvolnum>7</manvolnum></citerefentry> suite.</para>
31
32 <para>The <command>gpfs</command> VFS module is the home
33 for all gpfs extensions that Samba requires for proper integration
34 with GPFS. It uses the GPL library interfaces provided by GPFS.
35 </para>
36
37 <para>Currently the gpfs vfs module provides extensions in following areas :
38 <itemizedlist>
39 <listitem><para>NFSv4 ACL Interfaces with configurable options for GPFS</para></listitem>
40 <listitem><para>Kernel oplock support on GPFS</para></listitem>
41 <listitem><para>Lease support on GPFS</para></listitem>
42 </itemizedlist>
43 </para>
44
45 <para><command>NOTE:</command> This module follows the posix-acl behaviour
46 and hence allows permission stealing via chown. Samba might allow at a later
47 point in time, to restrict the chown via this module as such restrictions
48 are the responsibility of the underlying filesystem than of Samba.
49 </para>
50
51 <para>This module makes use of the smb.conf parameter
52 <smbconfoption name="acl map full control"></smbconfoption>.
53 When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD
54 bit on a returned ACE entry for a file (not a directory) that already
55 contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD.
56 This can prevent Windows applications that request GENERIC_ALL access
57 from getting ACCESS_DENIED errors when running against a filesystem
58 with NFSv4 compatible ACLs.
59 </para>
60
61 <para>This module is stackable.</para>
62
63 <para>Since Samba 4.0 all options are per share options.</para>
64
65</refsect1>
66
67
68<refsect1>
69 <title>OPTIONS</title>
70
71 <variablelist>
72
73 <varlistentry>
74
75 <term>gpfs:sharemodes = [ yes | no ]</term>
76 <listitem>
77 <para>
78 Enable/Disable cross node sharemode handling for GPFS.
79 </para>
80
81 <itemizedlist>
82 <listitem><para>
83 <command>yes(default)</command> - propagate sharemodes across all GPFS nodes.
84 </para></listitem>
85 <listitem><para>
86 <command>no</command> - do not propagate sharemodes across all GPFS nodes.
87 This should only be used if the GPFS file system is
88 exclusively exported by Samba. Access by local unix application or
89 NFS exports could lead to corrupted files.
90 </para></listitem>
91 </itemizedlist>
92 </listitem>
93
94 </varlistentry>
95 <varlistentry>
96
97 <term>gpfs:leases = [ yes | no ]</term>
98 <listitem>
99 <para>
100 Enable/Disable cross node leases (oplocks) for GPFS.
101 You should also set the <command>oplocks</command> and <command>kernel oplocks</command>
102 options to the same value.
103 </para>
104
105 <itemizedlist>
106 <listitem><para>
107 <command>yes(default)</command> - propagate leases across all GPFS nodes.
108 </para></listitem>
109 <listitem><para>
110 <command>no</command> - do not propagate leases across all GPFS nodes.
111 This should only be used if the GPFS file system is
112 exclusively exported by Samba. Access by local unix application or
113 NFS exports could lead to corrupted files.
114 </para></listitem>
115 </itemizedlist>
116 </listitem>
117
118 </varlistentry>
119
120 <varlistentry>
121
122 <term>gpfs:hsm = [ yes | no ]</term>
123 <listitem>
124 <para>
125 Enable/Disable announcing if this FS has HSM enabled.
126 </para>
127
128 <itemizedlist>
129 <listitem><para>
130 <command>no(default)</command> - Do not announce HSM.
131 </para></listitem>
132 <listitem><para>
133 <command>yes</command> - Announce HSM.
134 </para></listitem>
135 </itemizedlist>
136 </listitem>
137
138 </varlistentry>
139
140 <varlistentry>
141 <term>gpfs:recalls = [ yes | no ]</term>
142 <listitem>
143 <para> When this option is set to no, an attempt to
144 open an offline file will be rejected with access
145 denied. This helps preventing recall storms triggered
146 by careless applications like Finder and
147 Explorer.</para>
148
149 <itemizedlist>
150 <listitem><para><command>yes(default)</command> - Open
151 files that are offline. This will recall the files
152 from HSM.</para></listitem>
153 <listitem><para><command>no</command> - Reject access
154 to offline files with access denied. This will prevent
155 recalls of files from HSM. Using this setting also
156 requires gpfs:hsm to be set to yes.</para></listitem>
157 </itemizedlist>
158
159 </listitem>
160 </varlistentry>
161
162 <varlistentry>
163
164 <term>gpfs:getrealfilename = [ yes | no ]</term>
165 <listitem>
166 <para>
167 Enable/Disable usage of the <command>gpfs_get_realfilename_path()</command> function.
168 This improves the casesensitive wildcard file name access.
169 </para>
170
171 <itemizedlist>
172 <listitem><para>
173 <command>yes(default)</command> - use <command>gpfs_get_realfilename_path()</command>.
174 </para></listitem>
175 <listitem><para>
176 <command>no</command> - do not use <command>gpfs_get_realfilename_path()</command>.
177 It seems that <command>gpfs_get_realfilename_path()</command> doesn't work on AIX.
178 </para></listitem>
179 </itemizedlist>
180 </listitem>
181
182 </varlistentry>
183 <varlistentry>
184
185 <term>gpfs:winattr = [ yes | no ]</term>
186 <listitem>
187 <para>
188 Enable/Disable usage of the windows attributes in GPFS.
189 GPFS is able to store windows file attributes e.g. HIDDEN,
190 READONLY, SYSTEM and others natively. That means Samba doesn't
191 need to map them to permission bits or extended attributes.
192 </para>
193
194 <itemizedlist>
195 <listitem><para>
196 <command>no(default)</command> - do not use GPFS windows attributes.
197 </para></listitem>
198 <listitem><para>
199 <command>yes</command> - use GPFS windows attributes.
200 </para></listitem>
201 </itemizedlist>
202 </listitem>
203
204 </varlistentry>
205 <varlistentry>
206
207 <term>gpfs:merge_writeappend = [ yes | no ]</term>
208 <listitem>
209 <para>
210 GPFS ACLs doesn't know about the 'APPEND' right.
211 This option lets Samba map the 'APPEND' right to 'WRITE'.
212 </para>
213
214 <itemizedlist>
215 <listitem><para>
216 <command>yes(default)</command> - map 'APPEND' to 'WRITE'.
217 </para></listitem>
218 <listitem><para>
219 <command>no</command> - do not map 'APPEND' to 'WRITE'.
220 </para></listitem>
221 </itemizedlist>
222 </listitem>
223
224 </varlistentry>
225 <varlistentry>
226
227 <term>gpfs:acl = [ yes | no ]</term>
228 <listitem>
229 <para>
230 This option lets Samba use or ignore GPFS ACLs.
231 </para>
232
233 <itemizedlist>
234 <listitem><para>
235 <command>yes(default)</command> - use GPFS ACLs.
236 </para></listitem>
237 <listitem><para>
238 <command>no</command> - do not use GPFS ACLs and pass everything
239 to the next SMB_VFS module.
240 </para></listitem>
241 </itemizedlist>
242 </listitem>
243
244 </varlistentry>
245 <varlistentry>
246
247 <term>gpfs:refuse_dacl_protected = [ yes | no ]</term>
248 <listitem>
249 <para>
250 As GPFS does not support the ACE4_FLAG_NO_PROPAGATE NFSv4 flag (which would be
251 the mapping for the DESC_DACL_PROTECTED flag), the status of this flag is
252 currently silently ignored by Samba. That means that if you deselect the "Allow
253 inheritable permissions..." checkbox in Windows' ACL dialog and then apply the
254 ACL, the flag will be back immediately.
255 </para>
256 <para>
257 To make sure that automatic migration with e.g. robocopy does not lead to
258 ACLs silently (and unintentionally) changed, you can set
259 <command>gpfs:refuse_dacl_protected = yes</command> to enable an explicit
260 check for this flag and if set, it will return NT_STATUS_NOT_SUPPORTED so
261 errors are shown up on the Windows side and the Administrator is aware of
262 the ACLs not being settable like intended
263 </para>
264
265 <itemizedlist>
266 <listitem><para>
267 <command>no(default)</command> - ignore the DESC_DACL_PROTECTED flags.
268 </para></listitem>
269 <listitem><para>
270 <command>yes</command> - reject ACLs with DESC_DACL_PROTECTED.
271 </para></listitem>
272 </itemizedlist>
273 </listitem>
274
275 </varlistentry>
276 <varlistentry>
277
278 <term>gpfs:dfreequota = [ yes | no ]</term>
279 <listitem>
280 <para>
281 Adjust reporting of the size and free space of a share
282 according to quotas. If this setting is "yes", a
283 request for size and free space will also evaluate the
284 user quota of the user requesting the data and the
285 group quota of the primary group of the user. Fileset
286 quotas are not queried, since GPFS already provides
287 the option --dfreequota to reflect the fileset quota
288 in the free space query. Please use that option to
289 include fileset quotas in the reported disk space.
290 </para>
291
292 <para>
293 If any of the soft or hard quota limits has been
294 reached, the free space will be reported as 0. If a
295 quota is in place, but the limits have not been
296 reached, the free space will be reported according to
297 the space left in the quota. If more than one quota
298 applies the free space will be reported as the smallest
299 space left in those quotas. The size of the share
300 will be reported according to the quota usage. If more
301 than one quota applies, the smallest size will be
302 reported for the share size according to these quotas.
303 </para>
304
305 <itemizedlist>
306 <listitem><para>
307 <command>yes</command> - include the quotas
308 when reporting the share size and free space
309 </para></listitem>
310 <listitem><para>
311 <command>no(default)</command> - do not include quotas,
312 simply report the size and free space of the file system
313 </para></listitem>
314 </itemizedlist>
315 </listitem>
316
317 </varlistentry>
318 <varlistentry>
319
320 <term>gpfs:prealloc = [ yes | no ]</term>
321 <listitem>
322 <para>
323 If set to yes the gpfs_prealloc function will be used in the
324 fallocate callback when appropriate. If set to no gpfs_prealloc
325 will not be used. In both cases the system and libc calls are
326 avoided.
327 </para>
328
329 <itemizedlist>
330 <listitem><para>
331 <command>yes (default)</command> - Use gpfs_prealloc for the
332 fallocate callback.
333 </para></listitem>
334 <listitem><para>
335 <command>no</command> - Do not use gpfs_prealloc for the
336 fallocate callback.
337 </para></listitem>
338 </itemizedlist>
339 </listitem>
340
341 </varlistentry>
342
343 <varlistentry>
344
345 <term>gpfs:settimes = [ yes | no ]</term>
346 <listitem>
347 <para>
348 Use the gpfs_set_times API when changing the
349 timestamps of a file or directory. If the GPFS API is
350 not available the old method of using utime and the
351 GPFS winattr call will be used instead.
352 </para>
353
354 <itemizedlist>
355 <listitem><para>
356 <command>yes(default)</command> - Use gpfs_set_times.
357 Fall back to utime and winattr when it is not available.
358 </para></listitem>
359 <listitem><para>
360 <command>no</command> - Do not use gpfs_set_times.
361 </para></listitem>
362 </itemizedlist>
363 </listitem>
364
365 </varlistentry>
366 <varlistentry>
367
368 <term>nfs4:mode = [ simple | special ]</term>
369 <listitem>
370 <para>
371 Controls substitution of special IDs (OWNER@ and GROUP@) on GPFS.
372 The use of mode simple is recommended.
373 In this mode only non inheriting ACL entries for the file owner
374 and group are mapped to special IDs.
375 </para>
376
377 <para>The following MODEs are understood by the module:</para>
378 <itemizedlist>
379 <listitem><para><command>simple(default)</command> - use OWNER@ and GROUP@ special IDs for non inheriting ACEs only.</para></listitem>
380 <listitem><para><command>special(deprecated)</command> - use OWNER@ and GROUP@ special IDs in ACEs for all file owner and group ACEs.</para></listitem>
381 </itemizedlist>
382 </listitem>
383
384 </varlistentry>
385
386
387 <varlistentry>
388 <term>nfs4:acedup = [dontcare|reject|ignore|merge]</term>
389 <listitem>
390 <para>
391 This parameter configures how Samba handles duplicate ACEs encountered in GPFS ACLs.
392 GPFS allows/creates duplicate ACE for different bits for same ID.
393 </para>
394
395 <para>Following is the behaviour of Samba for different values :</para>
396 <itemizedlist>
397 <listitem><para><command>dontcare (default)</command> - copy the ACEs as they come</para></listitem>
398 <listitem><para><command>reject</command> - stop operation and exit with error on ACL set op</para></listitem>
399 <listitem><para><command>ignore</command> - don't include the second matching ACE</para></listitem>
400 <listitem><para><command>merge</command> - bitwise OR the 2 ace.flag fields and 2 ace.mask fields of the 2 duplicate ACEs into 1 ACE</para></listitem>
401 </itemizedlist>
402 </listitem>
403 </varlistentry>
404
405
406 <varlistentry>
407 <term>nfs4:chown = [yes|no]</term>
408 <listitem>
409 <para>This parameter allows enabling or disabling the chown supported
410 by the underlying filesystem. This parameter should be enabled with
411 care as it might leave your system insecure.</para>
412 <para>Some filesystems allow chown as a) giving b) stealing. It is the latter
413 that is considered a risk.</para>
414
415 <para>Following is the behaviour of Samba for different values : </para>
416 <itemizedlist>
417 <listitem><para><command>yes</command> - Enable chown if as supported by the under filesystem</para></listitem>
418 <listitem><para><command>no (default)</command> - Disable chown</para></listitem>
419 </itemizedlist>
420 </listitem>
421 </varlistentry>
422
423 <varlistentry>
424 <term>gpfs:syncio = [yes|no]</term>
425 <listitem>
426 <para>This parameter makes Samba open all files with O_SYNC.
427 This triggers optimizations in GPFS for workloads that
428 heavily share files.</para>
429
430 <para>Following is the behaviour of Samba for different
431 values:
432 </para>
433 <itemizedlist>
434 <listitem><para><command>yes</command> - Open files with O_SYNC
435 </para></listitem>
436 <listitem><para><command>no (default)</command> - Open files as
437 normal Samba would do
438 </para></listitem>
439 </itemizedlist>
440 </listitem>
441 </varlistentry>
442
443 </variablelist>
444</refsect1>
445
446<refsect1>
447 <title>EXAMPLES</title>
448
449 <para>A GPFS mount can be exported via Samba as follows :</para>
450
451<programlisting>
452 <smbconfsection name="[samba_gpfs_share]"/>
453 <smbconfoption name="vfs objects">gpfs</smbconfoption>
454 <smbconfoption name="path">/test/gpfs_mount</smbconfoption>
455 <smbconfoption name="nfs4: mode">special</smbconfoption>
456 <smbconfoption name="nfs4: acedup">merge</smbconfoption>
457</programlisting>
458</refsect1>
459
460<refsect1>
461 <title>CAVEATS</title>
462 <para>
463 Depending on the version of gpfs, the <command>libgpfs_gpl</command>
464 library or the <command>libgpfs</command> library is needed at
465 runtime by the <command>gpfs</command> VFS module:
466 Starting with gpfs 3.2.1 PTF8, the complete <command>libgpfs</command>
467 is available as open source and <command>libgpfs_gpl</command> does no
468 longer exist. With earlier versions of gpfs, only the
469 <command>libgpfs_gpl</command> library was open source and could be
470 used at run time.
471 </para>
472 <para>
473 At build time, only the header file <command>gpfs_gpl.h</command>
474 is required, which is a symlink to <command>gpfs.h</command> in
475 gpfs versions newer than 3.2.1 PTF8.
476 </para>
477</refsect1>
478
479<refsect1>
480 <title>VERSION</title>
481 <para>This man page is correct for version 3.0.25 of the Samba suite.
482 </para>
483</refsect1>
484
485<refsect1>
486 <title>AUTHOR</title>
487
488 <para>The original Samba software and related utilities
489 were created by Andrew Tridgell. Samba is now developed
490 by the Samba Team as an Open Source project similar
491 to the way the Linux kernel is developed.</para>
492
493 <para>The GPFS VFS module was created with contributions from
494 Volker Lendecke and the developers at IBM.
495 </para>
496
497 <para> This manpage was created by the IBM FSCC team </para>
498</refsect1>
499
500</refentry>
Note: See TracBrowser for help on using the repository browser.