Fix cluster group update

[l2tpns.git] / Docs / manual.html

diff --git a/Docs/manual.html b/Docs/manual.html
index 0227ac3..384fe9a 100644 (file)
--- a/Docs/manual.html
+++ b/Docs/manual.html
@@ -52,21 +52,22 @@ H3 {
     <LI><A HREF="#Interception">Interception</A></LI>
     <LI><A HREF="#Authentication">Authentication</A></LI>
     <LI><A HREF="#Plugins">Plugins</A></LI>
     <LI><A HREF="#Interception">Interception</A></LI>
     <LI><A HREF="#Authentication">Authentication</A></LI>
     <LI><A HREF="#Plugins">Plugins</A></LI>

-    <LI><A HREF="#Walled Garden">Walled Garden</A></LI>
+    <LI><A HREF="#WalledGarden">Walled Garden</A></LI>
+    <LI><A HREF="#Filtering">Filtering</A></LI>

     <LI><A HREF="#Clustering">Clustering</A></LI>
     <LI><A HREF="#Routing">Routing</A></LI>
     <LI><A HREF="#Performance">Performance</A></LI>
 </OL>
 
 <H2 ID="Overview">Overview</H2>
     <LI><A HREF="#Clustering">Clustering</A></LI>
     <LI><A HREF="#Routing">Routing</A></LI>
     <LI><A HREF="#Performance">Performance</A></LI>
 </OL>
 
 <H2 ID="Overview">Overview</H2>

-l2tpns is half of a complete L2TP implementation.  It supports only the
-LNS side of the connection.<P>
+l2tpns a complete L2TP implementation. It supports the LAC, LNS and
+ PPPOE server.<P>

 
 L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2
 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection.  l2tpns
 implements PPP over L2TP only.<P>
 
 
 L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2
 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection.  l2tpns
 implements PPP over L2TP only.<P>
 

-There are a couple of other L2TP imlementations, of which <A
+There are a couple of other L2TP implementations, of which <A

 HREF="http://sourceforge.net/projects/l2tpd">l2tpd</A> is probably the
 most popular.  l2tpd also will handle being either end of a tunnel, and
 is a lot more configurable than l2tpns.  However, due to the way it works,
 HREF="http://sourceforge.net/projects/l2tpd">l2tpd</A> is probably the
 most popular.  l2tpd also will handle being either end of a tunnel, and
 is a lot more configurable than l2tpns.  However, due to the way it works,


@@ -86,7 +87,7 @@ included.<P>
 <BR>
 <EM>Documentation is not my best skill.  If you find any problems
 with this document, or if you wish to contribute, please email <A
 <BR>
 <EM>Documentation is not my best skill.  If you find any problems
 with this document, or if you wish to contribute, please email <A

-HREF="mailto:david@dparrish.com?subject=L2TPNS+Documentation">david@dparrish.com</A>.</EM><P>
+HREF="mailto:l2tpns-users@lists.sourceforge.net?subject=L2TPNS+Documentation">the mailing list</A>.</EM><P>

 
 <H2 ID="Installation">Installation</H2>
 <H3 ID="Requirements">Requirements</H3>
 
 <H2 ID="Installation">Installation</H2>
 <H3 ID="Requirements">Requirements</H3>


@@ -146,6 +147,7 @@ set ipaddress 192.168.1.1
 set boolean true
 </PRE>
 
 set boolean true
 </PRE>
 

+<P>

 <UL>
 <LI><B>debug</B> (int)<BR>
 Sets the level of messages that will be written to the log file.  The value
 <UL>
 <LI><B>debug</B> (int)<BR>
 Sets the level of messages that will be written to the log file.  The value


@@ -162,22 +164,36 @@ highest.  A rough description of the levels is:
 Note that the higher you set the debugging level, the slower the program
 will run.  Also, at level 5 a LOT of information will be logged.  This should
 only ever be used for working out why it doesn't work at all.
 Note that the higher you set the debugging level, the slower the program
 will run.  Also, at level 5 a LOT of information will be logged.  This should
 only ever be used for working out why it doesn't work at all.

-<P>

 </LI>
 
 <LI><B>log_file</B> (string)<BR>
 This will be where all logging and debugging information is written
 </LI>
 
 <LI><B>log_file</B> (string)<BR>
 This will be where all logging and debugging information is written

-to.  This can be either a filename, such as <EM>/var/log/l2tpns</EM>, or
+to.  This may be either a filename, such as <EM>/var/log/l2tpns</EM>, or

 the special magic string <EM>syslog:facility</EM>, where <EM>facility</EM>
 is any one of the syslog logging facilities, such as local5.
 the special magic string <EM>syslog:facility</EM>, where <EM>facility</EM>
 is any one of the syslog logging facilities, such as local5.

-<P>
+</LI>
+
+<LI><B>pid_file</B> (string)<BR>
+If set, the process id will be written to the specified file.  The
+value must be an absolute path.

 </LI>
 
 <LI><B>l2tp_secret</B> (string)<BR>
 </LI>
 
 <LI><B>l2tp_secret</B> (string)<BR>

-This sets the string that l2tpns will use for authenticating tunnel request.
-This must be the same as the LAC, or authentication will fail.  This will
-only actually be used if the LAC requests authentication.
-<P>
+The secret used by l2tpns for authenticating tunnel request.  Must be
+the same as the LAC, or authentication will fail.  Only actually be
+used if the LAC requests authentication.
+</LI>
+
+<LI><B>l2tp_mtu</B> (int)<BR>
+MTU of interface for L2TP traffic (default: 1500).  Used to set link
+MRU and adjust TCP MSS.
+</LI>
+
+<LI><B>ppp_restart_time</B> (int)<BR>
+<B>ppp_max_configure</B> (int)<BR>
+<B>ppp_max_failure</B> (int)<BR>
+PPP counter and timer values, as described in &sect;4.1 of
+<a href="ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt">RFC1661</a>.

 </LI>
 
 <LI><B>primary_dns</B> (ip address)
 </LI>
 
 <LI><B>primary_dns</B> (ip address)


@@ -185,46 +201,94 @@ only actually be used if the LAC requests authentication.
 Whenever a PPP connection is established, DNS servers will be sent to the
 user, both a primary and a secondary.  If either is set to 0.0.0.0, then that
 one will not be sent.
 Whenever a PPP connection is established, DNS servers will be sent to the
 user, both a primary and a secondary.  If either is set to 0.0.0.0, then that
 one will not be sent.

-<P>
-</LI>
-
-<LI><B>save_state</B> (boolean)<BR>
-When l2tpns receives a STGTERM it will write out its current
-ip_address_pool, session and tunnel tables to disk prior to exiting to
-be re-loaded at startup.  The validity of this data is obviously quite
-short and the intent is to allow an sessions to be retained over a
-software upgrade.
-<P>

 </LI>
 
 <LI><B>primary_radius</B> (ip address)
 <LI><B>secondary_radius</B> (ip address)<BR>
 </LI>
 
 <LI><B>primary_radius</B> (ip address)
 <LI><B>secondary_radius</B> (ip address)<BR>

-This sets the radius servers used for both authentication and
-accounting.  If the primary server does not respond, then the
-secondary radius server will be tried.
-<P>
+Sets the RADIUS servers used for both authentication and accounting. 
+If the primary server does not respond, then the secondary RADIUS
+server will be tried.<br>
+<strong>Note:</strong> in addition to the source IP address and
+identifier, the RADIUS server <strong>must</strong> include the source
+port when detecting duplicates to supress (in order to cope with a
+large number of sessions comming on-line simultaneously l2tpns uses a
+set of udp sockets, each with a seperate identifier).
+</LI>
+
+<LI><B>primary_radius_port</B> (short)
+<LI><B>secondary_radius_port</B> (short)<BR>
+Sets the authentication ports for the primary and secondary RADIUS
+servers.  The accounting port is one more than the authentication
+port.  If no RADIUS ports are given, the authentication port defaults
+to 1645, and the accounting port to 1646.

 </LI>
 
 <LI><B>radius_accounting</B> (boolean)<BR>
 </LI>
 
 <LI><B>radius_accounting</B> (boolean)<BR>

-If set to true, then radius accounting packets will be sent.  This
+If set to true, then RADIUS accounting packets will be sent.  This

 means that a Start record will be sent when the session is
 successfully authenticated, and a Stop record will be sent when the
 session is closed.
 means that a Start record will be sent when the session is
 successfully authenticated, and a Stop record will be sent when the
 session is closed.

-<P>

 </LI>
 
 <LI><B>radius_secret</B> (string)<BR>
 </LI>
 
 <LI><B>radius_secret</B> (string)<BR>

-This secret will be used in all radius queries.  If this is not set then
-radius queries will fail.
-<P>
+This secret will be used in all RADIUS queries.  If this is not set then
+RADIUS queries will fail.
+</LI>
+
+<LI><B>radius_authtypes</B> (string)</BR>
+A comma separated list of supported RADIUS authentication methods
+(<B>pap</B> or <B>chap</B>), in order of preference (default <B>pap</B>).
+</LI>
+
+<LI><B>radius_dae_port</B> (short)<BR>
+Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization)
+requests (default: <B>3799</B>).
+</LI>
+
+<LI><B>allow_duplicate_users</B> (boolean)</BR>
+Allow multiple logins with the same username.  If false (the default),
+any prior session with the same username will be dropped when a new
+session is established.

 </LI>
 
 <LI><B>bind_address</B> (ip address)<BR>
 </LI>
 
 <LI><B>bind_address</B> (ip address)<BR>

