<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry>
  <refmeta>
    <refentrytitle>shorewall-blacklist</refentrytitle>

    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>blacklist</refname>

    <refpurpose>Shorewall Blacklist file</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>/etc/shorewall/blacklist</command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The blacklist file is used to perform static blacklisting by source
    address (IP or MAC), or by application. The use of this file is deprecated
    and beginning with Shorewall 4.5.7, the file is no longer
    installed.</para>

    <para>The columns in the file are as follows (where the column name is
    followed by a different name in parentheses, the different name is used in
    the alternate specification syntax).</para>

    <variablelist>
      <varlistentry>
        <term><emphasis role="bold">ADDRESS/SUBNET</emphasis> (networks) -
        {<emphasis role="bold">-</emphasis>|<emphasis
        role="bold">~</emphasis><emphasis>mac-address</emphasis>|<emphasis>ip-address</emphasis>|<emphasis>address-range</emphasis>|<emphasis
        role="bold">+</emphasis><emphasis>ipset</emphasis>}</term>

        <listitem>
          <para>Host address, network address, MAC address, IP address range
          (if your kernel and iptables contain iprange match support) or ipset
          name prefaced by "+" (if your kernel supports ipset match).
          Exclusion (<ulink
          url="shorewall-exclusion.html">shorewall-exclusion</ulink>(5)) is
          supported.</para>

          <para>MAC addresses must be prefixed with "~" and use "-" as a
          separator.</para>

          <para>Example: ~00-A0-C9-15-39-78</para>

          <para>A dash ("-") in this column means that any source address will
          match. This is useful if you want to blacklist a particular
          application using entries in the PROTOCOL and PORTS columns.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">PROTOCOL</emphasis> (proto) - {<emphasis
        role="bold">-</emphasis>|[!]<emphasis>protocol-number</emphasis>|[!]<emphasis>protocol-name</emphasis>}</term>

        <listitem>
          <para>Optional - If specified, must be a protocol number or a
          protocol name from protocols(5).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">PORTS</emphasis> - {<emphasis
        role="bold">-</emphasis>|[!]<emphasis>port-name-or-number</emphasis>[,<emphasis>port-name-or-number</emphasis>]...}</term>

        <listitem>
          <para>Optional - may only be specified if the protocol is TCP (6) or
          UDP (17). A comma-separated list of destination port numbers or
          service names from services(5).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OPTIONS - {-|{dst|src|whitelist|audit}[,...]}</term>

        <listitem>
          <para>Optional - added in 4.4.12. If specified, indicates whether
          traffic <emphasis>from</emphasis> ADDRESS/SUBNET (<emphasis
          role="bold">src</emphasis>) or traffic <emphasis>to</emphasis>
          ADDRESS/SUBNET (<emphasis role="bold">dst</emphasis>) should be
          blacklisted. The default is <emphasis role="bold">src</emphasis>. If
          the ADDRESS/SUBNET column is empty, then this column has no effect
          on the generated rule.</para>

          <note>
            <para>In Shorewall 4.4.12, the keywords from and to were used in
            place of src and dst respectively. Blacklisting was still
            restricted to traffic <emphasis>arriving</emphasis> on an
            interface that has the 'blacklist' option set. So to block traffic
            from your local network to an internet host, you had to specify
            <option>blacklist</option> on your internal interface in <ulink
            url="shorewall-interfaces.html">shorewall-interfaces</ulink>
            (5).</para>
          </note>

          <note>
            <para>Beginning with Shorewall 4.4.13, entries are applied based
            on the <emphasis role="bold">blacklist</emphasis> setting in
            <ulink
            url="shorewall-zones.html">shorewall-zones</ulink>(5):</para>

            <orderedlist>
              <listitem>
                <para>'blacklist' in the OPTIONS or IN_OPTIONS column. Traffic
                from this zone is passed against the entries in this file that
                have the <emphasis role="bold">src</emphasis> option
                (specified or defaulted).</para>
              </listitem>

              <listitem>
                <para>'blacklist' in the OPTIONS or OUT_OPTIONS column.
                Traffic to this zone is passed against the entries in this
                file that have the <emphasis role="bold">dst</emphasis>
                option.</para>
              </listitem>
            </orderedlist>
          </note>

          <para>In Shorewall 4.4.20, the <emphasis
          role="bold">whitelist</emphasis> option was added. When <emphasis
          role="bold">whitelist</emphasis> is specified, packets/connections
          that match the entry are not matched against the remaining entries
          in the file.</para>

          <para>The <emphasis role="bold">audit</emphasis> option was also
          added in 4.4.20 and causes packets matching the entry to be audited.
          The <emphasis role="bold">audit</emphasis> option may not be
          specified in whitelist entries and require AUDIT_TARGET support in
          the kernel and iptables.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para></para>
  </refsect1>

  <refsect1>
    <title>Example</title>

    <variablelist>
      <varlistentry>
        <term>Example 1:</term>

        <listitem>
          <para>To block DNS queries from address 192.0.2.126:</para>

          <programlisting>        #ADDRESS/SUBNET         PROTOCOL        PORT
        192.0.2.126             udp             53</programlisting>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Example 2:</term>

        <listitem>
          <para>To block some of the nuisance applications:</para>

          <programlisting>        #ADDRESS/SUBNET         PROTOCOL        PORT
        -                       udp             1024:1033,1434
        -                       tcp             57,1433,1434,2401,2745,3127,3306,3410,4899,5554,6101,8081,9898</programlisting>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>FILES</title>

    <para>/etc/shorewall/blacklist</para>
  </refsect1>

  <refsect1>
    <title>See ALSO</title>

    <para><ulink
    url="http://shorewall.net/blacklisting_support.htm">http://shorewall.net/blacklisting_support.htm</ulink></para>

    <para><ulink
    url="http://shorewall.net/configuration_file_basics.htm#Pairs">http://shorewall.net/configuration_file_basics.htm#Pairs</ulink></para>

    <para>shorewall(8), shorewall-accounting(5), shorewall-actions(5),
    shorewall-hosts(5), shorewall_interfaces(5), shorewall-ipsets(5),
    shorewall-maclist(5), shorewall-masq(5), shorewall-nat(5),
    shorewall-netmap(5), shorewall-params(5), shorewall-policy(5),
    shorewall-providers(5), shorewall-proxyarp(5), shorewall-rtrules(5),
    shorewall-routestopped(5), shorewall-rules(5), shorewall.conf(5),
    shorewall-secmarks(5), shorewall-tcclasses(5), shorewall-tcdevices(5),
    shorewall-tcrules(5), shorewall-tos(5), shorewall-tunnels(5),
    shorewall-zones(5)</para>
  </refsect1>
</refentry>
