As I've already indicated on various mailing lists (freebsd-fs and
freebsd-security, in particular), this commit (message attached below)
adds the remainder of the necessary code to add POSIX.1e ACLs to FreeBSD
5.0-CURRENT.  As I describe in the commit message, this is not ready for
production use, and there may be API, ABI, and binary format changes that
cause experimental installations to get broken, but even so, I'd like to
appeal for testers to try and track down bugs, incompatibilities, etc.  As
such, this e-mail includes basic directions for getting ACLs working on a
file system, as well as having references to useful man pages and other
doucments.  Note:  these directions are copied from the README of the last
specific ACL patch release, acl-0.6.1, so you can always grab that off the
TrustedBSD downloads page and get the same thing. 

POSIX.1e Access Control Lists for FreeBSD, Version 0.6.1
March 19, 2001
Robert Watson <[EMAIL PROTECTED]>

This is the README file for 0.6.1 of POSIX.1e ACLs for TrustedBSD.


Access Control Lists provide a means by which more detailed permissions
may be associated with file system objects, allowing the granting of
rights in a discretionary way by the file owner.  POSIX.1e ACLs extend the
basic UNIX permission set allowing the granting of rights to additional
users and groups beyond the file owner and group.  These mechanisms can be
used to reduce the need for centralized file permission administration by
system administrators in the case of collaborative work (files and
directories can now give rights to sets of users without the system
administrator needing to define a group describing the set), and can also
be used to more finely tune permissions for system use. 

This is a still-experimental implementation, and should not be relied on
in production environments yet.  In general, the POSIX.1e draft standard
is adhered to for interfaces, except in specific documented cases.

(discussion of applying ACL patches and commit status ommitted)


(discussion of applying ACL patches and commit status ommitted)

Add the following options to your kernel config file:

   options      UFS_EXTATTR
   options      UFS_ACL

Run config to configure the kernel build, build and install the kernel. 
The userland libraries and tools required to use ACLs are now part of the
base FreeBSD distribution, and are built by default. 


(discussion of applying ACL patches and commit status ommitted)

The library and system call interfaces included in that source version
should be sufficient to support ACLs, so only rebuilding of the kernel is
required.  To enable support for ACLs in UFS, include option "UFS_ACL". 
This depends on the presence of "UFS_EXTATTR" to actually work, which
enables extended attributes on the FFS and MFS file systems; the
"UFS_EXTATTR_AUTOSTART"  option may also be useful as it reduces
administrative overhead associated with extended attributes. 

UFS ACLs rely on two different extended attributes: "posix1e.acl_access" 
to store the access ACL, and "posix1e.acl_default" to store default ACLs
on directories.  These must be initialized and enabled for ACLs to work on
a given file system.  In FreeBSD 5.0-CURRENT, extended attributes are
stored in backing files that must be explicitly configured for each file
system.  Once attribute backing files are initialized, they may be
manually enabled for the file system after mount, or with the
UFS_EXTATTR_AUTOSTART option compiled into the kernel, they can be
automatically started each time the file system is mounted.  To configure
extended attributes for a file system, first create a ".attribute"
directory off of the file system root.  Next, create two sub-directories
name "user" and "system", which will store the backing files for user and
system extended attributes.  To initialize the "posix1e.acl_access" and
"posix1e.acl_default" EAs, run the following commands in relevant
".attribute/system" directories on each file system: 

  extattrctl initattr 388 'posix1e.acl_access'
  extattrctl initattr 388 'posix1e.acl_default'

The 388 reflects the current maximum size of an ACL when stored.  These
files are not pre-initialized to conserve space, but the results of
running out of space for an ACL are generally unfortunate, and should be
avoided, either by preinitializing ('-p /'), or not consuming system free

After the EA backing files are initialized, you can manually start the
EA's on the file system, or if UFS_EXTATTR_AUTOSTART is enabled, simply
remount the file systems, or reboot the system.  To manually start and
enable the attributes for the root file system, do the following: 

  extattrctl start /
  extattrctl enable / posix1e.acl_access /.attribute/system/posix1e.acl_access
  extattrctl enable / posix1e.acl_default /.attribute/system/posix1e.acl_default

Once these EA's are available for a file system, ACLs will automatically
be enabled.  In the future, ACL support may require specific
administrative configuration.