-When the tun interface is created, it is assigned the address
-specified here.  If no address is given, 1.1.1.1 is used.  Packets
-containing user traffic should be routed via this address if given,
-otherwise the primary address of the machine.
-<P>
+It's the listen address of the l2tp udp protocol sent and received
+to LAC. This address is also assigned to the tun interface if no
+iftun_address is specified. Packets containing user traffic should be
+routed via this address if given, otherwise the primary address of the
+machine.
+</LI>
+
+<LI><B>iftun_address</B> (ip address)<BR>
+This parameter is used when you want a tun interface address different
+from the address of "bind_address" (For use in cases of specific configuration).
+If no address is given to iftun_address and bind_address, 1.1.1.1 is used.
+</LI>
+
+<LI><B>bind_multi_address</B> (ip address)<BR>
+This parameter permit to listen several addresss of the l2tp udp protocol
+(and set several address to the tun interface).
+<BR>
+WHEN this parameter is set, It OVERWRITE the parameters "bind_address"
+and "iftun_address".
+<BR>
+these can be interesting when you want do load-balancing in cluster mode
+of the uploaded from the LAC. For example you can set a bgp.prepend(MY_AS)
+for Address1 on LNS1 and a bgp.prepend(MY_AS) for Address2 on LNS2
+(see BGP AS-path prepending).
+<BR>
+example of use with 2 address:
+<BR>
+set bind_multi_address "64.14.13.41, 64.14.13.42"
+
+</LI>
+
+<LI><B>tundevicename</B> (string)<BR>
+Name of the tun interface (default: "tun0").
+</LI>
+
+<LI><B>peer_address</B> (ip address)<BR>
+Address to send to clients as the default gateway.

 </LI>
 
 <LI><B>send_garp</B> (boolean)<BR>
 </LI>
 
 <LI><B>send_garp</B> (boolean)<BR>


