shorewall_code/docs/Introduction.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="usefull_links">
  <!--$Id$-->

  <articleinfo>
    <title>Introduction</title>

    <author>
      <firstname>Tom</firstname>

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

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

    <copyright>
      <year>2003-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 type="" url="Copyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <section id="Intro">
    <title>Introduction</title>

    <para>The information in this document applies only to 4.x releases of
    Shorewall.</para>

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

      <itemizedlist>
        <listitem>
          <para><ulink url="http://www.netfilter.org">Netfilter</ulink> - the
          packet filter facility built into the 2.4 and later Linux
          kernels.</para>
        </listitem>

        <listitem>
          <para>ipchains - the packet filter facility built into the 2.2 Linux
          kernels. Also the name of the utility program used to configure and
          control that facility. Netfilter can be used in ipchains
          compatibility mode.</para>
        </listitem>

        <listitem>
          <para>iptables - the utility program used to configure and control
          Netfilter. The term <quote>iptables</quote> is often used to refer
          to the combination of iptables+Netfilter (with Netfilter not in
          ipchains compatibility mode).</para>
        </listitem>

        <listitem>
          <para>iptables-restore - a program included with iptables that
          allows for atomic installation of a set of Netfilter rules. This is
          a much more efficient way to install a ruleset than running the
          iptables utility once for each rule in the ruleset.</para>
        </listitem>

        <listitem>
          <para>ifconfig - An obsolete program included in the net-utils
          package. ifconfig was used to configure network interfaces.</para>
        </listitem>

        <listitem>
          <para>route - An obsolete program included in the net-utils package.
          route was used to configure routing.</para>
        </listitem>

        <listitem>
          <para>ip - A program included in the iproute2 package. ip replaces
          ifconfig and route in modern Linux systems.</para>
        </listitem>

        <listitem>
          <para>tc - A program included in the iproute2 package. tc is used to
          configure QOS/Traffic Shaping on Linux systems.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="Shorewall">
      <title>What is Shorewall?</title>

      <para>The Shoreline Firewall, more commonly known as
      <quote>Shorewall</quote>, is high-level tool for configuring Netfilter.
      You describe your firewall/gateway requirements using entries in a set
      of configuration files. Shorewall reads those configuration files and
      with the help of the iptables, iptables-restore, ip and tc utilities,
      Shorewall configures Netfilter and the Linux networking subsystem to
      match your requirements. Shorewall can be used on a dedicated firewall
      system, a multi-function gateway/router/server or on a standalone
      GNU/Linux system. Shorewall does not use Netfilter's ipchains
      compatibility mode and can thus take advantage of Netfilter's connection
      state tracking capabilities.</para>

      <para>Shorewall is not a daemon. Once Shorewall has configured the Linux
      networking subsystem, its job is complete and there is no
      <quote>Shorewall process</quote> left running in your system. The <ulink
      url="starting_and_stopping_shorewall.htm">/sbin/shorewall program can be
      used at any time to monitor the Netfilter firewall</ulink>.</para>

      <para>Shorewall is not the easiest to use of the available iptables
      configuration tools but I believe that it is the most flexible and
      powerful. So if you are looking for a simple point-and-click
      set-and-forget Linux firewall solution that requires a minimum of
      networking knowledge, I would encourage you to check out the following
      alternatives:</para>

      <itemizedlist>
        <listitem>
          <para><ulink
          url="http://www.m0n0.ch/wall/">http://www.m0n0.ch/wall/</ulink></para>
        </listitem>

        <listitem>
          <para><ulink
          url="http://www.fs-security.com/">http://www.fs-security.com/</ulink></para>
        </listitem>
      </itemizedlist>

      <para>If you are looking for a Linux firewall solution that can handle
      complex and fast changing network environments then Shorewall is a
      logical choice.</para>
    </section>
  </section>

  <section id="Concepts">
    <title>Shorewall Concepts</title>

    <para>The configuration files for Shorewall are contained in the directory
    <filename class="directory">/etc/shorewall</filename> -- for simple
    setups, you will only need to deal with a few of them.</para>

    <para>Shorewall views the network where it is running as being composed of
    a set of <firstterm>zones</firstterm>. In the <ulink
    url="three-interface.htm">three-interface sample configuration</ulink> for
    example, the following zone names are used:</para>

    <programlisting>#NAME                  DESCRIPTION
fw                     The firewall itself
net                    The Internet
loc                    Your Local Network
dmz                    Demilitarized Zone</programlisting>

    <para>Zones are declared and given a type in the <ulink
    url="manpages/shorewall-zones.html"><filename
    class="directory">/etc/shorewall/</filename><filename>zones</filename></ulink>
    file.Here is the <ulink url="manpages/shorewall-zones.html"><filename
    class="directory">/etc/shorewall/</filename><filename>zones</filename></ulink>
    file from the three-interface sample:</para>

    <programlisting>#ZONE   TYPE    OPTIONS                 IN                      OUT
