roll in Michael's "limp along" fix for when a slave drops temporarily from the mcast...
[l2tpns.git] / Docs / manual.html
1 <HTML>
2 <HEAD>
3 <TITLE>L2TPNS Manual</TITLE>
4 <STYLE>
5 H1 {
6 text-align: center;
7 }
8
9 H2 {
10 border-top: 1px solid black;
11 border-bottom: 1px solid black;
12 background-color: lightblue;
13 padding-left: 10px;
14 }
15
16 H3 {
17 text-decoration: underline;
18 }
19 </STYLE>
20 </HEAD>
21 <BODY>
22 <H1>L2TPNS Manual</H1>
23 <OL>
24 <LI>Overview</LI>
25 <LI>Installation</LI>
26 <LI>Configuration</LI>
27 <LI>Controlling the process</LI>
28 <LI>Command-Line Interface</LI>
29 <LI>Throttling</LI>
30 <LI>Interception</LI>
31 <LI>Authentication</LI>
32 <LI>Plugins</LI>
33 <LI>Walled Garden</LI>
34 <LI>Clustering</LI>
35 <LI>Performance</LI>
36 </OL>
37 <H2>Overview</H2>
38 L2TPNS is half of a complete L2TP implementation. It supports only the
39 LNS side of the connection.<P>
40
41 L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2
42 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection. L2TPNS
43 implements PPP over L2TP only.<P>
44
45 There are a couple of other L2TP imlementations, of which <A
46 HREF="http://sourceforge.net/projects/l2tpd">l2tpd</A> is probably the
47 most popular. l2tpd also will handle being either end of a tunnel, and
48 is a lot more configurable than L2TPNS. However, due to the way it works,
49 it is nowhere near as scalable.<P>
50
51 L2TPNS uses the TUN/TAP interface provided by the Linux kernel to receive
52 and send packets. Using some packet manipulation it doesn't require a
53 single interface per connection, as l2tpd does.<P>
54
55 This allows it to scale extremely well to very high loads and very high
56 numbers of connections.<P>
57
58 It also has a plugin architecture which allows custom code to be run
59 during processing. An example of this is in the walled garden module
60 included.<P>
61
62 <BR>
63 <EM>Documentation is not my best skill. If you find any problems
64 with this document, or if you wish to contribute, please email <A
65 HREF="mailto:david@dparrish.com?subject=L2TPNS+Documentation">david@dparrish.com</A>.</EM><P>
66
67 <H2>Installation</H2>
68 <H3>Requirements</H3>
69
70 <OL>
71 <LI>Linux kernel version 2.4 or above, with the Tun/Tap interface either
72 compiled in, or as a module.</LI>
73
74 <LI>libcli 1.5 or greater.<BR>You can get this from <A
75 HREF="http://sourceforge.net/projects/libcli">http://sourceforge.net/projects/libcli</A></LI>
76
77 <LI>The iproute2 user-space tools. These are used for throttling,
78 so if you don't want to throttle then this is not required.<BR>You
79 may also need to patch tc and the kernel to include HTB
80 support. You can find the relevant patches and instructions at <A
81 HREF="http://luxik.cdi.cz/~devik/qos/htb/">http://luxik.cdi.cz/~devik/qos/htb/</A>.</LI>
82
83 </OL>
84
85 <H3>Compile</H3>
86
87 You can generally get away with just running <B>make</B> from the source
88 directory. This will compile the daemon, associated tools and any modules
89 shipped with the distribution.<P>
90
91 <H3>Install</H3>
92
93 After you have successfully compiled everything, run <B>make
94 install</B> to install it. By default, the binaries are installed into
95 <EM>/usr/sbin</EM>, the configuration into <EM>/etc/l2tpns</EM>, and the
96 modules into <EM>/usr/lib/l2tpns</EM>.<P>
97
98 You will definately need to edit the configuration file before you start.
99 See the Configuration section for more information.<P>
100
101 You should also create the appropriate iptables chains if you want to use
102 throttling or walled garden.
103 <PRE>
104 # Create the walled garden stuff
105 iptables -t nat -N l2tpns
106 iptables -t nat -F l2tpns
107 iptables -t nat -A PREROUTING -j l2tpns
108 iptables -t nat -A l2tpns -j garden_users
109 # Create the throttling stuff
110 iptables -t mangle -N l2tpns
111 iptables -t mangle -F l2tpns
112 iptables -t mangle -N throttle
113 iptables -t mangle -F throttle
114 iptables -t mangle -A PREROUTING -j l2tpns
115 iptables -t mangle -A l2tpns -j throttle
116 </PRE>
117
118 <H3>Running it</H3>
119
120 You only need to run <B>/usr/sbin/l2tpns</B> as root to start it. It does
121 not detach to a daemon process, so you should perhaps run it from init.<P>
122
123 By default there is no log destination set, so all log messages will go to
124 stdout.<P>
125
126 <H2>Configuration</H2>
127
128 All configuration of the software is done from the files installed into
129 /etc/l2tpns.
130
131 <H3>l2tpns.cfg</H3>
132
133 This is the main configuration file for L2TPNS. The format of the file is a
134 list of commands that can be run through the command-line interface. This
135 file can also be written directly by the L2TPNS process if a user runs the
136 <EM>write memory</EM> command, so any comments will be lost. However if your
137 policy is not to write the config by the program, then feel free to comment
138 the file with a # at the beginning of the line.<P>
139
140 A list of the possible configuration directives follows. Each of these
141 should be set by a line like:<P>
142 <PRE>
143 set configstring "value"
144 set ipaddress 192.168.1.1
145 set boolean true
146 </PRE>
147
148 <UL>
149 <LI><B>debug</B> (int)<BR>
150 Sets the level of messages that will be written to the log file. The value
151 should be between 0 and 5, with 0 being no debugging, and 5 being the
152 highest. A rough description of the levels is:
153 <OL>
154 <LI VALUE=0>Critical Errors - Things are probably broken</LI>
155 <LI>Errors - Things might have gone wrong, but probably will recover</LI>
156 <LI>Warnings - Just in case you care what is not quite perfect</LI>
157 <LI>Information - Parameters of control packets</LI>
158 <LI>Calls - For tracing the execution of the code</LI>
159 <LI>Packets - Everything, including a hex dump of all packets processed... probably twice</LI>
160 </OL>
161 Note that the higher you set the debugging level, the slower the program
162 will run. Also, at level 5 a LOT of information will be logged. This should
163 only ever be used for working out why it doesn't work at all.
164 <P>
165 </LI>
166
167 <LI><B>log_file</B> (string)<BR>
168 This will be where all logging and debugging information is written
169 to. This can be either a filename, such as <EM>/var/log/l2tpns</EM>, or
170 the special magic string <EM>syslog:facility</EM>, where <EM>facility</EM>
171 is any one of the syslog logging facilities, such as local5.
172 <P>
173 </LI>
174
175 <LI><B>l2tp_secret</B> (string)<BR>
176 This sets the string that L2TPNS will use for authenticating tunnel request.
177 This must be the same as the LAC, or authentication will fail. This will
178 only actually be used if the LAC requests authentication.
179 <P>
180 </LI>
181
182 <LI><B>primary_dns</B> (ip address)<BR>
183 Whenever a PPP connection is established, DNS servers will be sent to the
184 user, both a primary and a secondary. If either is set to 0.0.0.0, then that
185 one will not be sent.<BR>
186 This sets the first DNS entry that will be sent.
187 <P>
188 </LI>
189
190 <LI><B>secondary_dns</B> (ip address)<BR>
191 See <EM>primary_dns</EM>.
192 <P>
193 </LI>
194
195 <LI><B>snoop_host</B> (ip address)<BR>
196 Whenever a user is intercepted, a copy of their traffic will be sent to this
197 IP address, using the port specified by <EM>snoop_port</EM>. Each packet
198 will be sent as UDP.
199 <P>
200 </LI>
201
202 <LI><B>snoop_port</B> (int)<BR>
203 See <EM>snoop_host</EM>.
204 <P>
205 </LI>
206
207 <LI><B>primary_radius</B> (ip address)<BR>
208 This sets the primary radius server used for both authentication and
209 accounting. If this server does not respond, then the secondary radius
210 server will be used.
211 <P>
212 </LI>
213
214 <LI><B>secondary_radius</B> (ip address)<BR>
215 See <EM>primary_radius</EM>.
216 <P>
217 </LI>
218
219 <LI><B>radius_accounting</B> (boolean)<BR>
220 If set to true, then radius accounting packets will be sent. This means that
221 a Start record will be sent when the session is successfully authenticated,
222 and a Stop record will be sent when the session is closed.
223 <P>
224 </LI>
225
226 <LI><B>radius_secret</B> (string)<BR>
227 This secret will be used in all radius queries. If this is not set then
228 radius queries will fail.
229 <P>
230 </LI>
231
232 <LI><B>bind_address</B> (ip address)<BR>
233 When the tun interface is created, it is assigned the address specified
234 here. If no address is given, 1.1.1.1 is used.<BR>
235 If an address is given here, then packets containing user traffic should be
236 routed via this address, otherwise the primary address of the machine.<BR>
237 This is set automatically by the cluster master when taking over a failed
238 machine.
239 <P>
240 </LI>
241
242 <LI><B>cluster_master</B> (ip address)<BR>
243 This sets the address of the cluster master. See the <EM>Clustering</EM>
244 section for more information on configuring a cluster.
245 <P>
246 </LI>
247
248 <LI><B>throttle_speed</B> (int)<BR>
249 Sets the speed (in kbits/s) which sessions will be limited to. If this is
250 set to 0, then throttling will not be used at all. Note: You can set this by
251 the CLI, but changes will not affect currently connected users.
252 <P>
253 </LI>
254
255 <LI><B>dump_speed</B> (boolean)<BR>
256 If set to true, then the current bandwidth utilization will be logged every
257 second. Even if this is disabled, you can see this information by running
258 the <EM>uptime</EM> command on the CLI.
259 <P>
260 </LI>
261
262 <LI><B>setuid</B> (int)<BR>
263 After starting up and binding the interface, change UID to this. This
264 doesn't work properly.
265 <P>
266 </LI>
267
268 <LI><B>accounting_dir</B> (string)<BR>
269 If set to a directory, then every 5 minutes the current usage for every
270 connected use will be dumped to a file. Each file dumped begins with a
271 header, where each line is prefixed by #. Following the header is a single
272 line for every connected user, fields separated by a space.<BR>
273 The fields are username, ip, qos, uptxoctets, downrxoctets. The qos
274 field is 1 if a standard user, and 2 if the user is throttled.
275
276 <P>
277 </LI>
278
279 <LI><B>save_state</B> (boolean)<BR>
280 If set to true, a state file will be dumped to disk when the process dies.
281 This will be restored on startup, loading all active tunnels and sessions.
282 <P>
283 </LI>
284
285 </UL>
286
287 <H3>l2tpns.users</H3>
288
289 This file's sole purpose is to manage access to the command-line
290 interface. If this file doesn't exist, then anyone who can get to port
291 23 will be allowed access without a username / password.<P>
292
293 If this is not what you want, then create this file and put in it a list of
294 username / password pairs, separated by a <B>:</B>. e.g.:<P>
295
296 <PRE>
297 user.1:randompassword
298 fred:bhPe4rD1ME8.s
299 bob:SP2RHKl3Q3qo6
300 </PRE>
301
302 Keep in mind that the password should be in clear-text. There is no user
303 privilege distinction, so anyone on this list will have full control of the
304 system.<P>
305
306 <H3>l2tpns.ip_pool</H3>
307
308 This file is used to configure the IP address pool which user addresses are
309 assigned from. This file should contain either an IP address or a IP mask
310 per line. e.g.:<P>
311
312 <PRE>
313 192.168.1.1
314 192.168.1.2
315 192.168.1.3
316 192.168.4.0/24
317 172.16.0.0/16
318 10.0.0.0/8
319 </PRE>
320
321 Keep in mind that L2TPNS can only handle 65535 connections per process, so
322 don't put more than 65535 IP addresses in the configuration file. They will
323 be wasted.
324
325 <H2>Controlling the process</H2>
326
327 A running L2TPNS process can be controlled in a number of ways. The primary
328 method of control is by the Command-Line Interface (CLI).<P>
329
330 You can also remotely send commands to modules via the nsctl client
331 provided. This currently only works with the walled garden module, but
332 modification is trivial to support other modules.<P>
333
334 Also, there are a number of signals that L2TPNS understands and takes action
335 when it receives them.
336
337 <H3>Command-Line Interface</H3>
338
339 You can access the command line interface by telnet'ing to port 23. There is
340 no IP address restriction, so it's a good idea to firewall this port off
341 from anyone who doesn't need access to it. See l2tpns.users for information
342 on restricting access based on a username and password.<P>
343
344 The CLI gives you real-time control over almost everything in
345 the process. The interface is designed to look like a CISCO
346 device, and supports things like command history, line editing and
347 context sensitive help. This is provided by linking with the <A
348 HREF="http://sourceforge.net/projects/libcli">libcli</A> library.<P>
349
350 After you have connected to the telnet port (and perhaps logged in), you
351 will be presented with a prompt <PRE>l2tpns&gt;</PRE><P>
352
353 You can type <EM>help</EM> to get a list of all possible commands, but this
354 list could be quite long. A brief overview of the more important commands
355 follows:
356
357 <UL>
358 <LI><B>show session</B><BR>
359 Without specifying a session ID, this will list all tunnels currently
360 connected. If you specify a session ID, you will be given all information on
361 a single tunnel. Note that the full session list can be around 185 columns
362 wide, so you should probably use a wide terminal to see the list
363 properly.<P>
364 The columns listed in the overview are:
365 <TABLE>
366 <TR><TD><B>SID</B></TD><TD>Session ID</TD></TR>
367 <TR><TD><B>TID</B></TD><TD>Tunnel ID - Use with <EM>show tunnel tid</EM></TD></TR>
368 <TR><TD><B>Username</B></TD><TD>The username given in the PPP
369 authentication. If this is *, then LCP authentication has not
370 completed.</TD></TR>
371 <TR><TD><B>IP</B></TD><TD>The IP address given to the session. If
372 this is 0.0.0.0, LCP negotiation has not completed.</TD></TR>
373 <TR><TD><B>I</B></TD><TD>Intercept - Y or N depending on whether the
374 session is being snooped. See <EM>snoop</EM>.</TD></TR>
375 <TR><TD><B>T</B></TD><TD>Throttled - Y or N if the session is
376 currently throttled. See <EM>throttle</EM>.</TD></TR>
377 <TR><TD><B>G</B></TD><TD>Walled Garden - Y or N if the user is
378 trapped in the walled garden. This field is present even if the
379 garden module is not loaded.</TD></TR>
380 <TR><TD><B>opened</B></TD><TD>The number of seconds since the
381 session started</TD></TR>
382 <TR><TD><B>downloaded</B></TD><TD>Number of bytes downloaded by the user</TD></TR>
383 <TR><TD><B>uploaded</B></TD><TD>Number of bytes uploaded by the user</TD></TR>
384 <TR><TD><B>idle</B></TD><TD>The number of seconds since traffic was
385 detected on the session</TD></TR>
386 <TR><TD><B>LAC</B></TD><TD>The IP address of the LAC the session is
387 connected to.</TD></TR>
388 <TR><TD><B>CLI</B></TD><TD>The Calling-Line-Identification field
389 provided during the session setup. This field is generated by the
390 LAC.</TD></TR>
391 </TABLE>
392 <P>
393 </LI>
394
395 <LI><B>show tunnel</B><BR>
396 This will show all the open tunnels in a summary, or detail on a single
397 tunnel if you give a tunnel id.<P>
398 The columns listed in the overview are:
399 <TABLE>
400 <TR><TD><B>TID</B></TD><TD>Tunnel ID</TD></TR>
401 <TR><TD><B>Hostname</B></TD><TD>The hostname for the tunnel as
402 provided by the LAC. This has no relation to DNS, it is just
403 a text field.</TD></TR>
404 <TR><TD><B>IP</B></TD><TD>The IP address of the LAC</TD></TR>
405 <TR><TD><B>State</B></TD><TD>Tunnel state - Free, Open, Dieing,
406 Opening</TD></TR>
407 <TR><TD><B>Sessions</B></TD><TD>The number of open sessions on the
408 tunnel</TD></TR>
409 </TABLE>
410 <P>
411 </LI>
412
413 <LI><B>show pool</B><BR>
414 Displays the current IP address pool allocation. This will only display
415 addresses that are in use, or are reserved for re-allocation to a
416 disconnected user.<P>
417 If an address is not currently in use, but has been used, then in the User
418 column the username will be shown in square brackets, followed by the time
419 since the address was used:
420 <PRE>
421 IP Address Used Session User
422 192.168.100.6 N [joe.user] 1548s
423 </PRE>
424 <P>
425 </LI>
426
427 <LI><B>show radius</B><BR>
428 Show a summary of the in-use radius sessions. This list should not be very
429 long, as radius sessions should be cleaned up as soon as they are used. The
430 columns listed are:
431 <TABLE>
432 <TR><TD><B>Radius</B></TD><TD>The ID of the radius request. This is
433 sent in the packet to the radius server for identification.</TD></TR>
434 <TR><TD><B>State</B></TD><TD>The state of the request - WAIT, CHAP,
435 AUTH, IPCP, START, STOP, NULL.</TD></TR>
436 <TR><TD><B>Session</B></TD><TD>The session ID that this radius
437 request is associated with</TD></TR>
438 <TR><TD><B>Retry</B></TD><TD>If a response does not appear to the
439 request, it will retry at this time. This is a unix timestamp.</TD></TR>
440 <TR><TD><B>Try</B></TD><TD>Retry count. The radius request is
441 discarded after 3 retries.</TD></TR>
442 </TABLE>
443 <P>
444 </LI>
445
446 <LI><B>show running-config</B><BR>
447 This will list the current running configuration. This is in a format that
448 can either be pasted into the configuration file, or run directly at the
449 command line.
450 <P>
451 </LI>
452
453 <LI><B>show counters</B><BR>
454 Internally, counters are kept of key values, such as bytes and packets
455 transferred, as well as function call counters. This function displays all
456 these counters, and is probably only useful for debugging.<P>
457 You can reset these counters by running <EM>clear counters</EM>.
458 <P>
459 </LI>
460
461 <LI><B>write memory</B><BR>
462 This will write the current running configuration to the config file
463 l2tpns.cfg, which will be run on a restart.
464 <P>
465 </LI>
466
467 <LI><B>snoop</B><BR>
468 You must specify a username, which will be intercepted for the current
469 session. Specify <EM>no snoop username</EM> to disable interception for the
470 current session.<P>
471 If you want interception to be permanent, you will have to modify the radius
472 response for the user. See <EM>Interception</EM>.
473 <P>
474 </LI>
475
476 <LI><B>throttle</B><BR>
477 You must specify a username, which will be throttled for the current
478 session. Specify <EM>no throttle username</EM> to disable throttling for the
479 current session.<P>
480 If you want throttling to be permanent, you will have to modify the radius
481 response for the user. See <EM>Throttling</EM>.
482 <P>
483 </LI>
484
485 <LI><B>drop session</B><BR>
486 This will cleanly disconnect a session. You must specify a session id, which
487 you can get from <EM>show session</EM>. This will send a disconnect message
488 to the remote end.
489 <P>
490 </LI>
491
492 <LI><B>drop tunnel</B><BR>
493 This will cleanly disconnect a tunnel, as well as all sessions on that
494 tunnel. It will send a disconnect message for each session individually, and
495 after 10 seconds it will send a tunnel disconnect message.
496 <P>
497 </LI>
498
499 <LI><B>load plugin</B><BR>
500 Load a plugin. You must specify the plugin name, and it will search in
501 /usr/lib/l2tpns for <EM>plugin</EM>.so. You can unload a loaded plugin with
502 <EM>remove plugin</EM>.
503 <P>
504 </LI>
505
506 <LI><B>set</B><BR>
507 Set a configuration variable. You must specify the variable name, and the
508 value. If the value contains any spaces, you should quote the value with
509 double quotes (").
510 <P>
511 </LI>
512
513 <LI><B>uptime</B><BR>
514 This will show how long the L2TPNS process has been running, and the current
515 bandwidth utilization:
516 <PRE>
517 17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16
518 Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569
519 </PRE>
520 The bandwidth line contains 4 sets of values.<BR>
521 UDP-ETH is the current bandwidth going from the LAC to the ethernet
522 (user uploads), in mbits/sec.<BR>
523 ETH-UDP is the current bandwidth going from ethernet to the LAC (user
524 downloads).<BR>
525 TOTAL is the total aggregate bandwidth in mbits/s.<BR>
526 IN and OUT are packets/per-second going between UDP-ETH and ETH-UDP.
527 <P>
528 These counters are updated every second.
529 <P>
530 </LI>
531 </UL>
532
533 <H3>nsctl</H3>
534
535 nsctl was implemented (badly) to allow messages to be passed to modules.<P>
536
537 You must pass at least 2 parameters: <EM>host</EM> and <EM>command</EM>. The
538 host is the address of the L2TPNS server which you want to send the message
539 to.<BR>
540 Command can currently be either <EM>garden</EM> or <EM>ungarden</EM>. With
541 both of these commands, you must give a session ID as the 3rd parameter.
542 This will activate or deactivate the walled garden for a session
543 temporarily.
544
545 <H3>Signals</H3>
546
547 While the process is running, you can send it a few different signals, using
548 the kill command.
549 <PRE>
550 killall -HUP l2tpns
551 </PRE>
552
553 The signals understood are:
554 <UL>
555 <LI>SIGHUP - Reload the config from disk<P></LI>
556 <LI>SIGTERM / SIGINT - Shut down for a restart. This will dump the current
557 state to disk (if <EM>save_state</EM> is set to true). Upon restart, the
558 process will read this saved state to resume active sessions. <P>
559 This is really useful when doing an upgrade, as the code can change without
560 dropping any users. However, if the internal structures such as
561 <EM>sessiont</EM> or <EM>tunnelt</EM> change, then this saved state file
562 will not reload, and none of the sessions will be recreated. This is bad.<P>
563 If these structures do change, you should kill the server with SIGQUIT,
564 which won't dump the state.</LI>
565 <LI>SIGQUIT - Shut down cleanly. This will send a disconnect message for
566 every active session and tunnel before shutting down. This is a good idea
567 when upgrading the code, as no sessions will be left with the remote end
568 thinking they are open.</LI>
569 </UL>
570
571 <H2>Throttling</H2>
572
573 L2TPNS contains support for slowing down user sessions to whatever speed you
574 desire. You must first enable the global setting <EM>throttle_speed</EM>
575 before this will be activated. <P>
576
577 If you wish a session to be throttled permanently, you should set the
578 Vendor-Specific radius value <B>Cisco-Avpair="throttle=yes"</B>, which
579 will be handled by the <EM>autothrottle</EM> module.<P>
580
581 Otherwise, you can enable and disable throttling an active session using
582 the <EM>throttle</EM> CLI command.<P>
583
584 Throttling is actually performed using a combination of iptables and tc.<BR>
585 First, a HTB bucket is created using tc (unless one is already created and
586 unused).<BR>
587 Secondly, an iptables rule is inserted into the throttle chanin in the
588 mangle table so all packets destined for the user's IP address go into the
589 HTB.<P>
590
591 You can check the packets being throttled using the tc command. Find the HTB
592 handle by doing <EM>show session id</EM> in the CLI, next to the Filter
593 Bucket tag. Then at the shell prompt, you can run:
594 <PRE>
595 tc -s class ls dev tun0 | grep -A3 <EM>1:870</EM>
596 class htb 1:870 root prio 0 rate 28Kbit ceil 28Kbit burst 15Kb cburst 1634b
597 Sent 27042557 bytes 41464 pkts (dropped 1876, overlimits 0)
598 lended: 41471 borrowed: 0 giants: 0
599 tokens: 3490743 ctokens: 353601
600 </PRE>
601
602 <H2>Interception</H2>
603
604 You may have to deal with legal requirements to be able to intercept a
605 user's traffic at any time. L2TPNS allows you to begin and end interception
606 on the fly, as well as at authentication time.<P>
607
608 When a user is being intercepted, a copy of every packet they send and
609 receive will be sent wrapped in a UDP packet to the IP address and port set
610 in the <EM>snoop_host</EM> and <EM>snoop_port</EM> configuration
611 variables.<P>
612
613 The UDP packet contains just the raw IP frame, with no extra headers.<P>
614
615 To enable interception on a connected user, use the <EM>snoop username</EM>
616 and <EM>no snoop username</EM> CLI commands. These will enable interception
617 immediately.<P>
618
619 If you wish the user to be intercepted whenever they reconnect, you will
620 need to modify the radius response to include the Vendor-Specific value
621 <B>Cisco-Avpair="intercept=yes"</B>. For this feature to be enabled,
622 you need to have the <EM>autosnoop</EM> module loaded.<P>
623
624 <H2>Authentication</H2>
625
626 Whenever a session connects, it is not fully set up until authentication is
627 completed. The remote end must send a PPP CHAP or PPP PAP authentication
628 request to L2TPNS.<P>
629
630 This request is sent to the radius server, which will hopefully respond with
631 Auth-Accept or Auth-Reject.<P>
632
633 If Auth-Accept is received, the session is set up and an IP address is
634 assigned. The radius server can include a Framed-IP-Address field in the
635 reply, and that address will be assigned to the client. It can also include
636 specific DNS servers, and a Framed-Route if that is required.<P>
637
638 If Auth-Reject is received, then the client is sent a PPP AUTHNAK packet,
639 at which point they should disconnect. The exception to this is when the
640 walled garden module is loaded, in which case the user still receives the
641 PPP AUTHACK, but their session is flagged as being a garden'd user, and they
642 should not receive any service.<P>
643
644 The radius reply can also contain a Vendor-Specific attribute called
645 Cisco-Avpair. This field is a freeform text field that most CISCO
646 devices understand to contain configuration instructions for the session. In
647 the case of L2TPNS it is expected to be of the form
648 <PRE>
649 key=value,key2=value2,key3=value3,key<EM>n</EM>=<EM>value</EM>
650 </PRE>
651
652 Each key-value pair is separated and passed to any modules loaded. The
653 <EM>autosnoop</EM> and <EM>autothrottle</EM> understand the keys
654 <EM>intercept</EM> and <EM>throttle</EM> respectively. For example, to have
655 a user who is to be throttled and intercepted, the Cisco-Avpair value should
656 contain:
657 <PRE>
658 intercept=yes,throttle=yes
659 </PRE>
660
661 <H2>Plugins</H2>
662
663 So as to make L2TPNS as flexible as possible (I know the core code is pretty
664 difficult to understand), it includes a plugin API, which you can use to
665 hook into certain events.<P>
666
667 There are a few example modules included - autosnoop, autothrottle and
668 garden.<P>
669
670 When an event happens that has a hook, L2TPNS looks for a predefined
671 function name in every loaded module, and runs them in the order the modules
672 were loaded.<P>
673
674 The function should return <B>PLUGIN_RET_OK</B> if it is all OK. If it returns
675 <B>PLUGIN_RET_STOP</B>, then it is assumed to have worked, but that no further
676 modules should be run for this event.<P>
677 A return of <B>PLUGIN_RET_ERROR</B> means that this module failed, and
678 no further processing should be done for this event. <EM>Use this with care.</EM>
679
680 Every event function called takes a specific structure named
681 param_<EM>event</EM>, which varies in content with each event. The
682 function name for each event will be <B>plugin_<EM>event</EM></B>,
683 so for the event <EM>timer</EM>, the function declaration should look like:
684 <PRE>
685 int plugin_timer(struct param_timer *data);
686 </PRE>
687
688 A list of the available events follows, with a list of all the fields in the
689 supplied structure:
690 <TABLE CELLSPACING=0 CELLPADDING=0><TR BGCOLOR=LIGHTGREEN><TD>
691 <TABLE CELLSPACING=1 CELLPADDING=3>
692 <TR BGCOLOR=LIGHTGREEN><TH><B>Event</B></TH><TH><B>Description</B></TH><TH><B>Parameters</B></TH></TR>
693 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>pre_auth</B></TD>
694 <TD>This is called after a radius response has been
695 received, but before it has been processed by the
696 code. This will allow you to modify the response in
697 some way.
698 </TD>
699 <TD>
700 <UL>
701 <LI>t - Tunnel ID</LI>
702 <LI>s - Session ID</LI>
703 <LI>username</LI>
704 <LI>password</LI>
705 <LI>protocol (0xC023 for PAP, 0xC223 for CHAP)</LI>
706 <LI>continue_auth - Set to 0 to stop processing authentication modules</LI>
707 </UL>
708 </TD>
709 </TR>
710 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>post_auth</B></TD>
711 <TD>This is called after a radius response has been
712 received, and the basic checks have been performed. This
713 is what the garden module uses to force authentication
714 to be accepted.
715 </TD>
716 <TD>
717 <UL>
718 <LI>t - Tunnel ID</LI>
719 <LI>s - Session ID</LI>
720 <LI>username</LI>
721 <LI>auth_allowed - This is already set to true or
722 false depending on whether authentication has been
723 allowed so far. You can set this to 1 or 0 to force
724 allow or disallow authentication</LI>
725 <LI>protocol (0xC023 for PAP, 0xC223 for CHAP)</LI>
726 </UL>
727 </TD>
728 </TR>
729 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_rx</B></TD>
730 <TD>This is called whenever a session receives a
731 packet. <FONT COLOR=RED>Use this sparingly, as this will
732 seriously slow down the system.</FONT>
733 </TD>
734 <TD>
735 <UL>
736 <LI>t - Tunnel ID</LI>
737 <LI>s - Session ID</LI>
738 <LI>buf - The raw packet data</LI>
739 <LI>len - The length of buf</LI>
740 </UL>
741 </TD>
742 </TR>
743 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_tx</B></TD>
744 <TD>This is called whenever a session sends a
745 packet. <FONT COLOR=RED>Use this sparingly, as this will
746 seriously slow down the system.</FONT>
747 </TD>
748 <TD>
749 <UL>
750 <LI>t - Tunnel ID</LI>
751 <LI>s - Session ID</LI>
752 <LI>buf - The raw packet data</LI>
753 <LI>len - The length of buf</LI>
754 </UL>
755 </TD>
756 </TR>
757 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>timer</B></TD>
758 <TD>This is run every second, no matter what is happening.
759 This is called from a signal handler, so make sure anything
760 you do is reentrant.
761 </TD>
762 <TD>
763 <UL>
764 <LI>time_now - The current unix timestamp</LI>
765 </UL>
766 </TD>
767 </TR>
768 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>new_session</B></TD>
769 <TD>This is called after a session is fully set up. The
770 session is now ready to handle traffic.
771 </TD>
772 <TD>
773 <UL>
774 <LI>t - Tunnel ID</LI>
775 <LI>s - Session ID</LI>
776 </UL>
777 </TD>
778 </TR>
779 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>kill_session</B></TD>
780 <TD>This is called when a session is about to be shut down.
781 This may be called multiple times for the same session.
782 </TD>
783 <TD>
784 <UL>
785 <LI>t - Tunnel ID</LI>
786 <LI>s - Session ID</LI>
787 </UL>
788 </TD>
789 </TR>
790 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_response</B></TD>
791 <TD>This is called whenever a radius response includes a
792 Cisco-Avpair value. The value is split up into
793 <EM>key=value</EM> pairs, and each is processed through all
794 modules.
795 </TD>
796 <TD>
797 <UL>
798 <LI>t - Tunnel ID</LI>
799 <LI>s - Session ID</LI>
800 <LI>key</LI>
801 <LI>value</LI>
802 </UL>
803 </TD>
804 </TR>
805 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>control</B></TD>
806 <TD>This is called in whenever a nsctl packet is received.
807 This should handle the packet and form a response if
808 required.
809 </TD>
810 <TD>
811 <UL>
812 <LI>buf - The raw packet data</LI>
813 <LI>l - The raw packet data length</LI>
814 <LI>source_ip - Where the request came from</LI>
815 <LI>source_port - Where the request came from</LI>
816 <LI>response - Allocate a buffer and put your response in here</LI>
817 <LI>response_length - Length of response</LI>
818 <LI>send_response - true or false whether a response
819 should be sent. If you set this to true, you must
820 allocate a response buffer.</LI>
821 <LI>type - Type of request (see nsctl.c)</LI>
822 <LI>id - ID of request</LI>
823 <LI>data - I'm really not sure</LI>
824 <LI>data_length - Length of data</LI>
825 </UL>
826 </TD>
827 </TR>
828 </TABLE>
829 </TD></TR></TABLE>
830
831 <H2>Walled Garden</H2>
832
833 Walled Garden is implemented so that you can provide perhaps limited service
834 to sessions that incorrectly authenticate.<P>
835
836 Whenever a session provides incorrect authentication, and the
837 radius server responds with Auth-Reject, the walled garden module
838 (if loaded) will force authentication to succeed, but set the flag
839 <EM>garden</EM> in the session structure, and adds an iptables rule to
840 the <B>garden_users</B> chain to force all packets for the session's IP
841 address to traverse the <B>garden</B> chain.<P>
842
843 This doesn't <EM>just work</EM>. To set this all up, you will need to create
844 2 iptables chains on the nat table - <B>garden</B> and <B>garden_users</B>.
845 <PRE>
846 iptables -t nat -N garden
847 iptables -t nat -F garden
848 iptables -t nat -N garden_users
849 iptables -t nat -F garden_users
850 </PRE>
851
852 You should add rules to the <B>garden</B> chain to limit user's traffic. For
853 example, to force all traffic except DNS to be forwarded to 192.168.1.1, add
854 these entries to your firewall startup script:
855 <PRE>
856 iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
857 iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
858 </PRE>
859
860 L2TPNS will add entries to the garden_users chain as appropriate.<P>
861
862 You can check the amount of traffic being captured using the following
863 command:
864 <PRE>
865 iptables -t nat -L garden -nvx
866 </PRE>
867
868 <H2>Clustering</H2>
869
870 Clustering is currently broken. But here's how it's supposed to work.<P>
871
872 <H2>Performance</H2>
873
874 Performance is great.<P>
875
876 I'd like to include some pretty graphs here that show a linear performance
877 increase, with no impact by number of connected sessions.<P>
878
879 That's really what it looks like.<P>
880
881 <BR>
882 David Parrish<BR>
883 <A HREF="mailto:david@dparrish.com?subject=L2TPNS+Documentation">david@dparrish.com</A>
884 </BODY>
885 </HTML>