forked from extern/shorewall_code
490 lines
18 KiB
XML
490 lines
18 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="Install">
|
|
<!--$Id$-->
|
|
|
|
<articleinfo>
|
|
<title>Shorewall Installation and Upgrade</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2001-</year>
|
|
|
|
<year>2006</year>
|
|
|
|
<year>2009</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>
|
|
|
|
<caution>
|
|
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
|
|
later. If you are installing or upgrading to a version of Shorewall
|
|
earlier than Shorewall 4.3.5 then please see the documentation for that
|
|
release.</emphasis></para>
|
|
</caution>
|
|
|
|
<important>
|
|
<para>Before attempting installation, I strongly urge you to read and
|
|
print a copy of the <ulink url="shorewall_quickstart_guide.htm">Shorewall
|
|
QuickStart</ulink> Guide for the configuration that most closely matches
|
|
your own. This article only tells you how to install the product on your
|
|
system. The QuickStart Guides describe how to configure the
|
|
product.</para>
|
|
</important>
|
|
|
|
<important>
|
|
<para>Before upgrading, be sure to review the <ulink
|
|
url="upgrade_issues.htm">Upgrade Issues</ulink>.</para>
|
|
</important>
|
|
|
|
<note>
|
|
<para>Shorewall RPMs are signed. To avoid warnings such as the
|
|
following<programlisting>warning: shorewall-3.2.1-1.noarch.rpm: V3 DSA signature: NOKEY, key ID 6c562ac4</programlisting></para>
|
|
|
|
<para>download the <ulink
|
|
url="https://lists.shorewall.net/shorewall.gpg.key">Shorewall GPG
|
|
key</ulink> and run this command:</para>
|
|
|
|
<programlisting><command>rpm --import shorewall.gpg.key</command></programlisting>
|
|
</note>
|
|
|
|
<section id="Install_RPM">
|
|
<title>Install using RPM</title>
|
|
|
|
<para>To install Shorewall using the RPM:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Be sure that you have the correct RPM
|
|
package!</emphasis></para>
|
|
|
|
<para>The standard RPM package from shorewall.net and the mirrors is
|
|
known to work with <emphasis
|
|
role="bold"><trademark>SUSE</trademark></emphasis>, <emphasis
|
|
role="bold"><trademark>Power PPC</trademark></emphasis>, <emphasis
|
|
role="bold"><trademark>Trustix</trademark></emphasis> and <emphasis
|
|
role="bold"><trademark>TurboLinux</trademark></emphasis>. There is
|
|
also an RPM package provided by Simon Matter that is tailored for
|
|
<trademark><emphasis role="bold">RedHat/Fedora</emphasis></trademark>
|
|
and another package from Jack Coates that is customized for <emphasis
|
|
role="bold"><trademark>Mandriva</trademark></emphasis>. All of these
|
|
are available from the <ulink
|
|
url="http://www.shorewall.net/download.htm">download
|
|
page</ulink>.</para>
|
|
|
|
<para>If you try to install the wrong package, it probably won't
|
|
work.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Install the RPMs</para>
|
|
|
|
<programlisting><command>rpm -ivh <shorewall rpm></command></programlisting>
|
|
|
|
<caution>
|
|
<para>Some users are in the habit of using the <command>rpm
|
|
-U</command> command for installing packages as well as for updating
|
|
them. If you use that command when installing the Shorewall RPM then
|
|
you will have to manually enable Shorewall startup at boot time by
|
|
running <command>chkconfig</command>, <command>insserv</command> or
|
|
whatever utility you use to manipulate you init symbolic
|
|
links.</para>
|
|
</caution>
|
|
|
|
<note>
|
|
<para>Shorewall is dependent on the iproute package. Unfortunately,
|
|
some distributions call this package iproute2 which will cause the
|
|
installation of Shorewall to fail with the diagnostic:</para>
|
|
|
|
<programlisting>error: failed dependencies:iproute is needed by shorewall-3.2.x-1</programlisting>
|
|
|
|
<para>This problem should not occur if you are using the correct RPM
|
|
package (see 1., above) but may be worked around by using the
|
|
--nodeps option of rpm.</para>
|
|
|
|
<programlisting><command>rpm -ivh --nodeps <rpms></command></programlisting>
|
|
</note>
|
|
|
|
<para>Example:<programlisting><command>rpm -ivh shorewall-4.3.5-0base.noarch.rpm</command></programlisting></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="Install_Tarball">
|
|
<title>Install using tarball</title>
|
|
|
|
<para>To install Shorewall using the tarball and install script:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>cd to the shorewall directory (the version is encoded in the
|
|
directory name as in <quote>shorewall-4.3.5</quote>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Type:</para>
|
|
|
|
<programlisting><command>./install.sh </command></programlisting>
|
|
|
|
<para>or if you are installing Shorewall or Shorewall6 version 4.4.8
|
|
or later, you may type:</para>
|
|
|
|
<programlisting><command>./install.sh -s</command></programlisting>
|
|
|
|
<para>The <emphasis role="bold">-s</emphasis> option supresses
|
|
installation of all files in <filename
|
|
class="directory">/etc/shorewall</filename> except
|
|
<filename>shorewall.conf</filename>. You can copy any other files you
|
|
need from one of the <ulink url="GettingStarted.html">Samples</ulink>
|
|
or from <filename
|
|
class="directory">/usr/share/shorewall/configfiles/</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the install script was unable to configure Shorewall to be
|
|
started automatically at boot, see <ulink
|
|
url="starting_and_stopping_shorewall.htm">these
|
|
instructions</ulink>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Beginning with shorewall 4.4.20.1, the installer also supports a
|
|
<option>-a</option> (annotated) option. Beginning with that release, the
|
|
standard configuration files (including samples) may be annotated with the
|
|
contents of the associated manpage. The <option>-a</option> option enables
|
|
that behavior. The default remains that the configuration files do not
|
|
include documentation.</para>
|
|
|
|
<section>
|
|
<title>Executables in /usr and Perl Modules</title>
|
|
|
|
<para>Distributions have different philosophies about the proper file
|
|
hierarchy. Two issures are particularly contentious:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Executable files in
|
|
<filename>/usr/share/shorewall*</filename>. These include;</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>getparams</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>compiler.pl</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>wait4ifup</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>shorecap</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>ifupdown</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Perl Modules in
|
|
<filename>/usr/share/shorewall/Shorewall</filename>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>To allow distributions to designate alternate locations for these
|
|
files, the installers (install.sh) from 4.4.19 onward support the
|
|
following environmental variables:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>LIBEXEC</term>
|
|
|
|
<listitem>
|
|
<para>Determines where in /usr getparams, compiler.pl, wait4ifup,
|
|
shorecap and ifupdown are installed. Shorewall and Shorewall6 must
|
|
be installed with the same value of LIBEXEC. The listed
|
|
executables are installed in
|
|
<filename>/usr/${LIBEXEC}/shorewall*</filename>. The default value
|
|
of LIBEXEC is 'share'. LIBEXEC is recognized by all installers and
|
|
uninstallers.</para>
|
|
|
|
<para>Beginning with Shorewall 4.4.20, you can specify an absolute
|
|
path name for LIBEXEC, in which case the listed executables will
|
|
be installed in ${LIBEXEC}/shorewall*.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>PERLLIB</term>
|
|
|
|
<listitem>
|
|
<para>Determines where in <filename>/usr </filename>the Shorewall
|
|
Perl modules are installed. Shorewall and Shorewall6 must be
|
|
installed with the same value of PERLLIB. The modules are
|
|
installed in <filename>/usr/${PERLLIB}/Shorewall</filename>. The
|
|
default value of PERLLIB is 'share/shorewall'. PERLLIB is only
|
|
recognized by the Shorewall and Shorewall6 installers.</para>
|
|
|
|
<para>Beginning with Shorewall 4.4.20, you can specify an absolute
|
|
path name for PERLLIB, in which case the Shorewall Perl modules
|
|
will be installed in ${PERLLIB}/Shorewall/.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Debian">
|
|
<title>Install the .deb</title>
|
|
|
|
<important>
|
|
<para>Once you have installed the .deb packages and before you attempt
|
|
to configure Shorewall, please heed the advice of Lorenzo Martignoni,
|
|
former Shorewall Debian Maintainer:</para>
|
|
|
|
<para><quote>For more information about Shorewall usage on Debian system
|
|
please look at /usr/share/doc/shorewall-common/README.Debian provided by
|
|
[the] shorewall Debian package.</quote></para>
|
|
</important>
|
|
|
|
<para>The easiest way to install Shorewall on Debian, is to use
|
|
apt-get<command>.</command></para>
|
|
|
|
<para>First, to ensure that you are installing the latest version of
|
|
Shorewall, please modify your
|
|
<filename>/etc/apt/preferences:</filename></para>
|
|
|
|
<para><programlisting>Package: shorewall
|
|
Pin: release o=Debian,a=testing
|
|
Pin-Priority: 700
|
|
|
|
Package: shorewall-doc
|
|
Pin: release o=Debian,a=testing
|
|
Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
|
|
run:</emphasis></emphasis><programlisting># apt-get update
|
|
# apt-get install shorewall</programlisting></para>
|
|
|
|
<para><emphasis><emphasis role="bold">Once you have completed configuring
|
|
Shorewall, you can enable startup at boot time by setting startup=1 in
|
|
<filename>/etc/default/shorewall</filename>.</emphasis></emphasis></para>
|
|
</section>
|
|
|
|
<section id="Upgrade">
|
|
<title>General Notes about Upgrading Shorewall</title>
|
|
|
|
<para>Most problems associated with upgrades come from two causes:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The user didn't read and follow the migration considerations in
|
|
the release notes (these are also reproduced in the <ulink
|
|
url="upgrade_issues.htm">Shorewall Upgrade Issues</ulink>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The user mis-handled the
|
|
<filename>/etc/shorewall/shorewall.conf</filename> file during
|
|
upgrade. Shorewall is designed to allow the default behavior of the
|
|
product to evolve over time. To make this possible, the design assumes
|
|
that <emphasis role="bold">you will not replace your current
|
|
shorewall.conf</emphasis> <emphasis role="bold">file during
|
|
upgrades</emphasis>. It is recommended that after you first install
|
|
Shorewall that you modify
|
|
<filename>/etc/shorewall/shorewall.conf</filename> so as to prevent
|
|
your package manager from overwriting it during subsequent upgrades
|
|
(since the addition of STARTUP_ENABLED, such modification is assured
|
|
since you must manually change the setting of that option). If you
|
|
feel absolutely compelled to have the latest options in your
|
|
shorewall.conf then you must proceed carefully. You should determine
|
|
which new options have been added and you must reset their value (e.g.
|
|
OPTION=""); otherwise, you will get different behavior from what you
|
|
expect.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="Upgrade_RPM">
|
|
<title>Upgrade using RPM</title>
|
|
|
|
<para>If you already have the Shorewall RPM installed and are upgrading to
|
|
a new version:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Be sure that you have the correct RPM
|
|
package!</emphasis></para>
|
|
|
|
<para>The standard RPM package from shorewall.net and the mirrors is
|
|
known to work with <trademark>SUSE</trademark>, Power PPC, Trustix and
|
|
TurboLinux. There is also an RPM package provided by Simon Matter that
|
|
is tailored for RedHat/Fedora and another package from Jack Coates
|
|
that is customized for Mandriva. If you try to upgrade using the wrong
|
|
package, it probably won't work.<important>
|
|
<para>Simon Matter names his '<emphasis>common</emphasis>' rpm
|
|
'<emphasis>shorewall</emphasis>' rather than
|
|
'<emphasis>shorewall-common</emphasis>'.</para>
|
|
</important></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are upgrading from a 2.x or 3.x version to a 4.x version
|
|
or later, please see the <ulink url="upgrade_issues.htm">upgrade
|
|
issues</ulink> for specific instructions.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Upgrade the RPM</para>
|
|
|
|
<programlisting><command>rpm -Uvh <shorewall rpm file> </command></programlisting>
|
|
|
|
<note>
|
|
<para>Shorewall is dependent on the iproute package. Unfortunately,
|
|
some distributions call this package iproute2 which will cause the
|
|
upgrade of Shorewall to fail with the diagnostic:</para>
|
|
|
|
<programlisting>error: failed dependencies:iproute is needed by shorewall-3.2.1-1</programlisting>
|
|
|
|
<para>This may be worked around by using the --nodeps option of
|
|
rpm.</para>
|
|
|
|
<programlisting><command>rpm -Uvh --nodeps <shorewall rpm> ...</command></programlisting>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>See if there are any incompatibilities between your
|
|
configuration and the new Shorewall version and correct as
|
|
necessary.</para>
|
|
|
|
<programlisting><command>shorewall check</command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Restart the firewall.</para>
|
|
|
|
<programlisting><command>shorewall restart</command></programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="Upgrade_Tarball">
|
|
<title>Upgrade using tarball</title>
|
|
|
|
<para><important>
|
|
<para>If you are upgrading from a 2.x or 3.x version to a 4.x version
|
|
or later, please see the <ulink url="upgrade_issues.htm">upgrade
|
|
issues</ulink> for specific instructions.</para>
|
|
</important></para>
|
|
|
|
<para>If you already have Shorewall installed and are upgrading to a new
|
|
version using the tarball:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>unpack the tarball:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>cd to the shorewall-perl directory (the version is encoded in
|
|
the directory name as in <quote>shorewall-4.3.5</quote>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Type:</para>
|
|
|
|
<programlisting><command>./install.sh</command></programlisting>
|
|
|
|
<para>or if you are installing Shorewall or Shorewall6 version 4.4.8
|
|
or later, you may type:</para>
|
|
|
|
<programlisting><command>./install.sh -s</command></programlisting>
|
|
|
|
<para>The <emphasis role="bold">-s</emphasis> option supresses
|
|
installation of all files in <filename
|
|
class="directory">/etc/shorewall</filename> except
|
|
<filename>shorewall.conf</filename>. You can copy any other files you
|
|
need from one of the <ulink url="GettingStarted.html">Samples</ulink>
|
|
or from <filename
|
|
class="directory">/usr/share/shorewall/configfiles/</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>See if there are any incompatibilities between your
|
|
configuration and the new Shorewall version and correct as
|
|
necessary.</para>
|
|
|
|
<programlisting><command>shorewall check</command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Start the firewall by typing</para>
|
|
|
|
<programlisting><command>shorewall start</command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the install script was unable to configure Shorewall to be
|
|
started automatically at boot, see <ulink
|
|
url="starting_and_stopping_shorewall.htm">these
|
|
instructions</ulink>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="Upgrade_Deb">
|
|
<title>Upgrading the .deb</title>
|
|
|
|
<warning>
|
|
<para>When the installer asks if you want to replace
|
|
/etc/shorewall/shorewall.conf with the new version, we strongly advise
|
|
you to say No. See <link linkend="Upgrade">above</link>.</para>
|
|
</warning>
|
|
</section>
|
|
|
|
<section id="Config_Files">
|
|
<title>Configuring Shorewall</title>
|
|
|
|
<para>You will need to edit some or all of the configuration files to
|
|
match your setup. In most cases, the <ulink
|
|
url="shorewall_quickstart_guide.htm">Shorewall QuickStart Guides</ulink>
|
|
contain all of the information you need.</para>
|
|
</section>
|
|
|
|
<section id="Uninstall">
|
|
<title>Uninstall/Fallback</title>
|
|
|
|
<para>See <quote><ulink url="fallback.htm">Fallback and
|
|
Uninstall</ulink></quote>.</para>
|
|
</section>
|
|
</article>
|