Document EXPORTPARAMS

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5380 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

docs/CompiledPrograms.xml

@@ -73,8 +73,8 @@
 
             <listitem>
               <para>With Shorewall 3.2.0 through 3.2.8, the
-              <filename>/etc/shorewall/params</filename> extension script is
+              <filename>params</filename> extension script is executed at
-              executed at compile time as well as at run time.</para>
+              compile time as well as at run time.</para>
 
               <para>Running the script at compile time allows variable
               expansion (expanding $variable to it's defined value) of
@@ -92,9 +92,9 @@
               <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
+              compiled. On the other hand, if you use $EXT_IP in your start
-              /etc/shorewall/start script, the value will be the IP address of
+              script, the value will be the IP address of eth0 when the
-              eth0 when the program is run.</para>
+              program is run.</para>
 
               <para>Bottom line: You probably want to use only constant values
               for variables set in
@@ -102,14 +102,16 @@
             </listitem>
 
             <listitem>
-              <para>Beginning with Shorewall 3.4.0 RC2,
+              <para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
-              <filename>/etc/shorewall/params</filename> is only processed at
+              <filename>params</filename> file is only processed at compile
-              compile time. For run-time setting of shell variables, use
+              time if you set EXPORTPARAMS=No in
-              <filename>/etc/shorewall/init</filename>.</para>
+              <filename>shorewall.conf</filename>. For run-time setting of
+              shell variables, use the <filename>init</filename> extension
+              script.</para>
 
-              <para>If <filename>/etc/shorewall/params</filename> needs to set
+              <para>If the <filename>params</filename> file needs to set shell
-              shell variables based on the configuration of the firewall
+              variables based on the configuration of the firewall system, you
-              system, you can use this trick:</para>
+              can use this trick:</para>
 
               <programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
 
@@ -624,6 +626,61 @@ clean:
           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 it's 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>
 
@@ -728,7 +785,7 @@ 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
+    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>
 

docs/MultiISP.xml

@@ -715,12 +715,13 @@ eth1             eth2              130.252.99.27</programlisting>
       independent of Netfilter.</para>
 
       <warning>
-        <para>Entries in <filename>/etc/shorewall/route_rules</filename>
+        <para>Prior to Shorewall version 3.4.0, entries in
-        permanently alter your firewall/gateway's routing; that is, the effect
+        <filename>/etc/shorewall/route_rules</filename> permanently alter your
-        of these changes is not reversed by <command>shorewall stop</command>
+        firewall/gateway's routing; that is, the effect of these changes is
-        or <command>shorewall clear</command>. To restore routing to its
+        not reversed by <command>shorewall stop</command> or
-        original state, you may have to restart your network. This can usually
+        <command>shorewall clear</command>. To restore routing to its original
-        be done by <command>/etc/init.d/network restart</command> or
+        state, you may have to restart your network. This can usually be done
+        by <command>/etc/init.d/network restart</command> or
         <command>/etc/init.d/networking restart</command>. Check your
         distribution's networking documentation.</para>
 

docs/configuration_file_basics.xml

@@ -713,29 +713,21 @@ DNAT       net        loc:192.168.1.3 tcp       4000:4100</programlisting>
       </listitem>
 
       <listitem>
-        <para>In Shorewall 3.2, the <filename>/etc/shorewall/params</filename>
+        <para>The <filename>/etc/shorewall/params</filename> file is processed
-        file is processed by the compiler at compile-time and by the compiled
+        by the compiler at compile-time and by the compiled script at
-        script at run-time. Beginning with Shorewall version 3.2.9, the
+        run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if the "-e"
-        <filename>/etc/shorewall/params</filename> file is pre-processed in
+        flag is given to the compiler and you have set EXPORTPARAMS=No in
-        such a way that extra white-space is compressed from the file as it is
+        <filename>shorewall.conf</filename>, then the
-        being copied into the generated compiler output. So the code in
+        <filename><filename>params</filename></filename> file is only
-        /etc/shorewall/params should not depend on precise white-space,
+        processed by the compiler; it is not run by the compiled
-        including whitespace within quoted strings.</para>
+        script.</para>
       </listitem>
 
       <listitem>
-        <para>Beginning with Shorewall 3.4.0 RC2,
+        <para>If you are using Shorewall Lite and if the
-        <filename>/etc/shorewall/params</filename> is no longer copied into
+        <filename>params</filename> script needs to set shell variables based
-        the compiled script (and extra white-space is no longer compresed from
+        on the configuration of the firewall system, you can use this
-        the file). If you need to set shell variables for use by your run-time
+        trick:</para>
-        <ulink url="shorewall_extension_scripts.htm">extension
-        scripts</ulink>, then set those variables in your
-        <filename>/etc/shorewall/init</filename> file.</para>
-
-        <para>If you are using Shorewall Lite and if
-        <filename>/etc/shorewall/params</filename> 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>
 

docs/shorewall_extension_scripts.xml

@@ -245,17 +245,18 @@
     </listitem>
 
     <listitem>
-      <para><emphasis role="bold">Shorewall version 3.2.* only.</emphasis>
+      <para><emphasis role="bold">Shorewall version 3.2.0 - 3.2.8
-      When compiling your firewall configuration, Shorewall copies most
+      only.</emphasis> When compiling your firewall configuration, Shorewall
-      extension scripts directly into the "compiled" program where they are
+      copies most extension scripts directly into the "compiled" program where
-      executed in-line during processing of the start, restart and restore
+      they are executed in-line during processing of the start, restart and
-      commands. When copying a script, Shorewall indents the script to match
+      restore commands. When copying a script, Shorewall indents the script to
-      the surrounding code; if you have 'awk' installed on the system where
+      match the surrounding code; if you have 'awk' installed on the system
-      the configuration is being compiled, Shorewall can correctly handle line
+      where the configuration is being compiled, Shorewall can correctly
-      continuation in your script ("\" as the last character on a line). If
+      handle line continuation in your script ("\" as the last character on a
-      you do not have awk, you may not use line continuation in your scripts.
+      line). If you do not have awk, you may not use line continuation in your
-      Also beware that quoted strings continued from one line to another will
+      scripts. Also beware that quoted strings continued from one line to
-      have extra whitespace inserted as a result of indentation.</para>
+      another will have extra whitespace inserted as a result of
+      indentation.</para>
 
       <note>
         <para>The <filename>/etc/shorewall/params</filename> script is
@@ -279,20 +280,10 @@
         processed by the compiler rather than copied into the compiled
         script.</para>
       </note>
-
-      <note>
-        <para>Beginning in Shorewall version 3.4.9, a
-        <firstterm>compile</firstterm> extension script is supported. This
-        script is sourced during compiler initialization in the same way as
-        <filename>/etc/shorewall/params</filename>. This script is useful if
-        you are running Shorewall Lite on remote firewall systems and wish to
-        set variables only on the administrative system during
-        compilation.</para>
-      </note>
     </listitem>
 
     <listitem>
-      <para><emphasis role="bold">Shorewall version 3.4.0 RC2 and
+      <para><emphasis role="bold">Shorewall version 3.2.9 (3.4.0 RC2) and
       later.</emphasis> When compiling your firewall configuration, Shorewall
       copies most extension scripts directly into the "compiled" program where
       they are executed in-line during processing of the start, restart and
@@ -307,15 +298,25 @@
 
       <note>
         <para>The <filename>/etc/shorewall/params</filename> script is
-        processed only during compilation. So shell variables set in that file
+        processed only during compilation if the "-e" compiler flag is given
-        may be used in Shorewall configuration files only. Any variables that
+        and EXPORTPARAMS=No in <filename>shorewall.conf</filename>. So shell
-        your extension scripts require at run-time should be set in
+        variables set in that file may be used in Shorewall configuration
-        <filename>/etc/shorewall/init</filename>.Note that if you assign
+        files only. Any variables that your extension scripts require at
-        dynamic values to variables, there is no guarantee that the value
+        run-time on the firewall system should be set in the
-        calculated at compile time will be the same as what is calculated at
+        <filename>init</filename> extension script.</para>
-        run time. This is particularly true if you use the <command>shorewall
+
-        compile</command> command to compile a program then run that program
+        <para>When the "-e" flag is not given or when EXPORTPARAMS=Yes (the
-        at a later time or if you use Shorewall Lite.</para>
+        default), the <filename>/etc/shorewall/params</filename> script is
+        processed during compilation <emphasis role="bold">and</emphasis>
+        copied into the compiled script as described above. So shell variables
+        set during compilation may be used in Shorewall configuration files
+        while those set at run-time are available to your other extension
+        scripts.Note that if you assign dynamic values to variables, there is
+        no guarantee that the value calculated at compile time will be the
+        same as what is calculated at run time. This is particularly true if
+        you use the <command>shorewall compile</command> command to compile a
+        program then run that program at a later time or if you use Shorewall
+        Lite.</para>
       </note>
 
       <note>
@@ -327,12 +328,6 @@
         processed by the compiler rather than copied into the compiled
         script.</para>
       </note>
-
-      <note>
-        <para>The <firstterm>compile</firstterm> extension script is still
-        supported but its use is deprecated since it performs the same
-        function as <filename>/etc/shorewall/params</filename>.</para>
-      </note>
     </listitem>
   </itemizedlist>
 </article>