X-Git-Url: http://git.sameswireless.fr/l2tpns.git/blobdiff_plain/f5071c422df06800e59bb1be0218c0f6ec2ba831..5cc3beb6c7570c2b5b425e61d66000cc0a95da17:/Docs/manual.html
diff --git a/Docs/manual.html b/Docs/manual.html
index 59d6dbc..bebc7c8 100644
--- a/Docs/manual.html
+++ b/Docs/manual.html
@@ -52,9 +52,11 @@ H3 {
Interception
Authentication
Plugins
- Walled Garden
+ Walled Garden
+ Filtering
Clustering
Routing
+ Avoiding Fragmentation
Performance
@@ -66,7 +68,7 @@ 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 imlementations, 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,
@@ -183,6 +185,13 @@ the same as the LAC, or authentication will fail. Only actually be
used if the LAC requests authentication.
+
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
@@ -190,39 +199,52 @@ user, both a primary and a secondary. If either is set to 0.0.0.0, then that
one will not be sent.
-save_state (boolean)
-When l2tpns receives a STGTERM it will write out its current
-ip_address_pool, session and tunnel tables to disk prior to exiting to
-be re-loaded at startup. The validity of this data is obviously quite
-short and the intent is to allow an sessions to be retained over a
-software upgrade.
-
-
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.
+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 supress (in order to cope with a
+large number of sessions comming on-line simultaneously l2tpns uses a
+set of udp sockets, each with a seperate identifier).
primary_radius_port (short)
secondary_radius_port (short)
-Sets the authentication ports for the primary and secondary radius
+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
+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
+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.
+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)
@@ -276,10 +298,6 @@ second. Even if this is disabled, you can see this information by running
the uptime command on the CLI.
-cleanup_interval (int)
-Interval between regular cleanups (in seconds).
-
-
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
@@ -301,6 +319,13 @@ Keep all pages mapped by the l2tpns process in memory.
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.
@@ -310,6 +335,10 @@ on Clustering for more information.
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.
@@ -319,6 +348,11 @@ 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 minumum number of up to date slaves required before the
+master will drop routes (default: 1).
+
BGP routing configuration is entered by the command:
@@ -338,6 +372,42 @@ 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 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
Usernames and passwords for the command-line interface are stored in
@@ -500,19 +570,19 @@ IP Address Used Session User
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
+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. |
+ 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
+ |
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
+ |
Try | Retry count. The RADIUS request is
discarded after 3 retries. |
@@ -553,7 +623,7 @@ 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
+If you want interception to be permanent, you will have to modify the RADIUS
response for the user. See Interception.
@@ -564,7 +634,7 @@ 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.
+RADIUS response for the user. See Throttling.
@@ -642,16 +712,15 @@ killall -HUP l2tpns
The signals understood are:
-
-- SIGHUP - Reload the config from disk and re-open log file
-- SIGTERM / SIGINT - Shut down for a restart. This will dump the current
-state to disk (if save_state is set to true). Upon restart, the
-process will read this saved state to resume active sessions.
-
- SIGQUIT - Shut down cleanly. This will send a disconnect message for
-every active session and tunnel before shutting down. This is a good idea
-when upgrading the code, as no sessions will be left with the remote end
-thinking they are open.
-
+
+- 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
@@ -660,7 +729,7 @@ 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
+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
@@ -684,7 +753,7 @@ 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
+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.
@@ -694,11 +763,11 @@ 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
+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
+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.
@@ -708,7 +777,7 @@ 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
+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
@@ -758,39 +827,39 @@ supplied structure:
Event | Description | Parameters |
pre_auth |
- This is called after a radius response has been
+ | 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 ID
- - s - Session ID
- - username
- - password
- - protocol (0xC023 for PAP, 0xC223 for CHAP)
- - continue_auth - Set to 0 to stop processing authentication modules
-
+
+ - 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
+ | 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 ID
- - s - Session ID
- - username
- - auth_allowed - This is already set to true or
+
+ - 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)
-
+ allow or disallow authentication
+ protocol0xC023 for PAP, 0xC223 for CHAP
+
|
packet_rx |
@@ -799,12 +868,12 @@ supplied structure:
seriously slow down the system.
-
- - t - Tunnel ID
- - s - Session ID
- - buf - The raw packet data
- - len - The length of buf
-
+
+ - t
- Tunnel
+
- s
- Session
+
- buf
- The raw packet data
+
- len
- The length of buf
+
|
packet_tx |
@@ -813,12 +882,12 @@ supplied structure:
seriously slow down the system.
-
- - t - Tunnel ID
- - s - Session ID
- - buf - The raw packet data
- - len - The length of buf
-
+
+ - t
- Tunnel
+
- s
- Session
+
- buf
- The raw packet data
+
- len
- The length of buf
+
|
timer |
@@ -827,9 +896,9 @@ supplied structure:
you do is reentrant.
-
- - time_now - The current unix timestamp
-
+
+ - time_now
- The current unix timestamp
+
|
new_session |
@@ -837,10 +906,10 @@ supplied structure:
session is now ready to handle traffic.
-
- - t - Tunnel ID
- - s - Session ID
-
+
+ - t
- Tunnel
+
- s
- Session
+
|
kill_session |
@@ -848,25 +917,37 @@ supplied structure:
This may be called multiple times for the same session.
-
- - t - Tunnel ID
- - s - Session ID
-
+
+ - t
- Tunnel
+
- s
- Session
+
|
radius_response |
- This is called whenever a radius response includes a
+ | 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 ID
- - s - Session ID
- - key
- - value
-
+
+ - 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 |
@@ -875,21 +956,13 @@ supplied structure:
required.
-
- - buf - The raw packet data
- - l - The raw packet data length
- - source_ip - Where the request came from
- - source_port - Where the request came from
- - response - Allocate a buffer and put your response in here
- - response_length - Length of response
- - send_response - true or false whether a response
- should be sent. If you set this to true, you must
- allocate a response buffer.
- - type - Type of request (see nsctl.c)
- - id - ID of request
- - data - I'm really not sure
- - data_length - Length of data
-
+
+ - 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
+
|
@@ -901,7 +974,7 @@ 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
+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
@@ -926,6 +999,14 @@ 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
@@ -973,6 +1054,22 @@ 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.
+
Avoiding Fragmentation
+
+Fragmentation of encapsulated return packets to the LAC may be avoided
+for TCP sessions by adding a firewall rule to clamps the MSS on
+outgoing SYN packets.
+
+The following is appropriate for interfaces with a typical MTU of
+1500:
+
+
+iptables -A FORWARD -i tun+ -o eth0 \
+ -p tcp --tcp-flags SYN,RST SYN \
+ -m tcpmss --mss 1413:1600 \
+ -j TCPMSS --set-mss 1412
+
+
Performance is great.