Tom Eastep 2005 2006 2007 2008 Thomas M. Eastep Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. This document describes the Multi-ISP facility in Shorewall 4.0 and later. If you are running an earlier release, please see the documentation for that release. Reading just Shorewall documentation is probably not going to give you enough background to use this material. Shorewall may make iptables easy but the Shorewall team doesn't have the resources to be able to spoon-feed Linux policy routing to you (please remember that the user's manual for a tractor doesn't teach you to grow corn either). You will likely need to refer to the following additional information: The LARTC HOWTO: http://www.lartc.org Output of man ip Output of ip route help and ip rule help

Beginning with Shorewall 2.3.2, limited support is included for multiple internet connections. Limitations of this support are as follows: It utilizes static routing configuration. As such, there is no provision for reacting to the failure of any of the uplinks. The routing changes are made and the route cache is purged when Shorewall is started and when Shorewall is restarted (unless you specify the "-n" option to shorewall restart). Ideally, restarting the packet filter should have no effect on routing. Prior to Shorewall 3.4.0, the routes and route rules added by this support were not completely removed during shorewall stop, shorewall clear or shorewall restart. For most routing applications, Quagga is a better solution.

Let's assume that a firewall is connected via two separate ethernet interfaces to two different ISPs as in the following diagram. eth0 connects to ISP1. The IP address of eth0 is 206.124.146.176 and the ISP's gateway router has IP address 206.124.146.254. 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. eth2 connects to the local LAN. Its IP configuration is not relevant to this discussion. 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. This feature uses packet marking to control the routing. As a consequence, there are some restrictions concerning entries in /etc/shorewall/tcrules: Packet marking for traffic control purposes may not be done in the PREROUTING table for connections involving providers with 'track' specified (see below). You may not use the SAVE or RESTORE options. You may not use connection marking. 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. NAME The provider name. Must begin with a letter and consist of letters and digits. The provider name becomes the name of the generated routing table for this provider. NUMBER A number between 1 and 252. This becomes the routing table number for the generated table for this provider. MARK A mark value used in your /etc/shorewall/tcrules file to direct packets to this provider. Shorewall will also mark connections that have seen input from this provider with this value and will restore the packet mark in the PREROUTING CHAIN. Mark values must be in the range 1-255. Beginning with Shorewall version 3.2.0 Beta 6, you may use may set HIGH_ROUTE_MARKS=Yes in /etc/shorewall/shorewall.conf. This allows you to: Use connection marks for traffic shaping, provided that you assign those marks in the FORWARD chain. Use mark values > 255 for provider marks in this column. These mark values must be a multiple of 256 in the range 256-65280 (hex equivalent 0x100 - 0xFF00 with the low-order 8 bits being zero). DUPLICATE Gives the name or number of a routing table to duplicate. May be 'main' or the name or number of a previously declared provider. For most applications, you want to specify 'main' here. This field should be be specified as '-' when USE_DEFAULT_RT=Yes in shorewall.conf INTERFACE The name of the interface to the provider. Where multiple providers share the same interface (which is not recommended), you must follow the name of the interface by a colon (":") and the IP address assigned by this provider (e.g., eth0:206.124.146.176). See below for additional considerations. GATEWAY The IP address of the provider's Gateway router. You can enter detect here and Shorewall will attempt to automatically determine the gateway IP address. Hint: "detect" is appropriate for use in cases where the interface named in the INTERFACE column is dynamically configured via DHCP etc. The GATEWAY may be omitted (enter '-') for point-to-point links. OPTIONS A comma-separated list from the following: track If specified, connections FROM this interface are to be tracked so that responses may be routed back out this same interface. You want to specify 'track' if internet hosts will be connecting to local servers through this provider. Any time that you specify 'track', you will also want to specify 'balance' (see below). Use of this feature requires that your kernel and iptables include CONNMARK target and connmark match support (Warning: Standard Debian and Ubuntu kernels are lacking that support!). A bug in Shorewall versions 3.2.0-3.2.10, 3.4.0-3.4.6 and 4.0.0-4.0.2 prevents proper handling of PREROUTING marks when HIGH_ROUTE_MARKS=No and the track option is specified. Patches are available to correct this problem: Shorewall version 3.2.0-3.4.3: http://www1.shorewall.net/pub/shorewall/3.2/shorewall-3.2.10/errata/patches/Shorewall/patch-3.2.10-2.diff Shorewall version 3.4.4-3.4.6: http://www1.shorewall.net/pub/shorewall/3.4/shorewall-3.4.6/errata/patches/Shorewall/patch-3.4.6-1.diff Shorewall-shell version 4.0.0-4.0.2: http://www1.shorewall.net/pub/shorewall/4.0/shorewall-4.0.2/errata/patches/Shorewall-shell/patch-shell-4.0.2-2.diff If you are using /etc/shorewall/providers because you have multiple internet connections, we recommend that you specify 'track' even if you don't need it. It helps maintain long-term connections in which there are significant periods with no traffic. balance The providers that have 'balance' specified will get outbound traffic load-balanced among them. Balancing will not be perfect, as it is route based, and routes are cached. This means that routes to often-used sites will always be over the same provider. By default, each provider is given the same weight (1) . You can change the weight of a given provider by following balance with "=" and the desired weight (e.g., balance=2). The weights reflect the relative bandwidth of the providers connections and should be small numbers since the kernel actually creates additional default routes for each weight increment. If you are using /etc/shorewall/providers because you have multiple internet connections, we recommend that you specify 'balance' even if you don't need it. You can still use entries in /etc/shorewall/tcrules to force all traffic to one provider or another. If you don't heed this advice then be prepared to read FAQ 57 and FAQ 58. If you specify 'balance' and still find that all traffic is going out through only one provider, you may need to install a kernel built with CONFIG_IP_ROUTE_MULTIPATH_CACHED=n. Several users have reported that this change has corrected similar problems. The SuSE 10.0 kernel is subject to this problem, and a kernel oops may result in this circumstance. SUSE 10.1 and SLES 10 have CONFIG_IP_ROUTE_MULTIPATH_CACHED=n set by default. The source of the problem seems to be an incompatibility between the LARTC patches and CONFIG_IP_ROUTE_MULTIPATH_CACHED. loose Do not include routing rules that force traffic whose source IP is an address of the INTERFACE to be routed to this provider. Useful for defining providers that are to be used only when the appropriate packet mark is applied. Should not be specified together with balance. optional (added in Shorewall 3.2.2) Shorewall will determine of this interface is up and has a configured IPv4 address. If it is not, a warning is issued and this provider is not configured. 'optional' is designed to detect interface states that will cause shorewall start or shorewall restart to fail; just because an interface is in a state that Shorewall can [re]start without error doesn't mean that traffic can actually be sent through the interface. Beginning with Shorewall-perl 4.0.3, you can supply an 'isusable' extension script to extend Shorewall's interface state detection. src=source-address (Added in Shorewall-perl 4.1.5) 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 address 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. mtu=number (Added in Shorewall-perl 4.1.5) Specifies the MTU when forwarding through this provider. If not given, the MTU of the interface named in the INTERFACE column is assumed. For those of you who are termnally confused between track and balance: track governs incoming connections. balance governs outgoing connections. COPY A comma-separated list if interface names. Wildcards specified using an asterisk ("*") are permitted (e.g., tun* ). When you specify an existing table in the DUPLICATE column, Shorewall copies all routes through the interface specified in the INTERFACE column plus the interfaces listed in this column. Normally, you will list all interfaces on your firewall in this column except those internet interfaces specified in the INTERFACE column of entries in this file.

