source: postlfs/security/acl.xml@ bcad034

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY acl-download-http "http://download.savannah.gnu.org/releases/acl/acl-&acl-version;.src.tar.gz">
  <!ENTITY acl-download-ftp  " ">
  <!ENTITY acl-md5sum        "3fc0ce99dc5253bdcce4c9cd437bc267">
  <!ENTITY acl-size          "380 KB">
  <!ENTITY acl-buildsize     "5.5 MB">
  <!ENTITY acl-time          "0.1 SBU">
]>

<sect1 id="acl" xreflabel="acl-&acl-version;">
  <?dbhtml filename="acl.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>acl-&acl-version;</title>

  <indexterm zone="acl">
    <primary sortas="a-acl">acl</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to acl</title>

    <para>The <application>acl</application> package contains utilities to
    administer Access Control Lists, which are used to define more fine-grained
    discretionary access rights for files and directories.</para>

    &lfs70_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&acl-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&acl-download-ftp;"/></para>
      </listitem> 
      <listitem>
        <para>Download MD5 sum: &acl-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &acl-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &acl-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &acl-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">acl Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="attr"/></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/acl"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of acl</title>

    <para>Install <application>acl</application> by running the following
    commands:</para>

<screen><userinput>sed -i -e 's|/@pkg_name@|&amp;-@pkg_version@|' \
     include/builddefs.in &amp;&amp;

INSTALL_USER=root  \
INSTALL_GROUP=root \
./configure --prefix=/usr --libdir=/lib --libexecdir=/usr/lib &amp;&amp;
make</userinput></screen>

    <para>For meaningful results, the tests need to be carried out on a file
    system that supports extended attributes. It is also required that
    <application>Coreutils</application> is re-installed after
    <application>acl</application> is installed so that the extra acl bit
    displays correctly on a <command>ls</command> command.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<!-- Package uses DIST_ROOT instead of DESTDIR -->
<screen role="root"><userinput>
make install install-dev install-lib             &amp;&amp;
chmod -v 0755 /lib/libacl.so.1.1.0               &amp;&amp;
rm -v /lib/libacl.{a,la,so}                      &amp;&amp;
ln -sfv ../../lib/libacl.so.1 /usr/lib/libacl.so &amp;&amp;
install -v -m644 doc/*.txt /usr/share/doc/acl-&acl-version;</userinput></screen>

    <para>You should now re-install <application><ulink
    url="&lfs-root;/chapter06/coreutils.html">Coreutils</ulink>
    </application> and proceed to run the test suite.</para>

    <para>There are three sets of tests that come with this package. Issue the
    following to execute all three:
    <command>make tests root-tests ext-tests</command>.</para>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>sed -i ... include/builddefs.in</command>: This command
    modifies the documentation directory so that it is a versioned
    directory.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring acl</title>
    <sect3><title>Configuration Information</title>

      <para>There is no configuration to <application>acl</application> itself,
      but to get any use out of <application>acl</application>, a filesystem
      needs to support access control lists.</para>

      <para>One way to achieve this is to add the acl option to an ext3
      filesystem in the <filename>/etc/fstab</filename> file as shown
      below:</para>

<screen># file system  mount-point  type   options                 dump  fsck
#                                                                order

/dev/sda1      /            ext3   defaults,acl,user_xattr 0     2</screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>chacl, getfacl, and setfacl</seg>
        <seg>libacl.{so,a}</seg>
        <seg>/usr/{include/acl,share/doc/acl-&acl-version;}</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="chacl">
        <term><command>chacl</command></term>
        <listitem>
          <para>changes the access control list of a file or directory.</para>
          <indexterm zone="acl chacl">
            <primary sortas="b-chacl">chacl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="getfacl">
        <term><command>getfacl</command></term>
        <listitem>
          <para>gets file access control lists.</para>
          <indexterm zone="acl getfacl">
            <primary sortas="b-getfacl">getfacl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="setfacl">
        <term><command>setfacl</command></term>
        <listitem>
          <para>sets file access control lists.</para>
          <indexterm zone="acl setfacl">
            <primary sortas="b-setfacl">setfacl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libacl">
        <term><filename class='libraryfile'>libacl.{so,a}</filename></term>
        <listitem>
          <para>contains the <application>acl</application> API functions.</para>
          <indexterm zone="acl libacl">
            <primary sortas="c-libacl">libacl.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>