docs: Rename manpages-3 -> manpages.

This change was suggested by Andrew Bartlett on the samba-technical mailing
list.

Karolin

Autobuild-User(master): Karolin Seeger <kseeger@samba.org>
Autobuild-Date(master): Mon Sep  3 23:35:38 CEST 2012 on sn-devel-104

1 files changed, 443 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 0000000000..526d86d0d0
--- /dev/null
+++ b/docs-xml/manpages/vfs_gpfs.8.xml
@@ -0,0 +1,443 @@
+<?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">
+<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">3.6</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+	<refname>vfs_gpfs</refname>
+	<refpurpose>gpfs specific samba extensions like acls and prealloc</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 is stackable.</para>
+
+	<para>Since Samba 4.0 all options are per share options.</para>
+
+</refsect1>
+
+
+<refsect1>
+	<title>OPTIONS</title>
+
+	<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: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:merge_writeappend = [ yes | no ]</term>
+		<listitem>
+		<para>
+		GPFS ACLs doesn't know about the 'APPEND' right.
+		This option lets Samba map the 'APPEND' right to 'WRITE'.
+		</para>
+
+		<itemizedlist>
+		<listitem><para>
+		<command>yes(default)</command> - map 'APPEND' to 'WRITE'.
+		</para></listitem>
+		<listitem><para>
+		<command>no</command> - do not map 'APPEND' to 'WRITE'.
+		</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: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, the group
+		quota of the primary group of the user and the fileset
+		quota for the fileset containing the top level
+		directory of the share.
+		</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:prealloc = [ yes | no ]</term>
+		<listitem>
+		<para>
+		If set to yes the gpfs_prealloc function will be used in the
+		fallocate callback when appropriate. If set to no gpfs_prealloc
+		will not be used. In both cases the system and libc calls are
+		avoided.
+		</para>
+
+		<itemizedlist>
+		<listitem><para>
+		<command>yes (default)</command> - Use gpfs_prealloc for the
+		fallocate callback.
+		</para></listitem>
+		<listitem><para>
+		<command>no</command> - Do not use gpfs_prealloc for the
+		fallocate callback.
+		</para></listitem>
+		</itemizedlist>
+		</listitem>
+
+		</varlistentry>
+
+		<varlistentry>
+
+		<term>nfs4:mode = [ simple | special ]</term>
+		<listitem>
+		<para>
+		Enable/Disable substitution of special IDs on GPFS. This parameter
+		should not affect the windows users in anyway. It only ensures that Samba
+		sets the special IDs - OWNER@ and GROUP@ ( mappings to simple uids )
+		that are relevant to GPFS.
+		</para>
+
+		<para>The following MODEs are understood by the module:</para>
+		<itemizedlist>
+		<listitem><para><command>simple(default)</command> - do not use special IDs in GPFS ACEs</para></listitem>
+		<listitem><para><command>special</command> - use special IDs in GPFS ACEs. </para> </listitem>
+		</itemizedlist>
+		</listitem>
+
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>nfs4:acedup = [dontcare|reject|ignore|merge]</term>
+		<listitem>
+		<para>
+		This parameter configures how Samba handles duplicate ACEs encountered in GPFS ACLs.
+		GPFS allows/creates duplicate ACE for different bits for same ID.
+		</para>
+
+		<para>Following is the behaviour of Samba for different values :</para>
+		<itemizedlist>
+		<listitem><para><command>dontcare (default)</command> - copy the ACEs as they come</para></listitem>
+		<listitem><para><command>reject</command> - stop operation and exit with error on ACL set op</para></listitem>
+		<listitem><para><command>ignore</command> - don't include the second matching ACE</para></listitem>
+		<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>
+		</itemizedlist>
+		</listitem>
+		</varlistentry>
+
+
+		<varlistentry>
+		<term>nfs4:chown = [yes|no]</term>
+		<listitem>
+		<para>This parameter allows enabling or disabling the chown supported
+		by the underlying filesystem. This parameter should be enabled with
+		care as it might leave your system insecure.</para>
+		<para>Some filesystems allow chown as a) giving b) stealing. It is the latter
+		that is considered a risk.</para>
+
+		<para>Following is the behaviour of Samba for different values : </para>
+		<itemizedlist>
+		<listitem><para><command>yes</command> - Enable chown if as supported by the under filesystem</para></listitem>
+		<listitem><para><command>no (default)</command> - Disable chown</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 correct for version 3.0.25 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>