PERFORCE change 146322 for review

[Edward Tomasz Napierala]

http://perforce.freebsd.org/chv.cgi?CH=146322

Change 146322 by trasz at trasz_traszkan on 2008/07/31 14:52:37

	Update setfacl(1) manual page.  Needs to be revised.

Affected files ...

.. //depot/projects/soc2008/trasz_nfs4acl/TODO#24 edit
.. //depot/projects/soc2008/trasz_nfs4acl/bin/setfacl/setfacl.1#3 edit

Differences ...

==== //depot/projects/soc2008/trasz_nfs4acl/TODO#24 (text+ko) ====

@@ -1,6 +1,6 @@
 Things to do, in no particular order:
 
-- Update setfacl(1) manual page.
+- Make setfacl(1) error messages more user friendly.
 
 - Either add or extend existing manual pages for new API routines:
   acl_add_flag_np, acl_clear_flags_np, acl_create_entry_np, acl_delete_entry_np,

==== //depot/projects/soc2008/trasz_nfs4acl/bin/setfacl/setfacl.1#3 (text+ko) ====

@@ -33,6 +33,7 @@
 .Nd set ACL information
 .Sh SYNOPSIS
 .Nm
+.Op Fl a Ar position entries
 .Op Fl bdhkn
 .Op Fl m Ar entries
 .Op Fl M Ar file
@@ -50,9 +51,18 @@
 .Pp
 The following options are available:
 .Bl -tag -width indent
+.It Fl a Ar position entries
+Modify the ACL on the specified files by inserting new
+ACL entries
+specified in
+.Ar entries ,
+starting at position
+.Ar position .
+This option is only applicable to NFS4 ACLs.
 .It Fl b
-Remove all ACL entries except for the three required entries.
-If the ACL contains a
+Remove all ACL entries except for the three required entries
+(POSIX.1e ACLs) or six "canonical" entries (NFS4 ACLs).
+If the POSIX.1e ACL contains a
 .Dq Li mask
 entry, the permissions of the
 .Dq Li group
@@ -66,7 +76,7 @@
 The operations apply to the default ACL entries instead of
 access ACL entries.
 Currently only directories may have
-default ACL's.
+default ACL's.  This option is not applicable to NFS4 ACLs.
 .It Fl h
 If the target of the operation is a symbolic link, perform the operation
 on the symbolic link itself, rather than following the link.
@@ -77,7 +87,7 @@
 any default ACL entries.
 An error will be reported if any of
 the specified files cannot have a default entry (i.e.\&
-non-directories).
+non-directories).  This option is not applicable to NFS4 ACLs.
 .It Fl m Ar entries
 Modify the ACL entries on the specified files by adding new
 entries and modifying existing ACL entries with the ACL entries
@@ -95,7 +105,7 @@
 the input is taken from stdin.
 .It Fl n
 Do not recalculate the permissions associated with the ACL
-mask entry.
+mask entry.  This option is not applicable to NFS4 ACLs.
 .It Fl x Ar entries
 Remove the ACL entries specified in
 .Ar entries
@@ -108,8 +118,8 @@
 .Pp
 The above options are evaluated in the order specified
 on the command-line.
-.Sh ACL ENTRIES
-An ACL entry contains three colon-separated fields:
+.Sh POSIX.1e ACL ENTRIES
+A POSIX.1E ACL entry contains three colon-separated fields:
 an ACL tag, an ACL qualifier, and discretionary access
 permissions:
 .Bl -tag -width indent
@@ -223,7 +233,7 @@
 .Ql #
 is ignored (comments).
 .Pp
-When ACL entries are evaluated, the access check algorithm checks
+When POSIX.1e ACL entries are evaluated, the access check algorithm checks
 the ACL entries in the following order: file owner,
 .Dq Li user
 ACL entries, file owning group,
@@ -243,13 +253,110 @@
 For more details see the examples below.
 Default ACLs can be created by using
 .Fl d .
