shorewall_code/docs/CompiledPrograms.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</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>The <filename>/etc/shorewall/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
              /etc/shorewall/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>
          </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/firewall and use the /sbin/shorewall program
          included with Shorewall Lite to control the firewall just as if the
          full Shorewall distribution was installed.</para>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section>
    <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 ] [ &lt;directory name&gt; ]
      &lt;path name&gt;</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>&lt;directory name&gt;</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 &lt;directory-name&gt; 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>&lt;directory name&gt;/shorewall.conf</filename>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>&lt;path name&gt;</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>
      </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>On each firewall system, you run:</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>

        <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>
            <programlisting><command>cd &lt;export directory&gt;</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>
          </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 &lt;export directory&gt;</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>
    </orderedlist>

    <para>There is a <filename>shorewall.conf</filename> file installed as
    part of Shorewall Lite
    (<filename>/etc/shorewall-lite/shorewall.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. 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.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>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>
          <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>After having made the above changes to the firewall's export
          directory, execute the following commands:</para>

          <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>

          <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 &lt;export directory&gt;</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>/sbin/shorewall-lite show -f capabilities &gt; capabilities</command>
<command>scp capabilities &lt;admin system&gt;:&lt;this system's config dir&gt;</command></programlisting>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section>
    <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=&lt;iptables binary&gt; ] [
      MODULESDIR=&lt;kernel modules directory&gt; ]
      /usr/share/shorewall-lite/shorecap &gt; 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 &gt;
        capabilities</command></para>
      </blockquote></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>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        start</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        stop</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        clear</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        refresh</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        reset</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        restart</command></member>

        <member><command>&lt;program&gt; [ -q ] [ -v ] [ -n ]
        status</command></member>

        <member><command>&lt;program&gt; [ -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>