extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-11-21 23:23:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Doc updates

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9355 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2009-01-30 22:20:22 +00:00
parent 22180d5804
commit 7fcba909df
3 changed files with 196 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
docs/MultiISP.xml
View File

@ -103,8 +103,9 @@
<listitem>
<para>For most routing applications, <ulink
url="http://www.quagga.net/">Quagga</ulink> is a better
solution.</para>
url="http://www.quagga.net/">Quagga</ulink> is a better solution
although it requires that your ISPs offer routing protocol
support.</para>
</listitem>
</itemizedlist>
@ -618,13 +619,136 @@
<filename>/etc/shorewall/route_rules</filename>.</para>
</section>
<section id="Provider_Doesnt">
<title>What an entry in the Providers File Does NOT Do</title>
<section id="swping">
<title>Gateway Monitoring and Failover</title>
<para>Given that Shorewall is simply a tool to configure Netfilter and
does not run continuously in your system, entries in the providers file
<emphasis role="bold">do not provide any automatic failover in the event
of failure of one of your Internet connections</emphasis>.</para>
<para>Beginning with Shorewall 4.2.6, Shorewall includes a sample
monitoring script <filename>swping</filename>. The
<filename>swping</filename> file is available in the main directory
contained in the Shorewall-common tarball and is included in the
Shorewall-common documentation directory on the Shorewall-common
RPM.</para>
<para>For those not on 4.2.6 yet, the script may be downloaded from
<ulink
url="http://www.shorewall.net/pub/shorewall/contrib/MultiISP-failover/">http://www.shorewall.net/pub/shorewall/contrib/MultiISP-failover/</ulink>.</para>
<important>
<para>These samples are offered <emphasis>as is</emphasis> — they work
for me but I don't make any claim that they will work for anyone else.
But if you have a need for automated link monitoring, they offer you a
place to start.</para>
</important>
<para>The script monitors two interfaces but it is a trivial exercise to
extend it to more than two. At the top are a number of variables to
set:</para>
<programlisting># The commands to run when the status of a line changes. Both commands will be executed.
#
COMMAND1=
COMMAND2="ip -4 route ls"
...
#
# Interfaces to monitor -- you may use shell variables from your params file
#
IF1=eth0
IF2=eth1
#
# Sites to Ping. Must not depend on the associated interface having a default route through it.
#
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</programlisting>
<para>If you leave COMMAND1 empty, the script sets its value
automatically depending on whether Shorewall-lite is installed.</para>
<para>When the status of an interface changes:</para>
<itemizedlist>
<listitem>
<para>For each interface, a file is placed in /etc/shorewall to
record the status of the interface: either 0 (UP) or 1 (DOWN). The
name of the file is<emphasis> interface</emphasis>.status where
<emphasis>interface</emphasis> is the interface (e.g.,
<filename>eth0.status</filename>).</para>
</listitem>
<listitem>
<para>A <command>shorewall -f restart</command> command is executed
(<command>shorewall-lite restart</command>, if Shorewall-lite is
installed).</para>
</listitem>
<listitem>
<para>The contents of the main routing table are displayed.</para>
</listitem>
</itemizedlist>
<para>The .status files are intended to be used with the following
<filename>/etc/shorewall/isusable</filename> script.<programlisting>local status=0
case $1 in
<emphasis role="bold">eth0|eth1</emphasis>)
[ -f /etc/shorewall/${1}.status ] &amp;&amp; status=$(cat /etc/shorewall/${1}.status)
;;
esac
return $status</programlisting></para>
<para>Be sure that you modify the interface names to match your
configuration.</para>
<para>Also included is a sample init script
(<filename>swping.init</filename>) to start the monitoring daemon. Copy
it to<filename> /etc/init.d/swping</filename> and use your
distribution's SysV init tools to cause it to be run at boot. It works
on <trademark>OpenSuSE</trademark> 11.0 -- YMMV. Modify the PROG and
STATEDIR variables as needed.</para>
<para>This simple script has a number of limitations:</para>
<orderedlist>
<listitem>
<para>It only works on IPv4 (but is easy to modify for IPv6)</para>
</listitem>
<listitem>
<para>It's method of determining whether an interface is up or down
is crude. You will normally specify the default gateway for each
provider as the sites to ping and being able to ping the default
gateway is not a surefire indication that the provider is usable.
The method of determining whether a site is up or down is also
crude.</para>
</listitem>
<listitem>
<para>Because of the crudeness of the algorithm, hysteresis may
occur.</para>
</listitem>
<listitem>
<para>It is tricky to configure a system such that a system works
correctly when one of its providers is down unless you largely don't
care which interface is used.</para>
</listitem>
</orderedlist>
</section>
<section id="Martians">
@ -1007,7 +1131,7 @@ gateway:~ #</programlisting>Note that because we used a priority of 1000, the
a USE_DEFAULT_RT option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
<para>One of the drawbacks of the Mulit-ISP support as described in the
<para>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 <link linkend="Openvpn">one of the
@ -1136,7 +1260,7 @@ shorewall 2 2 - eth0 192.168.1.254 track,balance=2,optional<
<para>Example:</para>
<para>This is our home network circa fall 2008. We have two internet
<para>This is our home network circa fall 2008. We have two Internet
providers:</para>
<orderedlist>
@ -1339,11 +1463,12 @@ wlan0 192.168.0.0/24</programlisting><note>
</itemizedlist>
<para>As a consequence, I have disabled all route filtering on the
firewall and do not use the <emphasis role="bold">balance</emphasis>
option in <filename>/etc/shorewall/providers</filename>. The default route
in the main table is established by DHCP. By specifying the <emphasis
role="bold">fallback</emphasis> option on Avvanta, I ensure that there is
still a default route if Comcast is down.</para>
firewall and only use the <emphasis role="bold">balance</emphasis> option
in <filename>/etc/shorewall/providers</filename> on the Comcast provider
whose default route in the main table is established by DHCP. By
specifying the <emphasis role="bold">fallback</emphasis> option on
Avvanta, I ensure that there is still a default route if Comcast is down.
<link linkend="swping">swping</link> is used to monitor the links.</para>
<para><filename>/etc/sysctl.conf</filename>:</para>
@ -1351,13 +1476,19 @@ wlan0 192.168.0.0/24</programlisting><note>
<para><filename>/etc/shorewall/shorewall.conf</filename>:</para>
<programlisting>ROUTE_FILTER=No</programlisting>
<programlisting>ROUTE_FILTER=No
RESTORE_DEFAULT_ROUTE=No</programlisting>
<para>The RESTORE_DEFAULT_ROUTE option was added in Shorewall-perl 4.2.6
and causes the default route in the main table to be deleted when the
Comcast link is unavailable. That way, the default route in the default
table will be used until Comcast is available again.</para>
<para><filename>/etc/shorewall/providers</filename>:</para>
<programlisting>#NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
Avvanta 1 0x100 main eth0 206.124.146.254 track,loose,fallback eth2,eth4,tun*
Comcast 2 0x200 main eth3 detect track eth2,eth4,tun*
Comcast 2 0x200 main eth3 detect track,balance eth2,eth4,tun*
#LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE</programlisting>
<para>The <emphasis role="bold">loose</emphasis> option on Avvanta results
@ -1372,7 +1503,7 @@ Comcast 2 0x200 main eth3 detect track
<para><filename>/etc/shorewall/route_rules</filename>:</para>
<programlisting>#SOURCE DEST PROVIDER PRIORITY
- 162.20.0.0.24 main 1000 # Addresses assigned by routed OpenVPN server
- 172.20.0.0/24 main 1000 # Addresses assigned by routed OpenVPN server
206.124.146.176/30 - Avvanta 26000
206.124.146.180 - Avvanta 26000
- 216.168.3.44 Avvanta 26000 # Avvanta NNTP Server -- verifies source IP address
@ -1471,8 +1602,7 @@ COMMENT Masquerade Local Network
eth3 0.0.0.0/0
eth0 !206.124.146.0/24 206.124.146.179
#LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE
</programlisting>
#LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE</programlisting>
<para>All traffic leaving eth3 must use the dynamic IP address assigned to
that interface as the SOURCE address. All traffic leaving eth0 that does

