Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 31 Mar 2014 20:39:26 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r44403 - head/en_US.ISO8859-1/books/handbook/security
Message-ID:  <201403312039.s2VKdQ87074657@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Mon Mar 31 20:39:26 2014
New Revision: 44403
URL: http://svnweb.freebsd.org/changeset/doc/44403

Log:
  Editorial review of ACL chapter.
  Still need a section on ZFS and ACLs.
  This section would benefit from more usage examples and a
  more complete description of how ACLs augment tradiational
  permissions.
  
  Sponsored by:	iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/security/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/security/chapter.xml	Mon Mar 31 19:55:44 2014	(r44402)
+++ head/en_US.ISO8859-1/books/handbook/security/chapter.xml	Mon Mar 31 20:39:26 2014	(r44403)
@@ -72,7 +72,7 @@
       </listitem>
 
       <listitem>
-	<para>How to use filesystem <acronym>ACL</acronym>s.</para>
+	<para>How to use file system <acronym>ACL</acronym>s.</para>
       </listitem>
 
       <listitem>
@@ -1734,7 +1734,7 @@ kadmind5_server_enable="YES"</programlis
 	  not have a mechanism to authenticate the
 	  <acronym>KDC</acronym> to the users, hosts or services.
 	  This means that a trojanned &man.kinit.1; could record all
-	  user names and passwords.  Filesystem integrity checking
+	  user names and passwords.  File system integrity checking
 	  tools like <package>security/tripwire</package> can
 	  alleviate this.</para>
       </sect3>
@@ -2927,8 +2927,7 @@ user@unfirewalled-system.example.org's p
 
   <sect1 xml:id="fs-acl">
     <info>
-      <title>Filesystem Access Control Lists
-      (<acronym>ACL</acronym>)s</title>
+      <title>Access Control Lists</title>
 
       <authorgroup>
 	<author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed
@@ -2940,10 +2939,10 @@ user@unfirewalled-system.example.org's p
       <primary>ACL</primary>
     </indexterm>
 
-    <para>Filesystem Access Control Lists (<acronym>ACL</acronym>s)
+    <para>Access Control Lists (<acronym>ACL</acronym>s)
       extend the standard &unix; permission model in a &posix;.1e
-      compatible way.  This permits an administrator to make use of
-      and take advantage of a more sophisticated security
+      compatible way.  This permits an administrator to
+      take advantage of a more fine-grained permissions
       model.</para>
 
     <para>The &os; <filename>GENERIC</filename> kernel provides
@@ -2955,58 +2954,56 @@ user@unfirewalled-system.example.org's p
     <programlisting>options UFS_ACL</programlisting>
 
     <para>If this option is not compiled in, a warning message will be
-      displayed when attempting to mount a filesystem supporting
-      <acronym>ACL</acronym>s.  <acronym>ACL</acronym>s rely on
-      extended attributes being enabled on the filesystem.  Extended
-      attributes are natively supported in
+      displayed when attempting to mount a file system with
+      <acronym>ACL</acronym> support.  <acronym>ACL</acronym>s rely on
+      extended attributes which
+      are natively supported in
       <acronym>UFS2</acronym>.</para>
 
-    <note>
-      <para>A higher level of administrative overhead is required to
-	configure extended attributes on <acronym>UFS1</acronym>
-	than on <acronym>UFS2</acronym>.  The performance of
-	extended attributes on <acronym>UFS2</acronym> is also
-	substantially higher.  As a result, <acronym>UFS2</acronym>
-	is recommended for use with <acronym>ACL</acronym>s.</para>
-    </note>
+    <para>This chapter describes how to enable
+      <acronym>ACL</acronym> support and provides some usage
+      examples.</para>
+
+   <sect2>
+     <title>Enabling <acronym>ACL</acronym> Support</title>
 
     <para><acronym>ACL</acronym>s are enabled by the mount-time
       administrative flag, <option>acls</option>, which may be added
       to <filename>/etc/fstab</filename>.  The mount-time flag can
       also be automatically set in a persistent manner using
       &man.tunefs.8; to modify a superblock <acronym>ACL</acronym>s
-      flag in the filesystem header.  In general, it is preferred
+      flag in the file system header.  In general, it is preferred
       to use the superblock flag for several reasons:</para>
 
     <itemizedlist>
       <listitem>
-	<para>The mount-time <acronym>ACL</acronym>s flag cannot be
-	  changed by a remount using <option>mount -u</option>.  It
-	  requires a complete &man.umount.8; and fresh &man.mount.8;.
+	<para>The superblock flag cannot be
+	  changed by a remount using <option>mount -u</option> as it
+	  requires a complete <command>umount</command> and fresh <command>mount</command>.
 	  This means that <acronym>ACL</acronym>s cannot be enabled on
