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>2003-12-12</pubdate>

    <copyright>
      <year>2001-2003</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. Once you have
    installed <quote>firewall</quote> in your init.d directory, simply type
    <quote>chkconfig --add firewall</quote>. This will 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 the
    <quote>--level</quote> option in chkconfig (see <quote>man chkconfig</quote>)
    or using your favorite graphical 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 /etc/shorewall/startup_disabled. Note: Users of the .deb
          package must edit /etc/default/shorewall and set <quote>startup=1</quote>.</para>
        </listitem>

        <listitem>
          <para>If you use dialup, you may want to start the firewall in your
          /etc/ppp/ip-up.local script. I recommend just placing
          <quote>shorewall restart</quote> in that script.</para>
        </listitem>
      </itemizedlist>
    </caution>

    <para>You can manually start and stop Shoreline Firewall using the
    <quote>shorewall</quote> shell program. Please refer to the Shorewall
    State Diagram as shown at the bottom of this page.</para>

    <itemizedlist>
      <listitem>
        <para>shorewall start - starts the firewall</para>
      </listitem>

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

      <listitem>
        <para>shorewall restart - stops the firewall (if it&#39;s running) and
        then starts it again</para>
      </listitem>

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

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

      <listitem>
        <para>shorewall refresh - 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>     shorewall debug start 2&#62; /tmp/trace</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>     shorewall help [ command | host | address ]</programlisting>The
    <quote>shorewall</quote> program may also be used to monitor the firewall.</para>

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

      <listitem>
        <para>shorewall show chain1 [ chain2 ... ] - produce a verbose report
        about the listed chains (iptables -L chain -n -v) 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>shorewall show nat - produce a verbose report about the nat
        table (iptables -t nat -L -n -v)</para>
      </listitem>

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

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

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

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

      <listitem>
        <para>shorewall monitor [ delay ] - Continuously display the firewall
        status, last 20 log entries and nat. When the log entry display
        changes, an audible alarm is sounded.</para>
      </listitem>

      <listitem>
        <para>shorewall hits - Produces several reports about the Shorewall
        packet log messages in the current /var/log/messages file.</para>
      </listitem>

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

      <listitem>
        <para>shorewall check - Performs a cursory validation of the zones,
        interfaces, hosts, rules and policy files.<caution><para>The
        <quote>check</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>shorewall try configuration-directory [ timeout ] - Restart
        shorewall using the specified configuration and if an error occurs or
        if the timeout 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>shorewall logwatch (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>shorewall ipcalc [ address mask | address/vlsm ] - displays the
        network address, broadcast address, network in CIDR notation and
        netmask corresponding to the input[s].</para>
      </listitem>

      <listitem>
        <para>shorewall iprange address1-address2 - 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>shorewall drop &#60;ip address list&#62; - causes packets from
        the listed IP addresses to be silently dropped by the firewall.</para>
      </listitem>

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

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

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

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

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

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

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

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

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

    <programlisting>     shorewall [ -c configuration-directory ] {start|restart|check}
     shorewall try configuration-directory</programlisting>

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

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

      <listitem>
        <para>cd /etc/test</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>shorewall -c . check</para>
      </listitem>

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

      <listitem>
        <para>/sbin/shorewall try .</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>cp * /etc/shorewall</para>
      </listitem>

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

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

    <para>The Shorewall State Diargram is depicted below.<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
    /usr/share/shorewall/firewall; /sbin/shorewall 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>
</article>