extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2025-02-22 04:31:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add shorewall-logging(5)

Browse Source 
Signed-off-by: Tom Eastep <teastep@shorewall.net>
This commit is contained in:
Tom Eastep 2017-11-02 14:16:33 -07:00
parent ef8b85fc3e
commit 8dfa0be611
No known key found for this signature in database
GPG Key ID: 96E6B3F2423A4D10
9 changed files with 417 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Shorewall-core/manpages/shorewall.xml
View File

@ -3187,14 +3187,15 @@
shorewall-arprules(5), shorewall-blrules(5), shorewall.conf(5),
shorewall-conntrack(5), shorewall-ecn(5), shorewall-exclusion(5),
shorewall-hosts(5), shorewall-init(5), shorewall_interfaces(5),
shorewall-ipsets(5), shorewall-maclist(5), shorewall-mangle(5),
shorewall-masq(5), shorewall-modules(5), shorewall-nat(5),
shorewall-nesting(5), shorewall-netmap(5), shorewall-params(5),
shorewall-policy(5), shorewall-providers(5), shorewall-proxyarp(5),
shorewall6-proxyndp(5), shorewall-routes(5), shorewall-rtrules(5),
shorewall-rtrules(5), shorewall-rules(5), shorewall-secmarks(5),
shorewall-snat(5), shorewall-tcclasses(5), shorewall-tcdevices(5),
shorewall-tcfilters(5), shorewall-tcinterfaces(5), shorewall-tcpri(5),
shorewall-tunnels(5), shorewall-vardir(5), shorewall-zones(5)</para>
shorewall-ipsets(5), shorewall-logging(), shorewall-maclist(5),
shorewall-mangle(5), shorewall-masq(5), shorewall-modules(5),
shorewall-nat(5), shorewall-nesting(5), shorewall-netmap(5),
shorewall-params(5), shorewall-policy(5), shorewall-providers(5),
shorewall-proxyarp(5), shorewall6-proxyndp(5), shorewall-routes(5),
shorewall-rtrules(5), shorewall-rtrules(5), shorewall-rules(5),
shorewall-secmarks(5), shorewall-snat(5), shorewall-tcclasses(5),
shorewall-tcdevices(5), shorewall-tcfilters(5), shorewall-tcinterfaces(5),
shorewall-tcpri(5), shorewall-tunnels(5), shorewall-vardir(5),
shorewall-zones(5)</para>
</refsect1>
</refentry>

6
Shorewall/manpages/shorewall-accounting.xml
View File

@ -791,11 +791,7 @@
<title>See ALSO</title>
<para><ulink
url="/Accounting.html">http://www.shorewall.net/Accounting.html
</ulink></para>
<para><ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink></para>
url="shorewall-logging.htm">shorewall-logging(5)</ulink></para>
<para><ulink
url="/configuration_file_basics.htm#Pairs">http://www.shorewall.net/configuration_file_basics.htm#Pairs</ulink></para>

4
Shorewall/manpages/shorewall-blrules.xml
View File

@ -167,7 +167,7 @@
<listitem>
<para>queues matching packets to a back end logging daemon via
a netlink socket then continues to the next rule. See <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
</listitem>
</varlistentry>
@ -258,7 +258,7 @@
<para>You may also specify <emphasis role="bold">NFLOG</emphasis>
(must be in upper case) as a log level.This will log to the NFLOG
target for routing to a separate log through use of ulogd (<ulink
url="http://www.netfilter.org/projects/ulogd/index.html">http://www.netfilter.org/projects/ulogd/index.html</ulink>).</para>
url="shorewall-logging.html">shorewall-logging.htm</ulink>).</para>
<para>Actions specifying logging may be followed by a log tag (a
string of alphanumeric characters) which is appended to the string

385
Shorewall/manpages/shorewall-logging.xml Normal file
View File