Adding another entry in the providers file simply creates an alternate routing table for you. The table will usually contain two routes: A host route to the specified GATEWAY through the specified INTERFACE. A default route through the GATEWAY. 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 intefaces should be routed through the main table using entries in /etc/shorewall/route_rules (see Example 2 below). In addition: Unless loose is specified, an ip rule is generated for each IP address on the INTERFACE that routes traffic from that address through the associated routing table. If you specify track, then connections which have had at least one packet arrive on the interface listed in the INTERFACE column have their connection mark set to the value in the MARK column. In the PREROUTING chain, packets with a connection mark have their packet mark set to the value of the associated connection mark; packets marked in this way bypass any prerouting rules that you create in /etc/shorewall/tcrules. This ensures that packets associated with connections from outside are always routed out of the correct interface. If you specify balance, then Shorewall will replace the 'default' route with weight 100 in the 'main' routing table with a load-balancing route among those gateways where balance was specified. So if you configure default routes, be sure that their weight is less than 100 or the route added by Shorewall will not be used. That's all that these entries do. You still have to follow the principle stated in the Shorewall Routing documentation: Routing determines where packets are to be sent. Once routing determines where the packet is to go, the firewall (Shorewall) determines if the packet is allowed to go there. 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.

Given that Shorewall is simply a tool to configure Netfilter and does not run continuously in your system, entries in the providers file do not provide any automatic failover in the event of failure of one of your Internet connections.

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: You have connected both of your external interfaces to the same hub/switch. Connecting multiple firewall interfaces to a common hub or switch is always a bad idea that will result in hard-to-diagnose problems. You are specifying both the loose and balance options on your provider(s). This causes individual connections to ping-pong back and forth between the interfaces which is guaranteed to cause problems. You are redirecting traffic from the local system out of one interface or the other using packet marking in your /etc/shorewall/tcrules file. A better approach is to configure the application to use the appropriate local IP address (the IP address of the interface that you want the application to use). See below. 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 Regardless of whether you have masqueraded hosts or not, the following entries are required in /etc/shorewall/masq if you plan to redirect connections from the firewall using entries in /etc/shorewall/tcrules or if you specify balance on your providers. #INTERFACE SUBNET ADDRESS eth0 130.252.99.27 206.124.146.176 eth1 206.124.146.176 130.252.99.27 Those entries ensure that traffic originating on the firewall and redirected via packet marks always has the source IP address corresponding to the interface that it is routed out of. If you have a Dynamic IP address on either of the interfaces, you can use shell variables to construct the above rules. For example, if eth0 had a dynamic IP address, then: /etc/shorewall/params: ETH0_IP=$(find_first_interface_address eth0) /etc/shorewall/masq: #INTERFACE SUBNET ADDRESS eth0 130.252.99.27 $ETH0_IP eth1 $ETH0_IP 130.252.99.27 If you have masqueraded hosts, be sure to update /etc/shorewall/masq to masquerade to both ISPs. For example, if you masquerade all hosts connected to eth2 then: #INTERFACE SUBNET ADDRESS eth0 eth2 206.124.146.176 eth1 eth2 130.252.99.27 Entries in /etc/shorewall/masq have no effect on which ISP a particular connection will be sent through. That is rather the purpose of entries in /etc/shorewall/tcrules or /etc/shorewall/route_rules. 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

