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>