Let's assume that a firewall is connected via two separate Ethernet interfaces to two different ISPs as in the following diagram.

Each of these providers is described in an entry in the file /etc/shorewall/providers.

Entries in /etc/shorewall/providers can specify that outgoing connections are to be load-balanced between the two ISPs. Entries in /etc/shorewall/tcrules can be used to direct particular outgoing connections to one ISP or the other. Use of /etc/shorewall/tcrules is not required for /etc/shorewall/providers to work, but you must select a unique MARK value for each provider so Shorewall can set up the correct marking rules for you.

When you use the track option in /etc/shorewall/providers, connections from the Internet are automatically routed back out of the correct interface and through the correct ISP gateway. This works whether the connection is handled by the firewall itself or if it is routed or port-forwarded to a system behind the firewall.

Shorewall will set up the routing and will update the /etc/iproute2/rt_tables to include the table names and numbers of the tables that it adds.

The /etc/shorewall/providers file can also be used in other routing scenarios. See the Squid documentation for an example.

Entries in this file have the following columns. As in all Shorewall configuration files, enter "-" in a column if you don't want to enter any value.

Adding another entry in the providers file simply creates an alternate routing table for you. The table will usually contain two routes:

Note that the first route is omitted if "-" is specified as the GATEWAY; in that case, the default route does not specify a gateway (point-to-point link).

If the DUPLICATE column is non-empty, then routes from the table named in that column are copied into the new table. By default, all routes (except default routes) are copied. The set of routes copied can be restricted using the COPY column which lists the interfaces whose routes you want copied. You will generally want to include all local interfaces in this list. You should exclude the loopback interface (lo) and any interfaces that do not have an IPv4 configuration. You should also omit interfaces like tun interfaces that are created dynamically. Traffic to networks handled by those interfaces should be routed through the main table using entries in /etc/shorewall/route_rules (see Example 2 below).

In addition:

That's all that these entries do. You still have to follow the principle stated in the Shorewall Routing documentation:

The bottom line is that if you want traffic to go out through a particular provider then you must mark that traffic with the provider's MARK value in /etc/shorewall/tcrules and you must do that marking in the PREROUTING chain; or, you must provide the appropriate rules in /etc/shorewall/route_rules.

If you masquerade a local network, you will need to add masquerade rules for both external interfaces. Referring to the diagram above, if each of the interfaces has only a single IP address and you have no systems with public IP addresses behind your firewall, then I suggest the following simple entries:

#INTERFACE       SOURCE            ADDRESS
eth0             0.0.0.0/0         206.124.146.176
eth1             0.0.0.0/0         130.252.99.27

If you have a public subnet (for example 206.124.146.176/30) behind your firewall, then use exclusion:

#INTERFACE       SOURCE               ADDRESS
eth0             !206.124.146.176/29  206.124.146.176
eth1             0.0.0.0/0            130.252.99.27

Note that exclusion is only used on the interface corresponding to internal subnetwork.

If you have multiple IP addresses on one of your interfaces, you can use a similar technique -- simple exclude the smallest network that contains all of those addresses from being masqueraded.

One problem that often arises with Multi-ISP configuration is 'Martians'. If your Internet interfaces are configured with the routefilter option in /etc/shorewall/interfaces (remember that if you set that option, you should also select logmartians), then things may not work correctly and you will see messages like this:

Feb  9 17:23:45 gw.ilinx kernel: martian source 206.124.146.176 from 64.86.88.116, on dev eth1 
Feb  9 17:23:45 gw.ilinx kernel: ll header: 00:a0:24:2a:1f:72:00:13:5f:07:97:05:08:00

The above message is somewhat awkwardly phrased. The source IP in this incoming packet was 64.86.88.116 and the destination IP address is 206.124.146.176. Another gotcha is that the incoming packet has already had the destination IP address changed for DNAT or because the original outgoing connection was altered by an entry in /etc/shorewall/masq (SNAT or Masquerade). So the destination IP address (206.124.146.176) may not have been the destination IP address in the packet as it was initially received.

There a couple of common causes for these problems:

If all else fails, remove the routefilter option from your external interfaces. If you do this, you may wish to add rules to log and drop packets from the Internet that have source addresses in your local networks. For example, if the local LAN in the above diagram is 192.168.1.0/24, then you would add this rule:

#ACTION          SOURCE                     DEST
DROP:info        net:192.168.1.0/24         all

Be sure the above rule is added before any other rules with net in the SOURCE column.

The configuration in the figure at the top of this section would be specified in /etc/shorewall/providers as follows.

#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

Other configuration files go something like this:

/etc/shorewall/interfaces:

#ZONE    INTERFACE    BROADCAST       OPTIONS
net      eth0         detect          …          
net      eth1         detect          …

/etc/shorewall/policy:

