1SHOREWALL-PROVIDERS(5)        Configuration Files       SHOREWALL-PROVIDERS(5)
2
3
4

NAME

6       providers - Shorewall Providers file
7

SYNOPSIS

9       /etc/shorewall/providers
10

DESCRIPTION

12       This file is used to define additional routing tables. You will want to
13       define an additional table if:
14
15       •   You have connections to more than one ISP or multiple connections
16           to the same ISP
17
18       •   You run Squid as a transparent proxy on a host other than the
19           firewall.
20
21       •   You have other requirements for policy routing.
22
23       Each entry in the file defines a single routing table.
24
25       If you wish to omit a column entry but want to include an entry in the
26       next column, use "-" for the omitted entry.
27
28       The columns in the file are as follows.
29
30       NAME - name
31           The provider name. Must be a valid shell variable name. The names
32           'local', 'main', 'default' and 'unspec' are reserved and may not be
33           used as provider names.
34
35       NUMBER - number
36           The provider number -- a number between 1 and 15. Each provider
37           must be assigned a unique value.
38
39       MARK (Optional) - value
40           A FWMARK value used in your shorewall-mangle(5)[1] file to direct
41           packets to this provider.
42
43           If PROVIDER_OFFSET is non-zero in shorewall.conf(5)[2], then the
44           value must be a multiple of 2^^PROVIDER_OFFSET. In all cases, the
45           number of significant bits may not exceed PROVIDER_OFFSET +
46           PROVIDER_BITS.
47
48       DUPLICATE - routing-table-name
49           The name of an existing table to duplicate to create this routing
50           table. May be main or the name of a previously listed provider. You
51           may select only certain entries from the table to copy by using the
52           COPY column below. This column should contain a dash ("-') when
53           USE_DEFAULT_RT=Yes in shorewall.conf(5)[2].
54
55       INTERFACE - interface[:address]
56           The name of the network interface to the provider. Must be listed
57           in shorewall-interfaces(5)[3]. In general, that interface should
58           not have the proxyarp or proxyndp option specified unless loose is
59           given in the OPTIONS column of this entry.
60
61               Important
62               For IPv6, if the interface is an Ethernet device and an IP
63               address is supplied, it should be the upstream router's
64               link-level address, not its global address.
65           Where more than one provider is serviced through a single
66           interface, the interface must be followed by a colon and the IP
67           address of the interface that is supplied by the associated
68           provider.
69
70       GATEWAY - {-|address[,mac]|detect|none}
71           The IP address of the provider's gateway router. Beginning with
72           Shorewall 4.6.2, you may also specify the MAC address of the
73           gateway when there are multiple providers serviced through the same
74           interface. When the MAC is not specified, Shorewall will detect the
75           MAC during firewall start or restart.
76
77           You can enter detect here and Shorewall will attempt to detect the
78           gateway automatically.
79
80           Beginning with Shorewall 5.0.6, you may also enter none. This
81           causes creation of a routing table with no default route in it.
82
83           For PPP devices, you may omit this column.
84
85       OPTIONS (Optional) - [-|option[,option]...]
86           A comma-separated list selected from the following. The order of
87           the options is not significant but the list may contain no embedded
88           white-space.
89
90           autosrc
91               Added in Shorewall 4.5.17. Causes a host route to the
92               provider's gateway router to be added to the provider's routing
93               table. This is the default behavior unless overridden by a
94               following noautosrc option.
95
96           track
97               If specified, inbound connections on this interface are to be
98               tracked so that responses may be routed back out this same
99               interface.
100
101               You want to specify track if internet hosts will be connecting
102               to local servers through this provider.
103
104               Beginning with Shorewall 4.4.3, track defaults to the setting
105               of the TRACK_PROVIDERS option in shorewall.conf[2] (5). If you
106               set TRACK_PROVIDERS=Yes and want to override that setting for
107               an individual provider, then specify notrack (see below).
108
109           balance[=weight]
110               The providers that have balance specified will get outbound
111               traffic load-balanced among them. By default, all interfaces
112               with balance specified will have the same weight (1). You can
113               change the weight of an interface by specifying balance=weight
114               where weight is the weight of the route out of this interface.
115
116               Prior to Shorewall 5.1.1, when USE_DEFAULT_RT=Yes, balance=1 is
117               assumed unless the fallback, loose, load or tproxy option is
118               specified. Beginning with Shorewall 5.1.1, when
119               BALANCE_PROVIDERS=Yes, balance=1 is assumed unless the
120               fallback, loose, load or tproxy option is specified.I
121
122                   Caution
123                   In IPV6, the balance option does not cause balanced default
124                   routes to be created; it rather causes a sequence of
125                   default routes with different metrics to be created.
126
127           loose
128               Shorewall normally adds a routing rule for each IP address on
129               an interface which forces traffic whose source is that IP
130               address to be sent using the routing table for that interface.
131               Setting loose prevents creation of such rules on this
132               interface.
133
134           load=probability
135               Added in Shorewall 4.6.0. This option provides an alternative
136               method of load balancing based on probabilities. Providers to
137               be balanced are given a probability (a number 0 > n >= 1) with
138               up to 8 digits to the right of the decimal point. Beginning
139               with Shorewall 4.6.10, a warning is issued if the sum of the
140               probabilities is not 1.00000000.
141
142           noautosrc
143               Added in Shorewall 4.5.17. Prevents the addition of a host
144               route to the provider's gateway router from being added to the
145               provider's routing table. This option must be used with caution
146               as it can cause start and restart failures.
147
148           notrack
149               Added in Shorewall 4.4.3. When specified, turns off track.
150
151           optional (deprecated for use with providers that do not share an
152           interface)
153               If the interface named in the INTERFACE column is not up and
154               configured with an IPv4 address then ignore this provider. If
155               not specified, the value of the optional option for the
156               INTERFACE in shorewall-interfaces(5)[3] is assumed. Use of that
157               option is preferred to this one, unless an address is provider
158               in the INTERFACE column.
159
160           primary
161               Added in Shorewall 4.6.6, primary is equivalent to balance=1
162               and is preferred when the remaining providers specify fallback
163               or tproxy.
164
165           src=source-address
166               Specifies the source address to use when routing to this
167               provider and none is known (the local client has bound to the 0
168               address). May not be specified when an address is given in the
169               INTERFACE column. If this option is not used, Shorewall
170               substitutes the primary IP address on the interface named in
171               the INTERFACE column.
172
173           mtu=number
174               Specifies the MTU when forwarding through this provider. If not
175               given, the MTU of the interface named in the INTERFACE column
176               is assumed.
177
178           fallback[=weight]
179               Indicates that a default route through the provider should be
180               added to the default routing table (table 253). If a weight is
181               given, a balanced route is added with the weight of this
182               provider equal to the specified weight. If the option is given
183               without a weight, a separate default route is added through the
184               provider's gateway; the route has a metric equal to the
185               provider's NUMBER.
186
187               Prior to Shorewall 4.4.24, the option is ignored with a warning
188               message if USE_DEFAULT_RT=Yes in shorewall.conf.
189
190                   Caution
191                   In IPV6, specifying the fallback option on multiple
192                   providers does not cause balanced fallback routes to be
193                   created; it rather causes a sequence of fallback routes
194                   with different metrics to be created.
195
196           tproxy
197               Added in Shorewall 4.5.4. Used for supporting the TPROXY action
198               in shorewall-mangle(5). See
199               https://shorewall.org/Shorewall_Squid_Usage.html[4]. When
200               specified, the MARK, DUPLICATE and GATEWAY columns should be
201               empty, INTERFACE should be set to 'lo' and tproxy should be the
202               only OPTION. Only one tproxy provider is allowed.
203
204           hostroute
205               Added in Shorewall 4.5.21. This is the default behavior that
206               results in a host route to the defined GATEWAY being inserted
207               into the main routing table and into the provider's routing
208               table.  hostroute is required for older distributions but
209               nohostroute (below) is appropriate for recent distributions.
210               hostroute may interfere with Zebra's ability to add routes on
211               some distributions such as Debian 7. This option defaults to on
212               when BALANCE_PROVIDERS=Yes, in shorewall.conf(5)[2].
213
214           nohostroute
215               Added in Shorewall 4.5.21. nohostroute inhibits addition of a
216               host route to the defined GATEWAY being inserted into the main
217               routing table and into the provider's routing table.
218               nohostroute is not appropriate for older distributions but is
219               appropriate for recent distributions.  nohostroute allows
220               Zebra's to correctly add routes on some distributions such as
221               Debian 7. This option defaults to off when
222               BALANCE_PROVIDERS=Yes, in shorewall.conf(5)[2].
223
224           persistent
225               Added in Shorewall 5.0.2 and alters the behavior of the disable
226               command:
227
228               •   The provider's routing table still contains the apprioriate
229                   default route.
230
231               •   Unless the noautosrc option is specified, routing rules are
232                   generated to route traffic from the interfaces address(es)
233                   out of the provider's routing table.
234
235               •   Persistent routing rules in shorewall-rtrules(5)[5] are
236                   present.
237
238
239                   Note
240                   The generated script will attempt to reenable a disabled
241                   persistent provider during execution of the start, restart
242                   and reload commands. When persistent is not specified, only
243                   the enable and reenable commands can reenable the provider.
244
245                   Important
246                   RESTORE_DEFAULT_ROUTE=Yes in shorewall[6].conf is not
247                   recommended when the persistent option is used, as
248                   restoring default routes to the main routing table can
249                   prevent link status monitors such as foolsm from correctly
250                   detecting non-working providers.
251
252       COPY - [{none|interface[,interface]...}]
253           A comma-separated list of other interfaces on your firewall.
254           Wildcards specified using an asterisk ("*") are permitted (e.g.,
255           tun* ). Usually used only when DUPLICATE is main. Only copy routes
256           through INTERFACE and through interfaces listed here. If you only
257           wish to copy routes through INTERFACE, enter none in this column.
258
259           Beginning with Shorewall 4.5.17, blackhole, unreachable and
260           prohibit routes are no longer copied by default but may be copied
261           by including blackhole,unreachable and prohibit respectively in the
262           COPY list.
263

EXAMPLES

265       IPv4 Example 1:
266           You run squid in your DMZ on IP address 192.168.2.99. Your DMZ
267           interface is eth2
268
269                       #NAME   NUMBER  MARK DUPLICATE  INTERFACE GATEWAY       OPTIONS
270                       Squid   1       1    -          eth2      192.168.2.99  -
271
272       IPv4 Example 2:
273           eth0 connects to ISP 1. The IP address of eth0 is 206.124.146.176
274           and the ISP's gateway router has IP address 206.124.146.254.
275
276           eth1 connects to ISP 2. The IP address of eth1 is 130.252.99.27 and
277           the ISP's gateway router has IP address 130.252.99.254.
278
279           eth2 connects to a local network.
280
281                       #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY          OPTIONS            COPY
282                       ISP1  1       1    main      eth0      206.124.146.254 track,balance      eth2
283                       ISP2  2       2    main      eth1      130.252.99.254  track,balance      eth2
284
285       IPv6 Example 1:
286           You run squid in your DMZ on IP address 2002:ce7c:92b4:1::2. Your
287           DMZ interface is eth2
288
289                       #NAME   NUMBER  MARK DUPLICATE  INTERFACE GATEWAY              OPTIONS
290                       Squid   1       1    -          eth2      2002:ce7c:92b4:1::2  -
291
292       IPv6 Example 2:
293           eth0 connects to ISP 1. The ISP's gateway router has IP address
294           2001:ce7c:92b4:1::2.
295
296           eth1 connects to ISP 2. The ISP's gateway router has IP address
297           2001:d64c:83c9:12::8b.
298
299           eth2 connects to a local network.
300
301                       #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY               OPTIONS    COPY
302                       ISP1  1       1    main      eth0     2001:ce7c:92b4:1::2   track      eth2
303                       ISP2  2       2    main      eth1     2001:d64c:83c9:12::8b track      eth2
304

FILES

306       /etc/shorewall/providers
307
308       /etc/shorewall6/providers
309

SEE ALSO

311       https://shorewall.org/MultiISP.html[6]
312
313       https://shorewall.org/configuration_file_basics.htm#Pairs[7]
314
315       shorewall(8)
316

NOTES

318        1. shorewall-mangle(5)
319           https://shorewall.org/manpages/shorewall-mangle.html
320
321        2. shorewall.conf(5)
322           https://shorewall.org/manpages/shorewall.conf.html
323
324        3. shorewall-interfaces(5)
325           https://shorewall.org/manpages/shorewall-interfaces.html
326
327        4. https://shorewall.org/Shorewall_Squid_Usage.html
328           https://shorewall.org/Shorewall_Squid_Usage.html
329
330        5. shorewall-rtrules(5)
331           https://shorewall.org/manpages/shorewall-rtrules.html
332
333        6. https://shorewall.org/MultiISP.html
334           https://shorewall.org/MultiISP.html
335
336        7. https://shorewall.org/configuration_file_basics.htm#Pairs
337           https://shorewall.org/configuration_file_basics.htm#Pairs
338
339
340
341Configuration Files               09/24/2020            SHOREWALL-PROVIDERS(5)
Impressum