shorewall_code/Shorewall-docs/starting_and_stopping_shorewall.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>Starting/Stopping and Monitoring the Firewall</title>

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

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

    <pubdate>2004-01-04</pubdate>

    <copyright>
      <year>2001-2004</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>Operating Shorewall</title>

    <para>If you have a permanent internet connection such as DSL or Cable, I
    recommend that you start the firewall automatically at boot. The <ulink
    url="Install.htm">installation procedure</ulink> attempts to set up the
    init scripts to start the firewall in run levels 2-5 and stop it in run
    levels 1 and 6. If you want to configure your firewall differently from
    this default, you can use your distribution&#39;s run-level editor.</para>

    <caution>
      <itemizedlist>
        <listitem>
          <para>Shorewall startup is disabled by default. Once you have
          configured your firewall, you can enable startup by removing the
          file <filename>/etc/shorewall/startup_disabled</filename>. Note:
          Users of the .deb package must 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>You can manually start and stop Shoreline Firewall using the
    <quote><command>/sbin/shorewall</command></quote> shell program.</para>

    <itemizedlist>
      <listitem>
        <para><command>shorewall start </command>- starts the firewall. It
        important to understand that when the firewall is in the <emphasis
        role="bold">Started</emphasis> state there is <emphasis>no Shorewall
        Program</emphasis> <emphasis>running</emphasis>. It rather means that
        Netfilter has been configured to handle traffic as described in your
        Shorewall configuration files. Please refer to the <link
        linkend="State">Shorewall State Diagram</link> as shown at the bottom
        of this page for more information.</para>
      </listitem>

      <listitem>
        <para><command>shorewall stop</command> - stops the firewall; the only
        traffic permitted through the firewall is from systems listed in
        <filename>/etc/shorewall/routestopped</filename> (Beginning with
        version 1.4.7, if ADMINISABSENTMINDED=Yes in <filename>/etc/shorewall/shorewall.conf</filename>
        then in addition, all existing connections are permitted and any new
        connections originating from the firewall itself are allowed).</para>
      </listitem>

      <listitem>
        <para><command>shorewall restart </command>- stops the firewall (if it
        is in the <emphasis role="bold">Started</emphasis> state) and then
        starts it again</para>
      </listitem>

      <listitem>
        <para><command>shorewall reset</command> - reset the packet and byte
        counters in the firewall</para>
      </listitem>

      <listitem>
        <para><command>shorewall clear</command> - remove all rules and chains
        installed by Shoreline Firewall. The firewall is <quote>wide open</quote></para>
      </listitem>

      <listitem>
        <para><command>shorewall refresh</command> - refresh the rules
        involving the broadcast addresses of firewall interfaces, the black
        list, traffic control rules and ECN control rules.</para>
      </listitem>
    </itemizedlist>

    <para>If you include the keyword debug as the first argument, then a shell
    trace of the command is produced as in:</para>

    <para><programlisting>     <command>shorewall debug start 2&#62; /tmp/trace</command></programlisting>The
    above command would trace the <quote>start</quote> command and place the
    trace information in the file /tmp/trace</para>

    <para>Beginning with version 1.4.7, shorewall can give detailed help about
    each of its commands: <programlisting>     <command>shorewall help [ command | host | address ]</command></programlisting>The
    <quote>shorewall</quote> program may also be used to monitor the firewall.</para>

    <itemizedlist>
      <listitem>
        <para><command>shorewall status</command> - produce a verbose report
        about the firewall (iptables -L -n -v)</para>
      </listitem>

      <listitem>
        <para><command>shorewall show &#60;chain1&#62; [ &#60;chain2&#62; ...
        ]</command> - produce a verbose report about the listed chains (<command>iptables
        -L chain -n -v</command>) Note: You may only list one chain in the
        show command when running Shorewall version 1.4.6 and earlier. Version
        1.4.7 and later allow you to list multiple chains in one command.</para>
      </listitem>

      <listitem>
        <para><command>shorewall show nat</command> - produce a verbose report
        about the nat table (<command>iptables -t nat -L -n -v</command>)</para>
      </listitem>

      <listitem>
        <para><command>shorewall show tos</command> - produce a verbose report
        about the mangle table (<command>iptables -t mangle -L -n -v</command>)</para>
      </listitem>

      <listitem>
        <para><command>shorewall show log</command> - display the last 20
        packet log entries.</para>
      </listitem>

      <listitem>
        <para><command>shorewall show connections</command> - displays the IP
        connections currently being tracked by the firewall.</para>
      </listitem>

      <listitem>
        <para><command>shorewall show tc</command> - displays information
        about the traffic control/shaping configuration.</para>
      </listitem>

      <listitem>
        <para><command>shorewall monitor [ &#60;delay&#62; ]</command> -
        Continuously display the firewall status, last 20 log entries and nat.
        When the log entry display changes, an audible alarm is sounded. The
        <emphasis>&#60;delay&#62;</emphasis> indicates the number of seconds
        between updates with the default being 10 seconds.</para>
      </listitem>

      <listitem>
        <para><command>shorewall hits</command> - Produces several reports
        about the Shorewall packet log messages in the current log file named
        in the LOGFILE variable in <filename>/etc/shorewall/shorewall.conf</filename>.</para>
      </listitem>

      <listitem>
        <para><command>shorewall version</command> - Displays the installed
        version number.</para>
      </listitem>

      <listitem>
        <para><command>shorewall check</command> - Performs a cursory
        validation of the zones, interfaces, hosts, rules and policy files.<caution><para>The
        <quote><command>check</command></quote> command is totally unsuppored
        and does not parse and validate the generated iptables commands. Even
        though the <quote>check</quote> command completes successfully, the
        configuration may fail to start. Problem reports that complain about
        errors that the <quote>check</quote> command does not detect will not
        be accepted.</para><para>See the recommended way to make configuration
        changes described below.</para></caution></para>
      </listitem>

      <listitem>
        <para><command>shorewall try &#60;<errortype>configuration-directory</errortype>&#62;
        [ &#60;timeout&#62; ]</command> - Restart shorewall using the
        specified configuration and if an error occurs or if the
        <emphasis>&#60;timeout&#62;</emphasis> option is given and the new
        configuration has been up for that many seconds then shorewall is
        restarted using the standard configuration.</para>
      </listitem>

      <listitem>
        <para><command>shorewall logwatch</command> (added in version 1.3.2) -
        Monitors the LOGFILE and produces an audible alarm when new Shorewall
        messages are logged.</para>
      </listitem>
    </itemizedlist>

    <para>Beginning with Shorewall 1.4.6, /sbin/shorewall supports a couple of
    commands for dealing with IP addresses and IP address ranges:</para>

    <itemizedlist>
      <listitem>
        <para><command>shorewall ipcalc [ &#60;address&#62; &#60;mask&#62; |
        &#60;address&#62;/&#60;vlsm&#62; ] </command>- displays the network
        address, broadcast address, network in CIDR notation and netmask
        corresponding to the input[s].</para>
      </listitem>

      <listitem>
        <para><command>shorewall iprange &#60;address1&#62;-&#60;address2&#62;</command>
        - Decomposes the specified range of IP addresses into the equivalent
        list of network/host addresses</para>
      </listitem>
    </itemizedlist>

    <para>There is a set of commands dealing with <ulink
    url="blacklisting_support.htm">dynamic blacklisting</ulink>:</para>

    <itemizedlist>
      <listitem>
        <para><command>shorewall drop &#60;ip address list&#62;</command> -
        causes packets from the listed IP addresses to be silently dropped by
        the firewall.</para>
      </listitem>

      <listitem>
        <para><command>shorewall reject &#60;ip address list&#62;</command> -
        causes packets from the listed IP addresses to be rejected by the
        firewall.</para>
      </listitem>

      <listitem>
        <para><command>shorewall allow &#60;ip address list&#62;</command> -
        re-enables receipt of packets from hosts previously blacklisted by a
        drop or reject command.</para>
      </listitem>

      <listitem>
        <para><command>shorewall save</command> - save the dynamic
        blacklisting configuration so that it will be automatically restored
        the next time that the firewall is restarted.</para>
      </listitem>

      <listitem>
        <para><command>show dynamic</command> - displays the dynamic
        blacklisting chain.</para>
      </listitem>
    </itemizedlist>

    <para>Finally, the <quote><quote>shorewall</quote></quote> program may be
    used to dynamically alter the contents of a zone.</para>

    <itemizedlist>
      <listitem>
        <para><command>shorewall add &#60;interface&#62;[:&#60;host&#62;]
        &#60;zone&#62;</command> - Adds the specified interface (and host if
        included) to the specified zone.</para>
      </listitem>

      <listitem>
        <para><command>shorewall delete &#60;interface&#62;[:&#60;host&#62;]
        &#60;zone&#62;</command> - Deletes the specified interface (and host
        if included) from the specified zone.</para>

        <para>Examples:<programlisting>     <command>shorewall add ipsec0:192.0.2.24 vpn1</command> -- adds the address 192.0.2.24 from interface ipsec0 to the zone vpn1
     <command>shorewall delete ipsec0:192.0.2.24 vpn1</command> -- deletes the address 192.0.2.24 from interface ipsec0 from zone vpn1</programlisting></para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Alternate Configurations</title>

    <para>The <command>shorewall start</command>, <command>shorewall restart</command>,
    <command>shorewall check</command>, and <command>shorewall try </command>commands
    allow you to specify which Shorewall configuration to use:</para>

    <programlisting>     <command>shorewall [ -c &#60;configuration-directory&#62; ] {start|restart|check}</command>
     <command>shorewall try &#60;configuration-directory&#62;</command></programlisting>

    <para>If a <emphasis>&#60;configuration-directory</emphasis>&#62; is
    specified, each time that Shorewall is going to use a file in <filename
    class="directory">/etc/shorewall</filename> it will first look in the<emphasis>
    &#60;configuration-directory&#62;</emphasis> . If the file is present in
    the <emphasis>&#60;configuration-directory&#62;,</emphasis> that file will
    be used; otherwise, the file in <filename class="directory">/etc/shorewall</filename>
    will be used. When changing the configuration of a production firewall, I
    recommend the following:</para>

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

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

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

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

      <listitem>
        <para>&#60;correct any errors found by check and check again&#62;</para>
      </listitem>

      <listitem>
        <para><command>/sbin/shorewall try ./</command></para>
      </listitem>
    </itemizedlist>

    <para>If the configuration starts but doesn&#39;t work, just
    <quote>shorewall restart</quote> to restore the old configuration. If the
    new configuration fails to start, the <quote>try</quote> command will
    automatically start the old one for you.</para>

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

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

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

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

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

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

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

    <para>You will note that the commands that result in state transitions use
    the word <quote>firewall</quote> rather than <quote>shorewall</quote>.
    That is because the actual transitions are done by <command>/usr/share/shorewall/firewall</command>;
    <command>/sbin/shorewall</command> runs <quote>firewall</quote> according
    to the following table:</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. For Shorewall versions
            beginning with 1.4.7, 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 &#60;new configuration&#62; restart If
            unsuccessful then firewall start (standard configuration) If
            timeout then firewall restart (standard configuration)</entry>

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

  <appendix>
    <title>Revision History</title>

    <para><revhistory><revision><revnumber>1.3-1.8</revnumber><date>2004-01-04</date><authorinitials>TE</authorinitials><revremark>Docbook
    standards</revremark></revision><revision><revnumber>1.2</revnumber><date>2003-12-31</date><authorinitials>TE</authorinitials><revremark>Added
    clarification about &#34;Started State&#34;</revremark></revision><revision><revnumber>1.1</revnumber><date>2003-12-29</date><authorinitials>TE</authorinitials><revremark>Initial
    Docbook conversion</revremark></revision></revhistory></para>
  </appendix>
</article>