shorewall_code/Shorewall-docs/shorewall_logging.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="IPIP">
  <!--$Id$-->

  <articleinfo>
    <title>Shorewall Logging</title>

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

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

    <pubdate>2003-12-18</pubdate>

    <copyright>
      <year>2001 - 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>How to Log Traffic Through a Shorewall Firewall</title>

    <para>The disposition of packets entering a Shorewall firewall is
    determined by one of a number of Shorewall facilities. Only some of these
    facilities permit logging.</para>

    <orderedlist>
      <listitem>
        <para>The packet is part of an established commection. The packet is
        accepted and connot be logged.</para>
      </listitem>

      <listitem>
        <para>The packet represents a connection request that is related to an
        established connection (such as a <ulink url="FTP.html">data
        connection associated with an FTP control connection</ulink>). These
        packets also cannot be logged.</para>
      </listitem>

      <listitem>
        <para>The packet is rejected because of an option in <ulink
        url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink> or
        <ulink url="Documentation.htm#Interfaces">/etc/shorewall/interfaces</ulink>.
        These packets can be logged by setting the appropriate logging-related
        option in <ulink url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>.</para>
      </listitem>

      <listitem>
        <para>The packet matches a rule in <ulink
        url="Documentation.htm#Rules">/etc/shorewall/rules</ulink>. By
        including a syslog level (see below) in the ACTION column of a rule
        (e.g., <quote>ACCEPT<emphasis role="bold">:info</emphasis> net fw tcp
        22</quote>), the connection attempt will be logged at that level.</para>
      </listitem>

      <listitem>
        <para>The packet doesn&#39;t match a rule so it is handled by a policy
        defined in <ulink url="Documentation.htm#Policy">/etc/shorewall/policy</ulink>.
        These may be logged by specifying a syslog level in the LOG LEVEL
        column of the policy&#39;s entry (e.g., <quote>loc net ACCEPT
        <emphasis role="bold">info</emphasis></quote>).</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Where the Traffic is Logged and How to Change the Destination</title>

    <para>By default, Shorewall directs NetFilter to log using syslog (8).
    Syslog classifies log messages by a <emphasis>facility</emphasis> and a
    <emphasis>priority</emphasis> (using the notation <emphasis>facility.priority</emphasis>).</para>

    <para>The facilities defined by syslog are <emphasis>auth, authpriv, cron,
    daemon, kern, lpr, mail, mark, news, syslog, user, uucp</emphasis> and
    <emphasis>local0</emphasis> through <emphasis>local7.</emphasis></para>

    <para>Throughout the Shorewall documentation, I will use the term
    <emphasis>level</emphasis> rather than <emphasis>priority </emphasis>since
    <emphasis>level</emphasis> is the term used by NetFilter. The syslog
    documentation uses the term <emphasis>priority</emphasis>.</para>

    <section>
      <title>Syslog Levels</title>

      <para>Syslog levels are a method of describing to syslog (8) the
      importance of a message. A number of Shorewall parameters have a syslog
      level as their value.</para>

      <para>Valid levels are:</para>

      <simplelist>
        <member>7 - <emphasis role="bold">debug</emphasis> (Debug-level
        messages)</member>

        <member>6 - <emphasis role="bold">info</emphasis> (Informational)</member>

        <member>5 - <emphasis role="bold">notice</emphasis> (Normal but
        significant Condition)</member>

        <member>4 - <emphasis role="bold">warning</emphasis> (Warning
        Condition)</member>

        <member>3 - <emphasis role="bold">err</emphasis> (Error Condition)</member>

        <member>2 - <emphasis role="bold">crit</emphasis> (Critical
        Conditions)</member>

        <member>1 - <emphasis role="bold">alert</emphasis> (must be handled
        immediately)</member>

        <member>0 - <emphasis role="bold">emerg</emphasis> (System is
        unusable)</member>
      </simplelist>

      <para>For most Shorewall logging, a level of 6 (info) is appropriate.
      Shorewall log messages are generated by NetFilter and are logged using
      the <emphasis>kern</emphasis> facility and the level that you specify.
      If you are unsure of the level to choose, 6 (info) is a safe bet. You
      may specify levels by name or by number.</para>

      <para>Syslogd writes log messages to files (typically in /var/log/*)
      based on their facility and level. The mapping of these facility/level
      pairs to log files is done in /etc/syslog.conf (5). If you make changes
      to this file, you must restart syslogd before the changes can take
      effect.</para>
    </section>

    <section>
      <title>Configuring a Separate Log for Shorewall Messages</title>

      <para>There are a couple of limitations to syslogd-based logging:</para>

      <orderedlist>
        <listitem>
          <para>If you give, for example, kern.info it&#39;s own log
          destination then that destination will also receive all kernel
          messages of levels 5 (notice) through 0 (emerg).</para>

          <destructorsynopsis>
            <void />
          </destructorsynopsis>
        </listitem>

        <listitem>
          <para>All kernel.info messages will go to that destination and not
          just those from NetFilter.</para>
        </listitem>
      </orderedlist>

      <para>Beginning with Shorewall version 1.3.12, if your kernel has ULOG
      target support (and most vendor-supplied kernels do), you may also
      specify a log level of ULOG (must be all caps). When ULOG is used,
      Shorewall will direct netfilter to log the related messages via the ULOG
      target which will send them to a process called <quote>ulogd</quote>.
      The ulogd program is available from <ulink
      url="http://www.gnumonks.org/projects/ulogd">http://www.gnumonks.org/projects/ulogd</ulink>
      and can be configured to log all Shorewall message to their own log
      file.</para>

      <note>
        <para>The ULOG logging mechanism is <emphasis role="underline">completely
        separate</emphasis> from syslog. Once you switch to ULOG, the settings
        in /etc/syslog.conf have absolutely no effect on your Shorewall
        logging (except for Shorewall status messages which still go to
        syslog).</para>
      </note>

      <para>You will need to have the kernel source available to compile
      ulogd.</para>

      <para>Download the ulog tar file and:</para>

      <orderedlist>
        <listitem>
          <para>Be sure that /usr/src/linux is linked to your kernel source
          tree</para>
        </listitem>

        <listitem>
          <para>cd /usr/local/src (or whereever you do your builds)</para>
        </listitem>

        <listitem>
          <para>tar -zxf <emphasis>source-tarball-that-you-downloaded</emphasis></para>
        </listitem>

        <listitem>
          <para>cd ulod-<emphasis>version</emphasis></para>
        </listitem>

        <listitem>
          <para>./configure</para>
        </listitem>

        <listitem>
          <para>make</para>
        </listitem>

        <listitem>
          <para>make install</para>
        </listitem>
      </orderedlist>

      <para>If you are like me and don&#39;t have a development environment on
      your firewall, you can do the first six steps on another system then
      either NFS mount your /usr/local/src directory or tar up the
      /usr/local/src/ulogd-<emphasis>version</emphasis> directory and move it
      to your firewall system.</para>

      <para>Now on the firewall system, edit /usr/local/etc/ulogd.conf and
      set:</para>

      <orderedlist>
        <listitem>
          <para>syslogfile &#60;<emphasis>the file that you wish to log to</emphasis>&#62;</para>
        </listitem>

        <listitem>
          <para>syslogsync 1</para>
        </listitem>
      </orderedlist>

      <para>Also on the firewall system:</para>

      <simplelist>
        <member>touch &#60;<emphasis>the file that you wish to log to</emphasis>&#62;</member>
      </simplelist>

      <para>I also copied the file /usr/local/src/ulogd-<emphasis>version</emphasis>/ulogd.init
      to /etc/init.d/ulogd. I had to edit the line that read <quote>daemon
      /usr/local/sbin/ulogd</quote> to read <quote>daemon
      /usr/local/sbin/ulogd -d</quote>. On a RedHat system, a simple
      <quote>chkconfig --level 3 ulogd on</quote> starts ulogd during boot up.
      Your init system may need something else done to activate the script.</para>

      <para>You will need to change all instances of log levels (usually
      <quote>info</quote>) in your configuration files to <quote>ULOG</quote>
      - this includes entries in the policy, rules and shorewall.conf files.
      Here&#39;s what I have:</para>

      <programlisting>     [root@gateway shorewall]# grep ULOG *
     policy:loc fw  REJECT ULOG
     policy:net all DROP   ULOG    10/sec:40
     policy:all all REJECT ULOG
     rules:REJECT:ULOG loc net tcp 6667
     shorewall.conf:TCP_FLAGS_LOG_LEVEL=ULOG
     shorewall.conf:RFC1918_LOG_LEVEL=ULOG
     [root@gateway shorewall]#</programlisting>

      <para>Finally edit /etc/shorewall/shorewall.conf and set LOGFILE=&#60;<emphasis>file
      that you wish to log to</emphasis>&#62;. This tells the /sbin/shorewall
      program where to look for the log when processing its <quote>show log</quote>,
      <quote>logwatch</quote> and <quote>monitor</quote> commands.</para>
    </section>
  </section>

  <section>
    <title>Syslog-ng</title>

    <para><ulink
    url="http://marc.theaimsgroup.com/?l=gentoo-security&#38;amp;m=106040714910563&#38;amp;w=2">Here</ulink>
    is a post describing configuring syslog-ng to work with Shorewall.</para>
  </section>

  <section>
    <title>Understanding the Contents of Shorewall Log Messages</title>

    <para>For general information on the contents of Netfilter log messages,
    see <ulink url="http://logi.cc/linux/netfilter-log-format.php3">http://logi.cc/linux/netfilter-log-format.php3</ulink>.</para>

    <para>For Shorewall-specific information, see <ulink url="FAQ.htm#faq17">FAQ
    #17</ulink>.</para>
  </section>
</article>