#SOURCE    DESTINATION    POLICY     LIMIT:BURST
net        net            DROP

/etc/shorewall/masq (assumes that there are no public subnets behind the firewall):

#INTERFACE       SUBNET            ADDRESS
eth0             0.0.0.0/0        206.124.146.176
eth1             0.0.0.0/0        130.252.99.27

This continues the example in the preceding section.

Now suppose that you want to route all outgoing SMTP traffic from your local network through ISP 2. You would make this entry in /etc/shorewall/tcrules (and if you are running a version of Shorewall earlier than 3.0.0, you would set TC_ENABLED=Yes in /etc/shorewall/shorewall.conf).

#MARK           SOURCE          DEST            PROTO   PORT(S) CLIENT  USER    TEST
#                                                               PORT(S)
2:P             <local network> 0.0.0.0/0       tcp     25

Shorewall provides considerable flexibility for port forwarding in a multi-ISP environment.

Normal port forwarding rules such as the following will forward from both providers.

/etc/shorewall/rules:

#ACTION        SOURCE             DEST              PROTO     DEST PORT(S)     SOURCE       ORIGINAL
#                                                                              PORTS(S)     DEST
DNAT           net                loc:192.168.1.3   tcp       25

Continuing the above example, to forward only connection requests from ISP 1, you can either:

When there are more than two providers, you need to extend the two-provider case in the expected way:

If we extend the above example to add eth3 with IP address 16.105.78.4 with gateway 16.105.78.254, then:

/etc/shorewall/providers:

#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
ISP3    3       3       main            eth3            16.105.78.254   track,balance    eth2

/etc/shorewall/masq:

#INTERFACE       SUBNET            ADDRESS
eth0             130.252.99.27     206.124.146.176
eth3             130.252.99.27     16.105.78.4
eth1             206.124.146.176   130.252.99.27
eth3             206.124.146.176   16.105.78.4
eth0             16.106.78.4       206.124.146.176
eth1             16.106.78.4       130.252.99.27
eth0             eth2              206.124.146.176
eth1             eth2              130.252.99.27
eth3             eth2              16.105.78.4

Experience has shown that in some cases, problems occur with applications running on the firewall itself. This is especially true when you have specified routefilter on your external interfaces in /etc/shorewall/interfaces (see above). When this happens, it is suggested that you have the application use specific local IP addresses rather than 0.

Examples:

Note that some traffic originating on the firewall doesn't have a SOURCE IP address before routing. At least one Shorewall user reports that an entry in /etc/shorewall/route_rules with 'lo' in the SOURCE column seems to be the most reliable way to direct such traffic to a particular ISP.

If you have an IPSEC gateway on your firewall, be sure to arrange for ESP packets to be routed out of the same interface that you have configured your keying daemon to use.

The /etc/shorewall/route_rules file was added in Shorewall version 3.2.0. The route_rules file allows assigning certain traffic to a particular provider just as entries in the tcrules file. The difference between the two files is that entries in route_rules are independent of Netfilter.

gateway:~ # ip rule ls
0:      from all lookup local                <=== Local (to the firewall) IP addresses
10001:  from all fwmark 0x1 lookup Blarg     <=== This and the next rule are generated by the
10002:  from all fwmark 0x2 lookup Comcast        'MARK' values in /etc/shorewall/providers.
20000:  from 206.124.146.176 lookup Blarg    <=== This and the next rule are generated unless
20256:  from 24.12.22.33 lookup Comcast           'loose' is specified; based in the output of 'ip addr ls'
32766:  from all lookup main                 <=== This is the routing table shown by 'iproute -n'
32767:  from all lookup default              <=== This table is usually empty
gateway:~ #

#SOURCE            DEST      PROVIDER        PRIORITY
eth1               -         Comcast         1000

gateway:~ # ip rule ls
0:      from all lookup local
1000:   from all iif eth1 lookup Comcast
10001:  from all fwmark 0x1 lookup Blarg
10002:  from all fwmark 0x2 lookup Comcast
20000:  from 206.124.146.176 lookup Blarg
20256:  from 24.12.22.33 lookup Comcast
32766:  from all lookup main
32767:  from all lookup default
gateway:~ #

#SOURCE                 DEST            PROVIDER        PRIORITY
-                       10.8.0.0/24     main            1000

Beginning with Shorewall 4.2.0 Beta3, Shorewall-perl has supported a USE_DEFAULT_RT option in shorewall.conf (5).

One of the drawbacks of the Multi-ISP support as described in the preceding sections is that changes to the main table made by applications are not added to the individual provider tables. This makes route rules such as described in one of the examples above necessary.

USE_DEFAULT_RT=Yes works around that problem by passing packets through the main table first rather than last. This has a number of implications:

