<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Shorewall Logging</title><link rel="stylesheet" href="html.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="IPIP"></a>Shorewall Logging</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Eastep</span></h3></div></div></div><div><p class="copyright">Copyright © 2001 - 2007 Thomas M. Eastep</p></div><div><div class="legalnotice"><a id="id286316"></a><p>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
“<span class="quote"><a class="ulink" href="GnuCopyright.htm" target="_self">GNU Free Documentation
License</a></span>”.</p></div></div><div><p class="pubdate">2008/12/15</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#Log">How to Log Traffic Through a Shorewall Firewall</a></span></dt><dt><span class="section"><a href="#Where">Where the Traffic is Logged and How to Change the
Destination</a></span></dt><dd><dl><dt><span class="section"><a href="#Levels">Syslog Levels</a></span></dt><dt><span class="section"><a href="#ULOG">Configuring a Separate Log for Shorewall Messages (ulogd)</a></span></dt></dl></dd><dt><span class="section"><a href="#Syslog-ng">Syslog-ng</a></span></dt><dt><span class="section"><a href="#Contents">Understanding the Contents of Shorewall Log Messages</a></span></dt></dl></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p><span class="bold"><strong>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.</strong></span></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Log"></a>How to Log Traffic Through a Shorewall Firewall</h2></div></div></div><p>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.</p><div class="orderedlist"><ol type="1"><li><p>The packet is part of an established connection. While the
packet can be logged using LOG rules in the ESTABLISHED section of
<a class="ulink" href="manpages/shorewall-rules.html" target="_self">/etc/shorewall/rules</a>, that
is not recommended because of the large amount of information that may
be logged.</p></li><li><p>The packet represents a connection request that is related to an
established connection (such as a <a class="ulink" href="FTP.html" target="_self">data
connection associated with an FTP control connection</a>). These
packets may be logged using LOG rules in the RELATED section of <a class="ulink" href="manpages/shorewall-rules.html" target="_self">/etc/shorewall/rules</a>.</p></li><li><p>The packet is rejected because of an option in <a class="ulink" href="manpages/shorewall.conf.html" target="_self">/etc/shorewall/shorewall.conf</a>
or <a class="ulink" href="manpages/shorewall-interfaces.html" target="_self">/etc/shorewall/interfaces</a>.
These packets can be logged by setting the appropriate logging-related
option in <a class="ulink" href="manpages/shorewall.conf.html" target="_self">/etc/shorewall/shorewall.conf</a>.</p></li><li><p>The packet matches a rule in <a class="ulink" href="manpages/shorewall-rules.html" target="_self">/etc/shorewall/rules</a>. By
including a syslog level (see below) in the ACTION column of a rule
(e.g., “<span class="quote">ACCEPT<span class="bold"><strong>:info</strong></span> net $FW tcp
22</span>”), the connection attempt will be logged at that
level.</p></li><li><p>The packet doesn't match a rule so it is handled by a policy
defined in <a class="ulink" href="manpages/shorewall-policy.html" target="_self">/etc/shorewall/policy</a>.
These may be logged by specifying a syslog level in the LOG LEVEL
column of the policy's entry (e.g., “<span class="quote">loc net ACCEPT <span class="bold"><strong>info</strong></span></span>”).</p></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Where"></a>Where the Traffic is Logged and How to Change the
Destination</h2></div></div></div><p>By default, Shorewall directs Netfilter to log using syslog (8).
Syslog classifies log messages by a <span class="emphasis"><em>facility</em></span> and a
<span class="emphasis"><em>priority</em></span> (using the notation
<span class="emphasis"><em>facility.priority</em></span>).</p><p>The facilities defined by syslog are <span class="emphasis"><em>auth, authpriv, cron,
daemon, kern, lpr, mail, mark, news, syslog, user, uucp</em></span> and
<span class="emphasis"><em>local0</em></span> through <span class="emphasis"><em>local7.</em></span></p><p>Throughout the Shorewall documentation, I will use the term
<span class="emphasis"><em>level</em></span> rather than <span class="emphasis"><em>priority </em></span>since
<span class="emphasis"><em>level</em></span> is the term used by Netfilter. The syslog
documentation uses the term <span class="emphasis"><em>priority</em></span>.</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="Levels"></a>Syslog Levels</h3></div></div></div><p>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.</p><p>Valid levels are:</p><table class="simplelist" border="0" summary="Simple list"><tr><td>7 - <span class="bold"><strong>debug</strong></span> (Debug-level
messages)</td></tr><tr><td>6 - <span class="bold"><strong>info</strong></span>
(Informational)</td></tr><tr><td>5 - <span class="bold"><strong>notice</strong></span> (Normal but
significant Condition)</td></tr><tr><td>4 - <span class="bold"><strong>warning</strong></span> (Warning
Condition)</td></tr><tr><td>3 - <span class="bold"><strong>err</strong></span> (Error
Condition)</td></tr><tr><td>2 - <span class="bold"><strong>crit</strong></span> (Critical
Conditions)</td></tr><tr><td>1 - <span class="bold"><strong>alert</strong></span> (must be handled
immediately)</td></tr><tr><td>0 - <span class="bold"><strong>emerg</strong></span> (System is
unusable)</td></tr></table><p>For most Shorewall logging, a level of 6 (info) is appropriate.
Shorewall log messages are generated by Netfilter and are logged using
the <span class="emphasis"><em>kern</em></span> 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.</p><p>Syslogd writes log messages to files (typically in <code class="filename">/var/log/</code>*) 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.</p><p>Syslog may also write to your system console. See <a class="ulink" href="FAQ.htm#faq16" target="_self">Shorewall FAQ 16</a> for ways to avoid having
Shorewall messages written to the console.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="ULOG"></a>Configuring a Separate Log for Shorewall Messages (ulogd)</h3></div></div></div><p>There are a couple of limitations to syslogd-based logging:</p><div class="orderedlist"><ol type="1"><li><p>If you give, for example, kern.info its own log destination
then that destination will also receive all kernel messages of
levels 5 (notice) through 0 (emerg).</p></li><li><p>All kernel.info messages will go to that destination and not
just those from Netfilter.</p></li></ol></div><p>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 “<span class="quote">ulogd</span>”.
The ulogd program is included in most distributions and is also
available from <a class="ulink" href="http://www.netfilter.org/projects/ulogd/index.html" target="_self">http://www.netfilter.org/projects/ulogd/index.html</a>.
Ulogd can be configured to log all Shorewall messages to their own log
file.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The ULOG logging mechanism is <span class="underline">completely separate</span> from syslog. Once you
switch to ULOG, the settings in <code class="filename">/etc/syslog.conf</code>
have absolutely no effect on your Shorewall logging (except for
Shorewall status messages which still go to syslog).</p></div><p>You will need to change all instances of log levels (usually
“<span class="quote">info</span>”) in your Shorewall configuration files to
“<span class="quote">ULOG</span>” - this includes entries in the policy, rules and
shorewall.conf files. Here's what I had at one time:</p><pre class="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# </pre><p>Finally edit <code class="filename">/etc/shorewall/shorewall.conf</code>
and set LOGFILE=<<span class="emphasis"><em>file that you wish to log
to</em></span>>. This tells the <code class="filename">/sbin/shorewall</code>
program where to look for the log when processing its
“<span class="quote"><span class="command"><strong>show log</strong></span></span>”,
“<span class="quote"><span class="command"><strong>logwatch</strong></span></span>” and
“<span class="quote"><span class="command"><strong>dump</strong></span></span>” commands.</p><p>Beginning in Shorewall-perl 4.1, the NFLOG target is
supported.</p><p>NFLOG is a successor to ULOG. When using <a class="ulink" href="Shorewall-perl.html" target="_self">Shorewall-perl</a> 4.1 or later, both ULOG
and NFLOG may be followed by a list of up to three numbers in
parentheses.</p><div class="itemizedlist"><ul type="disc"><li><p>The first number specifies the netlink group (1-32). If
omitted (e.g., NFLOG(,0,10)) then a value of 1 is assumed.</p></li><li><p>The second number specifies the maximum number of bytes to
copy. If omitted, 0 (no limit) is assumed.</p></li><li><p>The third number specifies the number of log messages that
should be buffered in the kernel before they are sent to user space.
The default is 1.</p></li></ul></div><p>Examples:</p><p><code class="filename">/etc/shorewall/shorewall.conf</code>:
</p><pre class="programlisting">MACLIST_LOG_LEVEL=NFLOG(1,0,1)</pre><p><code class="filename">/etc/shorewall/rules</code>:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST
# PORT(S)
ACCEPT:NFLOG(1,0,1) vpn fw tcp ssh,time,631,8080 </pre></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Syslog-ng"></a>Syslog-ng</h2></div></div></div><p><a class="ulink" href="http://marc.theaimsgroup.com/?l=gentoo-security&amp;m=106040714910563&amp;w=2" target="_self">Here</a>
is a post describing configuring syslog-ng to work with Shorewall. Recent
<span class="trademark">SUSE</span>™ releases come preconfigured with syslog-ng
with Netfilter messages (including Shorewall's) are written to
<code class="filename">/var/log/firewall</code>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Contents"></a>Understanding the Contents of Shorewall Log Messages</h2></div></div></div><p>For general information on the contents of Netfilter log messages,
see <a class="ulink" href="http://logi.cc/linux/netfilter-log-format.php3" target="_self">http://logi.cc/linux/netfilter-log-format.php3</a>.</p><p>For Shorewall-specific information, see <a class="ulink" href="FAQ.htm#faq17" target="_self">FAQ #17</a>.</p></div></div></body></html>
