X-Git-Url: http://git.sameswireless.fr/l2tpns.git/blobdiff_plain/60589c977c109666cbec754da1a589fb22cd3f6d..b3f40f41f7de7a383c6f1170e546d0b09cc57338:/Docs/manual.html diff --git a/Docs/manual.html b/Docs/manual.html index d1ce33c..1c59720 100644 --- a/Docs/manual.html +++ b/Docs/manual.html @@ -52,41 +52,30 @@ H3 {
  • Interception
  • Authentication
  • Plugins
    • -
  • Walled Garden
    • +
  • Walled Garden
    • +
  • Filtering
  • Clustering
  • Routing
  • Performance

    • Overview

    -l2tpns is half of a complete L2TP implementation. It supports only the -LNS side of the connection.

    +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.

    +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, -it is nowhere near as scalable.

    +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.

    +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.

    +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.

    +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 david@dparrish.com.

    +HREF="mailto:l2tpns-users@lists.sourceforge.net?subject=L2TPNS+Documentation">the mailing list.

    Installation

    Requirements

    @@ -146,6 +135,7 @@ set ipaddress 192.168.1.1 set boolean true +

    +

    LAC configuration

    + + +

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

    + + + +

    BGP configuration

    + +

    BGP routing configuration is entered by the command: +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 +
    neighbout 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 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 @@ -390,8 +566,7 @@ 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. This currently only works with the walled garden module, but -modification is trivial to support other modules.

    +provided.

    Also, there are a number of signals that l2tpns understands and takes action when it receives them. @@ -496,19 +671,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: - + - -
    RadiusThe ID of the radius request. This is - sent in the packet to the radius server for identification.
    RadiusThe ID of the RADIUS request. This is + sent in the packet to the RADIUS server for identification.
    StateThe state of the request - WAIT, CHAP, AUTH, IPCP, START, STOP, NULL.
    SessionThe session ID that this radius +
    SessionThe session ID that this RADIUS request is associated with
    RetryIf a response does not appear to the request, it will retry at this time. This is a unix timestamp.
    TryRetry count. The radius request is +
    TryRetry count. The RADIUS request is discarded after 3 retries.

    @@ -549,7 +724,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.

    • @@ -560,7 +735,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.

    @@ -621,16 +796,13 @@ this way, although some may require a restart to take effect.

    nsctl

    -nsctl was implemented (badly) to allow messages to be passed to modules.

    +nsctl allows messages to be passed to plugins.

    -You must pass at least 2 parameters: host and command. The -host is the address of the l2tpns server which you want to send the message -to.

    +Arguments are command and optional args. See +nsctl(8) for more details.

    -Command can currently be either garden or ungarden. With -both of these commands, you must give a session ID as the 3rd parameter. -This will activate or deactivate the walled garden for a session -temporarily. +Built-in command are load_plugin, unload_plugin and +help. Any other commands are passed to plugins for processing.

    Signals

    @@ -641,16 +813,15 @@ 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

    @@ -659,7 +830,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 @@ -683,7 +854,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.

    @@ -693,11 +864,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.

    @@ -707,7 +878,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 @@ -757,39 +928,39 @@ supplied structure: - - @@ -798,12 +969,12 @@ supplied structure: seriously slow down the system. @@ -812,12 +983,12 @@ supplied structure: seriously slow down the system. @@ -826,9 +997,9 @@ supplied structure: you do is reentrant. @@ -836,10 +1007,10 @@ supplied structure: session is now ready to handle traffic. @@ -847,25 +1018,37 @@ supplied structure: This may be called multiple times for the same session. - + + + + @@ -874,21 +1057,13 @@ supplied structure: required.
    EventDescriptionParameters
    pre_authThis 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_authThis 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 +
    protocol
    0xC023 for PAP, 0xC223 for CHAP +
    packet_rx -
      -
    • 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 -
      -
    • 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 -
      -
    • time_now - The current unix timestamp
      • -
    +
    +
    time_now
    The current unix timestamp +
    new_session -
      -
    • t - Tunnel ID
      • -
    • s - Session ID
      • -
    +
    +
    t
    Tunnel +
    s
    Session +
    kill_session -
      -
    • t - Tunnel ID
      • -
    • s - Session ID
      • -
    +
    +
    t
    Tunnel +
    s
    Session +
    radius_responseThis 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_resetThis 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 -
      -
    • 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 +
    @@ -900,7 +1075,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 @@ -925,6 +1100,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 @@ -983,6 +1166,6 @@ That's really what it looks like.


    David Parrish
    -david@dparrish.com +l2tpns-users@lists.sourceforge.net