1
0
shorewall_code/docs/shorewall_logging.xml
judas_iscariote 4033e6051b renamed to a simpler "docs"
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@3521 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
2006-02-23 01:22:17 +00:00

279 lines
11 KiB
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>2005-10-10</pubdate>
<copyright>
<year>2001 - 2005</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>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.</emphasis></para>
</caution>
<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 connecection. While the
packet can be logged using LOG rules in the ESTABLISHED section of
<ulink url="Documentation.htm#Rules">/etc/shorewall/rules</ulink>,
that is not recommended because of the large amount of information
that may 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 may be logged using LOG rules in the RELATED section of <ulink
url="Documentation.htm#Rules">/etc/shorewall/rules</ulink>.</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>
<para>Syslog may also write to your system console. See <ulink
url="FAQ.htm#faq16">Shorewall FAQ 16</ulink> for ways to avoid having
Shorewall messages written to the console.</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>
</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 included in most distributions and is also
available from <ulink
url="http://www.gnumonks.org/projects/ulogd">http://www.gnumonks.org/projects/ulogd</ulink>.
Ulogd can be configured to log all Shorewall messages 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>Once you have installed ulogd, edit /etc/ulogd.conf
(<filename>/usr/local/etc/ulogd.conf</filename> if you built ulogd
yourself) and set:</para>
<orderedlist>
<listitem>
<para>syslogfile &lt;<emphasis>the file that you wish to log
to</emphasis>&gt;</para>
</listitem>
<listitem>
<para>syslogsync 1</para>
</listitem>
</orderedlist>
<para>Also on the firewall system:</para>
<simplelist>
<member>touch &lt;<emphasis>the file that you wish to log
to</emphasis>&gt;</member>
</simplelist>
<para>Your distribution's ulogd package may include a logrotate file in
/etc/logrotate.d. If you change the log file location, be sure to change
that logrotate file accordingly.</para>
<para>You will need to change all instances of log levels (usually
<quote>info</quote>) in your Shorewall configuration files to
<quote>ULOG</quote> - this includes entries in the policy, rules and
shorewall.conf files. Here's what I had at one time:</para>
<programlisting>gateway:/etc/shorewall# grep -v ^\# * | egrep '\$LOG|ULOG|LOGFILE'
params:LOG=ULOG
policy:loc $FW REJECT $LOG
policy:net all DROP $LOG 10/sec:40
policy:all all REJECT $LOG
rules:REJECT:$LOG loc net tcp 25
rules:REJECT:$LOG loc net udp 1025:1031
rules:REJECT:$LOG dmz net udp 1025:1031
rules:ACCEPT:$LOG dmz net tcp 1024: 20
rules:REJECT:$LOG $FW net udp 1025:1031
shorewall.conf:LOGFILE=/var/log/shorewall
shorewall.conf:LOGUNCLEAN=$LOG
shorewall.conf:MACLIST_LOG_LEVEL=$LOG
shorewall.conf:TCP_FLAGS_LOG_LEVEL=$LOG
shorewall.conf:RFC1918_LOG_LEVEL=$LOG
gateway:/etc/shorewall# </programlisting>
<para>Finally edit /etc/shorewall/shorewall.conf and set
LOGFILE=&lt;<emphasis>file that you wish to log to</emphasis>&gt;. 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;amp;m=106040714910563&amp;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>