@@ -232,14 +296,18 @@ Determines whether or not to send a gratuitous ARP for the
 bind_address when the server is ready to handle traffic (default: 
 true).<BR>
 This value is ignored if BGP is configured.
 bind_address when the server is ready to handle traffic (default: 
 true).<BR>
 This value is ignored if BGP is configured.

-<P>

 </LI>
 
 <LI><B>throttle_speed</B> (int)<BR>
 </LI>
 
 <LI><B>throttle_speed</B> (int)<BR>

-Sets the speed (in kbits/s) which sessions will be limited to.  If this is
-set to 0, then throttling will not be used at all.  Note: You can set this by
-the CLI, but changes will not affect currently connected users.
-<P>
+Sets the default speed (in kbits/s) which sessions will be limited to. 
+If this is set to 0, then throttling will not be used at all.  Note: 
+You can set this by the CLI, but changes will not affect currently
+connected users.
+</LI>
+
+<LI><B>throttle_buckets</B> (int)<BR>
+Number of token buckets to allocate for throttling.  Each throttled
+session requires two buckets (in and out).

 </LI>
 
 <LI><B>accounting_dir</B> (string)<BR>
 </LI>
 
 <LI><B>accounting_dir</B> (string)<BR>


@@ -250,89 +318,211 @@ Following the header is a single line for every connected user, fields
 separated by a space.<BR> The fields are username, ip, qos,
 uptxoctets, downrxoctets.  The qos field is 1 if a standard user, and
 2 if the user is throttled.
 separated by a space.<BR> The fields are username, ip, qos,
 uptxoctets, downrxoctets.  The qos field is 1 if a standard user, and
 2 if the user is throttled.

-<P>

 </LI>
 
 <LI><B>setuid</B> (int)<BR>
 After starting up and binding the interface, change UID to this.  This
 doesn't work properly.
 </LI>
 
 <LI><B>setuid</B> (int)<BR>
 After starting up and binding the interface, change UID to this.  This
 doesn't work properly.

-<P>

 </LI>
 
 <LI><B>dump_speed</B> (boolean)<BR>
 If set to true, then the current bandwidth utilization will be logged every
 second.  Even if this is disabled, you can see this information by running
 the <EM>uptime</EM> command on the CLI.
 </LI>
 
 <LI><B>dump_speed</B> (boolean)<BR>
 If set to true, then the current bandwidth utilization will be logged every
 second.  Even if this is disabled, you can see this information by running
 the <EM>uptime</EM> command on the CLI.

-<P>
-</LI>
-
-<LI><B>cleanup_interval</B> (int)<BR>
-Interval between regular cleanups (in seconds).
-<P>

 </LI>
 
 <LI><B>multi_read_count</B> (int)<BR>
 Number of packets to read off each of the UDP and TUN fds when
 returned as readable by select (default:  10).  Avoids incurring the
 unnecessary system call overhead of select on busy servers.
 </LI>
 
 <LI><B>multi_read_count</B> (int)<BR>
 Number of packets to read off each of the UDP and TUN fds when
 returned as readable by select (default:  10).  Avoids incurring the
 unnecessary system call overhead of select on busy servers.

-<P>

 </LI>
 
 <LI><B>scheduler_fifo</B> (boolean)<BR>
 Sets the scheduling policy for the l2tpns process to SCHED_FIFO.  This
 </LI>
 
 <LI><B>scheduler_fifo</B> (boolean)<BR>
 Sets the scheduling policy for the l2tpns process to SCHED_FIFO.  This

-causes the kernel to immediately preempt any currently SCHED_OTHER
+causes the kernel to immediately preempt any currently running SCHED_OTHER

 (normal) process in favour of l2tpns when it becomes runnable. 
 Ignored on uniprocessor systems.
 (normal) process in favour of l2tpns when it becomes runnable. 
 Ignored on uniprocessor systems.

-<P>

 </LI>
 
 <LI><B>lock_pages</B> (boolean)<BR>
 Keep all pages mapped by the l2tpns process in memory.
 </LI>
 
 <LI><B>lock_pages</B> (boolean)<BR>
 Keep all pages mapped by the l2tpns process in memory.

-<P>

 </LI>
 
 <LI><B>icmp_rate</B> (int)<BR>
 </LI>
 
 <LI><B>icmp_rate</B> (int)<BR>

