shorewall_code/Shorewall/manpages/shorewall-providers.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-providers</refentrytitle>

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

  <refnamediv>
    <refname>providers</refname>

    <refpurpose>Shorewall Providers file</refpurpose>
  </refnamediv>

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

  <refsect1>
    <title>Description</title>

    <para>This file is used to define additional routing tables. You will want
    to define an additional table if:</para>

    <itemizedlist>
      <listitem>
        <para>You have connections to more than one ISP or multiple
        connections to the same ISP</para>
      </listitem>

      <listitem>
        <para>You run Squid as a transparent proxy on a host other than the
        firewall.</para>
      </listitem>

      <listitem>
        <para>You have other requirements for policy routing.</para>
      </listitem>
    </itemizedlist>

    <para>Each entry in the file defines a single routing table.</para>

    <para>If you wish to omit a column entry but want to include an entry in
    the next column, use "-" for the omitted entry.</para>

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

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

        <listitem>
          <para>The provider <emphasis>name</emphasis>. Must be a valid shell
          variable name. The names 'local', 'main', 'default' and 'unspec' are
          reserved and may not be used as provider names.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">NUMBER</emphasis> -
        <emphasis>number</emphasis></term>

        <listitem>
          <para>The provider number -- a number between 1 and 15. Each
          provider must be assigned a unique value.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">MARK</emphasis> (Optional) -
        <emphasis>value</emphasis></term>

        <listitem>
          <para>A FWMARK <emphasis>value</emphasis> used in your <ulink
          url="/manpages/shorewall-mangle.html">shorewall-mangle(5)</ulink> file to
          direct packets to this provider.</para>

          <para>If HIGH_ROUTE_MARKS=Yes in <ulink
          url="/manpages/shorewall.conf.html">shorewall.conf(5)</ulink>, then the value
          must be a multiple of 256 between 256 and 65280 or their hexadecimal
          equivalents (0x0100 and 0xff00 with the low-order byte of the value
          being zero). Otherwise, the value must be between 1 and 255. Each
          provider must be assigned a unique mark value. This column may be
          omitted if you don't use packet marking to direct connections to a
          particular provider.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">DUPLICATE</emphasis> -
        <emphasis>routing-table-name</emphasis></term>

        <listitem>
          <para>The name of an existing table to duplicate to create this
          routing table. May be <option>main</option> or the name of a
          previously listed provider. You may select only certain entries from
          the table to copy by using the COPY column below. This column should
          contain a dash ("-') when USE_DEFAULT_RT=Yes in <ulink
          url="/manpages/shorewall.conf.html">shorewall.conf(5)</ulink>.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>The name of the network interface to the provider. Must be
          listed in <ulink
          url="/manpages/shorewall-interfaces.html">shorewall-interfaces(5)</ulink>. In
          general, that interface should not have the
          <option>proxyarp</option> option specified unless
          <option>loose</option> is given in the OPTIONS column of this
          entry.</para>

          <para>Where more than one provider is serviced through a single
          interface, the <emphasis>interface</emphasis> must be followed by a
          colon and the IP <emphasis>address</emphasis> of the interface that
          is supplied by the associated provider.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">GATEWAY</emphasis> - {<emphasis
        role="bold">-</emphasis>|<emphasis>address</emphasis>|<emphasis
        role="bold">detect</emphasis>}</term>

        <listitem>
          <para>The IP address of the provider's gateway router.</para>

          <para>You can enter "detect" here and Shorewall will attempt to
          detect the gateway automatically.</para>

          <para>For PPP devices, you may omit this column.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>A comma-separated list selected from the following. The order
          of the options is not significant but the list may contain no
          embedded white-space.</para>

          <variablelist>
            <varlistentry>
              <term>autosrc</term>

              <listitem>
                <para>Added in Shorewall 4.5.17. Causes a host route to the
                provider's gateway router to be added to the provider's
                routing table. This is the default behavior unless overridden
                by a following <emphasis role="bold">noautosrc</emphasis>
                option.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>If specified, inbound connections on this interface are
                to be tracked so that responses may be routed back out this
                same interface.</para>

                <para>You want to specify <option>track</option> if internet
                hosts will be connecting to local servers through this
                provider.</para>

                <para>Beginning with Shorewall 4.4.3, <option>track</option>
                defaults to the setting of the TRACK_PROVIDERS option in
                <ulink url="/manpages/shorewall.conf.html">shorewall.conf</ulink> (5).
                If you set TRACK_PROVIDERS=Yes and want to override that
                setting for an individual provider, then specify
                <option>notrack</option> (see below).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">balance[=<replaceable>weight</replaceable>]</emphasis></term>

              <listitem>
                <para>The providers that have <option>balance</option>
                specified will get outbound traffic load-balanced among them.
                By default, all interfaces with <option>balance</option>
                specified will have the same weight (1). You can change the
                weight of an interface by specifying
                <option>balance=</option><replaceable>weight</replaceable>
                where <replaceable>weight</replaceable> is the weight of the
                route out of this interface.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Shorewall normally adds a routing rule for each IP
                address on an interface which forces traffic whose source is
                that IP address to be sent using the routing table for that
                interface. Setting <option>loose</option> prevents creation of
                such rules on this interface.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>noautosrc</term>

              <listitem>
                <para>Added in Shorewall 4.5.17. Prevents the addition of a
                host route to the provider's gateway router from being added
                to the provider's routing table. This option must be used with
                caution as it can cause start and restart failures.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Added in Shorewall 4.4.3. When specified, turns off
                <option>track</option>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">optional (deprecated for use with
              providers that do not share an interface)</emphasis></term>

              <listitem>
                <para>If the interface named in the INTERFACE column is not up
                and configured with an IPv4 address then ignore this provider.
                If not specified, the value of the <option>optional</option>
                option for the INTERFACE in <ulink
                url="/manpages/shorewall-interfaces.html">shorewall-interfaces(5)</ulink>
                is assumed. Use of that option is preferred to this one,
                unless an <replaceable>address</replaceable> is provider in
                the INTERFACE column.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">src=</emphasis><replaceable>source-address</replaceable></term>

              <listitem>
                <para>Specifies the source address to use when routing to this
                provider and none is known (the local client has bound to the
                0 address). May not be specified when an
                <replaceable>address</replaceable> is given in the INTERFACE
                column. If this option is not used, Shorewall substitutes the
                primary IP address on the interface named in the INTERFACE
                column.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">mtu=</emphasis><replaceable>number</replaceable></term>

              <listitem>
                <para>Specifies the MTU when forwarding through this provider.
                If not given, the MTU of the interface named in the INTERFACE
                column is assumed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis
              role="bold">fallback[=<replaceable>weight</replaceable>]</emphasis></term>

              <listitem>
                <para>Indicates that a default route through the provider
                should be added to the default routing table (table 253). If a
                <replaceable>weight</replaceable> is given, a balanced route
                is added with the weight of this provider equal to the
                specified <replaceable>weight</replaceable>. If the option is
                given without a <replaceable>weight</replaceable>, an separate
                default route is added through the provider's gateway; the
                route has a metric equal to the provider's NUMBER.</para>

                <para>Prior to Shorewall 4.4.24, the option is ignored with a
                warning message if USE_DEFAULT_RT=Yes in
                <filename>shorewall.conf</filename>.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Added in Shorewall 4.5.4. Used for supporting the TPROXY
                action in shorewall-mangle(5). See <ulink
                url="/Shorewall_Squid_Usage.html">http://www.shorewall.net/Shorewall_Squid_Usage.html</ulink>.
                When specified, the MARK, DUPLICATE and GATEWAY columns should
                be empty, INTERFACE should be set to 'lo' and
                <option>tproxy</option> should be the only OPTION. Only one
                <option>tproxy</option> provider is allowed.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Added in Shorewall 4.5.21. This is the default behavior
                that results in a host route to the defined <emphasis
                role="bold">GATEWAY</emphasis> being inserted into the main
                routing table and into the provider's routing table. <emphasis
                role="bold">hostroute</emphasis> is required for older
                distributions but <emphasis role="bold">nohostroute</emphasis>
                (below) is appropriate for recent distributions. <emphasis
                role="bold">hostroute</emphasis> may interfere with Zebra's
                ability to add routes on some distributions such as Debian
                7.</para>
              </listitem>
            </varlistentry>

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

              <listitem>
                <para>Added in Shorewall 4.5.21. nohostroute inhibits addition
                of a host route to the defined <emphasis
                role="bold">GATEWAY</emphasis> being inserted into the main
                routing table and into the provider's routing table. <emphasis
                role="bold">nohostroute</emphasis> is not appropriate for
                older distributions but is appropriate for recent
                distributions. <emphasis role="bold">nohostroute</emphasis>
                allows Zebra's to correctly add routes on some distributions
                such as Debian 7.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">COPY</emphasis> -
        [{<option>none</option>|<emphasis>interface</emphasis><emphasis
        role="bold">[,</emphasis><emphasis>interface</emphasis>]...}]</term>

        <listitem>
          <para>A comma-separated list of other interfaces on your firewall.
          Wildcards specified using an asterisk ("*") are permitted (e.g.,
          tun* ). Usually used only when DUPLICATE is <option>main</option>.
          Only copy routes through INTERFACE and through interfaces listed
          here. If you only wish to copy routes through INTERFACE, enter
          <option>none</option> in this column.</para>

          <para>Beginning with Shorewall 4.5.17, blackhole, unreachable and
          prohibit routes are no longer copied by default but may be copied by
          including <emphasis role="bold">blackhole</emphasis>,<emphasis
          role="bold">unreachable</emphasis> and <emphasis
          role="bold">prohibit</emphasis> respectively in the COPY
          list.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Examples</title>

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

        <listitem>
          <para>You run squid in your DMZ on IP address 192.168.2.99. Your DMZ
          interface is eth2</para>

          <programlisting>        #NAME   NUMBER  MARK DUPLICATE  INTERFACE GATEWAY       OPTIONS
        Squid   1       1    -          eth2      192.168.2.99  -</programlisting>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>eth0 connects to ISP 1. The IP address of eth0 is
          206.124.146.176 and the ISP's gateway router has IP address
          206.124.146.254.</para>

          <para>eth1 connects to ISP 2. The IP address of eth1 is
          130.252.99.27 and the ISP's gateway router has IP address
          130.252.99.254.</para>

          <para>eth2 connects to a local network.</para>

          <programlisting>        #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY          OPTIONS            COPY
        ISP1  1       1    main      eth0      206.124.146.254 track,balance      eth2
        ISP2  2       2    main      eth1      130.252.99.254  track,balance      eth2</programlisting>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>FILES</title>

    <para>/etc/shorewall/providers</para>
  </refsect1>

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

    <para><ulink
    url="/MultiISP.html">http://www.shorewall.net/MultiISP.html</ulink></para>

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

    <para>shorewall(8), shorewall-accounting(5), shorewall-actions(5),
    shorewall-blacklist(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-proxyarp(5), shorewall-rtrules(5),
    shorewall-routestopped(5), shorewall-rules(5), shorewall.conf(5),
    shorewall-secmarks(5), shorewall-tcclasses(5), shorewall-tcdevices(5),
    shorewall-mangle(5), shorewall-tos(5), shorewall-tunnels(5),
    shorewall-zones(5)</para>
  </refsect1>
</refentry>