1
0
shorewall_code/Shorewall6/manpages/shorewall6-providers.xml
Tom Eastep 94cfe54f92 Allow routing tables with no default route
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2016-02-17 11:49:09 -08:00

470 lines
19 KiB
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-providers</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo>Configuration Files</refmiscinfo>
</refmeta>
<refnamediv>
<refname>providers</refname>
<refpurpose>Shorewall6 Providers file</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>/etc/shorewall6/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="/manpages6/shorewall6-mangle.html">shorewall6-mangle</ulink>(5)
file to direct packets to this provider.</para>
<para>If HIGH_ROUTE_MARKS=Yes in <ulink
url="/manpages6/shorewall6.conf.html">shorewall6.conf</ulink>(5),
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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">INTERFACE</emphasis> -
<emphasis>interface</emphasis></term>
<listitem>
<para>The name of the network interface to the provider. Must be
listed in <ulink
url="/manpages6/shorewall6-interfaces.html">shorewall6-interfaces</ulink>(5).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">GATEWAY</emphasis> - {<emphasis
role="bold">-</emphasis>|<emphasis>address</emphasis>|<emphasis
role="bold">detect|none</emphasis>}</term>
<listitem>
<para>The IP address of the provider's gateway router.</para>
<para>You can enter <emphasis role="bold">detect</emphasis> here and
Shorewall6 will attempt to detect the gateway automatically.</para>
<para>Beginning with Shorewall 5.0.6, you may also enter <emphasis
role="bold">none</emphasis>. This causes creation of a routing table
with no default route in it.</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">balance</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.25. Causes a default route to
this provider's gateway to be added to the <emphasis
role="bold">main</emphasis> routing table (USE_DEFAULT_RT=No)
or to the <emphasis role="bold">balance</emphasis> routing
table (USE_DEFAULT_RT=Yes). Only one provider can specify this
option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">fallback</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.25. Causes a default route to
this provider's gateway to be added to the <emphasis
role="bold">default</emphasis> routing table.At most one
provider can specify this 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="/manpages6/shorwewall6.conf.html">shorewall6.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">loose</emphasis></term>
<listitem>
<para>Shorewall6 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><emphasis
role="bold">load=<replaceable>probability</replaceable></emphasis></term>
<listitem>
<para>Added in Shorewall 4.6.0. This option provides an
alternative method of load balancing based on probabilities.
Providers to be balanced are given a
<replaceable>probability</replaceable> (a number 0 &gt; n
&gt;= 1) with up to 8 digits to the right of the decimal
point. Beginning with Shorewall 4.6.10, a warning is issued if
the sum of the probabilities is not 1.00000000.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">noautosrc</emphasis></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</emphasis> (deprecated for
use with providers that do not share an interface)</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="/manpages6/shorewall6-interfaces.html">shorewall6-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">primary</emphasis></term>
<listitem>
<para>Added in Shorewall 4.6.6, <emphasis
role="bold">primary</emphasis> is a synonym for <emphasis
role="bold">balance</emphasis> (see above) and is preferred
when the remaining providers specify <emphasis
role="bold">fallback</emphasis> or <emphasis
role="bold">tproxy</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>src=<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, Shorewall6 substitutes the
primary IP address on the interface named in the INTERFACE
column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>mtu=<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">tproxy</emphasis></term>
<listitem>
<para>Added in Shorewall 4.5.4. Used for supporting the TPROXY
action in shorewall-tcrules(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>
<varlistentry>
<term><emphasis role="bold">persistent</emphasis></term>
<listitem>
<para>Added in Shorewall 5.0.2 and alters the behavior of the
<command>disable</command> command:</para>
<itemizedlist>
<listitem>
<para>The provider's routing table still contains the
apprioriate default route.</para>
</listitem>
<listitem>
<para>Unless the <option>noautosrc</option> option is
specified, routing rules are generated to route traffic
from the interfaces address(es) out of the provider's
routing table.</para>
</listitem>
<listitem>
<para>Persistent routing rules in <ulink
url="shorewall-rtrules.html">shorewall6-rtrules(5)</ulink>
are present.</para>
</listitem>
</itemizedlist>
</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 2002:ce7c:92b4:1::2.
Your DMZ interface is eth2</para>
<programlisting> #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS
Squid 1 1 - eth2 2002:ce7c:92b4:1::2 -</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>Example 2:</term>
<listitem>
<para>eth0 connects to ISP 1. The ISP's gateway router has IP
address 2001:ce7c:92b4:1::2.</para>
<para>eth1 connects to ISP 2. The ISP's gateway router has IP
address 2001:d64c:83c9:12::8b.</para>
<para>eth2 connects to a local network.</para>
<programlisting> #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
ISP1 1 1 main eth0 2001:ce7c:92b4:1::2 track eth2
ISP2 2 2 main eth1 2001:d64c:83c9:12::8b track eth2</programlisting>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>FILES</title>
<para>/etc/shorewall6/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>shorewall6(8), shorewall6-accounting(5), shorewall6-actions(5),
shorewall6-blacklist(5), shorewall6-hosts(5), shorewall6-interfaces(5),
shorewall6-maclist(5), shorewall6-netmap(5),shorewall6-params(5),
shorewall6-policy(5), shorewall6-rtrules(5), shorewall6-routestopped(5),
shorewall6-rules(5), shorewall6.conf(5), shorewall6-secmarks(5),
shorewall6-tcclasses(5), shorewall6-tcdevices(5), shorewall6-mangle(5),
shorewall6-tos(5), shorewall6-tunnels(5), shorewall6-zones(5)</para>
</refsect1>
</refentry>