Add LSM to Multi-ISP doc

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9523 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

docs/MultiISP.xml

@@ -1075,9 +1075,15 @@ shorewall     2    2    -        eth0    192.168.1.254 track,balance=2,optional<
 -           -         shorewall       11999</programlisting></para>
     </section>
 
-    <section id="swping">
+    <section id="LinkMonitor">
       <title>Gateway Monitoring and Failover</title>
 
+      <para>There are a couple of options available for monitoring the status
+      of provider links and taking action when a failure occurs.</para>
+
+      <section id="swping">
+        <title>SWPING</title>
+
         <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
@@ -1092,29 +1098,29 @@ shorewall     2    2    -        eth0    192.168.1.254 track,balance=2,optional<
         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
+          <para>These samples are offered <emphasis>as is</emphasis> — they
-        for me but I don't make any claim that they will work for anyone else.
+          work for me but I don't make any claim that they will work for
-        But if you have a need for automated link monitoring, they offer you a
+          anyone else. But if you have a need for automated link monitoring,
-        place to start.</para>
+          they offer you a place to start.</para>
         </important>
 
-      <para>The script should be copied to a directory on root's PATH such as
+        <para>The script should be copied to a directory on root's PATH such
-      <filename>/usr/local/sbin/</filename>.</para>
+        as <filename>/usr/local/sbin/</filename>.</para>
 
         <para>The script works by sending pings to <emphasis>target</emphasis>
         IP addresses through each external interface. These targets must not
         depend on any routes other than those that are present in the main
-      routing table. That ensures that a route is available to the target even
+        routing table. That ensures that a route is available to the target
-      when the target's interface is not working and Shorewall has omitted it
+        even when the target's interface is not working and Shorewall has
-      from the routing configuration. An interface is assumed to be
+        omitted it from the routing configuration. An interface is assumed to
-      <firstterm>up</firstterm> when a specified number (UP_COUNT) of
+        be <firstterm>up</firstterm> when a specified number (UP_COUNT) of
-      consecutive ping operations succeed. Similarly, an interface is assumed
+        consecutive ping operations succeed. Similarly, an interface is
-      to be <firstterm>down</firstterm> when a specified number (DOWN_COUNT)
+        assumed to be <firstterm>down</firstterm> when a specified number
-      of consecutive ping operations fail. You can specify the interval
+        (DOWN_COUNT) of consecutive ping operations fail. You can specify the
-      between pings (PING_INTERVAL).</para>
+        interval between pings (PING_INTERVAL).</para>
 
-      <para>The script monitors two interfaces but it is a trivial exercise to
+        <para>The script monitors two interfaces but it is a trivial exercise
-      extend it to more than two. At the top are a number of variables to
+        to extend it to more than two. At the top are a number of variables to
         set:</para>
 
         <programlisting>#
@@ -1173,9 +1179,9 @@ DOWN_COUNT=2</programlisting>
           </listitem>
 
           <listitem>
-          <para>A <command>shorewall -f restart</command> command is executed
+            <para>A <command>shorewall -f restart</command> command is
-          (<command>shorewall-lite restart</command>, if Shorewall-lite is
+            executed (<command>shorewall-lite restart</command>, if
-          installed).</para>
+            Shorewall-lite is installed).</para>
           </listitem>
 
           <listitem>
@@ -1198,8 +1204,8 @@ return $status</programlisting></para>
         configuration.</para>
 
         <para>Also included is a sample init script
-      (<filename>swping.init</filename>) to start the monitoring daemon. Copy
+        (<filename>swping.init</filename>) to start the monitoring daemon.
-      it to<filename> /etc/init.d/swping</filename> and use your
+        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>
@@ -1223,9 +1229,9 @@ fi</programlisting></para>
 
         <orderedlist>
           <listitem>
-          <para>It only works on IPv4 or IPv6 but not both at once. So if you
+            <para>It only works on IPv4 or IPv6 but not both at once. So if
-          want to monitor both IPv4 and IPv6, you need to clone the script are
+            you want to monitor both IPv4 and IPv6, you need to clone the
-          run two copies; one for IPv4 and one for IPv6.</para>
+            script are run two copies; one for IPv4 and one for IPv6.</para>
           </listitem>
 
           <listitem>
