<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- For license information see sanewall-manual-info.xml.in -->
<refentry id="def-router">

<refmeta>
<refentrytitle>router definition: sanewall-router</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>

<refnamediv>
<refdescriptor>sanewall-router</refdescriptor>
<refname>sanewall-router</refname>
<refpurpose>create a router definition</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>router</command>
    <arg choice="plain"><replaceable>name</replaceable></arg>
    <arg choice="opt"><replaceable>rule-params</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
  <para>
    A <command>router</command> definition consists of a set of rules for
    traffic passing through the host running the firewall.
  </para>
  <para>
    The default policy for router definitions is RETURN,
    meaning packets are not dropped by any particular router. Packets not
    matched by any router are dropped at the end of the firewall.
  </para>
  <para>
    The behaviour of the defined router is controlled by adding subcommands
    (listed in <xref linkend="rt-see-also"/>).
  </para>
</refsect1>

<refsect1><title>Parameters</title>
  <variablelist>
    <varlistentry><term><replaceable>name</replaceable></term>
      <listitem>
        <para>
          This is a name for this router. You should use short names
          (10 characters maximum) without spaces or other symbols.
        </para>
        <para>
          A name should be unique for all <application>Sanewall</application>
          interface and router definitions.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term><replaceable>rule-params</replaceable></term>
      <listitem>
        <para>
          The set of rule parameters to further restrict the
          traffic that is matched to this router.
        </para>
        <para>
          See <xref linkend="rule-params"/> for information on the
          parameters that can be used. Some examples:
          <programlisting>
router mylan inface ppp+ outface eth0 src not ${UNROUTABLE_IPS}

router myrouter
          </programlisting>
          See <xref linkend="sanewall.conf"/> for an explanation
          of <envar>${UNROUTABLE_IPS}</envar>.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1><title>Working with routers</title>
  <para>
    Routers create stateful <command>iptables</command> rules which
    match traffic in both directions.
  </para>

  <para>
    To match some client or server traffic, the input/output interface
    or source/destination of the request must be specified. All
    <option>inface</option>/<option>outface</option> and
    <option>src</option>/<option>dst</option>
    <xref linkend="rule-params"/> can be given on the router statement
    (in which case they will be applied to all subcommands for the router)
    or just within the subcommands of the router.
  </para>

  <para>
    For example,
    to define a router which matches requests from any PPP interface
    and destined for eth0, and on this allowing HTTP servers (on eth0) to
    be accessed by clients (from PPP) and SMTP clients (from eth0) to
    access any servers (on PPP):
    <programlisting>
router mylan inface ppp+ outface eth0
  server http accept
  client smtp accept
    </programlisting>
    <note><para>
       The <option>client</option> subcommand reverses any optional
       rule parameters passed to the <command>router</command>, in this
       case the inface and outface.
    </para></note>
  </para>

  <para>
    Equivalently, to define a router which matches all forwarded traffic
    and within the the router allow HTTP servers on eth0 to be accessible
    to PPP and any SMTP servers on PPP to be accessible from eth0:
    <programlisting>
router mylan
  server http accept inface ppp+ outface eth0
  server smtp accept inface eth0 outface ppp
    </programlisting>
    <note><para>
      In this instance two <option>server</option> subcommands are used
      since there are no parameters on the router to reverse. Avoid the
      use of the <option>client</option> subcommand in routers unless
      the inputs and outputs are defined as part of the router.
    </para></note>
  </para>

  <para>
    Any number of routers can be defined and the traffic they match can
    overlap. Since the default policy is RETURN, any traffic that is
    not matched by any rules in one will proceed to the next, in order,
    until none are left.
  </para>

</refsect1>

<refsect1 id="rt-see-also"><title>See Also</title>
  <simplelist type="vert">
    <member><xref linkend="sanewall"/></member>
    <member><xref linkend="sanewall.conf"/></member>
    <member><xref linkend="def-interface"/></member>
    <member><xref linkend="cmd-policy"/></member>
    <member><xref linkend="cmd-protection"/></member>
    <member><xref linkend="cmd-client"/></member>
    <member><xref linkend="cmd-server"/></member>
    <member><xref linkend="cmd-group"/></member>
    <member><xref linkend="helpcmd-iptables"/></member>
    <member><xref linkend="helpcmd-masquerade"/></member>
    <member><xref linkend="helpcmd-tcpmss"/></member>
  </simplelist>
</refsect1>

</refentry>
