extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-11-25 00:53:49 +01:00
Code Issues Packages Projects Releases Wiki Activity
386dff4c33
shorewall_code/docs/Shorewall-5.xml
Tom Eastep b997bfcd97
Update copyright of Shorewall 5 Document 
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2018-04-10 10:44:38 -07:00

623 lines
21 KiB
XML
Raw Blame History

<?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>
<year>2018</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>
<listitem>
<para>MODULE_SUFFIX (Removed in Shorewall 5.1.7). Shorewall can now
locate modules independent of their suffix (extension).</para>
</listitem>
<listitem>
<para>INLINE_MATCHES (Removed in Shorewall 5.2). Inline matches are
now separated from column-oriented input by two adjacent semicolons
(";;").</para>
</listitem>
<listitem>
<para>MAPOLDACTIONS (Removed in Shorewall 5.2). </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', 'tos' and 'masq' files.</para>
<para>The <command>update</command> command is available to convert the
'tcrules' and 'tos' files to the equivalent 'mangle' file, to convert
the 'blacklist' file into an equivalent 'blrules' file, and to convert
the 'masq' file to the equivalent 'snat' file.</para>
<para>As in Shorewall 4.6.12, the <command>update</command> command
converts the 'routestopped' file into the equivalent 'stoppedrules' file
and converts a 'notrack' file to the equivalent 'conntrack' file.</para>
<para>Note that in Shorewall 5.2, the update command </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>
<title>refresh</title>
<para>Given the availability of ipset-based blacklisting, the
<command>refresh</command> command was eliminated in Shorewall
5.2.</para>
<para>Some users may have been using <command>refresh</command> as a
lightweight form of <command>reload</command>. The most common of these
uses seem to be for reloading traffic shaping after an interface has
gone down and come back up. The best way to handle this situation under
5.2 is to make the interface 'optional' in your
/etc/shorewall[6]/interfaces file, then either:</para>
<itemizedlist>
<listitem>
<para>Install Shorewall-init and enable IFUPDOWN; or</para>
</listitem>
<listitem>
<para>Use the <command>reenable</command> command when the interface
comes back up in place of the <command>refresh</command>
command.</para>
</listitem>
</itemizedlist>
</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><important>
<para>For detailed upgrade information, please consult the 'Migration
Issues' section of the release notes for the version that you are
upgrading to.</para>
</important>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. The -i option was
removed in Shorewall 5.2, given that the INLINE_MATCHES option was also
removed.</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>
Reference in New Issue View Git Blame Copy Permalink