arprefresh: fix some spelling
[olsrd.git] / README-Olsr-Extensions
index 6000f2a..5423e03 100644 (file)
@@ -221,20 +221,23 @@ More information on NIIT can be found at: http://wiki.freifunk.net/Niit
     5.) Smart gateways (asymmetric gateway tunnels)
 *******************************************************
 
+    5.1) Introduction
+
 The smart gateway mechanism was written by Markus Kittenberger and
 Henning Rogge to allow an OLSR user to directly choose their default
 Internet gateway instead of relying on the hop by hop decisions on
 the way to the gateway. OLSRd 0.6.0 can create an IPIP tunnel
-to the gateways OLSRd address to side-step the same nasty effects
+to the gateway's OLSRd address to side-step the same nasty effects
 described in the NAT-Threshold section.
 
 The smart gateway code can be split into two sections, one is
 responsible for announcing the existence of a smart gateway uplink
 and one (on the client nodes) to choose an uplink and create the
-tunnel to the gateway. It uses a modified (but backward compatible)
-special HNA to signal the gateways to the clients. The clients can
-use a plugin (or the integrated default code) to choose one of the
-available gateways and change it if necessary.
+tunnel to the gateway. The announcing code uses a modified (but
+backward compatible) special HNA to signal the gateways to the
+clients. The clients can use a plugin (or the integrated default
+code) to choose one of the available gateways and change it if
+necessary.
 
 The smart gateway system is setup by several configuration parameters,
 most of them with a sane default setting. The whole system can be
@@ -245,14 +248,96 @@ SmartGateway <yes/no>
 All other parameters will be ignored if SmartGateway is set to "no"
 (the default is "no").
 
-On the client side there is a single additional parameter which
-controls if you want to allow the selection of an outgoing ipv4
-gateway with NAT (Network Address Translation).
 
-SmartGatewayAllowNAT <yes/no>
+    5.2) Client Side
+
+1- SmartGatewayUseCount controls the maximum number of gateways that can be
+   in use at any given time. This setting is used to mitigate the effects of
+   breaking connections (due to the selection of a new gateway) on a dynamic
+   network.
+   The default setting is 1.
+2- SmartGatewayPolicyRoutingScript controles the policy routing script that is
+   executed during startup and shutdown of olsrd. The script is only executed
+   when SmartGatewayUseCount is set to a value larger than 1. The script must
+   setup policy routing rules such that multi-gateway mode works. A sample
+   script is included.
+   The default setting is 'not set'.
+3- SmartGatewayEgressInterfaces determines the egress interfaces that are part
+   of the multi-gateway setup and therefore only relevant when
+   SmartGatewayUseCount is larger than 1 (in which case it must be explicitly
+   set).
+   The default setting is 'not set'.
+4- SmartGatewayMarkOffsetEgress and SmartGatewayMarkOffsetTunnels determine
+   the ranges of policy routing rule markings that are used in a multi-gateway
+   setup. The ranges are not allowed to overlap. Both settings are only
+   relevant when a multi-gateway setup is used.
+   The default settings are 91 and 101 respectively.
+5- SmartGatewayAllowNAT controls whether you want to allow the selection
+   of an outgoing ipv4 gateway with NAT (Network Address Translation).
+   The default setting is "yes".
+6- SmartGatewayPeriod determines the period (in milliseconds) on which
+   a new smart gateway selection is performed.
+   The default setting is 10000 milliseconds.
+7- SmartGatewayStableCount determines the number of times the link state
+   database must be stable before a new smart gateway is selected.
+   The default setting is 6.
+8- SmartGatewayThreshold controls whether you want to allow re-selection
+   of a new outgoing gateway if its routing cost is lower or equal to the
+   configured percentage of the routing cost of the current gateway.
+   The default setting is 0, which disables it.
+9- SmartGatewayWeightExitLinkUp, SmartGatewayWeightExitLinkDown,
+   SmartGatewayWeightEtx and SmartGatewayDividerEtx control the weighing
+   of gateway bandwidth and ETX costs.
+
+   If SmartGatewayDividerEtx is zero then no weighing is performed (classical
+   behaviour). Classical behaviour only takes ETX costs into account when
+   choosing a gateway (select the 'nearest' gateway).
+
+   The weighing also takes the gateway bandwidths into account (select the
+   'nearest fat pipe' gateway).
+
+   Gateways that have zero bandwidth for either their uplink or downlink are
+   ignored.
+
+   * The Weighing Process
+   ======================
+
+     ** Configuration Parameters
+     ===========================
+     SmartGatewayWeightExitLinkUp   = gateway exit link uplink weight
+     SmartGatewayWeightExitLinkDown = gateway exit link downlink weight
+     SmartGatewayWeightEtx          = ETX path cost weight
+     SmartGatewayDividerEtx         = ETX path cost divider
+
+     ** Gateway Parameters
+     ===========================
+     gw->uplink   (Mbps)            = gateway exit link uplink  , in Mbps
+     gw->downlink (Mbps)            = gateway exit link downlink, in Mbps
+
+     ** Weighing Formula
+     ===================
+                          SmartGatewayWeightExitLinkUp
+     path_cost_weighed =  ---------------------------- +
+                                gw->uplink (Mbps)
+
+                          SmartGatewayWeightExitLinkDown
+                          ------------------------------ +
+                                gw->downlink (Mbps)
+
+                           SmartGatewayWeightEtx
+                          ---------------------- * path_cost
+                          SmartGatewayDividerEtx
+
+     ** Recommended Configuration Parameter Settings
+     ===============================================
+     SmartGatewayWeightExitLinkUp   = 1 (default is 1)
+     SmartGatewayWeightExitLinkDown = 1 (default is 1)
+     SmartGatewayWeightEtx          = 1 (default is 1)
+     SmartGatewayDividerEtx         = 4 (default is 0)
+
+
+    5.3) Uplink Side
 
-The uplink side of the smart gateway code has four parameters to
-set up the type of the uplink:
 1- SmartGatewayUplink defines which kind of uplink is exported to the
    other mesh nodes. The existence of the uplink is detected by looking
    for a local HNA of 0.0.0.0/0, ::ffff:0:0/96 or 2000::/3. The default
@@ -267,12 +352,12 @@ set up the type of the uplink:
    local IPv6 address to use the IPv6 gateway without any kind of address
    translation. The maximum prefix length is 64 bits,
    the default is ::/0 (no prefix).
+5- SmartGatewayAlwaysRemoveServerTunnel can be used to signal that the
+   server tunnel must always be removed on shutdown, irrespective of the
+   interface up/down state during startup.
+
 
-SmartGatewayThreshold <threshold>
-SmartGatewayUplink <none/ipv4/ipv6/both>
-SmartGatewayUplinkNAT <yes/no>
-SmartGatewaySpeed <uplink> <downlink>
-SmartGatewayPrefix <prefix>
+    5.4) Architecture & Notes
 
 On the smart gateway server (the OLSR instance announcing 'Internet here!' via
 HNA 0/0 or similar) the implicit tunl0 interface is used to forward incoming