diff --git a/Docs/common/config.xml b/Docs/common/config.xml
deleted file mode 100644
index 6207ae3..0000000
--- a/Docs/common/config.xml
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
diff --git a/Docs/common/docbook.css b/Docs/common/docbook.css
deleted file mode 100644
index 00e3974..0000000
--- a/Docs/common/docbook.css
+++ /dev/null
@@ -1,69 +0,0 @@
-div.article > div.titlepage {
- text-align: center;
-}
-
-.abstract {
- text-align: justify;
-}
-
-.title {
- font-family: sans-serif;
- font-weight: bolder;
- margin-bottom: 0.5em;
-}
-
-.sect2, .sect2, .sect3, .sect4 {
- margin-left: 2%;
- margin-right: 2%;
-}
-
-.sect2 .title, .sect2 .title, .sect3 .title, .sect4 .title {
- margin-left: 0;
- margin-right: 0;
-}
-
-.synopsis, .screen, .programlisting {
- font-family: monospace;
- font-size: 1em;
- display: block;
- padding: 10px;
- border: 1px solid #bbb;
- background-color: #eee;
- color: #000;
- overflow: auto;
- border-radius: 2.5px;
- -moz-border-radius: 2.5px;
- margin: 0.5em 2em;
-}
-
-.programlisting em {
- color: red;
-}
-
-.hanging-indent {
- margin-left: 4em;
- text-indent: -2em;
-}
-
-table {
- margin: 0.5em 2em;
- border: 1px solid #bbb;
- border-collapse: collapse;
-}
-
-td {
- vertical-align: baseline;
-}
-
-thead {
- background-color: #eee;
-}
-
-td table {
- margin: 0;
- border: 0;
-}
-
-td {
- border: 1px solid #bbb;
-}
\ No newline at end of file
diff --git a/Docs/l2tpns.8 b/Docs/l2tpns.8
deleted file mode 100644
index ab15bc5..0000000
--- a/Docs/l2tpns.8
+++ /dev/null
@@ -1,257 +0,0 @@
-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-. ds C`
-. ds C'
-'br\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.\"
-.\" Avoid warning from groff about undefined register 'F'.
-.de IX
-..
-.nr rF 0
-.if \n(.g .if rF .nr rF 1
-.if (\n(rF:(\n(.g==0)) \{
-. if \nF \{
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. if !\nF==2 \{
-. nr % 0
-. nr F 2
-. \}
-. \}
-.\}
-.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "L2TPNS"
-.TH L2TPNS 8 "2014-09-14" "perl v5.20.2" "User Contributed Perl Documentation"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
-.SH "NAME"
-l2tpns \- Layer 2 tunneling protocol network server (LNS)
-.SH "SYNOPSIS"
-.IX Header "SYNOPSIS"
-\&\fBl2tpns\fR [\-\fBd\fR] [\-\fBv\fR] [\-\fBc\fR \fIfile\fR] [\-\fBh\fR \fIhostname\fR]
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-\&\fBl2tpns\fR is a daemon for terminating layer 2 tunneling protocol (L2TP: \s-1RFC2661\s0) sessions.
-.PP
-\&\fBl2tpns\fR is a complete L2TP implementation. It supports the \s-1LAC, LNS, PPPOE\s0 and DHCPv6 server.
-.PP
-Once running, \fBl2tpns\fR may be controlled by telnetting to port 23 on the machine running the daemon and with the \fBnsctl\fR utility.
-.SH "OPTIONS"
-.IX Header "OPTIONS"
-.IP "\fB\-d\fR Detach from terminal and fork into the background. By default l2tpns will stay in the foreground." 4
-.IX Item "-d Detach from terminal and fork into the background. By default l2tpns will stay in the foreground."
-\&.
-.IP "\fB\-v\fR Increase verbosity for debugging. Can be used multiple times." 4
-.IX Item "-v Increase verbosity for debugging. Can be used multiple times."
-\&.
-.IP "\fB\-c\fR \fIfile\fR" 4
-.IX Item "-c file"
-Specify configuration file.
-.IP "\fB\-h\fR \fIhostname\fR" 4
-.IX Item "-h hostname"
-Force hostname to \fIhostname\fR.
-.SH "FILES"
-.IX Header "FILES"
-.IP "\fI/etc/l2tpns/startup\-config\fR" 4
-.IX Item "/etc/l2tpns/startup-config"
-The default configuration file.
-.IP "\fI/etc/l2tpns/ip_pool\fR" 4
-.IX Item "/etc/l2tpns/ip_pool"
-\&\s-1IP\s0 address pool configuration.
-.IP "\fI/etc/l2tpns/users\fR" 4
-.IX Item "/etc/l2tpns/users"
-Username/password configuration for access to admin interface.
-.SH "SIGNALS"
-.IX Header "SIGNALS"
-.IP "\fB\s-1SIGHUP\s0\fR Reload the config from disk and re-open log file." 4
-.IX Item "SIGHUP Reload the config from disk and re-open log file."
-\&.
-.IP "\fB\s-1SIGTERM\s0\fR, \fB\s-1SIGINT\s0\fR" 4
-.IX Item "SIGTERM, SIGINT"
-Stop process. Tunnels and sessions are not terminated. This signal should be used to stop l2tpns on a cluster node where there are other machines to continue handling traffic.
-.IP "\fB\s-1SIGQUIT\s0\fR" 4
-.IX Item "SIGQUIT"
-Shut down tunnels and sessions, exit process when complete.
-.SH "MANAGED RADIUS ATTRIBUTE"
-.IX Header "MANAGED RADIUS ATTRIBUTE"
-.IP "\fBAscend-Client-Primary-DNS\fR, \fBAscend-Client-Secondary-DNS\fR" 4
-.IX Item "Ascend-Client-Primary-DNS, Ascend-Client-Secondary-DNS"
-Specifies a primary and secondary \s-1DNS\s0 server address to send to user.
-.IP "\fBDelegated\-IPv6\-Prefix\fR" 4
-.IX Item "Delegated-IPv6-Prefix"
-Assign a network address IPv6 prefix to a user by DHCPv6.
-.IP "\fBFramed-IP-Address\fR" 4
-.IX Item "Framed-IP-Address"
-The address to be configured for the user (IPv4 address of the interface ppp).
-.IP "\fBFramed-Route\fR" 4
-.IX Item "Framed-Route"
-provides routing information to be configured for the user.
-.IP "\fBFramed\-IPv6\-Route\fR" 4
-.IX Item "Framed-IPv6-Route"
-Has the same action as \fBDelegated\-IPv6\-Prefix\fR. \fBDelegated\-IPv6\-Prefix\fR is the correct one to use.
-.IP "\fBFramed\-IPv6\-Address\fR" 4
-.IX Item "Framed-IPv6-Address"
-IPv6 address to be assigned to the user by DHCPv6 (IPv6 address of the interface ppp).
-.IP "\fBIdle-Timeout\fR" 4
-.IX Item "Idle-Timeout"
-disconnects the session if no data for more than \fBIdle-Timeout\fR (in seconds).
-.IP "\fBSession-Timeout\fR" 4
-.IX Item "Session-Timeout"
-disconnects the user session when the time \fBSession-Timeout\fR is reached (in seconds).
-.IP "\fBTunnel-Type\fR, \fBTunnel-Medium-Type\fR, \fBTunnel-Server-Endpoint\fR, \fBTunnel-Password\fR, \fBTunnel-Assignment-Id\fR" 4
-.IX Item "Tunnel-Type, Tunnel-Medium-Type, Tunnel-Server-Endpoint, Tunnel-Password, Tunnel-Assignment-Id"
-attributes returned by the Radius of the remote \s-1LNS\s0 server (\s-1LAC\s0 functionality).
-.Sp
-example, Radius that return the information of 2 remote \s-1LNS\s0 server with which must be open a L2TP \s-1TUNNEL:\s0
-.RS 4
-.IP "\fBTunnel-Type\fR: 1 = L2TP" 4
-.IX Item "Tunnel-Type: 1 = L2TP"
-.PD 0
-.IP "\fBTunnel-Medium-Type\fR: 1 = IPv4" 4
-.IX Item "Tunnel-Medium-Type: 1 = IPv4"
-.ie n .IP "\fBTunnel-Password\fR: 1 = ""TheSecretL2TP""" 4
-.el .IP "\fBTunnel-Password\fR: 1 = ``TheSecretL2TP''" 4
-.IX Item "Tunnel-Password: 1 = TheSecretL2TP"
-.ie n .IP "\fBTunnel-Server-Endpoint\fR: 1 = ""88.xx.xx.x1""" 4
-.el .IP "\fBTunnel-Server-Endpoint\fR: 1 = ``88.xx.xx.x1''" 4
-.IX Item "Tunnel-Server-Endpoint: 1 = 88.xx.xx.x1"
-.ie n .IP "\fBTunnel-Assignment-Id\fR: 1 = ""friendisp_lns1""" 4
-.el .IP "\fBTunnel-Assignment-Id\fR: 1 = ``friendisp_lns1''" 4
-.IX Item "Tunnel-Assignment-Id: 1 = friendisp_lns1"
-.IP "\fBTunnel-Type\fR: 2 = L2TP" 4
-.IX Item "Tunnel-Type: 2 = L2TP"
-.IP "\fBTunnel-Medium-Type\fR: 2 = IPv4" 4
-.IX Item "Tunnel-Medium-Type: 2 = IPv4"
-.ie n .IP "\fBTunnel-Password\fR: 2 = ""TheSecretL2TP""" 4
-.el .IP "\fBTunnel-Password\fR: 2 = ``TheSecretL2TP''" 4
-.IX Item "Tunnel-Password: 2 = TheSecretL2TP"
-.ie n .IP "\fBTunnel-Server-Endpoint\fR: 2 = ""88.xx.xx.x2""" 4
-.el .IP "\fBTunnel-Server-Endpoint\fR: 2 = ``88.xx.xx.x2''" 4
-.IX Item "Tunnel-Server-Endpoint: 2 = 88.xx.xx.x2"
-.ie n .IP "\fBTunnel-Assignment-Id\fR: 2 = ""friendisp_lns2""" 4
-.el .IP "\fBTunnel-Assignment-Id\fR: 2 = ``friendisp_lns2''" 4
-.IX Item "Tunnel-Assignment-Id: 2 = friendisp_lns2"
-.RE
-.RS 4
-.RE
-.PD
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fBstartup-config\fR(5), \fBnsctl\fR(8)
-.SH "AUTHOR"
-.IX Header "AUTHOR"
-This manual page was written by Jonathan McDowell and Fernando Alves (fendo@sameswifi.fr), for the Debian GNU/Linux system (but may be used by others).
diff --git a/Docs/l2tpns.8.pod b/Docs/l2tpns.8.pod
deleted file mode 100644
index e2aa240..0000000
--- a/Docs/l2tpns.8.pod
+++ /dev/null
@@ -1,151 +0,0 @@
-=pod
-
-=head1 NAME
-
-l2tpns - Layer 2 tunneling protocol network server (LNS)
-
-=head1 SYNOPSIS
-
-B [-B] [-B] [-B I] [-B I]
-
-=head1 DESCRIPTION
-
-B is a daemon for terminating layer 2 tunneling protocol (L2TP: RFC2661) sessions.
-
-B is a complete L2TP implementation. It supports the LAC, LNS, PPPOE and DHCPv6 server.
-
-Once running, B may be controlled by telnetting to port 23 on the machine running the daemon and with the B utility.
-
-=head1 OPTIONS
-
-=over
-
-=item B<-d> Detach from terminal and fork into the background. By default l2tpns will stay in the foreground.
-
-.
-
-=item B<-v> Increase verbosity for debugging. Can be used multiple times.
-
-.
-
-=item B<-c> I
-
-Specify configuration file.
-
-=item B<-h> I
-
-Force hostname to I.
-
-=back
-
-=head1 FILES
-
-=over
-
-=item I
-
-The default configuration file.
-
-=item I
-
-IP address pool configuration.
-
-=item I
-
-Username/password configuration for access to admin interface.
-
-=back
-
-=head1 SIGNALS
-
-=over
-
-=item B Reload the config from disk and re-open log file.
-
-.
-
-=item B, B
-
-Stop process. Tunnels and sessions are not terminated. This signal should be used to stop l2tpns on a cluster node where there are other machines to continue handling traffic.
-
-=item B
-
-Shut down tunnels and sessions, exit process when complete.
-
-=back
-
-=head1 MANAGED RADIUS ATTRIBUTE
-
-=over
-
-=item B, B
-
-Specifies a primary and secondary DNS server address to send to user.
-
-=item B
-
-Assign a network address IPv6 prefix to a user by DHCPv6.
-
-=item B
-
-The address to be configured for the user (IPv4 address of the interface ppp).
-
-=item B
-
-provides routing information to be configured for the user.
-
-=item B
-
-Has the same action as B. B is the correct one to use.
-
-=item B
-
-IPv6 address to be assigned to the user by DHCPv6 (IPv6 address of the interface ppp).
-
-=item B
-
-disconnects the session if no data for more than B (in seconds).
-
-=item B
-
-disconnects the user session when the time B is reached (in seconds).
-
-=item B, B, B, B, B
-
-attributes returned by the Radius of the remote LNS server (LAC functionality).
-
-example, Radius that return the information of 2 remote LNS server with which must be open a L2TP TUNNEL:
-
-=over
-
-=item B: 1 = L2TP
-
-=item B: 1 = IPv4
-
-=item B: 1 = "TheSecretL2TP"
-
-=item B: 1 = "88.xx.xx.x1"
-
-=item B: 1 = "friendisp_lns1"
-
-=item B: 2 = L2TP
-
-=item B: 2 = IPv4
-
-=item B: 2 = "TheSecretL2TP"
-
-=item B: 2 = "88.xx.xx.x2"
-
-=item B: 2 = "friendisp_lns2"
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-B(5), B(8)
-
-=head1 AUTHOR
-
-This manual page was written by Jonathan McDowell and Fernando Alves (fendo@sameswifi.fr), for the Debian GNU/Linux system (but may be used by others).
diff --git a/Docs/manual.html b/Docs/manual.html
deleted file mode 100644
index e1d144c..0000000
--- a/Docs/manual.html
+++ /dev/null
@@ -1,1189 +0,0 @@
-
-
-
-
-L2TPNS Manual
-
-
-
-
-l2tpns a complete L2TP implementation. It supports the LAC, LNS, PPPOE and DHCPv6 server.
-
-L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection. l2tpns implements PPP over L2TP only.
-
-There are a couple of other L2TP implementations, of which l2tpd is probably the most popular. l2tpd also will handle being either end of a tunnel, and is a lot more configurable than l2tpns. However, due to the way it works, it is nowhere near as scalable.
-
-l2tpns uses the TUN/TAP interface provided by the Linux kernel to receive and send packets. Using some packet manipulation it doesn't require a single interface per connection, as l2tpd does.
-
-This allows it to scale extremely well to very high loads and very high numbers of connections.
-
-It also has a plugin architecture which allows custom code to be run during processing. An example of this is in the walled garden module included.
-
-
-Documentation is not my best skill. If you find any problems
-with this document, or if you wish to contribute, please email the mailing list.
-
-
Installation
-
Requirements
-
-
-
Linux kernel version 2.4 or above, with the Tun/Tap interface either
-compiled in, or as a module.
-
-You can generally get away with just running make from the source
-directory. This will compile the daemon, associated tools and any modules
-shipped with the distribution.
-
-
Install
-
-After you have successfully compiled everything, run make
-install to install it. By default, the binaries are installed into
-/usr/sbin, the configuration into /etc/l2tpns, and the
-modules into /usr/lib/l2tpns.
-
-You will definately need to edit the configuration files before you
-start. See the Configuration section for
-more information.
-
-
Running
-
-You only need to run /usr/sbin/l2tpns as root to start it. It does
-not detach to a daemon process, so you should perhaps run it from init.
-
-By default there is no log destination set, so all log messages will go to
-stdout.
-
-
Configuration
-
-All configuration of the software is done from the files installed into
-/etc/l2tpns.
-
-
startup-config
-
-This is the main configuration file for l2tpns. The format of the file is a
-list of commands that can be run through the command-line interface. This
-file can also be written directly by the l2tpns process if a user runs the
-write memory command, so any comments will be lost. However if your
-policy is not to write the config by the program, then feel free to comment
-the file with a # or ! at the beginning of the line.
-
-A list of the possible configuration directives follows. Each of these
-should be set by a line like:
debug (int)
-Sets the level of messages that will be written to the log file. The value
-should be between 0 and 5, with 0 being no debugging, and 5 being the
-highest. A rough description of the levels is:
-
-
Critical Errors - Things are probably broken
-
Errors - Things might have gone wrong, but probably will recover
-
Warnings - Just in case you care what is not quite perfect
-
Information - Parameters of control packets
-
Calls - For tracing the execution of the code
-
Packets - Everything, including a hex dump of all packets processed... probably twice
-
-Note that the higher you set the debugging level, the slower the program
-will run. Also, at level 5 a LOT of information will be logged. This should
-only ever be used for working out why it doesn't work at all.
-
-
-
log_file (string)
-This will be where all logging and debugging information is written to. This may be either a filename, such as /var/log/l2tpns, or the special magic string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
-
-
-
pid_file (string)
-If set, the process id will be written to the specified file. The value must be an absolute path.
-
-
-
random_deviceB> (string)
-Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
-
-
-
l2tp_secret (string)
-The secret used by l2tpns for authenticating tunnel request. Must be
-the same as the LAC, or authentication will fail. Only actually be
-used if the LAC requests authentication.
-
-
-
l2tp_mtu (int)
-MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
-
-
-
ppp_restart_time (int)
-ppp_max_configure (int)
-ppp_max_failure (int)
-PPP counter and timer values, as described in §4.1 of
-RFC1661.
-
-
-
primary_dns (ip address)
-
secondary_dns (ip address)
-Whenever a PPP connection is established, DNS servers will be sent to the
-user, both a primary and a secondary. If either is set to 0.0.0.0, then that
-one will not be sent.
-
-
-
primary_radius (ip address)
-
secondary_radius (ip address)
-Sets the RADIUS servers used for both authentication and accounting.
-If the primary server does not respond, then the secondary RADIUS
-server will be tried.
-Note: in addition to the source IP address and
-identifier, the RADIUS server must include the source
-port when detecting duplicates to suppress (in order to cope with a
-large number of sessions coming on-line simultaneously l2tpns uses a
-set of udp sockets, each with a separate identifier).
-
-
-
primary_radius_port (short)
-
secondary_radius_port (short)
-Sets the authentication ports for the primary and secondary RADIUS
-servers. The accounting port is one more than the authentication
-port. If no RADIUS ports are given, the authentication port defaults
-to 1645, and the accounting port to 1646.
-
-
-
radius_accounting (boolean)
-If set to true, then RADIUS accounting packets will be sent. This
-means that a Start record will be sent when the session is
-successfully authenticated, and a Stop record will be sent when the
-session is closed.
-
-
-
radius_secret (string)
-This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
-
-
-
radius_authtypes (string)
-A comma separated list of supported RADIUS authentication methods
-(pap or chap), in order of preference (default pap).
-
-
-
radius_dae_port (short)
-Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization)
-requests (default: 3799).
-
-
-
allow_duplicate_users (boolean)
-Allow multiple logins with the same username. If false (the default),
-any prior session with the same username will be dropped when a new
-session is established.
-
-
-
bind_address (ip address)
-It's the listen address of the l2tp udp protocol sent and received to LAC. This address is also assigned to the tun interface if no iftun_address is specified. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
-
-
-
iftun_address (ip address)
-This parameter is used when you want a tun interface address different
-from the address of "bind_address" (For use in cases of specific configuration).
-If no address is given to iftun_address and bind_address, 1.1.1.1 is used.
-
-
-
bind_multi_address (ip address)
-This parameter permit on to listen several address of the l2tp udp protocol
-(and set several address to the tun interface).
-
-WHEN this parameter is set, It OVERWRITE the parameters "bind_address"
-and "iftun_address".
-
-these can be interesting when you want do load-balancing in cluster mode
-of the uploaded from the LAC. For example you can set a bgp.prepend(MY_AS)
-for Address1 on LNS1 and a bgp.prepend(MY_AS) for Address2 on LNS2
-(see BGP AS-path prepending).
-
-example of use with 2 address:
-
-set bind_multi_address "64.14.13.41, 64.14.13.42"
-
-
-
tundevicename (string)
-Name of the tun interface (default: "tun0").
-
-
-
peer_address (ip address)
-Address to send to clients as the default gateway.
-
-
-
send_garp (boolean)
-Determines whether or not to send a gratuitous ARP for the
-bind_address when the server is ready to handle traffic (default:
-true).
-This value is ignored if BGP is configured.
-
-
-
throttle_speed (int)
-Sets the default speed (in kbits/s) which sessions will be limited to.
-If this is set to 0, then throttling will not be used at all. Note:
-You can set this by the CLI, but changes will not affect currently
-connected users.
-
-
-
throttle_buckets (int)
-Number of token buckets to allocate for throttling. Each throttled
-session requires two buckets (in and out).
-
-
-
accounting_dir (string)
-If set to a directory, then every 5 minutes the current usage for
-every connected use will be dumped to a file in this directory. Each
-file dumped begins with a header, where each line is prefixed by #.
-Following the header is a single line for every connected user, fields
-separated by a space. The fields are username, ip, qos,
-uptxoctets, downrxoctets, origin (optional). The qos field is 1 if a standard user, and
-2 if the user is throttled. The origin field is dump if account_all_origin is set to true
-(origin value: L=LAC data, R=Remote LNS data, P=PPPOE data).
-
-
-
account_all_origin (boolean)
-If set to true, all origin of the usage is dumped to the accounting file (LAC+Remote LNS+PPPOE)(default false).
-
-
-
dump_speed (boolean)
-If set to true, then the current bandwidth utilization will be logged every
-second. Even if this is disabled, you can see this information by running
-the uptime command on the CLI.
-
-
-
multi_read_count (int)
-Number of packets to read off each of the UDP and TUN fds when
-returned as readable by select (default: 10). Avoids incurring the
-unnecessary system call overhead of select on busy servers.
-
-
-
scheduler_fifo (boolean)
-Sets the scheduling policy for the l2tpns process to SCHED_FIFO. This
-causes the kernel to immediately preempt any currently running SCHED_OTHER
-(normal) process in favour of l2tpns when it becomes runnable.
-Ignored on uniprocessor systems.
-
-
-
lock_pages (boolean)
-Keep all pages mapped by the l2tpns process in memory.
-
-
-
icmp_rate (int)
-Maximum number of host unreachable ICMP packets to send per second.
-
-
-
packet_limit (int>
-Maximum number of packets of downstream traffic to be handled each
-tenth of a second per session. If zero, no limit is applied (default:
-0). Intended as a DoS prevention mechanism and not a general
-throttling control (packets are dropped, not queued).
-
-
-
cluster_address (ip address)
-Multicast cluster address (default: 239.192.13.13). See the section
-on Clustering for more information.
-
-
-
cluster_port (int udp port)
-UDP cluster port (default: 32792). See the section on
-Clustering for more information.
-
-
-
cluster_interface (string)
-Interface for cluster packets (default: eth0).
-
-
-
cluster_mcast_ttl (int)
-TTL for multicast packets (default: 1).
-
-
-
cluster_hb_interval (int)
-Interval in tenths of a second between cluster heartbeat/pings.
-
-
-
cluster_hb_timeout (int)
-Cluster heartbeat timeout in tenths of a second. A new master will be
-elected when this interval has been passed without seeing a heartbeat
-from the master.
-
-
-
cluster_master_min_adv (int)
-Determines the minimum number of up to date slaves required before the
-master will drop routes (default: 1).
-
-
-
echo_timeout (int)
-Time between last packet sent and LCP ECHO generation
-(default: 10 (seconds)).
-
-
-
idle_echo_timeout (int)
-Drop sessions who have not responded within idle_echo_timeout seconds
-(default: 240 (seconds))
-
-
-
ppp_keepalive (int)
-Change this value to no to force generation of LCP ECHO every
-echo_timeout seconds, even there are activity on the link.
-(default: yes)
-
-
-
auth_tunnel_change_addr_src (boolean)
-This parameter authorize to change the source IP of the tunnels l2tp.
-This parameter can be used when the remotes BAS/LAC are l2tpns server
-configured in cluster mode, but that the interface to remote LNS are
-not clustered (the tunnel can be coming from different source IP)
-(default: no).
-
-
-
disable_sending_hello (boolean)
-Disable l2tp sending HELLO message for Apple compatibility.
-Some OS X implementation of l2tp no manage the L2TP "HELLO message".
-(default: no).
-
-
-
-
-
LAC configuration
-
-
bind_address_remotelns (ip address)
-Address of the interface to listen the remote LNS tunnels.
-If no address is given, all interfaces are listened (Any Address).
-
-
-
bind_portremotelns (short)
-Port to bind for the Remote LNS (default: 65432).
-
-
-
-
-
A static REMOTES LNS configuration can be entered by the command:
-
setforwardMASKIPPORTSECRET
-
-where MASK specifies the mask of users who have forwarded to
-remote LNS (ex: "/friendISP@company.com").
-where IP specifies the IP of the remote LNS (ex: "66.66.66.55").
-where PORT specifies the L2TP Port of the remote LNS
-(Normally should be 1701) (ex: 1701).
-where SECRET specifies the secret password the remote LNS (ex: mysecret).
-
-The static Remote LNS configuration can be used when the friend ISP not
-have a proxied Radius.
-If the proxied Radius is used, It will return the RADIUS attributes:
- Tunnel-Type: 1 = L2TP
- Tunnel-Medium-Type: 1 = IPv4
- Tunnel-Password: 1 = "LESECRETL2TP"
- Tunnel-Server-Endpoint: 1 = "88.xx.xx.x1"
- Tunnel-Assignment-Id: 1 = "friendisp_lns1"
- Tunnel-Type: 2 = L2TP
- Tunnel-Medium-Type: 2 = IPv4
- Tunnel-Password: 2 = "LESECRETL2TP"
- Tunnel-Server-Endpoint: 2 = "88.xx.xx.x2"
- Tunnel-Assignment-Id: 2 = "friendisp_lns2"
-
-
PPPOE configuration
-
-
-
pppoe_if_to_bind (string)
-PPPOE server interface to bind (ex: "eth0.12"), If not specified the server PPPOE is not enabled.
-For the pppoe clustering, all the interfaces PPPOE of the clusters must use the same HW address (MAC address).
-
-
-
pppoe_service_name (string)
-PPPOE service name (default: NULL).
-
-
-
pppoe_ac_name (string)
-PPPOE access concentrator name (default: "l2tpns-pppoe").
-
-
-
pppoe_only_equal_svc_name (boolean)
-If set to yes, the PPPOE server only accepts clients with a "service-name"
-different from NULL and a "service-name" equal to server "service-name" (default: no).
-
-
-
-
-
BGP configuration
-
-
BGP routing configuration is entered by the command:
-The routing configuration section is entered by the command
-
router bgpas
-where as specifies the local AS number.
-
-
Subsequent lines prefixed with
-
neighbourpeer
-define the attributes of BGP neighhbours. Valid commands are:
-
-
neighbourpeerremote-asas
-
neighboutpeertimerskeepalive hold
-
-
-Where peer specifies the BGP neighbour as either a hostname or
-IP address, as is the remote AS number and keepalive,
-hold are the timer values in seconds.
-
-
Named access-lists are configured using one of the commands:
-
-
ip access-list standardname
-
ip access-list extendedname
-
-
-
Subsequent lines prefixed with permit or deny
-define the body of the access-list. Standard access-list syntax:
-
-
-Usernames and passwords for the command-line interface are stored in
-this file. The format is username:password where
-password may either by plain text, an MD5 digest (prefixed by
-$1salt$) or a DES password, distinguished from
-plain text by the prefix {crypt}.
-
-The username enable has a special meaning and is used to set
-the enable password.
-
-Note: If this file doesn't exist, then anyone who can get to
-port 23 will be allowed access without a username / password.
-
-
ip_pool
-
-This file is used to configure the IP address pool which user
-addresses are assigned from. This file should contain either an IP
-address or a CIDR network per line. e.g.:
-
-Keep in mind that l2tpns can only handle 65535 connections per
-process, so don't put more than 65535 IP addresses in the
-configuration file. They will be wasted.
-
-
build-garden
-
-The garden plugin on startup creates a NAT table called "garden" then
-sources the build-garden script to populate that table. All
-packets from gardened users will be sent through this table. Example:
-
-
-
-A running l2tpns process can be controlled in a number of ways. The primary
-method of control is by the Command-Line Interface (CLI).
-
-You can also remotely send commands to modules via the nsctl client
-provided.
-
-Also, there are a number of signals that l2tpns understands and takes action
-when it receives them.
-
-
Command-Line Interface
-
-You can access the command line interface by telnet'ing to port 23.
-There is no IP address restriction, so it's a good idea to firewall
-this port off from anyone who doesn't need access to it. See
-users for information on restricting access based
-on a username and password.
-
-The CLI gives you real-time control over almost everything in
-the process. The interface is designed to look like a Cisco
-device, and supports things like command history, line editing and
-context sensitive help. This is provided by linking with the
-libcli
-library. Some general documentation of the interface is
-
-here.
-
-After you have connected to the telnet port (and perhaps logged in), you
-will be presented with a hostname> prompt.
-
-Enter help to get a list of possible commands. A brief
-overview of the more important commands follows:
-
-
-
show session
-Without specifying a session ID, this will list all tunnels currently
-connected. If you specify a session ID, you will be given all
-information on a single tunnel. Note that the full session list can
-be around 185 columns wide, so you should probably use a wide terminal
-to see the list properly.
-The columns listed in the overview are:
-
-
SID
Session ID
-
TID
Tunnel ID - Use with show tunnel tid
-
Username
The username given in the PPP
- authentication. If this is *, then LCP authentication has not
- completed.
-
IP
The IP address given to the session. If
- this is 0.0.0.0, LCP negotiation has not completed.
-
I
Intercept - Y or N depending on whether the
- session is being snooped. See snoop.
-
T
Throttled - Y or N if the session is
- currently throttled. See throttle.
-
G
Walled Garden - Y or N if the user is
- trapped in the walled garden. This field is present even if the
- garden module is not loaded.
-
opened
The number of seconds since the
- session started
-
downloaded
Number of bytes downloaded by the user
-
uploaded
Number of bytes uploaded by the user
-
idle
The number of seconds since traffic was
- detected on the session
-
LAC
The IP address of the LAC the session is
- connected to.
-
CLI
The Calling-Line-Identification field
- provided during the session setup. This field is generated by the
- LAC.
-
-
-
-
-
show users
-With no arguments, display a list of currently connected users. If an
-argument is given, the session details for the given username are
-displayed.
-
-
-
show tunnel
-This will show all the open tunnels in a summary, or detail on a single
-tunnel if you give a tunnel id.
-The columns listed in the overview are:
-
-
TID
Tunnel ID
-
Hostname
The hostname for the tunnel as
- provided by the LAC. This has no relation to DNS, it is just
- a text field.
-
IP
The IP address of the LAC
-
State
Tunnel state - Free, Open, Dieing,
- Opening
-
Sessions
The number of open sessions on the
- tunnel
-
-
-
-
-
show pool
-Displays the current IP address pool allocation. This will only display
-addresses that are in use, or are reserved for re-allocation to a
-disconnected user.
-If an address is not currently in use, but has been used, then in the User
-column the username will be shown in square brackets, followed by the time
-since the address was used:
-
-IP Address Used Session User
-192.168.100.6 N [joe.user] 1548s
-
-
-
-
-
show radius
-Show a summary of the in-use RADIUS sessions. This list should not be very
-long, as RADIUS sessions should be cleaned up as soon as they are used. The
-columns listed are:
-
-
Radius
The ID of the RADIUS request. This is
- sent in the packet to the RADIUS server for identification.
-
State
The state of the request - WAIT, CHAP,
- AUTH, IPCP, START, STOP, NULL.
-
Session
The session ID that this RADIUS
- request is associated with
-
Retry
If a response does not appear to the
- request, it will retry at this time. This is a unix timestamp.
-
Try
Retry count. The RADIUS request is
- discarded after 3 retries.
-
-
-
-
-
show running-config
-This will list the current running configuration. This is in a format that
-can either be pasted into the configuration file, or run directly at the
-command line.
-
-
-
-
show counters
-Internally, counters are kept of key values, such as bytes and packets
-transferred, as well as function call counters. This function displays all
-these counters, and is probably only useful for debugging.
-You can reset these counters by running clear counters.
-
-
-
-
show cluster
-Show cluster status. Shows the cluster state for this server
-(Master/Slave), information about known peers and (for slaves) the
-master IP address, last packet seen and up-to-date status.
write memory
-This will write the current running configuration to the config file
-startup-config, which will be run on a restart.
-
-
-
-
snoop
-You must specify a username, IP address and port. All packets for the
-current session for that username will be forwarded to the given
-host/port. Specify no snoop username to disable interception
-for the session.
-
-If you want interception to be permanent, you will have to modify the RADIUS
-response for the user. See Interception.
-
-
-
-
throttle
-You must specify a username, which will be throttled for the current
-session. Specify no throttle username to disable throttling
-for the current session.
-
-If you want throttling to be permanent, you will have to modify the
-RADIUS response for the user. See Throttling.
-
-
-
-
drop session
-This will cleanly disconnect a session. You must specify a session id, which
-you can get from show session. This will send a disconnect message
-to the remote end.
-
-
-
-
drop tunnel
-This will cleanly disconnect a tunnel, as well as all sessions on that
-tunnel. It will send a disconnect message for each session individually, and
-after 10 seconds it will send a tunnel disconnect message.
-
-
-
-
uptime
-This will show how long the l2tpns process has been running, and the current
-bandwidth utilization:
-
-The bandwidth line contains 4 sets of values.
-UDP-ETH is the current bandwidth going from the LAC to the ethernet
-(user uploads), in mbits/sec.
-ETH-UDP is the current bandwidth going from ethernet to the LAC (user
-downloads).
-TOTAL is the total aggregate bandwidth in mbits/s.
-IN and OUT are packets/per-second going between UDP-ETH and ETH-UDP.
-
-These counters are updated every second.
-
-
-
-
configure terminal
-Enter configuration mode. Use exit or ^Z to exit this mode.
-The following commands are valid in this mode:
-
-
-
load plugin
-Load a plugin. You must specify the plugin name, and it will search in
-/usr/lib/l2tpns for plugin.so. You can unload a loaded plugin with
-remove plugin.
-
-
-
-
set
-Set a configuration variable. You must specify the variable name, and
-the value. If the value contains any spaces, you should quote the
-value with double (") or single (') quotes.
-
-You can set any startup-config value in
-this way, although some may require a restart to take effect.
-
-
-
-
nsctl
-
-nsctl allows messages to be passed to plugins.
-
-Arguments are command and optional args. See
-nsctl(8) for more details.
-
-Built-in command are load_plugin, unload_plugin and
-help. Any other commands are passed to plugins for processing.
-
-
Signals
-
-While the process is running, you can send it a few different signals, using
-the kill command.
-
-killall -HUP l2tpns
-
-
-The signals understood are:
-
-
SIGHUP
Reload the config from disk and re-open log file.
-
SIGTERM, SIGINT
Stop process. Tunnels and sessions are not
-terminated. This signal should be used to stop l2tpns on a
-cluster node where there are other machines to
-continue handling traffic.
-
SIGQUIT
Shut down tunnels and sessions, exit process when
-complete.
-
-
-
Throttling
-
-l2tpns contains support for slowing down user sessions to whatever speed you
-desire. You must first enable the global setting throttle_speed
-before this will be activated.
-
-If you wish a session to be throttled permanently, you should set the
-Vendor-Specific RADIUS value Cisco-Avpair="throttle=yes", which
-will be handled by the autothrottle module.
-
-Otherwise, you can enable and disable throttling an active session using
-the throttle CLI command.
-
-
Interception
-
-You may have to deal with legal requirements to be able to intercept a
-user's traffic at any time. l2tpns allows you to begin and end interception
-on the fly, as well as at authentication time.
-
-When a user is being intercepted, a copy of every packet they send and
-receive will be sent wrapped in a UDP packet to the IP address and port set
-in the snoop_host and snoop_port configuration
-variables.
-
-The UDP packet contains just the raw IP frame, with no extra headers.
-
-To enable interception on a connected user, use the snoop username
-and no snoop username CLI commands. These will enable interception
-immediately.
-
-If you wish the user to be intercepted whenever they reconnect, you will
-need to modify the RADIUS response to include the Vendor-Specific value
-Cisco-Avpair="intercept=yes". For this feature to be enabled,
-you need to have the autosnoop module loaded.
-
-
Authentication
-
-Whenever a session connects, it is not fully set up until authentication is
-completed. The remote end must send a PPP CHAP or PPP PAP authentication
-request to l2tpns.
-
-This request is sent to the RADIUS server, which will hopefully respond with
-Auth-Accept or Auth-Reject.
-
-If Auth-Accept is received, the session is set up and an IP address is
-assigned. The RADIUS server can include a Framed-IP-Address field in the
-reply, and that address will be assigned to the client. It can also include
-specific DNS servers, and a Framed-Route if that is required.
-
-If Auth-Reject is received, then the client is sent a PPP AUTHNAK packet,
-at which point they should disconnect. The exception to this is when the
-walled garden module is loaded, in which case the user still receives the
-PPP AUTHACK, but their session is flagged as being a garden'd user, and they
-should not receive any service.
-
-The RADIUS reply can also contain a Vendor-Specific attribute called
-Cisco-Avpair. This field is a freeform text field that most Cisco
-devices understand to contain configuration instructions for the session. In
-the case of l2tpns it is expected to be of the form
-
-key=value,key2=value2,key3=value3,keyn=value
-
-
-Each key-value pair is separated and passed to any modules loaded. The
-autosnoop and autothrottle understand the keys
-intercept and throttle respectively. For example, to have
-a user who is to be throttled and intercepted, the Cisco-Avpair value should
-contain:
-
-intercept=yes,throttle=yes
-
-
-
Plugins
-
-So as to make l2tpns as flexible as possible (I know the core code is pretty
-difficult to understand), it includes a plugin API, which you can use to
-hook into certain events.
-
-There are a few example modules included - autosnoop, autothrottle and
-garden.
-
-When an event happens that has a hook, l2tpns looks for a predefined
-function name in every loaded module, and runs them in the order the modules
-were loaded.
-
-The function should return PLUGIN_RET_OK if it is all OK. If it returns
-PLUGIN_RET_STOP, then it is assumed to have worked, but that no further
-modules should be run for this event.
-A return of PLUGIN_RET_ERROR means that this module failed, and
-no further processing should be done for this event. Use this with care.
-
-Every event function called takes a specific structure named
-param_event, which varies in content with each event. The
-function name for each event will be plugin_event,
-so for the event timer, the function declaration should look like:
-
-int plugin_timer(struct param_timer *data);
-
-
-A list of the available events follows, with a list of all the fields in the
-supplied structure:
-
-
-
Event
Description
Parameters
-
pre_auth
-
This is called after a RADIUS response has been
- received, but before it has been processed by the
- code. This will allow you to modify the response in
- some way.
-
-
-
-
t
Tunnel
-
s
Session
-
username
-
password
-
protocol
0xC023 for PAP, 0xC223 for CHAP
-
continue_auth
Set to 0 to stop processing authentication modules
-
-
-
-
post_auth
-
This is called after a RADIUS response has been
- received, and the basic checks have been performed. This
- is what the garden module uses to force authentication
- to be accepted.
-
-
-
-
t
Tunnel
-
s
Session
-
username
-
auth_allowed
This is already set to true or
- false depending on whether authentication has been
- allowed so far. You can set this to 1 or 0 to force
- allow or disallow authentication
-
protocol
0xC023 for PAP, 0xC223 for CHAP
-
-
-
-
packet_rx
-
This is called whenever a session receives a
- packet. Use this sparingly, as this will
- seriously slow down the system.
-
-
-
-
t
Tunnel
-
s
Session
-
buf
The raw packet data
-
len
The length of buf
-
-
-
-
packet_tx
-
This is called whenever a session sends a
- packet. Use this sparingly, as this will
- seriously slow down the system.
-
-
-
-
t
Tunnel
-
s
Session
-
buf
The raw packet data
-
len
The length of buf
-
-
-
-
timer
-
This is run every second, no matter what is happening.
- This is called from a signal handler, so make sure anything
- you do is reentrant.
-
-
-
-
time_now
The current unix timestamp
-
-
-
-
new_session
-
This is called after a session is fully set up. The
- session is now ready to handle traffic.
-
-
-
-
t
Tunnel
-
s
Session
-
-
-
-
kill_session
-
This is called when a session is about to be shut down.
- This may be called multiple times for the same session.
-
-
-
-
t
Tunnel
-
s
Session
-
-
-
-
radius_response
-
This is called whenever a RADIUS response includes a
- Cisco-Avpair value. The value is split up into
- key=value pairs, and each is processed through all
- modules.
-
-
-
-
t
Tunnel
-
s
Session
-
key
-
value
-
-
-
-
radius_reset
-
This is called whenever a RADIUS CoA request is
- received to reset any options to default values before
- the new values are applied.
-
-
-
-
t
Tunnel
-
s
Session
-
-
-
-
control
-
This is called in whenever a nsctl packet is received.
- This should handle the packet and form a response if
- required.
-
-
-
-
iam_master
Cluster master status
-
argc
The number of arguments
-
argv
Arguments
-
response
Return value: NSCTL_RES_OK or NSCTL_RES_ERR
-
additional
Extended response text
-
-
-
-
-
-
-
Walled Garden
-
-Walled Garden is implemented so that you can provide perhaps limited service
-to sessions that incorrectly authenticate.
-
-Whenever a session provides incorrect authentication, and the
-RADIUS server responds with Auth-Reject, the walled garden module
-(if loaded) will force authentication to succeed, but set the flag
-garden in the session structure, and adds an iptables rule to
-the garden_users chain to force all packets for the session's IP
-address to traverse the garden chain.
-
-This doesn't just work. To set this all up, you will to
-setup the garden nat table with the
-build-garden script with rules to limit
-user's traffic. For example, to force all traffic except DNS to be
-forwarded to 192.168.1.1, add these entries to your
-build-garden:
-
-
-l2tpns will add entries to the garden_users chain as appropriate.
-
-You can check the amount of traffic being captured using the following
-command:
-
-iptables -t nat -L garden -nvx
-
-
-
Filtering
-
-Sessions may be filtered by specifying Filter-Id attributes in
-the RADIUS reply. filter.in specifies that the named
-access-list filter should be applied to traffic from the
-customer, filter.out specifies a list for traffic to the
-customer.
-
-
Clustering
-
-An l2tpns cluster consists of of one* or more servers configured with
-the same configuration, notably the multicast cluster_address.
-
-*A stand-alone server is simply a degraded cluster.
-
-Initially servers come up as cluster slaves, and periodically (every
-cluster_hb_interval/10 seconds) send out ping packets
-containing the start time of the process to the multicast
-cluster_address.
-
-A cluster master sends heartbeat rather than ping packets, which
-contain those session and tunnel changes since the last heartbeat.
-
-When a slave has not seen a heartbeat within
-cluster_hb_timeout/10 seconds it "elects" a new master by
-examining the list of peers it has seen pings from and determines
-which of these and itself is the "best" candidate to be master.
-"Best" in this context means the server with the highest uptime (the
-highest IP address is used as a tie-breaker in the case of equal
-uptimes).
-
-After discovering a master, and determining that it is up-to-date (has
-seen an update for all in-use sessions and tunnels from heartbeat
-packets) will raise a route (see Routing) for
-the bind_address and for all addresses/networks in
-ip_pool. Any packets recieved by the slave which would alter
-the session state, as well as packets for throttled or gardened
-sessions are forwarded to the master for handling. In addition, byte
-counters for session traffic are periodically forwarded.
-
-A master, when determining that it has at least one up-to-date slave
-will drop all routes (raising them again if all slaves disappear) and
-subsequently handle only packets forwarded to it by the slaves.
-
-*Configurable with cluster_master_min_adv
-
-Multiple clusters can be run on the same network by just using different
-multicast cluster_address. However, for a given host to be part
-of multiple clusters without mixing the clusters,
-cluster_port must be different for each cluster.
-
-
Routing
-If you are running a single instance, you may simply statically route
-the IP pools to the bind_address (l2tpns will send a gratuitous
-arp).
-
-For a cluster, configure the members as BGP neighbours on your router
-and configure multi-path load-balancing. Cisco uses "maximum-paths
-ibgp" for IBGP. If this is not supported by your IOS revision, you
-can use "maximum-paths" (which works for EBGP) and set
-as_number to a private value such as 64512.
-
-
Performance
-
-Performance is great.
-
-I'd like to include some pretty graphs here that show a linear performance
-increase, with no impact by number of connected sessions.
-
-That's really what it looks like.
-
-
-David Parrish
-l2tpns-users@lists.sourceforge.net
-
-
diff --git a/Docs/manual/manual.xml b/Docs/manual/manual.xml
deleted file mode 100644
index 853d116..0000000
--- a/Docs/manual/manual.xml
+++ /dev/null
@@ -1,2182 +0,0 @@
-
-
-
-
-
- L2TPNS Manual
-
-
-
- Overview
-
- l2tpns is half of a complete L2TP
- implementation. It supports only the LNS side of the
- connection.
-
-
-
- L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer
- 2 protocol (e.g. Ethernet, PPP) to be tunneled over an IP
- connection. l2tpns implements PPP over L2TP
- only.
-
-
-
- There are a couple of other L2TP implementations, of which
- l2tpd
- is probably the most popular. l2tpd also will handle being
- either end of a tunnel, and is a lot more configurable than
- l2tpns. However, due to the way it works, it
- is nowhere near as scalable.
-
-
-
- l2tpns uses the TUN/TAP interface provided by
- the Linux kernel to receive and send packets. Using some packet
- manipulation it doesn't require a single interface per
- connection, as l2tpd does.
-
-
-
- This allows it to scale extremely well to very high loads and
- very high numbers of connections.
-
-
-
- It also has a plugin architecture which allows custom code to be
- run during processing. An example of this is in the walled
- garden module included.
-
-
-
-
- Installation
-
- Requirements
-
-
-
- Linux kernel version 2.4 or above, with the Tun/Tap
- interface either compiled in, or as a module.
-
-
-
-
-
- libcli 1.8.5 or greater. You can get this from
-
- SourceForge
-
-
-
-
-
-
- Compiling
-
- You can generally get away with just running
- make from the source directory. This will
- compile the daemon, associated tools and any modules shipped
- with the distribution.
-
-
-
-
- Installing
-
- After you have successfully compiled everything, run
- make install to install it. By
- default, the binaries are installed into
- /usr/sbin, the configuration into
- /etc/l2tpns, and the modules into
- /usr/lib/l2tpns.
-
-
-
- You will definately need to edit the configuration files
- before you start. See for
- more information.
-
-
-
-
- Running
-
- You only need to run /usr/sbin/l2tpns as
- root to start it. It does not normally detach to a daemon
- process (see the option), so you should
- perhaps run it from init.
-
-
-
- By default there is no log destination set, so all log
- messages will go to stdout.
-
-
-
-
-
- Configuration
-
- All configuration of the software is done from the files
- installed into /etc/l2tpns.
-
-
-
- <filename>startup-config</filename>
-
- This is the main configuration file for
- l2tpns. The format of the file is a list
- of commands that can be run through the command-line
- interface. This file can also be written directly by the
- l2tpns process if a user runs the
- write memory command, so any comments
- will be lost. However if your policy is not to write the
- config by the program, then feel free to comment the file with
- a # or ! at the
- beginning of the line.
-
-
-
- A list of the possible configuration directives follows. Each
- of these should be set by a line like:
-
-set configstring "value"
-set ipaddress 192.168.1.1
-set boolean true
-
-
-
-
-
- debug (int)
-
-
- Sets the level of messages that will be written to the
- log file. The value should be between 0 and 5, with 0
- being no debugging, and 5 being the highest. A rough
- description of the levels is:
-
-
-
- 0: Critical Errors
-
- Things are probably broken
-
-
-
-
- 1: Errors
-
-
- Things might have gone wrong, but probably will
- recover
-
-
-
-
-
- 2: Warnings
-
-
- Just in case you care what is not quite perfect
-
-
-
-
-
- 3: Information
-
- Parameters of control packets
-
-
-
-
- 4: Calls
-
- For tracing the execution of the code
-
-
-
-
- 5: Packets
-
-
- Everything, including a hex dump of all packets
- processed... probably twice
-
-
-
-
-
-
-
- Note that the higher you set the debugging level, the
- slower the program will run. Also, at level 5 a
- lot of information will be logged.
- This should only ever be used for working out why it
- doesn't work at all.
-
-
-
-
-
- log_file (string)
-
-
- This will be where all logging and debugging information
- is written to. This may be either a filename, such as
- /var/log/l2tpns, or the special
- magic string
- syslog:facility,
- where facility is any one of
- the syslog logging facilities, such as
- local5.
-
-
-
-
-
- pid_file (string)
-
-
- If set, the process id will be written to the specified
- file. The value must be an absolute path.
-
-
-
-
-
- random_device (string)
-
-
- Path to random data source (default
- /dev/urandom). Use "" to use the
- rand() library function.
-
-
-
-
-
- l2tp_secret (string)
-
-
- The secret used by l2tpns for
- authenticating tunnel request. Must be the same as the
- LAC, or authentication will fail. Only actually be used
- if the LAC requests authentication.
-
-
-
-
-
- l2tp_mtu (int)
-
-
- MTU of interface for L2TP traffic (default:
- 1500). Used to set link MRU and
- adjust TCP MSS.
-
-
-
-
-
- ppp_restart_time (int)
- ppp_max_configure (int)
- ppp_max_failure (int)
-
-
- PPP counter and timer values, as described in §4.1
- of
- RFC1661.
-
-
-
-
-
- primary_dns (ip address)
- econdary_dns (ip address)
-
-
- Whenever a PPP connection is established, DNS servers
- will be sent to the user, both a primary and a
- secondary. If either is set to 0.0.0.0, then that one
- will not be sent.
-
-
-
-
-
- primary_radius (ip address)
- secondary_radius (ip address)
-
-
- Sets the RADIUS servers used for both authentication and
- accounting. If the primary server does not respond,
- then the secondary RADIUS server will be tried.
-
-
-
- In addition to the source IP address and identifier,
- the RADIUS server must include
- the source port when detecting duplicates to suppress
- (in order to cope with a large number of sessions
- coming on-line simultaneously
- l2tpns uses a set of udp sockets,
- each with a separate identifier).
-
-
-
-
-
-
-
- primary_radius_port (short)
- secondary_radius_port (short)
-
-
- Sets the authentication ports for the primary and
- secondary RADIUS servers. The accounting port is one
- more than the authentication port. If no RADIUS ports
- are given, the authentication port defaults to 1645, and
- the accounting port to 1646.
-
-
-
-
-
- radius_accounting (boolean)
-
-
- If set to true, then RADIUS accounting packets will be
- sent. This means that a Start record will be sent when
- the session is successfully authenticated, and a Stop
- record will be sent when the session is closed.
-
-
-
-
-
- radius_interim (int)
-
-
- If radius_accounting is on, defines
- the interval between sending of RADIUS interim
- accounting records (in seconds).
-
-
-
-
-
- radius_secret (string)
-
-
- This secret will be used in all RADIUS queries. If this
- is not set then RADIUS queries will fail.
-
-
-
-
-
- radius_authtypes (string)
-
-
- A comma separated list of supported RADIUS
- authentication methods (pap or
- chap), in order of preference
- (default pap).
-
-
-
-
-
- radius_bind_min (short)
- radius_bind_max (short)
-
-
- Define a port range in which to bind sockets used to
- send and receive RADIUS packets. Must be at least
- RADIUS_FDS (64) wide. Simplifies firewalling of RADIUS
- ports (default: dynamically assigned).
-
-
-
-
-
- radius_dae_port (short)
-
-
- Port for DAE RADIUS (Packet of Death/Disconnect, Change
- of Authorization) requests (default:
- 3799).
-
-
-
-
-
- allow_duplicate_users (boolean)
-
-
- Allow multiple logins with the same username. If false
- (the default), any prior session with the same username
- will be dropped when a new session is established.
-
-
-
-
-
- guest_account (string)
-
-
- Allow multiple logins matching this specific username.
-
-
-
-
-
- bind_address (ip address)
-
-
- When the tun interface is created, it is assigned the
- address specified here. If no address is given, 1.1.1.1
- is used. Packets containing user traffic should be
- routed via this address if given, otherwise the primary
- address of the machine.
-
-
-
-
-
- peer_address (ip address)
-
- Address to send to clients as the default gateway.
-
-
-
-
- send_garp (boolean)
-
-
- Determines whether or not to send a gratuitous ARP for
- the bind_address when the server is ready to handle
- traffic (default: true). This value
- is ignored if BGP is configured.
-
-
-
-
-
- throttle_speed (int)
-
-
- Sets the default speed (in kbits/s) which sessions will
- be limited to. If this is set to 0, then throttling
- will not be used at all. Note: You can set this by the
- CLI, but changes will not affect currently connected
- users.
-
-
-
-
-
- throttle_buckets (int)
-
-
- Number of token buckets to allocate for throttling.
- Each throttled session requires two buckets (in and
- out).
-
-
-
-
-
- accounting_dir (string)
-
-
- If set to a directory, then every 5 minutes the current
- usage for every connected use will be dumped to a file
- in this directory. Each file dumped begins with a
- header, where each line is prefixed by #.
- Following the header is a single line for every
- connected user, fields separated by a space.
-
-
-
- The fields are username, ip, qos, uptxoctets,
- downrxoctets. The qos field is 1 if a standard user,
- and 2 if the user is throttled.
-
-
-
-
-
- dump_speed (boolean)
-
-
- If set to true, then the current bandwidth utilization
- will be logged every second. Even if this is disabled,
- you can see this information by running the
- uptime command on the CLI.
-
-
-
-
-
- multi_read_count (int)
-
-
- Number of packets to read off each of the UDP and TUN
- fds when returned as readable by select (default: 10).
- Avoids incurring the unnecessary system call overhead of
- select on busy servers.
-
-
-
-
-
- scheduler_fifo (boolean)
-
-
- Sets the scheduling policy for the
- l2tpns process to
- SCHED_FIFO. This causes the kernel
- to immediately preempt any currently running
- SCHED_OTHER (normal) process in
- favour of l2tpns when it becomes
- runnable. Ignored on uniprocessor systems.
-
-
-
-
-
- lock_pages (boolean)
-
-
- Keep all pages mapped by the l2tpns
- process in memory.
-
-
-
-
-
- icmp_rate (int)
-
-
- Maximum number of host unreachable ICMP packets to send
- per second.
-
-
-
-
-
- packet_limit (int)
-
-
- Maximum number of packets of downstream traffic to be
- handled each tenth of a second per session. If zero, no
- limit is applied (default: 0). Intended as a DoS
- prevention mechanism and not a general throttling
- control (packets are dropped, not queued).
-
-
-
-
-
- cluster_address (ip address)
-
-
- Multicast cluster address (default: 239.192.13.13).
- See for more information.
-
-
-
-
-
- cluster_port (udp port)
-
-
- UDP cluster port (default: 32792).
- See for more information.
-
-
-
-
-
- cluster_interface (string)
-
- Interface for cluster packets (default: eth0)
-
-
-
-
- cluster_mcast_ttl (int)
-
- TTL for multicast packets (default: 1).
-
-
-
-
- cluster_hb_interval (int)
-
-
- Interval in tenths of a second between cluster
- heartbeat/pings.
-
-
-
-
-
- cluster_hb_timeout (int)
-
-
- Cluster heartbeat timeout in tenths of a second. A new
- master will be elected when this interval has been
- passed without seeing a heartbeat from the master.
-
-
-
-
-
- cluster_master_min_adv (int)
-
-
- Determines the minimum number of up to date slaves
- required before the master will drop routes (default: 1).
-
-
-
-
-
- ipv6_prefix (ipv6 address)
-
-
- Enable negotiation of IPv6. This forms the the first 64
- bits of the client allocated address. The remaining 64
- come from the allocated IPv4 address and 4 bytes of 0s.
-
-
-
-
-
-
- BGP
-
- BGP routing configuration is entered by the command:
- router bgp as
- where as specifies the local AS
- number.
-
-
-
- Subsequent lines prefixed with
- neighbour peer
- define the attributes of BGP neighhbours. Valid commands
- are:
-
-neighbour peer remote-as as
-neighbour peer timers keepalive hold
-
-
-
-
- Where peer specifies the BGP
- neighbour as either a hostname or IP address,
- as is the remote AS number and
- keepalive,
- hold are the timer values in
- seconds.
-
-
-
-
- Access Lists
-
- Named access-lists are configured using one of the commands:
-
-ip access-list standard name
-ip access-list extended name
-
-
-
-
- Subsequent lines prefixed with permit or
- deny define the body of the access-list.
- Standard access-list syntax:
-
-
-
- {permit|deny}
- {host|source
- source-wildcard|any}
- [{host|destination
- destination-wildcard|any}]
-
-
- Extended access-lists:
-
- {permit|deny}
- ip
- {host|source
- source-wildcard|any}
- {host|destination
- destination-wildcard|any}
- [fragments]
-
-
-
- {permit|deny}
- udp
- {host|source
- source-wildcard|any}
- [{eq|neq|gt|lt}
- port|range
- from
- to]
- {host|destination
- destination-wildcard|any}
- [{eq|neq|gt|lt}
- port|range
- from
- to]
- [fragments]
-
-
-
- {permit|deny}
- tcp
- {host|source
- source-wildcard|any}
- [{eq|neq|gt|lt}
- port|range
- from
- to]
- {host|destination
- destination-wildcard|any}
- [{eq|neq|gt|lt}
- port|range
- from
- to]
- [{established|{match-any|match-all}
- {+|-}{fin|syn|rst|psh|ack|urg}
- ...|fragments]
-
-
-
-
-
- <filename>users</filename>
-
- Usernames and passwords for the command-line interface are
- stored in this file. The format is
-
-username:password
-
- where password may either by plain
- text, an MD5 digest (prefixed by
- $1salt$)
- or a DES password, distinguished from plain text by the prefix
- {crypt}.
-
-
-
- The username enable has a special meaning
- and is used to set the enable password.
-
-
-
-
- If this file doesn't exist, then anyone who can get to port
- 23 will be allowed access without a username or password.
-
-
-
-
-
- <filename>ip_pool</filename>
-
- This file is used to configure the IP address pool which user
- addresses are assigned from. This file should contain either
- an IP address or a CIDR network per line. e.g.:
-
-
-192.168.1.1
-192.168.1.2
-192.168.1.3
-192.168.4.0/24
-172.16.0.0/16
-10.0.0.0/8
-
-
-
-
- Keep in mind that l2tpns can only handle
- 65535 connections per process, so don't put more than 65535 IP
- addresses in the configuration file. They will be
- wasted.
-
-
-
-
- <filename>build-garden</filename>
-
- The garden plugin on startup creates a NAT table called
- "garden" then sources the build-garden
- script to populate that table. All packets from gardened
- users will be sent through this table. Example:
-
-
-iptables -t nat -A garden -p tcp -m tcp --dport 25 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p udp -m udp --dport 53 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p tcp -m tcp --dport 53 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p tcp -m tcp --dport 80 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p tcp -m tcp --dport 110 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p tcp -m tcp --dport 443 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p icmp -m icmp --icmp-type echo-request -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p icmp -j ACCEPT
-iptables -t nat -A garden -j DROP
-
-
-
-
-
-
- Operation
-
- A running l2tpns process can be controlled in a number of ways.
- The primary method of control is by the Command-Line Interface
- (CLI).
-
-
-
- You can also remotely send commands to modules via the
- nsctl client provided.
-
-
-
- There are also a number of signals that l2tpns understands and
- takes action when it receives them.
-
-
-
- Command-Line Interface
-
- You can access the command line interface by telneting to port
- 23. There is no IP address restriction, so it's a good idea
- to firewall this port off from anyone who doesn't need access
- to it. See for information on
- restricting access based on a username and password.
-
-
-
- The CLI gives you real-time control over almost everything in
- the process. The interface is designed to look like a Cisco
- device, and supports things like command history, line editing
- and context sensitive help. This is provided by linking with
- the
- libcli library. Some general documentation of the
- interface is
- here.
-
-
-
- After you have connected to the telnet port (and perhaps
- logged in), you will be presented with a
- hostname>
- prompt.
-
-
-
- Enter help to get a list of possible
- commands, or press ? for
- context-specific help.
-
-
-
- A brief overview of the more important commands
- follows:
-
-
-
-
- show session [ID]
-
-
-
-
-
- Detailed information for a specific session is
- presented if you specify a session
- ID argument.
-
-
-
- If no ID is given, a
- summary of all connected sessions is produced. Note
- that this summary list can be around 185 columns wide,
- so you should probably use a wide
- terminal.
-
-
-
- The columns listed in the summary are:
-
-
-
-
-
-
-
-
- SID
- Session ID
-
-
- TID
- Tunnel ID
-
- See also the CLI
- command.
-
-
-
- Username
-
- The username given in the PPP authentication.
-
-
- If this is *, then LCP authentication has
- not completed.
-
-
-
- IP
- The IP address given to the session.
-
- If this is 0.0.0.0, IPCP negotiation has not
- completed
-
-
-
- I
- Intercept
-
- Y or N: indicates whether the session is
- being snooped. See also the
-
- CLI command.
-
-
-
- T
- Throttled
-
- Y or N: indicates whether the session is
- currently throttled. See also the
-
- CLI command.
-
-
-
- G
- Walled Garden
-
- Y or N: indicates whether the user is
- trapped in the walled garden. This field is
- present even if the garden module is not
- loaded.
-
-
-
- 6
- IPv6
-
- Y or N: indicates whether the session has
- IPv6 active (IPV6CP open)
-
-
-
- opened
-
- The number of seconds since the
- session started
-
-
-
- downloaded
-
- Number of bytes downloaded by the user
-
-
-
- uploaded
-
- Number of bytes uploaded by the user
-
-
-
- idle
-
- The number of seconds since traffic was
- detected on the session
-
-
-
- LAC
-
- The IP address of the LAC the session is
- connected to.
-
-
-
- CLI
-
- The Calling-Line-Identification field
- provided during the session setup. This
- field is generated by the LAC.
-
-
-
-
-
-
-
-
-
-
-
- show users
-
-
- show user username
-
-
-
-
-
- With no arguments, display a list of currently
- connected users. If an argument is given, the session
- details for the given
- username are displayed.
-
-
-
-
-
-
- show tunnel [ID]
-
-
-
-
- Produce a summary list of all open tunnels, or detail
- on a specific tunnel ID.
-
-
-
- The columns listed in the summary are:
-
-
-
-
-
- TID
- Tunnel ID
-
-
- Hostname
-
- The hostname for the tunnel as provided by
- the LAC. This has no relation to DNS, it is
- just a text field.
-
-
-
- IP
- The IP address of the LAC
-
-
- State
-
- Tunnel state: Free, Open, Dieing, Opening
-
-
-
- Sessions
- The number of open sessions on the tunnel
-
-
-
-
-
-
-
-
-
- show pool
-
-
- Displays the current IP address pool allocation. This
- will only display addresses that are in use, or are
- reserved for re-allocation to a disconnected user.
-
-
-
- If an address is not currently in use, but has been
- used, then in the User column the username will be
- shown in square brackets, followed by the time since
- the address was used:
-
-
-IP Address Used Session User
-192.168.100.6 N [joe.user] 1548s
-
-
-
-
-
-
- show radius
-
-
- Show a summary of the in-use RADIUS sessions. This
- list should not be very long, as RADIUS sessions
- should be cleaned up as soon as they are used. The
- columns listed are:
-
-
-
-
-
- Radius
-
- The ID of the RADIUS request. This is sent
- in the packet to the RADIUS server for
- identification
-
-
-
- State
-
- The state of the request: WAIT, CHAP, AUTH,
- IPCP, START, STOP or NULL
-
-
-
- Session
-
- The session ID that this RADIUS request is
- associated with
-
-
-
- Retry
-
- If a response does not appear to the
- request, it will retry at this time. This
- is a Unix timestamp
-
-
-
- Try
-
- Retry count. The RADIUS request is
- discarded after 3 retries
-
-
-
-
-
-
-
-
-
-
- show running-config
-
-
- This will list the current running configuration.
- This is in a format that can either be pasted into the
- configuration file, or run directly at the command
- line.
-
-
-
-
-
- show counters
-
-
- Internally, counters are kept of key values, such as
- bytes and packets transferred, as well as function
- call counters. This function displays all these
- counters, and is probably only useful for debugging.
-
-
-
- You can reset these counters by running
- clear counters.
-
-
-
-
-
- show cluster
-
-
- Show cluster status. Shows the cluster state for this
- server (Master/Slave), information about known peers
- and (for slaves) the master IP address, last packet
- seen and up-to-date status. See
- for more information.
-
-
-
-
-
- write memory
-
-
- This will write the current running configuration to
- the config file startup-config,
- which will be run on a restart.
-
-
-
-
-
-
- snoop user
- IP
- port
-
-
-
- You must specify a username, IP address and port. All
- packets for the current session for that username will
- be forwarded to the given host/port. Specify
- no snoop
- username to
- disable interception for the session.
-
-
-
- If you want interception to be permanent, you will
- have to modify the RADIUS response for the user. See
- .
-
-
-
-
-
-
- throttle user
- [in|out] rate
-
-
-
- You must specify a username, which will be throttled
- for the current session to
- rate Kbps. Prefix
- rate with
- in or
- out to set different upstream
- and downstream rates.
-
-
-
- Specify no throttle
- username to
- disable throttling for the current session.
-
-
-
- If you want throttling to be permanent, you will have
- to modify the RADIUS response for the user. See .
-
-
-
-
-
-
- drop session
-
-
-
- This will cleanly disconnect the session specified by
- session ID.
-
-
-
-
-
-
- drop tunnel
-
-
-
- This will cleanly disconnect the tunnel specified by
- tunnel ID, as well as all
- sessions on that tunnel.
-
-
-
-
-
- uptime
-
-
- This will show how long the l2tpns
- process has been running, and the current bandwidth
- utilization:
-
-
-17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16
-Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569
-
-
- The bandwidth line contains 4 sets of values:
-
-
-
-
-
- UDP-ETH
-
- The current bandwidth going from the LAC to
- the ethernet (user uploads), in mbits/sec.
-
-
-
- ETH-UDP
-
- The current bandwidth going from ethernet to
- the LAC (user downloads).
-
-
-
- TOTAL
- The total aggregate bandwidth in mbits/s.
-
-
- IN and OUT
-
- Packets/per-second going between UDP-ETH and
- ETH-UDP.
-
-
-
-
-
-
- These counters are updated every second.
-
-
-
-
-
- configure terminal
-
-
- Enter configuration mode. Use
- exit or
- ^Z to exit this mode.
-
-
-
- The following commands are valid in this mode:
-
-
-
-
- load plugin
- name
-
-
-
- Load a plugin. You must specify the plugin
- name, and it will search in
- /usr/lib/l2tpns for
- name.so.
- You can unload a loaded plugin with
- remove plugin
- name.
-
-
-
-
-
- set ...
-
-
- Set a configuration variable. You must specify
- the variable name, and the value. If the value
- contains any spaces, you should quote the value
- with double (") or single (') quotes.
-
-
-
- You can set any configuration value in this
- way, although some may require a restart to
- take effect. See .
-
-
-
-
-
- router bgp ...
-
-
- Configure BGP. See .
-
-
-
-
-
- ip access-list ...
-
-
- Configure a named access list. See .
-
-
-
-
-
-
-
-
-
-
-
-
- nsctl
-
- nsctl sends messages to a running
- l2tpns instance to be control plugins.
-
-
-
- Arguments are command and optional
- args. See
- nsctl(8).
-
-
-
- Built-in command are load_plugin,
- unload_plugin and
- help. Any other commands are passed to
- plugins for processing by the
- plugin_control function.
-
-
-
-
- Signals
-
- While the process is running, you can send it a few different
- signals, using the kill command.
-
-
-killall -HUP l2tpns
-
-
- The signals understood are:
-
-
-
- SIGHUP
-
- Reload the config from disk and re-open log file.
-
-
-
-
- SIGTERM
- SIGINT
-
-
- Stop process. Tunnels and sessions are not
- terminated. This signal should be used to stop
- l2tpns on a cluster node where
- there are other machines to continue handling traffic.
- See
-
-
-
-
-
- SIGQUIT
-
-
- Shut down tunnels and sessions, exit process when
- complete.
-
-
-
-
-
-
-
-
-
- Throttling
-
- l2tpns contains support for slowing down user
- sessions to whatever speed you desire. The global setting
- throttle_speed defines the default throttle
- rate.
-
-
-
- To throttle a sesion permanently, add a
- Cisco-AVPair RADIUS attribute. The
- autothrotle module interprets the following
- attributes:
-
-
-
-
-
- throttle=yes
-
- Throttle upstream/downstream traffic to the configured
- throttle_speed.
-
-
-
-
-
- throttle=rate
-
-
- Throttle upstream/downstream traffic to the specified
- rate Kbps.
-
-
-
-
-
- lcp:interface-config#1=service-policy input
- rate
-
-
-
- Alternate (Cisco) format: throttle
- upstream/downstream to specified
- rate Kbps.
-
-
-
-
-
- lcp:interface-config#2=service-policy output
- rate
-
-
-
-
-
-
-
-
- You can also enable and disable throttling an active session
- using the CLI command.
-
-
-
-
- Interception
-
- You may have to deal with legal requirements to be able to
- intercept a user's traffic at any time.
- l2tpns allows you to begin and end
- interception on the fly, as well as at authentication time.
-
-
-
- When a user is being intercepted, a copy of every packet they
- send and receive will be sent wrapped in a UDP packet to a
- specified host.
-
-
-
- The UDP packet contains just the raw IP frame, with no extra
- headers. The script scripts/l2tpns-capture
- may be used as the end-point for such intercepts, writing the
- data in PCAP format (suitable for inspection with
- tcpdump).
-
-
-
- To enable or disable interception of a connected user, use the
- and no
- snoop CLI commands. These will enable interception
- immediately.
-
-
-
- If you wish the user to be intercepted whenever they reconnect,
- you will need to modify the RADIUS response to include the
- Vendor-Specific value
- Cisco-AVPair="intercept=ip:port".
- For this feature to be enabled, you need to have the
- autosnoop module loaded.
-
-
-
-
- Plugins
-
- So as to make l2tpns as flexible as possible,
- a plugin API is include which you can use to hook into certain
- events.
-
-
-
- There are a some standard modules included which may be used as
- examples: autosnoop,
- autothrottle, garden,
- sessionctl,
- setrxspeed, snoopctl,
- stripdomain and
- throttlectl.
-
-
-
- When an event occurs that has a hook, l2tpns
- looks for a predefined function name in every loaded module, and
- runs them in the order the modules were loaded.
-
-
-
- The function should return PLUGIN_RET_OK if it is
- all OK. If it returns PLUGIN_RET_STOP, then it is
- assumed to have worked, but that no further modules should be
- run for this event.
-
-
-
- A return of PLUGIN_RET_ERROR means that this module
- failed, and no further processing should be done for this event.
- Use this with care.
-
-
-
- Most event functions take a specific structure named
- param_event, which
- varies in content with each event. The function name for each
- event will be
- plugin_event, so for the
- event timer, the function declaration
- should look like:
-
-
-int plugin_timer(struct param_timer *data);
-
-
- A list of the available events follows, with a list of all the
- fields in the supplied structure:
-
-
-
-
-
-
-
-
-
-
- Event
- Description
- Arguments
-
-
-
-
-
- plugin_init
-
-
- Called when the plugin is loaded. A pointer to a
- struct containing function pointers is passed as the
- only argument, allowing the plugin to call back into
- the main code.
-
-
- Prior to loading the plugin, l2tpns
- checks the API version the plugin was compiled
- against. All plugins should contain:
-
-int plugin_api_version = PLUGIN_API_VERSION;
-
-
-
- struct pluginfuncs *
-
-
-
- See pluginfuncs structure in
- plugin.h for available functions.
-
-
-
-
- plugin_done
-
- Called when the plugin is unloaded or
- l2tpns is shutdown.
-
- void
-
-
- No arguments.
-
-
-
- plugin_pre_auth
-
- Called after a RADIUS response has been received, but
- before it has been processed by the code. This will
- allow you to modify the response in some way.
-
-
- struct plugin param_pre_auth *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
- char *username
- User name.
-
-
- char *password
- Password.
-
-
- int protocol
-
- Authentication protocol: 0xC023 for PAP,
- 0xC223 for CHAP.
-
-
-
- int continue_auth
- Set to 0 to stop processing authentication modules.
-
-
-
- plugin_post_auth
-
- Called after a RADIUS response has been received, and
- the basic checks have been performed. This is what
- the garden module uses to force
- authentication to be accepted.
-
-
- struct plugin param_post_auth *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
- char *username
- User name.
-
-
- short auth_allowed
-
- Initially true or false depending on whether
- authentication has been allowed so far. You can
- set this to 1 or 0 to force authentication to be
- accepted or rejected.
-
-
-
- int protocol
-
- Authentication protocol: 0xC023 for PAP,
- 0xC223 for CHAP.
-
-
-
-
- plugin_timer
-
- Run once per second.
-
-
- struct plugin param_timer *
-
-
-
- time_t time_now
- The current unix timestamp.
-
-
-
- plugin_new_session
-
- Called after a session is fully set up. The session
- is now ready to handle traffic.
-
-
- struct plugin param_new_session *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
-
- plugin_kill_session
-
- Called when a session is about to be shut down. This
- may be called multiple times for the same session.
-
-
- struct plugin param_kill_session *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
-
- plugin_control
-
-
- Called in whenever a nsctl packet
- is received. This should handle the packet and form a
- response if required.
-
-
- Plugin-specific help strings may be included in the
- output of nsctl help by
- defining a NULL terminated list of
- strings as follows:
-
-char *plugin_control_help[] = { ..., NULL };
-
-
-
-
- struct plugin param_control *
-
-
-
- int iam_master
- If true, this node is the cluster master.
-
-
- int argc
- nsctl arguments.
-
-
- char **argc
-
-
- int response
-
- Response from control message (if handled): should be
- either NSCTL_RES_OK or
- NSCTL_RES_ERR.
-
-
-
- char *additional
-
- Additional information, output by
- nsctl on receiving the response.
-
-
-
-
- plugin_radius_response
-
- Called whenever a RADIUS response includes a
- Cisco-AVPair value. The value is
- split into
- key=value
- pairs. Will be called once for each pair in the
- response.
-
-
- struct plugin param_radius_response *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
- char *key
- Key and value.
-
-
- char *value
-
-
-
- plugin_radius_reset
-
- Called whenever a RADIUS CoA request is received to
- reset any options to default values before the new
- values are applied.
-
-
- struct param_radius_reset *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
-
- plugin_radius_account
-
- Called when preparing a RADIUS accounting record to
- allow additional data to be added to the packet.
-
-
- struct param_radius_account *
-
-
-
- tunnelt *t
- Tunnel.
-
-
- sessiont *s
- Session.
-
-
- uint8_t **packet
-
- Pointer to the end of the currently assembled
- packet buffer. The value should be incremented by the
- length of any data added.
-
-
-
-
- plugin_become_master
-
- Called when a node elects itself cluster master.
-
- void
-
-
- No arguments.
-
-
-
- plugin_new_session_master
-
- Called once for each open session on becoming cluster
- master.
-
- sessiont *
-
-
-
- Session.
-
-
-
-
-
-
-
-
-
- Walled Garden
-
- A "Walled Garden" is implemented so that you can provide perhaps
- limited service to sessions that incorrectly authenticate.
-
-
-
- Whenever a session provides incorrect authentication, and the
- RADIUS server responds with Auth-Reject, the walled garden
- module (if loaded) will force authentication to succeed, but set
- the walled_garden flag in the session
- structure, and adds an iptables rule to the
- garden_users chain to cause all packets for
- the session to traverse the garden chain.
-
-
-
- This doesn't just work. To set this all
- up, you will to setup the garden nat table
- with the script with rules
- to limit user's traffic.
-
-
-
- For example, to force all traffic except DNS to be forwarded to
- 192.168.1.1, add these entries to your
- build-garden script:
-
-
-iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
-iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
-
-
-
-
- l2tpns will add entries to the
- garden_users chain as appropriate.
-
-
-
- You can check the amount of traffic being captured using the
- following command:
-
-
-iptables -t nat -L garden -nvx
-
-
-
-
-
- Filtering
-
- Sessions may be filtered by specifying
- Filter-Id attributes in the RADIUS reply.
- filter.in
- specifies that the named access-list
- filter should be applied to traffic
- from the customer,
- filter.out
- specifies a list for traffic to the customer.
-
-
-
-
- Clustering
-
- An l2tpns cluster consists of one* or more
- servers configured with the same configuration, notably the
- multicast cluster_address and the
- cluster_port
-
-
- *A stand-alone server is simply a degraded cluster.
-
-
- Initially servers come up as cluster slaves, and periodically
- (every cluster_hb_interval/10 seconds) send
- out ping packets containing the start time of the process to the
- multicast cluster_address on
- cluster_port.
-
-
-
- A cluster master sends heartbeat rather than ping packets, which
- contain those session and tunnel changes since the last
- heartbeat.
-
-
-
- When a slave has not seen a heartbeat within
- cluster_hb_timeout/10 seconds it "elects" a
- new master by examining the list of peers it has seen pings from
- and determines which of these and itself is the "best" candidate
- to be master. "Best" in this context means the server with the
- highest uptime (the highest IP address is used as a tie-breaker
- in the case of equal uptimes).
-
-
-
- After discovering a master, and determining that it is
- up-to-date (has seen an update for all in-use sessions and
- tunnels from heartbeat packets) will raise a route (see ) for the bind_address and
- for all addresses/networks in ip_pool.
-
-
-
- Any packets recieved by the slave which would alter the session
- state, as well as packets for throttled or gardened sessions are
- forwarded to the master for handling. In addition, byte
- counters for session traffic are periodically forwarded.
-
-
-
- The master, when determining that it has at least one* up-to-date
- slave will drop all routes (raising them again if all slaves
- disappear) and subsequently handle only packets forwarded to it
- by the slaves.
-
-
- *Configurable with cluster_master_min_adv
-
-
- Multiple clusters can be run on the same network by just using different
- multicast cluster_address. However, for a given host to
- be part of multiple clusters without mixing the clusters,
- cluster_port must be different for each cluster.
-
-
-
-
- Routing
-
- If you are running a single instance, you may simply statically
- route the IP pools to the bind_address
- (l2tpns will send a gratuitous arp).
-
-
-
- For a cluster, configure the members as BGP neighbours on your
- router and configure multi-path load-balancing. Cisco uses
- maximum-paths ibgp for IBGP. If this is
- not supported by your IOS revision, you can use
- maximum-paths (which works for EBGP) and
- set as_number to a private value such as
- 64512.
-
-
-
diff --git a/Docs/nsctl.8 b/Docs/nsctl.8
deleted file mode 100644
index e56198d..0000000
--- a/Docs/nsctl.8
+++ /dev/null
@@ -1,69 +0,0 @@
-.\" -*- nroff -*-
-.de Id
-.ds Dt \\$4 \\$5
-..
-.Id $Id: nsctl.8,v 1.2 2004-11-17 15:08:19 bodea Exp $
-.TH NSCTL 8 "\*(Dt" L2TPNS "System Management Commands"
-.SH NAME
-nsctl \- manage running l2tpns instance
-.SH SYNOPSIS
-.B nsctl
-.RB [ \-d ]
-.RB [ \-h
-.IR host [: port ]]
-.RB [ \-t
-.IR timeout ]
-.I command
-.RI [ arg " ...]"
-.SH DESCRIPTION
-.B nsctl
-sends commands to a running
-.B l2tpns
-process. It provides both for the loading or unloading of plugins and
-also the management of sessions via functions provided by those plugins.
-.SH OPTIONS
-.TP
-.B \-d
-Enable debugging output.
-.TP
-.B \-h \fIhost\fR[:\fIport\fR]
-The host running
-.B l2tpns
-that should receive the message. By default the message is sent to
-UDP port 1702 on
-.BR localhost .
-.TP
-.B \-t \fItimeout\fR
-Timeout in seconds to wait for a response from the server.
-.SH COMMANDS
-The first argument specifies the command to send to
-.B l2tpns .
-The following commands are as defined:
-.TP
-.BI "load_plugin " plugin
-Load the named
-.IR plugin .
-.TP
-.BI "unload_plugin " plugin
-Unload the named
-.IR plugin .
-.TP
-.B help
-Each loaded plugin is queried for what commands it supports and the
-synopsis for each is output.
-.PP
-Any other value of
-.I command
-(and
-.I args
-if any)
-are sent to
-.B l2tpns
-as-is, to be passed to each plugin which registers a
-.B plugin_control
-function in turn (in which it may be acted upon).
-.SH SEE ALSO
-.BR l2tpns (8)
-.SH AUTHOR
-This manual page was written by Jonathan McDowell ,
-for the Debian GNU/Linux system (but may be used by others).
diff --git a/Docs/startup-config.5 b/Docs/startup-config.5
deleted file mode 100644
index 5e029d6..0000000
--- a/Docs/startup-config.5
+++ /dev/null
@@ -1,511 +0,0 @@
-.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-. ds C`
-. ds C'
-'br\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.\"
-.\" Avoid warning from groff about undefined register 'F'.
-.de IX
-..
-.nr rF 0
-.if \n(.g .if rF .nr rF 1
-.if (\n(rF:(\n(.g==0)) \{
-. if \nF \{
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. if !\nF==2 \{
-. nr % 0
-. nr F 2
-. \}
-. \}
-.\}
-.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "STARTUP-CONFIG"
-.TH STARTUP-CONFIG 5 "2017-05-26" "perl v5.20.2" "User Contributed Perl Documentation"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
-.SH "NAME"
-startup\-config \- configuration file for l2tpns
-.SH "SYNOPSIS"
-.IX Header "SYNOPSIS"
-/etc/l2tpns/startup\-config
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-\&\fBstartup-config\fR is the configuration file for \fBl2tpns\fR
-.PP
-The format is plain text, in the same format as accepted by
-the configuration mode of l2tpns's telnet administrative
-interface. Comments are indicated by either the character # or !.
-.SS "\s-1SETTINGS\s0"
-.IX Subsection "SETTINGS"
-Settings are specified with
-.IP "\fBset\fR \fIvariable\fR \fIvalue\fR" 4
-.IX Item "set variable value"
-.PP
-A list of the possible configuration directives follows. Each of these should be set by a line like:
-.ie n .IP "\fBset\fR \fIconfigstring\fR \fI""value""\fR" 4
-.el .IP "\fBset\fR \fIconfigstring\fR \fI``value''\fR" 4
-.IX Item "set configstring value"
-.PD 0
-.IP "\fBset\fR \fIipaddress\fR \fI192.168.1.1\fR" 4
-.IX Item "set ipaddress 192.168.1.1"
-.IP "\fBset\fR \fIboolean\fR \fItrue\fR" 4
-.IX Item "set boolean true"
-.PD
-.PP
-The following \fIvariables\fR may be set:
-.IP "\fBaccounting_dir\fR (string)" 4
-.IX Item "accounting_dir (string)"
-If set to a directory, then every 5 minutes the current usage for every connected use will be dumped to a file in this directory. Each file dumped begins with a header, where each line is prefixed by #. Following the header is a single line for every connected user, fields separated by a space.
-.Sp
-The fields are username, ip, qos, uptxoctets, downrxoctets, origin (optional). The qos field is 1 if a standard user, and 2 if the user is throttled. The origin field is dump if \fBaccount_all_origin\fR is set to true (origin value: L=LAC data, R=Remote \s-1LNS\s0 data, P=PPPOE data).
-.IP "\fBaccount_all_origin\fR (boolean)" 4
-.IX Item "account_all_origin (boolean)"
-If set to true, all origin of the usage is dumped to the accounting file (LAC+Remote \s-1LNS+PPPOE\s0)(default false).
-.IP "\fBallow_duplicate_users\fR (boolean)" 4
-.IX Item "allow_duplicate_users (boolean)"
-Allow multiple logins with the same username. If false (the default), any prior session with the same username will be dropped when a new session is established.
-.IP "\fBauth_tunnel_change_addr_src\fR (boolean)" 4
-.IX Item "auth_tunnel_change_addr_src (boolean)"
-This parameter authorize to change the source \s-1IP\s0 of the tunnels l2tp. This parameter can be used when the remotes \s-1BAS/LAC\s0 are l2tpns server configured in cluster mode, but that the interface to remote \s-1LNS\s0 are not clustered (the tunnel can be coming from different source \s-1IP\s0) (default: no).
-.IP "\fBbind_address\fR (ip address)" 4
-.IX Item "bind_address (ip address)"
-It's the listen address of the l2tp udp protocol sent and received to \s-1LAC.\s0 This address is also assigned to the tun interface if no iftun_address is specified. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
-.IP "\fBbind_multi_address\fR (ip address)" 4
-.IX Item "bind_multi_address (ip address)"
-This parameter permit on to listen several address of the l2tp udp protocol (and set several address to the tun interface).
-.Sp
-\&\s-1WHEN\s0 this parameter is set, It \s-1OVERWRITE\s0 the parameters \*(L"bind_address\*(R" and \*(L"iftun_address\*(R".
-.Sp
-these can be interesting when you want do load-balancing in cluster mode of the uploaded from the \s-1LAC.\s0 For example you can set a bgp.prepend(\s-1MY_AS\s0) for Address1 on \s-1LNS1\s0 and a bgp.prepend(\s-1MY_AS\s0) for Address2 on \s-1LNS2 \s0(see \s-1BGP\s0 AS-path prepending).
-.Sp
-example of use with 2 address:
-.Sp
-\&\fBset\fR \fIbind_multi_address\fR \*(L"64.14.13.41, 64.14.13.42\*(R"
-.IP "\fBcluster_address\fR (ip address)" 4
-.IX Item "cluster_address (ip address)"
-Multicast cluster address (default: 239.192.13.13). See the section on Clustering for more information.
-.IP "\fBBcluster_port\fR (int)" 4
-.IX Item "Bcluster_port (int)"
-\&\s-1UDP\s0 cluster port (default: 32792). See the section on Clustering for more information.
-.IP "\fBcluster_interface\fR (string)" 4
-.IX Item "cluster_interface (string)"
-Interface for cluster packets (default: eth0).
-.IP "\fBcluster_mcast_ttl\fR (int)" 4
-.IX Item "cluster_mcast_ttl (int)"
-\&\s-1TTL\s0 for multicast packets (default: 1).
-.IP "\fBcluster_hb_interval\fR (int)" 4
-.IX Item "cluster_hb_interval (int)"
-Interval in tenths of a second between cluster heartbeat/pings.
-.IP "\fBcluster_hb_timeout\fR (int)" 4
-.IX Item "cluster_hb_timeout (int)"
-Cluster heartbeat timeout in tenths of a second. A new master will be elected when this interval has been passed without seeing a heartbeat from the master.
-.IP "\fBcluster_master_min_adv\fR (int)" 4
-.IX Item "cluster_master_min_adv (int)"
-Determines the minimum number of up to date slaves required before the master will drop routes (default: 1).
-.IP "\fBdebug\fR (int)" 4
-.IX Item "debug (int)"
-Set the level of debugging messages written to the log file. The value should
-be between 0 and 5, with 0 being no debugging, and 5 being the highest.
-A rough description of the levels is:
-.RS 4
-.IP "0. Critical Errors \- Things are probably broken" 4
-.IX Item "0. Critical Errors - Things are probably broken"
-.PD 0
-.IP "1. Errors \- Things might have gone wrong, but probably will recover" 4
-.IX Item "1. Errors - Things might have gone wrong, but probably will recover"
-.IP "2. Warnings \- Just in case you care what is not quite perfect" 4
-.IX Item "2. Warnings - Just in case you care what is not quite perfect"
-.IP "3. Information \- Parameters of control packets" 4
-.IX Item "3. Information - Parameters of control packets"
-.IP "4. Calls \- For tracing the execution of the code" 4
-.IX Item "4. Calls - For tracing the execution of the code"
-.IP "5. Packets \- Everything, including a hex dump of all packets processed... probably twice" 4
-.IX Item "5. Packets - Everything, including a hex dump of all packets processed... probably twice"
-.RE
-.RS 4
-.PD
-.Sp
-Note that the higher you set the debugging level, the slower the program will run. Also, at level 5 a \s-1LOT\s0 of information will be logged. This should only ever be used for working out why it doesn't work at all.
-.RE
-.IP "\fBdump_speed\fR (boolean)" 4
-.IX Item "dump_speed (boolean)"
-If set to true, then the current bandwidth utilization will be logged every second. Even if this is disabled, you can see this information by running the uptime command on the \s-1CLI.\s0
-.IP "\fBdisable_sending_hello\fR (boolean)" 4
-.IX Item "disable_sending_hello (boolean)"
-Disable l2tp sending \s-1HELLO\s0 message for Apple compatibility. Some \s-1OS X\s0 implementation of l2tp no manage the L2TP \*(L"\s-1HELLO\s0 message\*(R". (default: no).
-.IP "\fBecho_timeout\fR (int)" 4
-.IX Item "echo_timeout (int)"
-Time between last packet sent and \s-1LCP ECHO\s0 generation (default: 10 (seconds)).
-.IP "\fBguest_account\fR" 4
-.IX Item "guest_account"
-Allow multiple logins matching this specific username.
-.IP "\fBicmp_rate\fR (int)" 4
-.IX Item "icmp_rate (int)"
-Maximum number of host unreachable \s-1ICMP\s0 packets to send per second.
-.IP "\fBidle_echo_timeout\fR (int)" 4
-.IX Item "idle_echo_timeout (int)"
-Drop sessions who have not responded within idle_echo_timeout seconds (default: 240 (seconds))
-.IP "\fBiftun_address\fR (ip address)" 4
-.IX Item "iftun_address (ip address)"
-This parameter is used when you want a tun interface address different from the address of \*(L"bind_address\*(R" (For use in cases of specific configuration). If no address is given to iftun_address and bind_address, 1.1.1.1 is used.
-.IP "\fBl2tp_mtu\fR (int)" 4
-.IX Item "l2tp_mtu (int)"
-\&\s-1MTU\s0 of interface for L2TP traffic (default: 1500). Used to set link \s-1MRU\s0 and adjust \s-1TCP MSS.\s0
-.IP "\fBl2tp_secret\fR (string)" 4
-.IX Item "l2tp_secret (string)"
-The secret used by l2tpns for authenticating tunnel request. Must be the same as the \s-1LAC,\s0 or authentication will fail. Only actually be used if the \s-1LAC\s0 requests authentication.
-.IP "\fBlock_pages\fR (boolean)" 4
-.IX Item "lock_pages (boolean)"
-Keep all pages mapped by the l2tpns process in memory.
-.IP "\fBlog_file\fR (string)" 4
-.IX Item "log_file (string)"
-This will be where all logging and debugging information is written to.This may be either a filename, such as /var/log/l2tpns, or the string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
-.IP "\fBmulti_read_count\fR (int)" 4
-.IX Item "multi_read_count (int)"
-Number of packets to read off each of the \s-1UDP\s0 and \s-1TUN\s0 fds when returned as readable by select (default: 10). Avoids incurring the unnecessary system call overhead of select on busy servers.
-.IP "\fBpacket_limit\fR (int>" 4
-.IX Item "packet_limit (int>"
-Maximum number of packets of downstream traffic to be handled each tenth of a second per session. If zero, no limit is applied (default: 0). Intended as a DoS prevention mechanism and not a general throttling control (packets are dropped, not queued).
-.IP "\fBpeer_address\fR (ip address)" 4
-.IX Item "peer_address (ip address)"
-Address to send to clients as the default gateway.
-.IP "\fBpid_file\fR (string)" 4
-.IX Item "pid_file (string)"
-If set, the process id will be written to the specified file. The value must be an absolute path.
-.IP "\fBppp_keepalive\fR (boolean)" 4
-.IX Item "ppp_keepalive (boolean)"
-Change this value to no to force generation of \s-1LCP ECHO\s0 every echo_timeout seconds, even there are activity on the link (default: yes)
-.IP "\fBppp_restart_time\fR (int)" 4
-.IX Item "ppp_restart_time (int)"
-.PD 0
-.IP "\fBppp_max_configure\fR (int)" 4
-.IX Item "ppp_max_configure (int)"
-.IP "\fBppp_max_failure\fR (int)" 4
-.IX Item "ppp_max_failure (int)"
-.PD
-\&\s-1PPP\s0 counter and timer values, as described in Section 4.1 of \s-1RFC1661.\s0
-.Sp
-\&\fIppp_restart_time\fR, Restart timer for \s-1PPP\s0 protocol negotiation in seconds (default: 3).
-.Sp
-\&\fIppp_max_configure\fR, Number of configure requests to send before giving up (default: 10).
-.Sp
-\&\fIppp_max_failure\fR, Number of Configure-Nak requests to send before sending a Configure-Reject (default: 5).
-.IP "\fBprimary_dns\fR (ip address), \fBsecondary_dns\fR (ip address)" 4
-.IX Item "primary_dns (ip address), secondary_dns (ip address)"
-Whenever a \s-1PPP\s0 connection is established, \s-1DNS\s0 servers will be sent to the user, both a primary and a secondary. If either is set to 0.0.0.0, then that one will not be sent.
-.IP "\fBprimary_radius\fR (ip address), \fBsecondary_radius\fR (ip address)" 4
-.IX Item "primary_radius (ip address), secondary_radius (ip address)"
-Sets the \s-1RADIUS\s0 servers used for both authentication and accounting. If the primary server does not respond, then the secondary \s-1RADIUS\s0 server will be tried.
-.Sp
-Note: in addition to the source \s-1IP\s0 address and identifier, the \s-1RADIUS\s0 server must include the source port when detecting duplicates to suppress (in order to cope with a large number of sessions coming on-line simultaneously l2tpns uses a set of udp sockets, each with a separate identifier).
-.IP "\fBprimary_radius_port\fR (short), \fBsecondary_radius_port\fR (short)" 4
-.IX Item "primary_radius_port (short), secondary_radius_port (short)"
-Sets the authentication ports for the primary and secondary \s-1RADIUS\s0 servers. The accounting port is one more than the authentication port. If no \s-1RADIUS\s0 ports are given, the authentication port defaults to 1645, and the accounting port to 1646.
-.IP "\fBradius_accounting\fR (boolean)" 4
-.IX Item "radius_accounting (boolean)"
-If set to true, then \s-1RADIUS\s0 accounting packets will be sent. This means that a \fBStart\fR record will be sent when the session is successfully authenticated, and a \fBStop\fR record will be sent when the session is closed.
-.IP "\fBradius_interim\fR (int)" 4
-.IX Item "radius_interim (int)"
-If radius_accounting is on, defines the interval between sending of \s-1RADIUS\s0 interim accounting records (in seconds).
-.IP "\fBradius_secret\fR (string)" 4
-.IX Item "radius_secret (string)"
-This secret will be used in all \s-1RADIUS\s0 queries. If this is not set then \s-1RADIUS\s0 queries will fail.
-.IP "\fBradius_authtypes\fR (string)" 4
-.IX Item "radius_authtypes (string)"
-A comma separated list of supported \s-1RADIUS\s0 authentication methods (\*(L"pap\*(R" or \*(L"chap\*(R"), in order of preference (default \*(L"pap\*(R").
-.IP "\fBradius_dae_port\fR (short)" 4
-.IX Item "radius_dae_port (short)"
-Port for \s-1DAE RADIUS \s0(Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
-.IP "\fBradius_bind_min\fR, \fBradius_bind_max\fR (int)" 4
-.IX Item "radius_bind_min, radius_bind_max (int)"
-Define a port range in which to bind sockets used to send and receive \s-1RADIUS\s0 packets. Must be at least \s-1RADIUS_FDS \s0(64) wide. Simplifies firewalling of \s-1RADIUS\s0 ports (default: dynamically assigned).
-.IP "\fBrandom_device\fR (string)" 4
-.IX Item "random_device (string)"
-Path to random data source (default /dev/urandom). Use "" to use the \fIrand()\fR library function.
-.IP "\fBscheduler_fifo\fR (boolean)" 4
-.IX Item "scheduler_fifo (boolean)"
-Sets the scheduling policy for the l2tpns process to \s-1SCHED_FIFO.\s0 This causes the kernel to immediately preempt any currently running \s-1SCHED_OTHER \s0(normal) process in favour of l2tpns when it becomes runnable. Ignored on uniprocessor systems.
-.IP "\fBsend_garp\fR (boolean)" 4
-.IX Item "send_garp (boolean)"
-Determines whether or not to send a gratuitous \s-1ARP\s0 for the bind_address when the server is ready to handle traffic (default: true). This value is ignored if \s-1BGP\s0 is configured.
-.IP "\fBtundevicename\fR (string)" 4
-.IX Item "tundevicename (string)"
-Name of the tun interface (default: \*(L"tun0\*(R").
-.IP "\fBthrottle_speed\fR (int)" 4
-.IX Item "throttle_speed (int)"
-Sets the default speed (in kbits/s) which sessions will be limited to. If this is set to 0, then throttling will not be used at all. Note: You can set this by the \s-1CLI,\s0 but changes will not affect currently connected users.
-.IP "\fBthrottle_buckets\fR (int)" 4
-.IX Item "throttle_buckets (int)"
-Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
-.SS "DHCPv6 And IPv6 \s-1SETTINGS\s0"
-.IX Subsection "DHCPv6 And IPv6 SETTINGS"
-.IP "\fBdhcp6_preferred_lifetime\fR (int)" 4
-.IX Item "dhcp6_preferred_lifetime (int)"
-The preferred lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
-.IP "\fBdhcp6_valid_lifetime\fR (int)" 4
-.IX Item "dhcp6_valid_lifetime (int)"
-The valid lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
-.IP "\fBdhcp6_server_duid\fR (int)" 4
-.IX Item "dhcp6_server_duid (int)"
-\&\s-1DUID\s0 Based on Link-layer Address (DUID-LL) (see rfc3315).
-.IP "\fBprimary_ipv6_dns\fR, \fBsecondary_ipv6_dns\fR (Ipv6 address)" 4
-.IX Item "primary_ipv6_dns, secondary_ipv6_dns (Ipv6 address)"
-IPv6 \s-1DNS\s0 servers will be sent to the user (see rfc3646).
-.IP "\fBdefault_ipv6_domain_list\fR (string)" 4
-.IX Item "default_ipv6_domain_list (string)"
-The Domain Search List (ex: \*(L"fdn.fr\*(R") (see rfc3646).
-.IP "\fBipv6_prefix\fR (Ipv6 address)" 4
-.IX Item "ipv6_prefix (Ipv6 address)"
-Enable negotiation of IPv6. This forms the the first 64 bits of the client allocated address. The remaining 64 come from the allocated IPv4 address and 4 bytes of 0.
-.SS "\s-1LAC SETTINGS\s0"
-.IX Subsection "LAC SETTINGS"
-.IP "\fBbind_address_remotelns\fR (ip address)" 4
-.IX Item "bind_address_remotelns (ip address)"
-Address of the interface to listen the remote \s-1LNS\s0 tunnels. If no address is given, all interfaces are listened (Any Address).
-.IP "\fBbind_portremotelns\fR (short)" 4
-.IX Item "bind_portremotelns (short)"
-Port to bind for the Remote \s-1LNS \s0(default: 65432).
-.PP
-A static \s-1REMOTES LNS\s0 configuration can be entered by the command:
-.IP "\fBsetforward\fR \fI\s-1MASK\s0\fR \fI\s-1IP\s0\fR \fI\s-1PORT\s0\fR \fI\s-1SECRET\s0\fR" 4
-.IX Item "setforward MASK IP PORT SECRET"
-where \s-1MASK\s0 specifies the mask of users who have forwarded to remote \s-1LNS \s0(ex: \*(L"/friendISP@company.com\*(R").
-.Sp
-where \s-1IP\s0 specifies the \s-1IP\s0 of the remote \s-1LNS \s0(ex: \*(L"66.66.66.55\*(R").
-.Sp
-where \s-1PORT\s0 specifies the L2TP Port of the remote \s-1LNS \s0(Normally should be 1701) (ex: 1701).
-.Sp
-where \s-1SECRET\s0 specifies the secret password the remote \s-1LNS \s0(ex: mysecret).
-.PP
-The static \s-1REMOTE LNS\s0 configuration can be used when the friend \s-1ISP\s0 not have a proxied Radius.
-.PP
-If a proxied Radius is used, It will return the \s-1RADIUS\s0 attributes:
-.IP "Tunnel\-Type:1 = L2TP" 4
-.IX Item "Tunnel-Type:1 = L2TP"
-.PD 0
-.IP "Tunnel\-Medium\-Type:1 = IPv4" 4
-.IX Item "Tunnel-Medium-Type:1 = IPv4"
-.ie n .IP "Tunnel\-Password:1 = ""\s-1LESECRETL2TP""\s0" 4
-.el .IP "Tunnel\-Password:1 = ``\s-1LESECRETL2TP''\s0" 4
-.IX Item "Tunnel-Password:1 = LESECRETL2TP"
-.ie n .IP "Tunnel\-Server\-Endpoint:1 = ""88.xx.xx.x1""" 4
-.el .IP "Tunnel\-Server\-Endpoint:1 = ``88.xx.xx.x1''" 4
-.IX Item "Tunnel-Server-Endpoint:1 = 88.xx.xx.x1"
-.ie n .IP "Tunnel\-Assignment\-Id:1 = ""friendisp_lns1""" 4
-.el .IP "Tunnel\-Assignment\-Id:1 = ``friendisp_lns1''" 4
-.IX Item "Tunnel-Assignment-Id:1 = friendisp_lns1"
-.IP "Tunnel\-Type:2 += L2TP" 4
-.IX Item "Tunnel-Type:2 += L2TP"
-.IP "Tunnel\-Medium\-Type:2 += IPv4" 4
-.IX Item "Tunnel-Medium-Type:2 += IPv4"
-.ie n .IP "Tunnel\-Password:2 += ""\s-1LESECRETL2TP""\s0" 4
-.el .IP "Tunnel\-Password:2 += ``\s-1LESECRETL2TP''\s0" 4
-.IX Item "Tunnel-Password:2 += LESECRETL2TP"
-.ie n .IP "Tunnel\-Server\-Endpoint:2 += ""88.xx.xx.x2""" 4
-.el .IP "Tunnel\-Server\-Endpoint:2 += ``88.xx.xx.x2''" 4
-.IX Item "Tunnel-Server-Endpoint:2 += 88.xx.xx.x2"
-.ie n .IP "Tunnel\-Assignment\-Id:2 += ""friendisp_lns2""" 4
-.el .IP "Tunnel\-Assignment\-Id:2 += ``friendisp_lns2''" 4
-.IX Item "Tunnel-Assignment-Id:2 += friendisp_lns2"
-.PD
-.SS "\s-1PPPOE SETTINGS\s0"
-.IX Subsection "PPPOE SETTINGS"
-.IP "\fBpppoe_if_to_bind\fR (string)" 4
-.IX Item "pppoe_if_to_bind (string)"
-\&\s-1PPPOE\s0 server interface to bind (ex: \*(L"eth0.12\*(R"), If not specified the server \s-1PPPOE\s0 is not enabled. For the pppoe clustering, all the interfaces \s-1PPPOE\s0 of the clusters must use the same \s-1HW\s0 address (\s-1MAC\s0 address).
-.IP "\fBpppoe_service_name\fR (string)" 4
-.IX Item "pppoe_service_name (string)"
-\&\s-1PPPOE\s0 service name (default: \s-1NULL\s0).
-.IP "\fBpppoe_ac_name\fR (string)" 4
-.IX Item "pppoe_ac_name (string)"
-\&\s-1PPPOE\s0 access concentrator name (default: \*(L"l2tpns\-pppoe\*(R").
-.IP "\fBpppoe_only_equal_svc_name\fR (boolean)" 4
-.IX Item "pppoe_only_equal_svc_name (boolean)"
-If set to yes, the \s-1PPPOE\s0 server only accepts clients with a \*(L"service-name\*(R" different from \s-1NULL\s0 and a \*(L"service-name\*(R" equal to server \*(L"service-name\*(R" (default: no).
-.SS "\s-1BGP ROUTING\s0"
-.IX Subsection "BGP ROUTING"
-The routing configuration section is entered by the command
-.PP
-\&\fBrouter\fR \fBbgp\fR \fIas\fR
-.PP
-where \fIas\fR specifies the local \s-1AS\s0 number.
-.PP
-Subsequent lines prefixed with \fBneighbour\fR \fIpeer\fR define the attributes of \s-1BGP\s0 neighhbours. Valid commands are:
-.PP
-\&\fBneighbour\fR \fIpeer\fR \fBremote-as\fR \fIas\fR
-.PP
-\&\fBneighbour\fR \fIpeer\fR \fBtimers\fR \fIkeepalive\fR \fIhold\fR
-.PP
-Where \fIpeer\fR specifies the \s-1BGP\s0 neighbour as either a hostname or \s-1IP\s0 address, \fIas\fR is the remote \s-1AS\s0 number and \fIkeepalive\fR, \fIhold\fR are the timer values in seconds.
-.SS "\s-1NAMED ACCESS LISTS\s0"
-.IX Subsection "NAMED ACCESS LISTS"
-Named access lists may be defined with either of
-.IP "\(bu" 4
-\&\fBip\fR \fBaccess-list\fR \fBstandard\fR \fIname\fR
-.IP "\(bu" 4
-\&\fBip\fR \fBaccess-list\fR \fBextended\fR \fIname\fR
-.PP
-Subsequent lines starting with permit or deny define the body of the access-list.
-.PP
-\fIStandard Access Lists\fR
-.IX Subsection "Standard Access Lists"
-.PP
-Standard access lists are defined with:
-.IP "\(bu" 4
-{\fBpermit\fR|\fBdeny\fR} \fIsource\fR [\fIdest\fR]
-.PP
-Where \fIsource\fR and \fIdest\fR specify \s-1IP\s0 matches using one of:
-.IP "\(bu" 4
-\&\fIaddress\fR \fIwildard\fR
-.IP "\(bu" 4
-\&\fBhost\fR \fIaddress\fR
-.IP "\(bu" 4
-\&\fBany\fR
-.PP
-\&\fIaddress\fR and \fIwildard\fR are in dotted-quad notation, bits in the \fIwildard\fR indicate which address bits in \fIaddress\fR are relevant to the match (0 = exact match; 1 = don't care).
-.PP
-The shorthand 'host address' is equivalent to '\fIaddress\fR \fB0.0.0.0\fR'; '\fBany\fR' to '\fB0.0.0.0\fR \fB255.255.255.255\fR'.
-.PP
-\fIExtended Access Lists\fR
-.IX Subsection "Extended Access Lists"
-.PP
-Extended access lists are defined with:
-.IP "\(bu" 4
-{\fBpermit\fR|\fBdeny\fR} \fIproto\fR \fIsource\fR [\fIports\fR] \fIdest\fR [\fIports\fR] [\fIflags\fR]
-.PP
-Where \fIproto\fR is one of \fBip\fR, \fBtcp\fR or \fBudp\fR, and \fIsource\fR and \fIdest\fR are as described above for standard lists.
-.PP
-For \s-1TCP\s0 and \s-1UDP\s0 matches, source and destination may be optionally followed by a ports specification:
-.IP "\(bu" 4
-{\fBeq|neq|gt|lt\fR} \fIport\fR
-.IP "\(bu" 4
-\&\fBrange\fR \fIfrom\fR \fIto\fR
-.PP
-\&\fIflags\fR may be one of:
-.IP "{\fBmatch\-any|match\-all\fR} {\fB+|\-\fR}{\fBfin|syn|rst|psh|ack|urg\fR} ..." 4
-.IX Item "{match-any|match-all} {+|-}{fin|syn|rst|psh|ack|urg} ..."
-Match packets with any or all of the tcp flags set (+) or clear (\-).
-.IP "\fBestablished\fR" 4
-.IX Item "established"
-Match \*(L"established\*(R" \s-1TCP\s0 connections: packets with \s-1RST\s0 or \s-1ACK\s0 set, and \s-1SYN\s0 clear.
-.IP "\fBfragments\fR" 4
-.IX Item "fragments"
-Match \s-1IP\s0 fragments. May not be specified on rules with layer 4 matches.
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fIl2tpns\fR\|(8)
diff --git a/Docs/startup-config.5.pod b/Docs/startup-config.5.pod
deleted file mode 100644
index db654c0..0000000
--- a/Docs/startup-config.5.pod
+++ /dev/null
@@ -1,501 +0,0 @@
-=pod
-
-=head1 NAME
-
-startup-config - configuration file for l2tpns
-
-=head1 SYNOPSIS
-
-/etc/l2tpns/startup-config
-
-=head1 DESCRIPTION
-
-B is the configuration file for B
-
-The format is plain text, in the same format as accepted by
-the configuration mode of l2tpns's telnet administrative
-interface. Comments are indicated by either the character # or !.
-
-=head2 SETTINGS
-
-Settings are specified with
-
-=over
-
-=item B F F
-
-=back
-
-A list of the possible configuration directives follows. Each of these should be set by a line like:
-
-=over
-
-=item B I I<"value">
-
-=item B I I<192.168.1.1>
-
-=item B I I
-
-=back
-
-The following F may be set:
-
-=over
-
-=item B (string)
-
-If set to a directory, then every 5 minutes the current usage for every connected use will be dumped to a file in this directory. Each file dumped begins with a header, where each line is prefixed by #. Following the header is a single line for every connected user, fields separated by a space.
-
-The fields are username, ip, qos, uptxoctets, downrxoctets, origin (optional). The qos field is 1 if a standard user, and 2 if the user is throttled. The origin field is dump if B is set to true (origin value: L=LAC data, R=Remote LNS data, P=PPPOE data).
-
-=item B (boolean)
-
-If set to true, all origin of the usage is dumped to the accounting file (LAC+Remote LNS+PPPOE)(default false).
-
-=item B (boolean)
-
-Allow multiple logins with the same username. If false (the default), any prior session with the same username will be dropped when a new session is established.
-
-=item B (boolean)
-
-This parameter authorize to change the source IP of the tunnels l2tp. This parameter can be used when the remotes BAS/LAC are l2tpns server configured in cluster mode, but that the interface to remote LNS are not clustered (the tunnel can be coming from different source IP) (default: no).
-
-=item B (ip address)
-
-It's the listen address of the l2tp udp protocol sent and received to LAC. This address is also assigned to the tun interface if no iftun_address is specified. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
-
-=item B (ip address)
-
-This parameter permit one to listen several address of the l2tp udp protocol (and set several address to the tun interface).
-
-WHEN this parameter is set, It OVERWRITE the parameters "bind_address" and "iftun_address".
-
-these can be interesting when you want do load-balancing in cluster mode of the uploaded from the LAC. For example you can set a bgp.prepend(MY_AS) for Address1 on LNS1 and a bgp.prepend(MY_AS) for Address2 on LNS2 (see BGP AS-path prepending).
-
-example of use with 2 address:
-
-B I "64.14.13.41, 64.14.13.42"
-
-=item B (ip address)
-
-Multicast cluster address (default: 239.192.13.13). See the section on Clustering for more information.
-
-=item B (int)
-
-UDP cluster port (default: 32792). See the section on Clustering for more information.
-
-=item B (string)
-
-Interface for cluster packets (default: eth0).
-
-=item B (int)
-
-TTL for multicast packets (default: 1).
-
-=item B (int)
-
-Interval in tenths of a second between cluster heartbeat/pings.
-
-=item B (int)
-
-Cluster heartbeat timeout in tenths of a second. A new master will be elected when this interval has been passed without seeing a heartbeat from the master.
-
-=item B (int)
-
-Determines the minimum number of up to date slaves required before the master will drop routes (default: 1).
-
-=item B (int)
-
-Set the level of debugging messages written to the log file. The value should
-be between 0 and 5, with 0 being no debugging, and 5 being the highest.
-A rough description of the levels is:
-
-=over
-
-=item 0. Critical Errors - Things are probably broken
-
-=item 1. Errors - Things might have gone wrong, but probably will recover
-
-=item 2. Warnings - Just in case you care what is not quite perfect
-
-=item 3. Information - Parameters of control packets
-
-=item 4. Calls - For tracing the execution of the code
-
-=item 5. Packets - Everything, including a hex dump of all packets processed... probably twice
-
-=back
-
-Note that the higher you set the debugging level, the slower the program will run. Also, at level 5 a LOT of information will be logged. This should only ever be used for working out why it doesn't work at all.
-
-=item B (boolean)
-
-If set to true, then the current bandwidth utilization will be logged every second. Even if this is disabled, you can see this information by running the uptime command on the CLI.
-
-=item B (boolean)
-
-Disable l2tp sending HELLO message for Apple compatibility. Some OS X implementation of l2tp no manage the L2TP "HELLO message". (default: no).
-
-=item B (int)
-
-Time between last packet sent and LCP ECHO generation (default: 10 (seconds)).
-
-=item B
-
-Allow multiple logins matching this specific username.
-
-=item B (int)
-
-Maximum number of host unreachable ICMP packets to send per second.
-
-=item B (int)
-
-Drop sessions who have not responded within idle_echo_timeout seconds (default: 240 (seconds))
-
-=item B (ip address)
-
-This parameter is used when you want a tun interface address different from the address of "bind_address" (For use in cases of specific configuration). If no address is given to iftun_address and bind_address, 1.1.1.1 is used.
-
-=item B (int)
-
-MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
-
-=item B (string)
-
-The secret used by l2tpns for authenticating tunnel request. Must be the same as the LAC, or authentication will fail. Only actually be used if the LAC requests authentication.
-
-=item B (boolean)
-
-Keep all pages mapped by the l2tpns process in memory.
-
-=item B (string)
-
-This will be where all logging and debugging information is written to.This may be either a filename, such as /var/log/l2tpns, or the string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
-
-=item B (int)
-
-Number of packets to read off each of the UDP and TUN fds when returned as readable by select (default: 10). Avoids incurring the unnecessary system call overhead of select on busy servers.
-
-=item B (int>
-
-Maximum number of packets of downstream traffic to be handled each tenth of a second per session. If zero, no limit is applied (default: 0). Intended as a DoS prevention mechanism and not a general throttling control (packets are dropped, not queued).
-
-=item B (ip address)
-
-Address to send to clients as the default gateway.
-
-=item B (string)
-
-If set, the process id will be written to the specified file. The value must be an absolute path.
-
-=item B (boolean)
-
-Change this value to no to force generation of LCP ECHO every echo_timeout seconds, even there are activity on the link (default: yes)
-
-=item B (int)
-
-=item B (int)
-
-=item B (int)
-
-PPP counter and timer values, as described in Section 4.1 of RFC1661.
-
-I, Restart timer for PPP protocol negotiation in seconds (default: 3).
-
-I, Number of configure requests to send before giving up (default: 10).
-
-I, Number of Configure-Nak requests to send before sending a Configure-Reject (default: 5).
-
-=item B (ip address), B (ip address)
-
-Whenever a PPP connection is established, DNS servers will be sent to the user, both a primary and a secondary. If either is set to 0.0.0.0, then that one will not be sent.
-
-=item B (ip address), B (ip address)
-
-Sets the RADIUS servers used for both authentication and accounting. If the primary server does not respond, then the secondary RADIUS server will be tried.
-
-Note: in addition to the source IP address and identifier, the RADIUS server must include the source port when detecting duplicates to suppress (in order to cope with a large number of sessions coming on-line simultaneously l2tpns uses a set of udp sockets, each with a separate identifier).
-
-=item B (short), B (short)
-
-Sets the authentication ports for the primary and secondary RADIUS servers. The accounting port is one more than the authentication port. If no RADIUS ports are given, the authentication port defaults to 1645, and the accounting port to 1646.
-
-=item B (boolean)
-
-If set to true, then RADIUS accounting packets will be sent. This means that a B record will be sent when the session is successfully authenticated, and a B record will be sent when the session is closed.
-
-=item B (int)
-
-If radius_accounting is on, defines the interval between sending of RADIUS interim accounting records (in seconds).
-
-=item B (string)
-
-This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
-
-=item B (string)
-
-A comma separated list of supported RADIUS authentication methods ("pap" or "chap"), in order of preference (default "pap").
-
-=item B (short)
-
-Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
-
-=item B, B (int)
-
-Define a port range in which to bind sockets used to send and receive RADIUS packets. Must be at least RADIUS_FDS (64) wide. Simplifies firewalling of RADIUS ports (default: dynamically assigned).
-
-=item B (string)
-
-Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
-
-=item B (boolean)
-
-Sets the scheduling policy for the l2tpns process to SCHED_FIFO. This causes the kernel to immediately preempt any currently running SCHED_OTHER (normal) process in favour of l2tpns when it becomes runnable. Ignored on uniprocessor systems.
-
-=item B (boolean)
-
-Determines whether or not to send a gratuitous ARP for the bind_address when the server is ready to handle traffic (default: true). This value is ignored if BGP is configured.
-
-=item B (string)
-
-Name of the tun interface (default: "tun0").
-
-=item B (int)
-
-Sets the default speed (in kbits/s) which sessions will be limited to. If this is set to 0, then throttling will not be used at all. Note: You can set this by the CLI, but changes will not affect currently connected users.
-
-=item B (int)
-
-Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
-
-=back
-
-=head2 DHCPv6 And IPv6 SETTINGS
-
-=over
-
-=item B (int)
-
-The preferred lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
-
-=item B (int)
-
-The valid lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
-
-=item B (int)
-
-DUID Based on Link-layer Address (DUID-LL) (see rfc3315).
-
-=item B, B (Ipv6 address)
-
-IPv6 DNS servers will be sent to the user (see rfc3646).
-
-=item B (string)
-
-The Domain Search List (ex: "fdn.fr") (see rfc3646).
-
-=item B (Ipv6 address)
-
-Enable negotiation of IPv6. This forms the the first 64 bits of the client allocated address. The remaining 64 come from the allocated IPv4 address and 4 bytes of 0.
-
-=back
-
-=head2 LAC SETTINGS
-
-=over
-
-=item B (ip address)
-
-Address of the interface to listen the remote LNS tunnels. If no address is given, all interfaces are listened (Any Address).
-
-=item B (short)
-
-Port to bind for the Remote LNS (default: 65432).
-
-=back
-
-A static REMOTES LNS configuration can be entered by the command:
-
-=over
-
-=item B I I I I
-
-where MASK specifies the mask of users who have forwarded to remote LNS (ex: "/friendISP@company.com").
-
-where IP specifies the IP of the remote LNS (ex: "66.66.66.55").
-
-where PORT specifies the L2TP Port of the remote LNS (Normally should be 1701) (ex: 1701).
-
-where SECRET specifies the secret password the remote LNS (ex: mysecret).
-
-=back
-
-The static REMOTE LNS configuration can be used when the friend ISP not have a proxied Radius.
-
-If a proxied Radius is used, It will return the RADIUS attributes:
-
-=over
-
-=item Tunnel-Type:1 = L2TP
-
-=item Tunnel-Medium-Type:1 = IPv4
-
-=item Tunnel-Password:1 = "LESECRETL2TP"
-
-=item Tunnel-Server-Endpoint:1 = "88.xx.xx.x1"
-
-=item Tunnel-Assignment-Id:1 = "friendisp_lns1"
-
-=item Tunnel-Type:2 += L2TP
-
-=item Tunnel-Medium-Type:2 += IPv4
-
-=item Tunnel-Password:2 += "LESECRETL2TP"
-
-=item Tunnel-Server-Endpoint:2 += "88.xx.xx.x2"
-
-=item Tunnel-Assignment-Id:2 += "friendisp_lns2"
-
-=back
-
-=head2 PPPOE SETTINGS
-
-=over
-
-=item B (string)
-
-PPPOE server interface to bind (ex: "eth0.12"), If not specified the server PPPOE is not enabled. For the pppoe clustering, all the interfaces PPPOE of the clusters must use the same HW address (MAC address).
-
-=item B (string)
-
-PPPOE service name (default: NULL).
-
-=item B (string)
-
-PPPOE access concentrator name (default: "l2tpns-pppoe").
-
-=item B (boolean)
-
-If set to yes, the PPPOE server only accepts clients with a "service-name" different from NULL and a "service-name" equal to server "service-name" (default: no).
-
-=back
-
-=head2 BGP ROUTING
-
-The routing configuration section is entered by the command
-
-B B I
-
-where I specifies the local AS number.
-
-Subsequent lines prefixed with B I define the attributes of BGP neighhbours. Valid commands are:
-
-B I B I
-
-B I B I I
-
-Where I specifies the BGP neighbour as either a hostname or IP address, I is the remote AS number and I, I are the timer values in seconds.
-
-=head2 NAMED ACCESS LISTS
-
-Named access lists may be defined with either of
-
-=over
-
-=item
-
-B B B I
-
-=item
-
-B B B I
-
-=back
-
-Subsequent lines starting with permit or deny define the body of the access-list.
-
-=head3 Standard Access Lists
-
-Standard access lists are defined with:
-
-=over
-
-=item
-
-{B|B} I [I]
-
-=back
-
-Where I and I specify IP matches using one of:
-
-=over
-
-=item
-
-I I
-
-=item
-
-B I
-
-=item
-
-B
-
-=back
-
-I and I are in dotted-quad notation, bits in the I indicate which address bits in I are relevant to the match (0 = exact match; 1 = don't care).
-
-The shorthand 'host address' is equivalent to 'I B<0.0.0.0>'; 'B' to 'B<0.0.0.0> B<255.255.255.255>'.
-
-=head3 Extended Access Lists
-
-Extended access lists are defined with:
-
-=over
-
-=item
-
-{B|B} I I [I] I [I] [I]
-
-=back
-
-Where I is one of B, B or B, and I and I are as described above for standard lists.
-
-For TCP and UDP matches, source and destination may be optionally followed by a ports specification:
-
-=over
-
-=item
-
-{B} I
-
-=item
-
-B I I
-
-=back
-
-I may be one of:
-
-=over
-
-=item {B} {B<+|->}{B} ...
-
-Match packets with any or all of the tcp flags set (+) or clear (-).
-
-=item B
-
-Match "established" TCP connections: packets with RST or ACK set, and SYN clear.
-
-=item B
-
-Match IP fragments. May not be specified on rules with layer 4 matches.
-
-=back
-
-=head1 SEE ALSO
-
-L
-
-=cut
diff --git a/Docs/vpn/practical-vpns.xml b/Docs/vpn/practical-vpns.xml
deleted file mode 100644
index ccb92c7..0000000
--- a/Docs/vpn/practical-vpns.xml
+++ /dev/null
@@ -1,1086 +0,0 @@
-
-
-
-
-
- Practical VPNs
- Implementing Full-scale VPNs
-
-
- Liran
- Tal
-
-
- liran@enginx.com
-
-
-
-
-
- Yakov
- Shtutz
- Special thanks
-
-
-
- Shahar
- Fermon
- Testing and feedback
-
-
-
-
- This document was compiled from the administrator's point of
- view, to explain what are VPNs, how they are deployed today
- and to detail the necessary steps and tools to achieve and
- create a fully working VPN solution, integrated with RADIUS
- systems for AAA.
-
-
-
- I will not dwell in this document on how to compile source
- packages or kernel patching, and with the same tone I'm
- assuming the reader is an exprerienced Linux user.
-
-
-
- VPNs have their share amount of gossip for being a very
- complex thing, and in some cases this may be true as they tend
- to be more security intenssive which require adding more and
- more layers to the scheme. With this said, we'll take a look
- at how fairly straight-forward it is to setup VPNs and
- maintain them with varius Open-Source tools.
-
-
-
-
-
- Overview of VPNs and IPsec
-
- Virtual Private Networks
-
- The purpose of a VPN is to create a secure channel ontop of an
- un-secure medium, where a computer or a device are put in each
- end-point in order to establish communication, each of these
- end-points are often reffered to as Point of Presense, or POP.
- This kind of a communication allows the capability of creating
- a Virtual Private Network, which is accesable over a medium
- such as the Internet and thus, extend the physical boundaries
- of an existing local network.
-
-
-
- VPNs have three forms:
-
-
- Site-To-Site VPNs
-
-
- these setups exist in order to extend the local network
- to create a much bigger LAN over the Internet.
-
-
-
-
-
- Network-To-Host or Remote access VPNs
-
-
- where a central VPN server is able to achieve multiple
- connections, often reffered to as RoadWarrior VPNs.
- (This setup is very common among ISPs)
-
-
-
-
-
- Network-To-Network
-
-
- extranet VPNs allow secure connections within branches
- and business partners, they are an extension of a
- Site-To-Site VPNs.
-
-
-
-
-
-
-
- shows a Site-To-Site VPN diagram.
-
- Site to Site VPN
-
-
-
-
-
-
-
-
-
- IP/VPNs are connections which are based upon IP tunnels. A
- tunnel is a way to encapsulate an IP packet inside another IP
- packet or some other type of packet. Why do we need
- tunneling? A Virtual Private Network is identified by IANA's
- private IP assignments and so such packet can not go beyond
- the uplink Internet interface.
-
-
-
- shows the tunneling process.
-
- Tunneling Process
-
-
-
-
-
-
-
-
-
- Several tunneling protocols are available for manifesting
- VPNs.
-
-
-
- L2F
-
-
- Layer 2 Forwarding, an older implementation which
- assume position at the link layer of the OSI. It has
- no encryption capabilities and hence, deprecated.
-
-
-
-
-
- L2TP
-
-
- Layer 2 Tunneling Protocol, still no encryption
- capabilities.
-
-
-
-
-
- PPTP
-
-
- Point-to-Point Tunneling Protocol, and yet again, no
- encryption.
-
-
-
-
-
-
-
- As seen, the requirement of encryption enhancement is urgent
- in order to assure authentication, data integrity and privacy.
- IPsec solves this by providing a suite of security measures
- implemented at layer 3.
-
-
-
-
- IP Security Suite (IPsec)
-
- VPN Security is now appearing, this complex things. How so?
- VPN tunnels by themselves are easily maintained by
- single-standalone tools like pppd, l2tpns, stunnel and others.
- Involving security with VPNs though requires more:
-
-
-
- authentication, data integrity and privacy
-
-
-
- keying management
-
-
-
-
-
-
- Keys are secrets being shared by two end-points to provide a
- secure mean of communication against a third-party
- connection from sniffing the actual data.
-
-
-
-
- Different ways to handle key management include RADIUS (Remote
- Authentication Dial In User Service) systems which provide AAA
- (Authentication, Authorization and Accounting). Another
- solution is ISAKMP/Oackly - Internet Security Association and
- Key Management Protocol. This solution requires you to posess
- one of the following:
-
-
-
- something you have
-
-
-
- something you know
-
-
-
- something you are
-
-
-
-
-
- The more requirements you meet the more secure is the medium,
- once established. Let's review, something we have is like a
- certificate, it proves who we are. Something we know, is a
- key, a secret password which we were told in a whisper, and
- something we are is our-fingerprint which identifies ourselves
- from other individuals.
-
-
-
- IPsec in Depth
-
- IPsec consists of two main protocols, an Authentication
- Header and Encapsulation Security Payload, also known as AH
- and ESP. Although it is not bound to these and can be
- extended (and often is) to other standarts such as
-
-
-
- Data Encryption Standart (DES and 3DES)
-
-
-
- Diffie-Hellman (DH)
-
-
-
- Secure Hash Algorithm-1 (SHA1)
-
-
-
- Message Digest 5 (MD5)
-
-
-
- Internet Key Exchange (IKE)
-
-
-
- Certification Authorities (CA)
-
-
-
-
-
- We'll be deploying an IKE daemon to handle the key
- management, which uses the Diffie- Hellman cryptography
- protocol in order to allow two parties to establish a
- connection based upon a shared secret key that both parties
- posess. (Authentication within IKE is handled by MD5
- hashing)
-
-
-
- IKE is responsible for authentication of two IPsec parties,
- negotiation of keys for encryption algorithms and security
- associations. This process is commonly regarded as two
- phases:
-
-
-
- Phase 1: IKE Security Association
-
-
- The IKE daemon authenticates against the peers in
- order to achieve a secure channel, according to the
- Diffie-Hellman key agreement.
-
-
-
-
-
- Phase 2: IKE IPsec Negotiation
-
-
- After achieving an authenticated channel, the
- parties now negotiate a secure transform (the way to
- encrypt and secure the medium) where the sender is
- offering his/hers transform set after which the
- receiver decides upon one. An IPsec session can now
- safely begin.
-
-
-
-
-
-
-
- Just to be clear, a Security Association is an agreed
- relation between two parties which describes how they will
- use security services (from IPsec) to communicate.
-
-
-
-
- IPsec Modes
-
- IPsec can operate in two different modes:
-
-
-
- Transport mode
-
-
- takes place when two devices (like a station and a
- gateway (now considered a host)) are establishing a
- connection which upon they both support IPsec.
-
-
-
-
-
- Tunnel mode
-
-
- we require tunnel mode when we proxy IPsec
- connetions between two stations behind the IPsec
- gateway. For example, in a Site-to-Site VPN a
- tunnel mode lives, since it exists in order to
- provide the stations behind these gateways runing
- the VPN/IPsec to communicate securely. In this
- situation, both end-points are runing an IPsec
- software.
-
-
-
-
-
-
-
- In definition, a tunnel mode IPsec is better secured than
- transport. Without going too deep into the ins-and-outs of
- the technical side, transport mode doesn't encapsulate the
- actual IP layer but only the tcp/udp (Transport layer of the
- OSI) where-as a tunnel mode encapsulate both the Transport
- layer and the IP layer into a new IP packet.
-
-
-
- To summarize, we need VPNs for data-exchange methods and a
- set of IPsec tools for security reasons.
-
-
-
-
-
-
- VPN Deployment
-
- I've assembled another diagram to view the actual VPN setup.
- gives a general description of
- how the network will be layed out in real-world scenario.
-
-
- VPN Deployment
-
-
-
-
-
-
-
-
-
- We notice that a single Linux box is acting as a Gateway and has
- all the services included with it. This is a bad idea from a
- security prespective but it's easy to just deploy the FreeRADIUS
- and MySQL servers on another machine. Of course the L2TPns and
- the rest of the IPsec tools suite would have to remain on the
- Gateway box (not necessarily the Firewall).
-
-
-
- attempts to explain the actual
- process that the VPN takes and to detail the place that each of
- that application-in-charge takes place.
-
-
- VPN Process
-
-
-
-
-
-
-
-
-
- Requirements
-
- The Toolbox
-
- Following is a description of the requirements you will
- have to meet:
-
-
-
- A Linux box
-
- preferably a 2.4.27 kernel or higher.
-
- Debian is the chosen distribution which means we'll
- be using apt-get for installation, but I'll also
- focus on basic source tarballs installation.
-
-
-
- Dependencies:
-
-
-
- ipsec configuration in the kernel
-
-
-
-
-
-
-
- L2TPns
-
- an L2TP PPP Termination tool.
-
- Dependencies:
-
-
-
- libcli 1.8.0 or greater
-
-
-
-
- tun/tap interface compiled in the kernel or as
- a module
-
-
-
-
-
-
-
-
- FreeRADIUS
-
- For authentication, and accounting.
-
-
-
-
- MySQL
-
- To act as a back-end database for the RADIUS.
-
-
-
-
- OpenSwan
-
- Provides the ipsec suite package.
-
-
-
-
-
-
-
- Kernel Support
-
- Debian stock kernel 2.4.27 and up are ipsec compatible
- although if you think otherwise check for the
- kernel-patch-openswan package.
-
-
-
-
-
- Installation
-
- L2TPns
-
- Installation
-
-
- L2TPns is a layer 2 tunneling protocol network server
- (LNS). It supports up to 65535 concurrent sessions per
- server/cluster plus ISP features such as rate limiting,
- walled garden, usage accounting, and more.
-
-
-
-
- In a personal note - L2TPns is highly configurable for
- many cases, and extremely reliable for
- production/commerical use.
-
-
-
-
-
- Step 1:
-
-
- Make sure you have libcli-1.8 development package
- installed:
-
-# apt-cache search libcli
-libcli-dev - emulates a cisco style telnet command-line interface (dev files)
-libcli1 - emulates a cisco style telnet command-line interface
-# apt-get install libcli-dev
-
-
-
-
-
-
- Step 2:
-
-
- Download the source from
-
- SourceForge.
-
-
-
-
-
- Step 3:
-
-
- Build and install:
- make && make install
-
-
-
-
-
-
-
-
- Alternately, you can skip these steps and simply
- apt-get install l2tpns.
-
-
-
-
-
- On RPM-based distributions, you should be able to make
- packages from the libcli and l2tpns source tarballs with
- rpmbuild -ta.
-
-
-
-
- Once compiliation is done you will have l2tpns in
- /usr/sbin/l2tpns, and all
- configuration files can be found in
- /etc/l2tpns/.
-
-
-
-
- Configuration
-
- The only configuration that L2TPns takes is centralized in
- the configuration file
- /etc/l2tpns/startup-config.
-
-set debug 2 # Debugging level
-set log_file "/var/log/l2tpns" # Log file: comment out to use stderr, use
- # "syslog:facility" for syslog
-set pid_file "/var/run/l2tpns.pid" # Write pid to this file
-set l2tp_secret "secret" # shared secret
-set primary_dns 212.117.128.6 # Only 2 DNS server entries are allowed
-set secondary_dns 212.117.129.3
-set primary_radius 192.168.0.1 # Can have multiple radius server entries,
- # but ony one radius secret
-set primary_radius_port 1812
-set radius_secret "radius_secret"
-set radius_accounting yes
-set radius_dae_port 3799
-set accounting_dir "/var/run/l2tpns/acct" # Write usage accounting files into specified
- # directory
-set peer_address 192.168.0.1 # Gateway address given to clients
-load plugin "sessionctl" # Drop/kill sessions
-load plugin "autothrottle" # Throttle/snoop based on RADIUS
-load plugin "throttlectl" # Control throttle/snoop with nsctl
-load plugin "snoopctl"
-
-
-
-
- This is the trimmed down version of probably most of
- the common configuration and even some extra options.
-
-
-
- Important configuration options are highlited and you
- should adjust these to meet your network needs. We can
- deploy all of the environment into one box which is of
- course not a very good idea from a security point of view,
- but will function just fine. Moreover, we will be using
- aliased IP addresses so once you've decided to move the
- FreeRADIUS daemon to another computer on the LAN it will
- be fairly easy and won't take too much configuration into
- it.
-
-
-
- Next, we need to setup the IP pool that L2TPns will
- provide to each VPN client. The configuration file is
- located at /etc/l2tpns/ip_pool and
- should look like the following:
- 172.16.21.0/24
-
-
-
-
- Of course you can change this pool to anything else
- (IANA IPs assigned for private internets only) just make
- sure it is not conflicting with your current LAN network
- addresses. This means that if you've assigned addresses
- of 192.168.0.1 and 192.168.0.2 to your LAN boxes you
- can't have a pool of 192.168.0.1/24 defined since L2TPns
- will try to route those addresses from the tun device,
- which is needless to say a bad idea...
-
-
-
- Next up, creating the access-list for L2TPns.
-
-
- Add a username and password into
- /etc/l2tpns/users:
- admin:12345
-
- The password may either be plain-text as above, or
- encrypted with MD5 or DES (to distinguish DES from
- plain-text passwords, prefix the value with
- {crypt}).
-
-
-
- L2TPns utilizes a terminal connection on port 23 which you
- would feel very comfortable in if you have worked with
- routers and switches devices before. The terminal
- provides control over the ppp termination which is why
- we've created an account to log on to.
-
-
-
-
-
- IPsec
-
- Installation
-
- User-space IPsec tools for various IPsec implementations
- exist for linux, among them is the port of KAME's
- libipsec, setkey, and racoon. Others are the OpenSWAN (a
- successor to the FreeSWAN project).
-
-
-
- Getting IPsec installed is fairly easy with Debian:
- # apt-get install openswan
-
-
-
- The OpenSWAN project provides packages for RPM-based
- distributions.
-
-
-
- Alternately, you may download the
- source
- from the OpenSWAN project:
-
-# tar xvzf openswan-2.4.4.tar.gz
-# cd openswan-2.4.4
-# ./configure && make && make install
-
-
-
-
-
- Configuration
-
- OpenSWAN acts as the IKE daemon (remember IKE? it's job
- is to authenticate between the two peers and negotiate a
- secure medium). We will be setting up the IKE daemon as a
- RoadWarrior configuration, a term for remote access
- VPNs.
-
-
-
- We desire this approach for compatibilty because after our
- VPN solution will be complete any user from a Windows
- machine will be easily ready to connect without any 3rd
- party applications, same for Linux.
-
-
-
- Configuration files are placed in
- /etc/ipsec.d/,
- /etc/ipsec.conf and
- /etc/ipsec.secrets.
-
-
-
- Let's start by choosing the remote client and it's PSK
- (Private Shared Key) /etc/ipsec.secrets:
-
-hostname_or_ipaddress %any : PSK "mysecretkeyisverylong"
-
-
-
-
- This is an IP/key pair. The IP or FQDN defines the local
- peer (like a SOHO branch), then the remote host. Here we
- defined %any for all hosts, though it's possible to define
- only a specific IP. At last, we define the key associated
- with it.
-
-
-
- A better way to create a key is to utilize /dev/random for
- creating a unique key.
- # dd if=/dev/random count=16 bs=1 2>/dev/null | xxd -ps
-
-
-
- Next, let's prepare the configuration file
- /etc/ipsec.conf:
-
-version 2.0
-config setup
- nat_traversal=yes
-
-conn l2tp
- authby=secret
- pfs=no
- keyingtries=3
- left=real_ip_address
- leftnexthop=%defaultroute
- leftprotoport=17/%any
- right=%any
- rightprotoport=17/%any
- auto=add
-
-include /etc/ipsec.d/examples/no_oe.conf
-
-
-
-
- In this file we have first defined version 2 which is a
- must, then enabled NAT Traversal. To understand the
- importance of this feature think of the following
- scenario: A remote user attempts to connect while he's
- behind a router and therefore NATed. The router has to
- de-encapsulate the packet, change things and then build it
- up again and send it. IPsec doesn't like other people
- messing with it's packet. That's why we solve this issue
- with NAT Traversal.
-
-
-
- Next up we configure authentication type (certificates,
- psk, rsa keys, etc) then the left and right peers. The
- default mode OpenSWAN takes is tunnel unless told
- otherwise. I won't go into in-depth explanation of every
- method, you can take a quick look at
- /etc/ipsec.d/examples for more
- explanation and other variations of working with RSA keys,
- Certificates, host-to-host, and more.
-
-
-
- In summary:
-
-
-
- We've configured an almost complete IPsec VPN setup.
-
-
-
-
-
- We've installed and configured a VPN server (L2TPns)
- and our IPsec security suite.
-
-
-
-
-
- To control both of them we use:
- /etc/init.d/l2tpns and
- /etc/init.d/racoon (location
- of start-up scripts may vary on non-Debian systems,
- or if you've installed from
- source).
-
-
-
-
-
-
-
-
- FreeRADIUS
-
- The VPN setup needs to authenticate against something, that
- is the users database which we chose to be a FreeRADIUS
- server backed with a MySQL database.
-
-
-
- Installation
-
-
- FreeRADIUS is the premiere open source RADIUS server.
- While detailed statistics are not available, we believe
- that FreeRADIUS is well within the top 5 RADIUS servers
- world-wide, in terms of the number of people who use it
- daily for authentication. It scales from embedded
- systems with small amounts of memory, to systems with
- millions of users. It is fast, flexible, configurable,
- and supports more authentication protocols than many
- commercial servers.
-
-
-
-
- Installing on Debian:
- # apt-get install freeradius freeradius-mysql
-
-
-
- From source: Download the latest freeradius package from
- freeradius.org
-
-
-# tar xvzf freeradius.tar.gz
-# cd freeradius
-# ./configure && make && make install
-
-
-
-
-
- Configuration
-
- This will appear a bit complex but it isn't, it's just a
- lot of configuration.
-
-
-
- Following are the configurations you need to have in your
- /etc/freeradius/ files.
-
-
-
- In this section I will not give you a dump of the
- configuration since they are very long and mostly default.
- I'll just post which changes to make.
-
-
-
- We haven't yet configured MySQL, but it'll come
- afterwards, don't worry.
-
-
-
- Make the following changes to the file
- /etc/freeradius/sql.conf:
-
-server = "192.168.0.1"
-login = "radius"
-password = "12345678"
-
-
-
-
- Add the following to the file
- /etc/freeradius/clients.conf:
-
-client 192.168.0.1 {
- secret = my_secret
- shortname = localhost
- nastype = other
-}
-
-
-
-
- Don't confuse the secret directive there with IPsec.
- RADIUS server are using secret keys also to identify their
- allowed NAS (Network Access Servers), these are the
- clients that talk to the RADIUS server.
-
-
-
- Also, change the client 127.0.0.1 {}
- directive to hold the secret "my_secret" like we
- configured for 192.168.0.1 to avoid conflicts.
-
-
-
- Uncomment the sql directive in the
- authorize, accounting, and
- session sections of
- /etc/freeradius/radiusd.conf.
-
-
-
- Now for populating FreeRADIUS with MySQL. If you don't
- know or haven't set root password for MySQL you can do it
- now with:
- # mysqladmin -u root password password_here
-
- Then add the following to
- /root/.my.cnf:
-
-
-[mysqladmin]
-user = root
-password = password_here
-
-
-
-
- Create the radius database, using the
- schema given in
- /usr/share/doc/freeradius/examples/db_mysql.sql.gz
- .
-
-
-
-
- It may be necessary to modify the column definition of
- id in the nas table, removing
- DEFAULT '0' such that the definition reads:
-
- id int(10) NOT NULL auto_increment,
-
-
-
-
-# mysqladmin create radius
-# mysql radius
-mysql> source db_mysql.sql
-mysql> GRANT ALL ON * TO 'radius'@'localhost' IDENTIFIED BY 'radius_password';
-
-
- All the configuration is now done. Let's add a user to
- our VPN database.
-
-# mysql radius
-mysql> INSERT INTO radcheck values (0, "test", "User-Password", "==", "1234");
-
-
-
-
- We have now created a user in the database of username
- test and password 1234.
-
-
-
- Testing the RADIUS setup is simple using the radtest
- utility provided with it.
-
-# radtest
-Usage: radtest user passwd radius-server[:port] nas-port-number secret [ppphint] [nasname]
-# radtest test 1234 192.168.0.1 1812 my_secret
-
-
-
-
- radtest sends an Access-Request to the RADIUS server and
- expects an Access-Accept back from it. If you're not
- getting an Access-Accept from the RADIUS you're advised to
- check the configuration again and see what you might have
- missed.
-
-
-
-
-
- Firewall Configuration
-
- We need to apply a few things to iptables configuration and
- kernel networking.
-
-
-
- First off, we need to accept VPN-specific packets through
- the firewall. Of course you will have to adjust the rules
- to fits you needs, in this case, ppp0 is the Internet
- interface.
-
-# iptables --append INPUT --in-interface ppp0 -p udp --dport 1701 -j ACCEPT
-# iptables --append INPUT --in-interface ppp0 -p udp --dport 500 -j ACCEPT
-# iptables --append INPUT --in-interface ppp0 -p udp --dport 4500 -j ACCEPT
-# iptables --append INPUT --in-interface ppp0 -p 50 -j ACCEPT
-
-
-
-
- If you haven't setup your Linux box as a gateway yet then
- you have to allow forwarding/masqing for the boxes on
- the LAN (and therefore for the VPN clients):
-
-# iptables --table nat --append POSTROUTING --out-interface ppp0 -j MASQUERADE
-# iptables --append FORWARD --in-interface eth0 -j ACCEPT
-# echo 1 > /proc/sys/net/ipv4/ip_forward
-
-
-
-
-
-
-
- References
-
-
- VPN Reference
-
-
-
-
-
-
-
-
- L2TPns Project
-
-
-
-
-
-
- OpenSWAN Project
-
-
-
-
-
-
-
diff --git a/Makefile b/Makefile
index 57091de..49a0d19 100644
--- a/Makefile
+++ b/Makefile
@@ -73,9 +73,9 @@ install: all
$(INSTALL) -m 0755 l2tpns $(DESTDIR)$(bindir)/l2tpns
$(INSTALL) -m 0755 nsctl $(DESTDIR)$(bindir)/nsctl
- $(INSTALL) -m 0644 Docs/startup-config.5 $(DESTDIR)$(man5dir)/startup-config.5
- $(INSTALL) -m 0644 Docs/l2tpns.8 $(DESTDIR)$(man8dir)/l2tpns.8
- $(INSTALL) -m 0644 Docs/nsctl.8 $(DESTDIR)$(man8dir)/nsctl.8
+ $(INSTALL) -m 0644 docs/startup-config.5 $(DESTDIR)$(man5dir)/startup-config.5
+ $(INSTALL) -m 0644 docs/l2tpns.8 $(DESTDIR)$(man8dir)/l2tpns.8
+ $(INSTALL) -m 0644 docs/nsctl.8 $(DESTDIR)$(man8dir)/nsctl.8
gzip --best --force $(DESTDIR)$(man5dir)/*.5 $(DESTDIR)$(man8dir)/*.8
diff --git a/docs/gen-docs.sh b/docs/gen-docs.sh
new file mode 100755
index 0000000..5128f0e
--- /dev/null
+++ b/docs/gen-docs.sh
@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# Source documentation in markdown lives in the src/ folder (html and manpages).
+# This is what you should edit if you want to make changes to the documentation.
+# From these sources, this script generates actual manpages and general
+# documentation in html using pandoc.
+
+if ! [ -x "$(command -v pandoc)" ]; then
+ echo "Pandoc is missing, please install it first"
+ exit 1
+fi
+
+# First we generate manpages
+
+echo "Manpages generation …"
+
+for src in src/man/*.md
+ do
+ pandoc -f markdown -t man "$src" > manpages/"$(basename "$src" .md)" && echo "$(basename "$src" .md) successfully built in docs/manpages directory" || echo "Unable to generate manpage from $src"
+done
+
+# We then generate the rest of the documentation
+
+echo ""
+
+echo "HTML generation …"
+
+
+for src in src/html/*.md
+ do
+ pandoc -f markdown -t html "$src" > html/"$(basename "$src" .md)".html && echo "$(basename "$src" .md).html successfully built in docs/html directory" || echo "Unable to generate html from $src"
+done
+
diff --git a/Docs/vpn/site-to-site-vpn.png b/docs/html/images/site-to-site-vpn.png
similarity index 100%
rename from Docs/vpn/site-to-site-vpn.png
rename to docs/html/images/site-to-site-vpn.png
diff --git a/Docs/vpn/tunneling-process.png b/docs/html/images/tunneling-process.png
similarity index 100%
rename from Docs/vpn/tunneling-process.png
rename to docs/html/images/tunneling-process.png
diff --git a/Docs/vpn/vpn-deployment.png b/docs/html/images/vpn-deployment.png
similarity index 100%
rename from Docs/vpn/vpn-deployment.png
rename to docs/html/images/vpn-deployment.png
diff --git a/Docs/vpn/vpn-process.png b/docs/html/images/vpn-process.png
similarity index 100%
rename from Docs/vpn/vpn-process.png
rename to docs/html/images/vpn-process.png
diff --git a/docs/html/manual.html b/docs/html/manual.html
new file mode 100644
index 0000000..4da8f96
--- /dev/null
+++ b/docs/html/manual.html
@@ -0,0 +1,733 @@
+
Overview
+
l2tpns is half of a complete L2TP implementation. It supports only the LNS side of the connection.
+
L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2 protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection. l2tpns implements PPP over L2TP only.
+
There are a couple of other L2TP implementations, of which l2tpd is probably the most popular. l2tpd also will handle being either end of a tunnel, and is a lot more configurable than l2tpns. However, due to the way it works, it is nowhere near as scalable.
+
l2tpns uses the TUN/TAP interface provided by the Linux kernel to receive and send packets. Using some packet manipulation it doesn't require a single interface per connection, as l2tpd does.
+
This allows it to scale extremely well to very high loads and very high numbers of connections.
+
It also has a plugin architecture which allows custom code to be run during processing. An example of this is in the walled garden module included.
+
Installation
+
Requirements
+
+
Linux kernel version 2.4 or above, with the Tun/Tap interface either compiled in, or as a module.
+
libcli 1.8.5 or greater. You can get this from SourceForge
+
+
Compiling
+
You can generally get away with just running make from the source directory. This will compile the daemon, associated tools and any modules shipped with the distribution.
+
Installing
+
After you have successfully compiled everything, run make install to install it. By default, the binaries are installed into /usr/sbin, the configuration into /etc/l2tpns, and the modules into /usr/lib/l2tpns.
+
You will definately need to edit the configuration files before you start. See Configuration for more information.
+
Running
+
You only need to run /usr/sbin/l2tpns as root to start it. It does not normally detach to a daemon process (see the -d option), so you should perhaps run it from init.
+
By default there is no log destination set, so all log messages will go to stdout.
+
Configuration
+
All configuration of the software is done from the files installed into /etc/l2tpns.
+
startup-config
+
This is the main configuration file for l2tpns. The format of the file is a list of commands that can be run through the command-line interface. This file can also be written directly by the l2tpns process if a user runs the write memory command, so any comments will be lost. However if your policy is not to write the config by the program, then feel free to comment the file with a # or ! at the beginning of the line.
+
A list of the possible configuration directives follows. Each of these should be set by a line like: set configstring "value" set ipaddress 192.168.1.1 set boolean true
+
+
debug (int)
+
Sets the level of messages that will be written to the log file. The value should be between 0 and 5, with 0 being no debugging, and 5 being the highest. A rough description of the levels is:
+
+
0: Critical Errors
+
Things are probably broken
+
+
1: Errors
+
Things might have gone wrong, but probably will recover
+
+
2: Warnings
+
Just in case you care what is not quite perfect
+
+
3: Information
+
Parameters of control packets
+
+
4: Calls
+
For tracing the execution of the code
+
+
5: Packets
+
Everything, including a hex dump of all packets processed... probably twice
+
+
+
Note that the higher you set the debugging level, the slower the program will run. Also, at level 5 a lot of information will be logged. This should only ever be used for working out why it doesn't work at all.
+
+
log_file (string)
+
This will be where all logging and debugging information is written to. This may be either a filename, such as /var/log/l2tpns, or the special magic string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
+
+
pid_file (string)
+
If set, the process id will be written to the specified file. The value must be an absolute path.
+
+
random_device (string)
+
Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
+
+
l2tp_secret (string)
+
The secret used by l2tpns for authenticating tunnel request. Must be the same as the LAC, or authentication will fail. Only actually be used if the LAC requests authentication.
+
+
l2tp_mtu (int)
+
MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
Whenever a PPP connection is established, DNS servers will be sent to the user, both a primary and a secondary. If either is set to 0.0.0.0, then that one will not be sent.
Sets the RADIUS servers used for both authentication and accounting. If the primary server does not respond, then the secondary RADIUS server will be tried.
+
+
In addition to the source IP address and identifier, the RADIUS server must include the source port when detecting duplicates to suppress (in order to cope with a large number of sessions coming on-line simultaneously l2tpns uses a set of udp sockets, each with a separate identifier).
Sets the authentication ports for the primary and secondary RADIUS servers. The accounting port is one more than the authentication port. If no RADIUS ports are given, the authentication port defaults to 1645, and the accounting port to 1646.
+
+
radius_accounting (boolean)
+
If set to true, then RADIUS accounting packets will be sent. This means that a Start record will be sent when the session is successfully authenticated, and a Stop record will be sent when the session is closed.
+
+
radius_interim (int)
+
If radius_accounting is on, defines the interval between sending of RADIUS interim accounting records (in seconds).
+
+
radius_secret (string)
+
This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
+
+
radius_authtypes (string)
+
A comma separated list of supported RADIUS authentication methods (pap or chap), in order of preference (default pap).
+
+
radius_bind_min (short); radius_bind_max (short)
+
Define a port range in which to bind sockets used to send and receive RADIUS packets. Must be at least RADIUS_FDS (64) wide. Simplifies firewalling of RADIUS ports (default: dynamically assigned).
+
+
radius_dae_port (short)
+
Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
+
+
allow_duplicate_users (boolean)
+
Allow multiple logins with the same username. If false (the default), any prior session with the same username will be dropped when a new session is established.
+
+
guest_account (string)
+
Allow multiple logins matching this specific username.
+
+
bind_address (ip address)
+
When the tun interface is created, it is assigned the address specified here. If no address is given, 1.1.1.1 is used. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
+
+
peer_address (ip address)
+
Address to send to clients as the default gateway.
+
+
send_garp (boolean)
+
Determines whether or not to send a gratuitous ARP for the bind_address when the server is ready to handle traffic (default: true). This value is ignored if BGP is configured.
+
+
throttle_speed (int)
+
Sets the default speed (in kbits/s) which sessions will be limited to. If this is set to 0, then throttling will not be used at all. Note: You can set this by the CLI, but changes will not affect currently connected users.
+
+
throttle_buckets (int)
+
Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
+
+
accounting_dir (string)
+
If set to a directory, then every 5 minutes the current usage for every connected use will be dumped to a file in this directory. Each file dumped begins with a header, where each line is prefixed by #. Following the header is a single line for every connected user, fields separated by a space.
+
The fields are username, ip, qos, uptxoctets, downrxoctets. The qos field is 1 if a standard user, and 2 if the user is throttled.
+
+
dump_speed (boolean)
+
If set to true, then the current bandwidth utilization will be logged every second. Even if this is disabled, you can see this information by running the uptime command on the CLI.
+
+
multi_read_count (int)
+
Number of packets to read off each of the UDP and TUN fds when returned as readable by select (default: 10). Avoids incurring the unnecessary system call overhead of select on busy servers.
+
+
scheduler_fifo (boolean)
+
Sets the scheduling policy for the l2tpns process to SCHED_FIFO. This causes the kernel to immediately preempt any currently running SCHED_OTHER (normal) process in favour of l2tpns when it becomes runnable. Ignored on uniprocessor systems.
+
+
lock_pages (boolean)
+
Keep all pages mapped by the l2tpns process in memory.
+
+
icmp_rate (int)
+
Maximum number of host unreachable ICMP packets to send per second.
+
+
packet_limit (int)
+
Maximum number of packets of downstream traffic to be handled each tenth of a second per session. If zero, no limit is applied (default: 0). Intended as a DoS prevention mechanism and not a general throttling control (packets are dropped, not queued).
+
+
cluster_address (ip address)
+
Multicast cluster address (default: 239.192.13.13). See Clustering for more information.
+
+
cluster_port (udp port)
+
UDP cluster port (default: 32792). See Clustering for more information.
+
+
cluster_interface (string)
+
Interface for cluster packets (default: eth0)
+
+
cluster_mcast_ttl (int)
+
TTL for multicast packets (default: 1).
+
+
cluster_hb_interval (int)
+
Interval in tenths of a second between cluster heartbeat/pings.
+
+
cluster_hb_timeout (int)
+
Cluster heartbeat timeout in tenths of a second. A new master will be elected when this interval has been passed without seeing a heartbeat from the master.
+
+
cluster_master_min_adv (int)
+
Determines the minimum number of up to date slaves required before the master will drop routes (default: 1).
+
+
ipv6_prefix (ipv6 address)
+
Enable negotiation of IPv6. This forms the the first 64 bits of the client allocated address. The remaining 64 come from the allocated IPv4 address and 4 bytes of 0s.
+
+
+
BGP
+
BGP routing configuration is entered by the command: router bgp as where as specifies the local AS number.
+
Subsequent lines prefixed with neighbour peer define the attributes of BGP neighhbours. Valid commands are: neighbour peer remote-as as neighbour peer timers keepalive hold
+
Where peer specifies the BGP neighbour as either a hostname or IP address, as is the remote AS number and keepalive, hold are the timer values in seconds.
+
Access Lists
+
Named access-lists are configured using one of the commands: ip access-list standard name ip access-list extended name
+
Subsequent lines prefixed with permit or deny define the body of the access-list. Standard access-list syntax:
{permit|deny} ip {host|source source-wildcard|any} {host|destination destination-wildcard|any} [fragments]
+
{permit|deny} udp {host|source source-wildcard|any} [{eq|neq|gt|lt} port|range from to] {host|destination destination-wildcard|any} [{eq|neq|gt|lt} port|range from to] [fragments]
+
{permit|deny} tcp {host|source source-wildcard|any} [{eq|neq|gt|lt} port|range from to] {host|destination destination-wildcard|any} [{eq|neq|gt|lt} port|range from to] [{established|{match-any|match-all} {+|-}{fin|syn|rst|psh|ack|urg} ...|fragments]
+
users
+
Usernames and passwords for the command-line interface are stored in this file. The format is username:password where password may either by plain text, an MD5 digest (prefixed by $1salt$) or a DES password, distinguished from plain text by the prefix {crypt}.
+
The username enable has a special meaning and is used to set the enable password.
+
+
If this file doesn't exist, then anyone who can get to port 23 will be allowed access without a username or password.
+
+
ip_pool
+
This file is used to configure the IP address pool which user addresses are assigned from. This file should contain either an IP address or a CIDR network per line. e.g.:
Keep in mind that l2tpns can only handle 65535 connections per process, so don't put more than 65535 IP addresses in the configuration file. They will be wasted.
+
build-garden
+
The garden plugin on startup creates a NAT table called "garden" then sources the build-garden script to populate that table. All packets from gardened users will be sent through this table. Example:
A running l2tpns process can be controlled in a number of ways. The primary method of control is by the Command-Line Interface (CLI).
+
You can also remotely send commands to modules via the nsctl client provided.
+
There are also a number of signals that l2tpns understands and takes action when it receives them.
+
Command-Line Interface
+
You can access the command line interface by telneting to port 23. There is no IP address restriction, so it's a good idea to firewall this port off from anyone who doesn't need access to it. See for information on restricting access based on a username and password.
+
The CLI gives you real-time control over almost everything in the process. The interface is designed to look like a Cisco device, and supports things like command history, line editing and context sensitive help. This is provided by linking with the libcli library. Some general documentation of the interface is here.
+
After you have connected to the telnet port (and perhaps logged in), you will be presented with a hostname> prompt.
+
Enter help to get a list of possible commands, or press ? for context-specific help.
+
A brief overview of the more important commands follows:
+
show session [ID]
+
: Detailed information for a specific session is presented if you specify a session ID argument.
+
If no ID is given, a summary of all connected sessions is produced.
+Note that this summary list can be around 185 columns wide, so you
+should probably use a wide terminal.
+
+The columns listed in the summary are:
+
+ -------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------
+ `SID` Session ID
+ `TID` Tunnel ID See also the [show tunnel](#operation-cli-show-tunnel) CLI command.
+ `Username` The username given in the PPP authentication. If this is \*, then LCP authentication has not completed.
+ `IP` The IP address given to the session. If this is 0.0.0.0, IPCP negotiation has not completed
+ `I` Intercept Y or N: indicates whether the session is being snooped. See also the [snoop](#operation-cli-snoop) CLI command.
+ `T` Throttled Y or N: indicates whether the session is currently throttled. See also the [throttle](#operation-cli-throttle) CLI command.
+ `G` Walled Garden Y or N: indicates whether the user is trapped in the walled garden. This field is present even if the garden module is not loaded.
+ `6` IPv6 Y or N: indicates whether the session has IPv6 active (IPV6CP open)
+ `opened` The number of seconds since the session started
+ `downloaded` Number of bytes downloaded by the user
+ `uploaded` Number of bytes uploaded by the user
+ `idle` The number of seconds since traffic was detected on the session
+ `LAC` The IP address of the LAC the session is connected to.
+ `CLI` The Calling-Line-Identification field provided during the session setup. This field is generated by the LAC.
+ -------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------
+
show users; show user username
+
: With no arguments, display a list of currently connected users. If an argument is given, the session details for the given username are displayed.
+
+
show tunnel [ID]
+
Produce a summary list of all open tunnels, or detail on a specific tunnel ID.
+
The columns listed in the summary are:
+
+
+
+
TID
+
Tunnel ID
+
+
+
Hostname
+
The hostname for the tunnel as provided by the LAC. This has no relation to DNS, it is just a text field.
+
+
+
IP
+
The IP address of the LAC
+
+
+
State
+
Tunnel state: Free, Open, Dieing, Opening
+
+
+
Sessions
+
The number of open sessions on the tunnel
+
+
+
+
+
show pool
+
Displays the current IP address pool allocation. This will only display addresses that are in use, or are reserved for re-allocation to a disconnected user.
+
If an address is not currently in use, but has been used, then in the User column the username will be shown in square brackets, followed by the time since the address was used:
+
IP Address Used Session User
+192.168.100.6 N [joe.user] 1548s
+
+
show radius
+
Show a summary of the in-use RADIUS sessions. This list should not be very long, as RADIUS sessions should be cleaned up as soon as they are used. The columns listed are:
+
+
+
+
Radius
+
The ID of the RADIUS request. This is sent in the packet to the RADIUS server for identification
+
+
+
State
+
The state of the request: WAIT, CHAP, AUTH, IPCP, START, STOP or NULL
+
+
+
Session
+
The session ID that this RADIUS request is associated with
+
+
+
Retry
+
If a response does not appear to the request, it will retry at this time. This is a Unix timestamp
+
+
+
Try
+
Retry count. The RADIUS request is discarded after 3 retries
+
+
+
+
+
show running-config
+
This will list the current running configuration. This is in a format that can either be pasted into the configuration file, or run directly at the command line.
+
+
show counters
+
Internally, counters are kept of key values, such as bytes and packets transferred, as well as function call counters. This function displays all these counters, and is probably only useful for debugging.
+
You can reset these counters by running clear counters.
+
+
show cluster
+
Show cluster status. Shows the cluster state for this server (Master/Slave), information about known peers and (for slaves) the master IP address, last packet seen and up-to-date status. See Clustering for more information.
+
+
write memory
+
This will write the current running configuration to the config file startup-config, which will be run on a restart.
+
+
+
snoop user IP port
+
: You must specify a username, IP address and port. All packets for the current session for that username will be forwarded to the given host/port. Specify no snoop username to disable interception for the session.
+
If you want interception to be permanent, you will have to modify
+the RADIUS response for the user. See [Interception](#interception).
+
throttle user [in|out] rate
+
: You must specify a username, which will be throttled for the current session to rate Kbps. Prefix rate with in or out to set different upstream and downstream rates.
+
Specify `no throttle
+ username` to disable throttling for the current session.
+
+If you want throttling to be permanent, you will have to modify the
+RADIUS response for the user. See [Throttling](#throttling).
+
+
drop session
+
This will cleanly disconnect the session specified by session ID.
+
+
drop tunnel
+
This will cleanly disconnect the tunnel specified by tunnel ID, as well as all sessions on that tunnel.
+
+
uptime
+
This will show how long the l2tpns process has been running, and the current bandwidth utilization:
The current bandwidth going from the LAC to the ethernet (user uploads), in mbits/sec.
+
+
+
ETH-UDP
+
The current bandwidth going from ethernet to the LAC (user downloads).
+
+
+
TOTAL
+
The total aggregate bandwidth in mbits/s.
+
+
+
IN and OUT
+
Packets/per-second going between UDP-ETH and ETH-UDP.
+
+
+
+
These counters are updated every second.
+
+
configure terminal
+
Enter configuration mode. Use exit or ^Z to exit this mode.
+
The following commands are valid in this mode:
+
load plugin name
+
: Load a plugin. You must specify the plugin name, and it will search in /usr/lib/l2tpns for name.so. You can unload a loaded plugin with remove plugin name.
+
+
set ...
+
Set a configuration variable. You must specify the variable name, and the value. If the value contains any spaces, you should quote the value with double (") or single (') quotes.
+
You can set any configuration value in this way, although some may require a restart to take effect. See .
nsctl sends messages to a running l2tpns instance to be control plugins.
+
Arguments are command and optional args. See nsctl(8).
+
Built-in command are load_plugin, unload_plugin and help. Any other commands are passed to plugins for processing by the plugin_control function.
+
Signals
+
While the process is running, you can send it a few different signals, using the kill command.
+
killall -HUP l2tpns
+
The signals understood are:
+
+
SIGHUP
+
Reload the config from disk and re-open log file.
+
+
SIGTERM; SIGINT
+
Stop process. Tunnels and sessions are not terminated. This signal should be used to stop l2tpns on a cluster node where there are other machines to continue handling traffic. See Clustering
+
+
SIGQUIT
+
Shut down tunnels and sessions, exit process when complete.
+
+
+
Throttling
+
l2tpns contains support for slowing down user sessions to whatever speed you desire. The global setting throttle_speed defines the default throttle rate.
+
To throttle a sesion permanently, add a Cisco-AVPair RADIUS attribute. The autothrotle module interprets the following attributes:
+
+
+
+
throttle=yes
+
Throttle upstream/downstream traffic to the configured throttle_speed.
+
+
+
throttle=rate
+
Throttle upstream/downstream traffic to the specified rate Kbps.
+
+
+
`lcp:interface-config#1=service-policy input
+
Alternate (Cisco) format: throttle upstream/downstream to specified rate Kbps.
+
+
+
rate`
+
+
+
+
`lcp:interface-config#2=service-policy output
+
+
+
+
rate`
+
+
+
+
+
You can also enable and disable throttling an active session using the throttle CLI command.
+
Interception
+
You may have to deal with legal requirements to be able to intercept a user's traffic at any time. l2tpns allows you to begin and end interception on the fly, as well as at authentication time.
+
When a user is being intercepted, a copy of every packet they send and receive will be sent wrapped in a UDP packet to a specified host.
+
The UDP packet contains just the raw IP frame, with no extra headers. The script scripts/l2tpns-capture may be used as the end-point for such intercepts, writing the data in PCAP format (suitable for inspection with tcpdump).
+
To enable or disable interception of a connected user, use the snoop and no snoop CLI commands. These will enable interception immediately.
+
If you wish the user to be intercepted whenever they reconnect, you will need to modify the RADIUS response to include the Vendor-Specific value Cisco-AVPair="intercept=ip:port". For this feature to be enabled, you need to have the autosnoop module loaded.
+
Plugins
+
So as to make l2tpns as flexible as possible, a plugin API is include which you can use to hook into certain events.
+
There are a some standard modules included which may be used as examples: autosnoop, autothrottle, garden, sessionctl, setrxspeed, snoopctl, stripdomain and throttlectl.
+
When an event occurs that has a hook, l2tpns looks for a predefined function name in every loaded module, and runs them in the order the modules were loaded.
+
The function should return PLUGIN_RET_OK if it is all OK. If it returns PLUGIN_RET_STOP, then it is assumed to have worked, but that no further modules should be run for this event.
+
A return of PLUGIN_RET_ERROR means that this module failed, and no further processing should be done for this event.
+
+
Use this with care.
+
+
Most event functions take a specific structure named param_event, which varies in content with each event. The function name for each event will be plugin_event, so for the event timer, the function declaration should look like:
+
int plugin_timer(struct param_timer *data);
+
A list of the available events follows, with a list of all the fields in the supplied structure:
+
+
+
+
+
+
+
+
+
Event
+
Description
+
Arguments
+
+
+
+
+
plugin_init
+
Called when the plugin is loaded. A pointer to a struct containing function pointers is passed as the only argument, allowing the plugin to call back into the main code.
+
Prior to loading the plugin, l2tpns checks the API version the plugin was compiled against. All plugins should contain:
+
int
+
plugin_api_version = PLUGIN_API_VERSION;
+
s truct pluginfuncs *
+
+
+
See pluginfuncs structure in plugin.h for available functions.
+
+
+
+
+
plugin_done
+
Called when the plugin is unloaded or l2tpns is shutdown.
+
void
+
+
+
No arguments.
+
+
+
+
+
plugin_pre_auth
+
Called after a RADIUS response has been received, but before it has been processed by the code. This will allow you to modify the response in some way.
+
struct plug in param_pre_auth *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
char *username
+
User name.
+
+
+
+
char *password
+
Password.
+
+
+
+
int protocol
+
Authentication protocol: 0xC023 for PAP, 0xC223 for CHAP.
+
+
+
+
int continue_auth
+
Set to 0 to stop processing authentication modules.
+
+
+
+
plugin_post_auth
+
Called after a RADIUS response has been received, and the basic checks have been performed. This is what the garden module uses to force authentication to be accepted.
+
struct plugi n param_post_auth *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
char *username
+
User name.
+
+
+
+
short auth_allowed
+
Initially true or false depending on whether authentication has been allowed so far. You can set this to 1 or 0 to force authentication to be accepted or rejected.
+
+
+
+
int protocol
+
Authentication protocol: 0xC023 for PAP, 0xC223 for CHAP.
+
+
+
+
plugin_timer
+
Run once per second.
+
struct p lugin param_timer *
+
+
+
time_t time_now
+
The current unix timestamp.
+
+
+
+
plugin_new_session
+
Called after a session is fully set up. The session is now ready to handle traffic.
+
struct plugin param_new_session *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
plugin_kill_session
+
Called when a session is about to be shut down. This may be called multiple times for the same session.
+
struct plugin p aram_kill_session *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
plugin_control
+
Called in whenever a nsctl packet is received. This should handle the packet and form a response if required.
+
Plugin-specific help strings may be included in the output of nsctl help by defining a NULL terminated list of strings as follows:
+
char
+
*plugin_control_hel p[] = { …, NULL };
+
struct plu gin param_control *
+
+
+
int iam_master
+
If true, this node is the cluster master.
+
+
+
+
int argc
+
nsctl arguments.
+
+
+
+
char **argc
+
+
+
+
+
int response
+
Response from control message (if handled): should be either NSCTL_RES_OK or NSCTL_RES_ERR.
+
+
+
+
char *additional
+
Additional information, output by nsctl on receiving the response.
+
+
+
+
plu gin_radius_response
+
Called whenever a RADIUS response includes a Cisco-AVPair value. The value is split into key=value pairs. Will be called once for each pair in the response.
+
struct plugin para m_radius_response *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
char *key
+
Key and value.
+
+
+
+
char *value
+
+
+
+
+
plugin_radius_reset
+
Called whenever a RADIUS CoA request is received to reset any options to default values before the new values are applied.
+
struct p aram_radius_reset *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
pl ugin_radius_account
+
Called when preparing a RADIUS accounting record to allow additional data to be added to the packet.
+
struct par am_radius_account *
+
+
+
tunnelt *t
+
Tunnel.
+
+
+
+
sessiont *s
+
Session.
+
+
+
+
uint8_t **packet
+
Pointer to the end of the currently assembled packet buffer. The value should be incremented by the length of any data added.
+
+
+
+
p lugin_become_master
+
Called when a node elects itself cluster master.
+
void
+
+
+
No arguments.
+
+
+
+
+
plugin _new_session_master
+
Called once for each open session on becoming cluster master.
+
sessiont *
+
+
+
Session.
+
+
+
+
+
+
Walled Garden
+
A "Walled Garden" is implemented so that you can provide perhaps limited service to sessions that incorrectly authenticate.
+
Whenever a session provides incorrect authentication, and the RADIUS server responds with Auth-Reject, the walled garden module (if loaded) will force authentication to succeed, but set the walled_garden flag in the session structure, and adds an iptables rule to the garden_users chain to cause all packets for the session to traverse the garden chain.
+
This doesn't just work. To set this all up, you will to setup the garden nat table with the build-garden script with rules to limit user's traffic.
+
For example, to force all traffic except DNS to be forwarded to 192.168.1.1, add these entries to your build-garden script:
l2tpns will add entries to the garden_users chain as appropriate.
+
You can check the amount of traffic being captured using the following command:
+
iptables -t nat -L garden -nvx
+
Filtering
+
Sessions may be filtered by specifying Filter-Id attributes in the RADIUS reply. filter.in specifies that the named access-list filter should be applied to traffic from the customer, filter.out specifies a list for traffic to the customer.
+
Clustering
+
An l2tpns cluster consists of one* or more servers configured with the same configuration, notably the multicast cluster_address and the cluster_port
+
*A stand-alone server is simply a degraded cluster.
+
Initially servers come up as cluster slaves, and periodically (every cluster_hb_interval/10 seconds) send out ping packets containing the start time of the process to the multicast cluster_address on cluster_port.
+
A cluster master sends heartbeat rather than ping packets, which contain those session and tunnel changes since the last heartbeat.
+
When a slave has not seen a heartbeat within cluster_hb_timeout/10 seconds it "elects" a new master by examining the list of peers it has seen pings from and determines which of these and itself is the "best" candidate to be master. "Best" in this context means the server with the highest uptime (the highest IP address is used as a tie-breaker in the case of equal uptimes).
+
After discovering a master, and determining that it is up-to-date (has seen an update for all in-use sessions and tunnels from heartbeat packets) will raise a route (see Routing) for the bind_address and for all addresses/networks in ip_pool.
+
Any packets recieved by the slave which would alter the session state, as well as packets for throttled or gardened sessions are forwarded to the master for handling. In addition, byte counters for session traffic are periodically forwarded.
+
The master, when determining that it has at least one* up-to-date slave will drop all routes (raising them again if all slaves disappear) and subsequently handle only packets forwarded to it by the slaves.
+
*Configurable with cluster_master_min_adv
+
Multiple clusters can be run on the same network by just using different multicast cluster_address. However, for a given host to be part of multiple clusters without mixing the clusters, cluster_port must be different for each cluster.
+
Routing
+
If you are running a single instance, you may simply statically route the IP pools to the bind_address (l2tpns will send a gratuitous arp).
+
For a cluster, configure the members as BGP neighbours on your router and configure multi-path load-balancing. Cisco uses maximum-paths ibgp for IBGP. If this is not supported by your IOS revision, you can use maximum-paths (which works for EBGP) and set as_number to a private value such as 64512.
diff --git a/docs/html/practical-vpns.html b/docs/html/practical-vpns.html
new file mode 100644
index 0000000..6b0af2b
--- /dev/null
+++ b/docs/html/practical-vpns.html
@@ -0,0 +1,305 @@
+
Overview of VPNs and IPsec
+
Virtual Private Networks
+
The purpose of a VPN is to create a secure channel ontop of an un-secure medium, where a computer or a device are put in each end-point in order to establish communication, each of these end-points are often reffered to as Point of Presense, or POP. This kind of a communication allows the capability of creating a Virtual Private Network, which is accesable over a medium such as the Internet and thus, extend the physical boundaries of an existing local network.
+
VPNs have three forms:
+
+
Site-To-Site VPNs
+
these setups exist in order to extend the local network to create a much bigger LAN over the Internet.
+
+
Network-To-Host or Remote access VPNs
+
where a central VPN server is able to achieve multiple connections, often reffered to as RoadWarrior VPNs. (This setup is very common among ISPs)
+
+
Network-To-Network
+
extranet VPNs allow secure connections within branches and business partners, they are an extension of a Site-To-Site VPNs.
+
+
+
+shows a Site-To-Site VPN diagram.
+
IP/VPNs are connections which are based upon IP tunnels. A tunnel is a way to encapsulate an IP packet inside another IP packet or some other type of packet. Why do we need tunneling? A Virtual Private Network is identified by IANA's private IP assignments and so such packet can not go beyond the uplink Internet interface.
+
+shows the tunneling process.
+
Several tunneling protocols are available for manifesting VPNs.
+
+
L2F
+
Layer 2 Forwarding, an older implementation which assume position at the link layer of the OSI. It has no encryption capabilities and hence, deprecated.
+
+
L2TP
+
Layer 2 Tunneling Protocol, still no encryption capabilities.
+
+
PPTP
+
Point-to-Point Tunneling Protocol, and yet again, no encryption.
+
+
+
As seen, the requirement of encryption enhancement is urgent in order to assure authentication, data integrity and privacy. IPsec solves this by providing a suite of security measures implemented at layer 3.
+
IP Security Suite (IPsec)
+
VPN Security is now appearing, this complex things. How so? VPN tunnels by themselves are easily maintained by single-standalone tools like pppd, l2tpns, stunnel and others. Involving security with VPNs though requires more:
+
+
authentication, data integrity and privacy
+
keying management
+
+
+
Keys are secrets being shared by two end-points to provide a secure mean of communication against a third-party connection from sniffing the actual data.
+
+
Different ways to handle key management include RADIUS (Remote Authentication Dial In User Service) systems which provide AAA (Authentication, Authorization and Accounting). Another solution is ISAKMP/Oackly - Internet Security Association and Key Management Protocol. This solution requires you to posess one of the following:
+
+
something you have
+
something you know
+
something you are
+
+
The more requirements you meet the more secure is the medium, once established. Let's review, something we have is like a certificate, it proves who we are. Something we know, is a key, a secret password which we were told in a whisper, and something we are is our-fingerprint which identifies ourselves from other individuals.
+
IPsec in Depth
+
IPsec consists of two main protocols, an Authentication Header and Encapsulation Security Payload, also known as AH and ESP. Although it is not bound to these and can be extended (and often is) to other standarts such as
+
+
Data Encryption Standart (DES and 3DES)
+
Diffie-Hellman (DH)
+
Secure Hash Algorithm-1 (SHA1)
+
Message Digest 5 (MD5)
+
Internet Key Exchange (IKE)
+
Certification Authorities (CA)
+
+
We'll be deploying an IKE daemon to handle the key management, which uses the Diffie- Hellman cryptography protocol in order to allow two parties to establish a connection based upon a shared secret key that both parties posess. (Authentication within IKE is handled by MD5 hashing)
+
IKE is responsible for authentication of two IPsec parties, negotiation of keys for encryption algorithms and security associations. This process is commonly regarded as two phases:
+
+
Phase 1: IKE Security Association
+
The IKE daemon authenticates against the peers in order to achieve a secure channel, according to the Diffie-Hellman key agreement.
+
+
Phase 2: IKE IPsec Negotiation
+
After achieving an authenticated channel, the parties now negotiate a secure transform (the way to encrypt and secure the medium) where the sender is offering his/hers transform set after which the receiver decides upon one. An IPsec session can now safely begin.
+
+
+
Just to be clear, a Security Association is an agreed relation between two parties which describes how they will use security services (from IPsec) to communicate.
+
IPsec Modes
+
IPsec can operate in two different modes:
+
+
Transport mode
+
takes place when two devices (like a station and a gateway (now considered a host)) are establishing a connection which upon they both support IPsec.
+
+
Tunnel mode
+
we require tunnel mode when we proxy IPsec connetions between two stations behind the IPsec gateway. For example, in a Site-to-Site VPN a tunnel mode lives, since it exists in order to provide the stations behind these gateways runing the VPN/IPsec to communicate securely. In this situation, both end-points are runing an IPsec software.
+
+
+
In definition, a tunnel mode IPsec is better secured than transport. Without going too deep into the ins-and-outs of the technical side, transport mode doesn't encapsulate the actual IP layer but only the tcp/udp (Transport layer of the OSI) where-as a tunnel mode encapsulate both the Transport layer and the IP layer into a new IP packet.
+
To summarize, we need VPNs for data-exchange methods and a set of IPsec tools for security reasons.
+
VPN Deployment
+
I've assembled another diagram to view the actual VPN setup.
+
+gives a general description of how the network will be layed out in real-world scenario.
+
We notice that a single Linux box is acting as a Gateway and has all the services included with it. This is a bad idea from a security prespective but it's easy to just deploy the FreeRADIUS and MySQL servers on another machine. Of course the L2TPns and the rest of the IPsec tools suite would have to remain on the Gateway box (not necessarily the Firewall).
+
+attempts to explain the actual process that the VPN takes and to detail the place that each of that application-in-charge takes place.
+
Requirements
+
The Toolbox
+
Following is a description of the requirements you will have to meet:
+
+
A Linux box
+
preferably a 2.4.27 kernel or higher.
+
Debian is the chosen distribution which means we'll be using apt-get for installation, but I'll also focus on basic source tarballs installation.
+
Dependencies:
+
+
ipsec configuration in the kernel
+
+
+
L2TPns
+
an L2TP PPP Termination tool.
+
Dependencies:
+
+
libcli 1.8.0 or greater
+
tun/tap interface compiled in the kernel or as a module
+
+
+
FreeRADIUS
+
For authentication, and accounting.
+
+
MySQL
+
To act as a back-end database for the RADIUS.
+
+
OpenSwan
+
Provides the ipsec suite package.
+
+
+
Kernel Support
+
Debian stock kernel 2.4.27 and up are ipsec compatible although if you think otherwise check for the kernel-patch-openswan package.
+
Installation
+
L2TPns
+
Installation
+
+
L2TPns is a layer 2 tunneling protocol network server (LNS). It supports up to 65535 concurrent sessions per server/cluster plus ISP features such as rate limiting, walled garden, usage accounting, and more.
+
+
In a personal note - L2TPns is highly configurable for many cases, and extremely reliable for production/commerical use.
+
+
Step 1:
+
Make sure you have libcli-1.8 development package installed:
Alternately, you can skip these steps and simply apt-get install l2tpns.
+
+
+
On RPM-based distributions, you should be able to make packages from the libcli and l2tpns source tarballs with rpmbuild -ta.
+
+
Once compiliation is done you will have l2tpns in /usr/sbin/l2tpns, and all configuration files can be found in /etc/l2tpns/.
+
Configuration
+
The only configuration that L2TPns takes is centralized in the configuration file /etc/l2tpns/startup-config.
+
set debug 2 # Debugging level
+set log_file "/var/log/l2tpns" # Log file: comment out to use stderr, use
+ # "syslog:facility" for syslog
+set pid_file "/var/run/l2tpns.pid" # Write pid to this file
+set l2tp_secret "secret" # shared secret
+set primary_dns 212.117.128.6 # Only 2 DNS server entries are allowed
+set secondary_dns 212.117.129.3
+set primary_radius 192.168.0.1 # Can have multiple radius server entries,
+ # but ony one radius secret
+set primary_radius_port 1812
+set radius_secret "radius_secret"
+set radius_accounting yes
+set radius_dae_port 3799
+set accounting_dir "/var/run/l2tpns/acct" # Write usage accounting files into specified
+ # directory
+set peer_address 192.168.0.1 # Gateway address given to clients
+load plugin "sessionctl" # Drop/kill sessions
+load plugin "autothrottle" # Throttle/snoop based on RADIUS
+load plugin "throttlectl" # Control throttle/snoop with nsctl
+load plugin "snoopctl"
+
This is the trimmed down version of probably most of the common configuration and even some extra options.
+
Important configuration options are highlited and you should adjust these to meet your network needs. We can deploy all of the environment into one box which is of course not a very good idea from a security point of view, but will function just fine. Moreover, we will be using aliased IP addresses so once you've decided to move the FreeRADIUS daemon to another computer on the LAN it will be fairly easy and won't take too much configuration into it.
+
Next, we need to setup the IP pool that L2TPns will provide to each VPN client. The configuration file is located at /etc/l2tpns/ip_pool and should look like the following:
+
172.16.21.0/24
+
+
Of course you can change this pool to anything else (IANA IPs assigned for private internets only) just make sure it is not conflicting with your current LAN network addresses. This means that if you've assigned addresses of 192.168.0.1 and 192.168.0.2 to your LAN boxes you can't have a pool of 192.168.0.1/24 defined since L2TPns will try to route those addresses from the tun device, which is needless to say a bad idea...
+
+
Next up, creating the access-list for L2TPns.
+
Add a username and password into /etc/l2tpns/users:
+
admin:12345
+
The password may either be plain-text as above, or encrypted with MD5 or DES (to distinguish DES from plain-text passwords, prefix the value with {crypt}).
+
L2TPns utilizes a terminal connection on port 23 which you would feel very comfortable in if you have worked with routers and switches devices before. The terminal provides control over the ppp termination which is why we've created an account to log on to.
+
IPsec
+
Installation
+
User-space IPsec tools for various IPsec implementations exist for linux, among them is the port of KAME's libipsec, setkey, and racoon. Others are the OpenSWAN (a successor to the FreeSWAN project).
+
Getting IPsec installed is fairly easy with Debian:
+
# apt-get install openswan
+
The OpenSWAN project provides packages for RPM-based distributions.
+
Alternately, you may download the source from the OpenSWAN project:
+
# tar xvzf openswan-2.4.4.tar.gz
+# cd openswan-2.4.4
+# ./configure && make && make install
+
Configuration
+
OpenSWAN acts as the IKE daemon (remember IKE? it's job is to authenticate between the two peers and negotiate a secure medium). We will be setting up the IKE daemon as a RoadWarrior configuration, a term for remote access VPNs.
+
We desire this approach for compatibilty because after our VPN solution will be complete any user from a Windows machine will be easily ready to connect without any 3rd party applications, same for Linux.
+
Configuration files are placed in /etc/ipsec.d/, /etc/ipsec.conf and /etc/ipsec.secrets.
+
Let's start by choosing the remote client and it's PSK (Private Shared Key) /etc/ipsec.secrets:
This is an IP/key pair. The IP or FQDN defines the local peer (like a SOHO branch), then the remote host. Here we defined %any for all hosts, though it's possible to define only a specific IP. At last, we define the key associated with it.
+
A better way to create a key is to utilize /dev/random for creating a unique key.
In this file we have first defined version 2 which is a must, then enabled NAT Traversal. To understand the importance of this feature think of the following scenario: A remote user attempts to connect while he's behind a router and therefore NATed. The router has to de-encapsulate the packet, change things and then build it up again and send it. IPsec doesn't like other people messing with it's packet. That's why we solve this issue with NAT Traversal.
+
Next up we configure authentication type (certificates, psk, rsa keys, etc) then the left and right peers. The default mode OpenSWAN takes is tunnel unless told otherwise. I won't go into in-depth explanation of every method, you can take a quick look at /etc/ipsec.d/examples for more explanation and other variations of working with RSA keys, Certificates, host-to-host, and more.
+
In summary:
+
+
We've configured an almost complete IPsec VPN setup.
+
We've installed and configured a VPN server (L2TPns) and our IPsec security suite.
+
To control both of them we use: /etc/init.d/l2tpns and /etc/init.d/racoon (location of start-up scripts may vary on non-Debian systems, or if you've installed from source).
+
+
FreeRADIUS
+
The VPN setup needs to authenticate against something, that is the users database which we chose to be a FreeRADIUS server backed with a MySQL database.
+
Installation
+
+
FreeRADIUS is the premiere open source RADIUS server. While detailed statistics are not available, we believe that FreeRADIUS is well within the top 5 RADIUS servers world-wide, in terms of the number of people who use it daily for authentication. It scales from embedded systems with small amounts of memory, to systems with millions of users. It is fast, flexible, configurable, and supports more authentication protocols than many commercial servers.
+
+
Installing on Debian:
+
# apt-get install freeradius freeradius-mysql
+
From source: Download the latest freeradius package from freeradius.org
+
# tar xvzf freeradius.tar.gz
+# cd freeradius
+# ./configure && make && make install
+
Configuration
+
This will appear a bit complex but it isn't, it's just a lot of configuration.
+
Following are the configurations you need to have in your /etc/freeradius/ files.
+
In this section I will not give you a dump of the configuration since they are very long and mostly default. I'll just post which changes to make.
+
We haven't yet configured MySQL, but it'll come afterwards, don't worry.
+
Make the following changes to the file /etc/freeradius/sql.conf:
+
server = "192.168.0.1"
+login = "radius"
+password = "12345678"
+
Add the following to the file /etc/freeradius/clients.conf:
Don't confuse the secret directive there with IPsec. RADIUS server are using secret keys also to identify their allowed NAS (Network Access Servers), these are the clients that talk to the RADIUS server.
+
Also, change the client 127.0.0.1 {} directive to hold the secret "my_secret" like we configured for 192.168.0.1 to avoid conflicts.
+
Uncomment the sql directive in the authorize, accounting, and session sections of /etc/freeradius/radiusd.conf.
+
Now for populating FreeRADIUS with MySQL. If you don't know or haven't set root password for MySQL you can do it now with:
Create the radius database, using the schema given in /usr/share/doc/freeradius/examples/db_mysql.sql.gz.
+
+
It may be necessary to modify the column definition of id in the nas table, removing DEFAULT '0' such that the definition reads:
+
id int(10) NOT NULL auto_increment,
+
+
# mysqladmin create radius
+# mysql radius
+mysql> source db_mysql.sql
+mysql> GRANT ALL ON * TO 'radius'@'localhost' IDENTIFIED BY 'radius_password';
+
All the configuration is now done. Let's add a user to our VPN database.
+
# mysql radius
+mysql> INSERT INTO radcheck values (0, "test", "User-Password", "==", "1234");
+
We have now created a user in the database of username test and password 1234.
+
Testing the RADIUS setup is simple using the radtest utility provided with it.
+
# radtest
+Usage: radtest user passwd radius-server[:port] nas-port-number secret [ppphint] [nasname]
+# radtest test 1234 192.168.0.1 1812 my_secret
+
radtest sends an Access-Request to the RADIUS server and expects an Access-Accept back from it. If you're not getting an Access-Accept from the RADIUS you're advised to check the configuration again and see what you might have missed.
+
Firewall Configuration
+
We need to apply a few things to iptables configuration and kernel networking.
+
First off, we need to accept VPN-specific packets through the firewall. Of course you will have to adjust the rules to fits you needs, in this case, ppp0 is the Internet interface.
If you haven't setup your Linux box as a gateway yet then you have to allow forwarding/masqing for the boxes on the LAN (and therefore for the VPN clients):
diff --git a/docs/manpages/l2tpns.8 b/docs/manpages/l2tpns.8
new file mode 100644
index 0000000..5c12533
--- /dev/null
+++ b/docs/manpages/l2tpns.8
@@ -0,0 +1,181 @@
+.SH NAME
+.PP
+l2tpns - Layer 2 tunneling protocol network server (LNS)
+.SH SYNOPSIS
+.PP
+\f[B]l2tpns\f[R] [-\f[B]d\f[R]] [-\f[B]v\f[R]] [-\f[B]c\f[R]
+\f[I]file\f[R]] [-\f[B]h\f[R] \f[I]hostname\f[R]]
+.SH DESCRIPTION
+.PP
+\f[B]l2tpns\f[R] is a daemon for terminating layer 2 tunneling protocol
+(L2TP: RFC2661) sessions.
+.PP
+\f[B]l2tpns\f[R] is a complete L2TP implementation.
+It supports the LAC, LNS, PPPOE and DHCPv6 server.
+.PP
+Once running, \f[B]l2tpns\f[R] may be controlled by telnetting to port
+23 on the machine running the daemon and with the \f[B]nsctl\f[R]
+utility.
+.SH OPTIONS
+.IP \[bu] 2
+\f[B]-d\f[R] Detach from terminal and fork into the background.
+By default l2tpns will stay in the foreground.
+.RS 2
+.PP
+\&.
+.RE
+.IP \[bu] 2
+\f[B]-v\f[R] Increase verbosity for debugging.
+Can be used multiple times.
+.RS 2
+.PP
+\&.
+.RE
+.IP \[bu] 2
+\f[B]-c\f[R] \f[I]file\f[R]
+.RS 2
+.PP
+Specify configuration file.
+.RE
+.IP \[bu] 2
+\f[B]-h\f[R] \f[I]hostname\f[R]
+.RS 2
+.PP
+Force hostname to \f[I]hostname\f[R].
+.RE
+.SH FILES
+.IP \[bu] 2
+\f[I]/etc/l2tpns/startup-config\f[R]
+.RS 2
+.PP
+The default configuration file.
+.RE
+.IP \[bu] 2
+\f[I]/etc/l2tpns/ip_pool\f[R]
+.RS 2
+.PP
+IP address pool configuration.
+.RE
+.IP \[bu] 2
+\f[I]/etc/l2tpns/users\f[R]
+.RS 2
+.PP
+Username/password configuration for access to admin interface.
+.RE
+.SH SIGNALS
+.IP \[bu] 2
+\f[B]SIGHUP\f[R] Reload the config from disk and re-open log file.
+.RS 2
+.PP
+\&.
+.RE
+.IP \[bu] 2
+\f[B]SIGTERM\f[R], \f[B]SIGINT\f[R]
+.RS 2
+.PP
+Stop process.
+Tunnels and sessions are not terminated.
+This signal should be used to stop l2tpns on a cluster node where there
+are other machines to continue handling traffic.
+.RE
+.IP \[bu] 2
+\f[B]SIGQUIT\f[R]
+.RS 2
+.PP
+Shut down tunnels and sessions, exit process when complete.
+.RE
+.SH MANAGED RADIUS ATTRIBUTE
+.IP \[bu] 2
+\f[B]Ascend-Client-Primary-DNS\f[R],
+\f[B]Ascend-Client-Secondary-DNS\f[R]
+.RS 2
+.PP
+Specifies a primary and secondary DNS server address to send to user.
+.RE
+.IP \[bu] 2
+\f[B]Delegated-IPv6-Prefix\f[R]
+.RS 2
+.PP
+Assign a network address IPv6 prefix to a user by DHCPv6.
+.RE
+.IP \[bu] 2
+\f[B]Framed-IP-Address\f[R]
+.RS 2
+.PP
+The address to be configured for the user (IPv4 address of the interface
+ppp).
+.RE
+.IP \[bu] 2
+\f[B]Framed-Route\f[R]
+.RS 2
+.PP
+provides routing information to be configured for the user.
+.RE
+.IP \[bu] 2
+\f[B]Framed-IPv6-Route\f[R]
+.RS 2
+.PP
+Has the same action as \f[B]Delegated-IPv6-Prefix\f[R].
+\f[B]Delegated-IPv6-Prefix\f[R] is the correct one to use.
+.RE
+.IP \[bu] 2
+\f[B]Framed-IPv6-Address\f[R]
+.RS 2
+.PP
+IPv6 address to be assigned to the user by DHCPv6 (IPv6 address of the
+interface ppp).
+.RE
+.IP \[bu] 2
+\f[B]Idle-Timeout\f[R]
+.RS 2
+.PP
+disconnects the session if no data for more than \f[B]Idle-Timeout\f[R]
+(in seconds).
+.RE
+.IP \[bu] 2
+\f[B]Session-Timeout\f[R]
+.RS 2
+.PP
+disconnects the user session when the time \f[B]Session-Timeout\f[R] is
+reached (in seconds).
+.RE
+.IP \[bu] 2
+\f[B]Tunnel-Type\f[R], \f[B]Tunnel-Medium-Type\f[R],
+\f[B]Tunnel-Server-Endpoint\f[R], \f[B]Tunnel-Password\f[R],
+\f[B]Tunnel-Assignment-Id\f[R]
+.RS 2
+.PP
+attributes returned by the Radius of the remote LNS server (LAC
+functionality).
+.PP
+example, Radius that return the information of 2 remote LNS server with
+which must be open a L2TP TUNNEL:
+.IP \[bu] 2
+\f[B]Tunnel-Type\f[R]: 1 = L2TP
+.IP \[bu] 2
+\f[B]Tunnel-Medium-Type\f[R]: 1 = IPv4
+.IP \[bu] 2
+\f[B]Tunnel-Password\f[R]: 1 = \[lq]TheSecretL2TP\[rq]
+.IP \[bu] 2
+\f[B]Tunnel-Server-Endpoint\f[R]: 1 = \[lq]88.xx.xx.x1\[rq]
+.IP \[bu] 2
+\f[B]Tunnel-Assignment-Id\f[R]: 1 = \[lq]friendisp_lns1\[rq]
+.IP \[bu] 2
+\f[B]Tunnel-Type\f[R]: 2 = L2TP
+.IP \[bu] 2
+\f[B]Tunnel-Medium-Type\f[R]: 2 = IPv4
+.IP \[bu] 2
+\f[B]Tunnel-Password\f[R]: 2 = \[lq]TheSecretL2TP\[rq]
+.IP \[bu] 2
+\f[B]Tunnel-Server-Endpoint\f[R]: 2 = \[lq]88.xx.xx.x2\[rq]
+.IP \[bu] 2
+\f[B]Tunnel-Assignment-Id\f[R]: 2 = \[lq]friendisp_lns2\[rq]
+.RE
+.SH SEE ALSO
+.PP
+\f[B]startup-config\f[R](5), \f[B]nsctl\f[R](8)
+.SH AUTHOR
+.PP
+This manual page was written by Jonathan McDowell and
+Fernando Alves (fendo\[at]sameswifi.fr), for the Debian GNU/Linux system
+(but may be used by others).
diff --git a/docs/manpages/nsctl.8 b/docs/manpages/nsctl.8
new file mode 100644
index 0000000..de2c939
--- /dev/null
+++ b/docs/manpages/nsctl.8
@@ -0,0 +1,51 @@
+.SH NAME
+.PP
+nsctl - manage running l2tpns instance
+.SH SYNOPSIS
+.PP
+\f[B]nsctl\f[R] [\f[B]-d\f[R]] [\f[B]-h\f[R]
+\f[I]host\f[R][:\f[I]port\f[R]]] [\f[B]-t\f[R] \f[I]timeout\f[R]]
+\f[I]command\f[R] [\f[I]arg\f[R] ...]
+.SH DESCRIPTION
+.PP
+\f[B]nsctl\f[R] sends commands to a running \f[B]l2tpns\f[R] process.
+It provides both for the loading or unloading of plugins and also the
+management of sessions via functions provided by those plugins.
+.SH OPTIONS
+.TP
+\f[B]-d\f[R]
+Enable debugging output.
+.TP
+\f[B]-h \f[BI]host\f[B][:\f[BI]port\f[B]]\f[R]
+The host running \f[B]l2tpns\f[R] that should receive the message.
+By default the message is sent to UDP port 1702 on \f[B]localhost\f[R].
+.TP
+\f[B]-t \f[BI]timeout\f[B]\f[R]
+Timeout in seconds to wait for a response from the server.
+.SH COMMANDS
+.PP
+The first argument specifies the command to send to \f[B]l2tpns .\f[R]
+The following commands are as defined:
+.TP
+\f[B]load_plugin \f[R]\f[I]plugin\f[R]
+Load the named \f[I]plugin\f[R].
+.TP
+\f[B]unload_plugin \f[R]\f[I]plugin\f[R]
+Unload the named \f[I]plugin\f[R].
+.TP
+\f[B]help\f[R]
+Each loaded plugin is queried for what commands it supports and the
+synopsis for each is output.
+.PP
+Any other value of \f[I]command\f[R] (and \f[I]args\f[R] if any) are
+sent to \f[B]l2tpns\f[R] as-is, to be passed to each plugin which
+registers a \f[B]plugin_control\f[R] function in turn (in which it may
+be acted upon).
+.SH SEE ALSO
+.PP
+\f[B]l2tpns\f[R](8)
+.SH AUTHOR
+.PP
+This manual page was written by Jonathan McDowell
+, for the Debian GNU/Linux system (but may be
+used by others).
diff --git a/docs/manpages/startup-config.5 b/docs/manpages/startup-config.5
new file mode 100644
index 0000000..168f7a1
--- /dev/null
+++ b/docs/manpages/startup-config.5
@@ -0,0 +1,682 @@
+.SH NAME
+.PP
+startup-config - configuration file for l2tpns
+.SH SYNOPSIS
+.PP
+/etc/l2tpns/startup-config
+.SH DESCRIPTION
+.PP
+\f[B]startup-config\f[R] is the configuration file for \f[B]l2tpns\f[R]
+.PP
+The format is plain text, in the same format as accepted by the
+configuration mode of l2tpns\[cq]s telnet administrative interface.
+Comments are indicated by either the character # or !.
+.SS SETTINGS
+.PP
+Settings are specified with
+.IP \[bu] 2
+\f[B]set\f[R] \f[C]variable\f[R] \f[C]value\f[R]
+.PP
+A list of the possible configuration directives follows.
+Each of these should be set by a line like:
+.IP \[bu] 2
+\f[B]set\f[R] \f[I]configstring\f[R] \f[I]\[lq]value\[rq]\f[R]
+.IP \[bu] 2
+\f[B]set\f[R] \f[I]ipaddress\f[R] \f[I]192.168.1.1\f[R]
+.IP \[bu] 2
+\f[B]set\f[R] \f[I]boolean\f[R] \f[I]true\f[R]
+.PP
+The following \f[C]variables\f[R] may be set:
+.IP \[bu] 2
+\f[B]accounting_dir\f[R] (string)
+.RS 2
+.PP
+If set to a directory, then every 5 minutes the current usage for every
+connected use will be dumped to a file in this directory.
+Each file dumped begins with a header, where each line is prefixed by #.
+Following the header is a single line for every connected user, fields
+separated by a space.
+.PP
+The fields are username, ip, qos, uptxoctets, downrxoctets, origin
+(optional).
+The qos field is 1 if a standard user, and 2 if the user is throttled.
+The origin field is dump if \f[B]account_all_origin\f[R] is set to true
+(origin value: L=LAC data, R=Remote LNS data, P=PPPOE data).
+.RE
+.IP \[bu] 2
+\f[B]account_all_origin\f[R] (boolean)
+.RS 2
+.PP
+If set to true, all origin of the usage is dumped to the accounting file
+(LAC+Remote LNS+PPPOE)(default false).
+.RE
+.IP \[bu] 2
+\f[B]allow_duplicate_users\f[R] (boolean)
+.RS 2
+.PP
+Allow multiple logins with the same username.
+If false (the default), any prior session with the same username will be
+dropped when a new session is established.
+.RE
+.IP \[bu] 2
+\f[B]auth_tunnel_change_addr_src\f[R] (boolean)
+.RS 2
+.PP
+This parameter authorize to change the source IP of the tunnels l2tp.
+This parameter can be used when the remotes BAS/LAC are l2tpns server
+configured in cluster mode, but that the interface to remote LNS are not
+clustered (the tunnel can be coming from different source IP) (default:
+no).
+.RE
+.IP \[bu] 2
+\f[B]bind_address\f[R] (ip address)
+.RS 2
+.PP
+It\[cq]s the listen address of the l2tp udp protocol sent and received
+to LAC.
+This address is also assigned to the tun interface if no iftun_address
+is specified.
+Packets containing user traffic should be routed via this address if
+given, otherwise the primary address of the machine.
+.RE
+.IP \[bu] 2
+\f[B]bind_multi_address\f[R] (ip address)
+.RS 2
+.PP
+This parameter permit one to listen several address of the l2tp udp
+protocol (and set several address to the tun interface).
+.PP
+WHEN this parameter is set, It OVERWRITE the parameters
+\[lq]bind_address\[rq] and \[lq]iftun_address\[rq].
+.PP
+these can be interesting when you want do load-balancing in cluster mode
+of the uploaded from the LAC.
+For example you can set a bgp.prepend(MY_AS) for Address1 on LNS1 and a
+bgp.prepend(MY_AS) for Address2 on LNS2 (see BGP AS-path prepending).
+.PP
+example of use with 2 address:
+.PP
+\f[B]set\f[R] \f[I]bind_multi_address\f[R] \[lq]64.14.13.41,
+64.14.13.42\[rq]
+.RE
+.IP \[bu] 2
+\f[B]cluster_address\f[R] (ip address)
+.RS 2
+.PP
+Multicast cluster address (default: 239.192.13.13).
+See the section on Clustering for more information.
+.RE
+.IP \[bu] 2
+\f[B]Bcluster_port\f[R] (int)
+.RS 2
+.PP
+UDP cluster port (default: 32792).
+See the section on Clustering for more information.
+.RE
+.IP \[bu] 2
+\f[B]cluster_interface\f[R] (string)
+.RS 2
+.PP
+Interface for cluster packets (default: eth0).
+.RE
+.IP \[bu] 2
+\f[B]cluster_mcast_ttl\f[R] (int)
+.RS 2
+.PP
+TTL for multicast packets (default: 1).
+.RE
+.IP \[bu] 2
+\f[B]cluster_hb_interval\f[R] (int)
+.RS 2
+.PP
+Interval in tenths of a second between cluster heartbeat/pings.
+.RE
+.IP \[bu] 2
+\f[B]cluster_hb_timeout\f[R] (int)
+.RS 2
+.PP
+Cluster heartbeat timeout in tenths of a second.
+A new master will be elected when this interval has been passed without
+seeing a heartbeat from the master.
+.RE
+.IP \[bu] 2
+\f[B]cluster_master_min_adv\f[R] (int)
+.RS 2
+.PP
+Determines the minimum number of up to date slaves required before the
+master will drop routes (default: 1).
+.RE
+.IP \[bu] 2
+\f[B]debug\f[R] (int)
+.RS 2
+.PP
+Set the level of debugging messages written to the log file.
+The value should be between 0 and 5, with 0 being no debugging, and 5
+being the highest.
+A rough description of the levels is:
+\[bu] .RS 2
+.IP "0." 3
+Critical Errors - Things are probably broken
+.RE
+\[bu] .RS 2
+.IP "1." 3
+Errors - Things might have gone wrong, but probably will recover
+.RE
+\[bu] .RS 2
+.IP "2." 3
+Warnings - Just in case you care what is not quite perfect
+.RE
+\[bu] .RS 2
+.IP "3." 3
+Information - Parameters of control packets
+.RE
+\[bu] .RS 2
+.IP "4." 3
+Calls - For tracing the execution of the code
+.RE
+\[bu] .RS 2
+.IP "5." 3
+Packets - Everything, including a hex dump of all packets processed\&...
+probably twice
+.RE
+.PP
+Note that the higher you set the debugging level, the slower the program
+will run.
+Also, at level 5 a LOT of information will be logged.
+This should only ever be used for working out why it doesn\[cq]t work at
+all.
+.RE
+.IP \[bu] 2
+\f[B]dump_speed\f[R] (boolean)
+.RS 2
+.PP
+If set to true, then the current bandwidth utilization will be logged
+every second.
+Even if this is disabled, you can see this information by running the
+uptime command on the CLI.
+.RE
+.IP \[bu] 2
+\f[B]disable_sending_hello\f[R] (boolean)
+.RS 2
+.PP
+Disable l2tp sending HELLO message for Apple compatibility.
+Some OS X implementation of l2tp no manage the L2TP \[lq]HELLO
+message\[rq].
+(default: no).
+.RE
+.IP \[bu] 2
+\f[B]echo_timeout\f[R] (int)
+.RS 2
+.PP
+Time between last packet sent and LCP ECHO generation (default: 10
+(seconds)).
+.RE
+.IP \[bu] 2
+\f[B]guest_account\f[R]
+.RS 2
+.PP
+Allow multiple logins matching this specific username.
+.RE
+.IP \[bu] 2
+\f[B]icmp_rate\f[R] (int)
+.RS 2
+.PP
+Maximum number of host unreachable ICMP packets to send per second.
+.RE
+.IP \[bu] 2
+\f[B]idle_echo_timeout\f[R] (int)
+.RS 2
+.PP
+Drop sessions who have not responded within idle_echo_timeout seconds
+(default: 240 (seconds))
+.RE
+.IP \[bu] 2
+\f[B]iftun_address\f[R] (ip address)
+.RS 2
+.PP
+This parameter is used when you want a tun interface address different
+from the address of \[lq]bind_address\[rq] (For use in cases of specific
+configuration).
+If no address is given to iftun_address and bind_address, 1.1.1.1 is
+used.
+.RE
+.IP \[bu] 2
+\f[B]l2tp_mtu\f[R] (int)
+.RS 2
+.PP
+MTU of interface for L2TP traffic (default: 1500).
+Used to set link MRU and adjust TCP MSS.
+.RE
+.IP \[bu] 2
+\f[B]l2tp_secret\f[R] (string)
+.RS 2
+.PP
+The secret used by l2tpns for authenticating tunnel request.
+Must be the same as the LAC, or authentication will fail.
+Only actually be used if the LAC requests authentication.
+.RE
+.IP \[bu] 2
+\f[B]lock_pages\f[R] (boolean)
+.RS 2
+.PP
+Keep all pages mapped by the l2tpns process in memory.
+.RE
+.IP \[bu] 2
+\f[B]log_file\f[R] (string)
+.RS 2
+.PP
+This will be where all logging and debugging information is written
+to.This may be either a filename, such as /var/log/l2tpns, or the string
+syslog:facility, where facility is any one of the syslog logging
+facilities, such as local5.
+.RE
+.IP \[bu] 2
+\f[B]multi_read_count\f[R] (int)
+.RS 2
+.PP
+Number of packets to read off each of the UDP and TUN fds when returned
+as readable by select (default: 10).
+Avoids incurring the unnecessary system call overhead of select on busy
+servers.
+.RE
+.IP \[bu] 2
+\f[B]packet_limit\f[R] (int>
+.RS 2
+.PP
+Maximum number of packets of downstream traffic to be handled each tenth
+of a second per session.
+If zero, no limit is applied (default: 0).
+Intended as a DoS prevention mechanism and not a general throttling
+control (packets are dropped, not queued).
+.RE
+.IP \[bu] 2
+\f[B]peer_address\f[R] (ip address)
+.RS 2
+.PP
+Address to send to clients as the default gateway.
+.RE
+.IP \[bu] 2
+\f[B]pid_file\f[R] (string)
+.RS 2
+.PP
+If set, the process id will be written to the specified file.
+The value must be an absolute path.
+.RE
+.IP \[bu] 2
+\f[B]ppp_keepalive\f[R] (boolean)
+.RS 2
+.PP
+Change this value to no to force generation of LCP ECHO every
+echo_timeout seconds, even there are activity on the link (default: yes)
+.RE
+.IP \[bu] 2
+\f[B]ppp_restart_time\f[R] (int)
+.IP \[bu] 2
+\f[B]ppp_max_configure\f[R] (int)
+.IP \[bu] 2
+\f[B]ppp_max_failure\f[R] (int)
+.RS 2
+.PP
+PPP counter and timer values, as described in Section 4.1 of RFC1661.
+.PP
+\f[I]ppp_restart_time\f[R], Restart timer for PPP protocol negotiation
+in seconds (default: 3).
+.PP
+\f[I]ppp_max_configure\f[R], Number of configure requests to send before
+giving up (default: 10).
+.PP
+\f[I]ppp_max_failure\f[R], Number of Configure-Nak requests to send
+before sending a Configure-Reject (default: 5).
+.RE
+.IP \[bu] 2
+\f[B]primary_dns\f[R] (ip address), \f[B]secondary_dns\f[R] (ip address)
+.RS 2
+.PP
+Whenever a PPP connection is established, DNS servers will be sent to
+the user, both a primary and a secondary.
+If either is set to 0.0.0.0, then that one will not be sent.
+.RE
+.IP \[bu] 2
+\f[B]primary_radius\f[R] (ip address), \f[B]secondary_radius\f[R] (ip
+address)
+.RS 2
+.PP
+Sets the RADIUS servers used for both authentication and accounting.
+If the primary server does not respond, then the secondary RADIUS server
+will be tried.
+.PP
+Note: in addition to the source IP address and identifier, the RADIUS
+server must include the source port when detecting duplicates to
+suppress (in order to cope with a large number of sessions coming
+on-line simultaneously l2tpns uses a set of udp sockets, each with a
+separate identifier).
+.RE
+.IP \[bu] 2
+\f[B]primary_radius_port\f[R] (short), \f[B]secondary_radius_port\f[R]
+(short)
+.RS 2
+.PP
+Sets the authentication ports for the primary and secondary RADIUS
+servers.
+The accounting port is one more than the authentication port.
+If no RADIUS ports are given, the authentication port defaults to 1645,
+and the accounting port to 1646.
+.RE
+.IP \[bu] 2
+\f[B]radius_accounting\f[R] (boolean)
+.RS 2
+.PP
+If set to true, then RADIUS accounting packets will be sent.
+This means that a \f[B]Start\f[R] record will be sent when the session
+is successfully authenticated, and a \f[B]Stop\f[R] record will be sent
+when the session is closed.
+.RE
+.IP \[bu] 2
+\f[B]radius_interim\f[R] (int)
+.RS 2
+.PP
+If radius_accounting is on, defines the interval between sending of
+RADIUS interim accounting records (in seconds).
+.RE
+.IP \[bu] 2
+\f[B]radius_secret\f[R] (string)
+.RS 2
+.PP
+This secret will be used in all RADIUS queries.
+If this is not set then RADIUS queries will fail.
+.RE
+.IP \[bu] 2
+\f[B]radius_authtypes\f[R] (string)
+.RS 2
+.PP
+A comma separated list of supported RADIUS authentication methods
+(\[lq]pap\[rq] or \[lq]chap\[rq]), in order of preference (default
+\[lq]pap\[rq]).
+.RE
+.IP \[bu] 2
+\f[B]radius_dae_port\f[R] (short)
+.RS 2
+.PP
+Port for DAE RADIUS (Packet of Death/Disconnect, Change of
+Authorization) requests (default: 3799).
+.RE
+.IP \[bu] 2
+\f[B]radius_bind_min\f[R], \f[B]radius_bind_max\f[R] (int)
+.RS 2
+.PP
+Define a port range in which to bind sockets used to send and receive
+RADIUS packets.
+Must be at least RADIUS_FDS (64) wide.
+Simplifies firewalling of RADIUS ports (default: dynamically assigned).
+.RE
+.IP \[bu] 2
+\f[B]random_device\f[R] (string)
+.RS 2
+.PP
+Path to random data source (default /dev/urandom).
+Use \[dq]\[dq] to use the rand() library function.
+.RE
+.IP \[bu] 2
+\f[B]scheduler_fifo\f[R] (boolean)
+.RS 2
+.PP
+Sets the scheduling policy for the l2tpns process to SCHED_FIFO.
+This causes the kernel to immediately preempt any currently running
+SCHED_OTHER (normal) process in favour of l2tpns when it becomes
+runnable.
+Ignored on uniprocessor systems.
+.RE
+.IP \[bu] 2
+\f[B]send_garp\f[R] (boolean)
+.RS 2
+.PP
+Determines whether or not to send a gratuitous ARP for the bind_address
+when the server is ready to handle traffic (default: true).
+This value is ignored if BGP is configured.
+.RE
+.IP \[bu] 2
+\f[B]tundevicename\f[R] (string)
+.RS 2
+.PP
+Name of the tun interface (default: \[lq]tun0\[rq]).
+.RE
+.IP \[bu] 2
+\f[B]throttle_speed\f[R] (int)
+.RS 2
+.PP
+Sets the default speed (in kbits/s) which sessions will be limited to.
+If this is set to 0, then throttling will not be used at all.
+Note: You can set this by the CLI, but changes will not affect currently
+connected users.
+.RE
+.IP \[bu] 2
+\f[B]throttle_buckets\f[R] (int)
+.RS 2
+.PP
+Number of token buckets to allocate for throttling.
+Each throttled session requires two buckets (in and out).
+.RE
+.SS DHCPv6 And IPv6 SETTINGS
+.IP \[bu] 2
+\f[B]dhcp6_preferred_lifetime\f[R] (int)
+.RS 2
+.PP
+The preferred lifetime for the IPv6 address and the IPv6 prefix address,
+expressed in units of seconds (see rfc3315).
+.RE
+.IP \[bu] 2
+\f[B]dhcp6_valid_lifetime\f[R] (int)
+.RS 2
+.PP
+The valid lifetime for the IPv6 address and the IPv6 prefix address,
+expressed in units of seconds (see rfc3315).
+.RE
+.IP \[bu] 2
+\f[B]dhcp6_server_duid\f[R] (int)
+.RS 2
+.PP
+DUID Based on Link-layer Address (DUID-LL) (see rfc3315).
+.RE
+.IP \[bu] 2
+\f[B]primary_ipv6_dns\f[R], \f[B]secondary_ipv6_dns\f[R] (Ipv6 address)
+.RS 2
+.PP
+IPv6 DNS servers will be sent to the user (see rfc3646).
+.RE
+.IP \[bu] 2
+\f[B]default_ipv6_domain_list\f[R] (string)
+.RS 2
+.PP
+The Domain Search List (ex: \[lq]fdn.fr\[rq]) (see rfc3646).
+.RE
+.IP \[bu] 2
+\f[B]ipv6_prefix\f[R] (Ipv6 address)
+.RS 2
+.PP
+Enable negotiation of IPv6.
+This forms the the first 64 bits of the client allocated address.
+The remaining 64 come from the allocated IPv4 address and 4 bytes of 0.
+.RE
+.SS LAC SETTINGS
+.IP \[bu] 2
+\f[B]bind_address_remotelns\f[R] (ip address)
+.RS 2
+.PP
+Address of the interface to listen the remote LNS tunnels.
+If no address is given, all interfaces are listened (Any Address).
+.RE
+.IP \[bu] 2
+\f[B]bind_portremotelns\f[R] (short)
+.RS 2
+.PP
+Port to bind for the Remote LNS (default: 65432).
+.RE
+.PP
+A static REMOTES LNS configuration can be entered by the command:
+.IP \[bu] 2
+\f[B]setforward\f[R] \f[I]MASK\f[R] \f[I]IP\f[R] \f[I]PORT\f[R]
+\f[I]SECRET\f[R]
+.RS 2
+.PP
+where MASK specifies the mask of users who have forwarded to remote LNS
+(ex: \[lq]/friendISP\[at]company.com\[rq]).
+.PP
+where IP specifies the IP of the remote LNS (ex: \[lq]66.66.66.55\[rq]).
+.PP
+where PORT specifies the L2TP Port of the remote LNS (Normally should be
+1701) (ex: 1701).
+.PP
+where SECRET specifies the secret password the remote LNS (ex:
+mysecret).
+.RE
+.PP
+The static REMOTE LNS configuration can be used when the friend ISP not
+have a proxied Radius.
+.PP
+If a proxied Radius is used, It will return the RADIUS attributes:
+.IP \[bu] 2
+Tunnel-Type:1 = L2TP
+.IP \[bu] 2
+Tunnel-Medium-Type:1 = IPv4
+.IP \[bu] 2
+Tunnel-Password:1 = \[lq]LESECRETL2TP\[rq]
+.IP \[bu] 2
+Tunnel-Server-Endpoint:1 = \[lq]88.xx.xx.x1\[rq]
+.IP \[bu] 2
+Tunnel-Assignment-Id:1 = \[lq]friendisp_lns1\[rq]
+.IP \[bu] 2
+Tunnel-Type:2 += L2TP
+.IP \[bu] 2
+Tunnel-Medium-Type:2 += IPv4
+.IP \[bu] 2
+Tunnel-Password:2 += \[lq]LESECRETL2TP\[rq]
+.IP \[bu] 2
+Tunnel-Server-Endpoint:2 += \[lq]88.xx.xx.x2\[rq]
+.IP \[bu] 2
+Tunnel-Assignment-Id:2 += \[lq]friendisp_lns2\[rq]
+.SS PPPOE SETTINGS
+.IP \[bu] 2
+\f[B]pppoe_if_to_bind\f[R] (string)
+.RS 2
+.PP
+PPPOE server interface to bind (ex: \[lq]eth0.12\[rq]), If not specified
+the server PPPOE is not enabled.
+For the pppoe clustering, all the interfaces PPPOE of the clusters must
+use the same HW address (MAC address).
+.RE
+.IP \[bu] 2
+\f[B]pppoe_service_name\f[R] (string)
+.RS 2
+.PP
+PPPOE service name (default: NULL).
+.RE
+.IP \[bu] 2
+\f[B]pppoe_ac_name\f[R] (string)
+.RS 2
+.PP
+PPPOE access concentrator name (default: \[lq]l2tpns-pppoe\[rq]).
+.RE
+.IP \[bu] 2
+\f[B]pppoe_only_equal_svc_name\f[R] (boolean)
+.RS 2
+.PP
+If set to yes, the PPPOE server only accepts clients with a
+\[lq]service-name\[rq] different from NULL and a \[lq]service-name\[rq]
+equal to server \[lq]service-name\[rq] (default: no).
+.RE
+.SS BGP ROUTING
+.PP
+The routing configuration section is entered by the command
+.PP
+\f[B]router\f[R] \f[B]bgp\f[R] \f[I]as\f[R]
+.PP
+where \f[I]as\f[R] specifies the local AS number.
+.PP
+Subsequent lines prefixed with \f[B]neighbour\f[R] \f[I]peer\f[R] define
+the attributes of BGP neighhbours.
+Valid commands are:
+.PP
+\f[B]neighbour\f[R] \f[I]peer\f[R] \f[B]remote-as\f[R] \f[I]as\f[R]
+.PP
+\f[B]neighbour\f[R] \f[I]peer\f[R] \f[B]timers\f[R] \f[I]keepalive\f[R]
+\f[I]hold\f[R]
+.PP
+Where \f[I]peer\f[R] specifies the BGP neighbour as either a hostname or
+IP address, \f[I]as\f[R] is the remote AS number and
+\f[I]keepalive\f[R], \f[I]hold\f[R] are the timer values in seconds.
+.SS NAMED ACCESS LISTS
+.PP
+Named access lists may be defined with either of
+.IP \[bu] 2
+\f[B]ip\f[R] \f[B]access-list\f[R] \f[B]standard\f[R] \f[I]name\f[R]
+.IP \[bu] 2
+\f[B]ip\f[R] \f[B]access-list\f[R] \f[B]extended\f[R] \f[I]name\f[R]
+.PP
+Subsequent lines starting with permit or deny define the body of the
+access-list.
+.SS Standard Access Lists
+.PP
+Standard access lists are defined with:
+.IP \[bu] 2
+{\f[B]permit\f[R]|\f[B]deny\f[R]} \f[I]source\f[R] [\f[I]dest\f[R]]
+.PP
+Where \f[I]source\f[R] and \f[I]dest\f[R] specify IP matches using one
+of:
+.IP \[bu] 2
+\f[I]address\f[R] \f[I]wildard\f[R]
+.IP \[bu] 2
+\f[B]host\f[R] \f[I]address\f[R]
+.IP \[bu] 2
+\f[B]any\f[R]
+.PP
+\f[I]address\f[R] and \f[I]wildard\f[R] are in dotted-quad notation,
+bits in the \f[I]wildard\f[R] indicate which address bits in
+\f[I]address\f[R] are relevant to the match (0 = exact match; 1 =
+don\[cq]t care).
+.PP
+The shorthand `host address' is equivalent to `\f[I]address\f[R]
+\f[B]0.0.0.0\f[R]'; `\f[B]any\f[R]' to `\f[B]0.0.0.0\f[R]
+\f[B]255.255.255.255\f[R]'.
+.SS Extended Access Lists
+.PP
+Extended access lists are defined with:
+.IP \[bu] 2
+{\f[B]permit\f[R]|\f[B]deny\f[R]} \f[I]proto\f[R] \f[I]source\f[R]
+[\f[I]ports\f[R]] \f[I]dest\f[R] [\f[I]ports\f[R]] [\f[I]flags\f[R]]
+.PP
+Where \f[I]proto\f[R] is one of \f[B]ip\f[R], \f[B]tcp\f[R] or
+\f[B]udp\f[R], and \f[I]source\f[R] and \f[I]dest\f[R] are as described
+above for standard lists.
+.PP
+For TCP and UDP matches, source and destination may be optionally
+followed by a ports specification:
+.IP \[bu] 2
+{\f[B]eq|neq|gt|lt\f[R]} \f[I]port\f[R]
+.IP \[bu] 2
+\f[B]range\f[R] \f[I]from\f[R] \f[I]to\f[R]
+.PP
+\f[I]flags\f[R] may be one of:
+.IP \[bu] 2
+{\f[B]match-any|match-all\f[R]}
+{\f[B]+|-\f[R]}{\f[B]fin|syn|rst|psh|ack|urg\f[R]} \&...
+.RS 2
+.PP
+Match packets with any or all of the tcp flags set (+) or clear (-).
+.RE
+.IP \[bu] 2
+\f[B]established\f[R]
+.RS 2
+.PP
+Match \[lq]established\[rq] TCP connections: packets with RST or ACK
+set, and SYN clear.
+.RE
+.IP \[bu] 2
+\f[B]fragments\f[R]
+.RS 2
+.PP
+Match IP fragments.
+May not be specified on rules with layer 4 matches.
+.RE
+.SH SEE ALSO
+.PP
+l2tpns(8) (http://man.he.net/man8/l2tpns)
diff --git a/docs/src/html/manual.md b/docs/src/html/manual.md
new file mode 100644
index 0000000..76521a3
--- /dev/null
+++ b/docs/src/html/manual.md
@@ -0,0 +1,1104 @@
+Overview
+========
+
+`l2tpns` is half of a complete L2TP implementation. It supports only the
+LNS side of the connection.
+
+L2TP (Layer 2 Tunneling Protocol) is designed to allow any layer 2
+protocol (e.g. Ethernet, PPP) to be tunneled over an IP connection.
+`l2tpns` implements PPP over L2TP only.
+
+There are a couple of other L2TP implementations, of which
+[l2tpd](http://sourceforge.net/projects/l2tpd) is probably the most
+popular. l2tpd also will handle being either end of a tunnel, and is a
+lot more configurable than `l2tpns`. However, due to the way it works,
+it is nowhere near as scalable.
+
+`l2tpns` uses the TUN/TAP interface provided by the Linux kernel to
+receive and send packets. Using some packet manipulation it doesn\'t
+require a single interface per connection, as l2tpd does.
+
+This allows it to scale extremely well to very high loads and very high
+numbers of connections.
+
+It also has a plugin architecture which allows custom code to be run
+during processing. An example of this is in the walled garden module
+included.
+
+Installation
+============
+
+Requirements {#installation-requirements}
+------------
+
+- Linux kernel version 2.4 or above, with the Tun/Tap interface either
+ compiled in, or as a module.
+
+- libcli 1.8.5 or greater. You can get this from
+ [SourceForge](http://sourceforge.net/projects/libcli)
+
+Compiling {#installation-compile}
+---------
+
+You can generally get away with just running `make` from the source
+directory. This will compile the daemon, associated tools and any
+modules shipped with the distribution.
+
+Installing {#installation-install}
+----------
+
+After you have successfully compiled everything, run `make install` to
+install it. By default, the binaries are installed into `/usr/sbin`, the
+configuration into `/etc/l2tpns`, and the modules into
+`/usr/lib/l2tpns`.
+
+You will definately need to edit the configuration files before you
+start. See [Configuration](#configuration) for more information.
+
+Running {#installation-run}
+-------
+
+You only need to run `/usr/sbin/l2tpns` as root to start it. It does not
+normally detach to a daemon process (see the `-d` option), so you should
+perhaps run it from `init`.
+
+By default there is no log destination set, so all log messages will go
+to stdout.
+
+Configuration
+=============
+
+All configuration of the software is done from the files installed into
+`/etc/l2tpns`.
+
+`startup-config` {#config-startup}
+----------------
+
+This is the main configuration file for `l2tpns`. The format of the file
+is a list of commands that can be run through the command-line
+interface. This file can also be written directly by the `l2tpns`
+process if a user runs the `write memory` command, so any comments will
+be lost. However if your policy is not to write the config by the
+program, then feel free to comment the file with a `#` or `!` at the
+beginning of the line.
+
+A list of the possible configuration directives follows. Each of these
+should be set by a line like: set configstring \"value\" set ipaddress
+192.168.1.1 set boolean true
+
+`debug` (int)
+
+: Sets the level of messages that will be written to the log file. The
+ value should be between 0 and 5, with 0 being no debugging, and 5
+ being the highest. A rough description of the levels is:
+
+ `0`: Critical Errors
+
+ : Things are probably broken
+
+ `1`: Errors
+
+ : Things might have gone wrong, but probably will recover
+
+ `2`: Warnings
+
+ : Just in case you care what is not quite perfect
+
+ `3`: Information
+
+ : Parameters of control packets
+
+ `4`: Calls
+
+ : For tracing the execution of the code
+
+ `5`: Packets
+
+ : Everything, including a hex dump of all packets processed\...
+ probably twice
+
+ Note that the higher you set the debugging level, the slower the
+ program will run. Also, at level 5 a *lot* of information will be
+ logged. This should only ever be used for working out why it
+ doesn\'t work at all.
+
+`log_file` (string)
+
+: This will be where all logging and debugging information is written
+ to. This may be either a filename, such as `/var/log/l2tpns`, or the
+ special magic string `syslog:`facility, where facility is any one of
+ the syslog logging facilities, such as `local5`.
+
+`pid_file` (string)
+
+: If set, the process id will be written to the specified file. The
+ value must be an absolute path.
+
+`random_device` (string)
+
+: Path to random data source (default `/dev/urandom`). Use \"\" to use
+ the rand() library function.
+
+`l2tp_secret` (string)
+
+: The secret used by `l2tpns` for authenticating tunnel request. Must
+ be the same as the LAC, or authentication will fail. Only actually
+ be used if the LAC requests authentication.
+
+`l2tp_mtu` (int)
+
+: MTU of interface for L2TP traffic (default: `1500`). Used to set
+ link MRU and adjust TCP MSS.
+
+`ppp_restart_time` (int); `ppp_max_configure` (int); `ppp_max_failure` (int)
+
+: PPP counter and timer values, as described in §4.1 of
+ [RFC1661](ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt).
+
+`primary_dns` (ip address); `econdary_dns` (ip address)
+
+: Whenever a PPP connection is established, DNS servers will be sent
+ to the user, both a primary and a secondary. If either is set to
+ 0.0.0.0, then that one will not be sent.
+
+`primary_radius` (ip address); `secondary_radius` (ip address)
+
+: Sets the RADIUS servers used for both authentication and accounting.
+ If the primary server does not respond, then the secondary RADIUS
+ server will be tried.
+
+ ::: {.note}
+ In addition to the source IP address and identifier, the RADIUS
+ server *must* include the source port when detecting duplicates to
+ suppress (in order to cope with a large number of sessions coming
+ on-line simultaneously `l2tpns` uses a set of udp sockets, each with
+ a separate identifier).
+ :::
+
+`primary_radius_port` (short); `secondary_radius_port` (short)
+
+: Sets the authentication ports for the primary and secondary RADIUS
+ servers. The accounting port is one more than the authentication
+ port. If no RADIUS ports are given, the authentication port defaults
+ to 1645, and the accounting port to 1646.
+
+`radius_accounting` (boolean)
+
+: If set to true, then RADIUS accounting packets will be sent. This
+ means that a Start record will be sent when the session is
+ successfully authenticated, and a Stop record will be sent when the
+ session is closed.
+
+`radius_interim` (int)
+
+: If `radius_accounting` is on, defines the interval between sending
+ of RADIUS interim accounting records (in seconds).
+
+`radius_secret` (string)
+
+: This secret will be used in all RADIUS queries. If this is not set
+ then RADIUS queries will fail.
+
+`radius_authtypes` (string)
+
+: A comma separated list of supported RADIUS authentication methods
+ (`pap` or `chap`), in order of preference (default `pap`).
+
+`radius_bind_min` (short); `radius_bind_max` (short)
+
+: Define a port range in which to bind sockets used to send and
+ receive RADIUS packets. Must be at least RADIUS\_FDS (64) wide.
+ Simplifies firewalling of RADIUS ports (default: dynamically
+ assigned).
+
+`radius_dae_port` (short)
+
+: Port for DAE RADIUS (Packet of Death/Disconnect, Change of
+ Authorization) requests (default: `3799`).
+
+`allow_duplicate_users` (boolean)
+
+: Allow multiple logins with the same username. If false (the
+ default), any prior session with the same username will be dropped
+ when a new session is established.
+
+`guest_account` (string)
+
+: Allow multiple logins matching this specific username.
+
+`bind_address` (ip address)
+
+: When the tun interface is created, it is assigned the address
+ specified here. If no address is given, 1.1.1.1 is used. Packets
+ containing user traffic should be routed via this address if given,
+ otherwise the primary address of the machine.
+
+`peer_address` (ip address)
+
+: Address to send to clients as the default gateway.
+
+`send_garp` (boolean)
+
+: Determines whether or not to send a gratuitous ARP for the
+ bind\_address when the server is ready to handle traffic (default:
+ `true`). This value is ignored if BGP is configured.
+
+`throttle_speed` (int)
+
+: Sets the default speed (in kbits/s) which sessions will be limited
+ to. If this is set to 0, then throttling will not be used at all.
+ Note: You can set this by the CLI, but changes will not affect
+ currently connected users.
+
+`throttle_buckets` (int)
+
+: Number of token buckets to allocate for throttling. Each throttled
+ session requires two buckets (in and out).
+
+`accounting_dir` (string)
+
+: If set to a directory, then every 5 minutes the current usage for
+ every connected use will be dumped to a file in this directory. Each
+ file dumped begins with a header, where each line is prefixed by
+ `#`. Following the header is a single line for every connected user,
+ fields separated by a space.
+
+ The fields are username, ip, qos, uptxoctets, downrxoctets. The qos
+ field is 1 if a standard user, and 2 if the user is throttled.
+
+`dump_speed` (boolean)
+
+: If set to true, then the current bandwidth utilization will be
+ logged every second. Even if this is disabled, you can see this
+ information by running the `uptime` command on the CLI.
+
+`multi_read_count` (int)
+
+: Number of packets to read off each of the UDP and TUN fds when
+ returned as readable by select (default: 10). Avoids incurring the
+ unnecessary system call overhead of select on busy servers.
+
+`scheduler_fifo` (boolean)
+
+: Sets the scheduling policy for the `l2tpns` process to `SCHED_FIFO`.
+ This causes the kernel to immediately preempt any currently running
+ `SCHED_OTHER` (normal) process in favour of `l2tpns` when it becomes
+ runnable. Ignored on uniprocessor systems.
+
+`lock_pages` (boolean)
+
+: Keep all pages mapped by the `l2tpns` process in memory.
+
+`icmp_rate` (int)
+
+: Maximum number of host unreachable ICMP packets to send per second.
+
+`packet_limit` (int)
+
+: Maximum number of packets of downstream traffic to be handled each
+ tenth of a second per session. If zero, no limit is applied
+ (default: 0). Intended as a DoS prevention mechanism and not a
+ general throttling control (packets are dropped, not queued).
+
+`cluster_address` (ip address)
+
+: Multicast cluster address (default: 239.192.13.13). See
+ [Clustering](#clustering) for more information.
+
+`cluster_port` (udp port)
+
+: UDP cluster port (default: 32792). See [Clustering](#clustering) for
+ more information.
+
+`cluster_interface` (string)
+
+: Interface for cluster packets (default: eth0)
+
+`cluster_mcast_ttl` (int)
+
+: TTL for multicast packets (default: 1).
+
+`cluster_hb_interval` (int)
+
+: Interval in tenths of a second between cluster heartbeat/pings.
+
+`cluster_hb_timeout` (int)
+
+: Cluster heartbeat timeout in tenths of a second. A new master will
+ be elected when this interval has been passed without seeing a
+ heartbeat from the master.
+
+`cluster_master_min_adv` (int)
+
+: Determines the minimum number of up to date slaves required before
+ the master will drop routes (default: 1).
+
+`ipv6_prefix` (ipv6 address)
+
+: Enable negotiation of IPv6. This forms the the first 64 bits of the
+ client allocated address. The remaining 64 come from the allocated
+ IPv4 address and 4 bytes of 0s.
+
+### BGP {#config-startup-bgp}
+
+BGP routing configuration is entered by the command: router bgp as where
+as specifies the local AS number.
+
+Subsequent lines prefixed with neighbour peer define the attributes of
+BGP neighhbours. Valid commands are: neighbour peer remote-as as
+neighbour peer timers keepalive hold
+
+Where peer specifies the BGP neighbour as either a hostname or IP
+address, as is the remote AS number and keepalive, hold are the timer
+values in seconds.
+
+### Access Lists {#config-startup-acl}
+
+Named access-lists are configured using one of the commands: ip
+access-list standard name ip access-list extended name
+
+Subsequent lines prefixed with `permit` or `deny` define the body of the
+access-list. Standard access-list syntax:
+
+{`permit`\|`deny`} {host\|source source-wildcard\|`any`}
+\[{host\|destination destination-wildcard\|`any`}\]
+
+Extended access-lists:
+
+{`permit`\|`deny`} `ip` {host\|source source-wildcard\|`any`}
+{host\|destination destination-wildcard\|`any`} \[`fragments`\]
+
+{`permit`\|`deny`} `udp` {host\|source source-wildcard\|`any`}
+\[{`eq`\|`neq`\|`gt`\|`lt`} port\|`range` from to\] {host\|destination
+destination-wildcard\|`any`} \[{`eq`\|`neq`\|`gt`\|`lt`} port\|`range`
+from to\] \[`fragments`\]
+
+{`permit`\|`deny`} `tcp` {host\|source source-wildcard\|`any`}
+\[{`eq`\|`neq`\|`gt`\|`lt`} port\|`range` from to\] {host\|destination
+destination-wildcard\|`any`} \[{`eq`\|`neq`\|`gt`\|`lt`} port\|`range`
+from to\] \[{`established`\|{`match-any`\|`match-all`}
+{`+`\|`-`}{`fin`\|`syn`\|`rst`\|`psh`\|`ack`\|`urg`} \...\|`fragments`\]
+
+`users` {#config-users}
+-------
+
+Usernames and passwords for the command-line interface are stored in
+this file. The format is username:password where password may either by
+plain text, an MD5 digest (prefixed by `$1`salt`$`) or a DES password,
+distinguished from plain text by the prefix `{crypt}`.
+
+The username `enable` has a special meaning and is used to set the
+enable password.
+
+::: {.important}
+If this file doesn\'t exist, then anyone who can get to port 23 will be
+allowed access without a username or password.
+:::
+
+`ip_pool` {#config-ip-pool}
+---------
+
+This file is used to configure the IP address pool which user addresses
+are assigned from. This file should contain either an IP address or a
+CIDR network per line. e.g.:
+
+ 192.168.1.1
+ 192.168.1.2
+ 192.168.1.3
+ 192.168.4.0/24
+ 172.16.0.0/16
+ 10.0.0.0/8
+
+Keep in mind that `l2tpns` can only handle 65535 connections per
+process, so don\'t put more than 65535 IP addresses in the configuration
+file. They will be wasted.
+
+`build-garden` {#config-build-garden}
+--------------
+
+The garden plugin on startup creates a NAT table called \"garden\" then
+sources the `build-garden` script to populate that table. All packets
+from gardened users will be sent through this table. Example:
+
+ iptables -t nat -A garden -p tcp -m tcp --dport 25 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p udp -m udp --dport 53 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p tcp -m tcp --dport 53 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p tcp -m tcp --dport 80 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p tcp -m tcp --dport 110 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p tcp -m tcp --dport 443 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p icmp -m icmp --icmp-type echo-request -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p icmp -j ACCEPT
+ iptables -t nat -A garden -j DROP
+
+Operation
+=========
+
+A running l2tpns process can be controlled in a number of ways. The
+primary method of control is by the Command-Line Interface (CLI).
+
+You can also remotely send commands to modules via the `nsctl` client
+provided.
+
+There are also a number of signals that l2tpns understands and takes
+action when it receives them.
+
+Command-Line Interface {#operation-cli}
+----------------------
+
+You can access the command line interface by telneting to port 23. There
+is no IP address restriction, so it\'s a good idea to firewall this port
+off from anyone who doesn\'t need access to it. See [](#config-users)
+for information on restricting access based on a username and password.
+
+The CLI gives you real-time control over almost everything in the
+process. The interface is designed to look like a Cisco device, and
+supports things like command history, line editing and context sensitive
+help. This is provided by linking with the
+[libcli](http://sourceforge.net/projects/libcli) library. Some general
+documentation of the interface is
+[here](http://sourceforge.net/docman/display_doc.php?docid=20501&group_id=79019).
+
+After you have connected to the telnet port (and perhaps logged in), you
+will be presented with a `hostname>` prompt.
+
+Enter `help` to get a list of possible commands, or press `?` for
+context-specific help.
+
+A brief overview of the more important commands follows:
+
+`show session [ID]
+ `
+
+: Detailed information for a specific session is presented if you
+ specify a session ID argument.
+
+ If no ID is given, a summary of all connected sessions is produced.
+ Note that this summary list can be around 185 columns wide, so you
+ should probably use a wide terminal.
+
+ The columns listed in the summary are:
+
+ -------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------
+ `SID` Session ID
+ `TID` Tunnel ID See also the [show tunnel](#operation-cli-show-tunnel) CLI command.
+ `Username` The username given in the PPP authentication. If this is \*, then LCP authentication has not completed.
+ `IP` The IP address given to the session. If this is 0.0.0.0, IPCP negotiation has not completed
+ `I` Intercept Y or N: indicates whether the session is being snooped. See also the [snoop](#operation-cli-snoop) CLI command.
+ `T` Throttled Y or N: indicates whether the session is currently throttled. See also the [throttle](#operation-cli-throttle) CLI command.
+ `G` Walled Garden Y or N: indicates whether the user is trapped in the walled garden. This field is present even if the garden module is not loaded.
+ `6` IPv6 Y or N: indicates whether the session has IPv6 active (IPV6CP open)
+ `opened` The number of seconds since the session started
+ `downloaded` Number of bytes downloaded by the user
+ `uploaded` Number of bytes uploaded by the user
+ `idle` The number of seconds since traffic was detected on the session
+ `LAC` The IP address of the LAC the session is connected to.
+ `CLI` The Calling-Line-Identification field provided during the session setup. This field is generated by the LAC.
+ -------------- -------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------
+
+`show users`; `show user username
+ `
+
+: With no arguments, display a list of currently connected users. If
+ an argument is given, the session details for the given username are
+ displayed.
+
+`show tunnel [ID]`
+
+: Produce a summary list of all open tunnels, or detail on a specific
+ tunnel ID.
+
+ The columns listed in the summary are:
+
+ ---------- -----------------------------------------------------------------------------------------------------------
+ TID Tunnel ID
+ Hostname The hostname for the tunnel as provided by the LAC. This has no relation to DNS, it is just a text field.
+ IP The IP address of the LAC
+ State Tunnel state: Free, Open, Dieing, Opening
+ Sessions The number of open sessions on the tunnel
+ ---------- -----------------------------------------------------------------------------------------------------------
+
+`show pool`
+
+: Displays the current IP address pool allocation. This will only
+ display addresses that are in use, or are reserved for re-allocation
+ to a disconnected user.
+
+ If an address is not currently in use, but has been used, then in
+ the User column the username will be shown in square brackets,
+ followed by the time since the address was used:
+
+ IP Address Used Session User
+ 192.168.100.6 N [joe.user] 1548s
+
+`show radius`
+
+: Show a summary of the in-use RADIUS sessions. This list should not
+ be very long, as RADIUS sessions should be cleaned up as soon as
+ they are used. The columns listed are:
+
+ --------- ----------------------------------------------------------------------------------------------------
+ Radius The ID of the RADIUS request. This is sent in the packet to the RADIUS server for identification
+ State The state of the request: WAIT, CHAP, AUTH, IPCP, START, STOP or NULL
+ Session The session ID that this RADIUS request is associated with
+ Retry If a response does not appear to the request, it will retry at this time. This is a Unix timestamp
+ Try Retry count. The RADIUS request is discarded after 3 retries
+ --------- ----------------------------------------------------------------------------------------------------
+
+`show running-config`
+
+: This will list the current running configuration. This is in a
+ format that can either be pasted into the configuration file, or run
+ directly at the command line.
+
+`show counters`
+
+: Internally, counters are kept of key values, such as bytes and
+ packets transferred, as well as function call counters. This
+ function displays all these counters, and is probably only useful
+ for debugging.
+
+ You can reset these counters by running `clear counters`.
+
+`show cluster`
+
+: Show cluster status. Shows the cluster state for this server
+ (Master/Slave), information about known peers and (for slaves) the
+ master IP address, last packet seen and up-to-date status. See
+ [Clustering](#clustering) for more information.
+
+`write memory`
+
+: This will write the current running configuration to the config file
+ `startup-config`, which will be run on a restart.
+
+`snoop user
+ IP
+ port`
+
+: You must specify a username, IP address and port. All packets for
+ the current session for that username will be forwarded to the given
+ host/port. Specify `no snoop
+ username` to disable interception for the session.
+
+ If you want interception to be permanent, you will have to modify
+ the RADIUS response for the user. See [Interception](#interception).
+
+`throttle user
+ [in|out] rate`
+
+: You must specify a username, which will be throttled for the current
+ session to rate Kbps. Prefix rate with `in` or `out` to set
+ different upstream and downstream rates.
+
+ Specify `no throttle
+ username` to disable throttling for the current session.
+
+ If you want throttling to be permanent, you will have to modify the
+ RADIUS response for the user. See [Throttling](#throttling).
+
+`drop session`
+
+: This will cleanly disconnect the session specified by session ID.
+
+`drop tunnel`
+
+: This will cleanly disconnect the tunnel specified by tunnel ID, as
+ well as all sessions on that tunnel.
+
+`uptime`
+
+: This will show how long the `l2tpns` process has been running, and
+ the current bandwidth utilization:
+
+ 17:10:35 up 8 days, 2212 users, load average: 0.21, 0.17, 0.16
+ Bandwidth: UDP-ETH:6/6 ETH-UDP:13/13 TOTAL:37.6 IN:3033 OUT:2569
+
+ The bandwidth line contains 4 sets of values:
+
+ ------------ ----------------------------------------------------------------------------------------
+ UDP-ETH The current bandwidth going from the LAC to the ethernet (user uploads), in mbits/sec.
+ ETH-UDP The current bandwidth going from ethernet to the LAC (user downloads).
+ TOTAL The total aggregate bandwidth in mbits/s.
+ IN and OUT Packets/per-second going between UDP-ETH and ETH-UDP.
+ ------------ ----------------------------------------------------------------------------------------
+
+ These counters are updated every second.
+
+`configure terminal`
+
+: Enter configuration mode. Use `exit` or `^Z` to exit this mode.
+
+ The following commands are valid in this mode:
+
+ `load plugin
+ name`
+
+ : Load a plugin. You must specify the plugin name, and it will
+ search in `/usr/lib/l2tpns` for `name.so`. You can unload a
+ loaded plugin with `remove plugin
+ name`.
+
+ `set` \...
+
+ : Set a configuration variable. You must specify the variable
+ name, and the value. If the value contains any spaces, you
+ should quote the value with double (\") or single (\') quotes.
+
+ You can set any configuration value in this way, although some
+ may require a restart to take effect. See [](#config-startup).
+
+ `router bgp` \...
+
+ : Configure BGP. See [BGP](#config-startup-bgp).
+
+ `ip access-list` \...
+
+ : Configure a named access list. See [Access
+ Lists](#config-startup-acl).
+
+nsctl {#operation-nsctl}
+-----
+
+`nsctl` sends messages to a running `l2tpns` instance to be control
+plugins.
+
+Arguments are `command` and optional args. See `nsctl(8)`.
+
+Built-in command are `load_plugin`, `unload_plugin` and `help`. Any
+other commands are passed to plugins for processing by the
+`plugin_control` function.
+
+Signals {#operation-signals}
+-------
+
+While the process is running, you can send it a few different signals,
+using the `kill` command.
+
+ killall -HUP l2tpns
+
+The signals understood are:
+
+SIGHUP
+
+: Reload the config from disk and re-open log file.
+
+SIGTERM; SIGINT
+
+: Stop process. Tunnels and sessions are not terminated. This signal
+ should be used to stop `l2tpns` on a cluster node where there are
+ other machines to continue handling traffic. See
+ [Clustering](#clustering)
+
+SIGQUIT
+
+: Shut down tunnels and sessions, exit process when complete.
+
+Throttling
+==========
+
+`l2tpns` contains support for slowing down user sessions to whatever
+speed you desire. The global setting `throttle_speed` defines the
+default throttle rate.
+
+To throttle a sesion permanently, add a `Cisco-AVPair` RADIUS attribute.
+The `autothrotle` module interprets the following attributes:
+
+ ----------------------------------------------- --------------------------------------------------------------------------------
+ `throttle=yes` Throttle upstream/downstream traffic to the configured `throttle_speed`.
+ `throttle=rate` Throttle upstream/downstream traffic to the specified rate Kbps.
+ `lcp:interface-config#1=service-policy input Alternate (Cisco) format: throttle upstream/downstream to specified rate Kbps.
+ rate`
+ `lcp:interface-config#2=service-policy output
+ rate`
+ ----------------------------------------------- --------------------------------------------------------------------------------
+
+You can also enable and disable throttling an active session using the
+[throttle](#operation-cli-throttle) CLI command.
+
+Interception
+============
+
+You may have to deal with legal requirements to be able to intercept a
+user\'s traffic at any time. `l2tpns` allows you to begin and end
+interception on the fly, as well as at authentication time.
+
+When a user is being intercepted, a copy of every packet they send and
+receive will be sent wrapped in a UDP packet to a specified host.
+
+The UDP packet contains just the raw IP frame, with no extra headers.
+The script `scripts/l2tpns-capture` may be used as the end-point for
+such intercepts, writing the data in PCAP format (suitable for
+inspection with `tcpdump`).
+
+To enable or disable interception of a connected user, use the
+[snoop](#operation-cli-snoop) and `no
+ snoop` CLI commands. These will enable interception immediately.
+
+If you wish the user to be intercepted whenever they reconnect, you will
+need to modify the RADIUS response to include the Vendor-Specific value
+`Cisco-AVPair="intercept=ip:port"`. For this feature to be enabled, you
+need to have the `autosnoop` module loaded.
+
+Plugins
+=======
+
+So as to make `l2tpns` as flexible as possible, a plugin API is include
+which you can use to hook into certain events.
+
+There are a some standard modules included which may be used as
+examples: `autosnoop`, `autothrottle`, `garden`, `sessionctl`,
+`setrxspeed`, `snoopctl`, `stripdomain` and `throttlectl`.
+
+When an event occurs that has a hook, `l2tpns` looks for a predefined
+function name in every loaded module, and runs them in the order the
+modules were loaded.
+
+The function should return `PLUGIN_RET_OK` if it is all OK. If it
+returns `PLUGIN_RET_STOP`, then it is assumed to have worked, but that
+no further modules should be run for this event.
+
+A return of `PLUGIN_RET_ERROR` means that this module failed, and no
+further processing should be done for this event.
+
+::: {.note}
+Use this with care.
+:::
+
+Most event functions take a specific structure named `param_event`,
+which varies in content with each event. The function name for each
+event will be `plugin_event`, so for the event timer, the function
+declaration should look like:
+
+ int plugin_timer(struct param_timer *data);
+
+A list of the available events follows, with a list of all the fields in
+the supplied structure:
+
++----------------------+----------------------+----------------------+
+| Event | Description | Arguments |
++======================+======================+======================+
+| `plugin_init` | Called when the | `s |
+| | plugin is loaded. A | truct pluginfuncs *` |
+| | pointer to a struct | |
+| | containing function | |
+| | pointers is passed | |
+| | as the only | |
+| | argument, allowing | |
+| | the plugin to call | |
+| | back into the main | |
+| | code. | |
+| | | |
+| | Prior to loading the | |
+| | plugin, `l2tpns` | |
+| | checks the API | |
+| | version the plugin | |
+| | was compiled | |
+| | against. All plugins | |
+| | should contain: | |
+| | | |
+| | int | |
+| | plugin_api_version = | |
+| | PLUGIN_API_VERSION; | |
++----------------------+----------------------+----------------------+
+| See `pluginfuncs` | | |
+| structure in | | |
+| `plugin.h` for | | |
+| available functions. | | |
++----------------------+----------------------+----------------------+
+| `plugin_done` | Called when the | `void` |
+| | plugin is unloaded | |
+| | or `l2tpns` is | |
+| | shutdown. | |
++----------------------+----------------------+----------------------+
+| No arguments. | | |
++----------------------+----------------------+----------------------+
+| `plugin_pre_auth` | Called after a | `struct plug |
+| | RADIUS response has | in param_pre_auth *` |
+| | been received, but | |
+| | before it has been | |
+| | processed by the | |
+| | code. This will | |
+| | allow you to modify | |
+| | the response in some | |
+| | way. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `char *username` | User name. | |
++----------------------+----------------------+----------------------+
+| `char *password` | Password. | |
++----------------------+----------------------+----------------------+
+| `int protocol` | Authentication | |
+| | protocol: `0xC023` | |
+| | for PAP, `0xC223` | |
+| | for CHAP. | |
++----------------------+----------------------+----------------------+
+| `int continue_auth` | Set to 0 to stop | |
+| | processing | |
+| | authentication | |
+| | modules. | |
++----------------------+----------------------+----------------------+
+| `plugin_post_auth` | Called after a | `struct plugi |
+| | RADIUS response has | n param_post_auth *` |
+| | been received, and | |
+| | the basic checks | |
+| | have been performed. | |
+| | This is what the | |
+| | `garden` module uses | |
+| | to force | |
+| | authentication to be | |
+| | accepted. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `char *username` | User name. | |
++----------------------+----------------------+----------------------+
+| `short auth_allowed` | Initially true or | |
+| | false depending on | |
+| | whether | |
+| | authentication has | |
+| | been allowed so far. | |
+| | You can set this to | |
+| | 1 or 0 to force | |
+| | authentication to be | |
+| | accepted or | |
+| | rejected. | |
++----------------------+----------------------+----------------------+
+| `int protocol` | Authentication | |
+| | protocol: `0xC023` | |
+| | for PAP, `0xC223` | |
+| | for CHAP. | |
++----------------------+----------------------+----------------------+
+| `plugin_timer` | Run once per second. | `struct p |
+| | | lugin param_timer *` |
++----------------------+----------------------+----------------------+
+| `time_t time_now` | The current unix | |
+| | timestamp. | |
++----------------------+----------------------+----------------------+
+| `plugin_new_session` | Called after a | `struct plugin |
+| | session is fully set | param_new_session *` |
+| | up. The session is | |
+| | now ready to handle | |
+| | traffic. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| ` | Called when a | `struct plugin p |
+| plugin_kill_session` | session is about to | aram_kill_session *` |
+| | be shut down. This | |
+| | may be called | |
+| | multiple times for | |
+| | the same session. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `plugin_control` | Called in whenever a | `struct plu |
+| | `nsctl` packet is | gin param_control *` |
+| | received. This | |
+| | should handle the | |
+| | packet and form a | |
+| | response if | |
+| | required. | |
+| | | |
+| | Plugin-specific help | |
+| | strings may be | |
+| | included in the | |
+| | output of | |
+| | `nsctl help` by | |
+| | defining a `NULL` | |
+| | terminated list of | |
+| | strings as follows: | |
+| | | |
+| | char | |
+| | *plugin_control_hel | |
+| | p[] = { ..., NULL }; | |
++----------------------+----------------------+----------------------+
+| `int iam_master` | If true, this node | |
+| | is the cluster | |
+| | master. | |
++----------------------+----------------------+----------------------+
+| `int argc` | `nsctl` arguments. | |
++----------------------+----------------------+----------------------+
+| `char **argc` | | |
++----------------------+----------------------+----------------------+
+| `int response` | Response from | |
+| | control message (if | |
+| | handled): should be | |
+| | either | |
+| | `NSCTL_RES_OK` or | |
+| | `NSCTL_RES_ERR`. | |
++----------------------+----------------------+----------------------+
+| `char *additional` | Additional | |
+| | information, output | |
+| | by `nsctl` on | |
+| | receiving the | |
+| | response. | |
++----------------------+----------------------+----------------------+
+| `plu | Called whenever a | `struct plugin para |
+| gin_radius_response` | RADIUS response | m_radius_response *` |
+| | includes a | |
+| | `Cisco-AVPair` | |
+| | value. The value is | |
+| | split into | |
+| | key`=`value pairs. | |
+| | Will be called once | |
+| | for each pair in the | |
+| | response. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `char *key` | Key and value. | |
++----------------------+----------------------+----------------------+
+| `char *value` | | |
++----------------------+----------------------+----------------------+
+| ` | Called whenever a | `struct p |
+| plugin_radius_reset` | RADIUS CoA request | aram_radius_reset *` |
+| | is received to reset | |
+| | any options to | |
+| | default values | |
+| | before the new | |
+| | values are applied. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `pl | Called when | `struct par |
+| ugin_radius_account` | preparing a RADIUS | am_radius_account *` |
+| | accounting record to | |
+| | allow additional | |
+| | data to be added to | |
+| | the packet. | |
++----------------------+----------------------+----------------------+
+| `tunnelt *t` | Tunnel. | |
++----------------------+----------------------+----------------------+
+| `sessiont *s` | Session. | |
++----------------------+----------------------+----------------------+
+| `uint8_t **packet` | Pointer to the end | |
+| | of the currently | |
+| | assembled packet | |
+| | buffer. The value | |
+| | should be | |
+| | incremented by the | |
+| | length of any data | |
+| | added. | |
++----------------------+----------------------+----------------------+
+| `p | Called when a node | `void` |
+| lugin_become_master` | elects itself | |
+| | cluster master. | |
++----------------------+----------------------+----------------------+
+| No arguments. | | |
++----------------------+----------------------+----------------------+
+| `plugin | Called once for each | `sessiont *` |
+| _new_session_master` | open session on | |
+| | becoming cluster | |
+| | master. | |
++----------------------+----------------------+----------------------+
+| Session. | | |
++----------------------+----------------------+----------------------+
+
+Walled Garden
+=============
+
+A \"Walled Garden\" is implemented so that you can provide perhaps
+limited service to sessions that incorrectly authenticate.
+
+Whenever a session provides incorrect authentication, and the RADIUS
+server responds with Auth-Reject, the walled garden module (if loaded)
+will force authentication to succeed, but set the `walled_garden` flag
+in the session structure, and adds an `iptables` rule to the
+`garden_users` chain to cause all packets for the session to traverse
+the `garden` chain.
+
+This doesn\'t *just work*. To set this all up, you will to setup the
+`garden` nat table with the [build-garden](#config-build-garden) script
+with rules to limit user\'s traffic.
+
+For example, to force all traffic except DNS to be forwarded to
+192.168.1.1, add these entries to your `build-garden` script:
+
+ iptables -t nat -A garden -p tcp --dport ! 53 -j DNAT --to 192.168.1.1
+ iptables -t nat -A garden -p udp --dport ! 53 -j DNAT --to 192.168.1.1
+
+`l2tpns` will add entries to the `garden_users` chain as appropriate.
+
+You can check the amount of traffic being captured using the following
+command:
+
+ iptables -t nat -L garden -nvx
+
+Filtering
+=========
+
+Sessions may be filtered by specifying `Filter-Id` attributes in the
+RADIUS reply. filter.`in` specifies that the named access-list filter
+should be applied to traffic from the customer, filter.`out` specifies a
+list for traffic to the customer.
+
+Clustering
+==========
+
+An `l2tpns` cluster consists of one\* or more servers configured with
+the same configuration, notably the multicast `cluster_address` and the
+`cluster_port`
+
+\*A stand-alone server is simply a degraded cluster.
+
+Initially servers come up as cluster slaves, and periodically (every
+`cluster_hb_interval`/10 seconds) send out ping packets containing the
+start time of the process to the multicast `cluster_address` on
+`cluster_port`.
+
+A cluster master sends heartbeat rather than ping packets, which contain
+those session and tunnel changes since the last heartbeat.
+
+When a slave has not seen a heartbeat within `cluster_hb_timeout`/10
+seconds it \"elects\" a new master by examining the list of peers it has
+seen pings from and determines which of these and itself is the \"best\"
+candidate to be master. \"Best\" in this context means the server with
+the highest uptime (the highest IP address is used as a tie-breaker in
+the case of equal uptimes).
+
+After discovering a master, and determining that it is up-to-date (has
+seen an update for all in-use sessions and tunnels from heartbeat
+packets) will raise a route (see [Routing](#routing)) for the
+`bind_address` and for all addresses/networks in `ip_pool`.
+
+Any packets recieved by the slave which would alter the session state,
+as well as packets for throttled or gardened sessions are forwarded to
+the master for handling. In addition, byte counters for session traffic
+are periodically forwarded.
+
+The master, when determining that it has at least one\* up-to-date slave
+will drop all routes (raising them again if all slaves disappear) and
+subsequently handle only packets forwarded to it by the slaves.
+
+\*Configurable with `cluster_master_min_adv`
+
+Multiple clusters can be run on the same network by just using different
+multicast `cluster_address`. However, for a given host to be part of
+multiple clusters without mixing the clusters, `cluster_port` must be
+different for each cluster.
+
+Routing
+=======
+
+If you are running a single instance, you may simply statically route
+the IP pools to the `bind_address` (`l2tpns` will send a gratuitous
+arp).
+
+For a cluster, configure the members as BGP neighbours on your router
+and configure multi-path load-balancing. Cisco uses `maximum-paths ibgp`
+for IBGP. If this is not supported by your IOS revision, you can use
+`maximum-paths` (which works for EBGP) and set `as_number` to a private
+value such as 64512.
diff --git a/docs/src/html/practical-vpns.md b/docs/src/html/practical-vpns.md
new file mode 100644
index 0000000..1305218
--- /dev/null
+++ b/docs/src/html/practical-vpns.md
@@ -0,0 +1,596 @@
+Overview of VPNs and IPsec {#overview}
+==========================
+
+Virtual Private Networks {#vpns}
+------------------------
+
+The purpose of a VPN is to create a secure channel ontop of an un-secure
+medium, where a computer or a device are put in each end-point in order
+to establish communication, each of these end-points are often reffered
+to as Point of Presense, or POP. This kind of a communication allows the
+capability of creating a Virtual Private Network, which is accesable
+over a medium such as the Internet and thus, extend the physical
+boundaries of an existing local network.
+
+VPNs have three forms:
+
+Site-To-Site VPNs
+
+: these setups exist in order to extend the local network to create a
+ much bigger LAN over the Internet.
+
+Network-To-Host or Remote access VPNs
+
+: where a central VPN server is able to achieve multiple connections,
+ often reffered to as RoadWarrior VPNs. (This setup is very common
+ among ISPs)
+
+Network-To-Network
+
+: extranet VPNs allow secure connections within branches and business
+ partners, they are an extension of a Site-To-Site VPNs.
+
+
+shows a Site-To-Site VPN diagram.
+
+IP/VPNs are connections which are based upon IP tunnels. A tunnel is a
+way to encapsulate an IP packet inside another IP packet or some other
+type of packet. Why do we need tunneling? A Virtual Private Network is
+identified by IANA\'s private IP assignments and so such packet can not
+go beyond the uplink Internet interface.
+
+
+shows the tunneling process.
+
+Several tunneling protocols are available for manifesting VPNs.
+
+L2F
+
+: Layer 2 Forwarding, an older implementation which assume position at
+ the link layer of the OSI. It has no encryption capabilities and
+ hence, deprecated.
+
+L2TP
+
+: Layer 2 Tunneling Protocol, still no encryption capabilities.
+
+PPTP
+
+: Point-to-Point Tunneling Protocol, and yet again, no encryption.
+
+As seen, the requirement of encryption enhancement is urgent in order to
+assure authentication, data integrity and privacy. IPsec solves this by
+providing a suite of security measures implemented at layer 3.
+
+IP Security Suite (IPsec) {#ipsec}
+-------------------------
+
+VPN Security is now appearing, this complex things. How so? VPN tunnels
+by themselves are easily maintained by single-standalone tools like
+pppd, l2tpns, stunnel and others. Involving security with VPNs though
+requires more:
+
+- authentication, data integrity and privacy
+
+- keying management
+
+::: {.note}
+Keys are secrets being shared by two end-points to provide a secure mean
+of communication against a third-party connection from sniffing the
+actual data.
+:::
+
+Different ways to handle key management include RADIUS (Remote
+Authentication Dial In User Service) systems which provide AAA
+(Authentication, Authorization and Accounting). Another solution is
+ISAKMP/Oackly - Internet Security Association and Key Management
+Protocol. This solution requires you to posess one of the following:
+
+- something you have
+
+- something you know
+
+- something you are
+
+The more requirements you meet the more secure is the medium, once
+established. Let\'s review, something we have is like a certificate, it
+proves who we are. Something we know, is a key, a secret password which
+we were told in a whisper, and something we are is our-fingerprint which
+identifies ourselves from other individuals.
+
+### IPsec in Depth
+
+IPsec consists of two main protocols, an Authentication Header and
+Encapsulation Security Payload, also known as AH and ESP. Although it is
+not bound to these and can be extended (and often is) to other standarts
+such as
+
+- Data Encryption Standart (DES and 3DES)
+
+- Diffie-Hellman (DH)
+
+- Secure Hash Algorithm-1 (SHA1)
+
+- Message Digest 5 (MD5)
+
+- Internet Key Exchange (IKE)
+
+- Certification Authorities (CA)
+
+We\'ll be deploying an IKE daemon to handle the key management, which
+uses the Diffie- Hellman cryptography protocol in order to allow two
+parties to establish a connection based upon a shared secret key that
+both parties posess. (Authentication within IKE is handled by MD5
+hashing)
+
+IKE is responsible for authentication of two IPsec parties, negotiation
+of keys for encryption algorithms and security associations. This
+process is commonly regarded as two phases:
+
+Phase 1: IKE Security Association
+
+: The IKE daemon authenticates against the peers in order to achieve a
+ secure channel, according to the Diffie-Hellman key agreement.
+
+Phase 2: IKE IPsec Negotiation
+
+: After achieving an authenticated channel, the parties now negotiate
+ a secure transform (the way to encrypt and secure the medium) where
+ the sender is offering his/hers transform set after which the
+ receiver decides upon one. An IPsec session can now safely begin.
+
+Just to be clear, a Security Association is an agreed relation between
+two parties which describes how they will use security services (from
+IPsec) to communicate.
+
+### IPsec Modes
+
+IPsec can operate in two different modes:
+
+Transport mode
+
+: takes place when two devices (like a station and a gateway (now
+ considered a host)) are establishing a connection which upon they
+ both support IPsec.
+
+Tunnel mode
+
+: we require tunnel mode when we proxy IPsec connetions between two
+ stations behind the IPsec gateway. For example, in a Site-to-Site
+ VPN a tunnel mode lives, since it exists in order to provide the
+ stations behind these gateways runing the VPN/IPsec to communicate
+ securely. In this situation, both end-points are runing an IPsec
+ software.
+
+In definition, a tunnel mode IPsec is better secured than transport.
+Without going too deep into the ins-and-outs of the technical side,
+transport mode doesn\'t encapsulate the actual IP layer but only the
+tcp/udp (Transport layer of the OSI) where-as a tunnel mode encapsulate
+both the Transport layer and the IP layer into a new IP packet.
+
+To summarize, we need VPNs for data-exchange methods and a set of IPsec
+tools for security reasons.
+
+VPN Deployment {#deployment}
+==============
+
+I\'ve assembled another diagram to view the actual VPN setup.
+
+gives a general description of how the network will be layed out in real-world scenario.
+
+We notice that a single Linux box is acting as a Gateway and has all the
+services included with it. This is a bad idea from a security
+prespective but it\'s easy to just deploy the FreeRADIUS and MySQL
+servers on another machine. Of course the L2TPns and the rest of the
+IPsec tools suite would have to remain on the Gateway box (not
+necessarily the Firewall).
+
+
+attempts to explain the actual process that the VPN takes and to detail the place that each of that
+application-in-charge takes place.
+
+Requirements {#deployment-requirements}
+------------
+
+### The Toolbox {#deployment-requirements-toolbox}
+
+Following is a description of the requirements you will have to meet:
+
+A Linux box
+
+: preferably a 2.4.27 kernel or higher.
+
+ Debian is the chosen distribution which means we\'ll be using
+ apt-get for installation, but I\'ll also focus on basic source
+ tarballs installation.
+
+ Dependencies:
+
+ - ipsec configuration in the kernel
+
+L2TPns
+
+: an L2TP PPP Termination tool.
+
+ Dependencies:
+
+ - libcli 1.8.0 or greater
+
+ - tun/tap interface compiled in the kernel or as a module
+
+FreeRADIUS
+
+: For authentication, and accounting.
+
+MySQL
+
+: To act as a back-end database for the RADIUS.
+
+OpenSwan
+
+: Provides the ipsec suite package.
+
+### Kernel Support {#deployment-requirements-kernel}
+
+Debian stock kernel 2.4.27 and up are ipsec compatible although if you
+think otherwise check for the kernel-patch-openswan package.
+
+Installation {#deployment-installation}
+------------
+
+### L2TPns {#deployment-installation-l2tpns}
+
+#### Installation {#deployment-installation-l2tpns-install}
+
+> L2TPns is a layer 2 tunneling protocol network server (LNS). It
+> supports up to 65535 concurrent sessions per server/cluster plus ISP
+> features such as rate limiting, walled garden, usage accounting, and
+> more.
+
+In a personal note - L2TPns is highly configurable for many cases, and
+extremely reliable for production/commerical use.
+
+Step 1:
+
+: Make sure you have libcli-1.8 development package installed:
+
+ # apt-cache search libcli
+ libcli-dev - emulates a cisco style telnet command-line interface (dev files)
+ libcli1 - emulates a cisco style telnet command-line interface
+ # apt-get install libcli-dev
+
+Step 2:
+
+: Download the source from
+ [SourceForge](http://sourceforge.net/projects/l2tpns/).
+
+Step 3:
+
+: Build and install: `make && make install`
+
+::: {.note}
+Alternately, you can skip these steps and simply
+`apt-get install l2tpns`.
+:::
+
+::: {.note}
+On RPM-based distributions, you should be able to make packages from the
+libcli and l2tpns source tarballs with `rpmbuild -ta`.
+:::
+
+Once compiliation is done you will have l2tpns in `/usr/sbin/l2tpns`,
+and all configuration files can be found in `/etc/l2tpns/`.
+
+#### Configuration {#deployment-installation-l2tpns-config}
+
+The only configuration that L2TPns takes is centralized in the
+configuration file `/etc/l2tpns/startup-config`.
+
+ set debug 2 # Debugging level
+ set log_file "/var/log/l2tpns" # Log file: comment out to use stderr, use
+ # "syslog:facility" for syslog
+ set pid_file "/var/run/l2tpns.pid" # Write pid to this file
+ set l2tp_secret "secret" # shared secret
+ set primary_dns 212.117.128.6 # Only 2 DNS server entries are allowed
+ set secondary_dns 212.117.129.3
+ set primary_radius 192.168.0.1 # Can have multiple radius server entries,
+ # but ony one radius secret
+ set primary_radius_port 1812
+ set radius_secret "radius_secret"
+ set radius_accounting yes
+ set radius_dae_port 3799
+ set accounting_dir "/var/run/l2tpns/acct" # Write usage accounting files into specified
+ # directory
+ set peer_address 192.168.0.1 # Gateway address given to clients
+ load plugin "sessionctl" # Drop/kill sessions
+ load plugin "autothrottle" # Throttle/snoop based on RADIUS
+ load plugin "throttlectl" # Control throttle/snoop with nsctl
+ load plugin "snoopctl"
+
+This is the trimmed down version of probably most of the common
+configuration and even some extra options.
+
+Important configuration options are highlited and you should adjust
+these to meet your network needs. We can deploy all of the environment
+into one box which is of course not a very good idea from a security
+point of view, but will function just fine. Moreover, we will be using
+aliased IP addresses so once you\'ve decided to move the FreeRADIUS
+daemon to another computer on the LAN it will be fairly easy and won\'t
+take too much configuration into it.
+
+Next, we need to setup the IP pool that L2TPns will provide to each VPN
+client. The configuration file is located at `/etc/l2tpns/ip_pool` and
+should look like the following:
+
+ 172.16.21.0/24
+
+::: {.important}
+Of course you can change this pool to anything else (IANA IPs assigned
+for private internets only) just make sure it is not conflicting with
+your current LAN network addresses. This means that if you\'ve assigned
+addresses of 192.168.0.1 and 192.168.0.2 to your LAN boxes you can\'t
+have a pool of 192.168.0.1/24 defined since L2TPns will try to route
+those addresses from the tun device, which is needless to say a bad
+idea\...
+:::
+
+Next up, creating the access-list for L2TPns.
+
+Add a username and password into `/etc/l2tpns/users`:
+
+ admin:12345
+
+The password may either be plain-text as above, or encrypted with MD5 or
+DES (to distinguish DES from plain-text passwords, prefix the value with
+`{crypt}`).
+
+L2TPns utilizes a terminal connection on port 23 which you would feel
+very comfortable in if you have worked with routers and switches devices
+before. The terminal provides control over the ppp termination which is
+why we\'ve created an account to log on to.
+
+### IPsec {#deployment-installation-ipsec}
+
+#### Installation {#deployment-installation-ipsec-install}
+
+User-space IPsec tools for various IPsec implementations exist for
+linux, among them is the port of KAME\'s libipsec, setkey, and racoon.
+Others are the OpenSWAN (a successor to the FreeSWAN project).
+
+Getting IPsec installed is fairly easy with Debian:
+
+ # apt-get install openswan
+
+The OpenSWAN project provides packages for RPM-based distributions.
+
+Alternately, you may download the
+[source](http://www.openswan.org/code/) from the OpenSWAN project:
+
+ # tar xvzf openswan-2.4.4.tar.gz
+ # cd openswan-2.4.4
+ # ./configure && make && make install
+
+#### Configuration {#deployment-installation-ipsec-config}
+
+OpenSWAN acts as the IKE daemon (remember IKE? it\'s job is to
+authenticate between the two peers and negotiate a secure medium). We
+will be setting up the IKE daemon as a RoadWarrior configuration, a term
+for remote access VPNs.
+
+We desire this approach for compatibilty because after our VPN solution
+will be complete any user from a Windows machine will be easily ready to
+connect without any 3rd party applications, same for Linux.
+
+Configuration files are placed in `/etc/ipsec.d/`, `/etc/ipsec.conf` and
+`/etc/ipsec.secrets`.
+
+Let\'s start by choosing the remote client and it\'s PSK (Private Shared
+Key) `/etc/ipsec.secrets`:
+
+ hostname_or_ipaddress %any : PSK "mysecretkeyisverylong"
+
+This is an IP/key pair. The IP or FQDN defines the local peer (like a
+SOHO branch), then the remote host. Here we defined %any for all hosts,
+though it\'s possible to define only a specific IP. At last, we define
+the key associated with it.
+
+A better way to create a key is to utilize /dev/random for creating a
+unique key.
+
+ # dd if=/dev/random count=16 bs=1 2>/dev/null | xxd -ps
+
+Next, let\'s prepare the configuration file `/etc/ipsec.conf`:
+
+ version 2.0
+ config setup
+ nat_traversal=yes
+
+ conn l2tp
+ authby=secret
+ pfs=no
+ keyingtries=3
+ left=real_ip_address
+ leftnexthop=%defaultroute
+ leftprotoport=17/%any
+ right=%any
+ rightprotoport=17/%any
+ auto=add
+
+ include /etc/ipsec.d/examples/no_oe.conf
+
+In this file we have first defined version 2 which is a must, then
+enabled NAT Traversal. To understand the importance of this feature
+think of the following scenario: A remote user attempts to connect while
+he\'s behind a router and therefore NATed. The router has to
+de-encapsulate the packet, change things and then build it up again and
+send it. IPsec doesn\'t like other people messing with it\'s packet.
+That\'s why we solve this issue with NAT Traversal.
+
+Next up we configure authentication type (certificates, psk, rsa keys,
+etc) then the left and right peers. The default mode OpenSWAN takes is
+tunnel unless told otherwise. I won\'t go into in-depth explanation of
+every method, you can take a quick look at `/etc/ipsec.d/examples` for
+more explanation and other variations of working with RSA keys,
+Certificates, host-to-host, and more.
+
+In summary:
+
+- We\'ve configured an almost complete IPsec VPN setup.
+
+- We\'ve installed and configured a VPN server (L2TPns) and our IPsec
+ security suite.
+
+- To control both of them we use: `/etc/init.d/l2tpns` and
+ `/etc/init.d/racoon` (location of start-up scripts may vary on
+ non-Debian systems, or if you\'ve installed from source).
+
+### FreeRADIUS {#deployment-installation-freeradius}
+
+The VPN setup needs to authenticate against something, that is the users
+database which we chose to be a FreeRADIUS server backed with a MySQL
+database.
+
+#### Installation {#deployment-installation-freeradius-install}
+
+> FreeRADIUS is the premiere open source RADIUS server. While detailed
+> statistics are not available, we believe that FreeRADIUS is well
+> within the top 5 RADIUS servers world-wide, in terms of the number of
+> people who use it daily for authentication. It scales from embedded
+> systems with small amounts of memory, to systems with millions of
+> users. It is fast, flexible, configurable, and supports more
+> authentication protocols than many commercial servers.
+
+Installing on Debian:
+
+ # apt-get install freeradius freeradius-mysql
+
+From source: Download the latest freeradius package from
+[freeradius.org](http://freeradius.org/getting.html)
+
+ # tar xvzf freeradius.tar.gz
+ # cd freeradius
+ # ./configure && make && make install
+
+#### Configuration {#deployment-installation-freeradius-config}
+
+This will appear a bit complex but it isn\'t, it\'s just a lot of
+configuration.
+
+Following are the configurations you need to have in your
+`/etc/freeradius/` files.
+
+In this section I will not give you a dump of the configuration since
+they are very long and mostly default. I\'ll just post which changes to
+make.
+
+We haven\'t yet configured MySQL, but it\'ll come afterwards, don\'t
+worry.
+
+Make the following changes to the file `/etc/freeradius/sql.conf`:
+
+ server = "192.168.0.1"
+ login = "radius"
+ password = "12345678"
+
+Add the following to the file `/etc/freeradius/clients.conf`:
+
+ client 192.168.0.1 {
+ secret = my_secret
+ shortname = localhost
+ nastype = other
+ }
+
+Don\'t confuse the secret directive there with IPsec. RADIUS server are
+using secret keys also to identify their allowed NAS (Network Access
+Servers), these are the clients that talk to the RADIUS server.
+
+Also, change the `client 127.0.0.1 {}` directive to hold the secret
+\"my\_secret\" like we configured for 192.168.0.1 to avoid conflicts.
+
+Uncomment the `sql` directive in the `authorize`, `accounting`, and
+`session` sections of `/etc/freeradius/radiusd.conf`.
+
+Now for populating FreeRADIUS with MySQL. If you don\'t know or haven\'t
+set root password for MySQL you can do it now with:
+
+ # mysqladmin -u root password password_here
+
+Then add the following to `/root/.my.cnf`:
+
+ [mysqladmin]
+ user = root
+ password = password_here
+
+Create the `radius` database, using the schema given in
+`/usr/share/doc/freeradius/examples/db_mysql.sql.gz
+ `.
+
+::: {.note}
+It may be necessary to modify the column definition of `id` in the `nas`
+table, removing `DEFAULT '0'` such that the definition reads:
+
+ id int(10) NOT NULL auto_increment,
+:::
+
+ # mysqladmin create radius
+ # mysql radius
+ mysql> source db_mysql.sql
+ mysql> GRANT ALL ON * TO 'radius'@'localhost' IDENTIFIED BY 'radius_password';
+
+All the configuration is now done. Let\'s add a user to our VPN
+database.
+
+ # mysql radius
+ mysql> INSERT INTO radcheck values (0, "test", "User-Password", "==", "1234");
+
+We have now created a user in the database of username `test` and
+password `1234`.
+
+Testing the RADIUS setup is simple using the radtest utility provided
+with it.
+
+ # radtest
+ Usage: radtest user passwd radius-server[:port] nas-port-number secret [ppphint] [nasname]
+ # radtest test 1234 192.168.0.1 1812 my_secret
+
+radtest sends an Access-Request to the RADIUS server and expects an
+Access-Accept back from it. If you\'re not getting an Access-Accept from
+the RADIUS you\'re advised to check the configuration again and see what
+you might have missed.
+
+### Firewall Configuration {#deployment-installation-firewall}
+
+We need to apply a few things to iptables configuration and kernel
+networking.
+
+First off, we need to accept VPN-specific packets through the firewall.
+Of course you will have to adjust the rules to fits you needs, in this
+case, ppp0 is the Internet interface.
+
+ # iptables --append INPUT --in-interface ppp0 -p udp --dport 1701 -j ACCEPT
+ # iptables --append INPUT --in-interface ppp0 -p udp --dport 500 -j ACCEPT
+ # iptables --append INPUT --in-interface ppp0 -p udp --dport 4500 -j ACCEPT
+ # iptables --append INPUT --in-interface ppp0 -p 50 -j ACCEPT
+
+If you haven\'t setup your Linux box as a gateway yet then you have to
+allow forwarding/masqing for the boxes on the LAN (and therefore for the
+VPN clients):
+
+ # iptables --table nat --append POSTROUTING --out-interface ppp0 -j MASQUERADE
+ # iptables --append FORWARD --in-interface eth0 -j ACCEPT
+ # echo 1 > /proc/sys/net/ipv4/ip_forward
+
+References
+==========
+
+VPN Reference
+
+: [](http://www.jacco2.dds.nl/networking/freeswan-l2tp.html)
+
+L2TPns Project
+
+: [](http://l2tpns.sourceforge.net)
+
+OpenSWAN Project
+
+: [](http://www.openswan.org)
diff --git a/docs/src/man/l2tpns.8.md b/docs/src/man/l2tpns.8.md
new file mode 100644
index 0000000..5647ef6
--- /dev/null
+++ b/docs/src/man/l2tpns.8.md
@@ -0,0 +1,120 @@
+# NAME
+
+l2tpns - Layer 2 tunneling protocol network server (LNS)
+
+# SYNOPSIS
+
+**l2tpns** \[-**d**\] \[-**v**\] \[-**c** _file_\] \[-**h** _hostname_\]
+
+# DESCRIPTION
+
+**l2tpns** is a daemon for terminating layer 2 tunneling protocol (L2TP: RFC2661) sessions.
+
+**l2tpns** is a complete L2TP implementation. It supports the LAC, LNS, PPPOE and DHCPv6 server.
+
+Once running, **l2tpns** may be controlled by telnetting to port 23 on the machine running the daemon and with the **nsctl** utility.
+
+# OPTIONS
+
+- **-d** Detach from terminal and fork into the background. By default l2tpns will stay in the foreground.
+
+ .
+
+- **-v** Increase verbosity for debugging. Can be used multiple times.
+
+ .
+
+- **-c** _file_
+
+ Specify configuration file.
+
+- **-h** _hostname_
+
+ Force hostname to _hostname_.
+
+# FILES
+
+- _/etc/l2tpns/startup-config_
+
+ The default configuration file.
+
+- _/etc/l2tpns/ip\_pool_
+
+ IP address pool configuration.
+
+- _/etc/l2tpns/users_
+
+ Username/password configuration for access to admin interface.
+
+# SIGNALS
+
+- **SIGHUP** Reload the config from disk and re-open log file.
+
+ .
+
+- **SIGTERM**, **SIGINT**
+
+ Stop process. Tunnels and sessions are not terminated. This signal should be used to stop l2tpns on a cluster node where there are other machines to continue handling traffic.
+
+- **SIGQUIT**
+
+ Shut down tunnels and sessions, exit process when complete.
+
+# MANAGED RADIUS ATTRIBUTE
+
+- **Ascend-Client-Primary-DNS**, **Ascend-Client-Secondary-DNS**
+
+ Specifies a primary and secondary DNS server address to send to user.
+
+- **Delegated-IPv6-Prefix**
+
+ Assign a network address IPv6 prefix to a user by DHCPv6.
+
+- **Framed-IP-Address**
+
+ The address to be configured for the user (IPv4 address of the interface ppp).
+
+- **Framed-Route**
+
+ provides routing information to be configured for the user.
+
+- **Framed-IPv6-Route**
+
+ Has the same action as **Delegated-IPv6-Prefix**. **Delegated-IPv6-Prefix** is the correct one to use.
+
+- **Framed-IPv6-Address**
+
+ IPv6 address to be assigned to the user by DHCPv6 (IPv6 address of the interface ppp).
+
+- **Idle-Timeout**
+
+ disconnects the session if no data for more than **Idle-Timeout** (in seconds).
+
+- **Session-Timeout**
+
+ disconnects the user session when the time **Session-Timeout** is reached (in seconds).
+
+- **Tunnel-Type**, **Tunnel-Medium-Type**, **Tunnel-Server-Endpoint**, **Tunnel-Password**, **Tunnel-Assignment-Id**
+
+ attributes returned by the Radius of the remote LNS server (LAC functionality).
+
+ example, Radius that return the information of 2 remote LNS server with which must be open a L2TP TUNNEL:
+
+ - **Tunnel-Type**: 1 = L2TP
+ - **Tunnel-Medium-Type**: 1 = IPv4
+ - **Tunnel-Password**: 1 = "TheSecretL2TP"
+ - **Tunnel-Server-Endpoint**: 1 = "88.xx.xx.x1"
+ - **Tunnel-Assignment-Id**: 1 = "friendisp\_lns1"
+ - **Tunnel-Type**: 2 = L2TP
+ - **Tunnel-Medium-Type**: 2 = IPv4
+ - **Tunnel-Password**: 2 = "TheSecretL2TP"
+ - **Tunnel-Server-Endpoint**: 2 = "88.xx.xx.x2"
+ - **Tunnel-Assignment-Id**: 2 = "friendisp\_lns2"
+
+# SEE ALSO
+
+**startup-config**(5), **nsctl**(8)
+
+# AUTHOR
+
+This manual page was written by Jonathan McDowell and Fernando Alves (fendo@sameswifi.fr), for the Debian GNU/Linux system (but may be used by others).
diff --git a/docs/src/man/nsctl.8.md b/docs/src/man/nsctl.8.md
new file mode 100644
index 0000000..0d7c3cc
--- /dev/null
+++ b/docs/src/man/nsctl.8.md
@@ -0,0 +1,68 @@
+NAME
+====
+
+nsctl - manage running l2tpns instance
+
+SYNOPSIS
+========
+
+**nsctl** \[**-d**\] \[**-h** *host*\[:*port*\]\] \[**-t** *timeout*\]
+*command* \[*arg* \...\]
+
+DESCRIPTION
+===========
+
+**nsctl** sends commands to a running **l2tpns** process. It provides
+both for the loading or unloading of plugins and also the management of
+sessions via functions provided by those plugins.
+
+OPTIONS
+=======
+
+**-d**
+
+: Enable debugging output.
+
+**-h *host*\[:*port*\]**
+
+: The host running **l2tpns** that should receive the message. By
+ default the message is sent to UDP port 1702 on **localhost**.
+
+**-t *timeout***
+
+: Timeout in seconds to wait for a response from the server.
+
+COMMANDS
+========
+
+The first argument specifies the command to send to **l2tpns .** The
+following commands are as defined:
+
+**load\_plugin ***plugin*
+
+: Load the named *plugin*.
+
+**unload\_plugin ***plugin*
+
+: Unload the named *plugin*.
+
+**help**
+
+: Each loaded plugin is queried for what commands it supports and the
+ synopsis for each is output.
+
+Any other value of *command* (and *args* if any) are sent to **l2tpns**
+as-is, to be passed to each plugin which registers a **plugin\_control**
+function in turn (in which it may be acted upon).
+
+SEE ALSO
+========
+
+**l2tpns**(8)
+
+AUTHOR
+======
+
+This manual page was written by Jonathan McDowell
+\, for the Debian GNU/Linux system (but may be
+used by others).
diff --git a/docs/src/man/startup-config.5.md b/docs/src/man/startup-config.5.md
new file mode 100644
index 0000000..20993f6
--- /dev/null
+++ b/docs/src/man/startup-config.5.md
@@ -0,0 +1,397 @@
+# NAME
+
+startup-config - configuration file for l2tpns
+
+# SYNOPSIS
+
+/etc/l2tpns/startup-config
+
+# DESCRIPTION
+
+**startup-config** is the configuration file for **l2tpns**
+
+The format is plain text, in the same format as accepted by
+the configuration mode of l2tpns's telnet administrative
+interface. Comments are indicated by either the character # or !.
+
+## SETTINGS
+
+Settings are specified with
+
+- **set** `variable` `value`
+
+A list of the possible configuration directives follows. Each of these should be set by a line like:
+
+- **set** _configstring_ _"value"_
+- **set** _ipaddress_ _192.168.1.1_
+- **set** _boolean_ _true_
+
+The following `variables` may be set:
+
+- **accounting\_dir** (string)
+
+ If set to a directory, then every 5 minutes the current usage for every connected use will be dumped to a file in this directory. Each file dumped begins with a header, where each line is prefixed by #. Following the header is a single line for every connected user, fields separated by a space.
+
+ The fields are username, ip, qos, uptxoctets, downrxoctets, origin (optional). The qos field is 1 if a standard user, and 2 if the user is throttled. The origin field is dump if **account\_all\_origin** is set to true (origin value: L=LAC data, R=Remote LNS data, P=PPPOE data).
+
+- **account\_all\_origin** (boolean)
+
+ If set to true, all origin of the usage is dumped to the accounting file (LAC+Remote LNS+PPPOE)(default false).
+
+- **allow\_duplicate\_users** (boolean)
+
+ Allow multiple logins with the same username. If false (the default), any prior session with the same username will be dropped when a new session is established.
+
+- **auth\_tunnel\_change\_addr\_src** (boolean)
+
+ This parameter authorize to change the source IP of the tunnels l2tp. This parameter can be used when the remotes BAS/LAC are l2tpns server configured in cluster mode, but that the interface to remote LNS are not clustered (the tunnel can be coming from different source IP) (default: no).
+
+- **bind\_address** (ip address)
+
+ It's the listen address of the l2tp udp protocol sent and received to LAC. This address is also assigned to the tun interface if no iftun\_address is specified. Packets containing user traffic should be routed via this address if given, otherwise the primary address of the machine.
+
+- **bind\_multi\_address** (ip address)
+
+ This parameter permit one to listen several address of the l2tp udp protocol (and set several address to the tun interface).
+
+ WHEN this parameter is set, It OVERWRITE the parameters "bind\_address" and "iftun\_address".
+
+ these can be interesting when you want do load-balancing in cluster mode of the uploaded from the LAC. For example you can set a bgp.prepend(MY\_AS) for Address1 on LNS1 and a bgp.prepend(MY\_AS) for Address2 on LNS2 (see BGP AS-path prepending).
+
+ example of use with 2 address:
+
+ **set** _bind\_multi\_address_ "64.14.13.41, 64.14.13.42"
+
+- **cluster\_address** (ip address)
+
+ Multicast cluster address (default: 239.192.13.13). See the section on Clustering for more information.
+
+- **Bcluster\_port** (int)
+
+ UDP cluster port (default: 32792). See the section on Clustering for more information.
+
+- **cluster\_interface** (string)
+
+ Interface for cluster packets (default: eth0).
+
+- **cluster\_mcast\_ttl** (int)
+
+ TTL for multicast packets (default: 1).
+
+- **cluster\_hb\_interval** (int)
+
+ Interval in tenths of a second between cluster heartbeat/pings.
+
+- **cluster\_hb\_timeout** (int)
+
+ Cluster heartbeat timeout in tenths of a second. A new master will be elected when this interval has been passed without seeing a heartbeat from the master.
+
+- **cluster\_master\_min\_adv** (int)
+
+ Determines the minimum number of up to date slaves required before the master will drop routes (default: 1).
+
+- **debug** (int)
+
+ Set the level of debugging messages written to the log file. The value should
+ be between 0 and 5, with 0 being no debugging, and 5 being the highest.
+ A rough description of the levels is:
+
+ - 0. Critical Errors - Things are probably broken
+ - 1. Errors - Things might have gone wrong, but probably will recover
+ - 2. Warnings - Just in case you care what is not quite perfect
+ - 3. Information - Parameters of control packets
+ - 4. Calls - For tracing the execution of the code
+ - 5. Packets - Everything, including a hex dump of all packets processed... probably twice
+
+ Note that the higher you set the debugging level, the slower the program will run. Also, at level 5 a LOT of information will be logged. This should only ever be used for working out why it doesn't work at all.
+
+- **dump\_speed** (boolean)
+
+ If set to true, then the current bandwidth utilization will be logged every second. Even if this is disabled, you can see this information by running the uptime command on the CLI.
+
+- **disable\_sending\_hello** (boolean)
+
+ Disable l2tp sending HELLO message for Apple compatibility. Some OS X implementation of l2tp no manage the L2TP "HELLO message". (default: no).
+
+- **echo\_timeout** (int)
+
+ Time between last packet sent and LCP ECHO generation (default: 10 (seconds)).
+
+- **guest\_account**
+
+ Allow multiple logins matching this specific username.
+
+- **icmp\_rate** (int)
+
+ Maximum number of host unreachable ICMP packets to send per second.
+
+- **idle\_echo\_timeout** (int)
+
+ Drop sessions who have not responded within idle\_echo\_timeout seconds (default: 240 (seconds))
+
+- **iftun\_address** (ip address)
+
+ This parameter is used when you want a tun interface address different from the address of "bind\_address" (For use in cases of specific configuration). If no address is given to iftun\_address and bind\_address, 1.1.1.1 is used.
+
+- **l2tp\_mtu** (int)
+
+ MTU of interface for L2TP traffic (default: 1500). Used to set link MRU and adjust TCP MSS.
+
+- **l2tp\_secret** (string)
+
+ The secret used by l2tpns for authenticating tunnel request. Must be the same as the LAC, or authentication will fail. Only actually be used if the LAC requests authentication.
+
+- **lock\_pages** (boolean)
+
+ Keep all pages mapped by the l2tpns process in memory.
+
+- **log\_file** (string)
+
+ This will be where all logging and debugging information is written to.This may be either a filename, such as /var/log/l2tpns, or the string syslog:facility, where facility is any one of the syslog logging facilities, such as local5.
+
+- **multi\_read\_count** (int)
+
+ Number of packets to read off each of the UDP and TUN fds when returned as readable by select (default: 10). Avoids incurring the unnecessary system call overhead of select on busy servers.
+
+- **packet\_limit** (int>
+
+ Maximum number of packets of downstream traffic to be handled each tenth of a second per session. If zero, no limit is applied (default: 0). Intended as a DoS prevention mechanism and not a general throttling control (packets are dropped, not queued).
+
+- **peer\_address** (ip address)
+
+ Address to send to clients as the default gateway.
+
+- **pid\_file** (string)
+
+ If set, the process id will be written to the specified file. The value must be an absolute path.
+
+- **ppp\_keepalive** (boolean)
+
+ Change this value to no to force generation of LCP ECHO every echo\_timeout seconds, even there are activity on the link (default: yes)
+
+- **ppp\_restart\_time** (int)
+- **ppp\_max\_configure** (int)
+- **ppp\_max\_failure** (int)
+
+ PPP counter and timer values, as described in Section 4.1 of RFC1661.
+
+ _ppp\_restart\_time_, Restart timer for PPP protocol negotiation in seconds (default: 3).
+
+ _ppp\_max\_configure_, Number of configure requests to send before giving up (default: 10).
+
+ _ppp\_max\_failure_, Number of Configure-Nak requests to send before sending a Configure-Reject (default: 5).
+
+- **primary\_dns** (ip address), **secondary\_dns** (ip address)
+
+ Whenever a PPP connection is established, DNS servers will be sent to the user, both a primary and a secondary. If either is set to 0.0.0.0, then that one will not be sent.
+
+- **primary\_radius** (ip address), **secondary\_radius** (ip address)
+
+ Sets the RADIUS servers used for both authentication and accounting. If the primary server does not respond, then the secondary RADIUS server will be tried.
+
+ Note: in addition to the source IP address and identifier, the RADIUS server must include the source port when detecting duplicates to suppress (in order to cope with a large number of sessions coming on-line simultaneously l2tpns uses a set of udp sockets, each with a separate identifier).
+
+- **primary\_radius\_port** (short), **secondary\_radius\_port** (short)
+
+ Sets the authentication ports for the primary and secondary RADIUS servers. The accounting port is one more than the authentication port. If no RADIUS ports are given, the authentication port defaults to 1645, and the accounting port to 1646.
+
+- **radius\_accounting** (boolean)
+
+ If set to true, then RADIUS accounting packets will be sent. This means that a **Start** record will be sent when the session is successfully authenticated, and a **Stop** record will be sent when the session is closed.
+
+- **radius\_interim** (int)
+
+ If radius\_accounting is on, defines the interval between sending of RADIUS interim accounting records (in seconds).
+
+- **radius\_secret** (string)
+
+ This secret will be used in all RADIUS queries. If this is not set then RADIUS queries will fail.
+
+- **radius\_authtypes** (string)
+
+ A comma separated list of supported RADIUS authentication methods ("pap" or "chap"), in order of preference (default "pap").
+
+- **radius\_dae\_port** (short)
+
+ Port for DAE RADIUS (Packet of Death/Disconnect, Change of Authorization) requests (default: 3799).
+
+- **radius\_bind\_min**, **radius\_bind\_max** (int)
+
+ Define a port range in which to bind sockets used to send and receive RADIUS packets. Must be at least RADIUS\_FDS (64) wide. Simplifies firewalling of RADIUS ports (default: dynamically assigned).
+
+- **random\_device** (string)
+
+ Path to random data source (default /dev/urandom). Use "" to use the rand() library function.
+
+- **scheduler\_fifo** (boolean)
+
+ Sets the scheduling policy for the l2tpns process to SCHED\_FIFO. This causes the kernel to immediately preempt any currently running SCHED\_OTHER (normal) process in favour of l2tpns when it becomes runnable. Ignored on uniprocessor systems.
+
+- **send\_garp** (boolean)
+
+ Determines whether or not to send a gratuitous ARP for the bind\_address when the server is ready to handle traffic (default: true). This value is ignored if BGP is configured.
+
+- **tundevicename** (string)
+
+ Name of the tun interface (default: "tun0").
+
+- **throttle\_speed** (int)
+
+ Sets the default speed (in kbits/s) which sessions will be limited to. If this is set to 0, then throttling will not be used at all. Note: You can set this by the CLI, but changes will not affect currently connected users.
+
+- **throttle\_buckets** (int)
+
+ Number of token buckets to allocate for throttling. Each throttled session requires two buckets (in and out).
+
+## DHCPv6 And IPv6 SETTINGS
+
+- **dhcp6\_preferred\_lifetime** (int)
+
+ The preferred lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
+
+- **dhcp6\_valid\_lifetime** (int)
+
+ The valid lifetime for the IPv6 address and the IPv6 prefix address, expressed in units of seconds (see rfc3315).
+
+- **dhcp6\_server\_duid** (int)
+
+ DUID Based on Link-layer Address (DUID-LL) (see rfc3315).
+
+- **primary\_ipv6\_dns**, **secondary\_ipv6\_dns** (Ipv6 address)
+
+ IPv6 DNS servers will be sent to the user (see rfc3646).
+
+- **default\_ipv6\_domain\_list** (string)
+
+ The Domain Search List (ex: "fdn.fr") (see rfc3646).
+
+- **ipv6\_prefix** (Ipv6 address)
+
+ Enable negotiation of IPv6. This forms the the first 64 bits of the client allocated address. The remaining 64 come from the allocated IPv4 address and 4 bytes of 0.
+
+## LAC SETTINGS
+
+- **bind\_address\_remotelns** (ip address)
+
+ Address of the interface to listen the remote LNS tunnels. If no address is given, all interfaces are listened (Any Address).
+
+- **bind\_portremotelns** (short)
+
+ Port to bind for the Remote LNS (default: 65432).
+
+A static REMOTES LNS configuration can be entered by the command:
+
+- **setforward** _MASK_ _IP_ _PORT_ _SECRET_
+
+ where MASK specifies the mask of users who have forwarded to remote LNS (ex: "/friendISP@company.com").
+
+ where IP specifies the IP of the remote LNS (ex: "66.66.66.55").
+
+ where PORT specifies the L2TP Port of the remote LNS (Normally should be 1701) (ex: 1701).
+
+ where SECRET specifies the secret password the remote LNS (ex: mysecret).
+
+The static REMOTE LNS configuration can be used when the friend ISP not have a proxied Radius.
+
+If a proxied Radius is used, It will return the RADIUS attributes:
+
+- Tunnel-Type:1 = L2TP
+- Tunnel-Medium-Type:1 = IPv4
+- Tunnel-Password:1 = "LESECRETL2TP"
+- Tunnel-Server-Endpoint:1 = "88.xx.xx.x1"
+- Tunnel-Assignment-Id:1 = "friendisp\_lns1"
+- Tunnel-Type:2 += L2TP
+- Tunnel-Medium-Type:2 += IPv4
+- Tunnel-Password:2 += "LESECRETL2TP"
+- Tunnel-Server-Endpoint:2 += "88.xx.xx.x2"
+- Tunnel-Assignment-Id:2 += "friendisp\_lns2"
+
+## PPPOE SETTINGS
+
+- **pppoe\_if\_to\_bind** (string)
+
+ PPPOE server interface to bind (ex: "eth0.12"), If not specified the server PPPOE is not enabled. For the pppoe clustering, all the interfaces PPPOE of the clusters must use the same HW address (MAC address).
+
+- **pppoe\_service\_name** (string)
+
+ PPPOE service name (default: NULL).
+
+- **pppoe\_ac\_name** (string)
+
+ PPPOE access concentrator name (default: "l2tpns-pppoe").
+
+- **pppoe\_only\_equal\_svc\_name** (boolean)
+
+ If set to yes, the PPPOE server only accepts clients with a "service-name" different from NULL and a "service-name" equal to server "service-name" (default: no).
+
+## BGP ROUTING
+
+The routing configuration section is entered by the command
+
+**router** **bgp** _as_
+
+where _as_ specifies the local AS number.
+
+Subsequent lines prefixed with **neighbour** _peer_ define the attributes of BGP neighhbours. Valid commands are:
+
+**neighbour** _peer_ **remote-as** _as_
+
+**neighbour** _peer_ **timers** _keepalive_ _hold_
+
+Where _peer_ specifies the BGP neighbour as either a hostname or IP address, _as_ is the remote AS number and _keepalive_, _hold_ are the timer values in seconds.
+
+## NAMED ACCESS LISTS
+
+Named access lists may be defined with either of
+
+- **ip** **access-list** **standard** _name_
+- **ip** **access-list** **extended** _name_
+
+Subsequent lines starting with permit or deny define the body of the access-list.
+
+### Standard Access Lists
+
+Standard access lists are defined with:
+
+- {**permit**|**deny**} _source_ \[_dest_\]
+
+Where _source_ and _dest_ specify IP matches using one of:
+
+- _address_ _wildard_
+- **host** _address_
+- **any**
+
+_address_ and _wildard_ are in dotted-quad notation, bits in the _wildard_ indicate which address bits in _address_ are relevant to the match (0 = exact match; 1 = don't care).
+
+The shorthand 'host address' is equivalent to '_address_ **0.0.0.0**'; '**any**' to '**0.0.0.0** **255.255.255.255**'.
+
+### Extended Access Lists
+
+Extended access lists are defined with:
+
+- {**permit**|**deny**} _proto_ _source_ \[_ports_\] _dest_ \[_ports_\] \[_flags_\]
+
+Where _proto_ is one of **ip**, **tcp** or **udp**, and _source_ and _dest_ are as described above for standard lists.
+
+For TCP and UDP matches, source and destination may be optionally followed by a ports specification:
+
+- {**eq|neq|gt|lt**} _port_
+- **range** _from_ _to_
+
+_flags_ may be one of:
+
+- {**match-any|match-all**} {**+|-**}{**fin|syn|rst|psh|ack|urg**} ...
+
+ Match packets with any or all of the tcp flags set (+) or clear (-).
+
+- **established**
+
+ Match "established" TCP connections: packets with RST or ACK set, and SYN clear.
+
+- **fragments**
+
+ Match IP fragments. May not be specified on rules with layer 4 matches.
+
+# SEE ALSO
+
+[l2tpns(8)](http://man.he.net/man8/l2tpns)
