Updated smbcacls documentation.

(This used to be commit bd87398b5a9421add8db8b455d02ccd6b2624f58)

1 files changed, 94 insertions, 9 deletions

diff --git a/docs/manpages/smbcacls.1 b/docs/manpages/smbcacls.1
index 69e9a92ef4..52b6a6ce3f 100644
--- a/docs/manpages/smbcacls.1
+++ b/docs/manpages/smbcacls.1
@@ -1,7 +1,7 @@
 .TH "smbcacls " "1" "3 Dec 2000" "Samba" "SAMBA" 
 .PP 
 .SH "NAME" 
-smbcacls \- Set or get ACLs on an NT file
+smbcacls \- Set or get ACLs on an NT file or directory 
 .PP 
 .SH "SYNOPSIS" 
 .PP 
@@ -17,28 +17,31 @@ SMB file shares\&.
 .PP 
 .SH "OPTIONS" 
 .PP 
-The following options are available to the \fBsmbcacls\fP program:
+The following options are available to the \fBsmbcacls\fP program\&.  The
+format of ACLs is described in the section ACL FORMAT
 .PP 
 .IP 
 .IP "\fB-A acls\fP" 
 .IP 
-Add the ACLs specified to the ACL list\&.
+Add the ACLs specified to the ACL list\&.  Existing access control entries
+are unchanged\&.
 .IP 
 .IP "\fB-M acls\fP" 
 .IP 
 Modify the mask value (permissions) for the ACLs specified on the command
-line\&.  An error will be printed if the ACL specified is not already present
-in the ACL list
+line\&.  An error will be printed for each ACL specified that was not already
+present in the ACL list\&.
 .IP 
 .IP "\fB-D acls\fP" 
 .IP 
-Delete any ACLs specfied on the command line\&.  An error is printed if any
-of the ACLs specified are not present in the ACL list\&.
+Delete any ACLs specfied on the command line\&.  An error will be printed for
+each ACL specified that was not already present in the ACL list\&.
 .IP 
 .IP "\fB-S acls\fP" 
 .IP 
-This command deletes the current ACLs for the file or directory and
-replaces them with the ACLs specified on the command line\&.
+This command sets the ACLs on the file with only the ones specified on the
+command line\&.  All other ACLs are erased\&.  Note that the ACL specified must
+contain at least a revision, type, owner and group for the call to succeed\&.
 .IP 
 .IP "\fB-U username\fP" 
 .IP 
@@ -60,6 +63,88 @@ format\&.
 Print usage information on the \fBsmbcacls\fP program
 .IP 
 .PP 
+.SH "ACL FORMAT" 
+.PP 
+The format of an ACL is one or more ACL entries separated by either spaces,
+commas or newlines\&.  An ACL entry is one of the following:
+.PP 
+
+.nf 
+ 
+
+REVISION:<revision number>
+OWNER:<sid or name>
+GROUP:<sid or name>
+ACL:<sid or name>:<type>/<flags>/<mask>
+.fi 
+ 
+
+.PP 
+The revision of the ACL specifies the internal Windows NT ACL revision for
+the security descriptor\&.  If not specified it defaults to 1\&.
+.PP 
+The owner and group specify the owner and group sids for the object\&.  If a
+SID in the format \f(CWS-1-x-y-z\fP is specified this is used, otherwise
+the name specified is resolved using the server on which the file or
+directory resides\&. 
+.PP 
+ACLs specify permissions granted to the SID\&.  This SID again can be
+specified in \f(CWS-1-x-y-z\fP format or as a name in which case it is resolved
+against the server on which the file or directory resides\&.  The type, flags
+and mask values determine the type of access granted to the SID\&.
+.PP 
+The type can be either 0 or 1 corresponding to ALLOWED or DENIED access to
+the SID\&.  The flags values are generally zero for file ACLs and either 9 or
+2 for directory ACLs\&.  Some common flags are:
+.PP 
+
+.nf 
+ 
+
+#define SEC_ACE_FLAG_OBJECT_INHERIT     	0x1
+#define SEC_ACE_FLAG_CONTAINER_INHERIT  	0x2
+#define SEC_ACE_FLAG_NO_PROPAGATE_INHERIT       0x4
+#define SEC_ACE_FLAG_INHERIT_ONLY       	0x8
+.fi 
+ 
+
+.PP 
+The mask is a value which expresses the access right granted to
+the SID\&.  It can be given as a hexadecimal value or by using one of the
+following text strings which map to the NT file permissions of the same
+name\&. 
+.PP 
+.IP 
+.IP "" 
+\f(CWR\fP 	Allow read access
+.IP 
+.IP "" 
+\f(CWW\fP 	Allow write access
+.IP 
+.IP "" 
+\f(CWX\fP 	Execute permission on the object
+.IP 
+.IP "" 
+\f(CWD\fP 	Delete the object
+.IP 
+.IP "" 
+\f(CWP\fP 	Change permissions
+.IP 
+.IP "" 
+\f(CWO\fP	Take ownership
+.IP 
+.PP 
+The following combined permissions can be specified:
+.PP 
+.IP 
+.IP "" 
+\f(CWREAD\fP	 Equivalent to \f(CWRX\fP permissions
+.IP "" 
+\f(CWCHANGE\fP Equivalent to \f(CWRXWD\fP permissions
+.IP "" 
+\f(CWFULL\fP   Equivalent to \f(CWRWXDPO\fP permissions
+.IP 
+.PP 
 .SH "EXIT STATUS" 
 .PP 
 .SH "AUTHOR"