Update Compiled Program doc

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@8513 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2008-05-20 23:54:16 +00:00
parent 9fd69523a8
commit 119eb3fc76

View File

@ -34,6 +34,13 @@
</legalnotice> </legalnotice>
</articleinfo> </articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 4.0 and
later. If you are running a version of Shorewall earlier than Shorewall
4.0.0-Beta4 or you are not running Shorewall-perl then please see <ulink
url="3.0/NewBridge.html">this article</ulink>.</emphasis></para>
</caution>
<section id="Overview"> <section id="Overview">
<title>Overview</title> <title>Overview</title>
@ -73,36 +80,6 @@
will not use the updated script.</para> will not use the updated script.</para>
</listitem> </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> <listitem>
<para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the <para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
<filename>params</filename> file is only processed at compile <filename>params</filename> file is only processed at compile
@ -211,13 +188,6 @@
<section id="Lite"> <section id="Lite">
<title>Shorewall Lite (Added in version 3.2.0 RC 1)</title> <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 <para>Shorewall Lite is a companion product to Shorewall and is designed
to allow you to maintain all Shorewall configuration information on a to allow you to maintain all Shorewall configuration information on a
single system within your network.</para> single system within your network.</para>
@ -237,7 +207,7 @@
by all users on the administrative system. Not all packages secure by all users on the administrative system. Not all packages secure
the files that way and you may have to change the file permissions the files that way and you may have to change the file permissions
yourself. /sbin/shorewall uses the SHOREWALL_COMPILER setting to yourself. /sbin/shorewall uses the SHOREWALL_COMPILER setting to
determine which compiler to lanuch. If the compiler is determine which compiler to launch. If the compiler is
shorewall-shell, then the SHOREWALL_SHELL setting from shorewall-shell, then the SHOREWALL_SHELL setting from
<filename>/etc/shorewall/shorewall.conf</filename> determines the <filename>/etc/shorewall/shorewall.conf</filename> determines the
shell to use. /sbin/shorewall also uses the VERBOSITY setting for shell to use. /sbin/shorewall also uses the VERBOSITY setting for
@ -326,45 +296,22 @@
</listitem> </listitem>
<listitem> <listitem>
<para>If you are running Shorewall 3.2.5 or earlier then:</para> <programlisting><command>cd &lt;export directory&gt;</command>
<blockquote>
<programlisting><command>cd &lt;export directory&gt;</command>
<command>/sbin/shorewall load firewall</command></programlisting>
<para>The <ulink
url="manpages/shorewall.html"><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 &lt;export directory&gt;</command>
<command>/sbin/shorewall load -c firewall</command></programlisting> <command>/sbin/shorewall load -c firewall</command></programlisting>
<para>The <ulink <para>The <ulink
url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink> url="starting_and_stopping_shorewall.htm#Load"><command>load</command></ulink>
command compiles a firewall script from the configuration files command compiles a firewall script from the configuration files in
in the current working directory (using <command>shorewall the current working directory (using <command>shorewall compile
compile -e</command>), copies that file to the remote system via -e</command>), copies that file to the remote system via scp and
scp and starts Shorewall Lite on the remote system via ssh. The starts Shorewall Lite on the remote system via ssh. The -c option
-c option causes the capabilities of the remote system to be causes the capabilities of the remote system to be generated and
generated and copied to a file named capabilities in the export copied to a file named capabilities in the export directory. See
directory. See <link linkend="Shorecap">below</link>.</para> <link linkend="Shorecap">below</link>.</para>
<para>Example (firewall's DNS name is 'gateway'):</para> <para>Example (firewall's DNS name is 'gateway'):</para>
<para><command>/sbin/shorewall load -c gateway</command></para> <para><command>/sbin/shorewall load -c gateway</command></para>
</blockquote>
</listitem> </listitem>
</orderedlist> </orderedlist>
</listitem> </listitem>
@ -496,13 +443,6 @@ clean:
use that file on the firewall system to override some of the settings from use that file on the firewall system to override some of the settings from
the shorewall.conf file in the export directory.</para> 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> <para>Settings that you can override are:</para>
<blockquote> <blockquote>
@ -605,14 +545,6 @@ clean:
startup=1.</para> startup=1.</para>
</listitem> </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 &gt; capabilities</command>
<command>scp capabilities &lt;admin system&gt;:&lt;this system's config dir&gt;</command></programlisting>
</listitem>
<listitem> <listitem>
<para>On the administrative system:</para> <para>On the administrative system:</para>
@ -646,75 +578,25 @@ clean:
<para>If you set variables in the params file, there are a couple of <para>If you set variables in the params file, there are a couple of
issues:</para> issues:</para>
<itemizedlist> <para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
<listitem> <filename>params</filename> file is only processed at compile time
<para>With Shorewall 3.2.0 through 3.2.8, the if you set EXPORTPARAMS=No in <filename>shorewall.conf</filename>.
<filename>params</filename> extension script is executed at For run-time setting of shell variables, use the
compile time as well as at run time.</para> <filename>init</filename> extension script.</para>
<para>Running the script at compile time allows variable <para>If the <filename>params</filename> file needs to set shell
expansion (expanding $variable to its defined value) of variables based on the configuration of the firewall system, you can
variables used in Shorewall configuration files to occur at use this trick:</para>
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=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
<programlisting>EXT_IP=$(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
<para>in <filename>/etc/shorewall/params</filename> then all an extension script.</para>
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 <para>After having made the above changes to the firewall's export
directory, execute the following commands.</para> directory, execute the following commands.</para>
<para>For Shorewall version 3.2.5 and earlier:</para>
<blockquote>
<programlisting><command>cd &lt;export directory&gt;</command>
<command>/sbin/shorewall load &lt;firewall system&gt;</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> <blockquote>
<programlisting><command>cd &lt;export directory&gt;</command> <programlisting><command>cd &lt;export directory&gt;</command>
<command>/sbin/shorewall load -c &lt;firewall system&gt;</command> <command>/sbin/shorewall load -c &lt;firewall system&gt;</command>
@ -877,9 +759,6 @@ CAPVERSION=30405</programlisting>
</simplelist> </simplelist>
</blockquote> </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 <para>The options have their same meaning is when they are passed to
<filename>/sbin/shorewall</filename> itself. The default VERBOSITY level <filename>/sbin/shorewall</filename> itself. The default VERBOSITY level
is the level specified in the shorewall.conf file used when then program is the level specified in the shorewall.conf file used when then program