mirror of
https://gitlab.com/shorewall/code.git
synced 2025-06-07 18:26:53 +02:00
Shuffle the Compiled Program article
This commit is contained in:
Tom Eastep
parent
ff402dcf09
commit
e8b26236e2
@ -5,7 +5,7 @@
|
||||
<!--$Id$-->
|
||||
|
||||
<articleinfo>
|
||||
<title>Compiled Firewall Programs and Shorewall Lite</title>
|
||||
<title>Shorewall Lite and Compiled Firewall Programs</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
@ -50,122 +50,6 @@
|
||||
Lite</emphasis> installed and can serve as the firewall creation script
|
||||
for that system.</para>
|
||||
|
||||
<section id="Restrictions">
|
||||
<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>All extension scripts used are copied into the program (with
|
||||
the exception of <ulink url="shorewall_extension_scripts.htm">those
|
||||
executed at compile-time by the compiler</ulink>). 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>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. If not
|
||||
given, ${VARDIR}/firewall is assumed (by default, ${VARDIR} is
|
||||
<filename>/var/lib/shorewall/</filename>)</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</blockquote>
|
||||
</section>
|
||||
|
||||
<section id="Lite">
|
||||
<title>Shorewall Lite</title>
|
||||
|
||||
@ -175,10 +59,11 @@
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<para>The administrative system may be a GNU/Linux system, a Windows
|
||||
system running <ulink url="http://www.cygwin.com/">Cygwin</ulink> or
|
||||
@ -208,21 +93,24 @@
|
||||
each export directory.</para>
|
||||
|
||||
<note>
|
||||
<para>Users of Debian and derivatives that install the package from
|
||||
their distribution will be disappointed to find that <filename
|
||||
<para>Users of Debian and derivatives that install the package
|
||||
from their distribution will be disappointed to find that
|
||||
<filename
|
||||
class="directory">/usr/share/shorewall/configfiles</filename> does
|
||||
not exist on their systems. They will instead need to either:</para>
|
||||
not exist on their systems. They will instead need to
|
||||
either:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Copy the files in /usr/share/doc/shorewall/default-config/
|
||||
into each export directory.</para>
|
||||
<para>Copy the files in
|
||||
/usr/share/doc/shorewall/default-config/ into each export
|
||||
directory.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Copy /etc/shorewall/shorewall.conf into each export
|
||||
directory and remove /etc/shorewall from the CONFIG_PATH setting
|
||||
in the copied files.</para>
|
||||
directory and remove /etc/shorewall from the CONFIG_PATH
|
||||
setting in the copied files.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
@ -247,23 +135,23 @@
|
||||
<para>The <filename>/etc/shorewall/shorewall.conf</filename> file is
|
||||
used to determine the VERBOSITY setting which determines how much
|
||||
output the compiler generates. All other settings are taken from the
|
||||
<filename>shorewall.conf </filename>file in the remote systems export
|
||||
directory.</para>
|
||||
<filename>shorewall.conf </filename>file in the remote systems
|
||||
export directory.</para>
|
||||
|
||||
<caution>
|
||||
<para>If you want to be able to allow non-root users to manage
|
||||
remote firewall systems, then the files
|
||||
<filename>/etc/shorewall/params</filename> and
|
||||
<filename>/etc/shorewall/shorewall.conf</filename> must be readable
|
||||
by all users on the administrative system. Not all packages secure
|
||||
the files that way and you may have to change the file permissions
|
||||
yourself.</para>
|
||||
<filename>/etc/shorewall/shorewall.conf</filename> must be
|
||||
readable by all users on the administrative system. Not all
|
||||
packages secure the files that way and you may have to change the
|
||||
file permissions yourself.</para>
|
||||
</caution>
|
||||
</listitem>
|
||||
|
||||
<listitem id="Debian">
|
||||
<para>On each firewall system, If you are running Debian or one of its
|
||||
derivatives like Ubuntu then edit
|
||||
<para>On each firewall system, If you are running Debian or one of
|
||||
its derivatives like Ubuntu then edit
|
||||
<filename>/etc/default/shorewall-lite</filename> and set
|
||||
startup=1.</para>
|
||||
</listitem>
|
||||
@ -283,24 +171,25 @@
|
||||
url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
|
||||
file</ulink>.</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>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>
|
||||
<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>
|
||||
@ -311,8 +200,8 @@
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The value of CONFIG_PATH used when the script is run on
|
||||
the firewall system is
|
||||
<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>
|
||||
@ -324,10 +213,11 @@
|
||||
|
||||
<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>
|
||||
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>
|
||||
|
||||
@ -348,16 +238,17 @@
|
||||
</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>
|
||||
<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="manpages/shorewall.html"><command>reload</command></ulink>
|
||||
command compiles a firewall script from the configuration files in the
|
||||
current working directory (using <command>shorewall compile
|
||||
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. The <emphasis
|
||||
role="bold">reload</emphasis> command also supports the '-c'
|
||||
@ -471,8 +362,8 @@ clean:
|
||||
<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>
|
||||
use that file on the firewall system to override some of the settings
|
||||
from the shorewall.conf file in the export directory.</para>
|
||||
|
||||
<para>Settings that you can override are:</para>
|
||||
|
||||
@ -501,8 +392,8 @@ clean:
|
||||
run Debian or one of its derivatives (see <link
|
||||
linkend="Debian">above</link>).</para>
|
||||
|
||||
<para>The <filename>/sbin/shorewall-lite</filename> program included with
|
||||
Shorewall Lite supports the same set of commands as the
|
||||
<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>
|
||||
|
||||
@ -530,11 +421,11 @@ clean:
|
||||
</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>
|
||||
<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>
|
||||
@ -555,7 +446,8 @@ clean:
|
||||
<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>
|
||||
system to the export directory on the administrative
|
||||
system.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
@ -587,12 +479,12 @@ clean:
|
||||
url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
|
||||
file</ulink>.</para>
|
||||
|
||||
<para>Also, edit the <filename>shorewall.conf</filename> 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>Also, edit the <filename>shorewall.conf</filename> 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>
|
||||
|
||||
@ -606,14 +498,14 @@ clean:
|
||||
<programlisting>CONFIG_PATH=<emphasis role="bold">/usr/share/shorewall/configfiles</emphasis>:/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> other than
|
||||
<filename>shorewall.conf</filename> and
|
||||
<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> other
|
||||
than <filename>shorewall.conf</filename> and
|
||||
<filename>params</filename>.</para>
|
||||
|
||||
<para>If you set variables in the params file, there are a couple of
|
||||
issues:</para>
|
||||
<para>If you set variables in the params file, there are a couple
|
||||
of issues:</para>
|
||||
|
||||
<para>The <filename>params</filename> file is not processed at run
|
||||
time if you set EXPORTPARAMS=No in
|
||||
@ -622,14 +514,14 @@ clean:
|
||||
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>
|
||||
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>
|
||||
<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>
|
||||
|
||||
<para>After having made the above changes to the firewall's export
|
||||
directory, execute the following commands.</para>
|
||||
@ -694,6 +586,122 @@ clean:
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="Restrictions">
|
||||
<title>Restrictions</title>
|
||||
|
||||
<para>While compiled Shorewall programs (as are used in Shorewall Lite)
|
||||
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>All extension scripts used are copied into the program (with
|
||||
the exception of <ulink url="shorewall_extension_scripts.htm">those
|
||||
executed at compile-time by the compiler</ulink>). 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>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. If not
|
||||
given, ${VARDIR}/firewall is assumed (by default, ${VARDIR} is
|
||||
<filename>/var/lib/shorewall/</filename>)</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</blockquote>
|
||||
</section>
|
||||
|
||||
<section id="Shorecap">
|
||||
<title>The /etc/shorewall/capabilities file and the shorecap
|
||||
program</title>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user