Several new interfaces are introduced to support access control lists. 
This includes library routines in libposix1e, new syscalls, VFS calls, and
reliance on the new extended attribute support.  The library and VFS calls
are documented in system man pages--see posix1e(3), acl(3)  and acl(9) for
starting points.

  Implementation Status

Userland utilities: The getfacl and setfacl tools are complete, and
                    committed to the base FreeBSD source treee. 

Libraries: The basis ACL set/get/text/etc is complete, but the detailed
           ACL editing support (inconvenient and unwieldy) is not. 

Syscalls: All syscalls are fully implemented; the extended attribute
          interface may evolve over time to reflect implementation and
          portability requirements.

Vnode calls: A vnode framework is provided, but individual file systems
             must provide their own ACL storage and management.  Generic
             ACL support code is provided in kern_acl.c to make this
             consistent across filesystems.

UFS: Support for ACLs relies on extended attributes; this appears to wok
     correctly, but extensive testing is required.

Documentation: Man pages for userland utilities, library calls, and VFS
               calls are complete.  UFS documents should be updated to
               reflect the current integration and design.


A paper presented at BSDcon 2000 documents the support for extended
attributes; other documentation is still forth-coming.  The POSIX.1e draft
(D17) documents the API in detail, and gives examples.  POSIX.2c documents
the command line tools.  Online man pages that are relevant include:

VOP_ACLCHECK(9) - Check an access control list for a vnode
VOP_GETACL(9)            - Retrieve access control list for a vnode
VOP_SETACL(9)            - Set the access control list for a vnode
acl(3)                   - introduction to the POSIX.1e ACL security API
acl(9)                   - virtual file system access control lists
acl_add_perm(3)          - add permissions to a permission set
acl_calc_mask(3)         - calculate and set ACL mask permissions
acl_canonicalize_principal(3), acl_check(3), acl_exact_match(3), acl_add(3), 
acl_delete(3), acl_initialize(3) - Access control list routines
acl_clear_perms(3)       - clear permissions from a permission set
acl_copy_entry(3)        - copy an ACL entry to another ACL entry
acl_delete_def_file(3), acl_delete_fd_np(3), acl_delete_file_np(3) -  delete an ACL 
from a file
acl_delete_entry(3)      - delete an ACL entry from an ACL
acl_delete_perm(3)       - delete permissions from a permission set
acl_dup(3)               - duplicate an ACL
acl_free(3)              - free ACL working state
acl_from_text(3)         - create an ACL from text
acl_get_fd(3), acl_get_fd_np(3), acl_get_file(3) - get an ACL for a file
acl_get_permset(3)       - retrieve permission set from an ACL entry
acl_get_qualifier(3)     - retrieve the qualifier from an ACL entry
acl_get_tag_type(3)      - calculate and set ACL mask permissions
acl_init(3)              - initialize ACL working storage
acl_set_fd(3), acl_set_fd_np(3), acl_set_file(3) - get an ACL for a file
acl_set_permset(3)       - set the permissions of an ACL entry
acl_set_qualifier(3)     - set ACL tag qualifier
acl_set_tag_type(3)      - set the tag type of an ACL entry
acl_to_text(3)           - convert an ACL to Text
acl_valid(3), acl_valid_fd_np(3), acl_valid_file_np(3) - validate an ACL
getfacl(1)               - get ACL Information
setfacl(1)               - set ACL Information

VOP_GETEXTATTR(9) - Retrieve named extended attribute from a vnode
VOP_SETEXTATTR(9)        - Set named extended attribute for a vnode
extattr(9)               - virtual file system named extended attributes
extattrctl(8)            - manage FFS extended attributes
getextattr(8)            - retrieve a named extended attribute
setextattr(8)            - set a named extended attribute

This README makes a good introduction.  The [EMAIL PROTECTED]
mailing list and archive make for a good source of information about
detailed semantics and ambiguities in the specifications. 


Chris D. Faulhaber provided the setfacl utility, as well as debugging of
  kernel components, and bugfixes to libposix1e.
Brian Feldman provided bugfixes to libposix1e, as well as provided
  assistance with acl_{to,from}_text.
Robert Watson provided the majority of the kernel and userland code.

  Mailing Lists


  Web Pages



Standard 2-clause BSD-style license (see top of this file), designed to
encourage wide-spread integration of the code in open-source and
commercial products.  This license encourages interoperability through the
use of compatible and consistent code across platforms--which is
consistent with the desire to produce a more portable and secure
environment.  Please feel free to contact me if you're interested in
alternative licenses that better suit your needs, or if you want to send
me money. 

  Contact Information