@ -0,0 +1,385 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry>
<refmeta>
<refentrytitle>shorewall-logging</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo>Configuration Files</refmiscinfo>
</refmeta>
<refnamediv>
<refname>logging</refname>
<refpurpose>Shorewall logging</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command><replaceable>action</replaceable>:<replaceable>level</replaceable></command>
</cmdsynopsis>
<cmdsynopsis>
<command>NFLOG(<replaceable>nflog-parameters</replaceable>)</command>
</cmdsynopsis>
<cmdsynopsis>
<command>ULOG(<replaceable>ulog-parameters</replaceable>)</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</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 connection. While the
packet can be logged using LOG rules in the ESTABLISHED section of
<ulink
url="manpages/shorewall-rules.html">/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="manpages/shorewall-rules.html">shorewall-rules(5)</ulink>.</para>
</listitem>
<listitem>
<para>The packet is rejected because of an option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5) or <ulink
url="manpages/shorewall-interfaces.html">shorewall-interfaces(5)</ulink>.
These packets can be logged by setting the appropriate logging-related
option in <ulink
url="manpages/shorewall.conf.html">/etc/shorewall/shorewall.conf</ulink>.</para>
</listitem>
<listitem>
<para>The packet matches a rule in <ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink>(5). 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="manpages/shorewall-policy.html">shorewall-policy(5)</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>
</refsect1>
<refsect1>
<title>Default Logging</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, the term
<emphasis>level</emphasis> rather than <emphasis>priority is used,
</emphasis>since <emphasis>level</emphasis> is the term used by Netfilter.
The syslog documentation uses the term
<emphasis>priority</emphasis>.</para>
</refsect1>
<refsect1>
<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>Beginning with Shorewall 4.5.5, the <replaceable>level</replaceable>
name or number may be optionally followed by a comma-separated list of one
or more<replaceable> log options</replaceable>. The list is enclosed in
parentheses. Log options cause additional information to be included in
each log message.</para>
<para>Valid log options are:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">ip_options</emphasis></term>
<listitem>
<para>Log messages will include the option settings from the IP
header.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">macdecode</emphasis></term>
<listitem>
<para>Decode the MAC address and protocol.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">tcp_sequence</emphasis></term>
<listitem>
<para>Include TCP sequence numbers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">tcp_options</emphasis></term>
<listitem>
<para>Include options from the TCP header.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">uid</emphasis></term>
<listitem>
<para>Include the UID of the sending program; only valid for packets
originating on the firewall itself.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Example: <emphasis
role="bold">info(tcp_options,tcp_sequence)</emphasis></para>
<para>Syslogd writes log messages to files (typically in <filename
class="directory">/var/log/</filename>*) 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>
</refsect1>
<refsect1>
<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 its 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>
<listitem>
<para>Netfilter (Shorewall) messages show up in
<command>dmesg</command>.</para>
</listitem>
</orderedlist>
<para>If your kernel has NFLOG target support (and most vendor-supplied
kernels do), you may also specify a log level of NFLOG (must be all caps).
When NFLOG is used, Shorewall will direct Netfilter to log the related
messages via the NFLOG target which will send them to a process called
<quote>ulogd</quote>. The ulogd program is included in most
distributions.</para>
<note>
<para>The NFLOG logging mechanism is <emphasis
role="underline">completely separate</emphasis> from syslog. Once you
switch to NFLOG, the settings in <filename>/etc/syslog.conf</filename>
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 change all instances of log levels (usually
<quote>info</quote>) in your Shorewall configuration files to
<quote>NFLOG</quote> - this includes entries in the policy, rules and
shorewall.conf files. If you initially installed using Shorewall 5.1.2 or
later, you can simply change the setting of LOG_LEVEL in
shorewall.conf.</para>
</refsect1>
<refsect1>
<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/en/2010/07/netfilter-log-format/">http://logi.cc/en/2010/07/netfilter-log-format/</ulink>.</para>
<para>For Shorewall-specific information, see <ulink
url="/FAQ.htm#faq17">FAQ #17</ulink>.</para>
</refsect1>
<refsect1>
<title>Customizing the Content of Shorewall Log Messages</title>
<para>In a Shorewall logging rule, the log level can be followed by a
<firstterm>log tag</firstterm> as in "DROP:NFLOG:junk". The generated log
message will include "<emphasis>chain-name</emphasis> junk DROP".</para>
<para>By setting the LOGTAGONLY option to Yes in <ulink
url="/manpages/shorewall.conf.html">shorewall.conf(5)</ulink> or <ulink
url="/manpages6/shorewall6.conf.html">shorewall6.conf(5)</ulink>, the
disposition ('DROP' in the above example) will be omitted. Consider the
following rule:</para>
<programlisting>#ACTION SOURCE DEST PROTO
REJECT(icmp-proto-unreachable):notice:IPv6 loc net 41 # who's using IPv6 tunneling</programlisting>
<para>This rule generates the following warning at compile time:</para>
<simplelist>
<member>WARNING: Log Prefix shortened to "Shorewall:IPv6:REJECT(icmp-p "
/etc/shorewall/rules (line 212)</member>
</simplelist>
<para>and produces the rather ugly prefix "Shorewall:IPv6:REJECT(icmp-p
".</para>
<para>Now consider this similar rule:</para>
<programlisting>#ACTION SOURCE DEST PROTO
REJECT(icmp-proto-unreachable):notice:IPv6,tunneling loc net 41 # who's using IPv6 tunneling</programlisting>
<para>With LOGTAGONLY=Yes, no warning is generated and the prefix becomes
"Shorewall:IPv6:tunneling:"</para>
<para>See the <ulink url="shorewall.conf.html">shorewall[6].conf man
page</ulink> for further information about how LOGTAGONLY=Yes can be
used.</para>
</refsect1>
<refsect1>
<title>Log Backends</title>
<para>Netfilter logging allows configuration of multiple backends. Logging
backends provide the The low-level forward of log messages. There are
currently three backends:</para>
<variablelist>
<varlistentry>
<term>LOG (ipt_LOG and ip6t_LOG).</term>
<listitem>
<para>Normal kernel-based logging to a syslog daemon.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ULOG (ipt_ULOG)</term>
<listitem>
<para>ULOG logging as described ablve. Only available for
IPv4.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>netlink (nfnetlink_log)</term>
<listitem>
<para>The logging backend behind NFLOG, defined above.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The currently-available and currently-selected IPv4 and IPv6
backends are shown in /proc/sys/net/netfilter/nf_log:</para>
<programlisting>cat /proc/net/netfilter/nf_log
0 NONE (nfnetlink_log)
1 NONE (nfnetlink_log)
2 ipt_ULOG (ipt_ULOG,ipt_LOG,nfnetlink_log)
3 NONE (nfnetlink_log)
4 NONE (nfnetlink_log)
5 NONE (nfnetlink_log)
6 NONE (nfnetlink_log)
7 NONE (nfnetlink_log)
8 NONE (nfnetlink_log)
9 NONE (nfnetlink_log)
10 ip6t_LOG (ip6t_LOG,nfnetlink_log)
11 NONE (nfnetlink_log)
12 NONE (nfnetlink_log)</programlisting>
<para>The magic numbers (0-12) are Linux address family numbers (AF_INET
is 2 and AF_INET6 is 10).</para>
<para>The name immediately following the number is the currently-selected
backend, and the ones in parantheses are the ones that are available. You
can change the currently selected backend by echoing it's name into
/proc/net/netfilter/nf_log.<replaceable>number</replaceable>.</para>
<para>Example - change the IPv4 backend to LOG:</para>
<programlisting>sysctl net.netfilter.nf_log.2=ipt_LOG</programlisting>
<para>Beginning with Shorewall 4.6.4, you can configure the backend using
the LOG_BACKEND option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> and <ulink
url="manpages6/shorewall6.conf.html">shorewall6.conf(5)</ulink>.</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para><ulink
url="/shorewall_logging.htm">http://www.shorewall.net/shorewall_logging.html</ulink></para>
</refsect1>
</refentry>

