openafs/doc/xml/AdminReference/sect1/fs_setacl.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="fs_setacl1">
  <refmeta>
    <refentrytitle>fs setacl</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>fs setacl</refname>
    <refpurpose>Sets the ACL for a directory</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Synopsis</title>
    <para><emphasis role="bold">fs setacl</emphasis> <emphasis role="bold">-dir</emphasis> &lt;<emphasis>directory</emphasis>&gt;+ <emphasis role="bold">-acl</emphasis> &lt;<emphasis>access list entries</emphasis>&gt;+
        [<emphasis role="bold">-clear</emphasis>] [<emphasis role="bold">-negative</emphasis>] [<emphasis role="bold">-id</emphasis>] [<emphasis role="bold">-if</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>

    <para><emphasis role="bold">fs sa</emphasis> <emphasis role="bold">-d</emphasis> &lt;<emphasis>directory</emphasis>&gt;+ <emphasis role="bold">-a</emphasis> &lt;<emphasis>access list entries</emphasis>&gt;+
        [<emphasis role="bold">-c</emphasis>] [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-id</emphasis>] [<emphasis role="bold">-if</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>

    <para><emphasis role="bold">fs seta</emphasis> <emphasis role="bold">-d</emphasis> &lt;<emphasis>directory</emphasis>&gt;+ <emphasis role="bold">-a</emphasis> &lt;<emphasis>access list entries</emphasis>&gt;+
        [<emphasis role="bold">-c</emphasis>] [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-id</emphasis>] [<emphasis role="bold">-if</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>

  </refsect1>
  <refsect1>
    <title>Description</title>
    <para>The <emphasis role="bold">fs setacl</emphasis> command adds the access control list (ACL) entries
    specified with the <emphasis role="bold">-acl</emphasis> argument to the ACL of each directory named by
    the <emphasis role="bold">-dir</emphasis> argument.</para>

    <para>If the <emphasis role="bold">-dir</emphasis> argument designates a pathname in DFS filespace (accessed
    via the AFS/DFS Migration Toolkit Protocol Translator), it can be a file
    as well as a directory. The ACL must already include an entry for
    <computeroutput>mask_obj</computeroutput>, however. For more details, refer to the <emphasis>IBM AFS/DFS
    Migration Toolkit Administration Guide and Reference</emphasis>.</para>

    <para>Only user and group entries are acceptable values for the <emphasis role="bold">-acl</emphasis>
    argument. Do not place machine entries (IP addresses) directly on an ACL;
    instead, make the machine entry a group member and place the group on the
    ACL.</para>

    <para>To completely erase the existing ACL before adding the new entries,
    provide the <emphasis role="bold">-clear</emphasis> flag. To add the specified entries to the <computeroutput>Negative
    rights</computeroutput> section of the ACL (deny rights to specified users or groups),
    provide the <emphasis role="bold">-negative</emphasis> flag.</para>

    <para>To display an ACL, use the fs listacl command. To copy an ACL from one
    directory to another, use the <emphasis role="bold">fs copyacl</emphasis> command.</para>

  </refsect1>
  <refsect1>
    <title>Cautions</title>
    <para>If the ACL already grants certain permissions to a user or group, the
    permissions specified with the <emphasis role="bold">fs setacl</emphasis> command replace the existing
    permissions, rather than being added to them.</para>

    <para>Setting negative permissions is generally unnecessary and not
    recommended. Simply omitting a user or group from the <computeroutput>Normal rights</computeroutput>
    section of the ACL is normally adequate to prevent access. In particular,
    note that it is futile to deny permissions that are granted to members of
    the system:anyuser group on the same ACL; the user needs only to issue the
    <emphasis role="bold">unlog</emphasis> command to receive the denied permissions.</para>

    <para>When including the <emphasis role="bold">-clear</emphasis> option, be sure to reinstate an entry for
    each directory's owner that includes at least the <computeroutput>l</computeroutput> (lookup)
    permission. Without that permission, it is impossible to resolve the "dot"
    (<computeroutput>.</computeroutput>) and "dot dot" (<computeroutput>..</computeroutput>) shorthand from within the directory. (The
    directory's owner does implicitly have the <computeroutput>a</computeroutput> (administer) permission
    even on a cleared ACL, but must know to use it to add other permissions.)</para>

  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term><emphasis role="bold">-dir</emphasis> &lt;<emphasis>directory</emphasis>&gt;+</term>
        <listitem>
          <para>Names each AFS directory, or DFS directory or file, for which the set the
          ACL. Partial pathnames are interpreted relative to the current working
          directory.</para>

          <para>Specify the read/write path to each directory (or DFS file), to avoid the
          failure that results from attempting to change a read-only volume. By
          convention, the read/write path is indicated by placing a period before
          the cell name at the pathname's second level (for example,
          <replaceable>/afs/.abc.com</replaceable>). For further discussion of the concept of read/write and
          read-only paths through the filespace, see the <emphasis role="bold">fs mkmount</emphasis> reference
          page.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-acl</emphasis> &lt;<emphasis>access list entries</emphasis>&gt;+</term>
        <listitem>
          <para>Defines a list of one or more ACL entries, each a pair that names:</para>

          <itemizedlist>
            <listitem>
              <para>A user name or group name as listed in the Protection Database.</para>

            </listitem>
            <listitem>
              <para>One or more ACL permissions, indicated either by combining the individual
              letters or by one of the four acceptable shorthand words.</para>

            </listitem>
          </itemizedlist>
          <para>in that order, separated by a space (thus every instance of this argument
          has two parts). The accepted AFS abbreviations and shorthand words, and
          the meaning of each, are as follows:</para>

          <variablelist>
            <varlistentry>
              <term>a (administer)</term>
              <listitem>
                <para>Change the entries on the ACL.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>d (delete)</term>
              <listitem>
                <para>Remove files and subdirectories from the directory or move them to other
                directories.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>i (insert)</term>
              <listitem>
                <para>Add files or subdirectories to the directory by copying, moving or
                creating.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>k (lock)</term>
              <listitem>
                <para>Set read locks or write locks on the files in the directory.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>l (lookup)</term>
              <listitem>
                <para>List the files and subdirectories in the directory, stat the directory
                itself, and issue the <emphasis role="bold">fs listacl</emphasis> command to examine the directory's
                ACL.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>r (read)</term>
              <listitem>
                <para>Read the contents of files in the directory; issue the <computeroutput>ls -l</computeroutput> command to
                stat the elements in the directory.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>w (write)</term>
              <listitem>
                <para>Modify the contents of files in the directory, and issue the UNIX <emphasis role="bold">chmod</emphasis>
                command to change their mode bits.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>A, B, C, D, E, F, G, H</term>
              <listitem>
                <para>Have no default meaning to the AFS server processes, but are made
                available for applications to use in controlling access to the directory's
                contents in additional ways. The letters must be uppercase.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>all</term>
              <listitem>
                <para>Equals all seven permissions (<computeroutput>rlidwka</computeroutput>).</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>none</term>
              <listitem>
                <para>No permissions. Removes the user/group from the ACL, but does not
                guarantee they have no permissions if they belong to groups that remain on
                the ACL.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>read</term>
              <listitem>
                <para>Equals the <computeroutput>r</computeroutput> (read) and <computeroutput>l</computeroutput> (lookup) permissions.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>write</term>
              <listitem>
                <para>Equals all permissions except <computeroutput>a</computeroutput> (administer), that is, <computeroutput>rlidwk</computeroutput>.</para>

              </listitem>
            </varlistentry>
          </variablelist>
          <para>It is acceptable to mix entries that combine the individual letters with
          entries that use the shorthand words, but not use both types of notation
          within an individual pairing of user or group and permissions.</para>

          <para>To learn the proper format and acceptable values for DFS ACL entries, see
          the <emphasis>IBM AFS/DFS Migration Toolkit Administration Guide and Reference</emphasis>.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-clear</emphasis></term>
        <listitem>
          <para>Removes all existing entries on each ACL before adding the entries
          specified with the <emphasis role="bold">-acl</emphasis> argument.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-negative</emphasis></term>
        <listitem>
          <para>Places the specified ACL entries in the <computeroutput>Negative rights</computeroutput> section of each
          ACL, explicitly denying the rights to the user or group, even if entries
          on the accompanying <computeroutput>Normal rights</computeroutput> section of the ACL grant them
          permissions.</para>

          <para>This argument is not supported for DFS files or directories, because DFS
          does not implement negative ACL permissions.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-id</emphasis></term>
        <listitem>
          <para>Places the ACL entries on the Initial Container ACL of each DFS directory,
          which are the only file system objects for which this flag is supported.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-if</emphasis></term>
        <listitem>
          <para>Places the ACL entries on the Initial Object ACL of each DFS directory,
          which are the only file system objects for which this flag is supported.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-help</emphasis></term>
        <listitem>
          <para>Prints the online help for this command. All other valid options are
          ignored.</para>

        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Examples</title>
    <para>The following example adds two entries to the <computeroutput>Normal rights</computeroutput> section of
    the current working directory's ACL: the first entry grants <computeroutput>r</computeroutput> (read)
    and <computeroutput>l</computeroutput> (lookup) permissions to the group pat:friends, while the other
    (using the <computeroutput>write</computeroutput> shorthand) gives all permissions except <computeroutput>a</computeroutput>
    (administer) to the user <computeroutput>smith</computeroutput>.</para>

<programlisting>
   % fs setacl -dir . -acl pat:friends rl smith write

</programlisting>
<programlisting>
   % fs listacl -path .
   Access list for . is
   Normal rights:
      pat:friends rl
      smith rlidwk

</programlisting>
        <para>The following example includes the <emphasis role="bold">-clear</emphasis> flag, which removes the
        existing permissions (as displayed with the <emphasis role="bold">fs listacl</emphasis> command) from
        the current working directory's <replaceable>reports</replaceable> subdirectory and replaces them
        with a new set.</para>

<programlisting>
   % fs listacl -dir reports
   Access list for reports is
   Normal rights:
      system:authuser rl
      pat:friends rlid
      smith rlidwk
      pat rlidwka
   Negative rights:
      terry rl

</programlisting>
<programlisting>
   % fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl

</programlisting>
<programlisting>
   % fs listacl -dir reports
   Access list for reports is
   Normal rights:
      system:anyuser rl
      smith rlidwk
      pat rlidwka

</programlisting>
              <para>The following example use the <emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> switches because it sets
              the ACL for more than one directory (both the current working directory
              and its <replaceable>public</replaceable> subdirectory).</para>

<programlisting>
   % fs setacl -dir . public -acl pat:friends rli

</programlisting>
<programlisting>
   % fs listacl -path . public
   Access list for . is
   Normal rights:
      pat rlidwka
      pat:friends rli
   Access list for public is
   Normal rights:
      pat rlidwka
      pat:friends rli

</programlisting>
                </refsect1>
                <refsect1>
                  <title>Privilege Required</title>
                  <para>The issuer must have the <computeroutput>a</computeroutput> (administer) permission on the directory's
                  ACL; the directory's owner and the members of the system:administrators
                  group have the right implicitly, even if it does not appear on the ACL.</para>

                </refsect1>
                <refsect1>
                  <title>See Also</title>
                  <para><link linkend="fs_copyacl1">fs_copyacl(1)</link>,
                  <link linkend="fs_listacl1">fs_listacl(1)</link>,
                  <link linkend="fs_mkmount1">fs_mkmount(1)</link></para>

                  <para><emphasis>IBM AFS/DFS Migration Toolkit Administration Guide and Reference</emphasis></para>

                </refsect1>
                <refsect1>
                  <title>Copyright</title>
                  <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>

                  <para>This documentation is covered by the IBM Public License Version 1.0.  It was
                  converted from HTML to POD by software written by Chas Williams and Russ
                  Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>

                </refsect1>
              </refentry>