shorewall_code/docs/starting_and_stopping_shorewall.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>Operating Shorewall and Shorewall Lite</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2004</year>

      <year>2005</year>

      <year>2006</year>

      <year>2007</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>

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 4.3 and
    later. If you are running a version of Shorewall earlier than Shorewall
    4.3.5 then please see the documentation for that
    release</emphasis>.</para>
  </caution>

  <section id="CLI">
    <title>/sbin/shorewall and /sbin/shorewall-lite</title>

    <para><filename>/sbin/shorewall</filename> is the program that you use to
    interact with Shorewall. Normally the root user's PATH includes
    <filename>/sbin</filename> and the program can be run from a shell prompt
    by simply typing <command>shorewall</command> followed by a
    command.</para>

    <warning>
      <para>In some releases of KDE, the default configuration of the
      <emphasis role="bold">konsole</emphasis> program is brain dead with
      respect to the "Root Console". It executes the command "su" where it
      should execute "su -"; the latter will cause a login shell to be created
      which will in turn set PATH properly. You can correct this problem as
      follows:</para>

      <orderedlist>
        <listitem>
          <para>Click on "Settings" on the toolbar and select "Configure
          Konsole"</para>
        </listitem>

        <listitem>
          <para>Select the "Session" tab.</para>
        </listitem>

        <listitem>
          <para>Click on "Root Console"</para>
        </listitem>

        <listitem>
          <para>Change the Execute command from "su" to "su -"</para>
        </listitem>

        <listitem>
          <para>Click on "Save Session"</para>
        </listitem>

        <listitem>
          <para>Click on "Ok"</para>
        </listitem>
      </orderedlist>
    </warning>

    <para>To see a list of supported commands, use the <command>help</command>
    command:</para>

    <programlisting><command>shorewall help</command></programlisting>

    <para>To get further information about a particular command, use the
    <command>man</command> command:</para>

    <programlisting><command>man shorewall</command>
