shorewall_code/Shorewall6/manpages/shorewall6-interfaces.xml

<?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>shorewall6-interfaces</refentrytitle>

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

  <refnamediv>
    <refname>interfaces</refname>

    <refpurpose>shorewall6 interfaces file</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>/etc/shorewall6/interfaces</command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>The interfaces file serves to define the firewall's network
    interfaces to shorewall6. The order of entries in this file is not
    significant in determining zone composition.</para>

    <para>Beginning with Shorewall 4.5.3, the interfaces file supports two
    different formats:</para>

    <variablelist>
      <varlistentry>
        <term>FORMAT 1 (default - deprecated)</term>

        <listitem>
          <para>There is a ANYCAST column which provides compatibility with
          older versions of Shorewall..</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FORMAT 2</term>

        <listitem>
          <para>The BROADCAST column is omitted.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The format is specified by a line as follows:</para>

    <blockquote>
      <para><emphasis role="bold">FORMAT {1|2}</emphasis></para>
    </blockquote>

    <para>The columns in the file are as follows.</para>

    <variablelist>
      <varlistentry>
        <term><emphasis role="bold">ZONE</emphasis> -
        <emphasis>zone-name</emphasis></term>

        <listitem>
          <para>Zone for this interface. Must match the name of a zone
          declared in /etc/shorewall6/zones. You may not list the firewall
          zone in this column.</para>

          <para>If the interface serves multiple zones that will be defined in
          the <ulink url="shorewall6-hosts.html">shorewall6-hosts</ulink>(5)
          file, you should place "-" in this column.</para>

          <para>If there are multiple interfaces to the same zone, you must
          list them in separate entries.</para>

          <para>Example:</para>

          <blockquote>
            <programlisting>#ZONE   INTERFACE       BROADCAST
