shorewall_code/manpages/shorewall-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>shorewall-interfaces</refentrytitle>

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

  <refnamediv>
    <refname>interfaces</refname>

    <refpurpose>Shorewall interfaces file</refpurpose>
  </refnamediv>

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

  <refsect1>
    <title>Description</title>

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

    <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/shorewall/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="shorewall-hosts.html">shorewall-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>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></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, …</para>

          <para>When using Shorewall versions before 4.1.4, care must be
          exercised when using wildcards where there is another zone that uses
          a matching specific interface. See <ulink
          url="shorewall-nesting.html">shorewall-nesting</ulink>(5) for a
          discussion of this problem.</para>

          <para>Beginning with Shorewall 4.2.3, Shorewall-perl allows '+' as
          an interface name.</para>

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

          <para>(Shorewall-perl only) 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 may not contain the following options when a
          <replaceable>port</replaceable> is given.</para>

          <simplelist>
            <member>arp_filter</member>

            <member>arp_ignore</member>

            <member>bridge</member>

            <member>log_martians</member>

            <member>mss</member>

            <member>optional</member>

            <member>proxyarp</member>

            <member>routefilter</member>

            <member>sourceroute</member>

            <member>upnp</member>
          </simplelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">BROADCAST</emphasis> (Optional) -
        {<emphasis role="bold">-</emphasis>|<emphasis
        role="bold">detect</emphasis>|<emphasis>address</emphasis>[,<emphasis>address</emphasis>]...}</term>

        <listitem>
          <para>The broadcast address(es) for the network(s) to which the
          interface belongs. For P-T-P interfaces, this column is left blank.
          If the interface has multiple addresses on multiple subnets then
          list the broadcast addresses as a comma-separated list.</para>

          <para>If you use the special value <emphasis
          role="bold">detect</emphasis>, Shorewall will detect the broadcast
          address(es) for you. If you select this option, the interface must
          be up before the firewall is started.</para>

          <para>If you don't want to give a value for this column but you want
          to enter a value in the OPTIONS column, enter <emphasis
          role="bold">-</emphasis> in this column.</para>

          <para><emphasis role="bold">Note to Shorewall-perl users:</emphasis>
          Shorewall-perl only supports <option>detect</option> or <emphasis
          role="bold">-</emphasis> in this column. If you specify
          <replaceable>address</replaceable>es, a compilation warning will be
          issued.</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">arp_filter[={0|1}]</emphasis></term>

              <listitem>
                <para>If specified, this interface will only respond to ARP
                who-has requests for IP addresses configured on the interface.
                If not specified, the interface can respond to ARP who-has
                requests for IP addresses on any of the firewall's interface.
                The interface must be up when Shorewall is started.</para>

                <para>The option value (0 or 1) may only be specified if you
                are using Shorewall-perl. With Shorewall-perl, only those
                interfaces with the <option>arp_filter</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>

                <para></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><emphasis
              role="bold">arp_ignore</emphasis>[=<emphasis>number</emphasis>]</term>

              <listitem>
                <para>If specified, this interface will respond to arp
                requests based on the value of <emphasis>number</emphasis>
                (defaults to 1).</para>

                <para>1 - reply only if the target IP address is local address
                configured on the incoming interface</para>

                <para>2 - reply only if the target IP address is local address
                configured on the incoming interface and the sender's IP
                address is part from same subnet on this interface</para>

                <para>3 - do not reply for local addresses configured with
                scope host, only resolutions for global and link</para>

                <para>4-7 - reserved</para>

                <para>8 - do not reply for all local addresses</para>

                <para></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>

                <para></para>

                <warning>
                  <para>Do not specify <emphasis
                  role="bold">arp_ignore</emphasis> for any interface involved
                  in <ulink url="../ProxyARP.htm">Proxy ARP</ulink>.</para>
                </warning>
              </listitem>
            </varlistentry>

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

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

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

              <listitem>
                <para>(Shorewall-perl only) Designates the interface as a
                bridge.</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 67 and 68.</para>
                    </note>
                  </listitem>
                </orderedlist>

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

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

              <listitem>
                <para>Turn on kernel martian logging (logging of packets with
                impossible source addresses. It is strongly suggested that if
                you set <emphasis role="bold">routefilter</emphasis> on an
                interface that you also set <emphasis
                role="bold">logmartians</emphasis>. Even if you do not specify
                the <option>routefilter</option> option, it is a good idea to
                specify <option>logmartians</option> because your distribution
                may be enabling route filtering without you knowing it.</para>

                <para>The option value (0 or 1) may only be specified if you
                are using Shorewall-perl. With Shorewall-perl, only those
                interfaces with the <option>logmartians</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>

                <para>To find out if route filtering is set on a given
                <replaceable>interface</replaceable>, check the contents of
                <filename>/proc/sys/net/ipv4/conf/<replaceable>interface</replaceable>/rp_filter</filename>
                - a non-zero value indicates that route filtering is
                enabled.</para>

                <para>Example:</para>

                <programlisting>        teastep@lists:~$ <command>cat /proc/sys/net/ipv4/conf/eth0/rp_filter </command>
        1
        teastep@lists:~$ </programlisting>

                <para></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>

                <blockquote>
                  <para>This option may also be enabled globally in the <ulink
                  url="shorewall.conf.html">shorewall.conf</ulink>(5)
                  file.</para>
                </blockquote>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Connection requests from this interface are compared
                against the contents of <ulink
                url="shorewall-maclist.html">shorewall-maclist</ulink>(5). If
                this option is specified, the interface must be an ethernet
                NIC and must be up before Shorewall is started.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Added in Shorewall 4.0.3. 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">nosmurfs</emphasis></term>

              <listitem>
                <para>Filter packets for smurfs (packets with a broadcast
                address as the source).</para>

                <para>Smurfs will be optionally logged based on the setting of
                SMURF_LOG_LEVEL in <ulink
                url="shorewall.conf.html">shorewall.conf</ulink>(5). After
                logging, the packets are dropped.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Only supported by Shorewall-perl. When
                <option>optional</option> is specified for an interface,
                Shorewall will be silent when:</para>

                <itemizedlist>
                  <listitem>
                    <para>a <filename
                    class="directory">/proc/sys/net/ipv4/conf/</filename>
                    entry for the interface cannot be modified (including for
                    proxy ARP).</para>
                  </listitem>

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

                <para></para>

                <blockquote>
                  <para>I specify <option>optional</option> on interfaces to
                  Xen virtual machines that may or may not be running when
                  Shorewall is [re]started.</para>

                  <para></para>

                  <caution>
                    <para>Use <option>optional</option> at your own risk. If
                    you [re]start Shorewall when an 'optional' interface is
                    not available and then do a <command>shorewall
                    save</command>, subsequent <command>shorewall
                    restore</command> and <command>shorewall -f
                    start</command> operations will instantiate a ruleset that
                    does not support that interface, even if it is available
                    at the time of the restore/start.</para>
                  </caution>
                </blockquote>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Sets
                /proc/sys/net/ipv4/conf/<emphasis>interface</emphasis>/proxy_arp.
                Do NOT use this option if you are employing Proxy ARP through
                entries in <ulink
                url="shorewall-proxyarp.html">shorewall-proxyarp</ulink>(5).
                This option is intended solely for use with Proxy ARP
                sub-networking as described at: <ulink
                url="http://tldp.org/HOWTO/Proxy-ARP-Subnet/index.html">http://tldp.org/HOWTO/Proxy-ARP-Subnet/index.html.
                </ulink></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>The option value (0 or 1) may only be specified if you
                are using Shorewall-perl. With Shorewall-perl, only those
                interfaces with the <option>proxyarp</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">routeback</emphasis></term>

              <listitem>
                <para>If specified, indicates that Shorewall 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>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Turn on kernel route filtering for this interface
                (anti-spoofing measure).</para>

                <para>The option value (0 or 1) may only be specified if you
                are using Shorewall-perl. With Shorewall-perl, only those
                interfaces with the <option>routefilter</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>

                <para></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>

                <blockquote>
                  <para>This option can also be enabled globally in the <ulink
                  url="shorewall.conf.html">shorewall.conf</ulink>(5)
                  file.</para>
                </blockquote>
              </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/ipv4/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>The option value (0 or 1) may only be specified if you
                are using Shorewall-perl. With Shorewall-perl, 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>

                <para></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><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">upnp</emphasis></term>

              <listitem>
                <para>Incoming requests from this interface may be remapped
                via UPNP (upnpd). See <ulink
                url="../UPnP.html">http://www.shorewall.net/UPnP.html</ulink>.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>This option is intended for laptop users who always run
                Shorewall on their system yet need to run UPnP-enabled client
                apps such as Transmission (BitTorrent client). The option
                causes Shorewall to detect the default gateway through the
                interface and to accept UDP packets from that gateway. Note
                that, like all aspects of UPnP, this is a security hole so use
                this option at your own risk. </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 and that your local subnet is
          192.168.1.0/24. The interface gets it's IP address via DHCP from
          subnet 206.191.149.192/27. You have a DMZ with subnet 192.168.2.0/24
          using eth2.</para>

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

          <programlisting>#ZONE   INTERFACE BROADCAST        OPTIONS
net     eth0      206.191.149.223  dhcp
loc     eth1      192.168.1.255
dmz     eth2      192.168.2.255</programlisting>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>The same configuration without specifying broadcast addresses
          is:</para>

          <programlisting>#ZONE   INTERFACE BROADCAST        OPTIONS
net     eth0      detect           dhcp
loc     eth1      detect
dmz     eth2      detect</programlisting>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Example 3:</term>

        <listitem>
          <para>You have a simple dial-in system with no ethernet
          connections.</para>

          <programlisting>#ZONE   INTERFACE BROADCAST        OPTIONS
net     ppp0      -</programlisting>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>FILES</title>

    <para>/etc/shorewall/interfaces</para>
  </refsect1>

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

    <para>shorewall(8), shorewall-accounting(5), shorewall-actions(5),
    shorewall-blacklist(5), shorewall-hosts(5), shorewall-ipsec(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-route_rules(5),
    shorewall-routestopped(5), shorewall-rules(5), shorewall.conf(5),
    shorewall-tcclasses(5), shorewall-tcdevices(5), shorewall-tcrules(5),
    shorewall-tos(5), shorewall-tunnels(5), shorewall-zones(5)</para>
  </refsect1>
</refentry>