Although 'balance' is automatically assumed when USE_DEFAULT_RT=Yes, you can easily cause all traffic to use one provider except when you explicitly direct it to use the other provider via shorewall-route_rules (5) or shorewall-tcrules (5).

Example (send all traffic through the 'shorewall' provider unless otherwise directed).

/etc/shorewall/providers:

#NAME    NUMBER MARK DUPLICATE INTERFACE GATEWAY       OPTIONS
linksys       1    1    -        wlan0   172.20.1.1    track,balance=1,optional
shorewall     2    2    -        eth0    192.168.1.254 track,balance=2,optional

/etc/shorewall/route_rules:

#SOURCE     DEST      PROVIDER        PRIORITY
-           -         shorewall       11999

There are a couple of options available for monitoring the status of provider links and taking action when a failure occurs.

When using either solution, it is important that the providers be optional.

If you are using Shorewall 4.0, you must specify the optional option in /etc/shorewall/providers:

#NAME   NUMBER  MARK    DUPLICATE       INTERFACE       GATEWAY         OPTIONS                   COPY
ISP1    1       1       main            eth0            206.124.146.254 track,balance,optional    eth2
ISP2    2       2       main            eth1            130.252.99.254  track,balance,optional    eth2

If you are using Shorwall 4.2 (which is highly recommended), you specify the optional option in /etc/shorewall/interfaces:

#ZONE    INTERFACE    BROADCAST       OPTIONS
net      eth0         detect          optional         
net      eth1         detect          optional

#
# IP family -- 4 or 6
#
FAMILY=4
#
# The commands to run when the status of a line changes. Multiple commands may be specified 
# when separated by semicolons (";")
#
COMMAND=

...
#
# Interfaces to monitor -- you may use shell variables from your params file
#
IF1=eth0
IF2=eth1
#
# Sites to Ping. Must depend only on routes in the 'main' routing table. If not specified,
# the interface is assumed to be managed by dhcpcd and the script uses the gateway address
# from /var/lib/dhcpcd/dhcpcd-${IFx}.info
#
TARGET1=
TARGET2=
#
# How often to ping
#
PING_INTERVAL=5
#
# Value for ping's -W option
#
PING_TIMEOUT=2
#
# This many successive pings must succeed for the interface to be marked up when it is down
#
UP_COUNT=5
#
# This many successive pings must fail for the interface to be marked down when it is up
#
DOWN_COUNT=2

local status=0

case $1 in
    eth0|eth1)
        [ -f /etc/shorewall/${1}.status ] && status=$(cat /etc/shorewall/${1}.status)
        ;;
esac

return $status

if [ "$COMMAND" = start ]; then
   killall -9 swping 2> /dev/null #be sure that there are none left running
   /usr/local/sbin/swping &
fi

if [ "$COMMAND" = stop -o "$COMMAND" = clear ]; then
   killall -9 swping 2> /dev/null
fi

local status
status=0

[ -f /etc/shorewall/${1}.status ] && status=$(cat /etc/shorewall/${1}.status)

return $status

###############################################################################
# My 'restored' script calls this one if there is no lsm process running
###############################################################################
if [ "$COMMAND" = start -o "$COMMAND" = restore ]; then
   killproc lsm 2> /dev/null
   cat <<EOF > /etc/lsm/shorewall.conf
connection {
    name=Avvanta
    checkip=206.124.146.254
    device=eth0
    ttl=2
}

