welterde/l2tpns
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Convert docbook documentation to markdown, add build mechanism using pandoc

Browse source
This commit is contained in:
Julien Rabier 2021-01-31 17:06:23 +01:00
parent db5ff8c356
commit 72609641db
26 changed files with 4273 additions and 6022 deletions
Download patch file Download diff file Expand all files Collapse all files

1104
docs/src/html/manual.md Normal file
View file

File diff suppressed because it is too large Load diff

596
docs/src/html/practical-vpns.md Normal file
View file

@ -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.
![site to site](./images/site-to-site-vpn.png)
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.
![tunneling process](./images/tunneling-process.png)
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.
![vpn deployment](./images/vpn-deployment.png)
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).
![vpn process](./images/vpn-process.png)
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)

120
docs/src/man/l2tpns.8.md Normal file
View file

@ -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 <noodles@earth.li> and Fernando Alves (fendo@sameswifi.fr), for the Debian GNU/Linux system (but may be used by others).

68
docs/src/man/nsctl.8.md Normal file
View file

@ -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
\<noodles\@the.earth.li\>, for the Debian GNU/Linux system (but may be
used by others).

397
docs/src/man/startup-config.5.md Normal file
View file

@ -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)