When there are more than two providers, you need to extend the two-provider case in the expected way: For each external address, you need an entry in /etc/shorewall/masq to handle the case where a connection using that address as the SOURCE is sent out of the interfaces other than the one that the address is configured on. For each external interface, you need to add an entry to /etc/shorewall/masq for each internal network that needs to be masqueraded (or use SNAT) through that interface. 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: Squid: In squid.conf, set tcp_outgoing_address to the IP address of the interface that you want Squid to use. In OpenVPN, set local (--local on the command line) to the IP address that you want the server to receive connections on. 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.

Routing rules are maintained by the Linux kernel and can be displayed using the ip rule ls command. When routing a packet, the rules are processed in turn until the packet is successfully routed. 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:~ # In the above example, there are two providers: Blarg and Comcast with MARK 1 going to Blarg and mark 2 going to Comcast.

Columns in the file are: SOURCE (Optional) An ip address (network or host) that matches the source IP address in a packet. May also be specified as an interface name optionally followed by ":" and an address. If the device 'lo' is specified, the packet must originate from the firewall itself. DEST (Optional) An ip address (network or host) that matches the destination IP address in a packet. If you choose to omit either SOURCE or DEST, place "-" in that column. Note that you may not omit both SOURCE and DEST. PROVIDER The provider to route the traffic through. May be expressed either as the provider name or the provider number. PRIORITY The rule's priority which determines the order in which the rules are processed. 1000-1999 Before Shorewall-generated 'MARK' rules 11000- 11999 After 'MARK' rules but before Shorewall-generated rules for ISP interfaces. 26000-26999 After ISP interface rules but before 'default' rule. Rules with equal priority are applied in the order in which they appear in the file.