4
Shorewall/manpages/shorewall-policy.xml
View File

@ -279,8 +279,8 @@
separate log through use of ulogd (<ulink
url="http://www.netfilter.org/projects/ulogd/index.html">http://www.netfilter.org/projects/ulogd/index.html</ulink>).</para>
<para>For a description of log levels, see <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.</para>
<para>For a description of logging, see <ulink
url="/shorewall_logging.html">shorewall-logging(5)</ulink>.</para>
<para>If you don't want to log but need to specify the following
column, place "-" here.</para>

18
Shorewall/manpages/shorewall-rules.xml
View File

@ -67,7 +67,7 @@
this section.</para>
<para>The only ACTIONs allowed in this section are ACCEPT, DROP,
REJECT, LOG, NFQUEUE and QUEUE</para>
REJECT, LOG, NFLOG, NFQUEUE and QUEUE</para>
<para>There is an implicit ACCEPT rule inserted at the end of this
section.</para>
@ -82,7 +82,7 @@
section.</para>
<para>The only ACTIONs allowed in this section are ACCEPT, DROP,
REJECT, LOG, NFQUEUE and QUEUE</para>
REJECT, LOG, NFLOG, NFQUEUE and QUEUE</para>
<para>There is an implicit rule added at the end of this section
that invokes the RELATED_DISPOSITION (<ulink
@ -98,7 +98,7 @@
processed by rules in this section.</para>
<para>The only Actions allowed in this section are ACCEPT, DROP,
REJECT, LOG, NFQUEUE and QUEUE.</para>
REJECT, LOG, NFLOG, NFQUEUE and QUEUE.</para>
<para>There is an implicit rule added at the end of this section
that invokes the INVALID_DISPOSITION (<ulink
@ -114,7 +114,7 @@
processed by rules in this section.</para>
<para>The only Actions allowed in this section are ACCEPT, DROP,
REJECT, LOG, NFQUEUE and QUEUE.</para>
REJECT, LOG, NFLOG, NFQUEUE and QUEUE.</para>
<para>There is an implicit rule added at the end of this section
that invokes the UNTRACKED_DISPOSITION (<ulink
@ -908,7 +908,7 @@
<para>IPv4 only. Added in Shorewall 4.5.10. Queues matching
packets to a back end logging daemon via a netlink socket then
continues to the next rule. See <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
<para>Similar to<emphasis role="bold">
LOG:ULOG</emphasis>[(<replaceable>ulog-parameters</replaceable>)],
@ -956,7 +956,7 @@
(IPv4 only) or <emphasis role="bold">NFLOG</emphasis> (must be in
upper case) as a log level.This will log to the ULOG or NFLOG target
for routing to a separate log through use of ulogd (<ulink
url="http://www.netfilter.org/projects/ulogd/index.html">http://www.netfilter.org/projects/ulogd/index.html</ulink>).</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>).</para>
<para>Actions specifying logging may be followed by a log tag (a
string of alphanumeric characters) which is appended to the string
@ -2636,15 +2636,15 @@
<refsect1>
<title>See ALSO</title>
<para><ulink
url="shorewall-logging.html">shorewall-logging(5)</ulink></para>
<para><ulink
url="/ipsets.html">http://www.shorewall.net/ipsets.html</ulink></para>
<para><ulink
url="/configuration_file_basics.htm#Pairs">http://www.shorewall.net/configuration_file_basics.htm#Pairs</ulink></para>
<para><ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink></para>
<para>shorewall(8)</para>
</refsect1>
</refentry>

6
Shorewall/manpages/shorewall-snat.xml
View File

@ -56,7 +56,7 @@
5.1.9, with the exception of NFLOG and ULOG, the action may be
followed by a colon (":") and a <replaceable>log level</replaceable>
(see <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>).</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>).</para>
<para>Choices for ACTION are:</para>
@ -121,7 +121,7 @@
<para>Added in Shorewall 5.1.9. Queues matching packets to a
back end logging daemon via a netlink socket then continues to
the next rule. See <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
<para>The <replaceable>nflog-parameters</replaceable> are a
comma-separated list of up to 3 numbers:</para>
@ -220,7 +220,7 @@
<para>IPv4 only. Added in Shorewall 5.1.9. Queues matching
packets to a back end logging daemon via a netlink socket then
continues to the next rule. See <ulink
url="/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.</para>
url="shorewall-logging.html">shorewall-logging(5)</ulink>.</para>
<para>Similar to<emphasis role="bold">
LOG:ULOG</emphasis>[(<replaceable>ulog-parameters</replaceable>)],

7
Shorewall/manpages/shorewall.conf.xml
View File

@ -1566,10 +1566,9 @@ net all DROP info</programlisting>then the chain name is 'net-all'
log</emphasis>, and <emphasis role="bold">hits</emphasis> commands.
If not assigned or if assigned an empty value, /var/log/messages is
assumed. For further information, see <ulink
url="/manpages/shorewall_logging.html">http://www.shorewall.net/shorewall_logging.html</ulink>.
Beginning with Shorewall 5.0.10.1, you may specify
<option>systemd</option> to use <command>journelctl -r</command> to
read the log.</para>
url="shorewall-logging.html">shorewall-logging(8)</ulink>. Beginning
with Shorewall 5.0.10.1, you may specify <option>systemd</option> to
use <command>journelctl -r</command> to read the log.</para>
</listitem>
</varlistentry>

4
docs/shorewall_logging.xml
View File

@ -248,7 +248,7 @@
<para>If your kernel has NFLOG target support (and most vendor-supplied
kernels do), you may also specify a log level of NFLOG (must be all
caps). When NFLOG is used, Shorewall will direct Netfilter to log the
related messages via the ULOG target which will send them to a process
related messages via the NFLOG 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.netfilter.org/projects/ulogd/index.html">http://www.netfilter.org/projects/ulogd/index.html</ulink>.
@ -258,7 +258,7 @@
<note>
<para>The NFLOG logging mechanism is <emphasis
role="underline">completely separate</emphasis> from syslog. Once you
switch to ULOG, the settings in <filename>/etc/syslog.conf</filename>
switch to NFLOG, the settings in <filename>/etc/syslog.conf</filename>
have absolutely no effect on your Shorewall logging (except for
Shorewall status messages which still go to syslog).</para>
</note>