@@ -1234,12 +1240,12 @@ fi</programlisting></para>
           </listitem>
 
           <listitem>
-          <para>It's method of determining whether an interface is up or down
+            <para>It's method of determining whether an interface is up or
-          is crude. You will normally specify the default gateway for each
+            down is crude. You will normally specify the default gateway for
-          provider as the sites to ping and being able to ping the default
+            each provider as the sites to ping and being able to ping the
-          gateway is not a surefire indication that the provider is usable.
+            default gateway is not a surefire indication that the provider is
-          The method of determining whether a site is up or down is also
+            usable. The method of determining whether a site is up or down is
-          crude.</para>
+            also crude.</para>
           </listitem>
 
           <listitem>
@@ -1248,13 +1254,159 @@ fi</programlisting></para>
           </listitem>
 
           <listitem>
-          <para>It is tricky to configure a system such that the system works
+            <para>It is tricky to configure a system such that the system
-          correctly when one of its providers is down unless you largely don't
+            works correctly when one of its providers is down unless you
-          care which interface is used.</para>
+            largely don't care which interface is used.</para>
           </listitem>
         </orderedlist>
       </section>
 
+      <section id="lsm">
+        <title>Link Status Monitor (LSM)</title>
+
+        <para><ulink url="http://lsm.foobar.fi/">Link Status Monitor</ulink>
+        was written by Mika Ilmaranta &lt;ilmis at nullnet.fi&gt; and performs
+        more sophisticated monitoring than the simple swping script described
+        in the preceding section.</para>
+
+        <para>I personally use LSM here at shorewall.net. Here are my relevant
+        configuration files:</para>
+
+        <para><filename>/etc/shorewall/isusable</filename>:</para>
+
+        <programlisting>local status
+status=0
+
+case $1 in
+    eth0|eth3)
+        [ -f /etc/shorewall/${1}.status ] &amp;&amp; status=$(cat /etc/shorewall/${1}.status)
+        ;;
+esac
+
+return $status</programlisting>
+
+        <para><filename>/etc/shorewall/started</filename>:</para>
+
+        <programlisting>###############################################################################
+# My 'restored' script calls this one if there is no lsm process running
+###############################################################################
+if [ "$COMMAND" = start -o "$COMMAND" = restore ]; then
+   killproc lsm 2&gt; /dev/null
+   cat &lt;&lt;EOF &gt; /etc/lsm/shorewall.conf
+connection {
+    name=Avvanta
+    checkip=206.124.146.254
+    device=eth0
+    ttl=2
+}
+
+connection {
+    name=Comcast
+    checkip=$ETH3_GATEWAY
+    device=eth3
+    ttl=1
+}
+EOF
+   rm -f /etc/shorewall/*.status
+   /usr/sbin/lsm /etc/lsm/lsm.conf &gt;&gt; /var/log/lsm
+fi</programlisting>
+
+        <para>eth3 has a dynamic IP address so I need to use the
+        Shorewall-detected gateway address ($ETH3_GATEWAY).</para>
+
+        <para><filename>/etc/shorewall/restored</filename>:</para>
+
+        <programlisting>if [ -z "$(ps ax | grep 'lsm ' | grep -v 'grep ' )" ]; then
+   run_started_exit
+fi</programlisting>
+
+        <para><filename>/etc/lsm/lsm.conf</filename>:</para>
+
+        <programlisting>#
+# 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=
+  device=eth0
+  ttl=64
+}
+
+include /etc/lsm/shorewall.conf</programlisting>
+
+        <para><filename>/etc/lsm/script</filename><programlisting>#!/bin/sh
+#
+# (C) 2009 Mika Ilmaranta &lt;ilmis@nullnet.fi&gt;
+# (C) 2009 Tom Eastep &lt;teastep@shorewall.net&gt;
+#
+# 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 &lt;&lt;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 ] &amp;&amp; state=0 || state=1
+
+echo $state &gt; /etc/shorewall/${DEVICE}.status
+
+/sbin/shorewall -f restart &gt;&gt; /var/log/lsm 2&gt;&amp;1
+
+/sbin/shorewall show routing &gt;&gt; /var/log/lsm
+
+exit 0;
+
+#EOF</programlisting>:</para>
+      </section>
+    </section>
+
     <section id="Shared">
       <title>Two Providers Sharing an Interface</title>