1
0
mirror of https://gitlab.com/shorewall/code.git synced 2024-12-19 04:41:07 +01:00
shorewall_code/Shorewall-docs2/upgrade_issues.xml

739 lines
29 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- $Id$ -->
<article id="upgrade_issues">
<articleinfo>
<title>Upgrade Issues</title>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<holder>2005 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 type="" url="copyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
</legalnotice>
</articleinfo>
<section>
<title>Important</title>
<para>It is important that you read all of the sections on this page where
the version number mentioned in the section title is later than what you
are currently running.</para>
<para>In the descriptions that follows, the term
<emphasis>group</emphasis> refers to a particular network or subnetwork
(which may be <literal>0.0.0.0/0</literal> or it may be a host address)
accessed through a particular interface.</para>
<para>Examples:</para>
<simplelist columns="1" type="vert">
<member><literal>eth0:0.0.0.0/0</literal></member>
<member><literal>eth2:192.168.1.0/24</literal></member>
<member><literal>eth3:192.0.2.123</literal></member>
</simplelist>
<para>You can use the <command moreinfo="none">shorewall check</command>
command to see the groups associated with each of your zones.</para>
</section>
<section>
<title>Version &gt;= 2.2.0</title>
<para></para>
<orderedlist>
<listitem>
<para>Shorewall configuration files except shorewall.conf are now
empty (they contain only comments). If you wish to retain the defaults
in any of the following files, you should copy these files before
upgrading them then restore them after the upgrade:</para>
<simplelist>
<member>/etc/shorewall/zones</member>
<member>/etc/shorewall/policy</member>
<member>/etc/shorewall/tos</member>
</simplelist>
</listitem>
<listitem>
<para>The following builtin actions have been removed and have been
replaced by the new action logging implementation described in the new
features below.</para>
<simplelist>
<member>logNotSyn</member>
<member>rLogNotSyn</member>
<member>dLogNotSyn</member>
</simplelist>
</listitem>
<listitem>
<para>If shorewall.conf is upgraded to the latest version, it needs to
be modified to set STARTUP_ENABLED=Yes.</para>
</listitem>
<listitem>
<para>The Leaf/Bering version of Shorewall was previously
named:</para>
<simplelist>
<member>shorwall-&lt;version&gt;.lrp</member>
</simplelist>
<para>Beginning with 2.1, that file will now be named:</para>
<simplelist>
<member>shorewall-lrp-&lt;version&gt;.tgz</member>
</simplelist>
<para>Simply rename that file to 'shorwall.lrp' when installing it on
your LEAF/Bering system.</para>
</listitem>
<listitem>
<para>The ORIGINAL DEST column of the /etc/shorewall/rules file may no
longer contain a second (SNAT) address. You must use an entry in
/etc/shorewall/masq instead.</para>
<para>Example from Shorewall FAQ #1:</para>
<blockquote>
<para>Prior to Shorewall 2.1:</para>
<para>/etc/shorewall/interfaces</para>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
loc eth1 detect routeback</programlisting>
<para>/etc/shorewall/rules</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT SOURCE ORIGINAL
# PORT DEST
DNAT loc loc:192.168.1.12 tcp 80 - 130.252.100.69:192.168.1.254 </programlisting>
<para>Shorewall 2.1 and Later:</para>
<para>/etc/shorewall/interfaces</para>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
loc eth1 detect routeback</programlisting>
<para>/etc/shorewall/masq:</para>
<programlisting>#INTERFACE SUBNETS ADDRESS PROTO PORT(S)
eth1 eth1 192.168.1.254 tcp 80</programlisting>
<para>/etc/shorewall/rules:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT SOURCE ORIGINAL
# PORT DEST
DNAT loc loc:192.168.1.12 tcp 80 - 130.252.100.69</programlisting>
</blockquote>
</listitem>
<listitem>
<para>The 'logunclean' and 'dropunclean' options that were deprecated
in Shorewall 2.0 have now been removed completely.</para>
</listitem>
<listitem>
<para>The default port for 'openvpn' tunnels (/etc/shorewall/tunnels)
has been changed to 1194 to match a similar change in the OpenVPN
product. The IANA has registered port 1194 for use by OpenVPN.</para>
</listitem>
<listitem>
<para>A new IPTABLES variable has been added to shorewall.conf. This
variable names the iptables executable that Shorewall will use. The
variable is set to "/sbin/iptables". If you use the new
shorewall.conf, you may need to change this setting to maintain
compatibility with your current setup (if you use your existing
shorewall.conf that does not set IPTABLES then you should experience
no change in behavior).</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Version &gt;= 2.0.2 RC1</title>
<itemizedlist>
<listitem>
<para>If you are upgrading from Shorewall 1.4.x and you have commands
in your <filename>/etc/shorewall/common</filename> file that are not
directly related to the <emphasis role="bold">common</emphasis> chain
then you will want to move those commands to
<filename>/etc/shorewall/initdone</filename>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 2.0.2 Beta 1</title>
<itemizedlist>
<listitem>
<para>Extension Scripts - In order for extension scripts to work
properly with the new iptables-save/restore integration introduced in
Shorewall 2.0.2 Beta 1, some change may be required to your extension
scripts.</para>
<para>If your extension scripts are executing commands other than
<command>iptables</command> then those commands must also be written
to the restore file (a temporary file in <filename
class="directory">/var/lib/shorewall</filename> that is renamed
<filename>/var/lib/shorewall/restore-base</filename> at the completion
of the <filename>/sbin/shorewall</filename> command). The following
functions should be of help:</para>
<orderedlist>
<listitem>
<para>save_command() -- saves the passed command to the restore
file.</para>
<para>Example: <programlisting>save_command echo Operation Complete</programlisting></para>
<para>That command would simply write "echo Operation Complete" to
the restore file.</para>
</listitem>
<listitem>
<para>run_and_save_command() -- saves the passed command to the
restore file then executes it. The return value is the exit status
of the command. Example: <programlisting>run_and_save_command "echo 1 &gt; /proc/sys/net/ipv4/icmp_echo_ignore_all"</programlisting></para>
<para>Note that as in this example, when the command involves file
redirection then the entire command must be enclosed in quotes.
This applies to all of the functions described here.</para>
</listitem>
<listitem>
<para>ensure_and_save_command() -- runs the passed command. If the
command fails, the firewall is restored to it's prior saved state
and the operation is terminated. If the command succeeds, the
command is written to the restore file</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Dynamic Zone support. - If you don't need to use the
<command>shorewall add</command> and <command>shorewall
delete</command> commands, you should set DYNAMIC_ZONES=No in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 2.0.1</title>
<itemizedlist>
<listitem>
<para>The function of 'norfc1918' is now split between that option and
a new 'nobogons' option. The rfc1918 file released with Shorewall now
contains entries for only those three address ranges reserved by RFC
1918. A 'nobogons' interface option has been added which handles bogon
source addresses (those which are reserved by the IANA, those reserved
for DHCP auto-configuration and the class C test-net reserved for
testing and documentation examples). This will allow users to perform
RFC 1918 filtering without having to deal with out of date data from
IANA. Those who are willing to update their
<filename>/usr/share/shorewall/bogons</filename> file regularly can
specify the 'nobogons' option in addition to 'norfc1918'. The level at
which bogon packets are logged is specified in the new BOGON_LOG_LEVEL
variable in shorewall.conf. If that option is not specified or is
specified as empty (e.g, BOGON_LOG_LEVEL="") then bogon packets whose
TARGET is 'logdrop' in
<filename>/usr/share/shorewall/bogons</filename> are logged at the
'info' level.</para>
<warning>
<para>If you have a file named <filename>rfc1918</filename> in your
<filename class="directory">/etc/shorewall</filename> directory, you
must either remove that file or you must copy
<filename>/usr/share/shorewall/rfc1918</filename> to <filename
class="directory">/etc/shorewall</filename> and modify that file
appropriately. Do not leave the old <filename>rfc1918</filename>
file in <filename
class="directory">/etc/shorewall</filename>.</para>
</warning>
</listitem>
</itemizedlist>
</section>
<section>
<title>VERSION &gt;= 2.0.0-Beta1</title>
<itemizedlist>
<listitem>
<para>The 'dropunclean' and 'logunclean' interface options are no
longer supported. If either option is specified in
<filename>/etc/shorewall/interfaces</filename>, a threatening message
will be generated.</para>
</listitem>
<listitem>
<para>The NAT_BEFORE_RULES option has been removed from
<filename>shorewall.conf</filename>. The behavior of Shorewall 2.0 is
as if NAT_BEFORE_RULES=No had been specified. In other words, DNAT
rules now always take precedence over one-to-one NAT
specifications.</para>
</listitem>
<listitem>
<para>The default value for the ALL INTERFACES column in
<filename>/etc/shorewall/nat</filename> has changed. In Shorewall 1.*,
if the column was left empty, a value of "Yes" was assumed. This has
been changed so that a value of "No" is now assumed.</para>
</listitem>
<listitem>
<para>The following files don't exist in Shorewall 2.0:</para>
<simplelist>
<member><filename>/etc/shorewall/common.def</filename></member>
<member><filename>/etc/shorewall/common</filename></member>
<member><filename>/etc/shorewall/icmpdef</filename></member>
<member><filename>/etc/shorewall/action.template</filename> (moved
to
<filename>/usr/share/shorewall/action.template</filename>)</member>
</simplelist>
<para>The <filename>/etc/shorewall/action</filename> file now allows
an action to be designated as the "common" action for a particular
policy type by following the action name with ":" and the policy
(DROP, REJECT or ACCEPT).</para>
<para>The file /usr/share/shorewall/actions.std has been added to
define those actions that are released as part of Shorewall 2.0 In
that file are two actions as follows:</para>
<simplelist>
<member>Drop:DROP</member>
<member>Reject:REJECT</member>
</simplelist>
<para>The <quote>Drop</quote> action is the common action for DROP
policies while the <quote>Reject</quote> action is the default action
for REJECT policies. These actions will be performed on packets prior
to applying the DROP or REJECT policy respectively. In the first
release, the difference between "Reject" and "Drop" is that "Reject"
REJECTs SMB traffic while "Drop" silently drops such traffic.</para>
<para>As described above, Shorewall allows a common action for ACCEPT
policies but does not specify such an action in the default
configuration.</para>
<para>For more information see the <ulink
url="Actions.html">User-defined Action Page</ulink>.</para>
</listitem>
<listitem>
<para>The <filename>/etc/shorewall</filename> directory no longer
contains <filename>users</filename> file or a
<filename>usersets</filename> file. Similar functionality is now
available using user-defined actions.</para>
<para>Now, action files created by copying
<filename>/usr/share/shorewall/action.template</filename> may now
specify a USER and or GROUP name/id in the final column just like in
the rules file (see below). It is thus possible to create actions that
control traffic from a list of users and/or groups.</para>
</listitem>
<listitem>
<para>The last column in <filename>/etc/shorewall/rules</filename> is
now labeled USER/GROUP and may contain:</para>
<simplelist>
<member>[!]&lt;<emphasis>user number</emphasis>&gt;[:]</member>
<member>[!]&lt;<emphasis>user name</emphasis>&gt;[:]</member>
<member>[!]:&lt;<emphasis>group number</emphasis>&gt;</member>
<member>[!]:&lt;<emphasis>group name</emphasis>&gt;</member>
<member>[!]&lt;<emphasis>user
number</emphasis>&gt;:&lt;<emphasis>group
number</emphasis>&gt;</member>
<member>[!]&lt;<emphasis>user
name</emphasis>&gt;:&lt;<emphasis>group
number</emphasis>&gt;</member>
<member>[!]&lt;<emphasis>user
inumber</emphasis>&gt;:&lt;<emphasis>group
name</emphasis>&gt;</member>
<member>[!]&lt;<emphasis>user
name</emphasis>&gt;:&lt;<emphasis>group name</emphasis>&gt;</member>
</simplelist>
</listitem>
<listitem>
<para>If your kernel has IPV6 support (recent
<trademark>SuSe</trademark> for example), and you don't use IPV6 then
you will probably want to set DISABLE_IPV6=Yes in <ulink
url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>.
You must have ipv6tables installed.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 1.4.9</title>
<itemizedlist>
<listitem>
<para>The default value of NEWNOTSYN set in <ulink
url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink> has
been changed from 'No' to 'Yes'. I find that NEWNOTSYN=No tends to
result in lots of "stuck" connections because any network timeout
during TCP session tear down results in retries being dropped
(Netfilter has removed the connection from the conntrack table but the
end-points haven't completed shutting down the connection). I
therefore have chosen NEWNOTSYN=Yes as the default value and I advise
caution in using NEWNOTSYN=Yes.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 1.4.8</title>
<itemizedlist mark="bullet">
<listitem>
<para>The meaning of <varname>ROUTE_FILTER=Yes</varname> has changed.
Previously this setting was documented as causing route filtering to
occur on all network interfaces; this didn't work. Beginning with this
release, <varname>ROUTE_FILTER=Yes</varname> causes route filtering to
occur on all interfaces brought up while Shorewall is running. This
means that it may be appropriate to set
<varname>ROUTE_FILTER=Yes</varname> and use the routefilter option in
<filename
class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
entries.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 1.4.6</title>
<itemizedlist mark="bullet">
<listitem>
<para>The <varname>NAT_ENABLED</varname>,
<varname>MANGLE_ENABLED</varname> and <varname>MULTIPORT</varname>
options have been removed from <filename>shorewall.conf</filename>.
These capabilities are now automatically detected by Shorewall.</para>
</listitem>
<listitem>
<para>An undocumented feature previously allowed entries in the host
file as follows: <synopsis>
zone eth1:192.168.1.0/24,eth2:192.168.2.0/24
</synopsis> This capability was never documented and has been removed in
1.4.6 to allow entries of the following format: <synopsis>
zone eth1:192.168.1.0/24,192.168.2.0/24
</synopsis></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 1.4.4</title>
<para>If you are upgrading from 1.4.3 and have set the
<varname>LOGMARKER</varname> variable in <filename
class="directory">/etc/shorewall/</filename><filename>shorewall.conf</filename>,
then you must set the new <varname>LOGFORMAT</varname> variable
appropriately and remove your setting of
<varname>LOGMARKER</varname>.</para>
</section>
<section>
<title>Version 1.4.4</title>
<para>If you have zone names that are 5 characters long, you may
experience problems starting Shorewall because the
<option>--log-prefix</option> in a logging rule is too long. Upgrade to
Version 1.4.4a to fix this problem.</para>
</section>
<section>
<title>Version &gt;= 1.4.2</title>
<para>There are some cases where you may want to handle traffic from a
particular group to itself. While I personally think that such a setups
are ridiculous, there are two cases covered in this documentation where it
can occur: <itemizedlist>
<listitem>
<para><ulink url="FAQ.htm#faq2">In FAQ #2</ulink></para>
</listitem>
<listitem>
<para><ulink url="Shorewall_Squid_Usage.html">When running
<application>Squid</application> as a transparent proxy in your
local zone.</ulink></para>
</listitem>
</itemizedlist> If you have either of these cases, you will want to
review the current documentation and change your configuration
accordingly.</para>
</section>
<section>
<title>Version &gt;= 1.4.1</title>
<itemizedlist mark="bullet">
<listitem>
<para>Beginning with Version 1.4.1, traffic between groups in the same
zone is accepted by default. Previously, traffic from a zone to itself
was treated just like any other traffic; any matching rules were
applied followed by enforcement of the appropriate policy. With 1.4.1
and later versions, unless you have explicit rules for traffic from Z
to Z or you have an explicit Z to Z policy (where "Z" is some zone)
then traffic between the groups in zone Z will be accepted. If you do
have one or more explicit rules for Z to Z or if you have an explicit
Z to Z policy then the behavior is as it was in prior versions.</para>
<orderedlist numeration="arabic">
<listitem>
<para>If you have a Z Z ACCEPT policy for a zone to allow traffic
between two interfaces to the same zone, that policy can be
removed and traffic between the interfaces will traverse fewer
rules than previously.</para>
</listitem>
<listitem>
<para>If you have a Z Z DROP or Z Z REJECT policy or you have
Z-&gt;Z rules then your configuration should not require any
change.</para>
</listitem>
<listitem>
<para>If you are currently relying on a implicit policy (one that
has "all" in either the SOURCE or DESTINATION column) to prevent
traffic between two interfaces to a zone Z and you have no rules
for Z-&gt;Z then you should add an explicit DROP or REJECT policy
for Z to Z.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Sometimes, you want two separate zones on one interface but you
don't want Shorewall to set up any infrastructure to handle traffic
between them. <example>
<title>The <filename>zones</filename>,
<filename>interfaces</filename> and, <filename>hosts</filename>
file contents</title>
<programlisting>
<filename class="directory">/etc/shorewall/</filename><filename>zones</filename>
z1 Zone1 The first Zone
z2 Zone2 The second Zone
<filename class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
z2 eth1 192.168.1.255
<filename class="directory">/etc/shorewall/</filename><filename>hosts</filename>
z1 eth1:192.168.1.3
</programlisting>
</example> Here, zone z1 is nested in zone z2 and the firewall is
not going to be involved in any traffic between these two zones.
Beginning with Shorewall 1.4.1, you can prevent Shorewall from setting
up any infrastructure to handle traffic between z1 and z2 by using the
new NONE policy: <example>
<title>The contents of <filename>policy</filename></title>
<programlisting>
<filename class="directory">/etc/shorewall/</filename><filename>policy</filename>
z1 z2 NONE
z2 z1 NONE
</programlisting>
</example> Note that NONE policies are generally used in pairs
unless there is asymmetric routing where only the traffic on one
direction flows through the firewall and you are using a NONE policy
in the other direction.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version 1.4.1</title>
<itemizedlist mark="bullet">
<listitem>
<para>In Version 1.4.1, Shorewall will never create rules to deal with
traffic from a given group back to itself. The
<varname>multi</varname> interface option is no longer available so if
you want to route traffic between two subnetworks on the same
interface then I recommend that you upgrade to Version 1.4.2 and use
the <varname>routeback</varname> interface or host option.</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Version &gt;= 1.4.0</title>
<important>
<para>Shorewall &gt;=1.4.0 requires the <command>iproute</command>
package ('<literal>ip</literal>' utility).</para>
</important>
<note>
<para>Unfortunately, some distributions call this package
<command>iproute2</command> which will cause the upgrade of Shorewall to
fail with the diagnostic: <synopsis>
error: failed dependencies:iproute is needed by shorewall-1.4.0-1
</synopsis> This may be worked around by using the
<option>--nodeps</option> option of <command>rpm</command> (<command>rpm
-Uvh --nodeps
<filename>your_shorewall_rpm.rpm</filename></command>).</para>
</note>
<para>If you are upgrading from a version &lt; 1.4.0, then: <itemizedlist
mark="bullet">
<listitem>
<para>The <varname>noping</varname> and
<varname>forwardping</varname> interface options are no longer
supported nor is the <varname>FORWARDPING</varname> option in
<filename>shorewall.conf</filename>. ICMP echo-request (ping)
packets are treated just like any other connection request and are
subject to rules and policies.</para>
</listitem>
<listitem>
<para>Interface names of the form
<varname>&lt;device&gt;:&lt;integer&gt;</varname> in <filename
class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
now generate a Shorewall error at startup (they always have produced
warnings in <application
class="software">iptables</application>).</para>
</listitem>
<listitem>
<para>The <varname>MERGE_HOSTS</varname> variable has been removed
from <filename>shorewall.conf</filename>. Shorewall 1.4 behaves like
1.3 did when <varname>MERGE_HOSTS=Yes</varname>; that is zone
contents are determined by <emphasis>BOTH</emphasis> the interfaces
and hosts files when there are entries for the zone in both
files.</para>
</listitem>
<listitem>
<para>The <varname>routestopped</varname> option in the interfaces
and hosts file has been eliminated; use entries in the
<filename>routestopped</filename> file instead.</para>
</listitem>
<listitem>
<para>The Shorewall 1.2 syntax for <varname>DNAT</varname> and
<varname>REDIRECT</varname> rules is no longer accepted; you must
convert to using the new syntax.</para>
</listitem>
<listitem>
<para>The <varname>ALLOWRELATED</varname> variable in
<filename>shorewall.conf</filename> is no longer supported.
Shorewall 1.4 behavior is the same as 1.3 with
<varname>ALLOWRELATED=Yes</varname>.</para>
</listitem>
<listitem>
<para>Late-arriving DNS replies are now dropped by default; there is
no need for your own <filename
class="directory">/etc/shorewall/</filename><filename>common</filename>
file simply to avoid logging these packets.</para>
</listitem>
<listitem>
<para>The <filename>firewall</filename>,
<filename>functions</filename> and <filename>version</filename>
files have been moved to <filename
class="directory">/usr/share/shorewall</filename>.</para>
</listitem>
<listitem>
<para>The <filename>icmp.def</filename> file has been removed. If
you include it from <filename
class="directory">/etc/shorewall/</filename><filename>icmpdef</filename>,
you will need to modify that file.</para>
</listitem>
<listitem>
<para>If you followed the advice in FAQ #2 and call
<varname>find_interface_address</varname> in <filename
class="directory">/etc/shorewall/</filename><filename>params</filename>,
that code should be moved to <filename
class="directory">/etc/shorewall/</filename><filename>init</filename>.</para>
</listitem>
</itemizedlist></para>
</section>
<section>
<title>Version 1.4.0</title>
<itemizedlist mark="bullet">
<listitem>
<para>The <varname>multi</varname> interface option is no longer
supported. Shorewall will generate rules for sending packets back out
the same interface that they arrived on in two cases: <itemizedlist
mark="hollow">
<listitem>
<para>There is an <emphasis>explicit</emphasis> policy for the
source zone to or from the destination zone. An explicit policy
names both zones and does not use the <varname>all</varname>
reserved word.</para>
</listitem>
<listitem>
<para>There are one or more rules for traffic for the source
zone to or from the destination zone including rules that use
the <varname>all</varname> reserved word. Exception: if the
source zone and destination zone are the same then the rule must
be explicit - it must name the zone in both the
<varname>SOURCE</varname> and <varname>DESTINATION</varname>
columns.</para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist>
</section>
</article>