47
docs/traffic_shaping.xml
View File

@ -594,33 +594,36 @@ ppp0 6000kbit 500kbit</programlisting>
file.</para>
<para>Because tcrules are not stateful, it is necessary to understand
basic IP socket operation. Here is an excerpt from a post on the
Shorewall Users list:<blockquote>
basic IP socket operation. Here is an edited excerpt from a post on
the Shorewall Users list:<blockquote>
<para>For the purposes of this discussion, the world is separated
into clients and servers. Servers provide services to
clients.</para>
<para>When a server starts, it creates a socket and *binds* the
socket to an *address*. For AF_INET (IPv4) and AF_INET6 (IPv6)
sockets, that address is an ordered triple consisting of an IPv4
or IPv6 address, a protocol, and possibly a port number. Port
numbers are only used when the protocol is TCP, UDP, SCTP or SCCP.
<para>When a server starts, it creates a socket and
<emphasis>binds</emphasis> the socket to an
<emphasis>address</emphasis>. For AF_INET (IPv4) and AF_INET6
(IPv6) sockets, that address is an ordered triple consisting of an
IPv4 or IPv6 address, a protocol, and possibly a port number. Port
numbers are only used when the protocol is TCP, UDP, SCTP or DCCP.
The protocol and port number used by a server are typically
well-known so that clients will be able to connect to it. So SSH
servers bind to TCP port 22, SMTP servers bind to TCP port 25,
etc. We will call this port the SERVER PORT. </para>
well-known so that clients will be able to connect to it or send
datagrams to it. So SSH servers bind to TCP port 22, SMTP servers
bind to TCP port 25, etc. We will call this port the SERVER
PORT.</para>
<para>When a client want to use the service provided by a server,
it also creates a socket. Like the server's socket, the client's
socket must also be bound to an address. But in the case of the
client, the socket is usually given an automatic address binding.
For AF_INET and AF_INET6 sockets. the IP address is the IP address
of the client system (loose generalization) and the port number is
selected from a *local port range*. On Linux systems, the local
port ranges can be seen by 'cat
/proc/sys/net/ipv4/ip_local_port_range'. So it is not possible in
advance to determine what port the client will be using. Whatever
it is, we'll call it the CLIENT PORT. </para>
it also creates a socket and, like the server's socket, the
client's socket must be bound to an address. But in the case of
the client, the socket is usually given an automatic address
binding. For AF_INET and AF_INET6 sockets. the IP address is the
IP address of the client system (loose generalization) and the
port number is selected from a <firstterm>local port
range</firstterm>. On Linux systems, the local port range can be
seen by <command>cat
/proc/sys/net/ipv4/ip_local_port_range</command>. So it is not
possible in advance to determine what port the client will be
using. Whatever it is, we'll call it the CLIENT PORT.</para>
<para>Now: <blockquote>
<para>Packets sent from the client to the server will
@ -639,8 +642,8 @@ ppp0 6000kbit 500kbit</programlisting>
</blockquote></para>
<para>Since the SERVER PORT is generally the only port known ahead
of time, we therefore categorize traffic from the server to the
client using the SOURCE PORT.</para>
of time, we must categorize traffic from the server to the client
using the SOURCE PORT.</para>
</blockquote></para>
</important>

21
manpages/shorewall.conf.xml
View File

@ -1247,6 +1247,27 @@ net all DROP info</programlisting>then the chain name is 'net2all'
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">RESTORE_DEFAULT_ROUTE=</emphasis>[<emphasis
role="bold">Yes</emphasis>|<emphasis role="bold">No</emphasis>]</term>
<listitem>
<para>Added in Shorewall 4.2.6, this option determines whether to
restore the default route saved when here are 'balance' providers
defined but all of them are down.</para>
<para>The default is RESTORE_DEFAULT_ROUTE=Yes which preserves the
pre-4.2.6 behavior.</para>
<para>RESTORE_DEFAULT_ROUTE=No is appropriate when you don't want a
default route in the main table (USE_DEFAULT_RT=No) or in the
default table (USE_DEFAULT_RT=Yes) when there are no balance
providers available. In that case, RESTORE_DEFAULT_ROUTE=No will
cause any default route in the relevant table to be deleted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">RESTOREFILE=</emphasis><emphasis>filename</emphasis></term>