doc: describe smbcacls --propagate-inheritance expanding INHERITANCE section

Signed-off-by: Noel Power <noel.power@suse.com>
Reviewed-by: Jeremy Allison <jra@samba.org>

diff --git a/docs-xml/manpages/smbcacls.1.xml b/docs-xml/manpages/smbcacls.1.xml
index 783171513da42ffb612457e626af5f5b941fe7c7..7efcc087cfda5ab658bc88fd8675d2037c0a2ed1 100644 (file)
--- a/docs-xml/manpages/smbcacls.1.xml
+++ b/docs-xml/manpages/smbcacls.1.xml
@@ -295,18 +295,80 @@ ACL:<sid or name>:<type>/<flags>/<mask>
        <title>INHERITANCE</title>
 
        <para>Per-ACE inheritance flags can be set in the ACE flags field. By
-       default, ACEs marked for object inheritance (OI) or container
-       inheritance (CI) are not propagated to sub-files or folders. However,
-       with the <parameter>--propagate-inheritance</parameter> arguement
-       specified, such ACEs are recursively applied to all applicable child
-       objects in the directory tree.</para>
-
-       <para>Any ACEs applied to sub-files of folders are marked with the
-       inherited (I) flag.</para>
-
+       default, inheritable ACEs e.g. those marked for object inheritance (OI)
+       or container inheritance (CI), are not propagated to sub-files or
+       folders. However, with the
+       <parameter>--propagate-inheritance</parameter> argument specified, such
+       ACEs are automatically propagated according to some inheritance
+       rules.
+       <itemizedlist>
+               <listitem><para>Inheritable (OI)(OI) ACE flags can only be
+               applied to folders. </para></listitem>
+               <listitem><para>Any inheritable ACEs applied to sub-files or
+               folders are marked with the inherited (I) flag. Inheritable
+               ACE(s) are applied to folders unless the no propagation (NP)
+               flag is set. </para>
+               </listitem>
+               <listitem><para>When an ACE with the (OI) flag alone set is
+               progagated to a child folder the inheritance only flag (IO) is
+               also applied. This indicates the permissions associated with
+               the ACE don't apply to the folder itself (only to it's
+               child files). When applying the ACE to a child file the ACE is
+               inherited as normal.</para></listitem>
+               <listitem><para>When an ace with the (CI) flag alone set is
+               propagated to a child file there is no effect, when propagated
+               to a child folder it is inherited as normal.
+               </para></listitem>
+               <listitem><para>When an ACE that has both (OI) &amp; (CI) flags
+               set the ACE is inherited as normal by both folders and
+               files.</para></listitem>
+       </itemizedlist></para>
+<para>(OI)(READ) added to parent folder</para>
+<para><programlisting>
++-parent/        (OI)(READ)
+| +-file.1       (I)(READ)
+| +-nested/      (OI)(IO)(I)(READ)
+  |   +-file.2   (I)(READ)
+</programlisting></para>
+<para>(CI)(READ) added to parent folder</para>
+<para><programlisting>
++-parent/        (CI)(READ)
+| +-file.1
+| +-nested/      (CI)(I)(READ)
+  |   +-file.2
+</programlisting></para>
+<para>(OI)(CI)(READ) added to parent folder</para>
+<para><programlisting>
++-parent/        (OI)(CI)(READ)
+| +-file.1       (I)(READ)
+| +-nested/      (OI)(CI)(I)(READ)
+  |   +-file.2   (I)(READ)
+</programlisting></para>
+<para>(OI)(NP)(READ) added to parent folder</para>
+<para><programlisting>
++-oi_dir/        (OI)(NP)(READ)
+| +-file.1       (I)(READ)
+| +-nested/
+|   +-file.2
+</programlisting></para>
+<para>(CI)(NP)(READ) added to parent folder</para>
+<para><programlisting>
++-oi_dir/        (CI)(NP)(READ)
+| +-file.1
+| +-nested/      (I)(READ)
+|   +-file.2
+</programlisting></para>
+<para>(OI)(CI)(NP)(READ) added to parent folder</para>
+<para><programlisting>
++-parent/        (CI)(OI)(NP)(READ)
+| +-file.1       (I)(READ)
+| +-nested/      (I)(READ)
+|   +-file.2
+</programlisting></para>
        <para>Files and folders with protected ACLs do not allow inheritable
        permissions (set with <parameter>-I</parameter>). Such objects will
        not receive ACEs flagged for inheritance with (CI) or (OI).</para>
+
 </refsect1>
 
 <refsect1>