loc     eth1            -
loc     eth2            -</programlisting>
          </blockquote>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">INTERFACE</emphasis> -
        <emphasis>interface</emphasis><emphasis
        role="bold">[:</emphasis><emphasis>port</emphasis><emphasis
        role="bold">]</emphasis></term>

        <listitem>
          <para>Logical name of interface. Each interface may be listed only
          once in this file. You may NOT specify the name of a "virtual"
          interface (e.g., eth0:0) here; see <ulink
          url="http://www.shorewall.net/FAQ.htm#faq18">http://www.shorewall.net/FAQ.htm#faq18</ulink>.
          If the <option>physical</option> option is not specified, then the
          logical name is also the name of the actual interface.</para>

          <para>You may use wildcards here by specifying a prefix followed by
          the plus sign ("+"). For example, if you want to make an entry that
          applies to all PPP interfaces, use 'ppp+'; that would match ppp0,
          ppp1, ppp2, …Please note that the '+' means '<emphasis
          role="bold">one</emphasis> or more additional characters' so 'ppp'
          does not match 'ppp+'.</para>

          <para>Care must be exercised when using wildcards where there is
          another zone that uses a matching specific interface. See <ulink
          url="shorewall6-nesting.html">shorewall6-nesting</ulink>(5) for a
          discussion of this problem.</para>

          <para>Shorewall6 allows '+' as an interface name.</para>

          <para>There is no need to define the loopback interface (lo) in this
          file.</para>

          <para>If a <replaceable>port</replaceable> is given, then the
          <replaceable>interface</replaceable> must have been defined
          previously with the <option>bridge</option> option. The OPTIONS
          column must be empty when a <replaceable>port</replaceable> is
          given.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">ANYCAST</emphasis> - <emphasis
        role="bold">-</emphasis></term>

        <listitem>
          <para>Enter '<emphasis role="bold">-'</emphasis> in this column. It
          is here for compatibility between Shorewall6 and Shorewall and is
          omitted if FORMAT is 2.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">OPTIONS</emphasis> (Optional) -
        [<emphasis>option</emphasis>[<emphasis
        role="bold">,</emphasis><emphasis>option</emphasis>]...]</term>

        <listitem>
          <para>A comma-separated list of options from the following list. The
          order in which you list the options is not significant but the list
          should have no embedded white space.</para>

          <variablelist>
            <varlistentry>
              <term><emphasis role="bold">blacklist</emphasis></term>

              <listitem>
                <para>Check packets arriving on this interface against the
                <ulink
                url="shorewall6-blacklist.html">shorewall6-blacklist</ulink>(5)
                file.</para>

                <para>Beginning with Shorewall 4.4.13:</para>

                <itemizedlist>
                  <listitem>
                    <para>If a <replaceable>zone</replaceable> is given in the
                    ZONES column, then the behavior is as if <emphasis
                    role="bold">blacklist</emphasis> had been specified in the
                    IN_OPTIONS column of <ulink
                    url="shorewall6-zones.html">shorewall6-zones</ulink>(5).</para>
                  </listitem>

                  <listitem>
                    <para>Otherwise, the option is ignored with a
                    warning:</para>

                    <blockquote>
                      <para><emphasis role="bold">WARNING: The 'blacklist'
                      option is ignored on mult-zone
                      interfaces</emphasis></para>
                    </blockquote>
                  </listitem>
                </itemizedlist>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">bridge</emphasis></term>

              <listitem>
                <para>Designates the interface as a bridge. Beginning with
                Shorewall 4.4.7, setting this option also sets
                <option>routeback</option>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">dhcp</emphasis></term>

              <listitem>
                <para>Specify this option when any of the following are
                true:</para>

                <orderedlist spacing="compact">
                  <listitem>
                    <para>the interface gets its IP address via DHCP</para>
                  </listitem>

                  <listitem>
                    <para>the interface is used by a DHCP server running on
                    the firewall</para>
                  </listitem>

                  <listitem>
                    <para>the interface has a static IP but is on a LAN
                    segment with lots of DHCP clients.</para>
                  </listitem>

                  <listitem>
                    <para>the interface is a <ulink
                    url="../SimpleBridge.html">simple bridge</ulink> with a
                    DHCP server on one port and DHCP clients on another
                    port.</para>

                    <note>
                      <para>If you use <ulink
                      url="../bridge-Shorewall-perl.html">Shorewall-perl for
                      firewall/bridging</ulink>, then you need to include
                      DHCP-specific rules in <ulink
                      url="shorewall-rules.html">shorewall-rules</ulink>(8).
                      DHCP uses UDP ports 546 and 547.</para>
                    </note>
                  </listitem>
                </orderedlist>

                <para>This option allows DHCP datagrams to enter and leave the
                interface.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">forward</emphasis>[={0|1}]</term>

              <listitem>
                <para>Sets the /proc/sys/net/ipv6/conf/interface/forwarding
                option to the specified value. If no value is supplied, then 1
                is assumed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">ignore</emphasis></term>

              <listitem>
                <para>When specified, causes the generated script to ignore
                up/down events from Shorewall-init for this device.
                Additionally, the option exempts the interface from hairpin
                filtering.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">mss</emphasis>=<emphasis>number</emphasis></term>

              <listitem>
                <para>Causes forwarded TCP SYN packets entering or leaving on
                this interface to have their MSS field set to the specified
                <replaceable>number</replaceable>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">nets=(<emphasis>net</emphasis>[,...])</emphasis></term>

              <listitem>
                <para>Limit the zone named in the ZONE column to only the
                listed networks. If you specify this option, be sure to
                include the link-local network (ff80::/10).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">nets=dynamic</emphasis></term>

              <listitem>
                <para>Added in Shorewall 4.4.21. Defines the zone as
                <firstterm>dynamic</firstterm>. Requires ipset match support
                in your iptables and kernel. See <ulink
                url="http://www.shorewall.net/Dynamic.html">http://www.shorewall.net/Dynamic.html</ulink>
                for further information.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">optional</emphasis></term>

              <listitem>
                <para>When <option>optional</option> is specified for an
                interface, shorewall6 will be silent when:</para>

                <itemizedlist>
                  <listitem>
                    <para>a <filename
                    class="directory">/proc/sys/net/ipv6/conf/</filename>
                    entry for the interface cannot be modified.</para>
                  </listitem>

                  <listitem>
                    <para>The first global IPv6 address of the interface
                    cannot be obtained.</para>
                  </listitem>
                </itemizedlist>

                <para>This option may not be specified together with <emphasis
                role="bold">required</emphasis>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">physical</emphasis>=<emphasis
              role="bold"><emphasis>name</emphasis></emphasis></term>

              <listitem>
                <para>Added in Shorewall 4.4.4. When specified, the interface
                or port name in the INTERFACE column is a logical name that
                refers to the name given in this option. It is useful when you
                want to specify the same wildcard port name on two or more
                bridges. See <ulink
                url="http://www.shorewall.net/bridge-Shorewall-perl.html#Multiple">http://www.shorewall.net/bridge-Shorewall-perl.html#Multiple</ulink>.</para>

                <para>If the <emphasis>interface</emphasis> name is a wildcard
                name (ends with '+'), then the physical
                <emphasis>name</emphasis> must also end in '+'.</para>

                <para>If <option>physical</option> is not specified, then it's
                value defaults to the <emphasis>interface</emphasis>
                name.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">required</emphasis></term>

              <listitem>
                <para>Added in Shorewall 4.4.10. When specified, the firewall
                will fail to start if the interface named in the INTERFACE
                column is not usable. May not be specified together with
                <emphasis role="bold">optional</emphasis>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">routeback</emphasis></term>

              <listitem>
                <para>If specified, indicates that shorewall6 should include
                rules that allow traffic arriving on this interface to be
                routed back out that same interface. This option is also
                required when you have used a wildcard in the INTERFACE column
                if you want to allow traffic between the interfaces that match
                the wildcard.</para>

                <para>Beginning with Shorewall 4.4.20, if you specify this
                option, then you should also specify <option>sfilter</option>
                (see below).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">sourceroute[={0|1}]</emphasis></term>

              <listitem>
                <para>If this option is not specified for an interface, then
                source-routed packets will not be accepted from that interface
                (sets
                /proc/sys/net/ipv6/conf/<emphasis>interface</emphasis>/accept_source_route
                to 1). Only set this option if you know what you are doing.
                This might represent a security risk and is not usually
                needed.</para>

                <para>Only those interfaces with the
                <option>sourceroute</option> option will have their setting
                changes; the value assigned to the setting will be the value
                specified (if any) or 1 if no value is given.</para>

                <note>
                  <para>This option does not work with a wild-card
                  <replaceable>interface</replaceable> name (e.g., eth0.+) in
                  the INTERFACE column.</para>
                </note>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sfilter=(<emphasis>net</emphasis>[,...])</term>

              <listitem>
                <para>Added in Shorewall 4.4.20. At this writing (spring
                2011), Linux does not support reverse path filtering (RFC3704)
                for IPv6. In its absence, <option>sfilter</option> may be used
                as an anti-spoofing measure.</para>

                <para>This option should be used on bridges or other
                interfaces with the <option>routeback</option> option. On
                these interfaces, <option>sfilter</option> should list those
                local networks that are connected to the firewall through
                other interfaces.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">tcpflags</emphasis></term>

              <listitem>
                <para>Packets arriving on this interface are checked for
                certain illegal combinations of TCP flags. Packets found to
                have such a combination of flags are handled according to the
                setting of TCP_FLAGS_DISPOSITION after having been logged
                according to the setting of TCP_FLAGS_LOG_LEVEL.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">proxyndp</emphasis>[={0|1}]</term>

              <listitem>
                <para>Sets
                /proc/sys/net/ipv6/conf/<emphasis>interface</emphasis>/proxy_ndp.</para>

                <para><emphasis role="bold">Note</emphasis>: This option does
                not work with a wild-card <replaceable>interface</replaceable>
                name (e.g., eth0.+) in the INTERFACE column.</para>

                <para>Only those interfaces with the <option>proxyndp</option>
                option will have their setting changed; the value assigned to
                the setting will be the value specified (if any) or 1 if no
                value is given.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">wait</emphasis>=<emphasis>seconds</emphasis></term>

              <listitem>
                <para>Added in Shorewall 4.4.10. Causes the generated script
                to wait up to <emphasis>seconds</emphasis> seconds for the
                interface to become usable before applying the <emphasis
                role="bold">required</emphasis> or <emphasis
                role="bold">optional</emphasis> options.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Example</title>

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

        <listitem>
          <para>Suppose you have eth0 connected to a DSL modem and eth1
          connected to your local network You have a DMZ using eth2.</para>

          <para>Your entries for this setup would look like:</para>

          <programlisting>FORMAT 2
#ZONE   INTERFACE OPTIONS
net     eth0      -
loc     eth1      -
dmz     eth2      -</programlisting>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Example 4 (Shorewall 4.4.9 and later):</term>

        <listitem>
          <para>You have a bridge with no IP address and you want to allow
          traffic through the bridge.</para>

          <programlisting>FORMAT 2
#ZONE   INTERFACE        OPTIONS
-       br0              routeback</programlisting>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>FILES</title>

    <para>/etc/shorewall6/interfaces</para>
  </refsect1>

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

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

    <para>shorewall6(8), shorewall6-accounting(5), shorewall6-actions(5),
    shorewall6-blacklist(5), shorewall6-hosts(5), shorewall6-maclist(5),
    shoewall6-netmap(5),shorewall6-params(5), shorewall6-policy(5),
    shorewall6-providers(5), shorewall6-rtrules(5),
    shorewall6-routestopped(5), shorewall6-rules(5), shorewall6.conf(5),
    shorewall6-secmarks(5), shorewall6-tcclasses(5), shorewall6-tcdevices(5),
    shorewall6-tcrules(5), shorewall6-tos(5), shorewall6-tunnels(5),
    shorewall6-zones(5)</para>
  </refsect1>
</refentry>