<!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-interface">

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

<refnamediv>
<refdescriptor>sanewall-interface</refdescriptor>
<refname>sanewall-interface</refname>
<refpurpose>create an interface definition</refpurpose>
</refnamediv>

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

<refsect1><title>Description</title>
  <para>
    An <command>interface</command> definition creates a firewall for
    protecting the host on which the firewall is running.
  </para>
  <para>
    The default policy is DROP, so that if no subcommands are given,
    the firewall will just drop all incoming and outgoing traffic using
    this interface.
  </para>
  <para>
    The behaviour of the defined interface is controlled by adding subcommands
    (listed in <xref linkend="if-see-also"/>).
  </para>
  <note><para>
    Forwarded traffic is never matched by the <command>interface</command>
    rules, even if it was originally destined for the firewall but was
    redirected using NAT. Any traffic to be passed through the firewall
    for whatever reason must be in a <command>router</command> (see
    <xref linkend="def-router"/>).
  </para></note>
</refsect1>

<refsect1><title>Parameters</title>
  <variablelist>
    <varlistentry><term><replaceable>real-interface</replaceable></term>
      <listitem>
        <para>
          This is the interface name as shown by
          <userinput>ip link show</userinput>.
          Generally anything <command>iptables</command> accepts
          is valid.
        </para>
        <para>
          The + (plus sign) after some text will match all interfaces
          that start with this text.
        </para>
        <para>
          Multiple interfaces may be specified by enclosing them within
          quotes, delimited by spaces for example:
          <programlisting>
interface "eth0 eth1 ppp0" myname
          </programlisting>
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term><replaceable>name</replaceable></term>
      <listitem>
        <para>
          This is a name for this interface. 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 interface.
        </para>
        <para>
          See <xref linkend="rule-params"/> for information on the
          parameters that can be used. Some examples:
          <programlisting>
interface eth0 intranet src 192.0.2.0/24

interface eth0 internet src not "${UNROUTABLE_IPS}"
          </programlisting>
          See <xref linkend="sanewall.conf"/> for an explanation
          of <envar>${UNROUTABLE_IPS}</envar>.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1 id="if-see-also"><title>See Also</title>
  <simplelist type="vert">
    <member><xref linkend="sanewall"/></member>
    <member><xref linkend="sanewall.conf"/></member>
    <member><xref linkend="def-router"/></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>
  </simplelist>
</refsect1>

</refentry>
