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 <ns:Root xmlns:xi="http://www.w3.org/2003/XInclude"
   4    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   5    xmlns:ns="urn:TestNamespace">
   6 <refentry id="vfs_gpfs.8">
   7
   8
   9 <refmeta>
  10         <refentrytitle>vfs_gpfs</refentrytitle>
  11         <manvolnum>8</manvolnum>
  12         <refmiscinfo class="source">Samba</refmiscinfo>
  13         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  14         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  15 </refmeta>
  16
  17
  18 <refnamediv>
  19         <refname>vfs_gpfs</refname>
  20         <refpurpose>gpfs specific samba extensions like acls</refpurpose>
  21 </refnamediv>
  22
  23 <refsynopsisdiv>
  24         <cmdsynopsis>
  25                 <command>vfs objects = gpfs</command>
  26         </cmdsynopsis>
  27 </refsynopsisdiv>
  28
  29 <refsect1>
  30         <title>DESCRIPTION</title>
  31
  32         <para>This VFS module is part of the
  33         <citerefentry><refentrytitle>samba</refentrytitle>
  34         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  35
  36         <para>The <command>gpfs</command> VFS module is the home
  37         for all gpfs extensions that Samba requires for proper integration
  38         with GPFS. It uses the GPL library interfaces provided by GPFS.
  39         </para>
  40
  41         <para>Currently the gpfs vfs module provides extensions in following areas :
  42         <itemizedlist>
  43         <listitem><para>NFSv4 ACL Interfaces with configurable options for GPFS</para></listitem>
  44         <listitem><para>Kernel oplock support on GPFS</para></listitem>
  45         <listitem><para>Lease support on GPFS</para></listitem>
  46         </itemizedlist>
  47         </para>
  48
  49         <para><command>NOTE:</command> This module follows the posix-acl behaviour
  50         and hence allows permission stealing via chown. Samba might allow at a later
  51         point in time, to restrict the chown via this module as such restrictions
  52         are the responsibility of the underlying filesystem than of Samba.
  53         </para>
  54
  55         <para>This module makes use of the smb.conf parameter
  56         <smbconfoption name="acl map full control"></smbconfoption>.
  57         When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD
  58         bit on a returned ACE entry for a file (not a directory) that already
  59         contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD.
  60         This can prevent Windows applications that request GENERIC_ALL access
  61         from getting ACCESS_DENIED errors when running against a filesystem
  62         with NFSv4 compatible ACLs.
  63         </para>
  64
  65         <para>This module is stackable.</para>
  66
  67         <para>Since Samba 4.0 all options are per share options.</para>
  68
  69 </refsect1>
  70
  71
  72 <refsect1>
  73         <title>OPTIONS</title>
  74
  75         <xi:include href="nfs4.xml.include" xpointer="xpointer(*/*)" />
  76
  77         <variablelist>
  78
  79                 <varlistentry>
  80
  81                 <term>gpfs:sharemodes = [ yes | no ]</term>
  82                 <listitem>
  83                 <para>
  84                 Enable/Disable cross node sharemode handling for GPFS.
  85                 </para>
  86
  87                 <itemizedlist>
  88                 <listitem><para>
  89                 <command>yes(default)</command> - propagate sharemodes across all GPFS nodes.
  90                 </para></listitem>
  91                 <listitem><para>
  92                 <command>no</command> - do not propagate sharemodes across all GPFS nodes.
  93                 This should only be used if the GPFS file system is
  94                 exclusively exported by Samba. Access by local unix application or
  95                 NFS exports could lead to corrupted files.
  96                 </para></listitem>
  97                 </itemizedlist>
  98                 </listitem>
  99
 100                 </varlistentry>
 101                 <varlistentry>
 102
 103                 <term>gpfs:leases = [ yes | no ]</term>
 104                 <listitem>
 105                 <para>
 106                 Enable/Disable cross node leases (oplocks) for GPFS.
 107                 You should also set the <command>oplocks</command> and <command>kernel oplocks</command>
 108                 options to the same value.
 109                 </para>
 110
 111                 <itemizedlist>
 112                 <listitem><para>
 113                 <command>yes(default)</command> - propagate leases across all GPFS nodes.
 114                 </para></listitem>
 115                 <listitem><para>
 116                 <command>no</command> - do not propagate leases across all GPFS nodes.
 117                 This should only be used if the GPFS file system is
 118                 exclusively exported by Samba. Access by local unix application or
 119                 NFS exports could lead to corrupted files.
 120                 </para></listitem>
 121                 </itemizedlist>
 122                 </listitem>
 123
 124                 </varlistentry>
 125
 126                 <varlistentry>
 127
 128                 <term>gpfs:hsm = [ yes | no ]</term>
 129                 <listitem>
 130                 <para>
 131                 Enable/Disable announcing if this FS has HSM enabled.
 132                 </para>
 133
 134                 <itemizedlist>
 135                 <listitem><para>
 136                 <command>no(default)</command> - Do not announce HSM.
 137                 </para></listitem>
 138                 <listitem><para>
 139                 <command>yes</command> - Announce HSM.
 140                 </para></listitem>
 141                 </itemizedlist>
 142                 </listitem>
 143
 144                 </varlistentry>
 145
 146                 <varlistentry>
 147                 <term>gpfs:recalls = [ yes | no ]</term>
 148                 <listitem>
 149                 <para> When this option is set to no, an attempt to
 150                 open an offline file will be rejected with access
 151                 denied.  This helps preventing recall storms triggered
 152                 by careless applications like Finder and
 153                 Explorer.</para>
 154
 155                 <itemizedlist>
 156                 <listitem><para><command>yes(default)</command> - Open
 157                 files that are offline. This will recall the files
 158                 from HSM.</para></listitem>
 159                 <listitem><para><command>no</command> - Reject access
 160                 to offline files with access denied. This will prevent
 161                 recalls of files from HSM. Using this setting also
 162                 requires gpfs:hsm to be set to yes.</para></listitem>
 163                 </itemizedlist>
 164
 165                 </listitem>
 166                 </varlistentry>
 167
 168                 <varlistentry>
 169
 170                 <term>gpfs:getrealfilename = [ yes | no ]</term>
 171                 <listitem>
 172                 <para>
 173                 Enable/Disable usage of the <command>gpfs_get_realfilename_path()</command> function.
 174                 This improves the casesensitive wildcard file name access.
 175                 </para>
 176
 177                 <itemizedlist>
 178                 <listitem><para>
 179                 <command>yes(default)</command> - use <command>gpfs_get_realfilename_path()</command>.
 180                 </para></listitem>
 181                 <listitem><para>
 182                 <command>no</command> - do not use <command>gpfs_get_realfilename_path()</command>.
 183                 It seems that <command>gpfs_get_realfilename_path()</command> doesn't work on AIX.
 184                 </para></listitem>
 185                 </itemizedlist>
 186                 </listitem>
 187
 188                 </varlistentry>
 189                 <varlistentry>
 190
 191                 <term>gpfs:winattr = [ yes | no ]</term>
 192                 <listitem>
 193                 <para>
 194                 Enable/Disable usage of the windows attributes in GPFS.
 195                 GPFS is able to store windows file attributes e.g. HIDDEN,
 196                 READONLY, SYSTEM and others natively. That means Samba doesn't
 197                 need to map them to permission bits or extended attributes.
 198                 </para>
 199
 200                 <itemizedlist>
 201                 <listitem><para>
 202                 <command>no(default)</command> - do not use GPFS windows attributes.
 203                 </para></listitem>
 204                 <listitem><para>
 205                 <command>yes</command> - use GPFS windows attributes.
 206                 </para></listitem>
 207                 </itemizedlist>
 208                 </listitem>
 209
 210                 </varlistentry>
 211                 <varlistentry>
 212
 213                 <term>gpfs:acl = [ yes | no ]</term>
 214                 <listitem>
 215                 <para>
 216                 This option lets Samba use or ignore GPFS ACLs.
 217                 </para>
 218
 219                 <itemizedlist>
 220                 <listitem><para>
 221                 <command>yes(default)</command> - use GPFS ACLs.
 222                 </para></listitem>
 223                 <listitem><para>
 224                 <command>no</command> - do not use GPFS ACLs and pass everything
 225                 to the next SMB_VFS module.
 226                 </para></listitem>
 227                 </itemizedlist>
 228                 </listitem>
 229
 230                 </varlistentry>
 231                 <varlistentry>
 232
 233                 <term>gpfs:check_fstype = [ yes | no ]</term>
 234                 <listitem>
 235                 <para>
 236                 Check for a mounted GPFS file system on access to a SMB share.
 237                 </para>
 238
 239                 <itemizedlist>
 240                 <listitem><para>
 241                 <command>yes(default)</command> - Check that the SMB share path
 242                 is on a GPFS file system. Share access will be denied when a
 243                 different file system is found.
 244                 </para></listitem>
 245                 <listitem><para>
 246                 <command>no</command> - skip check for GPFS file system on SMB
 247                 share path.
 248                 </para></listitem>
 249                 </itemizedlist>
 250                 </listitem>
 251
 252                 </varlistentry>
 253                 <varlistentry>
 254
 255                 <term>gpfs:dfreequota = [ yes | no ]</term>
 256                 <listitem>
 257                 <para>
 258                 Adjust reporting of the size and free space of a share
 259                 according to quotas. If this setting is "yes", a
 260                 request for size and free space will also evaluate the
 261                 user quota of the user requesting the data and the
 262                 group quota of the primary group of the user. Fileset
 263                 quotas are not queried, since GPFS already provides
 264                 the option --dfreequota to reflect the fileset quota
 265                 in the free space query. Please use that option to
 266                 include fileset quotas in the reported disk space.
 267                 </para>
 268
 269                 <para>
 270                 If any of the soft or hard quota limits has been
 271                 reached, the free space will be reported as 0. If a
 272                 quota is in place, but the limits have not been
 273                 reached, the free space will be reported according to
 274                 the space left in the quota. If more than one quota
 275                 applies the free space will be reported as the smallest
 276                 space left in those quotas. The size of the share
 277                 will be reported according to the quota usage. If more
 278                 than one quota applies, the smallest size will be
 279                 reported for the share size according to these quotas.
 280                 </para>
 281
 282                 <itemizedlist>
 283                 <listitem><para>
 284                 <command>yes</command> - include the quotas
 285                 when reporting the share size and free space
 286                 </para></listitem>
 287                 <listitem><para>
 288                 <command>no(default)</command> - do not include quotas,
 289                 simply report the size and free space of the file system
 290                 </para></listitem>
 291                 </itemizedlist>
 292                 </listitem>
 293
 294                 </varlistentry>
 295                 <varlistentry>
 296
 297                 <term>gpfs:settimes = [ yes | no ]</term>
 298                 <listitem>
 299                 <para>
 300                 Use the gpfs_set_times API when changing the
 301                 timestamps of a file or directory. If the GPFS API is
 302                 not available the old method of using utime and the
 303                 GPFS winattr call will be used instead.
 304                 </para>
 305
 306                 <itemizedlist>
 307                 <listitem><para>
 308                 <command>yes(default)</command> - Use gpfs_set_times.
 309                 Fall back to utime and winattr when it is not available.
 310                 </para></listitem>
 311                 <listitem><para>
 312                 <command>no</command> - Do not use gpfs_set_times.
 313                 </para></listitem>
 314                 </itemizedlist>
 315                 </listitem>
 316
 317                 </varlistentry>
 318
 319                 <varlistentry>
 320                 <term>gpfs:syncio = [yes|no]</term>
 321                 <listitem>
 322                 <para>This parameter makes Samba open all files with O_SYNC.
 323                   This triggers optimizations in GPFS for workloads that
 324                   heavily share files.</para>
 325
 326                 <para>Following is the behaviour of Samba for different
 327                   values:
 328                 </para>
 329                 <itemizedlist>
 330                 <listitem><para><command>yes</command> - Open files with O_SYNC
 331                 </para></listitem>
 332                 <listitem><para><command>no (default)</command> - Open files as
 333                     normal Samba would do
 334                 </para></listitem>
 335                 </itemizedlist>
 336                 </listitem>
 337                 </varlistentry>
 338
 339         </variablelist>
 340
 341 </refsect1>
 342
 343 <refsect1>
 344         <title>EXAMPLES</title>
 345
 346         <para>A GPFS mount can be exported via Samba as follows :</para>
 347
 348 <programlisting>
 349         <smbconfsection name="[samba_gpfs_share]"/>
 350         <smbconfoption name="vfs objects">gpfs</smbconfoption>
 351         <smbconfoption name="path">/test/gpfs_mount</smbconfoption>
 352         <smbconfoption name="nfs4: mode">special</smbconfoption>
 353         <smbconfoption name="nfs4: acedup">merge</smbconfoption>
 354 </programlisting>
 355 </refsect1>
 356
 357 <refsect1>
 358         <title>CAVEATS</title>
 359         <para>
 360         Depending on the version of gpfs, the <command>libgpfs_gpl</command>
 361         library or the <command>libgpfs</command> library is needed at
 362         runtime by the <command>gpfs</command> VFS module:
 363         Starting with gpfs 3.2.1 PTF8, the complete <command>libgpfs</command>
 364         is available as open source and <command>libgpfs_gpl</command> does no
 365         longer exist. With earlier versions of gpfs, only the
 366         <command>libgpfs_gpl</command> library was open source and could be
 367         used at run time.
 368         </para>
 369         <para>
 370         At build time, only the header file <command>gpfs_gpl.h</command>
 371         is required, which is a symlink to <command>gpfs.h</command> in
 372         gpfs versions newer than 3.2.1 PTF8.
 373         </para>
 374 </refsect1>
 375
 376 <refsect1>
 377         <title>VERSION</title>
 378         <para>This man page is part of version &doc.version; of the Samba suite.
 379         </para>
 380 </refsect1>
 381
 382 <refsect1>
 383         <title>AUTHOR</title>
 384
 385         <para>The original Samba software and related utilities
 386         were created by Andrew Tridgell. Samba is now developed
 387         by the Samba Team as an Open Source project similar
 388         to the way the Linux kernel is developed.</para>
 389
 390         <para>The GPFS VFS module was created with contributions from
 391         Volker Lendecke and the developers at IBM.
 392         </para>
 393
 394         <para> This manpage was created by the IBM FSCC team </para>
 395 </refsect1>
 396
 397 </refentry>
 398 </ns:Root>