diff options
Diffstat (limited to 'docs-xml/manpages/vfs_gpfs.8.xml')
| -rw-r--r-- | docs-xml/manpages/vfs_gpfs.8.xml | 429 |
1 files changed, 429 insertions, 0 deletions
diff --git a/docs-xml/manpages/vfs_gpfs.8.xml b/docs-xml/manpages/vfs_gpfs.8.xml new file mode 100644 index 0000000..a7168e4 --- /dev/null +++ b/docs-xml/manpages/vfs_gpfs.8.xml @@ -0,0 +1,429 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<ns:Root xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xmlns:ns="urn:TestNamespace"> +<refentry id="vfs_gpfs.8"> + + +<refmeta> + <refentrytitle>vfs_gpfs</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="source">Samba</refmiscinfo> + <refmiscinfo class="manual">System Administration tools</refmiscinfo> + <refmiscinfo class="version">&doc.version;</refmiscinfo> +</refmeta> + + +<refnamediv> + <refname>vfs_gpfs</refname> + <refpurpose>gpfs specific samba extensions like acls</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>vfs objects = gpfs</command> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This VFS module is part of the + <citerefentry><refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry> suite.</para> + + <para>The <command>gpfs</command> VFS module is the home + for all gpfs extensions that Samba requires for proper integration + with GPFS. It uses the GPL library interfaces provided by GPFS. + </para> + + <para>Currently the gpfs vfs module provides extensions in following areas : + <itemizedlist> + <listitem><para>NFSv4 ACL Interfaces with configurable options for GPFS</para></listitem> + <listitem><para>Kernel oplock support on GPFS</para></listitem> + <listitem><para>Lease support on GPFS</para></listitem> + </itemizedlist> + </para> + + <para><command>NOTE:</command> This module follows the posix-acl behaviour + and hence allows permission stealing via chown. Samba might allow at a later + point in time, to restrict the chown via this module as such restrictions + are the responsibility of the underlying filesystem than of Samba. + </para> + + <para>This module makes use of the smb.conf parameter + <smbconfoption name="acl map full control"></smbconfoption>. + When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD + bit on a returned ACE entry for a file (not a directory) that already + contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD. + This can prevent Windows applications that request GENERIC_ALL access + from getting ACCESS_DENIED errors when running against a filesystem + with NFSv4 compatible ACLs. + </para> + + <para>This module is stackable.</para> + + <para>Since Samba 4.0 all options are per share options.</para> + +</refsect1> + + +<refsect1> + <title>OPTIONS</title> + + <xi:include href="nfs4.xml.include" xpointer="xpointer(*/*)" /> + + <variablelist> + + <varlistentry> + + <term>gpfs:sharemodes = [ yes | no ]</term> + <listitem> + <para> + Enable/Disable cross node sharemode handling for GPFS. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - propagate sharemodes across all GPFS nodes. + </para></listitem> + <listitem><para> + <command>no</command> - do not propagate sharemodes across all GPFS nodes. + This should only be used if the GPFS file system is + exclusively exported by Samba. Access by local unix application or + NFS exports could lead to corrupted files. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:leases = [ yes | no ]</term> + <listitem> + <para> + Enable/Disable cross node leases (oplocks) for GPFS. + You should also set the <command>oplocks</command> and <command>kernel oplocks</command> + options to the same value. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - propagate leases across all GPFS nodes. + </para></listitem> + <listitem><para> + <command>no</command> - do not propagate leases across all GPFS nodes. + This should only be used if the GPFS file system is + exclusively exported by Samba. Access by local unix application or + NFS exports could lead to corrupted files. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + + <varlistentry> + + <term>gpfs:hsm = [ yes | no ]</term> + <listitem> + <para> + Enable/Disable announcing if this FS has HSM enabled. + </para> + + <itemizedlist> + <listitem><para> + <command>no(default)</command> - Do not announce HSM. + </para></listitem> + <listitem><para> + <command>yes</command> - Announce HSM. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + + <varlistentry> + <term>gpfs:recalls = [ yes | no ]</term> + <listitem> + <para> When this option is set to no, an attempt to + open an offline file will be rejected with access + denied. This helps preventing recall storms triggered + by careless applications like Finder and + Explorer.</para> + + <itemizedlist> + <listitem><para><command>yes(default)</command> - Open + files that are offline. This will recall the files + from HSM.</para></listitem> + <listitem><para><command>no</command> - Reject access + to offline files with access denied. This will prevent + recalls of files from HSM. Using this setting also + requires gpfs:hsm to be set to yes.</para></listitem> + </itemizedlist> + + </listitem> + </varlistentry> + + <varlistentry> + + <term>gpfs:getrealfilename = [ yes | no ]</term> + <listitem> + <para> + Enable/Disable usage of the <command>gpfs_get_realfilename_path()</command> function. + This improves the casesensitive wildcard file name access. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - use <command>gpfs_get_realfilename_path()</command>. + </para></listitem> + <listitem><para> + <command>no</command> - do not use <command>gpfs_get_realfilename_path()</command>. + It seems that <command>gpfs_get_realfilename_path()</command> doesn't work on AIX. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:winattr = [ yes | no ]</term> + <listitem> + <para> + Enable/Disable usage of the windows attributes in GPFS. + GPFS is able to store windows file attributes e.g. HIDDEN, + READONLY, SYSTEM and others natively. That means Samba doesn't + need to map them to permission bits or extended attributes. + </para> + + <itemizedlist> + <listitem><para> + <command>no(default)</command> - do not use GPFS windows attributes. + </para></listitem> + <listitem><para> + <command>yes</command> - use GPFS windows attributes. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:acl = [ yes | no ]</term> + <listitem> + <para> + This option lets Samba use or ignore GPFS ACLs. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - use GPFS ACLs. + </para></listitem> + <listitem><para> + <command>no</command> - do not use GPFS ACLs and pass everything + to the next SMB_VFS module. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:check_fstype = [ yes | no ]</term> + <listitem> + <para> + Check for a mounted GPFS file system on access to a SMB share. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - Check that the SMB share path + is on a GPFS file system. Share access will be denied when a + different file system is found. + </para></listitem> + <listitem><para> + <command>no</command> - skip check for GPFS file system on SMB + share path. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:refuse_dacl_protected = [ yes | no ]</term> + <listitem> + <para> + As GPFS does not support the ACE4_FLAG_NO_PROPAGATE NFSv4 flag (which would be + the mapping for the DESC_DACL_PROTECTED flag), the status of this flag is + currently silently ignored by Samba. That means that if you deselect the "Allow + inheritable permissions..." checkbox in Windows' ACL dialog and then apply the + ACL, the flag will be back immediately. + </para> + <para> + To make sure that automatic migration with e.g. robocopy does not lead to + ACLs silently (and unintentionally) changed, you can set + <command>gpfs:refuse_dacl_protected = yes</command> to enable an explicit + check for this flag and if set, it will return NT_STATUS_NOT_SUPPORTED so + errors are shown up on the Windows side and the Administrator is aware of + the ACLs not being settable like intended + </para> + + <itemizedlist> + <listitem><para> + <command>no(default)</command> - ignore the DESC_DACL_PROTECTED flags. + </para></listitem> + <listitem><para> + <command>yes</command> - reject ACLs with DESC_DACL_PROTECTED. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:dfreequota = [ yes | no ]</term> + <listitem> + <para> + Adjust reporting of the size and free space of a share + according to quotas. If this setting is "yes", a + request for size and free space will also evaluate the + user quota of the user requesting the data and the + group quota of the primary group of the user. Fileset + quotas are not queried, since GPFS already provides + the option --dfreequota to reflect the fileset quota + in the free space query. Please use that option to + include fileset quotas in the reported disk space. + </para> + + <para> + If any of the soft or hard quota limits has been + reached, the free space will be reported as 0. If a + quota is in place, but the limits have not been + reached, the free space will be reported according to + the space left in the quota. If more than one quota + applies the free space will be reported as the smallest + space left in those quotas. The size of the share + will be reported according to the quota usage. If more + than one quota applies, the smallest size will be + reported for the share size according to these quotas. + </para> + + <itemizedlist> + <listitem><para> + <command>yes</command> - include the quotas + when reporting the share size and free space + </para></listitem> + <listitem><para> + <command>no(default)</command> - do not include quotas, + simply report the size and free space of the file system + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + <varlistentry> + + <term>gpfs:settimes = [ yes | no ]</term> + <listitem> + <para> + Use the gpfs_set_times API when changing the + timestamps of a file or directory. If the GPFS API is + not available the old method of using utime and the + GPFS winattr call will be used instead. + </para> + + <itemizedlist> + <listitem><para> + <command>yes(default)</command> - Use gpfs_set_times. + Fall back to utime and winattr when it is not available. + </para></listitem> + <listitem><para> + <command>no</command> - Do not use gpfs_set_times. + </para></listitem> + </itemizedlist> + </listitem> + + </varlistentry> + + <varlistentry> + <term>gpfs:syncio = [yes|no]</term> + <listitem> + <para>This parameter makes Samba open all files with O_SYNC. + This triggers optimizations in GPFS for workloads that + heavily share files.</para> + + <para>Following is the behaviour of Samba for different + values: + </para> + <itemizedlist> + <listitem><para><command>yes</command> - Open files with O_SYNC + </para></listitem> + <listitem><para><command>no (default)</command> - Open files as + normal Samba would do + </para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + </variablelist> + +</refsect1> + +<refsect1> + <title>EXAMPLES</title> + + <para>A GPFS mount can be exported via Samba as follows :</para> + +<programlisting> + <smbconfsection name="[samba_gpfs_share]"/> + <smbconfoption name="vfs objects">gpfs</smbconfoption> + <smbconfoption name="path">/test/gpfs_mount</smbconfoption> + <smbconfoption name="nfs4: mode">special</smbconfoption> + <smbconfoption name="nfs4: acedup">merge</smbconfoption> +</programlisting> +</refsect1> + +<refsect1> + <title>CAVEATS</title> + <para> + Depending on the version of gpfs, the <command>libgpfs_gpl</command> + library or the <command>libgpfs</command> library is needed at + runtime by the <command>gpfs</command> VFS module: + Starting with gpfs 3.2.1 PTF8, the complete <command>libgpfs</command> + is available as open source and <command>libgpfs_gpl</command> does no + longer exist. With earlier versions of gpfs, only the + <command>libgpfs_gpl</command> library was open source and could be + used at run time. + </para> + <para> + At build time, only the header file <command>gpfs_gpl.h</command> + is required, which is a symlink to <command>gpfs.h</command> in + gpfs versions newer than 3.2.1 PTF8. + </para> +</refsect1> + +<refsect1> + <title>VERSION</title> + <para>This man page is part of version &doc.version; of the Samba suite. + </para> +</refsect1> + +<refsect1> + <title>AUTHOR</title> + + <para>The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed.</para> + + <para>The GPFS VFS module was created with contributions from + Volker Lendecke and the developers at IBM. + </para> + + <para> This manpage was created by the IBM FSCC team </para> +</refsect1> + +</refentry> +</ns:Root> |