Personal: Robert Watson <[EMAIL PROTECTED]>
FreeBSD-related: Robert Watson <[EMAIL PROTECTED]>

Robert N M Watson             FreeBSD Core Team, TrustedBSD Project
[EMAIL PROTECTED]      NAI Labs, Safeport Network Services

---------- Forwarded message ----------
Date: Mon, 26 Mar 2001 09:53:19 -0800 (PST)
From: Robert Watson <[EMAIL PROTECTED]>
Subject: cvs commit: src/sys/conf files options src/sys/ufs/ufs acl.h         
ufs_acl.c ufs_vnops.c

rwatson     2001/03/26 09:53:19 PST

  Modified files:
    sys/conf             files options 
    sys/ufs/ufs          ufs_vnops.c 
  Added files:
    sys/ufs/ufs          acl.h ufs_acl.c 
  Introduce support for POSIX.1e ACLs on UFS-based file systems.  This
  implementation is still experimental, and while fairly broadly tested,
  is not yet intended for production use.  Support for POSIX.1e ACLs on
  UFS will not be MFC'd to RELENG_4.
  This implementation works by providing implementations of VOP_[GS]ETACL()
  for FFS, as well as modifying the appropriate access control and file
  creation routines.  In this implementation, ACLs are backed into extended
  attributes; the base ACL (owner, group, other) permissions remain in the
  inode for performance and compatibility reasons, so only the extended and
  default ACLs are placed in extended attributes.  The logic for ACL
  evaluation is provided by the fs-independent kern/kern_acl.c.
  o Introduce UFS_ACL, a compile-time configuration option that enables
    support for ACLs on FFS (and potentially other UFS-based file systems).
  o Introduce ufs_getacl(), ufs_setacl(), ufs_aclcheck(), which
    respectively get, set, and check the ACLs on the passed vnode.
  o Introduce ufs_sync_acl_from_inode(), ufs_sync_inode_from_acl() to
    maintain access control information between inode permissions and
    extended attribute data.
  o Modify ufs_access() to load a file access ACL and invoke
    vaccess_acl_posix1e() if ACLs are available on the file system
  o Modify ufs_mkdir() and ufs_makeinode() to associate ACLs with newly
    created directories and files, inheriting from the parent directory's
    default ACL.
  o Enable these new vnode operations and conditionally compiled code
    paths if UFS_ACL is defined.
  A few notes:
  o This implementation is fairly widely tested, but still should be
    considered experimental.
  o Currently, ACLs are not exported via NFS, instead, the summarizing
    file mode/etc from the inode is.  This results in conservative
    protection behavior, similar to the behavior of ACL-nonaware programs
    acting locally.
  o It is possible that underlying binary data formats associated with
    this implementation may change.  Consumers of the implementation
    should expect to find their local configuration obsoleted in the
    next few months, resulting in possible loss of ACL data during an
  o The extended attributes interface and implementation is still
    undergoing modification to address portable interface concerns, as
    well as performance.
  o Many applications do not yet correctly handle ACLs.  In general,
    due to the POSIX.1e ACL model, behavior of ACL-unaware applications
    will be conservative with respects to file protection; some caution
    is recommended.
  o Instructions for configuring and maintaining ACLs on UFS will be
    committed in the near future; in the mean time it is possible to
    reference the README included in the last UFS ACL distribution
    placed in the TrustedBSD web site:
  Substantial debugging, hardware, travel, or connectivity support for this
  project was provided by: BSDi, Safeport Network Services, and NAI Labs.
  Significant coding contributions were made by Chris Faulhaber.  Additional
  support was provided by Brian Feldman, Thomas Moestl, and Ilmar Habibulin.
  Reviewed by:  jedgar, keichii, mckusick, trustedbsd-discuss, freebsd-fs
  Obtained from:        TrustedBSD Project
  Revision  Changes    Path
  1.502     +2 -1      src/sys/conf/files
  1.266     +6 -1      src/sys/conf/options
  1.160     +214 -6    src/sys/ufs/ufs/ufs_vnops.c

To Unsubscribe: send mail to [EMAIL PROTECTED]
with "unsubscribe freebsd-current" in the body of the message

Reply via email to