forked from extern/shorewall_code
Add Shorewall-5 Article
Signed-off-by: Tom Eastep <teastep@shorewall.net>
This commit is contained in:
Tom Eastep
parent
2451c14d8c
commit
463206a3eb
409
docs/Shorewall-5.xml
Normal file
409
docs/Shorewall-5.xml
Normal file
@ -0,0 +1,409 @@
|
|||||||
|
<?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>
|
||||||
|
|
||||||
|
<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 two 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>
|
||||||
|
</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>
|
||||||
|
</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>
|
||||||
|
</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 for 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' file 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>
|
||||||
|
|
||||||
|
<para> No update option is available to update the 'tos' file. Its
|
||||||
|
entries must be manually converted to TOS rules in the 'mangle'
|
||||||
|
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>DEST PORT(S)</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>SOURCE PORT(S)</para>
|
||||||
|
</listitem>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>ORIGINAL DEST</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.</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 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
|
||||||
|
LEGACY_RESTART option has been added to shorewall[6].conf. The option
|
||||||
|
defaults to No but if set to Yes, then the <command>restart</command>
|
||||||
|
command does what it did in earlier releases.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Upgrading to Shorewall 5</title>
|
||||||
|
|
||||||
|
<para>It is stongly 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.12 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>If you have a non-empty 'tos' file, it is also suggested that you
|
||||||
|
manually convert its entries to equivalent TOS entries in the 'mangle'
|
||||||
|
file.</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>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Potential Upgrade Issues</title>
|
||||||
|
|
||||||
|
<para>There are several potential problems with using the <command>update
|
||||||
|
-A</command> command. These are described in the following
|
||||||
|
sections.</para>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Sparse /etc/shorewall[6] Directory</title>
|
||||||
|
|
||||||
|
<para>If you run a Debian-based distribution or another once that does
|
||||||
|
not fully populate /etc/shorewall[6] and you include a fully-populated
|
||||||
|
directory in your CONFIG_PATH, then an additional step is required
|
||||||
|
before running<command> update -A</command>. You must copy skeleton
|
||||||
|
'blrules', 'mangle' and 'conntrack' files into /etc/shorewall[6] or
|
||||||
|
<command>update -A</command> will update the files in the fully
|
||||||
|
populated directory rather than creating new files in
|
||||||
|
/etc/shorewall[6].</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>Old Multi-ISP Configurations</title>
|
||||||
|
|
||||||
|
<para>If you have an old Multi-ISP configuration that does not include
|
||||||
|
USE_DEFAULT_RT in shorewall.conf, then you need to add USE_DEFAULT_RT=No
|
||||||
|
in that file prior to running <command>update -A</command>. Otherwise,
|
||||||
|
the <command>update</command> command will fail with the error:</para>
|
||||||
|
|
||||||
|
<simplelist>
|
||||||
|
<member>ERROR: The COPY column must be empty when
|
||||||
|
USE_DEFAULT_RT=Yes</member>
|
||||||
|
</simplelist>
|
||||||
|
|
||||||
|
<para>If you receive this error, modify the setting of USE_DEFAULT_RT to
|
||||||
|
No and rerun the command.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
</article>
|
||||||
Loading…
Reference in New Issue
Block a user