shorewall_code/docs/Modularization.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Shorewall Modularization</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 id="Intro">
    <title>Introduction</title>

    <para>One of the major changes in Shorewall version 3.4 involved breaking
    much of the code into <firstterm>libraries</firstterm>. This
    modularization is expected to be used primarily by embedded distributions
    that wish to minimize the Shorewall disk and RAM footprint.</para>

    <para>Shorewall libraries are Bourne shell source files that contain
    nothing but function declarations. Shorewall libraries may be loaded into
    a running shell program using the shell's "." operator. The library files
    have names which begin with "lib." and are installed in <filename
    class="directory">/usr/share/shorewall/</filename>.</para>

    <para>Individual libraries are of one of two classes. The first class of
    libraries are <firstterm>required libraries</firstterm> which, as their
    name implies, must be included in any Shorewall installation. The other
    libraries are <firstterm>optional libraries</firstterm> that implement a
    particular function. Each optional library may be included or omitted
    based on the requirements of the individual installation.</para>
  </section>

  <section id="Required">
    <title>Required Libraries</title>

    <para>Shorewall 3.4 includes the following required libraries.</para>

    <itemizedlist>
      <listitem>
        <para>lib.base — includes functions needed by all Shorewall
        programs.</para>
      </listitem>

      <listitem>
        <para>lib.cli — includes functions common to both
        <filename>/sbin/shorewall</filename> and
        <filename>/sbin/shorewall-lite</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.config — contains functions common to both
        <filename>/sbin/shorewall</filename> and
        <filename>/usr/share/shorewall/firewall</filename>.</para>
      </listitem>
    </itemizedlist>

    <para>lib.base and lib.cli are installed in /usr/share/shorewall-lite/ on
    Shorewall Lite systems.</para>
  </section>

  <section id="Optional">
    <title>Optional Libraries</title>

    <para>Optional libraries are loaded upon demand based on the user's
    configuration.</para>

    <para>In Shorewall 3.4, the optional libraries are as follows.</para>

    <itemizedlist>
      <listitem>
        <para>lib.accounting — required if the
        <filename>/etc/shorewall/accounting</filename> file is
        non-empty.</para>
      </listitem>

      <listitem>
        <para>lib.actions — required if USE_ACTIONS=Yes in
        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.dynamiczones — required if DYNAMIC_ZONES=Yes in
        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.maclist — required if the maclist option is specified in any
        entry in <filename>/etc/shorewall/interfaces</filename> or
        <filename>/etc/shorewall/hosts</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.nat — required if the
        <filename>/etc/shorewall/masq</filename>,
        <filename>/etc/shorewall/nat</filename> or
        <filename>/etc/shorewall/netmap</filename> files are non-empty or if
        DNAT[-] rules are present in
        <filename>/etc/shorewall/rules</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.providers — required if the
        <filename>/etc/shorewall/providers</filename> file is
        non-empty.</para>
      </listitem>

      <listitem>
        <para>lib.proxyarp — required if the
        <filename>/etc/shorewall/proxyarp</filename> file is non-empty or if
        the <emphasis role="bold">proxyarp</emphasis> option is specified in
        an entry in <filename>/etc/shorewall/interfaces</filename>.</para>
      </listitem>

      <listitem>
        <para>lib.tc — required if the
        <filename>/etc/shorewall/tcdevices</filename> or
        <filename>/etc/shorewall/tcclasses</filename> file is
        non-empty.</para>
      </listitem>

      <listitem>
        <para>lib.tcrules — required if the
        <filename>/etc/shorewall/tcrules</filename> file is non-empty.</para>
      </listitem>

      <listitem>
        <para>lib.tunnels — required if the
        <firstterm>/etc/shorewall/tunnels</firstterm> file is
        non-empty.</para>
      </listitem>
    </itemizedlist>

    <para>As described, many of the libraries are required when one or more
    configuration files are non-empty and embedded distribution providers are
    encouraged to package each optional library together with its associated
    configuration files.</para>

    <informaltable>
      <tgroup cols="2">
        <colspec align="left" />

        <tbody>
          <row>
            <entry><emphasis role="bold">Library</emphasis></entry>

            <entry><emphasis role="bold">Files</emphasis></entry>
          </row>

          <row>
            <entry>lib.accounting</entry>

            <entry><filename>/etc/shorewall/accounting</filename></entry>
          </row>

          <row>
            <entry>lib.actions</entry>

            <entry><filename>/etc/shorewall/actions</filename></entry>
          </row>

          <row>
            <entry>lib.maclist</entry>

            <entry><filename>/etc/shorewall/maclist</filename></entry>
          </row>

          <row>
            <entry>lib.nat</entry>

            <entry><filename>/etc/shorewall/masq, /etc/shorewall/nat,
            /etc/shorewall/netmap</filename></entry>
          </row>

          <row>
            <entry>lib.providers</entry>

            <entry><filename>/etc/shorewall/route_rules,
            /etc/shorewall/providers</filename></entry>
          </row>

          <row>
            <entry>lib.proxyarp</entry>

            <entry><filename>/etc/shorewall/proxyarp</filename></entry>
          </row>

          <row>
            <entry>lib.tc</entry>

            <entry><filename>/etc/shorewall/tcclasses,
            /etc/shorewall/tcdevices</filename></entry>
          </row>

          <row>
            <entry>lib.tcrules</entry>

            <entry><filename>/etc/shorewall/tcrules</filename></entry>
          </row>

          <row>
            <entry>lib.tunnels</entry>

            <entry><filename>/etc/shorewall/tunnels</filename></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Note that in Shorewall 4, the optional libraries (with the exception
    of <filename>lib.dynamiczones</filename>) are included in the
    Shorewall-shell package while the required libraries and
    <filename>lib.dynamiczones</filename> are included in the Shorewall-common
    package.</para>
  </section>
</article>