Example 1: You want all traffic entering the firewall on eth1 to be routed through Comcast. #SOURCE DEST PROVIDER PRIORITY eth1 - Comcast 1000 With this entry, the output of ip rule ls would be as follows. 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:~ #Note that because we used a priority of 1000, the test for eth1 is inserted before the fwmark tests. Example 2: You use OpenVPN (routed setup w/tunX) in combination with multiple providers. In this case you have to set up a rule to ensure that the OpenVPN traffic is routed back through the tunX interface(s) rather than through any of the providers. 10.8.0.0/24 is the subnet choosen in your OpenVPN configuration (server 10.8.0.0 255.255.255.0). #SOURCE DEST PROVIDER PRIORITY - 10.8.0.0/24 main 1000

Shared interface support is available only in Shorewall-perl 4.1.2 and later. Only ethernet (or ethernet-like) interfaces can be used. For inbound traffic, the MAC addresses of the gateway routers are used to determine which provider a packet was received through. Note that only routed traffic can be categorized using this technique. You must specify the address on the interface that corresponds to a particular provider in the INTERFACE column by following the interface name with a colon (":") and the address. Entries in /etc/shorewall/masq must be qualified by the provider name (or number). This feature requires Realm Match support in your kernel and iptables. You must add route_rules entries for networks that are accessed through a particular provider. If you have additional IP addresses through either provider, you must add route_rules to direct traffic FROM each of those addresses through the appropriate provider. You must manually add MARK rules for traffic known to come from each provider. Example: Providers Blarg (1) and Avvanta (2) are both connected to eth0. The firewall's IP address with Blarg is 206.124.146.176/24 (gateway 206.124.146.254) and the IP address from Avvanta is 130.252.144.8/24 (gateway 130.252.144.254). We have a second IP address (206.124.146.177) from Blarg. /etc/shorewall/providers:#PROVIDER NUMBER MARK DUPLICATE INTERFACE GATEWAY Blarg 1 1 main eth0:206.124.146.176 206.124.146.254 ... Avvanta 2 2 main eth0:130.252.144.8 130.252.144.254 ... /etc/shorewall/masq:#INTERFACE SOURCE ADDRESS eth0(Blarg) 130.252.144.8 206.124.146.176 eth0(Avvanta) 206.124.146.176 130.252.144.8 eth0(Blarg) eth1 206.124.146.176 eth0(Avvanta) eth1 130.252.144.8 /etc/shorewall/route_rules: #SOURCE DEST PROVIDER PRIORITY - 206.124.146.0/24 Blarg 1000 - 130.252.144.0/24 Avvanta 1000 206.124.146.177 - Blarg 26000 /etc/shorewall/tcrules:#MARK/CLASSIFY SOURCE DEST PROTO 1:P eth0:206.124.146.0/24 0.0.0.0/0 2:P eth0:130.252.144.8/24 0.0.0.0/0

Beginning with Shorewall 4.2.0 Beta3, Shorewall-perl has supported a ROUTE_BALANCE option in shorewall.conf (5). ROUTE_BALANCE=Yes is marked as Experimental currently. This means that it is a 'use at your own risk' feature; if you encounter problems, the Shorewall support staff may not be able to provide you with a quick solution. One of the drawbacks of the Mulit-ISP support as described in the preceding section 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. ROUTE_BALANCE=Yes works around that problem by passing packets through the main table first rather than last. This has a number of implications: Both the DUPLICATE and the COPY columns in the providers file must remain empty or contain "-". The individual provider routing tables generated when ROUTE_BALANCE=Yes contain only a host route to the gateway and a default route via the gateway. The balance option is assumed for all interfaces that do not have the loose option. The default route generated by Shorewall is added to the default routing table (253) rather than to the main routing table (254). Packets are sent through the main routing table by a routing rule with priority 999. In ), the priority range 1-998 may be used for inserting rules that bypass the main table. All provider gateways must be specified explicitly in the GATEWAY column. 'detect' may not be specified. Note that for ppp interfaces, the GATEWAY may remain unspecified ("-"). You should disable all default route management outside of Shorewall. If a default route is inadvertently added to the main table while Shorewall is started, then all policy routing will stop working except for those routing rules in the priority range 1-998. Although 'balance' is automatically assumed when ROUTE_BALANCE=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/rules:#SOURCE DEST PROVIDER PRIORITY - - shorewall 11999