</programlisting>

    <para>The program <emphasis role="bold">/sbin/shorewall-lite</emphasis>
    performs a similar role with Shorewall-lite.</para>

    <para>For a more complete description of the files and directories
    involved in Shorewall and Shorewall-lite, see the <ulink
    url="Anatomy.html">Shorewall Anatomy article</ulink>.</para>
  </section>

  <section id="Starting">
    <title>Starting, Stopping and Clearing</title>

    <para>As explained in the <ulink
    url="Introduction.html">Introduction</ulink>, Shorewall is not something
    that runs all of the time in your system. Nevertheless, for integrating
    Shorewall into your initialization scripts it is useful to speak of
    <firstterm>starting</firstterm> Shorewall and
    <emphasis>stopping</emphasis> Shorewall.</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall is started using the <command>shorewall
        start</command> command. Once the start command completes
        successfully, Netfilter is configured as described in your Shorewall
        configuration files. If there is an error during <command>shorewall
        start</command>, then if you have a <firstterm>saved
        configuration</firstterm> then that configuration is restored.
        Otherwise, an implicit <command>shorewall stop</command> is
        executed.</para>

        <important>
          <para><command>shorewall start</command> is implemented as a
          <firstterm>compile and go</firstterm>; that is, the configuration is
          compiled and if there are no compilation errors then the resulting
          compiled script is executed. If there are compilation errors, the
          command is aborted and the state of the firewall is not
          altered.</para>
        </important>
      </listitem>

      <listitem>
        <para>Shorewall is stopped using the <command>shorewall stop</command>
        command.</para>

        <important>
          <para>The <command>shorewall stop</command> command does not remove
          all Netfilter rules and open your firewall for all traffic to pass.
          It rather places your firewall in a safe state defined by the
          contents of your <ulink
          url="manpages/shorewall-routestopped.html">/etc/shorewall/routestopped</ulink>
          file and the setting of ADMINISABSENTMINDED in <ulink
          url="manpages/shorewall.conf.html">/etc/shorewall/shorewall.conf</ulink>.</para>
        </important>
      </listitem>

      <listitem>
        <para>If you want to remove all Netfilter rules and open your firewall
        for all traffic to pass, use the <command>shorewall clear</command>
        command.</para>
      </listitem>

      <listitem>
        <para>If you change your configuration and want to install the
        changes, use the <command>shorewall restart </command>command.</para>
      </listitem>
    </itemizedlist>

    <para>For additional information, see the<link linkend="State"> Shorewall
    State Diagram</link> section.</para>
  </section>

  <section id="Init">
    <title>/etc/init.d/shorewall and /etc/init.d/shorewall-lite</title>

    <para>Because of the different requirements of distribution packaging
    systems, the behavior of <filename>/etc/init.d/shorewall</filename> and
    <filename>/etc/init.d/shorewall-lite</filename> is not consistent between
    distributions. As an example, when using the distribution Shorewall
    packages on <trademark>Debian</trademark> and
    <trademark>Ubuntu</trademark> systems, running
    <command>/etc/init.d/shorewall stop</command> will actually execute the
    command <command>/sbin/shorewall clear</command> rather than
    <command>/sbin/shorewall stop</command>! So don't expect the meaning of
    <emphasis>start</emphasis>, <emphasis>stop</emphasis>,
    <emphasis>restart</emphasis>, etc. to be consistent between
    <filename>/sbin/shorewall</filename> (or
    <filename>/sbin/shorewall-lite</filename>) and your init scripts unless
    you got your Shorewall package from shorewall.net.</para>
  </section>

  <section id="Trace">
    <title>Tracing Command Execution and other Debugging Aids</title>

    <para>If you include the word <emphasis role="bold">trace</emphasis> as
    the first parameter to an <filename>/sbin/shorewall</filename> command
    that transfers control to
    <filename>/usr/share/shorewall/firewall</filename>, execution of the
    latter program will be traced to STDERR.</para>

    <example id="trace">
      <title>Tracing <command>shorewall start</command></title>

      <para>To trace the execution of <command>shorewall start</command> and
      write the trace to the file <filename>/tmp/trace</filename>, you would
      enter:<programlisting><command>shorewall trace start 2&gt; /tmp/trace</command></programlisting><note>
          <para>The <emphasis role="bold">trace</emphasis> keyword does not
          result in a trace of the execution of the Shorewall rules compiler.
          It rather causes additional diagnostic information to be included in
          warning and error messages generated by the compiler.</para>
        </note></para>

      <para>You may also include the word <emphasis
      role="bold">debug</emphasis> as the first argument to the
      <filename>/sbin/shorewall</filename> and
      <filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In
      most cases, <emphasis role="bold">debug</emphasis> is a synonym for
      <emphasis role="bold">trace</emphasis>. The exceptions are:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">debug</emphasis> is ignored by the
          Shorewall-perl compiler.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">debug</emphasis> causes altered behavior
          of scripts generated by the Shorewall-perl compiler. These scripts
          normally use<command> iptables-restore</command> to install the
          Netfilter ruleset but with <emphasis role="bold">debug</emphasis>,
          the commands normally passed to <command>iptables-restore</command>
          in its input file are passed individually to
          <command>iptables</command>. This is a diagnostic aid which allows
          identifying the individual command that is causing
          <command>iptables-restore</command> to fail; it should be used when
          iptables-restore fails when executing a <command>COMMIT</command>
          command.</para>
        </listitem>
      </itemizedlist>

      <para><warning>
          <para>The <emphasis role="bold">debug</emphasis> feature is strictly
          for problem analysis. When <emphasis role="bold">debug</emphasis> is
          used:</para>

          <orderedlist>
            <listitem>
              <para>The firewall is made 'wide open' before the rules are
              applied.</para>
            </listitem>

            <listitem>
              <para>The <filename>routestopped</filename> file is not
              consulted.</para>
            </listitem>

            <listitem>
              <para>The rules are applied in the canonical
              <command>iptables-restore</command> order. So if you need
              critical hosts to be always available during start/restart, you
              may not be able to use <emphasis
              role="bold">debug</emphasis>.</para>
            </listitem>
          </orderedlist>
        </warning></para>
    </example>
  </section>

  <section id="Boot">
    <title>Having Shorewall Start Automatically at Boot Time</title>

    <para>The .rpm, .deb and .tgz all try to configure your startup scripts so
    that Shorewall will start automatically at boot time. If you are using the
    <command>install.sh </command>script from the .tgz and it cannot determine
    how to configure automatic startup, a message to that effect will be
    displayed. You will need to consult your distribution's documentation to
    see how to integrate the <filename>/etc/init.d/shorewall</filename> script
    into the distribution's startup mechanism.<caution>
        <itemizedlist>
          <listitem>
            <para>Shorewall startup is disabled by default. Once you have
            configured your firewall, you can enable startup by editing
            <filename>/etc/shorewall/shorewall.conf</filename> and setting
            STARTUP_ENABLED=Yes.. Note: Users of the .deb package must rather
            edit <filename>/etc/default/shorewall</filename> and set
            <quote>startup=1</quote>.</para>
          </listitem>

          <listitem>
            <para>If you use dialup or some flavor of PPP where your IP
            address can change arbitrarily, you may want to start the firewall
            in your <command>/etc/ppp/ip-up.local</command> script. I
            recommend just placing <quote><command>/sbin/shorewall
            restart</command></quote> in that script.</para>
          </listitem>
        </itemizedlist>
      </caution></para>
  </section>

  <section id="Saved">
    <title>Saving a Working Configuration for Error Recovery and Fast
    Startup</title>

    <para>Once you have Shorewall working the way that you want it to, you can
    use <command>shorewall save</command> to <firstterm>save</firstterm> the
    commands necessary to recreate that configuration in a <firstterm>restore
    script</firstterm>.</para>

    <para>In its simplest form, the save command is just:</para>

    <programlisting><command>shorewall save</command></programlisting>

    <para>That command creates the default restore script,
    <filename>/var/lib/shorewall/restore</filename>. The default may be
    changed using the RESTOREFILE option in <ulink
    url="manpages/shorewall.conf.html">/etc/shorewall/shorewall.conf</ulink>.
    A different file name may also be specified in the <command>save</command>
    command:</para>

    <programlisting><command>shorewall save &lt;filename&gt;</command></programlisting>

    <para>Where &lt;<emphasis>filename</emphasis>&gt; is a simple file name
    (no slashes).</para>

    <para>Once created, the default restore script serves several useful
    purposes:</para>

    <itemizedlist>
      <listitem>
        <para>If you change your configuration and there is an error when you
        try to restart Shorewall, the restore script will be run to restore
        your firewall to working order.</para>
      </listitem>

      <listitem>
        <para>Bootup is faster (although with Shorewall-perl, the difference
        is minimal). The -f option of the start command (e.g.,
        <command>shorewall -f start</command>) causes Shorewall to look for
        the default restore script and if it exists, the script is run. When
        using Shorewall-shell, this is much faster than starting Shorewall
        using the normal mechanism of reading the configuration files and
        running <command>iptables</command> dozens or even hundreds of
        times.</para>

        <para>The default is to not use -f. If you wish to change the default,
        you must set the OPTIONS shell variable in either
        <filename>/etc/default/shorewall</filename> or
        <filename>/etc/sysconfig/shorewall</filename> (if your distribution
        provides neither of these files, you must create one or the other).
        </para>
      </listitem>

      <listitem>
        <para>The <command>shorewall restore</command> command can be used at
        any time to quickly configure the firewall.</para>

        <programlisting><command>shorewall restore [ &lt;filename&gt; ]</command></programlisting>

        <para>If no &lt;<emphasis>filename</emphasis>&gt; is given, the
        default restore script is used. Otherwise, the script
        <filename>/var/lib/shorewall/&lt;filename&gt;</filename> is
        used.</para>
      </listitem>
    </itemizedlist>

    <para>The ability to have multiple restore scripts means that you can save
    different Shorewall firewall configurations and switch between them
    quickly using the <command>restore</command> command.</para>

    <para>Restore scripts may be removed using the <command>shorewall
    forget</command> command:</para>

    <programlisting><command>shorewall forget [ &lt;filename&gt; ]</command></programlisting>

    <para>If no &lt;<emphasis>filename</emphasis>&gt; is given, the default
    restore script is removed. Otherwise,
    <filename>/var/lib/shorewall/&lt;filename&gt;</filename> is removed (of
    course, you can also use the Linux <command>rm</command> command from the
    shell prompt to remove these files).</para>
  </section>

  <section id="AddDirectories">
    <title>Additional Configuration Directories</title>

    <para>The CONFIG_PATH setting in
    <filename>/etc/shorewall/shorewall.conf</filename> determines where
    Shorewall looks for configuration files. The default setting is
    CONFIG_PATH=<filename
    class="directory">/etc/shorewall</filename>:<filename
    class="directory">/usr/share/shorewall</filename> which means that
    <filename class="directory">/etc/shorewall</filename> is searched first
    and if the file is not found then <filename
    class="directory">/usr/share/shorewall</filename> is searched. You can
    change the value of CONFIG_PATH to cause additional directories to be
    searched but CONFIG_PATH should <emphasis>always</emphasis> include both
    <filename class="directory">/etc/shorewall</filename> and <filename
    class="directory">/usr/share/shorewall</filename>.</para>

    <para>When an alternate configuration directory is specified as described
    in the <link linkend="AddDirectories">next section</link>, that directory
    is searched <emphasis>before</emphasis> those directories listed in
    CONFIG_PATH.</para>

    <para>Example - Search <filename
    class="directory">/etc/shorewall</filename>, <filename
    class="directory">/etc/shorewall/actiondir</filename> and <filename
    class="directory">/usr/share/shorewall</filename> in that order:</para>

    <programlisting>CONFIG_PATH=/etc/shorewall:/etc/shorewall/actiondir:/usr/share/shorewall</programlisting>

    <para>The above is the setting that I once used to allow me to place all
    of my user-defined 'action.' files in <filename
    class="directory">/etc/shorewall/actiondir</filename>.</para>
  </section>

  <section id="AltConfig">
    <title>Alternate Configuration Directories</title>

    <para>As explained <link linkend="AddDirectories">above</link>, Shorewall
    normally looks for configuration files in the directories specified by the
    CONFIG_PATH option in <filename
    class="directory">/etc/shorewall/shorewall.conf</filename>. The
    <command>shorewall start</command>, <command>shorewall restart</command>,
    <command>shorewall check</command>, and <command>shorewall try
    </command>commands allow you to specify an additional directory for
    Shorewall to check before looking in the directories listed in
    CONFIG_PATH.</para>

    <programlisting>     <command>shorewall {start|restart|check} &lt;configuration-directory&gt;</command>
     <command>shorewall try &lt;configuration-directory&gt; [ &lt;timeout&gt; ]</command></programlisting>

    <para>If a <emphasis>&lt;configuration-directory</emphasis>&gt; is
    specified, each time that Shorewall is going to read a file, it will first
    look in the<emphasis> &lt;configuration-directory&gt;</emphasis> . If the
    file is present in the
    <emphasis>&lt;configuration-directory&gt;,</emphasis> that file will be
    used; otherwise, the directories in the CONFIG_PATH will be searched. When
    changing the configuration of a production firewall, I recommend the
    following:</para>

    <itemizedlist>
      <listitem>
        <para>If you haven't saved the current working configuration, do so
        using <command>shorewall save</command>.</para>
      </listitem>

      <listitem>
        <para><command>mkdir /etc/test</command></para>
      </listitem>

      <listitem>
        <para><command>cd /etc/test</command></para>
      </listitem>

      <listitem>
        <para>&lt;copy any files that you need to change from /etc/shorewall
        to . and change them here&gt;</para>
      </listitem>

      <listitem>
        <para><command>shorewall check ./</command></para>
      </listitem>

      <listitem>
        <para>&lt;correct any errors found by check and check again&gt;</para>
      </listitem>

      <listitem>
        <para><command>shorewall restart ./</command></para>
      </listitem>
    </itemizedlist>

    <para>If the <command>restart</command> fails, your configuration will be
    restored to its state at the last <command>shorewall
    save</command>.</para>

    <para>When the new configuration works then just:</para>

    <itemizedlist>
      <listitem>
        <para><command>cp -f * /etc/shorewall</command></para>
      </listitem>

      <listitem>
        <para><command>cd</command></para>
      </listitem>

      <listitem>
        <para><command>rm -rf /etc/test</command></para>
      </listitem>

      <listitem>
        <para><command>shorewall save</command></para>
      </listitem>
    </itemizedlist>

    <important>
      <para>Shorewall requires that the file
      <filename>/etc/shorewall/shorewall.conf</filename> to always exist.
      Certain global settings are always obtained from that file. If you
      create alternative configuration directories, do not remove
      /etc/shorewall/shorewall.conf.</para>
    </important>
  </section>

  <section id="Commands">
    <title>Commands</title>

    <para>The general form of a command is:</para>

    <blockquote>
      <para><command>shorewall [ &lt;options&gt; ] &lt;command&gt; [
      &lt;command options&gt; ] [ &lt;argument&gt; ... ]</command></para>

      <para>Available options are:</para>

      <variablelist>
        <varlistentry>
          <term>-c &lt;directory&gt;</term>

          <listitem>
            <para>Specifies an <link linkend="AltConfig">alternate
            configuration directory</link>. Use of this option is
            deprecated.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-f</term>

          <listitem>
            <para>Specifies fast restart. See the <command>start</command>
            command below.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-n</term>

          <listitem>
            <para>Prevents the command from changing the firewall system's
            routing configuration.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-q</term>

          <listitem>
            <para>Reduces the verbosity level (see VERBOSITY setting in <ulink
            url="manpages/shorewall.conf.htmlig">shorewall.conf</ulink>). May
            be repeated (e.g., "-qq") with each instance reducing the
            verbosity level by one.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-v</term>

          <listitem>
            <para>Increases the verbosity level (see VERBOSITY setting in
            <ulink
            url="manpages/shorewall.conf.htmlig">shorewall.conf</ulink>). May
            be repeated (e.g., "-qq") with each instance increasing the
            verbosity level by one.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-x</term>

          <listitem>
            <para>Causes all iptables -L commands to display actual packet and
            byte counts.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-t</term>

          <listitem>
            <para>All progress messages are timestamped with the date and
            time.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>In addition, the <command>-q</command> and <command>-v</command>
      options may be repeated to make the output less or more verbose
      respectively. The default level of verbosity is determined by the
      setting of the VERBOSITY option in
      <filename>/etc/shorewall/shorewall.conf</filename>.</para>

      <para>For Shorewall Lite, the general command form is:</para>

      <para><command>shorewall-lite [ &lt;options&gt; ] &lt;command&gt; [
      &lt;command options&gt; ] [ &lt;argument&gt; ... ]</command></para>

      <para>where the options are the same as with Shorewall.</para>

      <para>The complete documentation for each command may be found in the
      <ulink url="manpages/shorewall.html">shorewall</ulink> and <ulink
      url="manpages/shorewall-lite.html">shorewall-lite</ulink> man
      pages.</para>
    </blockquote>
  </section>

  <section id="State">
    <title>Shorewall State Diagram</title>

    <para>The Shorewall State Diagram is depicted below.</para>

    <para><graphic align="center" fileref="images/State_Diagram.png" /></para>

    <informaltable>
      <tgroup cols="3">
        <thead>
          <row>
            <entry align="center">/sbin/shorewall Command</entry>

            <entry align="center">Resulting /usr/share/shorewall/firewall
            Command</entry>

            <entry align="center">Effect if the Command Succeeds</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>shorewall start</entry>

            <entry>firewall start</entry>

            <entry>The system filters packets based on your current Shorewall
            Configuration</entry>
          </row>

          <row>
            <entry>shorewall stop</entry>

            <entry>firewall stop</entry>

            <entry>Only traffic to/from hosts listed in /etc/shorewall/hosts
            is passed to/from/through the firewall. If ADMINISABSENTMINDED=Yes
            in /etc/shorewall/shorewall.conf then in addition, all existing
            connections are retained and all connection requests from the
            firewall are accepted.</entry>
          </row>

          <row>
            <entry>shorewall restart</entry>

            <entry>firewall restart</entry>

            <entry>Logically equivalent to <quote>firewall stop;firewall
            start</quote></entry>
          </row>

          <row>
            <entry>shorewall add</entry>

            <entry>firewall add</entry>

            <entry>Adds a host or subnet to a dynamic zone</entry>
          </row>

          <row>
            <entry>shorewall delete</entry>

            <entry>firewall delete</entry>

            <entry>Deletes a host or subnet from a dynamic zone</entry>
          </row>

          <row>
            <entry>shorewall refresh</entry>

            <entry>firewall refresh</entry>

            <entry>Reloads rules dealing with static blacklisting, traffic
            control and ECN.</entry>
          </row>

          <row>
            <entry>shorewall reset</entry>

            <entry>firewall reset</entry>

            <entry>Resets traffic counters</entry>
          </row>

          <row>
            <entry>shorewall clear</entry>

            <entry>firewall clear</entry>

            <entry>Removes all Shorewall rules, chains, addresses, routes and
            ARP entries.</entry>
          </row>

          <row>
            <entry>shorewall try</entry>

            <entry>firewall -c &lt;new configuration&gt; restart If
            unsuccessful then firewall start (standard configuration) If
            timeout then firewall restart (standard configuration)</entry>

            <entry></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The only time that a program other than
    <command>/usr/share/shorewall[-lite[/firewall</command> performs a state
    transition itself is when the <command>shorewall[-lite] restore</command>
    command is executed. In that case, the
    <command>/var/lib/shorewall[-lite]/restore</command> program sets the
    state to "Started".</para>

    <para>With any command that involves compilation, there is no state
    transition while the compiler is running. If compilation fails, the state
    remains unchanged.</para>

    <para>Also, <command>shorewall start</command> and <command>shorewall
    restart</command> involve compilation followed by execution of the
    compiled script. So it is the compiled script that performs the state
    transition in these commands rather than
    <command>/usr/share/shorewall/firewall</command>.</para>

    <para>The compiled script is placed in <filename
    class="directory">/var/lib/shorewall</filename> and is named either
    <filename>.start</filename> or <filename>.restart</filename> depending on
    the command.</para>
  </section>
</article>