connection {
    name=Comcast
    checkip=${ETH3_GATEWAY:-71.227.156.1}
    device=eth3
    ttl=1
}
EOF
   rm -f /etc/shorewall/*.status
   /usr/sbin/lsm /etc/lsm/lsm.conf >> /var/log/lsm
fi

if [ -z "$(ps ax | grep 'lsm ' | grep -v 'grep ' )" ]; then
   run_started_exit
fi

#
# Defaults for the connection entries
#
defaults {
  name=defaults
  checkip=127.0.0.1
  eventscript=/etc/lsm/script
  max_packet_loss=20
  max_successive_pkts_lost=7
  min_packet_loss=5
  min_successive_pkts_rcvd=10
  interval_ms=2000
  timeout_ms=2000
  warn_email=teastep@shorewall.net
  check_arp=0
  sourceip=
  ttl=64
}

include /etc/lsm/shorewall.conf

#!/bin/sh
#
# (C) 2009 Mika Ilmaranta <ilmis@nullnet.fi>
# (C) 2009 Tom Eastep <teastep@shorewall.net>
#
# License: GPLv2
#

STATE=${1}
NAME=${2}
CHECKIP=${3}
DEVICE=${4}
WARN_EMAIL=${5}
REPLIED=${6}
WAITING=${7}
TIMEOUT=${8}
REPLY_LATE=${9}
CONS_RCVD=${10}
CONS_WAIT=${11}
CONS_MISS=${12}
AVG_RTT=${13}

cat <<EOM | mail -s "${NAME} ${STATE}, DEV ${DEVICE}" ${WARN_EMAIL}

Hi,

Connection ${NAME} is now ${STATE}.

Following parameters were passed:
newstate     = ${STATE}
name         = ${NAME}
checkip      = ${CHECKIP}
device       = ${DEVICE}
warn_email   = ${WARN_EMAIL}

Packet counters:
replied      = ${REPLIED} packets replied
waiting      = ${WAITING} packets waiting for reply
timeout      = ${TIMEOUT} packets that have timed out (= packet loss)
reply_late   = ${REPLY_LATE} packets that received a reply after timeout
cons_rcvd    = ${CONS_RCVD} consecutively received replies in sequence
cons_wait    = ${CONS_WAIT} consecutive packets waiting for reply
cons_miss    = ${CONS_MISS} consecutive packets that have timed out
avg_rtt      = ${AVG_RTT} average rtt, notice that waiting and timed out packets have rtt = 0 when calculating this

Your LSM Daemon

EOM

[ ${STATE} = up ] && state=0 || state=1

echo $state > /etc/shorewall/${DEVICE}.status

/sbin/shorewall -f restart >> /var/log/lsm 2>&1

/sbin/shorewall show routing >> /var/log/lsm

exit 0;

#EOF

Shared interface support is available only in Shorewall-perl 4.2.0 and later.

Taken together, b. and h. effectively preclude using this technique with dynamic IP addresses.

Example:

This is our home network circa fall 2008. We have two Internet providers:

Because the old Compaq™ Presario™ that I use for a firewall only has three PCI slots and no onboard Ethernet, it doesn't have enough Ethernet controllers to support both providers. So I use a Linksys WRT300n pre-N router as a gateway to Comcast. Note that because the Comcast IP address is dynamic, I could not share a single firewall interface between the two providers directly.

On my personal laptop (ursa), I have 9 virtual machines running various Linux distributions. It is the Shorewall configuration on ursa that I will describe here.

Below is a diagram of our network:

The local wired network in my office is connected to both gateways and uses the private (RFC 1918) network 172.20.1.0/24. The Comcast gateway has local IP address 172.20.1.1 while the Avvanta gateway has local IP address 172.20.1.254. Ursa's eth0 interface has a single IP address (172.20.1.130).

This configuration uses USE_DEFAULT_RT=Yes in shorewall.conf (see above).

Here is the providers file:

#NAME          NUMBER   MARK DUPLICATE INTERFACE            GATEWAY      OPTIONS                            COPY
comcast        1        1    -         eth0:172.20.1.130    172.20.1.1   track,loose,balance,optional
avvanta        2        2    -         eth0:172.20.1.130    172.20.1.254 track,optional,loose
wireless       3        3    -         wlan0                172.20.1.1   track,optional

Several things to note:

Here is the route_rules file:

#SOURCE                 DEST                    PROVIDER        PRIORITY
-                       206.124.146.176/31      avvanta         1000
-                       206.124.146.178/31      avvanta         1000
-                       206.124.146.180/32      avvanta         1000

Those rules direct traffic to the five static Avvanta IP addresses (only two are currently used) through the avvanta provider.

Here is the tcrules file (MARK_IN_FORWARD_CHAIN=No in shorewall.conf):

#MARK           SOURCE          DEST            PROTO   PORT(S)         CLIENT  USER    TEST    LENGTH  TOS     CONNBYTES       HELPER
#                                                                       PORT(S) 
2               $FW             0.0.0.0/0       tcp     21
2               $FW             0.0.0.0/0       tcp     -               -       -       -       -       -       -               ftp
2               $FW             0.0.0.0/0       tcp     119

These rules:

The remaining files are for a rather standard two-interface config with a bridge as the local interface.

zones:

#ZONE   IPSEC   OPTIONS                 IN                      OUT
#       ONLY                            OPTIONS                 OPTIONS
fw      firewall
net     ipv4
kvm     ipv4

policy:

net             net             NONE
fw              net             ACCEPT
fw              kvm             ACCEPT
kvm             all             ACCEPT
net             all             DROP            info
all             all             REJECT          info

interfaces:

#ZONE    INTERFACE      BROADCAST       OPTIONS                 GATEWAY
#
net     eth0            detect          dhcp,tcpflags,routefilter,blacklist,logmartians,optional,arp_ignore
net     wlan0           detect          dhcp,tcpflags,routefilter,blacklist,logmartians,optional
kvm     br0             detect          routeback       #Virtual Machines

masq:

#INTERFACE              SUBNET          ADDRESS         PROTO   PORT(S) IPSEC
eth0                    192.168.0.0/24
wlan0                   192.168.0.0/24