docs-xml: some fixes to acl parameter documentation

Signed-off-by: Bjoern Jacke <bjacke@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
Autobuild-User(master): Jeremy Allison <jra@samba.org>
Autobuild-Date(master): Thu Oct  6 23:04:51 UTC 2022 on sn-devel-184

diff --git a/docs-xml/manpages/vfs_acl_xattr.8.xml b/docs-xml/manpages/vfs_acl_xattr.8.xml
index 5a26359fa26b72a31a7d2026037f78aca1e37d04..bb72f3facc6e1c9917fa7f1a13b60ad174b54853 100644 (file)
--- a/docs-xml/manpages/vfs_acl_xattr.8.xml
+++ b/docs-xml/manpages/vfs_acl_xattr.8.xml
@@ -29,16 +29,31 @@
        <citerefentry><refentrytitle>samba</refentrytitle>
        <manvolnum>7</manvolnum></citerefentry> suite.</para>
 
+       <para>This module is made for systems which do not support
+       standardized NFS4 ACLs but only a deprecated POSIX ACL
+       draft implementation. This is usually the case on Linux systems.
+       Systems that do support just use NFSv4 ACLs directly instead
+       of this module. Such support is usually provided by the filesystem
+       VFS module specific to the underlying filesystem that supports
+       NFS4 ACLs
+       </para>
+
        <para>The <command>vfs_acl_xattr</command> VFS module stores
        NTFS Access Control Lists (ACLs) in Extended Attributes (EAs).
        This enables the full mapping of Windows ACLs on Samba
-       servers.
+       servers even if the ACL implementation is not capable of
+       doing so.
        </para>
 
-       <para>The ACLs are stored in the Extended Attribute
-       <parameter>security.NTACL</parameter> of a file or directory.
-       This Attribute is <emphasis>not</emphasis> listed by
-       <command>getfattr -d <filename>filename</filename></command>.
+       <para>The NT ACLs are stored in the
+       <parameter>security.NTACL</parameter> extended attribute of files and
+       directories in a form containing the Windows SID representing the users
+       and groups in the ACL.
+       This is different from the uid and gids stored in local filesystem ACLs
+       and the mapping from users and groups to Windows SIDs must be
+       consistent in order to maintain the meaning of the stored NT ACL
+       That extended attribute is <emphasis>not</emphasis> listed by the Linux
+       command <command>getfattr -d <filename>filename</filename></command>.
        To show the current value, the name of the EA must be specified
        (e.g. <command>getfattr -n security.NTACL <filename>filename</filename>
        </command>).
@@ -85,7 +100,7 @@
                <listitem>
                <para>
                When set to <emphasis>yes</emphasis>, a best effort mapping
-               from/to the POSIX ACL layer will <emphasis>not</emphasis> be
+               from/to the POSIX draft ACL layer will <emphasis>not</emphasis> be
                done by this module. The default is <emphasis>no</emphasis>,
                which means that Samba keeps setting and evaluating both the
                system ACLs and the NT ACLs. This is better if you need your

diff --git a/docs-xml/smbdotconf/filename/mapreadonly.xml b/docs-xml/smbdotconf/filename/mapreadonly.xml
index dae17c25614fdb4f5c059c885b28f6d701263fd2..633b0e958c46bb1e92e4f19df1c903ddd48fa461 100644 (file)
--- a/docs-xml/smbdotconf/filename/mapreadonly.xml
+++ b/docs-xml/smbdotconf/filename/mapreadonly.xml
@@ -32,7 +32,7 @@
                <listitem><para>
                <constant>Permissions</constant> - The read only DOS attribute is mapped to the effective permissions of
                the connecting user, as evaluated by <citerefentry><refentrytitle>smbd</refentrytitle>
-               <manvolnum>8</manvolnum></citerefentry> by reading the unix permissions and POSIX ACL (if present).
+               <manvolnum>8</manvolnum></citerefentry> by reading the unix permissions and filesystem ACL (if present).
                If the connecting user does not have permission to modify the file, the read only attribute
                is reported as being set on the file.
                </para></listitem>

diff --git a/docs-xml/smbdotconf/protocol/ntaclsupport.xml b/docs-xml/smbdotconf/protocol/ntaclsupport.xml
index 1b1f9477906fd220fcca04ff3e73e8e9db54a241..f1577dd86a416efddf602233e0f132c9eb3af3bd 100644 (file)
--- a/docs-xml/smbdotconf/protocol/ntaclsupport.xml
+++ b/docs-xml/smbdotconf/protocol/ntaclsupport.xml
@@ -7,7 +7,7 @@
     <manvolnum>8</manvolnum></citerefentry> will attempt to map 
     UNIX permissions into Windows NT access control lists.  The UNIX
     permissions considered are the traditional UNIX owner and
-    group permissions, as well as POSIX ACLs set on any files or
+    group permissions, as well as filesystem ACLs set on any files or
     directories.  This parameter was formally a global parameter in
     releases prior to 2.2.2.</para>
 </description>