forked from extern/shorewall_code
b666fe9ece
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@4324 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
552 lines
21 KiB
XML
552 lines
21 KiB
XML
<?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">
|
|
<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>
|
|
|
|
<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 3.0 and
|
|
later. If you are installing or upgradeing to a version of Shorewall
|
|
earlier than Shorewall 3.0.0 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.</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 RPM</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>Some <trademark>SUSE</trademark> users have encountered a
|
|
problem whereby rpm reports a conflict with kernel <= 2.2 even
|
|
though a 2.4 kernel is installed. If this happens, simply use the
|
|
--nodeps option to rpm.</para>
|
|
|
|
<programlisting><filename><command>rpm -ivh --nodeps <shorewall rpm></command></filename></programlisting>
|
|
</note>
|
|
|
|
<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 <shorewall rpm></command></programlisting>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Edit the <link linkend="Config_Files">configuration files</link>
|
|
to match your configuration.</para>
|
|
|
|
<warning>
|
|
<para>YOU CAN <emphasis role="bold">NOT</emphasis> SIMPLY INSTALL
|
|
THE RPM AND ISSUE A <quote>shorewall start</quote> COMMAND. SOME
|
|
CONFIGURATION IS REQUIRED BEFORE THE FIREWALL WILL START. IF YOU
|
|
ISSUE A <quote>start</quote> COMMAND AND THE FIREWALL FAILS TO
|
|
START, YOUR SYSTEM WILL NO LONGER ACCEPT ANY NETWORK TRAFFIC. IF
|
|
THIS HAPPENS, ISSUE A <quote>shorewall clear</quote> COMMAND TO
|
|
RESTORE NETWORK CONNECTIVITY.</para>
|
|
</warning>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Enable startup by editing
|
|
/<filename>etc/shorewall/shorewall.conf</filename> and set
|
|
STARTUP_ENABLED to Yes).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Start the firewall by typing</para>
|
|
|
|
<programlisting><command>shorewall start</command></programlisting>
|
|
</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 tarball (tar -zxf shorewall-x.y.z.tgz).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>cd to the shorewall directory (the version is encoded in the
|
|
directory name as in <quote>shorewall-3.2.1</quote>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Type:</para>
|
|
|
|
<programlisting><command>./install.sh</command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Edit the <link linkend="Config_Files">configuration files</link>
|
|
to match your configuration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Enable Startup by editing
|
|
<filename>/etc/shorewall/shorewall.conf</filename> and set
|
|
STARTUP_ENABLED=Yes.</para>
|
|
</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="LRP">
|
|
<title>Install the .lrp</title>
|
|
|
|
<para>To install my version of Shorewall on a fresh Bering disk, simply
|
|
replace the <quote>shorwall.lrp</quote> file on the image with the file
|
|
that you downloaded. For example, if you download
|
|
<filename>shorewall-lrp-2.2.0.tgz</filename> then you will rename the file
|
|
to <filename>shorwall.lrp</filename> and replace the file by that name on
|
|
the Bering disk with the new file. Then proceed to configure Shorewall as
|
|
described in the Bering (or Bering uClibc) documentation.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Install the .deb</title>
|
|
|
|
<important>
|
|
<para>Once you have installed the .deb package and before you attempt to
|
|
configure Shorewall, please heed the advice of Lorenzo Martignoni, the
|
|
Shorewall Debian Maintainer:</para>
|
|
|
|
<para><quote>For more information about Shorewall usage on Debian system
|
|
please look at /usr/share/doc/shorewall/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>
|
|
<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 comments and 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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Upgrade the RPM</para>
|
|
|
|
<programlisting><command>rpm -Uvh <shorewall rpm file></command></programlisting>
|
|
|
|
<note>
|
|
<para>Some <trademark>SUSE</trademark> users have encountered a
|
|
problem whereby rpm reports a conflict with kernel <= 2.2 even
|
|
though a 2.4 kernel is installed. If this happens, simply use the
|
|
--nodeps option to rpm.</para>
|
|
|
|
<programlisting><command>rpm -Uvh --nodeps <shorewall rpm></command></programlisting>
|
|
</note>
|
|
|
|
<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>If you already have Shorewall installed and are upgrading to a new
|
|
version using the tarball:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>unpack the tarball.</para>
|
|
|
|
<programlisting><command>tar -zxf shorewall-x.y.z.tgz</command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>cd to the shorewall directory (the version is encoded in the
|
|
directory name as in <quote>shorewall-3.2.1</quote>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Type:</para>
|
|
|
|
<programlisting><command>./install.sh</command></programlisting>
|
|
</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="LRP_Upgrade">
|
|
<title>Upgrade the .lrp</title>
|
|
|
|
<para>The following was contributed by Charles Steinkuehler on the Leaf
|
|
mailing list:</para>
|
|
|
|
<blockquote>
|
|
<para>It's *VERY* simple...just put in a new CD and reboot! :-)
|
|
Actually, I'm only slightly kidding...that's exactly how I upgrade my
|
|
prodution firewalls. The partial backup feature I added to
|
|
Dachstein allows configuration data to be stored seperately from the
|
|
rest of the package.</para>
|
|
|
|
<para>Once the config data is seperated from the rest of the package,
|
|
it's an easy matter to upgrade the pacakge while keeping your current
|
|
configuration (in my case, just inserting a new CD and
|
|
re-booting).</para>
|
|
|
|
<para>Users who aren't running with multiple package paths and using
|
|
partial backups can still upgrade a package, it just takes a bit of
|
|
extra work. The general idea is to use a partial backup to save
|
|
your configuration, replace the package, and restore your old
|
|
configuration files. Step-by-step instructions for one way to do this
|
|
(assuming a conventional single-floppy LEAF system) would be:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Make a backup copy of your firewall disk ('NEW'). This
|
|
is the disk you will add the upgraded package(s) to.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Format a floppy to use as a temporary location for your
|
|
configuration file(s) ('XFER'). This disk should have the same
|
|
format as your firewall disk (and could simply be another backup
|
|
copy of your current firewall).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Make sure you have a working copy of your existing firewall
|
|
('OLD') in a safe place, that you *DO NOT* use durring this process.
|
|
That way, if anything goes wrong you can simply reboot off the OLD
|
|
disk to get back to a working configuration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Remove your current firewall configuration disk and replace it
|
|
with the XFER disk.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use the lrcfg backup menu to make a partial backup of the
|
|
package(s) you want to upgrade, being sure to backup the files to
|
|
the XFER disk. From the backup menu:</para>
|
|
|
|
<programlisting>t e <enter> p <enter>
|
|
b <package1> <enter>
|
|
b <package2> <enter>
|
|
...</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Download and copy the package(s) you want to upgrade onto the
|
|
NEW disk.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Reboot your firewall using the NEW disk...at this point your
|
|
upgraded packages will have their default configuration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Mount the XFER disk (mount -t msdos /dev/fd0u1680 /mnt)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CD to the root directory (cd /)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Manually extract configuration data for each package you
|
|
upgraded:</para>
|
|
|
|
<programlisting>tar -xzvf /mnt/package1.lrp
|
|
tar -xzvf /mnt/package2.lrp
|
|
...</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Unmount (umount /mnt) and remove the XFER disk</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Using lrcfg, do *FULL* backups of your upgraded
|
|
packages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Reboot, verifying the firewall works as expected. Some
|
|
configuration files may need to be 'tweaked' to work properly with
|
|
the upgraded package binaries.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<important>
|
|
<para>The new package file <package>.local can be used to
|
|
fine-tune which files are included (and excluded) from the partial
|
|
backup (see the Dachstein-CD README for details). If this file
|
|
doesn't exist, the backup scripts assume anything from the
|
|
<package>.list file that resides in /etc or /var/lib/lrpkg is
|
|
part of the configuration data and is used to create the partial
|
|
backup. If shorewall puts anything in /etc that isn't a user
|
|
modified configuration file, a proper shorwall.local file should be
|
|
created prior to making the partial backup [<emphasis
|
|
role="bold">Editor's note</emphasis>: Shorewall places only
|
|
user-modifiable files in /etc].</para>
|
|
</important>
|
|
|
|
<note>
|
|
<para>It's obviously possible to do the above 'in-place', without
|
|
using multiple disks, and even without making a partial backup (ie:
|
|
copy current config files to /tmp, manually extract new package on top
|
|
of current running firewall, then copy or merge config data from /tmp
|
|
and backup...or similar), but anyone capable of that level of command
|
|
line gymnastics is probably doing it already, without needing detailed
|
|
instructions! :-)</para>
|
|
</note>
|
|
</blockquote>
|
|
|
|
<para>For information on other LEAF/Bering upgrade tools, check out <ulink
|
|
url="http://leaf.cvs.sourceforge.net/*checkout*/leaf/devel/alexrh/lck/README.html">this
|
|
article by Alex Rhomberg</ulink>.</para>
|
|
</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>
|
|
<title>Uninstall/Fallback</title>
|
|
|
|
<para>See <quote><ulink url="fallback.htm">Fallback and
|
|
Uninstall</ulink></quote>.</para>
|
|
</section>
|
|
</article> |