1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <TITLE>L2TPNS Manual
</TITLE>
7 <STYLE TYPE=
"text/css">
13 border-top:
1px solid black;
14 border-bottom:
1px solid black;
15 background-color: lightblue;
20 text-decoration: underline;
25 <H1>L2TPNS Manual
</H1>
27 <LI><A HREF=
"#Overview">Overview
</A></LI>
28 <LI><A HREF=
"#Installation">Installation
</A>
30 <LI><A HREF=
"#Requirements">Requirements
</A></LI>
31 <LI><A HREF=
"#Compile">Compile
</A></LI>
32 <LI><A HREF=
"#Install">Install
</A></LI>
33 <LI><A HREF=
"#Running">Running
</A></LI>
36 <LI><A HREF=
"#Configuration">Configuration
</A>
38 <LI><A HREF=
"#startup-config">startup-config
</A></LI>
39 <LI><A HREF=
"#users">users
</A></LI>
40 <LI><A HREF=
"#ip-pool">ip_pool
</A></LI>
41 <LI><A HREF=
"#build-garden">build-garden
</A></LI>
44 <LI><A HREF=
"#ControllingtheProcess">Controlling the Process
</A>
46 <LI><A HREF=
"#Command-LineInterface">Command-Line Interface
</A></LI>
47 <LI><A HREF=
"#nsctl">nsctl
</A></LI>
48 <LI><A HREF=
"#Signals">Signals
</A></LI>
51 <LI><A HREF=
"#Throttling">Throttling
</A></LI>
52 <LI><A HREF=
"#Interception">Interception
</A></LI>
53 <LI><A HREF=
"#Authentication">Authentication
</A></LI>
54 <LI><A HREF=
"#Plugins">Plugins
</A></LI>
55 <LI><A HREF=
"#WalledGarden">Walled Garden
</A></LI>
56 <LI><A HREF=
"#Filtering">Filtering
</A></LI>
57 <LI><A HREF=
"#Clustering">Clustering
</A></LI>
58 <LI><A HREF=
"#Routing">Routing
</A></LI>
59 <LI><A HREF=
"#AvoidingFragmentation">Avoiding Fragmentation
</A></LI>
60 <LI><A HREF=
"#Performance">Performance
</A></LI>
63 <H2 ID=
"Overview">Overview
</H2>
64 l2tpns is half of a complete L2TP implementation. It supports only the
65 LNS side of the connection.
<P>
67 L2TP (Layer
2 Tunneling Protocol) is designed to allow any layer
2
68 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection. l2tpns
69 implements PPP over L2TP only.
<P>
71 There are a couple of other L2TP implementations, of which
<A
72 HREF=
"http://sourceforge.net/projects/l2tpd">l2tpd
</A> is probably the
73 most popular. l2tpd also will handle being either end of a tunnel, and
74 is a lot more configurable than l2tpns. However, due to the way it works,
75 it is nowhere near as scalable.
<P>
77 l2tpns uses the TUN/TAP interface provided by the Linux kernel to receive
78 and send packets. Using some packet manipulation it doesn't require a
79 single interface per connection, as l2tpd does.
<P>
81 This allows it to scale extremely well to very high loads and very high
82 numbers of connections.
<P>
84 It also has a plugin architecture which allows custom code to be run
85 during processing. An example of this is in the walled garden module
89 <EM>Documentation is not my best skill. If you find any problems
90 with this document, or if you wish to contribute, please email
<A
91 HREF=
"mailto:l2tpns-users@lists.sourceforge.net?subject=L2TPNS+Documentation">the mailing list
</A>.
</EM><P>
93 <H2 ID=
"Installation">Installation
</H2>
94 <H3 ID=
"Requirements">Requirements
</H3>
97 <LI>Linux kernel version
2.4 or above, with the Tun/Tap interface either
98 compiled in, or as a module.
</LI>
100 <LI>libcli
1.8.0 or greater.
<BR>You can get this from
<A
101 HREF=
"http://sourceforge.net/projects/libcli">http://sourceforge.net/projects/libcli
</A></LI>
104 <H3 ID=
"Compile">Compile
</H3>
106 You can generally get away with just running
<B>make
</B> from the source
107 directory. This will compile the daemon, associated tools and any modules
108 shipped with the distribution.
<P>
110 <H3 ID=
"Install">Install
</H3>
112 After you have successfully compiled everything, run
<B>make
113 install
</B> to install it. By default, the binaries are installed into
114 <EM>/usr/sbin
</EM>, the configuration into
<EM>/etc/l2tpns
</EM>, and the
115 modules into
<EM>/usr/lib/l2tpns
</EM>.
<P>
117 You will definately need to edit the configuration files before you
118 start. See the
<A HREF=
"#Configuration">Configuration
</A> section for
121 <H3 ID=
"Running">Running
</H3>
123 You only need to run
<B>/usr/sbin/l2tpns
</B> as root to start it. It does
124 not detach to a daemon process, so you should perhaps run it from init.
<P>
126 By default there is no log destination set, so all log messages will go to
129 <H2 ID=
"Configuration">Configuration
</H2>
131 All configuration of the software is done from the files installed into
134 <H3 ID=
"startup-config">startup-config
</H3>
136 This is the main configuration file for l2tpns. The format of the file is a
137 list of commands that can be run through the command-line interface. This
138 file can also be written directly by the l2tpns process if a user runs the
139 <EM>write memory
</EM> command, so any comments will be lost. However if your
140 policy is not to write the config by the program, then feel free to comment
141 the file with a # or ! at the beginning of the line.
<P>
143 A list of the possible configuration directives follows. Each of these
144 should be set by a line like:
<P>
146 set configstring
"value"
147 set ipaddress
192.168.1.1
153 <LI><B>debug
</B> (int)
<BR>
154 Sets the level of messages that will be written to the log file. The value
155 should be between
0 and
5, with
0 being no debugging, and
5 being the
156 highest. A rough description of the levels is:
158 <LI VALUE=
0>Critical Errors - Things are probably broken
</LI>
159 <LI>Errors - Things might have gone wrong, but probably will recover
</LI>
160 <LI>Warnings - Just in case you care what is not quite perfect
</LI>
161 <LI>Information - Parameters of control packets
</LI>
162 <LI>Calls - For tracing the execution of the code
</LI>
163 <LI>Packets - Everything, including a hex dump of all packets processed... probably twice
</LI>
165 Note that the higher you set the debugging level, the slower the program
166 will run. Also, at level
5 a LOT of information will be logged. This should
167 only ever be used for working out why it doesn't work at all.
170 <LI><B>log_file
</B> (string)
<BR>
171 This will be where all logging and debugging information is written
172 to. This may be either a filename, such as
<EM>/var/log/l2tpns
</EM>, or
173 the special magic string
<EM>syslog:facility
</EM>, where
<EM>facility
</EM>
174 is any one of the syslog logging facilities, such as local5.
177 <LI><B>pid_file
</B> (string)
<BR>
178 If set, the process id will be written to the specified file. The
179 value must be an absolute path.
182 <LI><B>l2tp_secret
</B> (string)
<BR>
183 The secret used by l2tpns for authenticating tunnel request. Must be
184 the same as the LAC, or authentication will fail. Only actually be
185 used if the LAC requests authentication.
188 <LI><B>l2tp_mtu
</B> (int)
<BR>
189 MTU of interface for L2TP traffic (default:
1500). Used to set link
190 MRU and adjust TCP MSS.
193 <LI><B>ppp_restart_time
</B> (int)
<BR>
194 <B>ppp_max_configure
</B> (int)
<BR>
195 <B>ppp_max_failure
</B> (int)
<BR>
196 PPP counter and timer values, as described in
§4.1 of
197 <a href=
"ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt">RFC1661
</a>.
200 <LI><B>primary_dns
</B> (ip address)
201 <LI><B>secondary_dns
</B> (ip address)
<BR>
202 Whenever a PPP connection is established, DNS servers will be sent to the
203 user, both a primary and a secondary. If either is set to
0.0.0.0, then that
204 one will not be sent.
207 <LI><B>primary_radius
</B> (ip address)
208 <LI><B>secondary_radius
</B> (ip address)
<BR>
209 Sets the RADIUS servers used for both authentication and accounting.
210 If the primary server does not respond, then the secondary RADIUS
211 server will be tried.
<br>
212 <strong>Note:
</strong> in addition to the source IP address and
213 identifier, the RADIUS server
<strong>must
</strong> include the source
214 port when detecting duplicates to supress (in order to cope with a
215 large number of sessions comming on-line simultaneously l2tpns uses a
216 set of udp sockets, each with a seperate identifier).
219 <LI><B>primary_radius_port
</B> (short)
220 <LI><B>secondary_radius_port
</B> (short)
<BR>
221 Sets the authentication ports for the primary and secondary RADIUS
222 servers. The accounting port is one more than the authentication
223 port. If no RADIUS ports are given, the authentication port defaults
224 to
1645, and the accounting port to
1646.
227 <LI><B>radius_accounting
</B> (boolean)
<BR>
228 If set to true, then RADIUS accounting packets will be sent. This
229 means that a Start record will be sent when the session is
230 successfully authenticated, and a Stop record will be sent when the
234 <LI><B>radius_secret
</B> (string)
<BR>
235 This secret will be used in all RADIUS queries. If this is not set then
236 RADIUS queries will fail.
239 <LI><B>radius_authtypes
</B> (string)
</BR>
240 A comma separated list of supported RADIUS authentication methods
241 (
<B>pap
</B> or
<B>chap
</B>), in order of preference (default
<B>pap
</B>).
244 <LI><B>radius_dae_port
</B> (short)
<BR>
245 Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization)
246 requests (default:
<B>3799</B>).
249 <LI><B>allow_duplicate_users
</B> (boolean)
</BR>
250 Allow multiple logins with the same username. If false (the default),
251 any prior session with the same username will be dropped when a new
252 session is established.
255 <LI><B>bind_address
</B> (ip address)
<BR>
256 When the tun interface is created, it is assigned the address
257 specified here. If no address is given,
1.1.1.1 is used. Packets
258 containing user traffic should be routed via this address if given,
259 otherwise the primary address of the machine.
262 <LI><B>peer_address
</B> (ip address)
<BR>
263 Address to send to clients as the default gateway.
266 <LI><B>send_garp
</B> (boolean)
<BR>
267 Determines whether or not to send a gratuitous ARP for the
268 bind_address when the server is ready to handle traffic (default:
270 This value is ignored if BGP is configured.
273 <LI><B>throttle_speed
</B> (int)
<BR>
274 Sets the default speed (in kbits/s) which sessions will be limited to.
275 If this is set to
0, then throttling will not be used at all. Note:
276 You can set this by the CLI, but changes will not affect currently
280 <LI><B>throttle_buckets
</B> (int)
<BR>
281 Number of token buckets to allocate for throttling. Each throttled
282 session requires two buckets (in and out).
285 <LI><B>accounting_dir
</B> (string)
<BR>
286 If set to a directory, then every
5 minutes the current usage for
287 every connected use will be dumped to a file in this directory. Each
288 file dumped begins with a header, where each line is prefixed by #.
289 Following the header is a single line for every connected user, fields
290 separated by a space.
<BR> The fields are username, ip, qos,
291 uptxoctets, downrxoctets. The qos field is
1 if a standard user, and
292 2 if the user is throttled.
295 <LI><B>setuid
</B> (int)
<BR>
296 After starting up and binding the interface, change UID to this. This
297 doesn't work properly.
300 <LI><B>dump_speed
</B> (boolean)
<BR>
301 If set to true, then the current bandwidth utilization will be logged every
302 second. Even if this is disabled, you can see this information by running
303 the
<EM>uptime
</EM> command on the CLI.
306 <LI><B>multi_read_count
</B> (int)
<BR>
307 Number of packets to read off each of the UDP and TUN fds when
308 returned as readable by select (default:
10). Avoids incurring the
309 unnecessary system call overhead of select on busy servers.
312 <LI><B>scheduler_fifo
</B> (boolean)
<BR>
313 Sets the scheduling policy for the l2tpns process to SCHED_FIFO. This
314 causes the kernel to immediately preempt any currently running SCHED_OTHER
315 (normal) process in favour of l2tpns when it becomes runnable.
316 Ignored on uniprocessor systems.
319 <LI><B>lock_pages
</B> (boolean)
<BR>
320 Keep all pages mapped by the l2tpns process in memory.
323 <LI><B>icmp_rate
</B> (int)
<BR>
324 Maximum number of host unreachable ICMP packets to send per second.
327 <LI><B>packet_limit
</B> (int
><BR>
328 Maximum number of packets of downstream traffic to be handled each
329 tenth of a second per session. If zero, no limit is applied (default:
330 0). Intended as a DoS prevention mechanism and not a general
331 throttling control (packets are dropped, not queued).
334 <LI><B>cluster_address
</B> (ip address)
<BR>
335 Multicast cluster address (default:
239.192.13.13). See the section
336 on
<A HREF=
"#Clustering">Clustering
</A> for more information.
339 <LI><B>cluster_interface
</B> (string)
<BR>
340 Interface for cluster packets (default: eth0).
343 <LI><B>cluster_mcast_ttl
</B> (int)
<BR>
344 TTL for multicast packets (default:
1).
347 <LI><B>cluster_hb_interval
</B> (int)
<BR>
348 Interval in tenths of a second between cluster heartbeat/pings.
351 <LI><B>cluster_hb_timeout
</B> (int)
<BR>
352 Cluster heartbeat timeout in tenths of a second. A new master will be
353 elected when this interval has been passed without seeing a heartbeat
357 <LI><B>cluster_master_min_adv
</B> (int)
<BR>
358 Determines the minumum number of up to date slaves required before the
359 master will drop routes (default:
1).
363 <P>BGP routing configuration is entered by the command:
364 The routing configuration section is entered by the command
365 <DL><DD><B>router bgp
</B> <I>as
</I></DL>
366 where
<I>as
</I> specifies the local AS number.
368 <P>Subsequent lines prefixed with
369 <DL><DD><B>neighbour
</B> <I>peer
</I></DL>
370 define the attributes of BGP neighhbours. Valid commands are:
372 <DD><B>neighbour
</B> <I>peer
</I> <B>remote-as
</B> <I>as
</I>
373 <DD><B>neighbout
</B> <I>peer
</I> <B>timers
</B> <I>keepalive hold
</I>
376 Where
<I>peer
</I> specifies the BGP neighbour as either a hostname or
377 IP address,
<I>as
</I> is the remote AS number and
<I>keepalive
</I>,
378 <I>hold
</I> are the timer values in seconds.
380 <P>Named access-lists are configured using one of the commands:
382 <DD><B>ip access-list standard
</B> <I>name
</I>
383 <DD><B>ip access-list extended
</B> <I>name
</I>
386 <P>Subsequent lines prefixed with
<B>permit
</B> or
<B>deny
</B>
387 define the body of the access-list. Standard access-list syntax:
389 <DD>{
<B>permit
</B>|
<B>deny
</B>}
390 {
<I>host
</I>|
<I>source source-wildcard
</I>|
<B>any
</B>}
391 [{
<I>host
</I>|
<I>destination destination-wildcard
</I>|
<B>any
</B>}]
394 Extended access-lists:
396 <DIV STYLE=
"margin-left: 4em; text-indent: -2em">
397 <P>{
<B>permit
</B>|
<B>deny
</B>}
<B>ip
</B>
398 {
<I>host
</I>|
<I>source source-wildcard
</I>|
<B>any
</B>}
399 {
<I>host
</I>|
<I>destination destination-wildcard
</I>|
<B>any
</B>} [
<B>fragments
</B>]
400 <P>{
<B>permit
</B>|
<B>deny
</B>}
<B>udp
</B>
401 {
<I>host
</I>|
<I>source source-wildcard
</I>|
<B>any
</B>}
402 [{
<B>eq
</B>|
<B>neq
</B>|
<B>gt
</B>|
<B>lt
</B>}
<I>port
</I>|
<B>range
</B> <I>from
</I> <I>to
</I>]
403 {
<I>host
</I>|
<I>destination destination-wildcard
</I>|
<B>any
</B>}
404 [{
<B>eq
</B>|
<B>neq
</B>|
<B>gt
</B>|
<B>lt
</B>}
<I>port
</I>|
<B>range
</B> <I>from
</I> <I>to
</I>]
406 <P>{
<B>permit
</B>|
<B>deny
</B>}
<B>tcp
</B>
407 {
<I>host
</I>|
<I>source source-wildcard
</I>|
<B>any
</B>}
408 [{
<B>eq
</B>|
<B>neq
</B>|
<B>gt
</B>|
<B>lt
</B>}
<I>port
</I>|
<B>range
</B> <I>from
</I> <I>to
</I>]
409 {
<I>host
</I>|
<I>destination destination-wildcard
</I>|
<B>any
</B>}
410 [{
<B>eq
</B>|
<B>neq
</B>|
<B>gt
</B>|
<B>lt
</B>}
<I>port
</I>|
<B>range
</B> <I>from
</I> <I>to
</I>]
411 [{
<B>established
</B>|{
<B>match-any
</B>|
<B>match-all
</B>}
412 {
<B>+
</B>|
<B>-
</B>}{
<B>fin
</B>|
<B>syn
</B>|
<B>rst
</B>|
<B>psh
</B>|
<B>ack
</B>|
<B>urg
</B>}
413 ...|
<B>fragments
</B>]
416 <H3 ID=
"users">users
</H3>
418 Usernames and passwords for the command-line interface are stored in
419 this file. The format is
<I>username
</I><B>:
</B><I>password
</I> where
420 <I>password
</I> may either by plain text, an MD5 digest (prefixed by
421 <B>$
1</B><I>salt
</I><B>$
</B>) or a DES password, distinguished from
422 plain text by the prefix
<B>{crypt}
</B>.
<P>
424 The username
<B>enable
</B> has a special meaning and is used to set
425 the enable password.
<P>
427 <B>Note:
</B> If this file doesn't exist, then anyone who can get to
428 port
23 will be allowed access without a username / password.
<P>
430 <H3 ID=
"ip-pool">ip_pool
</H3>
432 This file is used to configure the IP address pool which user
433 addresses are assigned from. This file should contain either an IP
434 address or a CIDR network per line. e.g.:
<P>
445 Keep in mind that l2tpns can only handle
65535 connections per
446 process, so don't put more than
65535 IP addresses in the
447 configuration file. They will be wasted.
449 <H3 ID=
"build-garden">build-garden
</H3>
451 The garden plugin on startup creates a NAT table called
"garden" then
452 sources the
<B>build-garden
</B> script to populate that table. All
453 packets from gardened users will be sent through this table. Example:
456 iptables -t nat -A garden -p tcp -m tcp --dport
25 -j DNAT --to
192.168.1.1
457 iptables -t nat -A garden -p udp -m udp --dport
53 -j DNAT --to
192.168.1.1
458 iptables -t nat -A garden -p tcp -m tcp --dport
53 -j DNAT --to
192.168.1.1
459 iptables -t nat -A garden -p tcp -m tcp --dport
80 -j DNAT --to
192.168.1.1
460 iptables -t nat -A garden -p tcp -m tcp --dport
110 -j DNAT --to
192.168.1.1
461 iptables -t nat -A garden -p tcp -m tcp --dport
443 -j DNAT --to
192.168.1.1
462 iptables -t nat -A garden -p icmp -m icmp --icmp-type echo-request -j DNAT --to
192.168.1.1
463 iptables -t nat -A garden -p icmp -j ACCEPT
464 iptables -t nat -A garden -j DROP
467 <H2 ID=
"ControllingtheProcess">Controlling the Process
</H2>
469 A running l2tpns process can be controlled in a number of ways. The primary
470 method of control is by the Command-Line Interface (CLI).
<P>
472 You can also remotely send commands to modules via the nsctl client
475 Also, there are a number of signals that l2tpns understands and takes action
476 when it receives them.
478 <H3 ID=
"Command-LineInterface">Command-Line Interface
</H3>
480 You can access the command line interface by telnet'ing to port
23.
481 There is no IP address restriction, so it's a good idea to firewall
482 this port off from anyone who doesn't need access to it. See
483 <A HREF=
"#users">users
</A> for information on restricting access based
484 on a username and password.
<P>
486 The CLI gives you real-time control over almost everything in
487 the process. The interface is designed to look like a Cisco
488 device, and supports things like command history, line editing and
489 context sensitive help. This is provided by linking with the
490 <A HREF=
"http://sourceforge.net/projects/libcli">libcli
</A>
491 library. Some general documentation of the interface is
492 <A HREF=
"http://sourceforge.net/docman/display_doc.php?docid=20501&group_id=79019">
495 After you have connected to the telnet port (and perhaps logged in), you
496 will be presented with a
<I>hostname
</I><B>></B> prompt.
<P>
498 Enter
<EM>help
</EM> to get a list of possible commands. A brief
499 overview of the more important commands follows:
502 <LI><B>show session
</B><BR>
503 Without specifying a session ID, this will list all tunnels currently
504 connected. If you specify a session ID, you will be given all
505 information on a single tunnel. Note that the full session list can
506 be around
185 columns wide, so you should probably use a wide terminal
507 to see the list properly.
<P>
508 The columns listed in the overview are:
510 <TR><TD><B>SID
</B></TD><TD>Session ID
</TD></TR>
511 <TR><TD><B>TID
</B></TD><TD>Tunnel ID - Use with
<EM>show tunnel tid
</EM></TD></TR>
512 <TR><TD><B>Username
</B></TD><TD>The username given in the PPP
513 authentication. If this is *, then LCP authentication has not
515 <TR><TD><B>IP
</B></TD><TD>The IP address given to the session. If
516 this is
0.0.0.0, LCP negotiation has not completed.
</TD></TR>
517 <TR><TD><B>I
</B></TD><TD>Intercept - Y or N depending on whether the
518 session is being snooped. See
<EM>snoop
</EM>.
</TD></TR>
519 <TR><TD><B>T
</B></TD><TD>Throttled - Y or N if the session is
520 currently throttled. See
<EM>throttle
</EM>.
</TD></TR>
521 <TR><TD><B>G
</B></TD><TD>Walled Garden - Y or N if the user is
522 trapped in the walled garden. This field is present even if the
523 garden module is not loaded.
</TD></TR>
524 <TR><TD><B>opened
</B></TD><TD>The number of seconds since the
525 session started
</TD></TR>
526 <TR><TD><B>downloaded
</B></TD><TD>Number of bytes downloaded by the user
</TD></TR>
527 <TR><TD><B>uploaded
</B></TD><TD>Number of bytes uploaded by the user
</TD></TR>
528 <TR><TD><B>idle
</B></TD><TD>The number of seconds since traffic was
529 detected on the session
</TD></TR>
530 <TR><TD><B>LAC
</B></TD><TD>The IP address of the LAC the session is
531 connected to.
</TD></TR>
532 <TR><TD><B>CLI
</B></TD><TD>The Calling-Line-Identification field
533 provided during the session setup. This field is generated by the
539 <LI><B>show users
</B><BR>
540 With no arguments, display a list of currently connected users. If an
541 argument is given, the session details for the given username are
545 <LI><B>show tunnel
</B><BR>
546 This will show all the open tunnels in a summary, or detail on a single
547 tunnel if you give a tunnel id.
<P>
548 The columns listed in the overview are:
550 <TR><TD><B>TID
</B></TD><TD>Tunnel ID
</TD></TR>
551 <TR><TD><B>Hostname
</B></TD><TD>The hostname for the tunnel as
552 provided by the LAC. This has no relation to DNS, it is just
553 a text field.
</TD></TR>
554 <TR><TD><B>IP
</B></TD><TD>The IP address of the LAC
</TD></TR>
555 <TR><TD><B>State
</B></TD><TD>Tunnel state - Free, Open, Dieing,
557 <TR><TD><B>Sessions
</B></TD><TD>The number of open sessions on the
563 <LI><B>show pool
</B><BR>
564 Displays the current IP address pool allocation. This will only display
565 addresses that are in use, or are reserved for re-allocation to a
566 disconnected user.
<P>
567 If an address is not currently in use, but has been used, then in the User
568 column the username will be shown in square brackets, followed by the time
569 since the address was used:
571 IP Address Used Session User
572 192.168.100.6 N [joe.user]
1548s
577 <LI><B>show radius
</B><BR>
578 Show a summary of the in-use RADIUS sessions. This list should not be very
579 long, as RADIUS sessions should be cleaned up as soon as they are used. The
582 <TR><TD><B>Radius
</B></TD><TD>The ID of the RADIUS request. This is
583 sent in the packet to the RADIUS server for identification.
</TD></TR>
584 <TR><TD><B>State
</B></TD><TD>The state of the request - WAIT, CHAP,
585 AUTH, IPCP, START, STOP, NULL.
</TD></TR>
586 <TR><TD><B>Session
</B></TD><TD>The session ID that this RADIUS
587 request is associated with
</TD></TR>
588 <TR><TD><B>Retry
</B></TD><TD>If a response does not appear to the
589 request, it will retry at this time. This is a unix timestamp.
</TD></TR>
590 <TR><TD><B>Try
</B></TD><TD>Retry count. The RADIUS request is
591 discarded after
3 retries.
</TD></TR>
596 <LI><B>show running-config
</B><BR>
597 This will list the current running configuration. This is in a format that
598 can either be pasted into the configuration file, or run directly at the
603 <LI><B>show counters
</B><BR>
604 Internally, counters are kept of key values, such as bytes and packets
605 transferred, as well as function call counters. This function displays all
606 these counters, and is probably only useful for debugging.
<P>
607 You can reset these counters by running
<EM>clear counters
</EM>.
611 <LI><B>show cluster
</B><BR>
612 Show cluster status. Shows the cluster state for this server
613 (Master/Slave), information about known peers and (for slaves) the
614 master IP address, last packet seen and up-to-date status.
<P>
615 See
<A HREF=
"#Clustering">Clustering
</A> for more information.
619 <LI><B>write memory
</B><BR>
620 This will write the current running configuration to the config file
621 <B>startup-config
</B>, which will be run on a restart.
626 You must specify a username, IP address and port. All packets for the
627 current session for that username will be forwarded to the given
628 host/port. Specify
<EM>no snoop username
</EM> to disable interception
631 If you want interception to be permanent, you will have to modify the RADIUS
632 response for the user. See
<A HREF=
"#Interception">Interception
</A>.
636 <LI><B>throttle
</B><BR>
637 You must specify a username, which will be throttled for the current
638 session. Specify
<EM>no throttle username
</EM> to disable throttling
639 for the current session.
<P>
641 If you want throttling to be permanent, you will have to modify the
642 RADIUS response for the user. See
<A HREF=
"#Throttling">Throttling
</A>.
646 <LI><B>drop session
</B><BR>
647 This will cleanly disconnect a session. You must specify a session id, which
648 you can get from
<EM>show session
</EM>. This will send a disconnect message
653 <LI><B>drop tunnel
</B><BR>
654 This will cleanly disconnect a tunnel, as well as all sessions on that
655 tunnel. It will send a disconnect message for each session individually, and
656 after
10 seconds it will send a tunnel disconnect message.
660 <LI><B>uptime
</B><BR>
661 This will show how long the l2tpns process has been running, and the current
662 bandwidth utilization:
664 17:
10:
35 up
8 days,
2212 users, load average:
0.21,
0.17,
0.16
665 Bandwidth: UDP-ETH:
6/
6 ETH-UDP:
13/
13 TOTAL:
37.6 IN:
3033 OUT:
2569
667 The bandwidth line contains
4 sets of values.
<BR>
668 UDP-ETH is the current bandwidth going from the LAC to the ethernet
669 (user uploads), in mbits/sec.
<BR>
670 ETH-UDP is the current bandwidth going from ethernet to the LAC (user
672 TOTAL is the total aggregate bandwidth in mbits/s.
<BR>
673 IN and OUT are packets/per-second going between UDP-ETH and ETH-UDP.
675 These counters are updated every second.
679 <LI><B>configure terminal
</B><BR>
680 Enter configuration mode. Use
<EM>exit
</EM> or ^Z to exit this mode.
681 The following commands are valid in this mode:
<P>
684 <LI><B>load plugin
</B><BR>
685 Load a plugin. You must specify the plugin name, and it will search in
686 /usr/lib/l2tpns for
<EM>plugin
</EM>.so. You can unload a loaded plugin with
687 <EM>remove plugin
</EM>.
692 Set a configuration variable. You must specify the variable name, and
693 the value. If the value contains any spaces, you should quote the
694 value with double (
") or single (') quotes.<P>
696 You can set any <A HREF="#startup-config
">startup-config</A> value in
697 this way, although some may require a restart to take effect.<P>
701 <H3 ID="nsctl
">nsctl</H3>
703 nsctl allows messages to be passed to plugins.<P>
705 Arguments are <EM>command</EM> and optional <EM>args</EM>. See
706 <STRONG>nsctl</STRONG>(8) for more details.<P>
708 Built-in command are <EM>load_plugin</EM>, <EM>unload_plugin</EM> and
709 <EM>help</EM>. Any other commands are passed to plugins for processing.
711 <H3 ID="Signals
">Signals</H3>
713 While the process is running, you can send it a few different signals, using
719 The signals understood are:
721 <DT>SIGHUP</DT><DD>Reload the config from disk and re-open log file.</DD>
722 <DT>SIGTERM, SIGINT</DT><DD>Stop process. Tunnels and sessions are not
723 terminated. This signal should be used to stop l2tpns on a
724 <A HREF="#Clustering
">cluster node</A> where there are other machines to
725 continue handling traffic.</DD>
726 <DT>SIGQUIT</DT><DD>Shut down tunnels and sessions, exit process when
730 <H2 ID="Throttling
">Throttling</H2>
732 l2tpns contains support for slowing down user sessions to whatever speed you
733 desire. You must first enable the global setting <EM>throttle_speed</EM>
734 before this will be activated.<P>
736 If you wish a session to be throttled permanently, you should set the
737 Vendor-Specific RADIUS value <B>Cisco-Avpair="throttle=yes
"</B>, which
738 will be handled by the <EM>autothrottle</EM> module.<P>
740 Otherwise, you can enable and disable throttling an active session using
741 the <EM>throttle</EM> CLI command.<P>
743 <H2 ID="Interception
">Interception</H2>
745 You may have to deal with legal requirements to be able to intercept a
746 user's traffic at any time. l2tpns allows you to begin and end interception
747 on the fly, as well as at authentication time.<P>
749 When a user is being intercepted, a copy of every packet they send and
750 receive will be sent wrapped in a UDP packet to the IP address and port set
751 in the <EM>snoop_host</EM> and <EM>snoop_port</EM> configuration
754 The UDP packet contains just the raw IP frame, with no extra headers.<P>
756 To enable interception on a connected user, use the <EM>snoop username</EM>
757 and <EM>no snoop username</EM> CLI commands. These will enable interception
760 If you wish the user to be intercepted whenever they reconnect, you will
761 need to modify the RADIUS response to include the Vendor-Specific value
762 <B>Cisco-Avpair="intercept=yes
"</B>. For this feature to be enabled,
763 you need to have the <EM>autosnoop</EM> module loaded.<P>
765 <H2 ID="Authentication
">Authentication</H2>
767 Whenever a session connects, it is not fully set up until authentication is
768 completed. The remote end must send a PPP CHAP or PPP PAP authentication
769 request to l2tpns.<P>
771 This request is sent to the RADIUS server, which will hopefully respond with
772 Auth-Accept or Auth-Reject.<P>
774 If Auth-Accept is received, the session is set up and an IP address is
775 assigned. The RADIUS server can include a Framed-IP-Address field in the
776 reply, and that address will be assigned to the client. It can also include
777 specific DNS servers, and a Framed-Route if that is required.<P>
779 If Auth-Reject is received, then the client is sent a PPP AUTHNAK packet,
780 at which point they should disconnect. The exception to this is when the
781 walled garden module is loaded, in which case the user still receives the
782 PPP AUTHACK, but their session is flagged as being a garden'd user, and they
783 should not receive any service.<P>
785 The RADIUS reply can also contain a Vendor-Specific attribute called
786 Cisco-Avpair. This field is a freeform text field that most Cisco
787 devices understand to contain configuration instructions for the session. In
788 the case of l2tpns it is expected to be of the form
790 key=value,key2=value2,key3=value3,key<EM>n</EM>=<EM>value</EM>
793 Each key-value pair is separated and passed to any modules loaded. The
794 <EM>autosnoop</EM> and <EM>autothrottle</EM> understand the keys
795 <EM>intercept</EM> and <EM>throttle</EM> respectively. For example, to have
796 a user who is to be throttled and intercepted, the Cisco-Avpair value should
799 intercept=yes,throttle=yes
802 <H2 ID="Plugins
">Plugins</H2>
804 So as to make l2tpns as flexible as possible (I know the core code is pretty
805 difficult to understand), it includes a plugin API, which you can use to
806 hook into certain events.<P>
808 There are a few example modules included - autosnoop, autothrottle and
811 When an event happens that has a hook, l2tpns looks for a predefined
812 function name in every loaded module, and runs them in the order the modules
815 The function should return <B>PLUGIN_RET_OK</B> if it is all OK. If it returns
816 <B>PLUGIN_RET_STOP</B>, then it is assumed to have worked, but that no further
817 modules should be run for this event.<P>
818 A return of <B>PLUGIN_RET_ERROR</B> means that this module failed, and
819 no further processing should be done for this event. <EM>Use this with care.</EM>
821 Every event function called takes a specific structure named
822 param_<EM>event</EM>, which varies in content with each event. The
823 function name for each event will be <B>plugin_<EM>event</EM></B>,
824 so for the event <EM>timer</EM>, the function declaration should look like:
826 int plugin_timer(struct param_timer *data);
829 A list of the available events follows, with a list of all the fields in the
831 <TABLE CELLSPACING=0 CELLPADDING=0><TR BGCOLOR=LIGHTGREEN><TD>
832 <TABLE CELLSPACING=1 CELLPADDING=3>
833 <TR BGCOLOR=LIGHTGREEN><TH><B>Event</B></TH><TH><B>Description</B></TH><TH><B>Parameters</B></TH></TR>
834 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>pre_auth</B></TD>
835 <TD>This is called after a RADIUS response has been
836 received, but before it has been processed by the
837 code. This will allow you to modify the response in
846 <DT>protocol<DD>0xC023 for PAP, 0xC223 for CHAP
847 <DT>continue_auth<DD>Set to 0 to stop processing authentication modules
851 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>post_auth</B></TD>
852 <TD>This is called after a RADIUS response has been
853 received, and the basic checks have been performed. This
854 is what the garden module uses to force authentication
862 <DT>auth_allowed<DD>This is already set to true or
863 false depending on whether authentication has been
864 allowed so far. You can set this to 1 or 0 to force
865 allow or disallow authentication
866 <DT>protocol<DD>0xC023 for PAP, 0xC223 for CHAP
870 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_rx</B></TD>
871 <TD>This is called whenever a session receives a
872 packet. <FONT COLOR=RED>Use this sparingly, as this will
873 seriously slow down the system.</FONT>
879 <DT>buf<DD>The raw packet data
880 <DT>len<DD>The length of buf
884 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>packet_tx</B></TD>
885 <TD>This is called whenever a session sends a
886 packet. <FONT COLOR=RED>Use this sparingly, as this will
887 seriously slow down the system.</FONT>
893 <DT>buf<DD>The raw packet data
894 <DT>len<DD>The length of buf
898 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>timer</B></TD>
899 <TD>This is run every second, no matter what is happening.
900 This is called from a signal handler, so make sure anything
905 <DT>time_now<DD>The current unix timestamp
909 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>new_session</B></TD>
910 <TD>This is called after a session is fully set up. The
911 session is now ready to handle traffic.
920 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>kill_session</B></TD>
921 <TD>This is called when a session is about to be shut down.
922 This may be called multiple times for the same session.
931 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_response</B></TD>
932 <TD>This is called whenever a RADIUS response includes a
933 Cisco-Avpair value. The value is split up into
934 <EM>key=value</EM> pairs, and each is processed through all
946 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>radius_reset</B></TD>
947 <TD>This is called whenever a RADIUS CoA request is
948 received to reset any options to default values before
949 the new values are applied.
958 <TR VALIGN=TOP BGCOLOR=WHITE><TD><B>control</B></TD>
959 <TD>This is called in whenever a nsctl packet is received.
960 This should handle the packet and form a response if
965 <DT>iam_master<DD>Cluster master status
966 <DT>argc<DD>The number of arguments
967 <DT>argv<DD>Arguments
968 <DT>response<DD>Return value: NSCTL_RES_OK or NSCTL_RES_ERR
969 <DT>additional<DD>Extended response text
976 <H2 ID="WalledGarden
">Walled Garden</H2>
978 Walled Garden is implemented so that you can provide perhaps limited service
979 to sessions that incorrectly authenticate.<P>
981 Whenever a session provides incorrect authentication, and the
982 RADIUS server responds with Auth-Reject, the walled garden module
983 (if loaded) will force authentication to succeed, but set the flag
984 <EM>garden</EM> in the session structure, and adds an iptables rule to
985 the <B>garden_users</B> chain to force all packets for the session's IP
986 address to traverse the <B>garden</B> chain.<P>
988 This doesn't <EM>just work</EM>. To set this all up, you will to
989 setup the <B>garden</B> nat table with the
990 <A HREF="#build-garden
">build-garden</A> script with rules to limit
991 user's traffic. For example, to force all traffic except DNS to be
992 forwarded to 192.168.1.1, add these entries to your
993 <EM>build-garden</EM>:
995 iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
996 iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
999 l2tpns will add entries to the garden_users chain as appropriate.<P>
1001 You can check the amount of traffic being captured using the following
1004 iptables -t nat -L garden -nvx
1007 <H2 ID="Filtering
">Filtering</H2>
1009 Sessions may be filtered by specifying <B>Filter-Id</B> attributes in
1010 the RADIUS reply. <I>filter</I>.<B>in</B> specifies that the named
1011 access-list <I>filter</I> should be applied to traffic from the
1012 customer, <I>filter</I>.<B>out</B> specifies a list for traffic to the
1015 <H2 ID="Clustering
">Clustering</H2>
1017 An l2tpns cluster consists of of one* or more servers configured with
1018 the same configuration, notably the multicast <B>cluster_address</B>.<P>
1020 *A stand-alone server is simply a degraded cluster.<P>
1022 Initially servers come up as cluster slaves, and periodically (every
1023 <B>cluster_hb_interval</B>/10 seconds) send out ping packets
1024 containing the start time of the process to the multicast
1025 <B>cluster_address</B>.<P>
1027 A cluster master sends heartbeat rather than ping packets, which
1028 contain those session and tunnel changes since the last heartbeat.<P>
1030 When a slave has not seen a heartbeat within
1031 <B>cluster_hb_timeout</B>/10 seconds it "elects
" a new master by
1032 examining the list of peers it has seen pings from and determines
1033 which of these and itself is the "best
" candidate to be master.
1034 "Best
" in this context means the server with the highest uptime (the
1035 highest IP address is used as a tie-breaker in the case of equal
1038 After discovering a master, and determining that it is up-to-date (has
1039 seen an update for all in-use sessions and tunnels from heartbeat
1040 packets) will raise a route (see <A HREF="#Routing
">Routing</A>) for
1041 the <B>bind_address</B> and for all addresses/networks in
1042 <B>ip_pool</B>. Any packets recieved by the slave which would alter
1043 the session state, as well as packets for throttled or gardened
1044 sessions are forwarded to the master for handling. In addition, byte
1045 counters for session traffic are periodically forwarded.<P>
1047 A master, when determining that it has at least one up-to-date slave
1048 will drop all routes (raising them again if all slaves disappear) and
1049 subsequently handle only packets forwarded to it by the slaves.<P>
1051 <H2 ID="Routing
">Routing</H2>
1052 If you are running a single instance, you may simply statically route
1053 the IP pools to the <B>bind_address</B> (l2tpns will send a gratuitous
1056 For a cluster, configure the members as BGP neighbours on your router
1057 and configure multi-path load-balancing. Cisco uses "maximum-paths
1058 ibgp
" for IBGP. If this is not supported by your IOS revision, you
1059 can use "maximum-paths
" (which works for EBGP) and set
1060 <B>as_number</B> to a private value such as 64512.<P>
1062 <H2 ID="AvoidingFragmentation
">Avoiding Fragmentation</H2>
1064 Fragmentation of encapsulated return packets to the LAC may be avoided
1065 for TCP sessions by adding a firewall rule to clamps the MSS on
1066 outgoing SYN packets.
1068 The following is appropriate for interfaces with a typical MTU of
1072 iptables -A FORWARD -i tun+ -o eth0 \
1073 -p tcp --tcp-flags SYN,RST SYN \
1074 -m tcpmss --mss 1413:1600 \
1075 -j TCPMSS --set-mss 1412
1078 <H2 ID="Performance
">Performance</H2>
1080 Performance is great.<P>
1082 I'd like to include some pretty graphs here that show a linear performance
1083 increase, with no impact by number of connected sessions.<P>
1085 That's really what it looks like.<P>
1089 <A HREF="mailto:l2tpns-users@lists.sourceforge.net?subject=L2TPNS%
20Documentation
">l2tpns-users@lists.sourceforge.net</A>