-	  the root filesystem after boot.  It also means that the
-	  disposition of a filesystem cannot be changed once it is in
+	  the root file system after boot.  It also means that
+	  <acronym>ACL</acronym> support on
+	  a file system cannot be changed while the system is in
 	  use.</para>
       </listitem>
 
       <listitem>
-	<para>Setting the superblock flag will cause the filesystem
+	<para>Setting the superblock flag causes the file system
 	  to always be mounted with <acronym>ACL</acronym>s enabled,
 	  even if there is not an <filename>fstab</filename> entry
 	  or if the devices re-order.  This prevents accidental
-	  mounting of the filesystem without <acronym>ACL</acronym>s
-	  enabled, which can result in the security problem of
-	  <acronym>ACL</acronym>s being improperly enforced.</para>
+	  mounting of the file system without <acronym>ACL</acronym>
+	  support.</para>
       </listitem>
     </itemizedlist>
 
     <note>
       <para>It is desirable to discourage accidental mounting without
-	<acronym>ACL</acronym>s enabled, because nasty things can
+	<acronym>ACL</acronym>s enabled because nasty things can
 	happen if <acronym>ACL</acronym>s are enabled, then disabled,
 	then re-enabled without flushing the extended attributes.  In
 	general, once <acronym>ACL</acronym>s are enabled on a
-	filesystem, they should not be disabled, as the resulting file
+	file system, they should not be disabled, as the resulting file
 	protections may not be compatible with those intended by the
 	users of the system, and re-enabling <acronym>ACL</acronym>s
 	may re-attach the previous <acronym>ACL</acronym>s to files
@@ -3014,9 +3011,9 @@ user@unfirewalled-system.example.org's p
 	unpredictable behavior.</para>
     </note>
 
-    <para>Filesystems with <acronym>ACL</acronym>s enabled will
-      show a <literal>+</literal> (plus) sign in their permission
-      settings when viewed.  For example:</para>
+    <para>File systems with <acronym>ACL</acronym>s enabled will
+      show a plus (<literal>+</literal>) sign in their permission
+      settings:</para>
 
     <programlisting>drwx------  2 robert  robert  512 Dec 27 11:54 private
 drwxrwx---+ 2 robert  robert  512 Dec 23 10:57 directory1
@@ -3031,12 +3028,13 @@ drwxr-xr-x  2 robert  robert  512 Nov 10
       are all taking advantage of <acronym>ACL</acronym>s, whereas
       <filename>public_html</filename>
       is not.</para>
+    </sect2>
 
     <sect2>
-      <title>Making Use of <acronym>ACL</acronym>s</title>
+      <title>Using <acronym>ACL</acronym>s</title>
 
-      <para>Filesystem <acronym>ACL</acronym>s can be viewed using
-	&man.getfacl.1;.  For instance, to view the
+      <para>File system <acronym>ACL</acronym>s can be viewed using
+	<command>getfacl</command>.  For instance, to view the
 	<acronym>ACL</acronym> settings on
 	<filename>test</filename>:</para>
 
@@ -3049,25 +3047,29 @@ drwxr-xr-x  2 robert  robert  512 Nov 10
 	other::r--</screen>
 
       <para>To change the <acronym>ACL</acronym> settings on this
-	file, use &man.setfacl.1;:</para>
-
-      <screen>&prompt.user; <userinput>setfacl -k test</userinput></screen>
-
-      <para>To remove all of the currently defined
-	<acronym>ACL</acronym>s from a file or filesystem, one can use
+	file, use <command>setfacl</command>.  To remove all of the currently defined
+	<acronym>ACL</acronym>s from a file or file system, include
 	<option>-k</option>.  However, the preferred method is to use
 	<option>-b</option> as it leaves the basic fields required
 	for <acronym>ACL</acronym>s to work.</para>
 
+      <screen>&prompt.user; <userinput>setfacl -k test</userinput></screen>
+
+      <para>To modify the default <acronym>ACL</acronym> entries, use
+	<option>-m</option>:</para>
+
       <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- test</userinput></screen>
 
-      <para>In this example, <option>-m</option> is used to modify the
-	default <acronym>ACL</acronym> entries.  Since there were no
+      <para>In this example, there were no
 	pre-defined entries, as they were removed by the previous
-	command, it restores the default options and assign the
+	command.  This command restores the default options and assigns the
 	options listed.  If a user or group is added which does not
 	exist on the system, an <errorname>Invalid
 	  argument</errorname> error will be displayed.</para>
+
+      <para>Refer to &man.getfacl.1; and &man.setfacl.1; for more
+	information about the options available for these
+	commands.</para>
     </sect2>
   </sect1>
 



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403312039.s2VKdQ87074657>