forked from extern/shorewall_code
75a9e45caf
- Update Copyright years - Tweaks to the Anatomy article Signed-off-by: Tom Eastep <teastep@shorewall.net>
571 lines
20 KiB
XML
571 lines
20 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 5</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2015</year>
|
|
|
|
<year>2016</year>
|
|
|
|
<year>2017</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>
|
|
|
|
<section>
|
|
<title>Introduction</title>
|
|
|
|
<para>There are currently three principle groups of changes that
|
|
distinguish Shorewall 5 from Shorewall 4:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Cruft Removal - over the years, as new ways to accomplish
|
|
various tasks are added to Shorewall, support for the old way of doing
|
|
things has generally been retained but deprecated. Shorewall 5 drops
|
|
support for those deprecated features.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes to CLI commands - In order to make command names more
|
|
accurately reflect what the associated commands do, a number of
|
|
commands have been renamed or the function that they perform has been
|
|
changed.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CLI unification - Beginning with Shorewall 5.1.0, there is a
|
|
single CLI program (<filename>/sbin/shorewall </filename>or
|
|
<filename>/usr/sbin/shorewall</filename> depending on your
|
|
distribution).</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Each of these groups is described in more detail in the sections
|
|
that follow.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Cruft Removal</title>
|
|
|
|
<para>Removal of superseded features makes the code cleaner and easier to
|
|
extend while also reducing compilation and execution time. The following
|
|
subsections detail the features that are no longer supported in Shorewall
|
|
5.</para>
|
|
|
|
<section>
|
|
<title>Scripts Compiled with Shorewall 4.4.7 or Earlier</title>
|
|
|
|
<para>Shorewall 5 cannot correctly run scripts compiled with Shorewall
|
|
4.4.7 or earlier releases. Such scripts must be recompiled with 4.4.8 or
|
|
later prior to upgrading to Shorewall 5.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Workarounds</title>
|
|
|
|
<para>Over the years, a number of workarounds have been added to
|
|
Shorewall to work around defects in other products. In current
|
|
distributions, those defects have been corrected, and in 4.6.11, a
|
|
WORKAROUNDS configuration option was added to disable those workarounds.
|
|
In Shorewall 5, the WORKAROUNDS setting is still available in the
|
|
shorewall[6].conf files but:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Its default setting has been changed to No.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>All workarounds for old distributions have been
|
|
eliminated.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If there is a need to add new workarounds in the future, those
|
|
workarounds will be enabled by WORKAROUNDS=Yes.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Removal of Configuration Options</title>
|
|
|
|
<para>A number of configuration options have been eliminated in
|
|
Shorewall 5. The following options have been eliminated and the
|
|
functionality that they enabled is been removed:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>EXPORTPARAMS</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>IPSECFILE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>LEGACY_FASTSTART</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CHAIN_SCRIPTS (Removed in Shorewall 5.1).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>A compilation warning is issued when any of these options are
|
|
encountered in the .conf file, and the <command>shorewall[6]
|
|
update</command> command will remove them from the configuration
|
|
file.</para>
|
|
|
|
<para>These options have been eliminated because they have been
|
|
superseded by newer options.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>LOGRATE and LOGBURST (superseded by LOGLIMIT)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>WIDE_TC_MARKS (superseded by TC_BITS)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>HIGH_ROUTE_MARKS (superseded by PROVIDER_OFFSET)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>BLACKLISTNEWONLY (superseded by BLACKLIST)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>A fatal compilation error is emitted if any of these options are
|
|
present in the .conf file, and the <command>shorewall[6]
|
|
update</command> command will replace these options with equivalent
|
|
setting of the options that supersede them.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Obsolete Configuration Files</title>
|
|
|
|
<para>Support has been removed for the 'blacklist', 'tcrules',
|
|
'routestopped', 'notrack' and 'tos' files.</para>
|
|
|
|
<para>The <option>-t</option> and <option>-b</option> options of the
|
|
<command>update</command> command are still available to convert the
|
|
'tcrules' and 'tos' files to the equivalent 'mangle' file and to convert
|
|
the 'blacklist' file into an equivalent 'blrules' file.</para>
|
|
|
|
<para>As in Shorewall 4.6.12, the <option>-s</option> option is
|
|
available to convert the 'routestopped' file into the equivalent
|
|
'stoppedrules' file and the <option>-n</option> option is available to
|
|
convert a 'notrack' file to the equivalent 'conntrack' file.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Macro and Action Formats</title>
|
|
|
|
<para>Originally, macro and action files had formats that were different
|
|
from that of the rules file,</para>
|
|
|
|
<para>Format-1 action files had the following columns:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>TARGET</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>SOURCE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DEST</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>PROTO</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DEST PORT(S)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>SOURCE PORT(S)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>RATE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>USER/GROUP</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MARK</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Format-1 macro files were similar but did not support the MARK
|
|
column.</para>
|
|
|
|
<para>Format-2 macro and action files have these columns:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>TARGET</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>SOURCE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DEST</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>PROTO</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DPORT</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>SPORT</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>ORIGDEST</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>RATE</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>USER/GROUP</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MARK</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CONNLIMIT</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>TIME</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>HEADERS (Only valid for IPv6)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>SWITCH</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>HELPER</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Notice that the first five columns of both sets are the same
|
|
(although the port-valued column names have changed, the contents are
|
|
the same).</para>
|
|
|
|
<para>In Shorewall 5, support for format-1 macros and actions has been
|
|
dropped and all macros and actions will be processed as if ?FORMAT 2
|
|
were included before the first entry. Given that the vast majority of
|
|
actions and macros only use the first five columns, this change will be
|
|
of no concern to most users, but will cause compilation errors if
|
|
columns beyold the fifth one are populated.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>COMMENT, FORMAT and SECTION Lines</title>
|
|
|
|
<para>COMMENT, FORMAT and SECTION Lines now require the leading question
|
|
mark ("?"). In earlier releases, the question mark was optional. The
|
|
<command>shorewall[6] update -D</command> command in Shorewall 4.6 will
|
|
insert the question marks for you.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>CLI Command Changes</title>
|
|
|
|
<para>A number of commands have been renamed and/or now perform a
|
|
different function.</para>
|
|
|
|
<section>
|
|
<title>restart</title>
|
|
|
|
<para>The <command>restart</command> command now does a true restart and
|
|
is equivalent to a <command>stop</command> followed by a
|
|
<command>start</command>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>load</title>
|
|
|
|
<para>The function performed by the Shorewall-4 <command>load</command>
|
|
command is now performed by the <command>remote-start</command>
|
|
command.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>reload</title>
|
|
|
|
<para>In Shorewall 5, the <command>reload</command> command now performs
|
|
the same function as the <command>restart</command> command did in
|
|
Shorewall 4. The action taken by the Shorewall-4
|
|
<command>reload</command> command is now performed by the
|
|
<command>remote-restart</command> command.</para>
|
|
|
|
<para>For those that can't get used to the idea of using
|
|
<command>reload</command> in place of <command>restart</command>, a
|
|
RESTART option has been added to shorewall[6].conf. The option defaults
|
|
to 'restart' but if set to 'reload', then the <command>restart</command>
|
|
command does what it did in earlier releases.</para>
|
|
|
|
<note>
|
|
<para>Beginning with Shorewall 5.0.1 and Shorewall 4.6.13.2, the
|
|
update command will set RESTART=reload to maintain compatibility with
|
|
earlier releases. Shorewall 5.0.0 created the setting
|
|
LEGACY_RESTART=No which was equivalent to RESTART=restart. Under
|
|
Shorewall 5.0.1 and later, update will convert LEGACY_RESTART to the
|
|
equivalent RESTART setting.</para>
|
|
</note>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>CLI Unification</title>
|
|
|
|
<para>Prior to Shorewall 5.1, there were four separate CLI
|
|
programs:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><filename>/sbin/shorewall </filename>or
|
|
<filename>/usr/sbin/shorewall</filename> depending on your
|
|
distribution. Packaged with Shorewall and used to control
|
|
Shorewall.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>/sbin/shorewall6 </filename>or
|
|
<filename>/usr/sbin/shorewall6</filename> depending on your
|
|
distribution. Packaged with Shorewall6 and used to control
|
|
Shorewall6.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>/sbin/shorewall-lite </filename>or
|
|
<filename>/usr/sbin/shorewall-lite</filename> depending on your
|
|
distribution. Packaged with Shorewall-lite and used to control
|
|
Shorewall-lite.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><filename>/sbin/shorewall6-lite </filename>or
|
|
<filename>/usr/sbin/shorewall6-lite</filename> depending on your
|
|
distribution. Packaged with Shorewall6-lite and used to control
|
|
Shorewall6-lite.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Each of these programs had their own (largely duplicated)
|
|
manpage.</para>
|
|
|
|
<para>Beginning with Shorewall 5.1, there is a single CLI program
|
|
(<filename>/sbin/shorewall</filename> or
|
|
<filename>/usr/sbin/shorewall</filename>) packaged with Shorewall-core.
|
|
The Shorewall6, Shorewall-lite and Shorewall6-lite packages create a
|
|
symbolic link to that program; the links are named shorewall6,
|
|
shorewall-lite and shorewall6-lite respectively. These symbolic links are
|
|
for backward compatibility only; all four products can be managed using
|
|
the single CLI program itself. The manpages shorewall6(8),
|
|
shorewall-lite(8) and shorewall6-lite(8) are skeletal and refer the reader
|
|
to shorewall(8).</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Upgrading to Shorewall 5</title>
|
|
|
|
<para>It is strongly recommended that you first upgrade your installation
|
|
to a 4.6 release that supports the <option>-A</option> option to the
|
|
<command>update</command> command; 4.6.13.2 or later is preferred.</para>
|
|
|
|
<para>Once you are on that release, execute the <command>shorewall update
|
|
-A</command> command (and <command>shorewall6 update -A</command> if you
|
|
also have Shorewall6).</para>
|
|
|
|
<para>Finally, add ?FORMAT 2 to each of your macro and action files and be
|
|
sure that the check command does not produce errors -- if it does, you can
|
|
shuffle the columns around to make them work on both Shorewall 4 and
|
|
Shorewall 5.</para>
|
|
|
|
<para>These steps can also be taken after you upgrade, but your firewall
|
|
likely won't start or work correctly until you do.</para>
|
|
|
|
<para>The <command>update</command> command in Shorewall 5 has many fewer
|
|
options. The <option>-b</option>, <option>-t</option>,
|
|
<option>-n</option>, <option>-D</option> and <option>-s </option>options
|
|
have been removed -- the updates triggered by those options are now
|
|
performed unconditionally. The <option>-i </option>and <option>-A
|
|
</option>options have been retained - both enable checking for issues that
|
|
could result if INLINE_MATCHES were to be set to Yes.</para>
|
|
|
|
<section>
|
|
<title id="CHAIN_SCRIPTS">CHAIN_SCRIPTS Removal</title>
|
|
|
|
<para>Prior to the availability of ?[BEGIN] PERL .... ?END PERL, the
|
|
only way to create Perl code to insert rules into a chain was to use a
|
|
per-Chain script with the same name as the chain. The most common use of
|
|
these scripts was with Actions where an action A would have an empty
|
|
action.A file and then a file named A that contained Perl code. This was
|
|
a hack, at best, and has been deprecated since embedded Perl has been
|
|
available in action files.</para>
|
|
|
|
<para>In Shorewall 5.1, the compiler notices that action.A is empty and
|
|
looks for a file named A on the CONFIG_PATH. If that file is found, the
|
|
compiler raises a fatal error:</para>
|
|
|
|
<programlisting> ERROR: File action.A is empty and file A exists - the two must be combined as described in the Migration Considerations section of the Shorewall release notes</programlisting>
|
|
|
|
<para>To resolve this issue, one of two approaches can be taken
|
|
depending on what the script A does.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If script A is simply inserting rules with ip[6]tables matches
|
|
and/or targets that Shorewall doesn't directly support, they can
|
|
probably be coded in the action.A file using the IP[6]TABLES action
|
|
and/or inline matches. For example, the following script
|
|
<filename>DNSDDOS</filename></para>
|
|
|
|
<programlisting>use Shorewall::Chains;
|
|
|
|
add_rule $chainref, q(-m string --algo bm --from 30 --to 31 --hex-string "|010000010000000000000000020001|" -j DROP);
|
|
add_rule $chainref, q(-m string --algo bm --from 30 --to 31 --hex-string "|000000010000000000000000020001|" -j DROP);
|
|
add_rule $chainref, q(-j ACCEPT);
|
|
|
|
1;</programlisting>
|
|
|
|
<para>can be coded in <filename>action.DNSDDOS</filename> as:</para>
|
|
|
|
<programlisting>DROP - - ;; -m string --algo bm --from 30 --to 31 --hex-string "|010000010000000000000000020001|"
|
|
DROP - - ;; -m string --algo bm --from 30 --to 31 --hex-string "|000000010000000000000000020001|"
|
|
ACCEPT - -</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The other approach is to simply convert A into embedded Perl
|
|
in action.A. Consider this <filename>SSHKnock</filename>
|
|
script:</para>
|
|
|
|
<programlisting>use Shorewall::Chains;
|
|
|
|
if ( $level ) {
|
|
log_rule_limit( $level,
|
|
$chainref,
|
|
'SSHKnock',
|
|
'ACCEPT',
|
|
'',
|
|
$tag,
|
|
'add',
|
|
'-p tcp --dport 22 -m recent --rcheck --name SSH ' );
|
|
log_rule_limit( $level,
|
|
$chainref,
|
|
'SSHKnock',
|
|
'DROP',
|
|
'',
|
|
$tag,
|
|
'add',
|
|
'-p tcp --dport ! 22 ' );
|
|
}
|
|
add_rule( $chainref, '-p tcp --dport 22 -m recent --rcheck --seconds 60 --name SSH -j ACCEPT' );
|
|
add_rule( $chainref, '-p tcp --dport 632 -m recent --name SSH --remove -j DROP' );
|
|
add_rule( $chainref, '-p tcp --dport 633 -m recent --name SSH --set -j DROP' );
|
|
add_rule( $chainref, '-p tcp --dport 634 -m recent --name SSH --remove -j DROP' );
|
|
1;</programlisting>
|
|
|
|
<para>Because this script uses the implicit $level and $tag
|
|
variables, it must remain in Perl. This mostly involves simply
|
|
moving the <filename>SSHKnock</filename> script into
|
|
<filename>action.SSHKnock</filename>, but requires some additional
|
|
code in <filename>action.SSHKnock</filename> as shown in <emphasis
|
|
role="bold">bold font</emphasis> below:</para>
|
|
|
|
<programlisting><emphasis role="bold">?begin perl</emphasis>
|
|
|
|
<emphasis role="bold">use Shorewall::Config;</emphasis>
|
|
use Shorewall::Chains;
|
|
|
|
<emphasis role="bold">my $chainref = get_action_chain;
|
|
my ( $level, $tag ) = get_action_logging;</emphasis>
|
|
|
|
if ( $level ) {
|
|
log_rule_limit( $level,
|
|
$chainref,
|
|
'SSHKnock',
|
|
'ACCEPT',
|
|
'',
|
|
$tag,
|
|
'add',
|
|
'-p tcp --dport 22 -m recent --rcheck --name SSH ' );
|
|
|
|
log_rule_limit( $level,
|
|
$chainref,
|
|
'SSHKnock',
|
|
'DROP',
|
|
'',
|
|
$tag,
|
|
'add',
|
|
'-p tcp --dport ! 22 ' );
|
|
}
|
|
|
|
add_rule( $chainref, '-p tcp --dport 22 -m recent --rcheck --seconds 60 --name SSH -j ACCEPT' );
|
|
add_rule( $chainref, '-p tcp --dport 632 -m recent --name SSH --remove -j DROP' );
|
|
add_rule( $chainref, '-p tcp --dport 633 -m recent --name SSH --set -j DROP' );
|
|
add_rule( $chainref, '-p tcp --dport 634 -m recent --name SSH --remove -j DROP' );
|
|
1;
|
|
|
|
<emphasis role="bold">?end perl</emphasis></programlisting>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</article>
|