docs-xml/manpages/vfs_gpfs.8.xml

   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.6</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>