source: archive/acl.xml@ 56605b9

<?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        "a61415312426e9c2212bd7dc7929abda">
  <!ENTITY acl-size          "384 KB">
  <!ENTITY acl-buildsize     "9.1 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>

    &lfs75_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 --libexecdir=/usr/lib --disable-static &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 755 /usr/lib/libacl.so                  &amp;&amp;
mv -v /usr/lib/libacl.so.* /lib                  &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. The local
    partition where the tests are run must be mounted with acl configured as
    described below.  Additionally, the users <systemitem
    class="username">bin</systemitem> and <systemitem
    class="username">daemon</systemitem> must be created or modified to have a
    proper shell and home directory and the group <systemitem
    class="groupname">daemon</systemitem> must be a member of the <systemitem
    class="groupname">bin</systemitem> group.  The kernel must also be
    configured with the appropriate ACL options (there are nine different
    options).</para>
    
    <para>To run the standard tests run <command>make tests </command>.  As
    <systemitem class="username">root</systemitem> user, run <command>make
    root-tests</command>.</para>

    <para>The third set of tests are Network File System (NFS) specific.  See
    the contents of the test files in the test/nfs/ directory for the setup
    requirements.</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>

    <para><command>--libexecdir=/usr/lib</command>: This switch ensures that
    <filename class="libraryfile">libacl.la</filename> is installed in the correct
    directory, and that a spurious
    <filename class="libraryfile">libacl.so</filename> symlink is not created in
    <filename class="directory">/usr/libexec/</filename>.</para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/static-libraries.xml"/>

  </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>