"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4 <article>
5 <!--$Id$-->
6
7 <articleinfo>
8 <title>Shorewall and Ipsets</title>
9
10 <authorgroup>
11 <author>
12 <firstname>Tom</firstname>
13
14 <surname>Eastep</surname>
15 </author>
16 </authorgroup>
17
18 <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
19
20 <copyright>
21 <year>2005</year>
22
23 <year>2008</year>
24
25 <year>2010</year>
26
27 <year>2015</year>
28
29 <year>2017</year>
30
31 <year>2019</year>
32
33 <year>2020</year>
34
35 <holder>Thomas M. Eastep</holder>
36 </copyright>
37
38 <legalnotice>
39 <para>Permission is granted to copy, distribute and/or modify this
40 document under the terms of the GNU Free Documentation License, Version
41 1.2 or any later version published by the Free Software Foundation; with
42 no Invariant Sections, with no Front-Cover, and with no Back-Cover
43 Texts. A copy of the license is included in the section entitled
44 <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
45 License</ulink></quote>.</para>
46 </legalnotice>
47 </articleinfo>
48
49 <caution>
50 <para><emphasis role="bold">This article applies to Shorewall 4.4 and
51 later. If you are running a version of Shorewall earlier than Shorewall
52 4.4.0 then please see the documentation appropriate for your
53 version.</emphasis></para>
54 </caution>
55
56 <section id="Ipsets">
57 <title>What are Ipsets?</title>
58
59 <para>Ipsets are an extension to Netfilter/iptables that are available in
60 <ulink url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>
61 if they are not available in your current distribution. Instructions for
62 installing xtables-addons may be found in the <ulink
63 url="Dynamic.html">Dynamic Zones article</ulink>. Note that xtables-addons
64 might not be required with the 'ipset' package provided by your
65 distribution. See also the section <ulink
66 url="configuration_file_basics.htm#capabilities">capabilities</ulink> in
67 the <ulink url="configuration_file_basics.htm">configuration file basics
68 article</ulink> and the <ulink url="Shorewall-Lite.html#Shorecap">Shorecap
69 program</ulink>.</para>
70
71 <para>Ipset allows you to create one or more named sets of addresses then
72 use those sets to define Netfilter/iptables rules. Possible uses of ipsets
73 include:</para>
74
75 <orderedlist>
76 <listitem>
77 <para>Blacklists. Ipsets provide an efficient way to represent large
78 sets of addresses and you can maintain the lists without the need to
79 restart or even refresh your Shorewall configuration.</para>
80 </listitem>
81
82 <listitem>
83 <para>Zone definition. Using the /etc/shorewall/hosts file, you can
84 <ulink url="Dynamic.html">define a zone based on the (dynamic)
85 contents of an ipset</ulink>. Again, you can then add or delete
86 addresses to the ipset without restarting Shorewall.</para>
87 </listitem>
88 </orderedlist>
89
90 <para>See the ipsets site (URL above) for additional information about
91 ipsets.</para>
92 </section>
93
94 <section id="Support">
95 <title>Shorewall Support for Ipsets</title>
96
97 <para>Support for ipsets was introduced in Shorewall version 2.3.0. In
98 most places where a host or network address may be used, you may also use
99 the name of an ipset prefaced by "+".</para>
100
101 <para>Example: "+Mirrors"</para>
102
103 <para>When using Shorewall, the names of ipsets are restricted as
104 follows:</para>
105
106 <itemizedlist>
107 <listitem>
108 <para>They must begin with a letter (after the '+').</para>
109 </listitem>
110
111 <listitem>
112 <para>They must be composed of letters, digits, dashes ("-") or
113 underscores ("_").</para>
114 </listitem>
115 </itemizedlist>
116
117 <para>To generate a negative match, prefix the "+" with "!" as in
118 "!+Mirrors".</para>
119
120 <para>Example 1: Blacklist all hosts in an ipset named "blacklist"</para>
121
122 <para><filename>/etc/shorewall/blrules</filename><programlisting>#ACTION SOURCE DEST PROTO DPORT
123 DROP net:+blacklist</programlisting></para>
124
125 <para>Example 2: Allow SSH from all hosts in an ipset named "sshok:</para>
126
127 <para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION SOURCE DEST PROTO DPORT
128 ACCEPT net:+sshok $FW tcp 22</programlisting></para>
129
130 <para>The name of the ipset can be optionally followed by a
131 comma-separated list of flags enclosed in square brackets ([...]). Each
132 flag is either <emphasis role="bold">src</emphasis> or <emphasis
133 role="bold">dst</emphasis> and specifies whether it is the SOURCE address
134 or port number or the DESTINATION address or port number that should be
135 matched. The number of flags must be appropriate for the type of ipset. If
136 no flags are given, Shorewall assumes that the set takes a single flag and
137 will select the flag based on the context. For example, in the blacklist
138 file and when the ipset appears in the SOURCE column of the rules file,
139 <emphasis role="bold">src</emphasis> is assumed. If the ipset appears in
140 the DEST column of the rules file, <emphasis role="bold">dst</emphasis> is
141 assumed. Note that by using <emphasis role="bold">[dst]</emphasis> in the
142 blacklist file, you can coerce the rule into matching the destination IP
143 address rather than the source.</para>
144
145 <para>Beginning with Shorewall 4.4.14, multiple source or destination
146 matches may be specified by placing multiple set names in '+[...]' (e.g.,
147 +[myset,myotherset]). When so enclosed, the set names need not be prefixed
148 with a plus sign. When such a list of sets is specified, matching packets
149 must match all of the listed sets.</para>
150
151 <para>Shorewall can save/restore your ipset contents with certain
152 restrictions:</para>
153
154 <orderedlist>
155 <listitem>
156 <para>You must set SAVE_IPSETS=Yes in <ulink
157 url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
158 </listitem>
159
160 <listitem>
161 <para>You must have at least one entry in the other configuration
162 files that uses an ipset.</para>
163 </listitem>
164
165 <listitem>
166 <para>You can use an ipset in <ulink
167 url="manpages/shorewall-stoppedulres.html">shorewall-stoppedrules</ulink>
168 (5), but SAVE_IPSET={Yes|ipv4} will not save such a set during 'stop'
169 processing. Use Shorewall-init to save/restore your ipsets in this
170 case (see below).</para>
171 </listitem>
172
173 <listitem>
174 <para>The <command>restore</command> command cannot restore ipset
175 contents saved by the <command>save</command> command unless the
176 firewall is first stopped.</para>
177 </listitem>
178 </orderedlist>
179
180 <para>Beginning with Shorewall 4.6.4, you can save selective ipsets by
181 setting SAVE_IPSETS to a comma-separated list of ipset names. You can also
182 restrict the group of sets saved to ipv4 sets by setting
183 SAVE_IPSETS=ipv4.</para>
184
185 <para>With Shorewall 4.6.4, the SAVE_IPSETS option may specify a list of
186 ipsets to be saved. When such a list is specified, only those ipsets
187 together with the ipsets supporting dynamic zones are saved. Shorewall6
188 support for the SAVE_IPSETS option was also added in 4.6.4. When
189 SAVE_IPSETS=Yes in <ulink
190 url="manpages/shorewall.conf.html">shorewall6.conf(5)</ulink>, only ipv6
191 ipsets are saved. For Shorewall, if SAVE_IPSETS=ipv4 in <ulink
192 url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink>, then only
193 ipv4 ipsets are saved. Both features require ipset version 5 or
194 later.</para>
195
196 <caution>
197 <para>After setting SAVE_IPSETS, it is important to recompile the
198 firewall script (e.g., 'shorewall compile', 'shorewall reload' or
199 'shorewall restart') before rebooting</para>
200 </caution>
201
202 <para>Although Shorewall can save the definition of your ipsets and
203 restore them when Shorewall starts, in most cases you must use the ipset
204 utility to initially create and load your ipsets. The exception is that
205 Shorewall will automatically create an empty iphash ipset to back each
206 dynamic zone. It will also create the ipset required by the
207 DYNAMIC_BLACKLIST=ipset:.. setting in <ulink
208 url="manpages/shorewall.conf.html">shorewall[6].conf(5)</ulink>,</para>
209 </section>
210
211 <section>
212 <title>Shorewall6 and Shorewall-init Support for Ipsets</title>
213
214 <para>Ipset support in Shorewall6 was added in Shorewall 4.4.21.</para>
215
216 <para>Beginning with Shorewall 4.6.4, SAVE_IPSETS is available in <ulink
217 url="manpages/shorewall.conf.html">shorewall6-conf(5)</ulink>. When set to
218 Yes, the ipv6 ipsets will be saved. You can also save selective ipsets by
219 setting SAVE_IPSETS to a comma-separated list of ipset names.</para>
220
221 <para>Prior to Shorewall 4.6.4, SAVE_IPSETS=Yes in <ulink
222 url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> won't work
223 correctly because it saves both IPv4 and IPv6 ipsets. To work around this
224 issue, Shorewall-init is capable restoring ipset contents during 'start'
225 and saving them during 'stop'. To direct Shorewall-init to save/restore
226 ipset contents, set the SAVE_IPSETS option in
227 /etc/sysconfig/shorewall-init (/etc/default/shorewall-init on Debian and
228 derivatives). The value of the option is a file name where the contents of
229 the ipsets will be save to and restored from. Shorewall-init will create
230 any necessary directories during the first 'save' operation.</para>
231
232 <caution>
233 <para>If you set SAVE_IPSETS in /etc/sysconfig/shorewall-init
234 (/etc/default/shorewall-init on Debian and derivatives) when
235 shorewall-init has not been started by systemd, then when the system is
236 going down during reboot, the ipset contents will not be saved. You can
237 work around that as follows:</para>
238
239 <itemizedlist>
240 <listitem>
241 <para>Suppose that you have set
242 SAVE_IPSETS=/var/lib/shorewall/init-save-ipsets.</para>
243 </listitem>
244
245 <listitem>
246 <para>Before rebooting, execute this command:</para>
247
248 <programlisting>ipset save > /var/lib/shorewall/init-save-ipsets</programlisting>
249 </listitem>
250
251 <listitem>
252 <para>Be sure to enable shoewall-init (e.g., <emphasis
253 role="bold">systemctl enable shorewall-init</emphasis>).</para>
254 </listitem>
255 </itemizedlist>
256 </caution>
257
258 <para>If you configure Shorewall-init to save/restore ipsets, be sure to
259 set SAVE_IPSETS=No in shorewall.conf and shorewall6.conf.</para>
260
261 <para>If you configure SAVE_IPSETS in <ulink
262 url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> and/or <ulink
263 url="manpages/shorewall.conf.html">shorewall6.conf(5)</ulink> then do not
264 set SAVE_IPSETS in shorewall-init.</para>
265 </section>
266 </article>