forked from extern/shorewall_code
acab08d0d5
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5757 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
868 lines
34 KiB
XML
868 lines
34 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$-->
|
|
|
|
<articleinfo>
|
|
<title>Compiled Firewall Programs and Shorewall Lite</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2006-2007</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>Overview</title>
|
|
|
|
<para>Beginning with Shorewall version 3.1, Shorewall has the capability
|
|
to compile a Shorewall configuration and produce a runnable firewall
|
|
program script. The script is a complete program which can be placed on a
|
|
system with <emphasis>Shorewall Lite</emphasis> installed and can serve as
|
|
the firewall creation script for that system.</para>
|
|
|
|
<section>
|
|
<title>Restrictions</title>
|
|
|
|
<para>While compiled Shorewall programs are useful in many cases, there
|
|
are some important restrictions that you should be aware of before
|
|
attempting to use them.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The <emphasis role="bold">detectnets</emphasis> interface
|
|
option is not supported.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DYNAMIC_ZONES=Yes in <filename>shorewall.conf</filename> is
|
|
not supported.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>All extension scripts used are copied into the program. The
|
|
ramifications of this are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If you update an extension script, the compiled program
|
|
will not use the updated script.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>With Shorewall 3.2.0 through 3.2.8, the
|
|
<filename>params</filename> extension script is executed at
|
|
compile time as well as at run time.</para>
|
|
|
|
<para>Running the script at compile time allows variable
|
|
expansion (expanding $variable to its defined value) of
|
|
variables used in Shorewall configuration files to occur at
|
|
compile time. Running it at run-time allows your extension
|
|
scripts to use the variables that it creates. BUT -- for any
|
|
given variable, the value at compile time may be different from
|
|
the value at run-time unless you only assign constant
|
|
values.</para>
|
|
|
|
<para>For example, if you have:</para>
|
|
|
|
<programlisting>EXT_IP=$(find_first_interface_address eth0)</programlisting>
|
|
|
|
<para>in <filename>/etc/shorewall/params</filename> then all
|
|
occurrences of $EXT_IP in Shorewall configuration files will be
|
|
replaced with eth0's IP address when the program is being
|
|
compiled. On the other hand, if you use $EXT_IP in your start
|
|
script, the value will be the IP address of eth0 when the
|
|
program is run.</para>
|
|
|
|
<para>Bottom line: You probably want to use only constant values
|
|
for variables set in
|
|
<filename>/etc/shorewall/params</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
|
|
<filename>params</filename> file is only processed at compile
|
|
time if you set EXPORTPARAMS=No in
|
|
<filename>shorewall.conf</filename>. For run-time setting of
|
|
shell variables, use the <filename>init</filename> extension
|
|
script. Although the default setting is EXPORTPARAMS=Yes for
|
|
compatibility, the recommended setting is
|
|
EXPORTPARAMS=No.</para>
|
|
|
|
<para>If the <filename>params</filename> file needs to set shell
|
|
variables based on the configuration of the firewall system, you
|
|
can use this trick:</para>
|
|
|
|
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
|
|
|
|
<para>The <command>shorewall-lite call</command> command allows
|
|
you to to call interactively any Shorewall function that you can
|
|
call in an extension script.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You must install Shorewall Lite on the system where you want
|
|
to run the script. You then install the compiled program in
|
|
/usr/share/shorewall-lite/firewall and use the /sbin/shorewall-lite
|
|
program included with Shorewall Lite to control the firewall just as
|
|
if the full Shorewall distribution was installed.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Compile">
|
|
<title>The "shorewall compile" command</title>
|
|
|
|
<para>A compiled script is produced using the <command>compile</command>
|
|
command:</para>
|
|
|
|
<blockquote>
|
|
<para><command>shorewall compile [ -e ] [ <directory name> ]
|
|
<path name></command></para>
|
|
</blockquote>
|
|
|
|
<para>where</para>
|
|
|
|
<blockquote>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-e</term>
|
|
|
|
<listitem>
|
|
<para>Indicates that the program is to be "exported" to another
|
|
system. When this flag is set, neither the "detectnets" interface
|
|
option nor DYNAMIC_ZONES=Yes in shorewall.conf are allowed. The
|
|
created program may be run on a system that has only Shorewall
|
|
Lite installed</para>
|
|
|
|
<para>When this flag is given, Shorewall does not probe the
|
|
current system to determine the kernel/iptables features that it
|
|
supports. It rather reads those capabilities from
|
|
<filename>/etc/shorewall/capabilities</filename>. See below for
|
|
details.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><directory name></term>
|
|
|
|
<listitem>
|
|
<para>specifies a directory to be searched for configuration files
|
|
before those directories listed in the CONFIG_PATH variable in
|
|
<filename>shorewall.conf</filename>.</para>
|
|
|
|
<para>When -e <directory-name> is included, only the
|
|
SHOREWALL_SHELL and VERBOSITY settings from
|
|
<filename>/etc/shorewall/shorewall.conf</filename> are used and
|
|
these apply only to the compiler itself. The settings used by the
|
|
compiled firewall script are determined by the contents of
|
|
<filename><directory name>/shorewall.conf</filename>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><path name></term>
|
|
|
|
<listitem>
|
|
<para>specifies the name of the script to be created.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</blockquote>
|
|
</section>
|
|
|
|
<section id="Lite">
|
|
<title>Shorewall Lite (Added in version 3.2.0 RC 1)</title>
|
|
|
|
<important>
|
|
<para>The following information applies to <emphasis
|
|
role="bold">Shorewall 3.2.2 and later</emphasis>. Users running versions
|
|
of Shorewall and Shorewall Lite earlier than 3.2.2 are urged to
|
|
upgrade.</para>
|
|
</important>
|
|
|
|
<para>Shorewall Lite is a companion product to Shorewall and is designed
|
|
to allow you to maintain all Shorewall configuration information on a
|
|
single system within your network.</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>You install the full Shorewall release on one system within your
|
|
network. You need not configure Shorewall there and you may totally
|
|
disable startup of Shorewall in your init scripts. For ease of
|
|
reference, we call this system the 'administrative system'.</para>
|
|
|
|
<caution>
|
|
<para>If you want to be able to allow non-root users to manage
|
|
remote filewall systems, then the file
|
|
<filename>/etc/shorewall/shorewall.conf</filename> must be readable
|
|
by all users on the administrative system. Not all packages secure
|
|
the file that way and you may have to change the file permissions
|
|
yourself. /sbin/shorewall uses the SHOREWALL_SHELL setting from
|
|
<filename>/etc/shorewall/shorewall.conf</filename> to determine the
|
|
shell to use when compiling programs and it uses the VERBOSITY
|
|
setting for determining how much output the compiler generates. All
|
|
other settings are taken from the <filename>shorewall.conf
|
|
</filename>file in the remote systems <firstterm>export
|
|
directory</firstterm> (see below).</para>
|
|
</caution>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>On each system where you wish to run a Shorewall-generated
|
|
firewall, you install Shorewall Lite. For ease of reference, we will
|
|
call these systems the 'firewall systems'.</para>
|
|
|
|
<note>
|
|
<para>The firewall systems do <emphasis role="bold">NOT</emphasis>
|
|
need to have the full Shorewall product installed but rather only
|
|
the Shorewall Lite product. Shorewall and Shorewall LIte may be
|
|
installed on the same system but that isn't encouraged.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>On the administrative system you create a separate 'export
|
|
directory' for each firewall system. You copy the contents of
|
|
/usr/share/shorewall/configfiles into each export directory.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are running Shorewall 3.2.5 or earlier, then on each
|
|
firewall system, you run:</para>
|
|
|
|
<programlisting><command>/usr/share/shorewall-lite/shorecap > capabilities</command>
|
|
<command>scp capabilities <admin system>:<this system's config dir></command></programlisting>
|
|
|
|
<para>If you are running Debian or one of its derivatives like Ubuntu
|
|
then edit /etc/default/shorewall-lite and set startup=1.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>On the administrative system, for each firewall system you do
|
|
the following (this may be done by a non-root user who has root ssh
|
|
access to the firewall system):</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>modify the files in the corresponding export directory
|
|
appropriately. It's a good idea to include the IP address of the
|
|
administrative system in the <filename>routestopped</filename>
|
|
file.</para>
|
|
|
|
<para>It is important to understand that with Shorewall Lite, the
|
|
firewall's export directory on the administrative system acts as
|
|
<filename class="directory">/etc/shorewall</filename> for that
|
|
firewall. So when the Shorewall documentation gives instructions
|
|
for placing entries in files in the firewall's <filename
|
|
class="directory">/etc/shorewall</filename>, when using Shorewall
|
|
Lite you make those changes in the firewall's export directory on
|
|
the administrative system.</para>
|
|
|
|
<para>The CONFIG_PATH variable is treated as follows:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The value of CONFIG_PATH in
|
|
<filename>/etc/shorewall/shorewall.conf </filename>is ignored
|
|
when compiling for export (the -e option in given) and when
|
|
the <command>load</command> or <command>reload</command>
|
|
command is being executed (see below).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The value of CONFIG_PATH in the
|
|
<filename>shorewall.conf</filename> file in the export
|
|
directory is used to search for configuration files during
|
|
compilation of that configuration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The value of CONFIG_PATH used when the script is run on
|
|
the firewall system is
|
|
"/etc/shorewall-lite:/usr/share/shorewall-lite".</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are running Shorewall 3.2.5 or earlier then:</para>
|
|
|
|
<blockquote>
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall load firewall</command></programlisting>
|
|
|
|
<para>The <ulink
|
|
url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink>
|
|
command compiles a firewall script from the configuration files
|
|
in the current working directory (using <command>shorewall
|
|
compile -e</command>), copies that file to the remote system via
|
|
scp and starts Shorewall Lite on the remote system via
|
|
ssh.</para>
|
|
|
|
<para>Example (firewall's DNS name is 'gateway'):</para>
|
|
|
|
<para><command>/sbin/shorewall load gateway</command></para>
|
|
</blockquote>
|
|
|
|
<para>If you are running Shorewall 3.2.6 or later then:</para>
|
|
|
|
<blockquote>
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall load -c firewall</command></programlisting>
|
|
|
|
<para>The <ulink
|
|
url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink>
|
|
command compiles a firewall script from the configuration files
|
|
in the current working directory (using <command>shorewall
|
|
compile -e</command>), copies that file to the remote system via
|
|
scp and starts Shorewall Lite on the remote system via ssh. The
|
|
-c option causes the capabilities of the remote system to be
|
|
generated and copied to a file named capabilities in the export
|
|
directory. See <link linkend="Shorecap">below</link>.</para>
|
|
|
|
<para>Example (firewall's DNS name is 'gateway'):</para>
|
|
|
|
<para><command>/sbin/shorewall load -c gateway</command></para>
|
|
</blockquote>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you later need to change the firewall's configuration, change
|
|
the appropriate files in the firewall's export directory then:</para>
|
|
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall reload firewall</command></programlisting>
|
|
|
|
<para>The <ulink
|
|
url="starting_and_stopping_shorewall.htm#Reload"><command>reload</command></ulink>
|
|
command compiles a firewall script from the configuration files in the
|
|
current working directory (using <command>shorewall compile
|
|
-e</command>), copies that file to the remote system via scp and
|
|
restarts Shorewall Lite on the remote system via ssh. Note: In
|
|
Shorewall 3.2.6 and later, the <emphasis role="bold">reload</emphasis>
|
|
command also supports the '-c' option.</para>
|
|
|
|
<para>I personally place a <filename>Makefile</filename> in each
|
|
export directory as follows:</para>
|
|
|
|
<blockquote>
|
|
<programlisting># Shorewall Packet Filtering Firewall Export Directory Makefile - V3.3
|
|
#
|
|
# This program is under GPL [http://www.gnu.org/copyleft/gpl.htm]
|
|
#
|
|
# (c) 2006 - Tom Eastep (teastep@shorewall.net)
|
|
#
|
|
# Shorewall documentation is available at http://www.shorewall.net
|
|
#
|
|
# This program is free software; you can redistribute it and/or modify
|
|
# it under the terms of Version 2 of the GNU General Public License
|
|
# as published by the Free Software Foundation.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program; if not, write to the Free Software
|
|
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
|
|
################################################################################
|
|
# Place this file in each export directory. Modify each copy to set HOST
|
|
# to the name of the remote firewall corresponding to the directory.
|
|
#
|
|
# To make the 'firewall' script, type "make".
|
|
#
|
|
# Once the script is compiling correctly, you can install it by
|
|
# typing "make install".
|
|
#
|
|
################################################################################
|
|
# V A R I A B L E S
|
|
#
|
|
# Files in the export directory on which the firewall script does not depend
|
|
#
|
|
IGNOREFILES = firewall% Makefile% trace% %~
|
|
#
|
|
# Remote Firewall system
|
|
#
|
|
HOST = gateway
|
|
#
|
|
# Save some typing
|
|
#
|
|
LITEDIR = /var/lib/shorewall-lite
|
|
#
|
|
# Set this if the remote system has a non-standard modules directory
|
|
#
|
|
MODULESDIR=
|
|
#
|
|
# Default target is the firewall script
|
|
#
|
|
################################################################################
|
|
# T A R G E T S
|
|
#
|
|
all: firewall
|
|
#
|
|
# Only generate the capabilities file if it doesn't already exist
|
|
#
|
|
capabilities:
|
|
ssh root@$(HOST) "MODULESDIR=$(MODULESDIR) /usr/share/shorewall-lite/shorecap > $(LITEDIR)/capabilities"
|
|
scp root@$(HOST):$(LITEDIR)/capabilities .
|
|
#
|
|
# Compile the firewall script. Using the 'wildcard' function causes "*" to be expanded so that
|
|
# 'filter-out' will be presented with the list of files in this directory rather than "*"
|
|
#
|
|
firewall: $(filter-out $(IGNOREFILES) capabilities , $(wildcard *) ) capabilities
|
|
shorewall compile -e . firewall
|
|
#
|
|
# Only reload on demand.
|
|
#
|
|
install: firewall
|
|
scp firewall firewall.conf root@$(HOST):$(LITEDIR)
|
|
ssh root@$(HOST) "/sbin/shorewall-lite restart"
|
|
#
|
|
# Save running configuration
|
|
#
|
|
save:
|
|
ssh root@$(HOST) "/sbin/shorewall-lite save"
|
|
#
|
|
# Remove generated files
|
|
#
|
|
clean:
|
|
rm -f capabilities firewall firewall.conf reload
|
|
</programlisting>
|
|
</blockquote>
|
|
|
|
<para>That way, after I've changed the configuration, I can simply
|
|
type <command>make</command> or <emphasis role="bold">make
|
|
install</emphasis>.</para>
|
|
|
|
<note>
|
|
<para>The above Makefile is available at <ulink
|
|
url="http://www1.shorewall.net/pub/shorewall/contrib/Shorewall-lite/">http://www.shorewall.net/pub/shorewall/contrib/Shorewall-lite/</ulink></para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>I omit trace% because I often trace compiler execution while
|
|
I'm debugging new versions of Shorewall.</para>
|
|
</note>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>There is a <filename>shorewall-lite.conf</filename> file installed
|
|
as part of Shorewall Lite
|
|
(<filename>/etc/shorewall-lite/shorewall-lite.conf</filename>). You can
|
|
use that file on the firewall system to override some of the settings from
|
|
the shorewall.conf file in the export directory.</para>
|
|
|
|
<important>
|
|
<para>In Shorewall 3.2.*, the name of the file was
|
|
<filename>/etc/shorewall-lite/shorewall.conf</filename> -- it was
|
|
changed to <filename>shorewall-lite.conf</filename> in version
|
|
3.4.0.</para>
|
|
</important>
|
|
|
|
<para>Settings that you can override are:</para>
|
|
|
|
<blockquote>
|
|
<simplelist>
|
|
<member>VERBOSITY</member>
|
|
|
|
<member>LOGFILE</member>
|
|
|
|
<member>LOGFORMAT</member>
|
|
|
|
<member>IPTABLES</member>
|
|
|
|
<member>PATH</member>
|
|
|
|
<member>SHOREWALL_SHELL</member>
|
|
|
|
<member>SUBSYSLOCK</member>
|
|
|
|
<member>RESTOREFILE</member>
|
|
</simplelist>
|
|
</blockquote>
|
|
|
|
<para>You will normally not need to touch
|
|
<filename>/etc/shorewall-lite/shorewall-lite.conf</filename>.</para>
|
|
|
|
<para>The <filename>/sbin/shorewall-lite</filename> program included with
|
|
Shorewall Lite supports the same set of commands as the
|
|
<filename>/sbin/shorewall</filename> program in a full Shorewall
|
|
installation with the following exceptions:</para>
|
|
|
|
<blockquote>
|
|
<simplelist>
|
|
<member>add</member>
|
|
|
|
<member>compile</member>
|
|
|
|
<member>delete</member>
|
|
|
|
<member>refresh</member>
|
|
|
|
<member>reload</member>
|
|
|
|
<member>try</member>
|
|
|
|
<member>safe-start</member>
|
|
|
|
<member>safe-restart</member>
|
|
|
|
<member>show actions</member>
|
|
|
|
<member>show macros</member>
|
|
</simplelist>
|
|
</blockquote>
|
|
|
|
<para>On systems with only Shorewall Lite installed, I recommend that you
|
|
create a symbolic link <filename>/sbin/shorewall</filename> and point it
|
|
at <filename>/sbin/shorewall-lite</filename>. That way, you can use
|
|
<command>shorewall</command> as the command regardless of which product is
|
|
installed.</para>
|
|
|
|
<blockquote>
|
|
<programlisting><command>ln -sf shorewall-lite /sbin/shorewall</command></programlisting>
|
|
</blockquote>
|
|
|
|
<section>
|
|
<title>Converting a system from Shorewall to Shorewall Lite</title>
|
|
|
|
<para>Converting a firewall system that is currently running Shorewall
|
|
to run Shorewall Lite instead is straight-forward.</para>
|
|
|
|
<orderedlist numeration="loweralpha">
|
|
<listitem>
|
|
<para>On the administrative system, create an export directory for
|
|
the firewall system.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Copy the contents of <filename
|
|
class="directory">/etc/shorewall/</filename> from the firewall
|
|
system to the export directory on the administrative system.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>On the firewall system:</para>
|
|
|
|
<para>Be sure that the IP address of the administrative system is
|
|
included in <filename>/etc/shorewall/routestopped</filename>.</para>
|
|
|
|
<programlisting><command>shorewall stop</command></programlisting>
|
|
|
|
<para><emphasis role="bold">We recommend that you uninstall
|
|
Shorewall at this point.</emphasis></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Install Shorewall Lite on the firewall system.</para>
|
|
|
|
<para>If you are running Debian or one of its derivatives like
|
|
Ubuntu then edit /etc/default/shorewall-lite and set
|
|
startup=1.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are running Shorewall 3.2.5 or earlier, then on the
|
|
firewall system:</para>
|
|
|
|
<programlisting><command>/usr/share/shorewall-lite/shorecap > capabilities</command>
|
|
<command>scp capabilities <admin system>:<this system's config dir></command></programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>On the administrative system:</para>
|
|
|
|
<para>It's a good idea to include the IP address of the
|
|
administrative system in the firewall system's
|
|
<filename>routestopped</filename> file.</para>
|
|
|
|
<para>Also, edit the shorewall.conf file in the firewall's export
|
|
directory and change the CONFIG_PATH setting to remove <filename
|
|
class="directory">/etc/shorewall</filename>. You can replace it with
|
|
<filename
|
|
class="directory">/usr/share/shorewall/configfiles</filename> if you
|
|
like.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<blockquote>
|
|
<para>Before editing:</para>
|
|
|
|
<programlisting>CONFIG_PATH=/etc/shorewall:/usr/share/shorewall</programlisting>
|
|
|
|
<para>After editing:</para>
|
|
|
|
<programlisting>CONFIG_PATH=/usr/share/shorewall/configfiles:/usr/share/shorewall</programlisting>
|
|
</blockquote>
|
|
|
|
<para>Changing CONFIG_PATH will ensure that subsequent compilations
|
|
using the export directory will not include any files from <filename
|
|
class="directory">/etc/shorewall</filename>.</para>
|
|
|
|
<para>If you set variables in the params file, there are a couple of
|
|
issues:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>With Shorewall 3.2.0 through 3.2.8, the
|
|
<filename>params</filename> extension script is executed at
|
|
compile time as well as at run time.</para>
|
|
|
|
<para>Running the script at compile time allows variable
|
|
expansion (expanding $variable to its defined value) of
|
|
variables used in Shorewall configuration files to occur at
|
|
compile time. Running it at run-time allows your extension
|
|
scripts to use the variables that it creates. BUT -- for any
|
|
given variable, the value at compile time may be different from
|
|
the value at run-time unless you only assign constant
|
|
values.</para>
|
|
|
|
<para>For example, if you have:</para>
|
|
|
|
<programlisting>EXT_IP=$(find_first_interface_address eth0)</programlisting>
|
|
|
|
<para>in <filename>/etc/shorewall/params</filename> then all
|
|
occurrences of $EXT_IP in Shorewall configuration files will be
|
|
replaced with eth0's IP address when the program is being
|
|
compiled. On the other hand, if you use $EXT_IP in your start
|
|
script, the value will be the IP address of eth0 when the
|
|
program is run.</para>
|
|
|
|
<para>Bottom line: You probably want to use only constant values
|
|
for variables set in <filename>/etc/shorewall/params</filename>
|
|
or upgrade to Shorewall 3.2.9 or later (3.4.0 RC2 or
|
|
later).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
|
|
<filename>params</filename> file is only processed at compile
|
|
time if you set EXPORTPARAMS=No in
|
|
<filename>shorewall.conf</filename>. For run-time setting of
|
|
shell variables, use the <filename>init</filename> extension
|
|
script.</para>
|
|
|
|
<para>If the <filename>params</filename> file needs to set shell
|
|
variables based on the configuration of the firewall system, you
|
|
can use this trick:</para>
|
|
|
|
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
|
|
|
|
<para>The <command>shorewall-lite call</command> command allows
|
|
you to to call interactively any Shorewall function that you can
|
|
call in an extension script.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>After having made the above changes to the firewall's export
|
|
directory, execute the following commands.</para>
|
|
|
|
<para>For Shorewall version 3.2.5 and earlier:</para>
|
|
|
|
<blockquote>
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall load <firewall system></command>
|
|
</programlisting>
|
|
|
|
<para>Example (firewall's DNS name is 'gateway'):</para>
|
|
|
|
<para><command>/sbin/shorewall load gateway</command></para>
|
|
</blockquote>
|
|
|
|
<para>For Shorewall versions 3.2.6 and later:</para>
|
|
|
|
<blockquote>
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall load -c <firewall system></command>
|
|
</programlisting>
|
|
|
|
<para>Example (firewall's DNS name is 'gateway'):</para>
|
|
|
|
<para><command>/sbin/shorewall load -c gateway</command></para>
|
|
</blockquote>
|
|
|
|
<para>The <ulink
|
|
url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink>
|
|
command compiles a firewall script from the configuration files in
|
|
the current working directory (using <command>shorewall compile
|
|
-e</command>), copies that file to the remote system via scp and
|
|
starts Shorewall Lite on the remote system via ssh.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you later need to change the firewall's configuration,
|
|
change the appropriate files in the firewall's export directory
|
|
then:</para>
|
|
|
|
<programlisting><command>cd <export directory></command>
|
|
<command>/sbin/shorewall reload firewall</command></programlisting>
|
|
|
|
<para>The <ulink
|
|
url="starting_and_stopping_shorewall.htm#Reload"><command>reload</command></ulink>
|
|
command compiles a firewall script from the configuration files in
|
|
the current working directory (using <command>shorewall compile
|
|
-e</command>), copies that file to the remote system via scp and
|
|
restarts Shorewall Lite on the remote system via ssh.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the kernel/iptables configuration on the firewall later
|
|
changes and you need to create a new capabilities file, do the
|
|
following:</para>
|
|
|
|
<programlisting><command>/usr/share/shorewall-lite/shorecap > capabilities</command>
|
|
<command>scp capabilities <admin system>:<this system's config dir></command></programlisting>
|
|
|
|
<para>Or, if you are running Shorewall 3.2.6 or later, simply use
|
|
the -c option the next time that you use the
|
|
<command>reload</command> command.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Shorecap">
|
|
<title>The /etc/shorewall/capabilities file and the shorecap
|
|
program</title>
|
|
|
|
<para>As mentioned above, the /etc/shorewall/capabilities file specifies
|
|
that kernel/iptables capabilities of the target system. Here is a sample
|
|
file:</para>
|
|
|
|
<blockquote>
|
|
<programlisting>NAT_ENABLED=Yes # NAT
|
|
MANGLE_ENABLED=Yes # Packet Mangling
|
|
MULTIPORT=Yes # Multi-port Match
|
|
XMULTIPORT=Yes # Extended Multi-port Match
|
|
CONNTRACK_MATCH=Yes # Connection Tracking Match
|
|
USEPKTTYPE= # Packet Type Match
|
|
POLICY_MATCH=Yes # Policy Match
|
|
PHYSDEV_MATCH=Yes # Physdev Match
|
|
LENGTH_MATCH=Yes # Packet Length Match
|
|
IPRANGE_MATCH=Yes # IP range Match
|
|
RECENT_MATCH=Yes # Recent Match
|
|
OWNER_MATCH=Yes # Owner match
|
|
IPSET_MATCH= # Ipset Match
|
|
CONNMARK=Yes # CONNMARK Target
|
|
XCONNMARK=Yes # Extended CONNMARK Target
|
|
CONNMARK_MATCH=Yes # Connmark Match
|
|
XCONNMARK_MATCH=Yes # Extended Connmark Match
|
|
RAW_TABLE=Yes # Raw Table
|
|
IPP2P_MATCH= # IPP2P Match
|
|
CLASSIFY_TARGET=Yes # CLASSIFY Target
|
|
ENHANCED_REJECT=Yes # Extended REJECT
|
|
KLUDGEFREE= # iptables accepts multiple "-m iprange" or "-m physdev" in a single command
|
|
MARK=Yes # MARK Target Support
|
|
XMARK=YES # Extended MARK Target Support
|
|
MANGLE_FORWARD # Mangle table has FORWARD chain</programlisting>
|
|
</blockquote>
|
|
|
|
<para>As you can see, the file contains a simple list of shell variable
|
|
assignments — the variables correspond to the capabilities listed by the
|
|
<command>shorewall show capabilities</command> command and they appear in
|
|
the same order as the output of that command.</para>
|
|
|
|
<para>To aid in creating this file, Shorewall Lite includes a
|
|
<command>shorecap</command> program. The program is installed in the
|
|
<filename>/usr/share/shorewall-lite/</filename> directory and may be run
|
|
as follows:</para>
|
|
|
|
<blockquote>
|
|
<para><command>[ IPTABLES=<iptables binary> ] [
|
|
MODULESDIR=<kernel modules directory> ]
|
|
/usr/share/shorewall-lite/shorecap > capabilities</command></para>
|
|
</blockquote>
|
|
|
|
<para>The IPTABLES and MODULESDIR options have their <ulink
|
|
url="Documentation.htm#Conf">usual Shorewall default
|
|
values</ulink>.</para>
|
|
|
|
<para>The <filename>capabilities</filename> file may then be copied to a
|
|
system with Shorewall installed and used when compiling firewall programs
|
|
to run on the remote system.</para>
|
|
|
|
<para>Beginning with Shorewall Lite version 3.2.2, the capabilities file
|
|
may also be creating using
|
|
<filename>/sbin/shorewall-lite:</filename><blockquote>
|
|
<para><command>shorewall-lite show -f capabilities >
|
|
capabilities</command></para>
|
|
</blockquote></para>
|
|
|
|
<para>Note that unlike the shorecap program, the <command>show
|
|
capabilities</command> command shows the kernel's current capabilities; it
|
|
does not attempt to load additional kernel modules.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Running compiled programs directly</title>
|
|
|
|
<para>Compiled firewall programs are complete programs that support the
|
|
following run-line commands:</para>
|
|
|
|
<blockquote>
|
|
<simplelist>
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
start</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
stop</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
clear</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
refresh</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
reset</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
restart</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
status</command></member>
|
|
|
|
<member><command><program> [ -q ] [ -v ] [ -n ]
|
|
version</command></member>
|
|
</simplelist>
|
|
</blockquote>
|
|
|
|
<para>The <command>refresh</command> command was added in Shorewall
|
|
3.2.3.</para>
|
|
|
|
<para>The options have their same meaning is when they are passed to
|
|
<filename>/sbin/shorewall</filename> itself. The default VERBOSITY level
|
|
is the level specified in the shorewall.conf file used when then program
|
|
was compiled.</para>
|
|
</section>
|
|
</article>
|