shorewall_code/Shorewall-docs/UserSets.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="UserSets">
  <!--$Id$-->

  <articleinfo>
    <title>Controlling Output Traffic by UID/GID</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate>2003-09-19</pubdate>

    <copyright>
      <year>2003</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <section>
    <title>Overview</title>

    <para>This capability was added in Shorewall release 1.4.7.</para>

    <para>Netfilter provides the capability to filter packets generated on the
    firewall system by User Id and/or Group Id. Shorewall provides two
    separate but related ways to use this Netfilter capability:</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall allows you to define collections of users called
        <quote><link linkend="UserSet">User Sets</link></quote> and then to
        restrict certain rules in /etc/shorewall/rules to a given User Set.</para>
      </listitem>

      <listitem>
        <para>Shorewall also allows you to restrict a given <link
        linkend="Rule">rule</link> to a particular user and/or group.</para>
      </listitem>
    </itemizedlist>

    <para>Since only packets created by programs running on the Shorewall box
    itself, only rules whose SOURCE is the firewall ($FW) may be restricted
    using either of the facilities.</para>
  </section>

  <section id="UserSet">
    <title>User Sets</title>

    <para>Given the way that this facility is implemented in Shorewall, it is
    not possible to control logging of individual rules using a User Set and
    logging is rather specified on the User Set itself.</para>

    <para>User Sets are defined in the /etc/shorewall/usersets file. Columns
    in that file include:</para>

    <variablelist>
      <varlistentry>
        <term>USERSET</term>

        <listitem>
          <para>The name of a User Set. Must be a legal shell identifier of no
          more than six (6) characters in length.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>REJECT</term>

        <listitem>
          <para>Log level for connections rejected for this User Set.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ACCEPT</term>

        <listitem>
          <para>Log level for connections accepted for this User Set.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DROP</term>

        <listitem>
          <para>Log level for connections dropped for this User Set.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>In the REJECT and ACCEPT columns, if you don&#39;t want to specify a
    value in the column but you want to specify a value in a following column,
    you may enter <quote>-</quote>.</para>

    <para>Users and/or groups are added to User Sets using the
    /etc/shorewall/users file. Columns in that file are:</para>

    <variablelist>
      <varlistentry>
        <term>USERSET</term>

        <listitem>
          <para>The name of a User Set defined in /etc/shorewall/usersets.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>USER</term>

        <listitem>
          <para>The name of a user defined on the system or a user number.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>GROUP</term>

        <listitem>
          <para>The name of a group defined on the system or a number.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Only one of the USER and GROUP column needs to be non-empty. If you
    wish to specify a GROUP but not a USER, enter <quote>-</quote> in the user
    column.</para>

    <para>If both USER and GROUP are specified then only programs running
    under that USER:GROUP pair will match rules specifying the User Set named
    in the USERSET column.</para>

    <para>Once a user set has been defined, its name may be placed in the USER
    SET column of the /etc/shorewall/rules file.</para>

    <important>
      <para>When the name of a user set is given in the USER SET column, you
      may not include a log level in the ACTION column; logging of such rules
      is governed solely by the user set&#39;s definition in the
      /etc/shorewall/userset file.</para>
    </important>

    <example>
      <title>You want members of the <quote>admin</quote> group and
      <quote>root</quote> to be able to use ssh on the firewall to connect to
      local systems. You want to log all connections accepted for these users
      using syslog at the <quote>info</quote> level.</title>

      <para>/etc/shorewall/usersets</para>

      <programlisting>#USERSET        REJECT  ACCEPT  DROP
admins          -       info</programlisting>

      <para>/etc/shorewall/users</para>

      <programlisting>#USERSET        USER            GROUP
admins          -               admin
admins          root</programlisting>

      <para>/etc/shorewall/rules</para>

      <programlisting>#ACTION SOURCE  DESTINATION     PROTO   PORT    SOURCE  ORIGINAL        RATE    USER
#                                               PORT(S) DESTINATION             SET

ACCEPT  $FW     loc             tcp     22      -       -               -       admins</programlisting>
    </example>
  </section>

  <section id="Rule">
    <title>Restricting a rule to a particular user and/or group</title>

    <para>In cases where you may want to restrict a rule to a particular user
    and/or group, the USER SET column in the rules file may be specified as:</para>

    <programlisting>[ &#60;<emphasis>user name or number</emphasis>&#62; ] : [ &#60;<emphasis>group name or number</emphasis>&#62; ]</programlisting>

    <para>When a user and/or group name is given in the USER SET column, it is
    OK to specify a log level in the ACTION column.</para>

    <example>
      <title>You want user <emphasis role="bold">mail</emphasis> to be able to
      send email from the firewall to the local net zone</title>

      <para>/etc/shorewall/rules (be sure to note the <quote>:</quote> in the
      USER SET column entry).</para>

      <programlisting>#ACTION SOURCE  DESTINATION     PROTO   PORT    SOURCE  ORIGINAL        RATE    USER
#                                               PORT(S) DESTINATION             SET

ACCEPT  $FW     loc             tcp     25      -       -               -       mail:</programlisting>
    </example>
  </section>
</article>