1
0
mirror of https://gitlab.com/shorewall/code.git synced 2024-12-28 09:08:48 +01:00
shorewall_code/docs/ipsets.xml
Tom Eastep a990ceecba Clarify ipsets WRT xtables-addons.
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2013-03-08 08:18:00 -08:00

178 lines
6.9 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
<!--$Id$-->
<articleinfo>
<title>Shorewall and Ipsets</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2005</year>
<year>2008</year>
<year>2010</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 4.4 and
later. If you are running a version of Shorewall earlier than Shorewall
4.4.0 then please see the documentation appropriate for your
version.</emphasis></para>
</caution>
<section id="Ipsets">
<title>What are Ipsets?</title>
<para>Ipsets are an extension to Netfilter/iptables that are available in
<ulink url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>
if they are not available in your current distribution. Instructions for
installing xtables-addons may be found in the <ulink
url="Dynamic.html">Dynamic Zones article</ulink>.</para>
<para>Ipset allows you to create one or more named sets of addresses then
use those sets to define Netfilter/iptables rules. Possible uses of ipsets
include:</para>
<orderedlist>
<listitem>
<para>Blacklists. Ipsets provide an efficient way to represent large
sets of addresses and you can maintain the lists without the need to
restart or even refresh your Shorewall configuration.</para>
</listitem>
<listitem>
<para>Zone definition. Using the /etc/shorewall/hosts file, you can
<ulink url="Dynamic.html">define a zone based on the (dynamic)
contents of an ipset</ulink>. Again, you can then add or delete
addresses to the ipset without restarting Shorewall.</para>
</listitem>
</orderedlist>
<para>See the ipsets site (URL above) for additional information about
ipsets.</para>
</section>
<section id="Support">
<title>Shorewall Support for Ipsets</title>
<para>Support for ipsets was introduced in Shorewall version 2.3.0. In
most places where a host or network address may be used, you may also use
the name of an ipset prefaced by "+".</para>
<para>Example: "+Mirrors"</para>
<para>When using Shorewall, the names of ipsets are restricted as
follows:</para>
<itemizedlist>
<listitem>
<para>They must begin with a letter (after the '+').</para>
</listitem>
<listitem>
<para>They must be composed of letters, digits, dashes ("-") or
underscores ("_").</para>
</listitem>
</itemizedlist>
<para>To generate a negative match, prefix the "+" with "!" as in
"!+Mirrors".</para>
<para>Example 1: Blacklist all hosts in an ipset named "blacklist"</para>
<para><filename>/etc/shorewall/blacklist</filename><programlisting>#ADDRESS/SUBNET PROTOCOL PORT
+blacklist</programlisting></para>
<para>Example 2: Allow SSH from all hosts in an ipset named "sshok:</para>
<para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT net:+sshok $FW tcp 22</programlisting></para>
<para>The name of the ipset can be optionally followed by a
comma-separated list of flags enclosed in square brackets ([...]). Each
flag is either <emphasis role="bold">src</emphasis> or <emphasis
role="bold">dst</emphasis> and specifies whether it is the SOURCE address
or port number or the DESTINATION address or port number that should be
matched. The number of flags must be appropriate for the type of ipset. If
no flags are given, Shorewall assumes that the set takes a single flag and
will select the flag based on the context. For example, in the blacklist
file and when the ipset appears in the SOURCE column of the rules file,
<emphasis role="bold">src</emphasis> is assumed. If the ipset appears in
the DEST column of the rules file, <emphasis role="bold">dst</emphasis> is
assumed. Note that by using <emphasis role="bold">[dst]</emphasis> in the
blacklist file, you can coerce the rule into matching the destination IP
address rather than the source.</para>
<para>Beginning with Shorewall 4.4.14, multiple source or destination
matches may be specified by placing multiple set names in '+[...]' (e.g.,
+[myset,myotherset]). When so inclosed, the set names need not be prefixed
with a plus sign.</para>
<para>Shorewall can save/restore your ipset contents with certain
restrictions:</para>
<orderedlist>
<listitem>
<para>You must set SAVE_IPSETS=Yes in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
</listitem>
<listitem>
<para>You cannot use an ipset in <ulink
url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
(5).</para>
</listitem>
<listitem>
<para>The <command>restore</command> command cannot restore ipset
contents saved by the <command>save</command> command unless the
firewall is first stopped.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Shorewall6 and Shorewall-init Support for Ipsets</title>
<para>Ipset support in Shorewall6 was added in Shorewall 4.4.21.</para>
<para>Unlike iptables, which has separate configurations for IPv4 and
IPv6, ipset has a single configuration that handles both. This means the
SAVE_IPSETS=Yes in shorewall.conf or shorewall6.conf won't work correctly
because . To work around this issue, Shorewall-init is now capable
restoring ipset contents during 'start' and saving them during 'stop'. To
direct Shorewall-init to save/restore ipset contents, set the SAVE_IPSETS
option in /etc/sysconfig/shorewall-init (/etc/default/shorewall-init on
Debian and derivatives). The value of the option is a file name where the
contents of the ipsets will be save to and restored from. Shorewall-init
will create any necessary directories during the first 'save' operation.
If you configure Shorewall-init to save/restore ipsets, be sure to set
SAVE_IPSETS=No in shorewall.conf and shorewall6.conf.</para>
</section>
</article>