+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>L2TPNS Manual</TITLE>
-<STYLE>
-H1 {
- text-align: center;
-}
-
-H2 {
- border-top: 1px solid black;
- border-bottom: 1px solid black;
- background-color: lightblue;
- padding-left: 10px;
-}
-
-H3 {
- text-decoration: underline;
-}
-</STYLE>
-</HEAD>
-<BODY>
-<H1>L2TPNS Manual</H1>
-<OL>
- <LI>Overview</LI>
- <LI>Installation</LI>
- <LI>Configuration</LI>
- <LI>Controlling the process</LI>
- <LI>Command-Line Interface</LI>
- <LI>Throttling</LI>
- <LI>Interception</LI>
- <LI>Authentication</LI>
- <LI>Plugins</LI>
- <LI>Walled Garden</LI>
- <LI>Clustering</LI>
- <LI>Performance</LI>
-</OL>
-<H2>Overview</H2>
-L2TPNS is half of a complete L2TP implementation. It supports only the
-LNS side of the connection.<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
-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,
-it is nowhere near as scalable.<P>
-
-L2TPNS uses the TUN/TAP interface provided by the Linux kernel to receive
-and send packets. Using some packet manipulation it doesn't require a
-single interface per connection, as l2tpd does.<P>
-
-This allows it to scale extremely well to very high loads and very high
-numbers of connections.<P>
-
-It also has a plugin architecture which allows custom code to be run
-during processing. An example of this is in the walled garden module
-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
-HREF="mailto:david@dparrish.com?subject=L2TPNS+Documentation">david@dparrish.com</A>.</EM><P>
-
-<H2>Installation</H2>
-<H3>Requirements</H3>
-
-<OL>
-<LI>Linux kernel version 2.4 or above, with the Tun/Tap interface either
-compiled in, or as a module.</LI>
-
-<LI>libcli 1.5 or greater.<BR>You can get this from <A
-HREF="http://sourceforge.net/projects/libcli">http://sourceforge.net/projects/libcli</A></LI>
-
-<LI>The iproute2 user-space tools. These are used for throttling,
-so if you don't want to throttle then this is not required.<BR>You
-may also need to patch tc and the kernel to include HTB
-support. You can find the relevant patches and instructions at <A
-HREF="http://luxik.cdi.cz/~devik/qos/htb/">http://luxik.cdi.cz/~devik/qos/htb/</A>.</LI>
-
-</OL>
-
-<H3>Compile</H3>
-
-You can generally get away with just running <B>make</B> from the source
-directory. This will compile the daemon, associated tools and any modules
-shipped with the distribution.<P>
-
-<H3>Install</H3>
-
-After you have successfully compiled everything, run <B>make
-install</B> to install it. By default, the binaries are installed into
-<EM>/usr/sbin</EM>, the configuration into <EM>/etc/l2tpns</EM>, and the
-modules into <EM>/usr/lib/l2tpns</EM>.<P>
-
-You will definately need to edit the configuration file before you start.
-See the Configuration section for more information.<P>
-
-You should also create the appropriate iptables chains if you want to use
-throttling or walled garden.
-<PRE>
-# Create the walled garden stuff
-iptables -t nat -N l2tpns
-iptables -t nat -F l2tpns
-iptables -t nat -A PREROUTING -j l2tpns
-iptables -t nat -A l2tpns -j garden_users
-# Create the throttling stuff
-iptables -t mangle -N l2tpns
-iptables -t mangle -F l2tpns
-iptables -t mangle -N throttle
-iptables -t mangle -F throttle
-iptables -t mangle -A PREROUTING -j l2tpns
-iptables -t mangle -A l2tpns -j throttle
-</PRE>
-
-<H3>Running it</H3>
-
-You only need to run <B>/usr/sbin/l2tpns</B> as root to start it. It does
-not detach to a daemon process, so you should perhaps run it from init.<P>
-
-By default there is no log destination set, so all log messages will go to
-stdout.<P>
-
-<H2>Configuration</H2>
-
-All configuration of the software is done from the files installed into
-/etc/l2tpns.
-
-<H3>l2tpns.cfg</H3>
-
-This is the main configuration file for L2TPNS. The format of the file is a
-list of commands that can be run through the command-line interface. This
-file can also be written directly by the L2TPNS process if a user runs the
-<EM>write memory</EM> command, so any comments will be lost. However if your
-policy is not to write the config by the program, then feel free to comment
-the file with a # at the beginning of the line.<P>
-
-A list of the possible configuration directives follows. Each of these
-should be set by a line like:<P>
-<PRE>
-set configstring "value"
-set ipaddress 192.168.1.1
-set boolean true
-</PRE>
-
-<UL>
-<LI><B>debug</B> (int)<BR>
-Sets the level of messages that will be written to the log file. The value
-should be between 0 and 5, with 0 being no debugging, and 5 being the
-highest. A rough description of the levels is:
- <OL>
- <LI VALUE=0>Critical Errors - Things are probably broken</LI>
- <LI>Errors - Things might have gone wrong, but probably will recover</LI>
- <LI>Warnings - Just in case you care what is not quite perfect</LI>
- <LI>Information - Parameters of control packets</LI>
- <LI>Calls - For tracing the execution of the code</LI>
- <LI>Packets - Everything, including a hex dump of all packets processed... probably twice</LI>
- </OL>
-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
-to. This can 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.
-<P>
-</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>
-</LI>
-
-<LI><B>primary_dns</B> (ip address)<BR>
-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.<BR>
-This sets the first DNS entry that will be sent.
-<P>
-</LI>
-
-<LI><B>secondary_dns</B> (ip address)<BR>
-See <EM>primary_dns</EM>.
-<P>
-</LI>
-
-<LI><B>snoop_host</B> (ip address)<BR>
-Whenever a user is intercepted, a copy of their traffic will be sent to this
-IP address, using the port specified by <EM>snoop_port</EM>. Each packet
-will be sent as UDP.
-<P>
-</LI>
-
-<LI><B>snoop_port</B> (int)<BR>
-See <EM>snoop_host</EM>.
-<P>
-</LI>
-
-<LI><B>primary_radius</B> (ip address)<BR>
-This sets the primary radius server used for both authentication and
-accounting. If this server does not respond, then the secondary radius
-server will be used.
-<P>
-</LI>
-
-<LI><B>secondary_radius</B> (ip address)<BR>
-See <EM>primary_radius</EM>.
-<P>
-</LI>
-
-<LI><B>radius_accounting</B> (boolean)<BR>
-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.
-<P>
-</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>
-</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.<BR>
-If an address is given here, then packets containing user traffic should be
-routed via this address, otherwise the primary address of the machine.<BR>
-This is set automatically by the cluster master when taking over a failed
-machine.
-<P>
-</LI>
-
-<LI><B>cluster_master</B> (ip address)<BR>
-This sets the address of the cluster master. See the <EM>Clustering</EM>
-section for more information on configuring a cluster.
-<P>
-</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>
-</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>setuid</B> (int)<BR>
-After starting up and binding the interface, change UID to this. This
-doesn't work properly.
-<P>
-</LI>
-
-<LI><B>accounting_dir</B> (string)<BR>
-If set to a directory, then every 5 minutes the current usage for every
-connected use will be dumped to a file. Each file dumped begins with a
-header, where each line is prefixed by #. 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.
-
-<P>
-</LI>
-
-<LI><B>save_state</B> (boolean)<BR>
-If set to true, a state file will be dumped to disk when the process dies.
-This will be restored on startup, loading all active tunnels and sessions.
-<P>
-</LI>
-
-</UL>
-
-<H3>l2tpns.users</H3>
-
-This file's sole purpose is to manage access to the command-line
-interface. If this file doesn't exist, then anyone who can get to port
-23 will be allowed access without a username / password.<P>
-
-If this is not what you want, then create this file and put in it a list of
-username / password pairs, separated by a <B>:</B>. e.g.:<P>
-
-<PRE>
-user.1:randompassword
-fred:bhPe4rD1ME8.s
-bob:SP2RHKl3Q3qo6
-</PRE>
-
-Keep in mind that the password should be in clear-text. There is no user
-privilege distinction, so anyone on this list will have full control of the
-system.<P>
-
-<H3>l2tpns.ip_pool</H3>
-
-This file is used to configure the IP address pool which user addresses are
-assigned from. This file should contain either an IP address or a IP mask
-per line. e.g.:<P>
-
-<PRE>
-192.168.1.1
-192.168.1.2
-192.168.1.3
-192.168.4.0/24
-172.16.0.0/16
-10.0.0.0/8
-</PRE>
-
-Keep in mind that L2TPNS can only handle 65535 connections per process, so
-don't put more than 65535 IP addresses in the configuration file. They will
-be wasted.
-
-<H2>Controlling the process</H2>
-
-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
-provided. This currently only works with the walled garden module, but
-modification is trivial to support other modules.<P>
-
-Also, there are a number of signals that L2TPNS understands and takes action
-when it receives them.
-
-<H3>Command-Line Interface</H3>
-
-You can access the command line interface by telnet'ing to port 23. There is
-no IP address restriction, so it's a good idea to firewall this port off
-from anyone who doesn't need access to it. See l2tpns.users for information
-on restricting access based on a username and password.<P>
-
-The CLI gives you real-time control over almost everything in
-the process. The interface is designed to look like a CISCO
-device, and supports things like command history, line editing and
-context sensitive help. This is provided by linking with the <A
-HREF="http://sourceforge.net/projects/libcli">libcli</A> library.<P>
-
-After you have connected to the telnet port (and perhaps logged in), you
-will be presented with a prompt <PRE>l2tpns></PRE><P>
-
-You can type <EM>help</EM> to get a list of all possible commands, but this
-list could be quite long. A brief overview of the more important commands
-follows:
-
-<UL>
-<LI><B>show session</B><BR>
-Without specifying a session ID, this will list all tunnels currently
-connected. If you specify a session ID, you will be given all information on
-a single tunnel. Note that the full session list can be around 185 columns
-wide, so you should probably use a wide terminal to see the list
-properly.<P>
-The columns listed in the overview are:
-<TABLE>
- <TR><TD><B>SID</B></TD><TD>Session ID</TD></TR>
- <TR><TD><B>TID</B></TD><TD>Tunnel ID - Use with <EM>show tunnel tid</EM></TD></TR>
- <TR><TD><B>Username</B></TD><TD>The username given in the PPP
- authentication. If this is *, then LCP authentication has not
- completed.</TD></TR>
- <TR><TD><B>IP</B></TD><TD>The IP address given to the session. If
- this is 0.0.0.0, LCP negotiation has not completed.</TD></TR>
- <TR><TD><B>I</B></TD><TD>Intercept - Y or N depending on whether the
- session is being snooped. See <EM>snoop</EM>.</TD></TR>
- <TR><TD><B>T</B></TD><TD>Throttled - Y or N if the session is
- currently throttled. See <EM>throttle</EM>.</TD></TR>
- <TR><TD><B>G</B></TD><TD>Walled Garden - Y or N if the user is
- trapped in the walled garden. This field is present even if the
- garden module is not loaded.</TD></TR>
- <TR><TD><B>opened</B></TD><TD>The number of seconds since the
- session started</TD></TR>
- <TR><TD><B>downloaded</B></TD><TD>Number of bytes downloaded by the user</TD></TR>
- <TR><TD><B>uploaded</B></TD><TD>Number of bytes uploaded by the user</TD></TR>
- <TR><TD><B>idle</B></TD><TD>The number of seconds since traffic was
- detected on the session</TD></TR>
- <TR><TD><B>LAC</B></TD><TD>The IP address of the LAC the session is
- connected to.</TD></TR>
- <TR><TD><B>CLI</B></TD><TD>The Calling-Line-Identification field
- provided during the session setup. This field is generated by the
- LAC.</TD></TR>
-</TABLE>
-<P>
-</LI>
-
-<LI><B>show tunnel</B><BR>
-This will show all the open tunnels in a summary, or detail on a single
-tunnel if you give a tunnel id.<P>
-The columns listed in the overview are:
-<TABLE>
- <TR><TD><B>TID</B></TD><TD>Tunnel ID</TD></TR>
- <TR><TD><B>Hostname</B></TD><TD>The hostname for the tunnel as
- provided by the LAC. This has no relation to DNS, it is just
- a text field.</TD></TR>
- <TR><TD><B>IP</B></TD><TD>The IP address of the LAC</TD></TR>
- <TR><TD><B>State</B></TD><TD>Tunnel state - Free, Open, Dieing,
- Opening</TD></TR>
- <TR><TD><B>Sessions</B></TD><TD>The number of open sessions on the
- tunnel</TD></TR>
-</TABLE>
-<P>
-</LI>
-
-<LI><B>show pool</B><BR>
-Displays the current IP address pool allocation. This will only display
-addresses that are in use, or are reserved for re-allocation to a
-disconnected user.<P>
-If an address is not currently in use, but has been used, then in the User
-column the username will be shown in square brackets, followed by the time
-since the address was used:
-<PRE>
-IP Address Used Session User
-192.168.100.6 N [joe.user] 1548s
-</PRE>
-<P>
-</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
-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>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
- 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
- discarded after 3 retries.</TD></TR>
-</TABLE>
-<P>
-</LI>
-
-<LI><B>show running-config</B><BR>
-This will list the current running configuration. This is in a format that
-can either be pasted into the configuration file, or run directly at the
-command line.
-<P>
-</LI>
-
-<LI><B>show counters</B><BR>
-Internally, counters are kept of key values, such as bytes and packets
-transferred, as well as function call counters. This function displays all
-these counters, and is probably only useful for debugging.<P>
-You can reset these counters by running <EM>clear counters</EM>.
-<P>
-</LI>
-
-<LI><B>write memory</B><BR>
-This will write the current running configuration to the config file
-l2tpns.cfg, which will be run on a restart.
-<P>
-</LI>
-
-<LI><B>snoop</B><BR>
-You must specify a username, which will be intercepted for the current
-session. Specify <EM>no snoop username</EM> to disable interception for the
-current session.<P>
-If you want interception to be permanent, you will have to modify the radius
-response for the user. See <EM>Interception</EM>.
-<P>
-</LI>
-
-<LI><B>throttle</B><BR>
-You must specify a username, which will be throttled for the current
-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 radius
-response for the user. See <EM>Throttling</EM>.
-<P>
-</LI>
-
-<LI><B>drop session</B><BR>
-This will cleanly disconnect a session. You must specify a session id, which
-you can get from <EM>show session</EM>. This will send a disconnect message
-to the remote end.
-<P>
-</LI>
-
-<LI><B>drop tunnel</B><BR>
-This will cleanly disconnect a tunnel, as well as all sessions on that
-tunnel. It will send a disconnect message for each session individually, and
-after 10 seconds it will send a tunnel disconnect message.
-<P>
-</LI>
-
-<LI><B>load plugin</B><BR>
-Load a plugin. You must specify the plugin name, and it will search in
-/usr/lib/l2tpns for <EM>plugin</EM>.so. You can unload a loaded plugin with
-<EM>remove plugin</EM>.
-<P>
-</LI>
-
-<LI><B>set</B><BR>
-Set a configuration variable. You must specify the variable name, and the
-value. If the value contains any spaces, you should quote the value with
-double quotes (").
-<P>
-</LI>
-
-<LI><B>uptime</B><BR>
-This will show how long the L2TPNS process has been running, and the current
-bandwidth utilization:
-<PRE>
-17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16
-Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569
-</PRE>
-The bandwidth line contains 4 sets of values.<BR>
-UDP-ETH is the current bandwidth going from the LAC to the ethernet
-(user uploads), in mbits/sec.<BR>
-ETH-UDP is the current bandwidth going from ethernet to the LAC (user
-downloads).<BR>
-TOTAL is the total aggregate bandwidth in mbits/s.<BR>
-IN and OUT are packets/per-second going between UDP-ETH and ETH-UDP.
-<P>
-These counters are updated every second.
-<P>
-</LI>
-</UL>
-
-<H3>nsctl</H3>
-
-nsctl was implemented (badly) to allow messages to be passed to modules.<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.<BR>
-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.
-
-<H3>Signals</H3>
-
-While the process is running, you can send it a few different signals, using
-the kill command.
-<PRE>
-killall -HUP l2tpns
-</PRE>
-
-The signals understood are:
-<UL>
-<LI>SIGHUP - Reload the config from disk<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>
-This is really useful when doing an upgrade, as the code can change without
-dropping any users. However, if the internal structures such as
-<EM>sessiont</EM> or <EM>tunnelt</EM> change, then this saved state file
-will not reload, and none of the sessions will be recreated. This is bad.<P>
-If these structures do change, you should kill the server with SIGQUIT,
-which won't dump the state.</LI>
-<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>
-
-<H2>Throttling</H2>
-
-L2TPNS contains support for slowing down user sessions to whatever speed you
-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
-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
-the <EM>throttle</EM> CLI command.<P>
-
-Throttling is actually performed using a combination of iptables and tc.<BR>
-First, a HTB bucket is created using tc (unless one is already created and
-unused).<BR>
-Secondly, an iptables rule is inserted into the throttle chanin in the
-mangle table so all packets destined for the user's IP address go into the
-HTB.<P>
-
-You can check the packets being throttled using the tc command. Find the HTB
-handle by doing <EM>show session id</EM> in the CLI, next to the Filter
-Bucket tag. Then at the shell prompt, you can run:
-<PRE>
-tc -s class ls dev tun0 | grep -A3 <EM>1:870</EM>
-class htb 1:870 root prio 0 rate 28Kbit ceil 28Kbit burst 15Kb cburst 1634b
- Sent 27042557 bytes 41464 pkts (dropped 1876, overlimits 0)
- lended: 41471 borrowed: 0 giants: 0
- tokens: 3490743 ctokens: 353601
-</PRE>
-
-<H2>Interception</H2>
-
-You may have to deal with legal requirements to be able to intercept a
-user's traffic at any time. L2TPNS allows you to begin and end interception
-on the fly, as well as at authentication time.<P>
-
-When a user is being intercepted, a copy of every packet they send and
-receive will be sent wrapped in a UDP packet to the IP address and port set
-in the <EM>snoop_host</EM> and <EM>snoop_port</EM> configuration
-variables.<P>
-
-The UDP packet contains just the raw IP frame, with no extra headers.<P>
-
-To enable interception on a connected user, use the <EM>snoop username</EM>
-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
-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>
-
-<H2>Authentication</H2>
-
-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>
-
-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
-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>
-
-If Auth-Reject is received, then the client is sent a PPP AUTHNAK packet,
-at which point they should disconnect. The exception to this is when the
-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>
-
-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
-<PRE>
-key=value,key2=value2,key3=value3,key<EM>n</EM>=<EM>value</EM>
-</PRE>
-
-Each key-value pair is separated and passed to any modules loaded. The
-<EM>autosnoop</EM> and <EM>autothrottle</EM> understand the keys
-<EM>intercept</EM> and <EM>throttle</EM> respectively. For example, to have
-a user who is to be throttled and intercepted, the Cisco-Avpair value should
-contain:
-<PRE>
-intercept=yes,throttle=yes
-</PRE>
-
-<H2>Plugins</H2>
-
-So as to make L2TPNS as flexible as possible (I know the core code is pretty
-difficult to understand), it includes a plugin API, which you can use to
-hook into certain events.<P>
-
-There are a few example modules included - autosnoop, autothrottle and
-garden.<P>
-
-When an event happens that has a hook, L2TPNS looks for a predefined
-function name in every loaded module, and runs them in the order the modules
-were loaded.<P>
-
-The function should return <B>PLUGIN_RET_OK</B> if it is all OK. If it returns
-<B>PLUGIN_RET_STOP</B>, then it is assumed to have worked, but that no further
-modules should be run for this event.<P>
-A return of <B>PLUGIN_RET_ERROR</B> means that this module failed, and
-no further processing should be done for this event. <EM>Use this with care.</EM>
-
-Every event function called takes a specific structure named
-param_<EM>event</EM>, which varies in content with each event. The
-function name for each event will be <B>plugin_<EM>event</EM></B>,
-so for the event <EM>timer</EM>, the function declaration should look like:
-<PRE>
-int plugin_timer(struct param_timer *data);
-</PRE>
-
-A list of the available events follows, with a list of all the fields in the
-supplied structure:
-<TABLE CELLSPACING=0 CELLPADDING=0><TR BGCOLOR=LIGHTGREEN><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
- 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>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>post_auth</B></TD>
- <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>
- <UL>
- <LI>t - Tunnel ID</LI>
- <LI>s - Session ID</LI>
- <LI>username</LI>
- <LI>auth_allowed - 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
- allow or disallow authentication</LI>
- <LI>protocol (0xC023 for PAP, 0xC223 for CHAP)</LI>
- </UL>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_rx</B></TD>
- <TD>This is called whenever a session receives a
- packet. <FONT COLOR=RED>Use this sparingly, as this will
- 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>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_tx</B></TD>
- <TD>This is called whenever a session sends a
- packet. <FONT COLOR=RED>Use this sparingly, as this will
- 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>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>timer</B></TD>
- <TD>This is run every second, no matter what is happening.
- This is called from a signal handler, so make sure anything
- you do is reentrant.
- </TD>
- <TD>
- <UL>
- <LI>time_now - The current unix timestamp</LI>
- </UL>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>new_session</B></TD>
- <TD>This is called after a session is fully set up. The
- session is now ready to handle traffic.
- </TD>
- <TD>
- <UL>
- <LI>t - Tunnel ID</LI>
- <LI>s - Session ID</LI>
- </UL>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>kill_session</B></TD>
- <TD>This is called when a session is about to be shut down.
- This may be called multiple times for the same session.
- </TD>
- <TD>
- <UL>
- <LI>t - Tunnel ID</LI>
- <LI>s - Session ID</LI>
- </UL>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_response</B></TD>
- <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>
- <UL>
- <LI>t - Tunnel ID</LI>
- <LI>s - Session ID</LI>
- <LI>key</LI>
- <LI>value</LI>
- </UL>
- </TD>
- </TR>
- <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>control</B></TD>
- <TD>This is called in whenever a nsctl packet is received.
- This should handle the packet and form a response if
- 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>
- </TD>
- </TR>
-</TABLE>
-</TD></TR></TABLE>
-
-<H2>Walled Garden</H2>
-
-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
-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
-address to traverse the <B>garden</B> chain.<P>
-
-This doesn't <EM>just work</EM>. To set this all up, you will need to create
-2 iptables chains on the nat table - <B>garden</B> and <B>garden_users</B>.
-<PRE>
-iptables -t nat -N garden
-iptables -t nat -F garden
-iptables -t nat -N garden_users
-iptables -t nat -F garden_users
-</PRE>
-
-You should add rules to the <B>garden</B> chain to limit user's traffic. For
-example, to force all traffic except DNS to be forwarded to 192.168.1.1, add
-these entries to your firewall startup script:
-<PRE>
-iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
-</PRE>
-
-L2TPNS will add entries to the garden_users chain as appropriate.<P>
-
-You can check the amount of traffic being captured using the following
-command:
-<PRE>
-iptables -t nat -L garden -nvx
-</PRE>
-
-<H2>Clustering</H2>
-
-Clustering is currently broken. But here's how it's supposed to work.<P>
-
-<H2>Performance</H2>
-
-Performance is great.<P>
-
-I'd like to include some pretty graphs here that show a linear performance
-increase, with no impact by number of connected sessions.<P>
-
-That's really what it looks like.<P>
-
-<BR>
-David Parrish<BR>
-<A HREF="mailto:david@dparrish.com?subject=L2TPNS+Documentation">david@dparrish.com</A>
-</BODY>
-</HTML>