+.Sh NFS4 ACL ENTRIES
+An NFS4 ACL entry contains four or five colon-separated fields: an ACL tag,
+an ACL qualifier (only for
+.Dq Li user
+and
+.Dq Li group
+tags), discretionary access permissions, ACL inheritance flags, and ACL type:
+.Bl -tag -width indent
+.It Ar "ACL tag"
+The ACL tag specifies the ACL entry type and consists of
+one of the following:
+.Dq Li user
+or
+.Ql u
+specifying the access
+granted to the specified user;
+.Dq Li group
+or
+.Ql g
+specifying the access granted to the specified group;
+.Dq Li owner@
+specifying the access granted to the owner of the file;
+.Dq Li group@
+specifying the access granted to the file owning group;
+.Dq Li everyone@
+specifying everyone.  Note that
+.Dq Li everyone@
+is not the same as traditional Unix
+.Dq Li other
+- it means,
+literally, everyone, including file owner and owning group.
+.It Ar "ACL qualifier"
+The ACL qualifier field describes the user or group associated with
+the ACL entry.
+It may consist of one of the following: uid or
+user name, or gid or group name.  In entries whose tag type is
+one of 
+.Dq Li owner@ ,
+.Dq Li group@ ,
+or
+.Dq Li everyone@ ,
+this field is ommited altogether, including the trailing comma.
+.It Ar "access permissions"
+The access permissions field contains up to one of each of
+the following:
+.Ql r ,
+.Ql w ,
+.Ql x ,
+.Ql p ,
+.Ql d ,
+.Ql D ,
+.Ql a ,
+.Ql A ,
+.Ql R ,
+.Ql W ,
+.Ql c ,
+.Ql C ,
+.Ql o ,
+and
+.Ql S
+to set read_data, write_data, execute, append_data, delete_child, delete,
+read_attributes, write_attributes, read_xattr, write_xattr, read_acl, write_acl,
+write_owner, and synchronize permissions, respectively.  This section obviously
+needs to be rewritten.
+Each of these may be excluded
+or replaced with a
+.Ql -
+character to indicate no access.
+.It Ar "ACL inheritance flags"
+The ACL inheritance flags field contains up to one of each of
+the following:
+.Ql f ,
+.Ql d ,
+.Ql i ,
+.Ql n ,
+to set file_inherit, dir_inherit, inherit_only, and no_propagate flags,
+respectively.  Inheritance flags may be only set on directories.
+.It Ar "ACL type"
+The ACL type field is either
+.Dq Li allow
+or
+.Dq Li deny .
+.El
+.Pp
+ACL entries applied from a file using the
+.Fl M
+or
+.Fl X
+options shall be of the following form: one ACL entry per line, as
+previously specified; whitespace is ignored; any text after a
+.Ql #
+is ignored (comments).
+.Pp
+NFS4 ACL entries are evaluated in their visible order.
+.Pp
+Multiple ACL entries specified on the command line are
+separated by commas.
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 .Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir
 .Dl setfacl -d -m g:admins:rwx dir
 .Pp
-The first command sets the mandatory elements of the default ACL.
+The first command sets the mandatory elements of the POSIX.1e default ACL.
 The second command specifies that users in group admins can have read, write, and execute
 permissions for directory named "dir".
 It should be noted that any files or directories created underneath "dir" will
@@ -259,9 +366,13 @@
 .Pp
 Sets read, write, and execute permissions for the
 .Pa file
-owner's ACL entry and read and write permissions for group mail on
+owner's POSIX.1e ACL entry and read and write permissions for group mail on
 .Pa file .
 .Pp
+.Dl setfacl -m owner@:rwxp::allow,g:mail:rwp::allow file
+.Pp
+Semantically equal to the example above, but for NFS4 ACL.
+.Pp
 .Dl setfacl -M file1 file2
 .Pp
 Sets/updates the ACL entries contained in
@@ -271,7 +382,7 @@
 .Pp
 .Dl setfacl -x g:mail:rw file
 .Pp
-Remove the group mail ACL entry containing read/write permissions
+Remove the group mail POSIX.1e ACL entry containing read/write permissions
 from
 .Pa file .
 .Pp