<?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>2004-06-28</pubdate> <copyright> <year>2001 - 2004</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 cannot 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'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'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 (ulogd)</title> <para>There are a couple of limitations to syslogd-based logging:</para> <orderedlist> <listitem> <para>If you give, for example, kern.info it'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'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 <<emphasis>the file that you wish to log to</emphasis>></para> </listitem> <listitem> <para>syslogsync 1</para> </listitem> </orderedlist> <para>Also on the firewall system:</para> <simplelist> <member>touch <<emphasis>the file that you wish to log to</emphasis>></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'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=<<emphasis>file that you wish to log to</emphasis>>. 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&amp;m=106040714910563&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>