-Maximum number of host unreachable icmp packets to send per second.
-<P>
+Maximum number of host unreachable ICMP packets to send per second.
+</LI>
+
+<LI><B>packet_limit</B> (int><BR>
+Maximum number of packets of downstream traffic to be handled each
+tenth of a second per session.  If zero, no limit is applied (default: 
+0).  Intended as a DoS prevention mechanism and not a general
+throttling control (packets are dropped, not queued).

 </LI>
 
 <LI><B>cluster_address</B> (ip address)<BR>
 Multicast cluster address (default:  239.192.13.13).  See the section
 on <A HREF="#Clustering">Clustering</A> for more information.
 </LI>
 
 <LI><B>cluster_address</B> (ip address)<BR>
 Multicast cluster address (default:  239.192.13.13).  See the section
 on <A HREF="#Clustering">Clustering</A> for more information.

-<P>

 </LI>
 
 <LI><B>cluster_interface</B> (string)<BR>
 Interface for cluster packets (default: eth0).
 </LI>
 
 <LI><B>cluster_interface</B> (string)<BR>
 Interface for cluster packets (default: eth0).

-<P>
+</LI>
+
+<LI><B>cluster_mcast_ttl</B> (int)<BR>
+TTL for multicast packets (default: 1).

 </LI>
 
 <LI><B>cluster_hb_interval</B> (int)<BR>
 Interval in tenths of a second between cluster heartbeat/pings.
 </LI>
 
 <LI><B>cluster_hb_interval</B> (int)<BR>
 Interval in tenths of a second between cluster heartbeat/pings.

-<P>

 </LI>
 
 <LI><B>cluster_hb_timeout</B> (int)<BR>
 Cluster heartbeat timeout in tenths of a second.  A new master will be
 elected when this interval has been passed without seeing a heartbeat
 from the master.
 </LI>
 
 <LI><B>cluster_hb_timeout</B> (int)<BR>
 Cluster heartbeat timeout in tenths of a second.  A new master will be
 elected when this interval has been passed without seeing a heartbeat
 from the master.

-<P>

 </LI>
 
 </LI>
 

-<LI><B>as_number</B> (int)<BR>
-Defines the local AS number for BGP (see <A HREF="#Routing">Routing</A>).
-<P>
+<LI><B>cluster_master_min_adv</B> (int)<BR>
+Determines the minumum number of up to date slaves required before the
+master will drop routes (default: 1).

 </LI>
 
 </LI>
 

-<LI><B>bgp_peer1</B> (string)
-<LI><B>bgp_peer1_as</B> (int)
-<LI><B>bgp_peer2</B> (string)
-<LI><B>bgp_peer2_as</B> (int)<BR>
-<P>
-DNS name (or IP) and AS number of BGP peers.
+<LI><B>echo_timeout</B> (int)<BR>
+Time between last packet sent and LCP ECHO generation
+(default: 10 (seconds)).
+</LI>
+
+<LI><B>idle_echo_timeout</B> (int)<BR>
+Drop sessions who have not responded within idle_echo_timeout seconds
+(default: 240 (seconds))
+</LI>
+
+<LI><B>auth_tunnel_change_addr_src</B> (boolean)<BR>
+This parameter authorize to change the source IP of the tunnels l2tp.
+This parameter can be used when the remotes BAS/LAC are l2tpns server
+configured in cluster mode, but that the interface to remote LNS are
+not clustered (the tunnel can be coming from different source IP)
+(default: no).
+</LI>
+
+<LI><B>disable_sending_hello</B> (boolean)<BR>
+Disable l2tp sending HELLO message for Apple compatibility.
+Some OS X implementation of l2tp no manage the L2TP "HELLO message".
+(default: no).
+</LI>
+
+</UL>
+
+<P><U><B>LAC configuration</B></U></P>
+<UL>
+<LI><B>bind_address_remotelns</B> (ip address)<BR>
+Address of the interface to listen the remote LNS tunnels.
+If no address is given, all interfaces are listened (Any Address).
+</LI>
+
+<LI><B>bind_portremotelns</B> (short)<BR>
+Port to bind for the Remote LNS (default: 65432).
+</LI>
+
+</UL>
+
+<P>A static REMOTES LNS configuration can be entered by the command:</P>
+<DL> <DD><B>setforward</B> <I>MASK</I> <I>IP</I> <I>PORT</I> <I>SECRET</I> </DL>
+
+where <I>MASK</I> specifies the mask of users who have forwarded to
+remote LNS (ex: "/friendISP@company.com").</BR>
+where <I>IP</I> specifies the IP of the  remote LNS (ex: "66.66.66.55").</BR>
+where <I>PORT</I> specifies the L2TP Port of the remote LNS
+(Normally should be 1701) (ex: 1701).</BR>
+where <I>SECRET</I> specifies the secret password the remote LNS (ex: mysecret).</BR>
+</BR>
+The static Remote LNS configuration can be used when the friend ISP not 
+have a proxied Radius.</BR>
+If the proxied Radius is used, It will return the RADIUS attributes:</BR>
+       Tunnel-Type: 1 = L2TP</BR>
+       Tunnel-Medium-Type: 1 = IPv4</BR>
+       Tunnel-Password: 1 = "LESECRETL2TP"</BR>
+       Tunnel-Server-Endpoint: 1 = "88.xx.xx.x1"</BR>
+       Tunnel-Assignment-Id: 1 = "friendisp_lns1"</BR>
+       Tunnel-Type: 2 = L2TP</BR>
+       Tunnel-Medium-Type: 2 = IPv4</BR>
+       Tunnel-Password: 2 = "LESECRETL2TP"</BR>
+       Tunnel-Server-Endpoint: 2 = "88.xx.xx.x2"</BR>
+       Tunnel-Assignment-Id: 2 = "friendisp_lns2"</BR>    
+
+<P><U><B>PPPOE configuration</B></U></P>
+
+<UL>
+<LI><B>pppoe_if_to_bind</B> (string)<BR>
+PPPOE server interface to bind (ex: "eth0.12"), If not specified the server PPPOE is not enabled.
+For the pppoe clustering, all the interfaces PPPOE of the clusters must use the same HW address (MAC address).
+</LI>
+
+<LI><B>pppoe_service_name</B> (string)<BR>
+PPPOE service name (default: NULL).

 </LI>
 </LI>

+
+<LI><B>pppoe_ac_name</B> (string)<BR>
+PPPOE  access concentrator name (default: "l2tpns-pppoe").
+</LI>
+

 </UL>
 
 </UL>
 

+<P><U><B>BGP configuration</B></U></P>
+
+<P>BGP routing configuration is entered by the command:
+The routing configuration section is entered by the command
+<DL><DD><B>router bgp</B> <I>as</I></DL>
+where <I>as</I> specifies the local AS number.
+
+<P>Subsequent lines prefixed with
+<DL><DD><B>neighbour</B> <I>peer</I></DL>
+define the attributes of BGP neighhbours.  Valid commands are:
+<DL>
+  <DD><B>neighbour</B> <I>peer</I> <B>remote-as</B> <I>as</I>
+  <DD><B>neighbout</B> <I>peer</I> <B>timers</B> <I>keepalive hold</I>
+</DL>
+
+Where <I>peer</I> specifies the BGP neighbour as either a hostname or
+IP address, <I>as</I> is the remote AS number and <I>keepalive</I>,
+<I>hold</I> are the timer values in seconds.
+
+<P>Named access-lists are configured using one of the commands:
+<DL>
+  <DD><B>ip access-list standard</B> <I>name</I>
+  <DD><B>ip access-list extended</B> <I>name</I>
+</DL>
+
+<P>Subsequent lines prefixed with <B>permit</B> or <B>deny</B>
+define the body of the access-list.  Standard access-list syntax:
+<DL>
+  <DD>{<B>permit</B>|<B>deny</B>}
+    {<I>host</I>|<I>source source-wildcard</I>|<B>any</B>}
+    [{<I>host</I>|<I>destination destination-wildcard</I>|<B>any</B>}]
+</DL>
+
+Extended access-lists:
+
+<DIV STYLE="margin-left: 4em; text-indent: -2em">
+  <P>{<B>permit</B>|<B>deny</B>} <B>ip</B>
+    {<I>host</I>|<I>source source-wildcard</I>|<B>any</B>}
+    {<I>host</I>|<I>destination destination-wildcard</I>|<B>any</B>} [<B>fragments</B>]
+  <P>{<B>permit</B>|<B>deny</B>} <B>udp</B>
+    {<I>host</I>|<I>source source-wildcard</I>|<B>any</B>}
+       [{<B>eq</B>|<B>neq</B>|<B>gt</B>|<B>lt</B>} <I>port</I>|<B>range</B> <I>from</I> <I>to</I>]
+    {<I>host</I>|<I>destination destination-wildcard</I>|<B>any</B>}
+       [{<B>eq</B>|<B>neq</B>|<B>gt</B>|<B>lt</B>} <I>port</I>|<B>range</B> <I>from</I> <I>to</I>]
+       [<B>fragments</B>]
+  <P>{<B>permit</B>|<B>deny</B>} <B>tcp</B>
+    {<I>host</I>|<I>source source-wildcard</I>|<B>any</B>}
+       [{<B>eq</B>|<B>neq</B>|<B>gt</B>|<B>lt</B>} <I>port</I>|<B>range</B> <I>from</I> <I>to</I>]
+    {<I>host</I>|<I>destination destination-wildcard</I>|<B>any</B>}
+       [{<B>eq</B>|<B>neq</B>|<B>gt</B>|<B>lt</B>} <I>port</I>|<B>range</B> <I>from</I> <I>to</I>]
+       [{<B>established</B>|{<B>match-any</B>|<B>match-all</B>}
+           {<B>+</B>|<B>-</B>}{<B>fin</B>|<B>syn</B>|<B>rst</B>|<B>psh</B>|<B>ack</B>|<B>urg</B>}
+           ...|<B>fragments</B>]
+</DIV>
+

 <H3 ID="users">users</H3>
 
 Usernames and passwords for the command-line interface are stored in
 <H3 ID="users">users</H3>
 
 Usernames and passwords for the command-line interface are stored in


@@ -390,8 +580,7 @@ A running l2tpns process can be controlled in a number of ways.  The primary
 method of control is by the Command-Line Interface (CLI).<P>
 
 You can also remotely send commands to modules via the nsctl client
 method of control is by the Command-Line Interface (CLI).<P>
 
 You can also remotely send commands to modules via the nsctl client

-provided.  This currently only works with the walled garden module, but
-modification is trivial to support other modules.<P>
+provided.<P>

 
 Also, there are a number of signals that l2tpns understands and takes action
 when it receives them.
 
 Also, there are a number of signals that l2tpns understands and takes action
 when it receives them.


@@ -496,19 +685,19 @@ IP Address      Used  Session User
 </LI>
 
 <LI><B>show radius</B><BR>
 </LI>
 
 <LI><B>show radius</B><BR>

-Show a summary of the in-use radius sessions.  This list should not be very
-long, as radius sessions should be cleaned up as soon as they are used.  The
+Show a summary of the in-use RADIUS sessions.  This list should not be very
+long, as RADIUS sessions should be cleaned up as soon as they are used.  The

 columns listed are:
 <TABLE>
 columns listed are:
 <TABLE>

-       <TR><TD><B>Radius</B></TD><TD>The ID of the radius request.  This is
-       sent in the packet to the radius server for identification.</TD></TR>
+       <TR><TD><B>Radius</B></TD><TD>The ID of the RADIUS request.  This is
+       sent in the packet to the RADIUS server for identification.</TD></TR>

        <TR><TD><B>State</B></TD><TD>The state of the request - WAIT, CHAP,
        AUTH, IPCP, START, STOP, NULL.</TD></TR>
        <TR><TD><B>State</B></TD><TD>The state of the request - WAIT, CHAP,
        AUTH, IPCP, START, STOP, NULL.</TD></TR>

-       <TR><TD><B>Session</B></TD><TD>The session ID that this radius
+       <TR><TD><B>Session</B></TD><TD>The session ID that this RADIUS

        request is associated with</TD></TR>
        <TR><TD><B>Retry</B></TD><TD>If a response does not appear to the
        request, it will retry at this time.  This is a unix timestamp.</TD></TR>
        request is associated with</TD></TR>
        <TR><TD><B>Retry</B></TD><TD>If a response does not appear to the
        request, it will retry at this time.  This is a unix timestamp.</TD></TR>

-       <TR><TD><B>Try</B></TD><TD>Retry count.  The radius request is
+       <TR><TD><B>Try</B></TD><TD>Retry count.  The RADIUS request is

        discarded after 3 retries.</TD></TR>
 </TABLE>
 <P>
        discarded after 3 retries.</TD></TR>
 </TABLE>
 <P>


@@ -549,7 +738,7 @@ current session for that username will be forwarded to the given
 host/port.  Specify <EM>no snoop username</EM> to disable interception
 for the session.<P>
 
 host/port.  Specify <EM>no snoop username</EM> to disable interception
 for the session.<P>
 

-If you want interception to be permanent, you will have to modify the radius
+If you want interception to be permanent, you will have to modify the RADIUS

 response for the user.  See <A HREF="#Interception">Interception</A>.
 <P>
 </LI>
 response for the user.  See <A HREF="#Interception">Interception</A>.
 <P>
 </LI>


@@ -560,7 +749,7 @@ session.  Specify <EM>no throttle username</EM> to disable throttling
 for the current session.<P>
 
 If you want throttling to be permanent, you will have to modify the
 for the current session.<P>
 
 If you want throttling to be permanent, you will have to modify the

-radius response for the user.  See <A HREF="#THrottling">Throttling</A>.
+RADIUS response for the user.  See <A HREF="#Throttling">Throttling</A>.

 <P>
 </LI>
 
 <P>
 </LI>
 


@@ -621,16 +810,13 @@ this way, although some may require a restart to take effect.<P>
 
 <H3 ID="nsctl">nsctl</H3>
 
 
 <H3 ID="nsctl">nsctl</H3>
 

-nsctl was implemented (badly) to allow messages to be passed to modules.<P>
+nsctl allows messages to be passed to plugins.<P>

 
 

-You must pass at least 2 parameters: <EM>host</EM> and <EM>command</EM>.  The
-host is the address of the l2tpns server which you want to send the message
-to.<P>
+Arguments are <EM>command</EM> and optional <EM>args</EM>.  See
+<STRONG>nsctl</STRONG>(8) for more details.<P>

 
 

-Command can currently be either <EM>garden</EM> or <EM>ungarden</EM>.  With
-both of these commands, you must give a session ID as the 3rd parameter.
-This will activate or deactivate the walled garden for a session
-temporarily.
+Built-in command are <EM>load_plugin</EM>, <EM>unload_plugin</EM> and
+<EM>help</EM>.  Any other commands are passed to plugins for processing.

 
 <H3 ID="Signals">Signals</H3>
 
 
 <H3 ID="Signals">Signals</H3>
 


@@ -641,16 +827,15 @@ killall -HUP l2tpns
 </PRE>
 
 The signals understood are:
 </PRE>
 
 The signals understood are:

-<UL>
-<LI>SIGHUP - Reload the config from disk and re-open log file<P></LI>
-<LI>SIGTERM / SIGINT - Shut down for a restart.  This will dump the current
-state to disk (if <EM>save_state</EM> is set to true).  Upon restart, the
-process will read this saved state to resume active sessions.<P>
-<LI>SIGQUIT - Shut down cleanly.  This will send a disconnect message for
-every active session and tunnel before shutting down.  This is a good idea
-when upgrading the code, as no sessions will be left with the remote end
-thinking they are open.</LI>
-</UL>
+<DL>
+<DT>SIGHUP</DT><DD>Reload the config from disk and re-open log file.</DD>
+<DT>SIGTERM, SIGINT</DT><DD>Stop process.  Tunnels and sessions are not
+terminated.  This signal should be used to stop l2tpns on a
+<A HREF="#Clustering">cluster node</A> where there are other machines to
+continue handling traffic.</DD>
+<DT>SIGQUIT</DT><DD>Shut down tunnels and sessions, exit process when
+complete.</DD>
+</DL>

 
 <H2 ID="Throttling">Throttling</H2>
 
 
 <H2 ID="Throttling">Throttling</H2>
 


@@ -659,7 +844,7 @@ desire.  You must first enable the global setting <EM>throttle_speed</EM>
 before this will be activated.<P>
 
 If you wish a session to be throttled permanently, you should set the
 before this will be activated.<P>
 
 If you wish a session to be throttled permanently, you should set the

-Vendor-Specific radius value <B>Cisco-Avpair="throttle=yes"</B>, which
+Vendor-Specific RADIUS value <B>Cisco-Avpair="throttle=yes"</B>, which

 will be handled by the <EM>autothrottle</EM> module.<P>
 
 Otherwise, you can enable and disable throttling an active session using
 will be handled by the <EM>autothrottle</EM> module.<P>
 
 Otherwise, you can enable and disable throttling an active session using


@@ -683,7 +868,7 @@ and <EM>no snoop username</EM> CLI commands.  These will enable interception
 immediately.<P>
 
 If you wish the user to be intercepted whenever they reconnect, you will
 immediately.<P>
 
 If you wish the user to be intercepted whenever they reconnect, you will

-need to modify the radius response to include the Vendor-Specific value
+need to modify the RADIUS response to include the Vendor-Specific value

 <B>Cisco-Avpair="intercept=yes"</B>.  For this feature to be enabled,
 you need to have the <EM>autosnoop</EM> module loaded.<P>
 
 <B>Cisco-Avpair="intercept=yes"</B>.  For this feature to be enabled,
 you need to have the <EM>autosnoop</EM> module loaded.<P>
 


@@ -693,11 +878,11 @@ Whenever a session connects, it is not fully set up until authentication is
 completed.  The remote end must send a PPP CHAP or PPP PAP authentication
 request to l2tpns.<P>
 
 completed.  The remote end must send a PPP CHAP or PPP PAP authentication
 request to l2tpns.<P>
 

-This request is sent to the radius server, which will hopefully respond with
+This request is sent to the RADIUS server, which will hopefully respond with

 Auth-Accept or Auth-Reject.<P>
 
 If Auth-Accept is received, the session is set up and an IP address is
 Auth-Accept or Auth-Reject.<P>
 
 If Auth-Accept is received, the session is set up and an IP address is

-assigned.  The radius server can include a Framed-IP-Address field in the
+assigned.  The RADIUS server can include a Framed-IP-Address field in the

 reply, and that address will be assigned to the client.  It can also include
 specific DNS servers, and a Framed-Route if that is required.<P>
 
 reply, and that address will be assigned to the client.  It can also include
 specific DNS servers, and a Framed-Route if that is required.<P>
 


@@ -707,7 +892,7 @@ walled garden module is loaded, in which case the user still receives the
 PPP AUTHACK, but their session is flagged as being a garden'd user, and they
 should not receive any service.<P>
 
 PPP AUTHACK, but their session is flagged as being a garden'd user, and they
 should not receive any service.<P>
 

-The radius reply can also contain a Vendor-Specific attribute called
+The RADIUS reply can also contain a Vendor-Specific attribute called

 Cisco-Avpair.  This field is a freeform text field that most Cisco
 devices understand to contain configuration instructions for the session.  In
 the case of l2tpns it is expected to be of the form
 Cisco-Avpair.  This field is a freeform text field that most Cisco
 devices understand to contain configuration instructions for the session.  In
 the case of l2tpns it is expected to be of the form


@@ -757,39 +942,39 @@ supplied structure:
 <TABLE CELLSPACING=1 CELLPADDING=3>
        <TR BGCOLOR=LIGHTGREEN><TH><B>Event</B></TH><TH><B>Description</B></TH><TH><B>Parameters</B></TH></TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>pre_auth</B></TD>
 <TABLE CELLSPACING=1 CELLPADDING=3>
        <TR BGCOLOR=LIGHTGREEN><TH><B>Event</B></TH><TH><B>Description</B></TH><TH><B>Parameters</B></TH></TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>pre_auth</B></TD>

-               <TD>This is called after a radius response has been
+               <TD>This is called after a RADIUS response has been

                received, but before it has been processed by the
                code.  This will allow you to modify the response in
                some way.
                </TD>
                <TD>
                received, but before it has been processed by the
                code.  This will allow you to modify the response in
                some way.
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-                       <LI>username</LI>
-                       <LI>password</LI>
-                       <LI>protocol (0xC023 for PAP, 0xC223 for CHAP)</LI>
-                       <LI>continue_auth - Set to 0 to stop processing authentication modules</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+                       <DT>username
+                       <DT>password
+                       <DT>protocol<DD>0xC023 for PAP, 0xC223 for CHAP
+                       <DT>continue_auth<DD>Set to 0 to stop processing authentication modules
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>post_auth</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>post_auth</B></TD>

-               <TD>This is called after a radius response has been
+               <TD>This is called after a RADIUS response has been

                received, and the basic checks have been performed.  This
                is what the garden module uses to force authentication
                to be accepted.
                </TD>
                <TD>
                received, and the basic checks have been performed.  This
                is what the garden module uses to force authentication
                to be accepted.
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-                       <LI>username</LI>
-                       <LI>auth_allowed - This is already set to true or
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+                       <DT>username
+                       <DT>auth_allowed<DD>This is already set to true or

                        false depending on whether authentication has been
                        allowed so far.  You can set this to 1 or 0 to force
                        false depending on whether authentication has been
                        allowed so far.  You can set this to 1 or 0 to force

-                       allow or disallow authentication</LI>
-                       <LI>protocol (0xC023 for PAP, 0xC223 for CHAP)</LI>
-               </UL>
+                       allow or disallow authentication
+                       <DT>protocol<DD>0xC023 for PAP, 0xC223 for CHAP
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_rx</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_rx</B></TD>


@@ -798,12 +983,12 @@ supplied structure:
                seriously slow down the system.</FONT>
                </TD>
                <TD>
                seriously slow down the system.</FONT>
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-                       <LI>buf - The raw packet data</LI>
-                       <LI>len - The length of buf</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+                       <DT>buf<DD>The raw packet data
+                       <DT>len<DD>The length of buf
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_tx</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_tx</B></TD>


@@ -812,12 +997,12 @@ supplied structure:
                seriously slow down the system.</FONT>
                </TD>
                <TD>
                seriously slow down the system.</FONT>
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-                       <LI>buf - The raw packet data</LI>
-                       <LI>len - The length of buf</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+                       <DT>buf<DD>The raw packet data
+                       <DT>len<DD>The length of buf
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>timer</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>timer</B></TD>


@@ -826,9 +1011,9 @@ supplied structure:
                you do is reentrant.
                </TD>
                <TD>
                you do is reentrant.
                </TD>
                <TD>

-               <UL>
-                       <LI>time_now - The current unix timestamp</LI>
-               </UL>
+               <DL>
+                       <DT>time_now<DD>The current unix timestamp
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>new_session</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>new_session</B></TD>


@@ -836,10 +1021,10 @@ supplied structure:
                session is now ready to handle traffic.
                </TD>
                <TD>
                session is now ready to handle traffic.
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>kill_session</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>kill_session</B></TD>


@@ -847,25 +1032,37 @@ supplied structure:
                This may be called multiple times for the same session.
                </TD>
                <TD>
                This may be called multiple times for the same session.
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_response</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_response</B></TD>

-               <TD>This is called whenever a radius response includes a
+               <TD>This is called whenever a RADIUS response includes a

                Cisco-Avpair value.  The value is split up into
                <EM>key=value</EM> pairs, and each is processed through all
                modules.
                </TD>
                <TD>
                Cisco-Avpair value.  The value is split up into
                <EM>key=value</EM> pairs, and each is processed through all
                modules.
                </TD>
                <TD>

-               <UL>
-                       <LI>t - Tunnel ID</LI>
-                       <LI>s - Session ID</LI>
-                       <LI>key</LI>
-                       <LI>value</LI>
-               </UL>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+                       <DT>key
+                       <DT>value
+               </DL>
+               </TD>
+       </TR>
+       <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_reset</B></TD>
+               <TD>This is called whenever a RADIUS CoA request is
+               received to reset any options to default values before
+               the new values are applied.
+               </TD>
+               <TD>
+               <DL>
+                       <DT>t<DD>Tunnel
+                       <DT>s<DD>Session
+               </DL>

                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>control</B></TD>
                </TD>
        </TR>
        <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>control</B></TD>


@@ -874,21 +1071,13 @@ supplied structure:
                required.
                </TD>
                <TD>
                required.
                </TD>
                <TD>

-               <UL>
-                       <LI>buf - The raw packet data</LI>
-                       <LI>l - The raw packet data length</LI>
-                       <LI>source_ip - Where the request came from</LI>
-                       <LI>source_port - Where the request came from</LI>
-                       <LI>response - Allocate a buffer and put your response in here</LI>
-                       <LI>response_length - Length of response</LI>
-                       <LI>send_response - true or false whether a response
-                       should be sent.  If you set this to true, you must
-                       allocate a response buffer.</LI>
-                       <LI>type - Type of request (see nsctl.c)</LI>
-                       <LI>id - ID of request</LI>
-                       <LI>data - I'm really not sure</LI>
-                       <LI>data_length - Length of data</LI>
-               </UL>
+               <DL>
+                       <DT>iam_master<DD>Cluster master status
+                       <DT>argc<DD>The number of arguments
+                       <DT>argv<DD>Arguments
+                       <DT>response<DD>Return value: NSCTL_RES_OK or NSCTL_RES_ERR
+                       <DT>additional<DD>Extended response text
+               </DL>

                </TD>
        </TR>
 </TABLE>
                </TD>
        </TR>
 </TABLE>


@@ -900,7 +1089,7 @@ Walled Garden is implemented so that you can provide perhaps limited service
 to sessions that incorrectly authenticate.<P>
 
 Whenever a session provides incorrect authentication, and the
 to sessions that incorrectly authenticate.<P>
 
 Whenever a session provides incorrect authentication, and the

-radius server responds with Auth-Reject, the walled garden module
+RADIUS server responds with Auth-Reject, the walled garden module

 (if loaded) will force authentication to succeed, but set the flag
 <EM>garden</EM> in the session structure, and adds an iptables rule to
 the <B>garden_users</B> chain to force all packets for the session's IP
 (if loaded) will force authentication to succeed, but set the flag
 <EM>garden</EM> in the session structure, and adds an iptables rule to
 the <B>garden_users</B> chain to force all packets for the session's IP


@@ -925,6 +1114,14 @@ command:
 iptables -t nat -L garden -nvx
 </PRE>
 
 iptables -t nat -L garden -nvx
 </PRE>
 

+<H2 ID="Filtering">Filtering</H2>
+
+Sessions may be filtered by specifying <B>Filter-Id</B> attributes in
+the RADIUS reply.  <I>filter</I>.<B>in</B> specifies that the named
+access-list <I>filter</I> should be applied to traffic from the
+customer, <I>filter</I>.<B>out</B> specifies a list for traffic to the
+customer.
+

 <H2 ID="Clustering">Clustering</H2>
 
 An l2tpns cluster consists of of one* or more servers configured with
 <H2 ID="Clustering">Clustering</H2>
 
 An l2tpns cluster consists of of one* or more servers configured with


@@ -983,6 +1180,6 @@ That's really what it looks like.<P>
 
 <BR>
 David Parrish<BR>
 
 <BR>
 David Parrish<BR>

-<A HREF="mailto:david@dparrish.com?subject=L2TPNS%20Documentation">david@dparrish.com</A>
+<A HREF="mailto:l2tpns-users@lists.sourceforge.net?subject=L2TPNS%20Documentation">l2tpns-users@lists.sourceforge.net</A>

 </BODY>
 </HTML>
 </BODY>
 </HTML>