kludge around problem with Netgear DM602 authentication
[l2tpns.git] / Docs / manual / manual.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://docbook.org/xml/4.4/docbookx.dtd">
4
5 <article>
6 <articleinfo>
7 <title>L2TPNS Manual</title>
8 </articleinfo>
9
10 <sect1 id="overview">
11 <title>Overview</title>
12 <para>
13 <command>l2tpns</command> is half of a complete L2TP
14 implementation. It supports only the LNS side of the
15 connection.
16 </para>
17
18 <para>
19 L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer
20 2 protocol (e.g. Ethernet, PPP) to be tunneled over an IP
21 connection. <command>l2tpns</command> implements PPP over L2TP
22 only.
23 </para>
24
25 <para>
26 There are a couple of other L2TP implementations, of which
27 <ulink url="http://sourceforge.net/projects/l2tpd">l2tpd</ulink>
28 is probably the most popular. l2tpd also will handle being
29 either end of a tunnel, and is a lot more configurable than
30 <command>l2tpns</command>. However, due to the way it works, it
31 is nowhere near as scalable.
32 </para>
33
34 <para>
35 <command>l2tpns</command> uses the TUN/TAP interface provided by
36 the Linux kernel to receive and send packets. Using some packet
37 manipulation it doesn't require a single interface per
38 connection, as l2tpd does.
39 </para>
40
41 <para>
42 This allows it to scale extremely well to very high loads and
43 very high numbers of connections.
44 </para>
45
46 <para>
47 It also has a plugin architecture which allows custom code to be
48 run during processing. An example of this is in the walled
49 garden module included.
50 </para>
51 </sect1>
52
53 <sect1 id="installation">
54 <title>Installation</title>
55 <sect2 id="installation-requirements">
56 <title>Requirements</title>
57 <itemizedlist>
58 <listitem>
59 <para>
60 Linux kernel version 2.4 or above, with the Tun/Tap
61 interface either compiled in, or as a module.
62 </para>
63 </listitem>
64
65 <listitem>
66 <para>
67 libcli 1.8.5 or greater. You can get this from
68 <ulink url="http://sourceforge.net/projects/libcli">
69 SourceForge</ulink>
70 </para>
71 </listitem>
72 </itemizedlist>
73 </sect2>
74
75 <sect2 id="installation-compile">
76 <title>Compiling</title>
77 <para>
78 You can generally get away with just running
79 <command>make</command> from the source directory. This will
80 compile the daemon, associated tools and any modules shipped
81 with the distribution.
82 </para>
83 </sect2>
84
85 <sect2 id="installation-install">
86 <title>Installing</title>
87 <para>
88 After you have successfully compiled everything, run
89 <userinput>make install</userinput> to install it. By
90 default, the binaries are installed into
91 <filename>/usr/sbin</filename>, the configuration into
92 <filename>/etc/l2tpns</filename>, and the modules into
93 <filename>/usr/lib/l2tpns</filename>.
94 </para>
95
96 <para>
97 You will definately need to edit the configuration files
98 before you start. See <xref linkend="configuration"/> for
99 more information.
100 </para>
101 </sect2>
102
103 <sect2 id="installation-run">
104 <title>Running</title>
105 <para>
106 You only need to run <filename>/usr/sbin/l2tpns</filename> as
107 root to start it. It does not normally detach to a daemon
108 process (see the <option>-d</option> option), so you should
109 perhaps run it from <command>init</command>.
110 </para>
111
112 <para>
113 By default there is no log destination set, so all log
114 messages will go to stdout.
115 </para>
116 </sect2>
117 </sect1>
118
119 <sect1 id="configuration">
120 <title>Configuration</title>
121 <para>
122 All configuration of the software is done from the files
123 installed into <filename>/etc/l2tpns</filename>.
124 </para>
125
126 <sect2 id="config-startup">
127 <title><filename>startup-config</filename></title>
128 <para>
129 This is the main configuration file for
130 <command>l2tpns</command>. The format of the file is a list
131 of commands that can be run through the command-line
132 interface. This file can also be written directly by the
133 <command>l2tpns</command> process if a user runs the
134 <userinput>write memory</userinput> command, so any comments
135 will be lost. However if your policy is not to write the
136 config by the program, then feel free to comment the file with
137 a <literal>#</literal> or <literal>!</literal> at the
138 beginning of the line.
139 </para>
140
141 <para>
142 A list of the possible configuration directives follows. Each
143 of these should be set by a line like:
144 <synopsis>
145 set configstring "value"
146 set ipaddress 192.168.1.1
147 set boolean true
148 </synopsis>
149 </para>
150
151 <variablelist>
152 <varlistentry>
153 <term><literal>debug</literal> (int)</term>
154 <listitem>
155 <para>
156 Sets the level of messages that will be written to the
157 log file. The value should be between 0 and 5, with 0
158 being no debugging, and 5 being the highest. A rough
159 description of the levels is:
160
161 <variablelist>
162 <varlistentry>
163 <term><constant>0</constant>: Critical Errors</term>
164 <listitem>
165 <para>Things are probably broken</para>
166 </listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term><constant>1</constant>: Errors</term>
171 <listitem>
172 <para>
173 Things might have gone wrong, but probably will
174 recover
175 </para>
176 </listitem>
177 </varlistentry>
178
179 <varlistentry>
180 <term><constant>2</constant>: Warnings</term>
181 <listitem>
182 <para>
183 Just in case you care what is not quite perfect
184 </para>
185 </listitem>
186 </varlistentry>
187
188 <varlistentry>
189 <term><constant>3</constant>: Information</term>
190 <listitem>
191 <para>Parameters of control packets</para>
192 </listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term><constant>4</constant>: Calls</term>
197 <listitem>
198 <para>For tracing the execution of the code</para>
199 </listitem>
200 </varlistentry>
201
202 <varlistentry>
203 <term><constant>5</constant>: Packets</term>
204 <listitem>
205 <para>
206 Everything, including a hex dump of all packets
207 processed... probably twice
208 </para>
209 </listitem>
210 </varlistentry>
211 </variablelist>
212 </para>
213
214 <para>
215 Note that the higher you set the debugging level, the
216 slower the program will run. Also, at level 5 a
217 <emphasis>lot</emphasis> of information will be logged.
218 This should only ever be used for working out why it
219 doesn't work at all.
220 </para>
221 </listitem>
222 </varlistentry>
223
224 <varlistentry>
225 <term><literal>log_file</literal> (string)</term>
226 <listitem>
227 <para>
228 This will be where all logging and debugging information
229 is written to. This may be either a filename, such as
230 <filename>/var/log/l2tpns</filename>, or the special
231 magic string
232 <literal>syslog:</literal><replaceable>facility</replaceable>,
233 where <replaceable>facility</replaceable> is any one of
234 the syslog logging facilities, such as
235 <literal>local5</literal>.
236 </para>
237 </listitem>
238 </varlistentry>
239
240 <varlistentry>
241 <term><literal>pid_file</literal> (string)</term>
242 <listitem>
243 <para>
244 If set, the process id will be written to the specified
245 file. The value must be an absolute path.
246 </para>
247 </listitem>
248 </varlistentry>
249
250 <varlistentry>
251 <term><literal>random_device</literal> (string)</term>
252 <listitem>
253 <para>
254 Path to random data source (default
255 <filename>/dev/urandom</filename>). Use "" to use the
256 rand() library function.
257 </para>
258 </listitem>
259 </varlistentry>
260
261 <varlistentry>
262 <term><literal>l2tp_secret</literal> (string)</term>
263 <listitem>
264 <para>
265 The secret used by <command>l2tpns</command> for
266 authenticating tunnel request. Must be the same as the
267 LAC, or authentication will fail. Only actually be used
268 if the LAC requests authentication.
269 </para>
270 </listitem>
271 </varlistentry>
272
273 <varlistentry>
274 <term><literal>l2tp_mtu</literal> (int)</term>
275 <listitem>
276 <para>
277 MTU of interface for L2TP traffic (default:
278 <literal>1500</literal>). Used to set link MRU and
279 adjust TCP MSS.
280 </para>
281 </listitem>
282 </varlistentry>
283
284 <varlistentry>
285 <term><literal>ppp_restart_time</literal> (int)</term>
286 <term><literal>ppp_max_configure</literal> (int)</term>
287 <term><literal>ppp_max_failure</literal> (int)</term>
288 <listitem>
289 <para>
290 PPP counter and timer values, as described in &sect;4.1
291 of <ulink url="ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt">
292 RFC1661</ulink>.
293 </para>
294 </listitem>
295 </varlistentry>
296
297 <varlistentry>
298 <term><literal>primary_dns</literal> (ip address)</term>
299 <term><literal>econdary_dns</literal> (ip address)</term>
300 <listitem>
301 <para>
302 Whenever a PPP connection is established, DNS servers
303 will be sent to the user, both a primary and a
304 secondary. If either is set to 0.0.0.0, then that one
305 will not be sent.
306 </para>
307 </listitem>
308 </varlistentry>
309
310 <varlistentry>
311 <term><literal>primary_radius</literal> (ip address)</term>
312 <term><literal>secondary_radius</literal> (ip address)</term>
313 <listitem>
314 <para>
315 Sets the RADIUS servers used for both authentication and
316 accounting. If the primary server does not respond,
317 then the secondary RADIUS server will be tried.
318
319 <note>
320 <para>
321 In addition to the source IP address and identifier,
322 the RADIUS server <emphasis>must</emphasis> include
323 the source port when detecting duplicates to supress
324 (in order to cope with a large number of sessions
325 comming on-line simultaneously
326 <command>l2tpns</command> uses a set of udp sockets,
327 each with a seperate identifier).
328 </para>
329 </note>
330 </para>
331 </listitem>
332 </varlistentry>
333
334 <varlistentry>
335 <term><literal>primary_radius_port</literal> (short)</term>
336 <term><literal>secondary_radius_port</literal> (short)</term>
337 <listitem>
338 <para>
339 Sets the authentication ports for the primary and
340 secondary RADIUS servers. The accounting port is one
341 more than the authentication port. If no RADIUS ports
342 are given, the authentication port defaults to 1645, and
343 the accounting port to 1646.
344 </para>
345 </listitem>
346 </varlistentry>
347
348 <varlistentry>
349 <term><literal>radius_accounting</literal> (boolean)</term>
350 <listitem>
351 <para>
352 If set to true, then RADIUS accounting packets will be
353 sent. This means that a Start record will be sent when
354 the session is successfully authenticated, and a Stop
355 record will be sent when the session is closed.
356 </para>
357 </listitem>
358 </varlistentry>
359
360 <varlistentry>
361 <term><literal>radius_interim</literal> (int)</term>
362 <listitem>
363 <para>
364 If <literal>radius_accounting</literal> is on, defines
365 the interval between sending of RADIUS interim
366 accounting records (in seconds).
367 </para>
368 </listitem>
369 </varlistentry>
370
371 <varlistentry>
372 <term><literal>radius_secret</literal> (string)</term>
373 <listitem>
374 <para>
375 This secret will be used in all RADIUS queries. If this
376 is not set then RADIUS queries will fail.
377 </para>
378 </listitem>
379 </varlistentry>
380
381 <varlistentry>
382 <term><literal>radius_authtypes</literal> (string)</term>
383 <listitem>
384 <para>
385 A comma separated list of supported RADIUS
386 authentication methods (<literal>pap</literal> or
387 <literal>chap</literal>), in order of preference
388 (default <literal>pap</literal>).
389 </para>
390 </listitem>
391 </varlistentry>
392
393 <varlistentry>
394 <term><literal>radius_dae_port</literal> (short)</term>
395 <listitem>
396 <para>
397 Port for DAE RADIUS (Packet of Death/Disconnect, Change
398 of Authorization) requests (default:
399 <literal>3799</literal>).
400 </para>
401 </listitem>
402 </varlistentry>
403
404 <varlistentry>
405 <term><literal>allow_duplicate_users</literal> (boolean)</term>
406 <listitem>
407 <para>
408 Allow multiple logins with the same username. If false
409 (the default), any prior session with the same username
410 will be dropped when a new session is established.
411 </para>
412 </listitem>
413 </varlistentry>
414
415 <varlistentry>
416 <term><literal>guest_account</literal> (string)</term>
417 <listitem>
418 <para>
419 Allow multiple logins matching this specific username.
420 </para>
421 </listitem>
422 </varlistentry>
423
424 <varlistentry>
425 <term><literal>bind_address</literal> (ip address)</term>
426 <listitem>
427 <para>
428 When the tun interface is created, it is assigned the
429 address specified here. If no address is given, 1.1.1.1
430 is used. Packets containing user traffic should be
431 routed via this address if given, otherwise the primary
432 address of the machine.
433 </para>
434 </listitem>
435 </varlistentry>
436
437 <varlistentry>
438 <term><literal>peer_address</literal> (ip address)</term>
439 <listitem>
440 <para>Address to send to clients as the default gateway.</para>
441 </listitem>
442 </varlistentry>
443
444 <varlistentry>
445 <term><literal>send_garp</literal> (boolean)</term>
446 <listitem>
447 <para>
448 Determines whether or not to send a gratuitous ARP for
449 the bind_address when the server is ready to handle
450 traffic (default: <literal>true</literal>). This value
451 is ignored if BGP is configured.
452 </para>
453 </listitem>
454 </varlistentry>
455
456 <varlistentry>
457 <term><literal>throttle_speed</literal> (int)</term>
458 <listitem>
459 <para>
460 Sets the default speed (in kbits/s) which sessions will
461 be limited to. If this is set to 0, then throttling
462 will not be used at all. Note: You can set this by the
463 CLI, but changes will not affect currently connected
464 users.
465 </para>
466 </listitem>
467 </varlistentry>
468
469 <varlistentry>
470 <term><literal>throttle_buckets</literal> (int)</term>
471 <listitem>
472 <para>
473 Number of token buckets to allocate for throttling.
474 Each throttled session requires two buckets (in and
475 out).
476 </para>
477 </listitem>
478 </varlistentry>
479
480 <varlistentry>
481 <term><literal>accounting_dir</literal> (string)</term>
482 <listitem>
483 <para>
484 If set to a directory, then every 5 minutes the current
485 usage for every connected use will be dumped to a file
486 in this directory. Each file dumped begins with a
487 header, where each line is prefixed by <code>#</code>.
488 Following the header is a single line for every
489 connected user, fields separated by a space.
490 </para>
491
492 <para>
493 The fields are username, ip, qos, uptxoctets,
494 downrxoctets. The qos field is 1 if a standard user,
495 and 2 if the user is throttled.
496 </para>
497 </listitem>
498 </varlistentry>
499
500 <varlistentry>
501 <term><literal>dump_speed</literal> (boolean)</term>
502 <listitem>
503 <para>
504 If set to true, then the current bandwidth utilization
505 will be logged every second. Even if this is disabled,
506 you can see this information by running the
507 <userinput>uptime</userinput> command on the CLI.
508 </para>
509 </listitem>
510 </varlistentry>
511
512 <varlistentry>
513 <term><literal>multi_read_count</literal> (int)</term>
514 <listitem>
515 <para>
516 Number of packets to read off each of the UDP and TUN
517 fds when returned as readable by select (default: 10).
518 Avoids incurring the unnecessary system call overhead of
519 select on busy servers.
520 </para>
521 </listitem>
522 </varlistentry>
523
524 <varlistentry>
525 <term><literal>scheduler_fifo</literal> (boolean)</term>
526 <listitem>
527 <para>
528 Sets the scheduling policy for the
529 <command>l2tpns</command> process to
530 <constant>SCHED_FIFO</constant>. This causes the kernel
531 to immediately preempt any currently running
532 <constant>SCHED_OTHER</constant> (normal) process in
533 favour of <command>l2tpns</command> when it becomes
534 runnable. Ignored on uniprocessor systems.
535 </para>
536 </listitem>
537 </varlistentry>
538
539 <varlistentry>
540 <term><literal>lock_pages</literal> (boolean)</term>
541 <listitem>
542 <para>
543 Keep all pages mapped by the <command>l2tpns</command>
544 process in memory.
545 </para>
546 </listitem>
547 </varlistentry>
548
549 <varlistentry>
550 <term><literal>icmp_rate</literal> (int)</term>
551 <listitem>
552 <para>
553 Maximum number of host unreachable ICMP packets to send
554 per second.
555 </para>
556 </listitem>
557 </varlistentry>
558
559 <varlistentry>
560 <term><literal>packet_limit</literal> (int)</term>
561 <listitem>
562 <para>
563 Maximum number of packets of downstream traffic to be
564 handled each tenth of a second per session. If zero, no
565 limit is applied (default: 0). Intended as a DoS
566 prevention mechanism and not a general throttling
567 control (packets are dropped, not queued).
568 </para>
569 </listitem>
570 </varlistentry>
571
572 <varlistentry>
573 <term><literal>cluster_address</literal> (ip address)</term>
574 <listitem>
575 <para>
576 Multicast cluster address (default: 239.192.13.13).
577 See <xref linkend="clustering"/> for more information.
578 </para>
579 </listitem>
580 </varlistentry>
581
582 <varlistentry>
583 <term><literal>cluster_interface</literal> (string)</term>
584 <listitem>
585 <para>Interface for cluster packets (default: eth0)</para>
586 </listitem>
587 </varlistentry>
588
589 <varlistentry>
590 <term><literal>cluster_mcast_ttl</literal> (int)</term>
591 <listitem>
592 <para>TTL for multicast packets (default: 1).</para>
593 </listitem>
594 </varlistentry>
595
596 <varlistentry>
597 <term><literal>cluster_hb_interval</literal> (int)</term>
598 <listitem>
599 <para>
600 Interval in tenths of a second between cluster
601 heartbeat/pings.
602 </para>
603 </listitem>
604 </varlistentry>
605
606 <varlistentry>
607 <term><literal>cluster_hb_timeout</literal> (int)</term>
608 <listitem>
609 <para>
610 Cluster heartbeat timeout in tenths of a second. A new
611 master will be elected when this interval has been
612 passed without seeing a heartbeat from the master.
613 </para>
614 </listitem>
615 </varlistentry>
616
617 <varlistentry>
618 <term><literal>cluster_master_min_adv</literal> (int)</term>
619 <listitem>
620 <para>
621 Determines the minumum number of up to date slaves
622 required before the master will drop routes (default: 1).
623 </para>
624 </listitem>
625 </varlistentry>
626
627 <varlistentry>
628 <term><literal>ipv6_prefix</literal> (ipv6 address)</term>
629 <listitem>
630 <para>
631 Enable negotiation of IPv6. This forms the the first 64
632 bits of the client allocated address. The remaining 64
633 come from the allocated IPv4 address and 4 bytes of 0s.
634 </para>
635 </listitem>
636 </varlistentry>
637 </variablelist>
638
639 <sect3 id="config-startup-bgp">
640 <title>BGP</title>
641 <para>
642 BGP routing configuration is entered by the command:
643 <synopsis>router bgp <replaceable>as</replaceable></synopsis>
644 where <replaceable>as</replaceable> specifies the local AS
645 number.
646 </para>
647
648 <para>
649 Subsequent lines prefixed with
650 <synopsis>neighbour <replaceable>peer</replaceable></synopsis>
651 define the attributes of BGP neighhbours. Valid commands
652 are:
653 <synopsis>
654 neighbour <replaceable>peer</replaceable> remote-as <replaceable>as</replaceable>
655 neighbour <replaceable>peer</replaceable> timers <replaceable>keepalive hold</replaceable>
656 </synopsis>
657 </para>
658
659 <para>
660 Where <replaceable>peer</replaceable> specifies the BGP
661 neighbour as either a hostname or IP address,
662 <replaceable>as</replaceable> is the remote AS number and
663 <replaceable>keepalive</replaceable>,
664 <replaceable>hold</replaceable> are the timer values in
665 seconds.
666 </para>
667 </sect3>
668
669 <sect3 id="config-startup-acl">
670 <title>Access Lists</title>
671 <para>
672 Named access-lists are configured using one of the commands:
673 <synopsis>
674 ip access-list standard <replaceable>name</replaceable>
675 ip access-list extended <replaceable>name</replaceable>
676 </synopsis>
677 </para>
678
679 <para>
680 Subsequent lines prefixed with <literal>permit</literal> or
681 <literal>deny</literal> define the body of the access-list.
682 Standard access-list syntax:
683 </para>
684
685 <para role="hanging-indent">
686 {<literal>permit</literal>|<literal>deny</literal>}
687 {<replaceable>host</replaceable>|<replaceable>source
688 source-wildcard</replaceable>|<literal>any</literal>}
689 [{<replaceable>host</replaceable>|<replaceable>destination
690 destination-wildcard</replaceable>|<literal>any</literal>}]
691 </para>
692
693 <para>Extended access-lists:</para>
694 <para role="hanging-indent">
695 {<literal>permit</literal>|<literal>deny</literal>}
696 <literal>ip</literal>
697 {<replaceable>host</replaceable>|<replaceable>source
698 source-wildcard</replaceable>|<literal>any</literal>}
699 {<replaceable>host</replaceable>|<replaceable>destination
700 destination-wildcard</replaceable>|<literal>any</literal>}
701 [<literal>fragments</literal>]
702 </para>
703
704 <para role="hanging-indent">
705 {<literal>permit</literal>|<literal>deny</literal>}
706 <literal>udp</literal>
707 {<replaceable>host</replaceable>|<replaceable>source
708 source-wildcard</replaceable>|<literal>any</literal>}
709 [{<literal>eq</literal>|<literal>neq</literal>|<literal>gt</literal>|<literal>lt</literal>}
710 <replaceable>port</replaceable>|<literal>range</literal>
711 <replaceable>from</replaceable>
712 <replaceable>to</replaceable>]
713 {<replaceable>host</replaceable>|<replaceable>destination
714 destination-wildcard</replaceable>|<literal>any</literal>}
715 [{<literal>eq</literal>|<literal>neq</literal>|<literal>gt</literal>|<literal>lt</literal>}
716 <replaceable>port</replaceable>|<literal>range</literal>
717 <replaceable>from</replaceable>
718 <replaceable>to</replaceable>]
719 [<literal>fragments</literal>]
720 </para>
721
722 <para role="hanging-indent">
723 {<literal>permit</literal>|<literal>deny</literal>}
724 <literal>tcp</literal>
725 {<replaceable>host</replaceable>|<replaceable>source
726 source-wildcard</replaceable>|<literal>any</literal>}
727 [{<literal>eq</literal>|<literal>neq</literal>|<literal>gt</literal>|<literal>lt</literal>}
728 <replaceable>port</replaceable>|<literal>range</literal>
729 <replaceable>from</replaceable>
730 <replaceable>to</replaceable>]
731 {<replaceable>host</replaceable>|<replaceable>destination
732 destination-wildcard</replaceable>|<literal>any</literal>}
733 [{<literal>eq</literal>|<literal>neq</literal>|<literal>gt</literal>|<literal>lt</literal>}
734 <replaceable>port</replaceable>|<literal>range</literal>
735 <replaceable>from</replaceable>
736 <replaceable>to</replaceable>]
737 [{<literal>established</literal>|{<literal>match-any</literal>|<literal>match-all</literal>}
738 {<literal>+</literal>|<literal>-</literal>}{<literal>fin</literal>|<literal>syn</literal>|<literal>rst</literal>|<literal>psh</literal>|<literal>ack</literal>|<literal>urg</literal>}
739 ...|<literal>fragments</literal>]
740 </para>
741 </sect3>
742 </sect2>
743
744 <sect2 id="config-users">
745 <title><filename>users</filename></title>
746 <para>
747 Usernames and passwords for the command-line interface are
748 stored in this file. The format is
749 <synopsis>
750 <replaceable>username</replaceable>:<replaceable>password</replaceable>
751 </synopsis>
752 where <replaceable>password</replaceable> may either by plain
753 text, an MD5 digest (prefixed by
754 <literal>$1</literal><replaceable>salt</replaceable><literal>$</literal>)
755 or a DES password, distinguished from plain text by the prefix
756 <literal>{crypt}</literal>.
757 </para>
758
759 <para>
760 The username <literal>enable</literal> has a special meaning
761 and is used to set the enable password.
762 </para>
763
764 <important>
765 <para>
766 If this file doesn't exist, then anyone who can get to port
767 23 will be allowed access without a username or password.
768 </para>
769 </important>
770 </sect2>
771
772 <sect2 id="config-ip-pool">
773 <title><filename>ip_pool</filename></title>
774 <para>
775 This file is used to configure the IP address pool which user
776 addresses are assigned from. This file should contain either
777 an IP address or a CIDR network per line. e.g.:
778
779 <programlisting>
780 192.168.1.1
781 192.168.1.2
782 192.168.1.3
783 192.168.4.0/24
784 172.16.0.0/16
785 10.0.0.0/8
786 </programlisting>
787 </para>
788
789 <para>
790 Keep in mind that <command>l2tpns</command> can only handle
791 65535 connections per process, so don't put more than 65535 IP
792 addresses in the configuration file. They will be
793 wasted.
794 </para>
795 </sect2>
796
797 <sect2 id="config-build-garden" xreflabel="build-garden">
798 <title><filename>build-garden</filename></title>
799 <para>
800 The garden plugin on startup creates a NAT table called
801 "garden" then sources the <filename>build-garden</filename>
802 script to populate that table. All packets from gardened
803 users will be sent through this table. Example:
804
805 <programlisting>
806 iptables -t nat -A garden -p tcp -m tcp --dport 25 -j DNAT --to 192.168.1.1
807 iptables -t nat -A garden -p udp -m udp --dport 53 -j DNAT --to 192.168.1.1
808 iptables -t nat -A garden -p tcp -m tcp --dport 53 -j DNAT --to 192.168.1.1
809 iptables -t nat -A garden -p tcp -m tcp --dport 80 -j DNAT --to 192.168.1.1
810 iptables -t nat -A garden -p tcp -m tcp --dport 110 -j DNAT --to 192.168.1.1
811 iptables -t nat -A garden -p tcp -m tcp --dport 443 -j DNAT --to 192.168.1.1
812 iptables -t nat -A garden -p icmp -m icmp --icmp-type echo-request -j DNAT --to 192.168.1.1
813 iptables -t nat -A garden -p icmp -j ACCEPT
814 iptables -t nat -A garden -j DROP
815 </programlisting>
816 </para>
817 </sect2>
818 </sect1>
819
820 <sect1 id="operation">
821 <title>Operation</title>
822 <para>
823 A running l2tpns process can be controlled in a number of ways.
824 The primary method of control is by the Command-Line Interface
825 (CLI).
826 </para>
827
828 <para>
829 You can also remotely send commands to modules via the
830 <command>nsctl</command> client provided.
831 </para>
832
833 <para>
834 There are also a number of signals that l2tpns understands and
835 takes action when it receives them.
836 </para>
837
838 <sect2 id="operation-cli">
839 <title>Command-Line Interface</title>
840 <para>
841 You can access the command line interface by telneting to port
842 23. There is no IP address restriction, so it's a good idea
843 to firewall this port off from anyone who doesn't need access
844 to it. See <xref linkend="config-users"/> for information on
845 restricting access based on a username and password.
846 </para>
847
848 <para>
849 The CLI gives you real-time control over almost everything in
850 the process. The interface is designed to look like a Cisco
851 device, and supports things like command history, line editing
852 and context sensitive help. This is provided by linking with
853 the <ulink url="http://sourceforge.net/projects/libcli">
854 libcli</ulink> library. Some general documentation of the
855 interface is <ulink
856 url="http://sourceforge.net/docman/display_doc.php?docid=20501&amp;group_id=79019">
857 here</ulink>.
858 </para>
859
860 <para>
861 After you have connected to the telnet port (and perhaps
862 logged in), you will be presented with a
863 <prompt><replaceable>hostname</replaceable>&gt;</prompt>
864 prompt.
865 </para>
866
867 <para>
868 Enter <userinput>help</userinput> to get a list of possible
869 commands, or press <userinput>?</userinput> for
870 context-specific help.
871 </para>
872
873 <para>
874 A brief overview of the more important commands
875 follows:
876
877 <variablelist>
878 <varlistentry id="operation-cli-show-session"
879 xreflabel="show session">
880 <term>
881 <userinput>show session [<replaceable>ID</replaceable>]
882 </userinput>
883 </term>
884
885 <listitem>
886 <para>
887 Detailed information for a specific session is
888 presented if you specify a session
889 <replaceable>ID</replaceable> argument.
890 </para>
891
892 <para>
893 If no <replaceable>ID</replaceable> is given, a
894 summary of all connected sessions is produced. Note
895 that this summary list can be around 185 columns wide,
896 so you should probably use a wide
897 terminal.
898 </para>
899
900 <para>
901 The columns listed in the summary are:
902
903 <informaltable>
904 <tgroup cols="3">
905 <colspec colname="col"/>
906 <colspec colname="desc"/>
907 <colspec colname="extra"/>
908 <tbody>
909 <row>
910 <entry><literal>SID</literal></entry>
911 <entry namest="desc" nameend="extra">Session ID</entry>
912 </row>
913 <row>
914 <entry><literal>TID</literal></entry>
915 <entry>Tunnel ID</entry>
916 <entry>
917 See also the <xref
918 linkend="operation-cli-show-tunnel"/> CLI
919 command.
920 </entry>
921 </row>
922 <row>
923 <entry><literal>Username</literal></entry>
924 <entry>
925 The username given in the PPP authentication.
926 </entry>
927 <entry>
928 If this is *, then LCP authentication has
929 not completed.
930 </entry>
931 </row>
932 <row>
933 <entry><literal>IP</literal></entry>
934 <entry>The IP address given to the session.</entry>
935 <entry>
936 If this is 0.0.0.0, IPCP negotiation has not
937 completed
938 </entry>
939 </row>
940 <row>
941 <entry><literal>I</literal></entry>
942 <entry>Intercept</entry>
943 <entry>
944 Y or N: indicates whether the session is
945 being snooped. See also the
946 <xref linkend="operation-cli-snoop"/>
947 CLI command.
948 </entry>
949 </row>
950 <row>
951 <entry><literal>T</literal></entry>
952 <entry>Throttled</entry>
953 <entry>
954 Y or N: indicates whether the session is
955 currently throttled. See also the
956 <xref linkend="operation-cli-throttle"/>
957 CLI command.
958 </entry>
959 </row>
960 <row>
961 <entry><literal>G</literal></entry>
962 <entry>Walled Garden</entry>
963 <entry>
964 Y or N: indicates whether the user is
965 trapped in the walled garden. This field is
966 present even if the garden module is not
967 loaded.
968 </entry>
969 </row>
970 <row>
971 <entry><literal>6</literal></entry>
972 <entry>IPv6</entry>
973 <entry>
974 Y or N: indicates whether the session has
975 IPv6 active (IPV6CP open)
976 </entry>
977 </row>
978 <row>
979 <entry><literal>opened</literal></entry>
980 <entry namest="desc" nameend="extra">
981 The number of seconds since the
982 session started
983 </entry>
984 </row>
985 <row>
986 <entry><literal>downloaded</literal></entry>
987 <entry namest="desc" nameend="extra">
988 Number of bytes downloaded by the user
989 </entry>
990 </row>
991 <row>
992 <entry><literal>uploaded</literal></entry>
993 <entry namest="desc" nameend="extra">
994 Number of bytes uploaded by the user
995 </entry>
996 </row>
997 <row>
998 <entry><literal>idle</literal></entry>
999 <entry namest="desc" nameend="extra">
1000 The number of seconds since traffic was
1001 detected on the session
1002 </entry>
1003 </row>
1004 <row>
1005 <entry><literal>LAC</literal></entry>
1006 <entry namest="desc" nameend="extra">
1007 The IP address of the LAC the session is
1008 connected to.
1009 </entry>
1010 </row>
1011 <row>
1012 <entry><literal>CLI</literal></entry>
1013 <entry namest="desc" nameend="extra">
1014 The Calling-Line-Identification field
1015 provided during the session setup. This
1016 field is generated by the LAC.
1017 </entry>
1018 </row>
1019 </tbody>
1020 </tgroup>
1021 </informaltable>
1022 </para>
1023 </listitem>
1024 </varlistentry>
1025
1026 <varlistentry id="operation-cli-show-user" xreflabel="show user">
1027 <term>
1028 <userinput>show users</userinput>
1029 </term>
1030 <term>
1031 <userinput>show user <replaceable>username</replaceable>
1032 </userinput>
1033 </term>
1034
1035 <listitem>
1036 <para>
1037 With no arguments, display a list of currently
1038 connected users. If an argument is given, the session
1039 details for the given
1040 <replaceable>username</replaceable> are displayed.
1041 </para>
1042 </listitem>
1043 </varlistentry>
1044
1045 <varlistentry id="operation-cli-show-tunnel" xreflabel="show tunnel">
1046 <term>
1047 <userinput>show tunnel [<replaceable>ID</replaceable>]</userinput>
1048 </term>
1049
1050 <listitem>
1051 <para>
1052 Produce a summary list of all open tunnels, or detail
1053 on a specific tunnel <replaceable>ID</replaceable>.
1054 </para>
1055
1056 <para>
1057 The columns listed in the summary are:
1058
1059 <informaltable>
1060 <tgroup cols="2">
1061 <tbody>
1062 <row>
1063 <entry>TID</entry>
1064 <entry>Tunnel ID</entry>
1065 </row>
1066 <row>
1067 <entry>Hostname</entry>
1068 <entry>
1069 The hostname for the tunnel as provided by
1070 the LAC. This has no relation to DNS, it is
1071 just a text field.
1072 </entry>
1073 </row>
1074 <row>
1075 <entry>IP</entry>
1076 <entry>The IP address of the LAC</entry>
1077 </row>
1078 <row>
1079 <entry>State</entry>
1080 <entry>
1081 Tunnel state: Free, Open, Dieing, Opening
1082 </entry>
1083 </row>
1084 <row>
1085 <entry>Sessions</entry>
1086 <entry>The number of open sessions on the tunnel</entry>
1087 </row>
1088 </tbody>
1089 </tgroup>
1090 </informaltable>
1091 </para>
1092 </listitem>
1093 </varlistentry>
1094
1095 <varlistentry id="operation-cli-show-pool" xreflabel="show pool">
1096 <term><userinput>show pool</userinput></term>
1097 <listitem>
1098 <para>
1099 Displays the current IP address pool allocation. This
1100 will only display addresses that are in use, or are
1101 reserved for re-allocation to a disconnected user.
1102 </para>
1103
1104 <para>
1105 If an address is not currently in use, but has been
1106 used, then in the User column the username will be
1107 shown in square brackets, followed by the time since
1108 the address was used:
1109
1110 <screen>
1111 IP Address Used Session User
1112 192.168.100.6 N [joe.user] 1548s
1113 </screen>
1114 </para>
1115 </listitem>
1116 </varlistentry>
1117
1118 <varlistentry id="operation-cli-show-radius" xreflabel="show radius">
1119 <term><userinput>show radius</userinput></term>
1120 <listitem>
1121 <para>
1122 Show a summary of the in-use RADIUS sessions. This
1123 list should not be very long, as RADIUS sessions
1124 should be cleaned up as soon as they are used. The
1125 columns listed are:
1126
1127 <informaltable>
1128 <tgroup cols="2">
1129 <tbody>
1130 <row>
1131 <entry>Radius</entry>
1132 <entry>
1133 The ID of the RADIUS request. This is sent
1134 in the packet to the RADIUS server for
1135 identification
1136 </entry>
1137 </row>
1138 <row>
1139 <entry>State</entry>
1140 <entry>
1141 The state of the request: WAIT, CHAP, AUTH,
1142 IPCP, START, STOP or NULL
1143 </entry>
1144 </row>
1145 <row>
1146 <entry>Session</entry>
1147 <entry>
1148 The session ID that this RADIUS request is
1149 associated with
1150 </entry>
1151 </row>
1152 <row>
1153 <entry>Retry</entry>
1154 <entry>
1155 If a response does not appear to the
1156 request, it will retry at this time. This
1157 is a Unix timestamp
1158 </entry>
1159 </row>
1160 <row>
1161 <entry>Try</entry>
1162 <entry>
1163 Retry count. The RADIUS request is
1164 discarded after 3 retries
1165 </entry>
1166 </row>
1167 </tbody>
1168 </tgroup>
1169 </informaltable>
1170 </para>
1171 </listitem>
1172 </varlistentry>
1173
1174 <varlistentry id="operation-cli-show-run" xreflabel="show run">
1175 <term><userinput>show running-config</userinput></term>
1176 <listitem>
1177 <para>
1178 This will list the current running configuration.
1179 This is in a format that can either be pasted into the
1180 configuration file, or run directly at the command
1181 line.
1182 </para>
1183 </listitem>
1184 </varlistentry>
1185
1186 <varlistentry id="operation-cli-show-counters"
1187 xreflabel="show counters">
1188 <term><userinput>show counters</userinput></term>
1189 <listitem>
1190 <para>
1191 Internally, counters are kept of key values, such as
1192 bytes and packets transferred, as well as function
1193 call counters. This function displays all these
1194 counters, and is probably only useful for debugging.
1195 </para>
1196
1197 <para>
1198 You can reset these counters by running
1199 <userinput>clear counters</userinput>.
1200 </para>
1201 </listitem>
1202 </varlistentry>
1203
1204 <varlistentry id="operation-cli-show-cluster"
1205 xreflabel="show cluster">
1206 <term><userinput>show cluster</userinput></term>
1207 <listitem>
1208 <para>
1209 Show cluster status. Shows the cluster state for this
1210 server (Master/Slave), information about known peers
1211 and (for slaves) the master IP address, last packet
1212 seen and up-to-date status. See
1213 <xref linkend="clustering"/> for more information.
1214 </para>
1215 </listitem>
1216 </varlistentry>
1217
1218 <varlistentry id="operation-cli-write-mem" xreflabel="write memory">
1219 <term><userinput>write memory</userinput></term>
1220 <listitem>
1221 <para>
1222 This will write the current running configuration to
1223 the config file <filename>startup-config</filename>,
1224 which will be run on a restart.
1225 </para>
1226 </listitem>
1227 </varlistentry>
1228
1229 <varlistentry id="operation-cli-snoop" xreflabel="snoop">
1230 <term>
1231 <userinput>snoop <replaceable>user</replaceable>
1232 <replaceable>IP</replaceable>
1233 <replaceable>port</replaceable></userinput>
1234 </term>
1235 <listitem>
1236 <para>
1237 You must specify a username, IP address and port. All
1238 packets for the current session for that username will
1239 be forwarded to the given host/port. Specify
1240 <userinput>no snoop
1241 <replaceable>username</replaceable></userinput> to
1242 disable interception for the session.
1243 </para>
1244
1245 <para>
1246 If you want interception to be permanent, you will
1247 have to modify the RADIUS response for the user. See
1248 <xref linkend="interception"/>.
1249 </para>
1250 </listitem>
1251 </varlistentry>
1252
1253 <varlistentry id="operation-cli-throttle" xreflabel="throttle">
1254 <term>
1255 <userinput>throttle <replaceable>user</replaceable>
1256 [in|out] <replaceable>rate</replaceable></userinput>
1257 </term>
1258 <listitem>
1259 <para>
1260 You must specify a username, which will be throttled
1261 for the current session to
1262 <replaceable>rate</replaceable> Kbps. Prefix
1263 <replaceable>rate</replaceable> with
1264 <userinput>in</userinput> or
1265 <userinput>out</userinput> to set different upstream
1266 and downstream rates.
1267 </para>
1268
1269 <para>
1270 Specify <userinput>no throttle
1271 <replaceable>username</replaceable></userinput> to
1272 disable throttling for the current session.
1273 </para>
1274
1275 <para>
1276 If you want throttling to be permanent, you will have
1277 to modify the RADIUS response for the user. See <xref
1278 linkend="throttling"/>.
1279 </para>
1280 </listitem>
1281 </varlistentry>
1282
1283 <varlistentry id="operation-cli-drop-session"
1284 xreflabel="drop session">
1285 <term>
1286 <userinput>drop <replaceable>session</replaceable></userinput>
1287 </term>
1288 <listitem>
1289 <para>
1290 This will cleanly disconnect the session specified by
1291 <replaceable>session</replaceable> ID.
1292 </para>
1293 </listitem>
1294 </varlistentry>
1295
1296 <varlistentry id="operation-cli-drop-tunnel" xreflabel="drop tunnel">
1297 <term>
1298 <userinput>drop <replaceable>tunnel</replaceable></userinput>
1299 </term>
1300 <listitem>
1301 <para>
1302 This will cleanly disconnect the tunnel specified by
1303 <replaceable>tunnel</replaceable> ID, as well as all
1304 sessions on that tunnel.
1305 </para>
1306 </listitem>
1307 </varlistentry>
1308
1309 <varlistentry id="operation-cli-uptime" xreflabel="uptime">
1310 <term><userinput>uptime</userinput></term>
1311 <listitem>
1312 <para>
1313 This will show how long the <command>l2tpns</command>
1314 process has been running, and the current bandwidth
1315 utilization:
1316
1317 <screen>
1318 17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16
1319 Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569
1320 </screen>
1321
1322 The bandwidth line contains 4 sets of values:
1323
1324 <informaltable>
1325 <tgroup cols="2">
1326 <tbody>
1327 <row>
1328 <entry>UDP-ETH</entry>
1329 <entry>
1330 The current bandwidth going from the LAC to
1331 the ethernet (user uploads), in mbits/sec.
1332 </entry>
1333 </row>
1334 <row>
1335 <entry>ETH-UDP</entry>
1336 <entry>
1337 The current bandwidth going from ethernet to
1338 the LAC (user downloads).
1339 </entry>
1340 </row>
1341 <row>
1342 <entry>TOTAL</entry>
1343 <entry>The total aggregate bandwidth in mbits/s.</entry>
1344 </row>
1345 <row>
1346 <entry>IN and OUT</entry>
1347 <entry>
1348 Packets/per-second going between UDP-ETH and
1349 ETH-UDP.
1350 </entry>
1351 </row>
1352 </tbody>
1353 </tgroup>
1354 </informaltable>
1355
1356 These counters are updated every second.
1357 </para>
1358 </listitem>
1359 </varlistentry>
1360
1361 <varlistentry id="operation-cli-configure" xreflabel="configure">
1362 <term><userinput>configure terminal</userinput></term>
1363 <listitem>
1364 <para>
1365 Enter configuration mode. Use
1366 <userinput>exit</userinput> or
1367 <userinput>^Z</userinput> to exit this mode.
1368 </para>
1369
1370 <para>
1371 The following commands are valid in this mode:
1372
1373 <variablelist>
1374 <varlistentry id="operation-cli-conf-load">
1375 <term>
1376 <userinput>load plugin
1377 <replaceable>name</replaceable></userinput>
1378 </term>
1379 <listitem>
1380 <para>
1381 Load a plugin. You must specify the plugin
1382 name, and it will search in
1383 <filename>/usr/lib/l2tpns</filename> for
1384 <filename><replaceable>name</replaceable>.so</filename>.
1385 You can unload a loaded plugin with
1386 <userinput>remove plugin
1387 <replaceable>name</replaceable></userinput>.
1388 </para>
1389 </listitem>
1390 </varlistentry>
1391
1392 <varlistentry id="operation-cli-conf-set">
1393 <term><userinput>set</userinput> ...</term>
1394 <listitem>
1395 <para>
1396 Set a configuration variable. You must specify
1397 the variable name, and the value. If the value
1398 contains any spaces, you should quote the value
1399 with double (") or single (') quotes.
1400 </para>
1401
1402 <para>
1403 You can set any configuration value in this
1404 way, although some may require a restart to
1405 take effect. See <xref
1406 linkend="config-startup"/>.
1407 </para>
1408 </listitem>
1409 </varlistentry>
1410
1411 <varlistentry id="operation-cli-conf-router">
1412 <term><userinput>router bgp</userinput> ...</term>
1413 <listitem>
1414 <para>
1415 Configure BGP. See <xref
1416 linkend="config-startup-bgp"/>.
1417 </para>
1418 </listitem>
1419 </varlistentry>
1420
1421 <varlistentry id="operation-cli-conf-acl">
1422 <term><userinput>ip access-list</userinput> ...</term>
1423 <listitem>
1424 <para>
1425 Configure a named access list. See <xref
1426 linkend="config-startup-acl"/>.
1427 </para>
1428 </listitem>
1429 </varlistentry>
1430 </variablelist>
1431 </para>
1432 </listitem>
1433 </varlistentry>
1434 </variablelist>
1435 </para>
1436 </sect2>
1437
1438 <sect2 id="operation-nsctl">
1439 <title>nsctl</title>
1440 <para>
1441 <command>nsctl</command> sends messages to a running
1442 <command>l2tpns</command> instance to be control plugins.
1443 </para>
1444
1445 <para>
1446 Arguments are <userinput>command</userinput> and optional
1447 <replaceable>args</replaceable>. See
1448 <literal>nsctl(8)</literal>.
1449 </para>
1450
1451 <para>
1452 Built-in command are <userinput>load_plugin</userinput>,
1453 <userinput>unload_plugin</userinput> and
1454 <userinput>help</userinput>. Any other commands are passed to
1455 plugins for processing by the
1456 <literal>plugin_control</literal> function.
1457 </para>
1458 </sect2>
1459
1460 <sect2 id="operation-signals">
1461 <title>Signals</title>
1462 <para>
1463 While the process is running, you can send it a few different
1464 signals, using the <command>kill</command> command.
1465
1466 <screen>
1467 killall -HUP l2tpns
1468 </screen>
1469
1470 The signals understood are:
1471
1472 <variablelist>
1473 <varlistentry>
1474 <term>SIGHUP</term>
1475 <listitem>
1476 <para>Reload the config from disk and re-open log file.</para>
1477 </listitem>
1478 </varlistentry>
1479
1480 <varlistentry>
1481 <term>SIGTERM</term>
1482 <term>SIGINT</term>
1483 <listitem>
1484 <para>
1485 Stop process. Tunnels and sessions are not
1486 terminated. This signal should be used to stop
1487 <command>l2tpns</command> on a cluster node where
1488 there are other machines to continue handling traffic.
1489 See <xref linkend="clustering"/>
1490 </para>
1491 </listitem>
1492 </varlistentry>
1493
1494 <varlistentry>
1495 <term>SIGQUIT</term>
1496 <listitem>
1497 <para>
1498 Shut down tunnels and sessions, exit process when
1499 complete.
1500 </para>
1501 </listitem>
1502 </varlistentry>
1503 </variablelist>
1504 </para>
1505 </sect2>
1506 </sect1>
1507
1508 <sect1 id="throttling">
1509 <title>Throttling</title>
1510 <para>
1511 <command>l2tpns</command> contains support for slowing down user
1512 sessions to whatever speed you desire. The global setting
1513 <literal>throttle_speed</literal> defines the default throttle
1514 rate.
1515 </para>
1516
1517 <para>
1518 To throttle a sesion permanently, add a
1519 <literal>Cisco-AVPair</literal> RADIUS attribute. The
1520 <filename>autothrotle</filename> module interprets the following
1521 attributes:
1522
1523 <informaltable>
1524 <tgroup cols="2">
1525 <tbody>
1526 <row>
1527 <entry><literal>throttle=yes</literal></entry>
1528 <entry>
1529 Throttle upstream/downstream traffic to the configured
1530 <literal>throttle_speed</literal>.
1531 </entry>
1532 </row>
1533
1534 <row>
1535 <entry>
1536 <literal>throttle=<replaceable>rate</replaceable></literal>
1537 </entry>
1538 <entry>
1539 Throttle upstream/downstream traffic to the specified
1540 <replaceable>rate</replaceable> Kbps.
1541 </entry>
1542 </row>
1543
1544 <row>
1545 <entry>
1546 <literal>lcp:interface-config#1=service-policy input
1547 <replaceable>rate</replaceable></literal>
1548 </entry>
1549
1550 <entry morerows="1">
1551 Alternate (Cisco) format: throttle
1552 upstream/downstream to specified
1553 <replaceable>rate</replaceable> Kbps.
1554 </entry>
1555 </row>
1556
1557 <row>
1558 <entry>
1559 <literal>lcp:interface-config#2=service-policy output
1560 <replaceable>rate</replaceable></literal>
1561 </entry>
1562 </row>
1563 </tbody>
1564 </tgroup>
1565 </informaltable>
1566 </para>
1567
1568 <para>
1569 You can also enable and disable throttling an active session
1570 using the <xref linkend="operation-cli-throttle"/> CLI command.
1571 </para>
1572 </sect1>
1573
1574 <sect1 id="interception">
1575 <title>Interception</title>
1576 <para>
1577 You may have to deal with legal requirements to be able to
1578 intercept a user's traffic at any time.
1579 <command>l2tpns</command> allows you to begin and end
1580 interception on the fly, as well as at authentication time.
1581 </para>
1582
1583 <para>
1584 When a user is being intercepted, a copy of every packet they
1585 send and receive will be sent wrapped in a UDP packet to a
1586 specified host.
1587 </para>
1588
1589 <para>
1590 The UDP packet contains just the raw IP frame, with no extra
1591 headers. The script <filename>scripts/l2tpns-capture</filename>
1592 may be used as the end-point for such intercepts, writing the
1593 data in PCAP format (suitable for inspection with
1594 <command>tcpdump</command>).
1595 </para>
1596
1597 <para>
1598 To enable or disable interception of a connected user, use the
1599 <xref linkend="operation-cli-snoop"/> and <userinput>no
1600 snoop</userinput> CLI commands. These will enable interception
1601 immediately.
1602 </para>
1603
1604 <para>
1605 If you wish the user to be intercepted whenever they reconnect,
1606 you will need to modify the RADIUS response to include the
1607 Vendor-Specific value
1608 <literal>Cisco-AVPair="intercept=<replaceable>ip</replaceable>:<replaceable>port</replaceable>"</literal>.
1609 For this feature to be enabled, you need to have the
1610 <filename>autosnoop</filename> module loaded.
1611 </para>
1612 </sect1>
1613
1614 <sect1 id="plugins">
1615 <title>Plugins</title>
1616 <para>
1617 So as to make <command>l2tpns</command> as flexible as possible,
1618 a plugin API is include which you can use to hook into certain
1619 events.
1620 </para>
1621
1622 <para>
1623 There are a some standard modules included which may be used as
1624 examples: <filename>autosnoop</filename>,
1625 <filename>autothrottle</filename>, <filename>garden</filename>,
1626 <filename>sessionctl</filename>,
1627 <filename>setrxspeed</filename>, <filename>snoopctl</filename>,
1628 <filename>stripdomain</filename> and
1629 <filename>throttlectl</filename>.
1630 </para>
1631
1632 <para>
1633 When an event occurs that has a hook, <command>l2tpns</command>
1634 looks for a predefined function name in every loaded module, and
1635 runs them in the order the modules were loaded.
1636 </para>
1637
1638 <para>
1639 The function should return <code>PLUGIN_RET_OK</code> if it is
1640 all OK. If it returns <code>PLUGIN_RET_STOP</code>, then it is
1641 assumed to have worked, but that no further modules should be
1642 run for this event.
1643 </para>
1644
1645 <para>
1646 A return of <code>PLUGIN_RET_ERROR</code> means that this module
1647 failed, and no further processing should be done for this event.
1648 <note><para>Use this with care.</para></note>
1649 </para>
1650
1651 <para>
1652 Most event functions take a specific structure named
1653 <code>param_<replaceable>event</replaceable></code>, which
1654 varies in content with each event. The function name for each
1655 event will be
1656 <code>plugin_<replaceable>event</replaceable></code>, so for the
1657 event <replaceable>timer</replaceable>, the function declaration
1658 should look like:
1659
1660 <programlisting>
1661 int plugin_timer(struct param_timer *data);
1662 </programlisting>
1663
1664 A list of the available events follows, with a list of all the
1665 fields in the supplied structure:
1666
1667 <informaltable>
1668 <tgroup cols="4">
1669 <colspec colname="event"/>
1670 <colspec colname="event_desc"/>
1671 <colspec colname="member"/>
1672 <colspec colname="member_desc"/>
1673 <spanspec spanname="args" namest="member" nameend="member_desc"/>
1674 <thead>
1675 <row>
1676 <entry>Event</entry>
1677 <entry>Description</entry>
1678 <entry spanname="args">Arguments</entry>
1679 </row>
1680 </thead>
1681
1682 <tbody>
1683 <row>
1684 <entry morerows="1"><code>plugin_init</code></entry>
1685 <entry morerows="1">
1686 <para>
1687 Called when the plugin is loaded. A pointer to a
1688 struct containing function pointers is passed as the
1689 only argument, allowing the plugin to call back into
1690 the main code.
1691 </para>
1692 <para>
1693 Prior to loading the plugin, <command>l2tpns</command>
1694 checks the API version the plugin was compiled
1695 against. All plugins should contain:
1696 <programlisting>
1697 int plugin_api_version = PLUGIN_API_VERSION;
1698 </programlisting>
1699 </para>
1700 </entry>
1701 <entry spanname="args"><code>struct pluginfuncs *</code></entry>
1702 </row>
1703 <row>
1704 <entry spanname="args">
1705 See <code>pluginfuncs</code> structure in
1706 <code>plugin.h</code> for available functions.
1707 </entry>
1708 </row>
1709
1710 <row>
1711 <entry morerows="1"><code>plugin_done</code></entry>
1712 <entry morerows="1">
1713 Called when the plugin is unloaded or
1714 <command>l2tpns</command> is shutdown.
1715 </entry>
1716 <entry spanname="args"><code>void</code></entry>
1717 </row>
1718 <row>
1719 <entry spanname="args">No arguments.</entry>
1720 </row>
1721
1722 <row>
1723 <entry morerows="6"><code>plugin_pre_auth</code></entry>
1724 <entry morerows="6">
1725 Called after a RADIUS response has been received, but
1726 before it has been processed by the code. This will
1727 allow you to modify the response in some way.
1728 </entry>
1729 <entry spanname="args">
1730 <code>struct plugin param_pre_auth *</code>
1731 </entry>
1732 </row>
1733 <row>
1734 <entry><code>tunnelt *t</code></entry>
1735 <entry>Tunnel.</entry>
1736 </row>
1737 <row>
1738 <entry><code>sessiont *s</code></entry>
1739 <entry>Session.</entry>
1740 </row>
1741 <row>
1742 <entry><code>char *username</code></entry>
1743 <entry>User name.</entry>
1744 </row>
1745 <row>
1746 <entry><code>char *password</code></entry>
1747 <entry>Password.</entry>
1748 </row>
1749 <row>
1750 <entry><code>int protocol</code></entry>
1751 <entry>
1752 Authentication protocol: <literal>0xC023</literal> for PAP,
1753 <literal>0xC223</literal> for CHAP.
1754 </entry>
1755 </row>
1756 <row>
1757 <entry><code>int continue_auth</code></entry>
1758 <entry>Set to 0 to stop processing authentication modules.</entry>
1759 </row>
1760
1761 <row>
1762 <entry morerows="5"><code>plugin_post_auth</code></entry>
1763 <entry morerows="5">
1764 Called after a RADIUS response has been received, and
1765 the basic checks have been performed. This is what
1766 the <filename>garden</filename> module uses to force
1767 authentication to be accepted.
1768 </entry>
1769 <entry spanname="args">
1770 <code>struct plugin param_post_auth *</code>
1771 </entry>
1772 </row>
1773 <row>
1774 <entry><code>tunnelt *t</code></entry>
1775 <entry>Tunnel.</entry>
1776 </row>
1777 <row>
1778 <entry><code>sessiont *s</code></entry>
1779 <entry>Session.</entry>
1780 </row>
1781 <row>
1782 <entry><code>char *username</code></entry>
1783 <entry>User name.</entry>
1784 </row>
1785 <row>
1786 <entry><code>short auth_allowed</code></entry>
1787 <entry>
1788 Initially true or false depending on whether
1789 authentication has been allowed so far. You can
1790 set this to 1 or 0 to force authentication to be
1791 accepted or rejected.
1792 </entry>
1793 </row>
1794 <row>
1795 <entry><code>int protocol</code></entry>
1796 <entry>
1797 Authentication protocol: <literal>0xC023</literal> for PAP,
1798 <literal>0xC223</literal> for CHAP.
1799 </entry>
1800 </row>
1801
1802 <row>
1803 <entry morerows="1"><code>plugin_timer</code></entry>
1804 <entry morerows="1">
1805 Run once per second.
1806 </entry>
1807 <entry spanname="args">
1808 <code>struct plugin param_timer *</code>
1809 </entry>
1810 </row>
1811 <row>
1812 <entry><code>time_t time_now</code></entry>
1813 <entry>The current unix timestamp.</entry>
1814 </row>
1815
1816 <row>
1817 <entry morerows="2"><code>plugin_new_session</code></entry>
1818 <entry morerows="2">
1819 Called after a session is fully set up. The session
1820 is now ready to handle traffic.
1821 </entry>
1822 <entry spanname="args">
1823 <code>struct plugin param_new_session *</code>
1824 </entry>
1825 </row>
1826 <row>
1827 <entry><code>tunnelt *t</code></entry>
1828 <entry>Tunnel.</entry>
1829 </row>
1830 <row>
1831 <entry><code>sessiont *s</code></entry>
1832 <entry>Session.</entry>
1833 </row>
1834
1835 <row>
1836 <entry morerows="2"><code>plugin_kill_session</code></entry>
1837 <entry morerows="2">
1838 Called when a session is about to be shut down. This
1839 may be called multiple times for the same session.
1840 </entry>
1841 <entry spanname="args">
1842 <code>struct plugin param_kill_session *</code>
1843 </entry>
1844 </row>
1845 <row>
1846 <entry><code>tunnelt *t</code></entry>
1847 <entry>Tunnel.</entry>
1848 </row>
1849 <row>
1850 <entry><code>sessiont *s</code></entry>
1851 <entry>Session.</entry>
1852 </row>
1853
1854 <row>
1855 <entry morerows="5"><code>plugin_control</code></entry>
1856 <entry morerows="5">
1857 <para>
1858 Called in whenever a <command>nsctl</command> packet
1859 is received. This should handle the packet and form a
1860 response if required.
1861 </para>
1862 <para>
1863 Plugin-specific help strings may be included in the
1864 output of <userinput>nsctl help</userinput> by
1865 defining a <code>NULL</code> terminated list of
1866 strings as follows:
1867 <programlisting>
1868 char *plugin_control_help[] = { <replaceable>...</replaceable>, NULL };
1869 </programlisting>
1870 </para>
1871 </entry>
1872 <entry spanname="args">
1873 <code>struct plugin param_control *</code>
1874 </entry>
1875 </row>
1876 <row>
1877 <entry><code>int iam_master</code></entry>
1878 <entry>If true, this node is the cluster master.</entry>
1879 </row>
1880 <row>
1881 <entry><code>int argc</code></entry>
1882 <entry morerows="1"><command>nsctl</command> arguments.</entry>
1883 </row>
1884 <row>
1885 <entry><code>char **argc</code></entry>
1886 </row>
1887 <row>
1888 <entry><code>int reponse</code></entry>
1889 <entry>
1890 Response from control message (if handled): should be
1891 either <code>NSCTL_RES_OK</code> or
1892 <code>NSCTL_RES_ERR</code>.
1893 </entry>
1894 </row>
1895 <row>
1896 <entry><code>char *additional</code></entry>
1897 <entry>
1898 Additional information, output by
1899 <command>nsctl</command> on receiving the response.
1900 </entry>
1901 </row>
1902
1903 <row>
1904 <entry morerows="4"><code>plugin_radius_response</code></entry>
1905 <entry morerows="4">
1906 Called whenever a RADIUS response includes a
1907 <literal>Cisco-AVPair</literal> value. The value is
1908 split into
1909 <replaceable>key</replaceable><literal>=</literal><replaceable>value</replaceable>
1910 pairs. Will be called once for each pair in the
1911 response.
1912 </entry>
1913 <entry spanname="args">
1914 <code>struct plugin param_radius_response *</code>
1915 </entry>
1916 </row>
1917 <row>
1918 <entry><code>tunnelt *t</code></entry>
1919 <entry>Tunnel.</entry>
1920 </row>
1921 <row>
1922 <entry><code>sessiont *s</code></entry>
1923 <entry>Session.</entry>
1924 </row>
1925 <row>
1926 <entry><code>char *key</code></entry>
1927 <entry morerows="1">Key and value.</entry>
1928 </row>
1929 <row>
1930 <entry><code>char *value</code></entry>
1931 </row>
1932
1933 <row>
1934 <entry morerows="2"><code>plugin_radius_reset</code></entry>
1935 <entry morerows="2">
1936 Called whenever a RADIUS CoA request is received to
1937 reset any options to default values before the new
1938 values are applied.
1939 </entry>
1940 <entry spanname="args">
1941 <code>struct param_radius_reset *</code>
1942 </entry>
1943 </row>
1944 <row>
1945 <entry><code>tunnelt *t</code></entry>
1946 <entry>Tunnel.</entry>
1947 </row>
1948 <row>
1949 <entry><code>sessiont *s</code></entry>
1950 <entry>Session.</entry>
1951 </row>
1952
1953 <row>
1954 <entry morerows="3"><code>plugin_radius_account</code></entry>
1955 <entry morerows="3">
1956 Called when preparing a RADIUS accounting record to
1957 allow additional data to be added to the packet.
1958 </entry>
1959 <entry spanname="args">
1960 <code>struct param_radius_account *</code>
1961 </entry>
1962 </row>
1963 <row>
1964 <entry><code>tunnelt *t</code></entry>
1965 <entry>Tunnel.</entry>
1966 </row>
1967 <row>
1968 <entry><code>sessiont *s</code></entry>
1969 <entry>Session.</entry>
1970 </row>
1971 <row>
1972 <entry><code>uint8_t **packet</code></entry>
1973 <entry>
1974 Pointer to the end of the currently assembled
1975 packet buffer. The value should be incremented by the
1976 length of any data added.
1977 </entry>
1978 </row>
1979
1980 <row>
1981 <entry morerows="1"><code>plugin_become_master</code></entry>
1982 <entry morerows="1">
1983 Called when a node elects itself cluster master.
1984 </entry>
1985 <entry spanname="args"><code>void</code></entry>
1986 </row>
1987 <row>
1988 <entry spanname="args">No arguments.</entry>
1989 </row>
1990
1991 <row>
1992 <entry morerows="1"><code>plugin_new_session_master</code></entry>
1993 <entry morerows="1">
1994 Called once for each open session on becoming cluster
1995 master.
1996 </entry>
1997 <entry spanname="args"><code>sessiont *</code></entry>
1998 </row>
1999 <row>
2000 <entry spanname="args">
2001 Session.
2002 </entry>
2003 </row>
2004 </tbody>
2005 </tgroup>
2006 </informaltable>
2007 </para>
2008 </sect1>
2009
2010 <sect1 id="walled-garden">
2011 <title>Walled Garden</title>
2012 <para>
2013 A "Walled Garden" is implemented so that you can provide perhaps
2014 limited service to sessions that incorrectly authenticate.
2015 </para>
2016
2017 <para>
2018 Whenever a session provides incorrect authentication, and the
2019 RADIUS server responds with Auth-Reject, the walled garden
2020 module (if loaded) will force authentication to succeed, but set
2021 the <literal>walled_garden</literal> flag in the session
2022 structure, and adds an <command>iptables</command> rule to the
2023 <literal>garden_users</literal> chain to cause all packets for
2024 the session to traverse the <literal>garden</literal> chain.
2025 </para>
2026
2027 <para>
2028 This doesn't <emphasis>just work</emphasis>. To set this all
2029 up, you will to setup the <literal>garden</literal> nat table
2030 with the <xref linkend="config-build-garden"/> script with rules
2031 to limit user's traffic.
2032 </para>
2033
2034 <para>
2035 For example, to force all traffic except DNS to be forwarded to
2036 192.168.1.1, add these entries to your
2037 <filename>build-garden</filename> script:
2038
2039 <programlisting>
2040 iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
2041 iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
2042 </programlisting>
2043 </para>
2044
2045 <para>
2046 <command>l2tpns</command> will add entries to the
2047 <literal>garden_users</literal> chain as appropriate.
2048 </para>
2049
2050 <para>
2051 You can check the amount of traffic being captured using the
2052 following command:
2053
2054 <screen>
2055 iptables -t nat -L garden -nvx
2056 </screen>
2057 </para>
2058 </sect1>
2059
2060 <sect1 id="filtering">
2061 <title>Filtering</title>
2062 <para>
2063 Sessions may be filtered by specifying
2064 <literal>Filter-Id</literal> attributes in the RADIUS reply.
2065 <replaceable>filter</replaceable>.<literal>in</literal>
2066 specifies that the named access-list
2067 <replaceable>filter</replaceable> should be applied to traffic
2068 from the customer,
2069 <replaceable>filter</replaceable>.<literal>out</literal>
2070 specifies a list for traffic to the customer.
2071 </para>
2072 </sect1>
2073
2074 <sect1 id="clustering">
2075 <title>Clustering</title>
2076 <para>
2077 An <command>l2tpns</command> cluster consists of one* or more
2078 servers configured with the same configuration, notably the
2079 multicast <literal>cluster_address</literal>.
2080 </para>
2081
2082 <para>*A stand-alone server is simply a degraded cluster.</para>
2083
2084 <para>
2085 Initially servers come up as cluster slaves, and periodically
2086 (every <literal>cluster_hb_interval</literal>/10 seconds) send
2087 out ping packets containing the start time of the process to the
2088 multicast <literal>cluster_address</literal>.
2089 </para>
2090
2091 <para>
2092 A cluster master sends heartbeat rather than ping packets, which
2093 contain those session and tunnel changes since the last
2094 heartbeat.
2095 </para>
2096
2097 <para>
2098 When a slave has not seen a heartbeat within
2099 <literal>cluster_hb_timeout</literal>/10 seconds it "elects" a
2100 new master by examining the list of peers it has seen pings from
2101 and determines which of these and itself is the "best" candidate
2102 to be master. "Best" in this context means the server with the
2103 highest uptime (the highest IP address is used as a tie-breaker
2104 in the case of equal uptimes).
2105 </para>
2106
2107 <para>
2108 After discovering a master, and determining that it is
2109 up-to-date (has seen an update for all in-use sessions and
2110 tunnels from heartbeat packets) will raise a route (see <xref
2111 linkend="routing"/>) for the <literal>bind_address</literal> and
2112 for all addresses/networks in <filename>ip_pool</filename>.
2113 </para>
2114
2115 <para>
2116 Any packets recieved by the slave which would alter the session
2117 state, as well as packets for throttled or gardened sessions are
2118 forwarded to the master for handling. In addition, byte
2119 counters for session traffic are periodically forwarded.
2120 </para>
2121
2122 <para>
2123 The master, when determining that it has at least one* up-to-date
2124 slave will drop all routes (raising them again if all slaves
2125 disappear) and subsequently handle only packets forwarded to it
2126 by the slaves.
2127 </para>
2128
2129 <para>*Configurable with <literal>cluster_master_min_adv</literal></para>
2130 </sect1>
2131
2132 <sect1 id="routing">
2133 <title>Routing</title>
2134 <para>
2135 If you are running a single instance, you may simply statically
2136 route the IP pools to the <literal>bind_address</literal>
2137 (<command>l2tpns</command> will send a gratuitous arp).
2138 </para>
2139
2140 <para>
2141 For a cluster, configure the members as BGP neighbours on your
2142 router and configure multi-path load-balancing. Cisco uses
2143 <userinput>maximum-paths ibgp</userinput> for IBGP. If this is
2144 not supported by your IOS revision, you can use
2145 <userinput>maximum-paths</userinput> (which works for EBGP) and
2146 set <literal>as_number</literal> to a private value such as
2147 64512.
2148 </para>
2149 </sect1>
2150 </article>