o POSIX.2c Userland tool support for POSIX.1e ACLs -- getfacl retrieves ACLs

  from files and directories, and setfacl sets ACLs on files and directories.

Submitted by:	jedgar
Obtained from:	TrustedBSD Project

1 files changed, 229 insertions, 0 deletions

diff --git a/bin/setfacl/setfacl.1 b/bin/setfacl/setfacl.1
new file mode 100644
index 0000000..fe28f86
--- /dev/null
+++ b/bin/setfacl/setfacl.1
@@ -0,0 +1,229 @@
+.\"
+.\" Copyright (c) 2001 Chris D. Faulhaber
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR THE VOICES IN HIS HEAD BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 7, 2001
+.Dt SETFACL 1
+.Os
+.Sh NAME
+.Nm setfacl
+.Nd Set ACL Information
+.Sh SYNOPSIS
+.Nm setfacl
+.Op Fl bdkn
+.Op Fl m Ar entries
+.Op Fl M Ar file1
+.Op Fl x Ar entries
+.Op Fl X Ar file1
+.Op Ar file ...
+.Sh DESCRIPTION
+The
+.Nm
+utility sets discretionary access control information on
+the specified file(s).
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl b
+Remove all ACL entries except for the three required entries.
+.It Fl d
+The operations apply to the default ACL entries instead of
+access ACL entries.  Currently only directories may have
+default ACL's.
+.It Fl k
+Delete any default ACL entries on the specified files.  It
+is not considered an error if the specified files do not have
+any default ACL entries.  An error will be reported if any of
+the specified files cannot have a default entry (i.e.
+non-directories).
+.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
+specified in
+.Ar entries .
+.It Fl M Ar file
+Modify the ACL entries on the specified files by adding new
+ACL entries and modifying existing ACL entries with the ACL
+entries specified in the file
+.Ar file .
+If
+.Ar file
+is "-", the input is taken from stdin.
+.It Fl n
+Do not recalculate the permissions associated with the ACL
+mask entry.
+.It Fl x Ar entries
+Remove the ACL entries specified in
+.Ar entries
+from the access or default ACL of the specified files.
+.It Fl X Ar file
+Remove the ACL entries specified in the file
+.Ar file
+from the access or default ACL of the specified files.
+.El
+.Pp
+The above options are evaluated in the order specified
+on the command-line.
+.Pp
+Multiple ACL entries specified on the command line shall be
+separated by commas.
+.Sh ACL ENTRIES
+An ACL entry shall contain three colon-separated fields:
+an ACL tag, an ACL qualifier, and discretionary access
+permissions:
+.Pp
+.Bl -tag -width indent
+.It Ar ACL tag
+The ACL tag specifies the ACL entry type and shall consist of
+one of the following: ``user'' or ``u'' specifying the access
+granted to the owner of the file or a specified user; ``group''
+or ``g'' specifying the access granted to the file owning group
+or a specified group; ``other'' or ``o'' specifying the access
+granted to any process that does not match any user or group
+ACL entry; ``mask'' or ``m'' specifying the maximum access
+granted to any ACL entry except the
+.Ar user
+ACL entry for the file owner and the
+.Ar other
+ACL entry.
+.Pp
+.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, gid or group name, or empty.  For
+.Ar user
+ACL entries, an empty field shall specify access granted to the
+file owner.  For
+.Ar group
+ACL entries, an empty field shall specify access granted to the
+file owning group.
+.Ar mask
+and
+.Ar other
+ACL entries do not use this field.
+.Pp
+.It Ar access permissions
+The access permissions field shall contain up to one of each of
+the following: ``r'', ``w'', and ``x'' to set read, write, and
+execute permissions, respectively.  Each of these may be excluded
+or replaced with a ``-'' character to indicate no access.
+.El
+.Pp
+A
+.Ar mask
+ACL entry is required on a file with any ACL entries other than
+the default
+.Ar user ,
+.Ar group ,
+and
+.Ar other
+ACL entries.  If the
+.Fl n
+option is not specified and no
+.Ar mask
+ACL entry was specified, the
+.Nm
+utility
+will apply a
+.Ar mask
+ACL entry consisting of the union of the permissions associated
+with all
+.Ar group
+ACL entries in the resulting ACL.
+.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 # is
+ignored (comments).
+.Pp
+When ACL entries are evaluated, the access check algorithm checks
+the ACL entries in the following order: file owner,
+.Ar user
+ACL entries, file owning group,
+.Ar group
+ACL entries, and
+.Ar other
+ACL entry.
+.Sh RETURN VALUES
+The
+.Nm
+utility returns 0 on success and > 0 if an error occurs.
+.Sh EXAMPLES
+.Dl setfacl -m u::rwx,g:mail:rw file
+.Pp
+Sets read, write, and execute permissions for the
+.Pa file
+owner's ACL entry and read and write permissions for group mail on
+.Pa file .
+.Pp
+.Dl setfacl -M file1 file2
+.Pp
+Sets/updates the ACL entries contained in
+.Pa file1
+on
+.Pa file2 .
+.Pp
+.Dl setfacl -x g:mail:rw file
+.Pp
+Remove the group mail ACL entry containing read/write permissions
+from
+.Pa file.
+.Pp
+.Dl setfacl -b file
+.Pp
+Remove all ACL entries except for the three required
+entries from
+.Pa file .
+.Pp
+.Dl getfacl file1 | setfacl -b -n -M - file2
+.Pp
+Copy ACL entries from
+.Pa file1
+to
+.Pa file2 .
+.Sh SEE ALSO
+.Xr getfacl 1 ,
+.Xr acl 3 ,
+.Xr getextattr 8 ,
+.Xr setextattr 8 ,
+.Xr acl 9 ,
+.Xr extattr 9 .
+.Sh STANDARDS
+The
+.Nm
+utility is expected to be IEEE Std 1003.2c compliant.
+.Sh HISTORY
+Extended Attribute and Access Control List support was developed
+as part of the TrustedBSD Project and introduced in
+.Fx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Chris D. Faulhaber Aq jedgar@fxp.org .