#                                       OPTIONS                 OPTIONS
fw      firewall
net     ipv4
loc     ipv4
dmz     ipv4
#LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE</programlisting>

    <para>Note that Shorewall recognizes the firewall system as its own zone.
    The name of the zone designating the firewall itself (usually 'fw' as
    shown in the above file) is stored in the shell variable
    $<firstterm>FW</firstterm> which may be used throughout the Shorewall
    configuration to refer to the firewall zone.</para>

    <para>The simplest way to define the hosts in a zone is to associate the
    zone with a network interface using the <ulink
    url="manpages/shorewall-interfaces.html"><filename>/etc/shorewall/interfaces</filename></ulink>
    file. In the three-interface sample, the three zones are defined using
    that file as follows:</para>

    <programlisting>#ZONE      INTERFACE     BROADCAST     OPTIONS
net        eth0          detect        dhcp,routefilter,norfc1918
loc        eth1          detect
dmz        eth2          detect</programlisting>

    <para>The above file defines the <emphasis>net</emphasis> zone as all IPv4
    hosts interfacing to the firewall through eth0, the
    <emphasis>loc</emphasis> zone as all IPv4 hosts interfacing through eth1
    and the <emphasis>dmz</emphasis> as all IPv4 hosts interfacing through
    eth2. It is important to note that the composition of a zone is defined in
    terms of a combination of addresses <emphasis role="bold">and</emphasis>
    interfaces. When using the <ulink
    url="manpages/shorewall-interfaces.html"><filename>/etc/shorewall/interfaces</filename></ulink>
    file to define a zone, all addresses are included; when you want to define
    a zone that contains a limited subset of the IPv4 address space, you use
    the <ulink
    url="manpages/shorewall-hosts.html"><filename>/etc/shorewall/hosts</filename></ulink>
    file.</para>

    <para>Rules about what traffic to allow and what traffic to deny are
    expressed in terms of zones. <itemizedlist spacing="compact">
        <listitem>
          <para>You express your default policy for connections from one zone
          to another zone in the <ulink
          url="manpages/shorewall-policy.html"><filename
          class="directory">/etc/shorewall/</filename><filename>policy</filename></ulink>
          file. The basic choices for policy are:</para>

          <itemizedlist>
            <listitem>
              <para>ACCEPT - Accept the connection.</para>
            </listitem>

            <listitem>
              <para>DROP - Ignore the connection request.</para>
            </listitem>

            <listitem>
              <para>REJECT - Return an appropriate error to the connection
              request.</para>
            </listitem>
          </itemizedlist>

          <para>Connection request logging may be specified as part of a
          policy and it is conventional (and highly recommended) to log DROP
          and REJECT policies.</para>
        </listitem>

        <listitem>
          <para>You define exceptions to these default policies in the <ulink
          url="manpages/shorewall-rules.html"><filename
          class="directory">/etc/shorewall/</filename><filename>rules</filename></ulink>
          file.</para>
        </listitem>

        <listitem>
          <para>You only need concern yourself with connection requests. You
          don't need to define rules for handling traffic that is part of an
          established connection is and in most cases you don't have to worry
          about how related connections are handled (ICMP error packets and
          <ulink url="FTP.html">related TCP connection requests such as used
          by FTP</ulink>).</para>
        </listitem>
      </itemizedlist>For each connection request entering the firewall, the
    request is first checked against the <filename
    class="directory">/etc/shorewall/</filename><filename>rules</filename>
    file. If no rule in that file matches the connection request then the
    first policy in <filename
    class="directory">/etc/shorewall/</filename><filename>policy</filename>
    that matches the request is applied. If there is a default action defined
    for the policy in /etc/shorewall/actions (or
    <filename>/usr/share/shorewall/actions.std</filename>) then that action is
    invoked before the policy is enforced. In the standard Shorewall
    distribution, the DROP policy has a default action called <emphasis
    role="bold">Drop</emphasis> and the REJECT policy has a default action
    called <emphasis role="bold">Reject</emphasis>. Default actions are used
    primarily to discard packets silently so that they don't clutter up your
    log.</para>

    <para>The <filename
    class="directory">/etc/shorewall/</filename><filename>policy</filename>
    file included with the three-interface sample has the following policies:
    <programlisting>#SOURCE    DEST        POLICY      LOG LEVEL    LIMIT:BURST
loc        net         ACCEPT
net        all         DROP        info
all        all         REJECT      info</programlisting>In the three-interface
    sample, the line below is included but commented out. If you want your
    firewall system to have full access to servers on the internet, uncomment
    that line. <programlisting>#SOURCE    DEST        POLICY      LOG LEVEL    LIMIT:BURST
