<!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="cmd-protection">

<refmeta>
<refentrytitle>protection command: sanewall-protection</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>

<refnamediv>
<refdescriptor>sanewall-protection</refdescriptor>
<refname>sanewall-protection</refname>
<refpurpose>add extra protections to a definition</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>protection</command>
    <arg choice="opt">reverse</arg>
    <arg choice="plain"><replaceable>flood-protection-type</replaceable></arg>
    <arg choice="opt">requests/period
      <arg choice="opt">burst</arg>
    </arg>
  </cmdsynopsis>

  <cmdsynopsis>
    <command>protection</command>
    <arg choice="opt">reverse</arg>
    <arg choice="plain">strong</arg>
    <arg choice="opt">requests/period
      <arg choice="opt">burst</arg>
    </arg>
  </cmdsynopsis>

  <cmdsynopsis>
    <command>protection</command>
    <arg choice="opt">reverse</arg>
    <arg choice="plain">
      <group choice="req">
        <arg choice="plain">bad-packets</arg>
        <arg choice="plain">
           <replaceable>packet-protection-type</replaceable>
        </arg>
      </group>
    </arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
  <para>
    The <command>protection</command> subcommand sets protection rules
    on an interface or router.
  </para>
  <para>
    Flood protections honour the options <option>requests/period</option>
    and <option>burst</option>. They are used to limit the rate of certain
    types of traffic.
  </para>
  <para>
    The default rate <application>Sanewall</application> uses is 100
    operations per second with a burst of 50.
    Run <userinput>iptables -m limit --help</userinput> for more information.
  </para>
  <para>
    The protection type <option>strong</option> will switch on
    all protections (both packet and flood protections) except
    <option>all-floods</option>. It has aliases
    <option>full</option> and <option>all</option>.
  </para>
  <para>
    The protection type <option>bad-packets</option> will switch on
    all packet protections but not flood protections.
  </para>
  <para>
    You can specify multiple protection types by using multiple
    <command>protection</command> commands or in a single command
    by enclosing the types in quotes.
  </para>
  <note>
    <para>
      On a router, protections are normally set up
      on <replaceable>inface</replaceable>.
    </para>
    <para>
       The <option>reverse</option> option will set up the protections
       on <replaceable>outface</replaceable>. You must use it as the
       first keyword.
    </para>
  </note>
</refsect1>

<refsect1><title>Packet protection types</title>
  <variablelist>
    <varlistentry><term>invalid</term>
      <listitem>
        <para>
          Drops all incoming invalid packets, as detected INVALID by
          the connection tracker.
        </para>
        <para>
          See also <envar>SANEWALL_DROP_INVALID</envar> in
          <xref linkend="sanewall-variables"/> which allows setting
          this function globally.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>fragments</term>
      <listitem>
        <para>
          Drops all packet fragments.
        </para>
        <para>
          This rule will probably never match anything since
          <command>iptables(8)</command> reconstructs all packets
          automatically before the firewall rules are processed whenever
          connection tracking is running.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>new-tcp-w/o-syn</term>
      <listitem>
        <para>
          Drops all TCP packets that initiate a socket but have not
          got the SYN flag set.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>malformed-xmas</term>
      <listitem>
        <para>
          Drops all TCP packets that have all TCP flags set.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>malformed-null</term>
      <listitem>
        <para>
          Drops all TCP packets that have all TCP flags unset.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>malformed-bad</term>
      <listitem>
        <para>
          Drops all TCP packets that have illegal combinations of TCP flags set.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1><title>Flood protection types</title>
  <variablelist>
    <varlistentry><term>icmp-floods [requests/period [burst]]</term>
      <listitem>
        <para>
          Allows only a certain amount of ICMP echo requests.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>syn-floods [requests/period [burst]]</term>
      <listitem>
        <para>
          Allows only a certain amount of new TCP connections.
        </para>
        <para>
          Be careful to not set the rate too low as the rule is
          applied to all connections regardless of their final result
          (rejected, dropped, established, etc).
        </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>all-floods [requests/period [burst]]</term>
      <listitem>
        <para>
          Allows only a certain amount of new connections.
        </para>
        <para>
          Be careful to not set the rate too low as the rule is
          applied to all connections regardless of their final result
          (rejected, dropped, established, etc).
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1><title>Examples</title>
  <programlisting>
protection strong

protection "invalid new-tcp-w/o-syn"

protection syn-floods 90/sec 40
  </programlisting>
</refsect1>

<refsect1><title>Bugs</title>
  <para>
    When using multiple types in a single command, if the quotes are
    forgotten, incorrect rules will be generated without warning.
  </para>

  <para>
    When using multiple types in a single command,
    <application>Sanewall</application> will silently ignore any types that
    come after a group type (<option>bad-packets</option>,
    <option>strong</option> and its aliases). Only use group types on
    their own line.
  </para>
</refsect1>

<refsect1><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="def-router"/></member>
  </simplelist>
</refsect1>

</refentry>