$FW        net         ACCEPT</programlisting> The above policy will:
    <itemizedlist>
        <listitem>
          <para>Allow all connection requests from your local network to the
          internet</para>
        </listitem>

        <listitem>
          <para>Drop (ignore) all connection requests from the internet to
          your firewall or local networks; these ignored connection requests
          will be logged using the <emphasis>info</emphasis> syslog priority
          (log level).</para>
        </listitem>

        <listitem>
          <para>Optionally accept all connection requests from the firewall to
          the internet (if you uncomment the additional policy)</para>
        </listitem>

        <listitem>
          <para>reject all other connection requests; these rejected
          connection requests will be logged using the
          <emphasis>info</emphasis> syslog priority (log level).</para>
        </listitem>
      </itemizedlist></para>

    <para>To illustrate how rules provide exceptions to policies, suppose that
    you have the polcies listed above but you want to be able to connect to
    your firewall from the internet using Secure Shell (SSH). Recall that SSH
    connects uses TCP port 22.</para>

    <programlisting>#ACTION    SOURCE        DEST      PROTO      DEST
#                                             PORT(S)
ACCEPT     net           $FW       tcp        22</programlisting>

    <para>So although you have a policy of ignoring all connection attempts
    from the net zone (from the internet), the above exception to that policy
    allows you to connect to the SSH server running on your firewall.</para>

    <para>Because Shorewall makes no assumptions about what traffic you want
    accepted, there are certain rules (exceptions) that need to be added to
    almost any configuration.</para>

    <itemizedlist>
      <listitem>
        <para>The <ulink url="shorewall_quickstart_guide.htm">QuickStart
        guildes</ulink> point to pre-populated files for use in common setups
        and the <ulink url="shorewall_setup_guide.htm">Shorewall Setup
        Guide</ulink> shows you examples for use with other more complex
        setups.</para>
      </listitem>

      <listitem>
        <para>To keep your <ulink url="shorewall_logging.html">firewall
        log</ulink> from filling up with useless noise, Shorewall provides
        <ulink url="Actions.html">common actions</ulink> that silently discard
        or reject such noise before it can be logged. As with everything in
        Shorewall, you can alter the behavior of these common actions (or do
        away with them entirely) as you see fit.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Compile">
    <title>Compile then Execute</title>

    <para>Shorewall versions beginning with 3.2.0 use a "compile" then
    "execute" approach. The Shorewall configuration compiler reads the
    configuration files and generates a shell script. Errors in the
    compilation step cause the script to be discarded and the command to be
    aborted. If the compilation step doesn't find any errors then the shell
    script is executed.</para>

    <para>The 'compiled' scripts are placed in the directory <filename
    class="directory">/var/lib/shorewall</filename> and are named to
    correspond to the command being executed. For example, the command
    "/sbin/shorewall start" will generate a script named
    <filename>/var/lib/shorewall/.start</filename> and, if the compilation is
    error free, that script will then be executed.</para>
  </section>

  <section id="Packages">
    <title>Shorewall Packages</title>

    <para>Shorewall 4.0 consists of four packages.</para>

    <orderedlist>
      <listitem>
        <para><emphasis role="bold">Shorewall-common</emphasis>. This package
        must be installed on at least one system in your network. That system
        must also have Shorewall-shell and/or Shorewall-perl installed.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall-shell</emphasis>. This package
        includes the legacy Shorewall configuration compiler written in Bourne
        Shell. This compiler is very portable but suffers from performance
        problems and has become hard to maintain.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall-perl</emphasis>. An alternative
        to Shorewall-shell written in the Perl language. This compiler is
        highly portable to those Unix-like platforms that support Perl
        (including Cygwin) and is the compiler of choice for new Shorewall
        installations. Scripts created using Shorewall-perl use
        iptables-restore to install the generated Netfilter ruleset.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall
        allows for central administration of multiple firewalls through use of
        Shorewall lite. The full Shorewall product (along with Shorewall-shell
        and/or Shorewall-perl) are installed on a central administrative
        system where compiled Shorewall scripts are generated. These scripts
        are copied to the firewall systems where they run under the control of
        Shorewall-lite.</para>
      </listitem>
    </orderedlist>
  </section>

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

    <para>This program is free software; you can redistribute it and/or modify
    it under the terms of <ulink
    url="http://www.gnu.org/licenses/gpl.html">Version 2 of the GNU General
    Public License</ulink> as published by the Free Software
    Foundation.</para>

    <para>This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
    for more detail.</para>

    <para>You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software Foundation,
    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.</para>
  </section>
</article>