prol2tp

NAME

prol2tp - command-line management application for ProL2TP

SYNOPSIS

prol2tp show system [statistics | config]
prol2tp show license
prol2tp show peer profile [<name>]
prol2tp show tunnel profile [<name>]
prol2tp show session profile [<name>]
prol2tp show ppp profile [<name>]
prol2tp show ethernet profile [<name>]
prol2tp show tunnel [<name|id>] [config|status]
prol2tp show session [<name|@id>] [<name|@id>]] [config|status]
prol2tp show ippool [<name>]
prol2tp debug <debug-option-list> <on|off>
prol2tp debug tunnel profile <name> <on|off>
prol2tp debug session profile <name> <on|off>
prol2tp debug ippool <name> <on|off>
prol2tp debug tunnel <name|@id> <on|off>
prol2tp debug session <name|@id> <name|@id> <on|off>
prol2tp show log
prol2tp clear log

DESCRIPTION

This document provides documentation of ProL2TP's prol2tp command line utility, which is used to display status of the prol2tpd daemon. It also provides a convenient interface to modify debug control settings. Refer to prol2tp(7) for a general description of the ProL2TP package. Use the following command to access that page instead of this one.

# man 7 prol2tp

ProL2TP is controlled using a private control socket. Messages are exchanged with the prol2tp daemon. This application lets operators examine the state of a running prol2tpd, showing detailed configuration information and listing currently open tunnels and sessions.

With the optional ProL2TP SDK, custom applications using the ProL2TP API may be developed where closer integration with third party systems is needed, e.g. billing systems.

The main configuration interface of prol2tpd is the config file, described in prol2tpd.conf(5). This application provides read-only access to the daemon's state.

For information about the general features of ProL2TP please refer to the prol2tp(7) manual page.

ENVIRONMENT

prol2tpd must be running before the first prol2tp command is issued. ProL2TP uses private Unix sockets to communicate with prol2tpd, so the system must be capable of running Unix sockets. If prol2tpd is not running when prol2tp is invoked, an error will occur.

SHOW COMMANDS

The commands supported by prol2tp are listed below.

SHOW SYSTEM

prol2tp show system [statistics | config]

Displays system global configuration or statistics. Use this command to quickly see how many active tunnels and sessions that prol2tpd is handling. For debugging problems, dump detailed statistics from the daemon using the optional statistics command switch.

SHOW LICENSE

prol2tp show license

Displays information about the license. Some licenses limit the features available. Use this command to verify the license is installed correctly.

SHOW PEER PROFILE

prol2tp show peer profile [<profile-name>]

Displays a list of peer profiles or information about a specific peer profile. To see detailed configuration of a specific profile, provide the profile name when entering the command.

Peer profiles are the core mechanism used in servers to identify specific tunnel, session and ppp profiles for incoming requests from clients. Peers are identified by name or by IP address / netmask. The peer profile specifies default tunnel, session and PPP profile names which are to be used for the peer, unless overridden by other settings. Peer profiles are matched by IP address or peer identifier, which is provided in the L2TP tunnel setup request. Thus, peer profiles are only needed when different parameters are required for different peers.

SHOW TUNNEL PROFILE

prol2tp show tunnel profile [<profile-name>]

Displays a list of tunnel profiles or information about a specific tunnel profile. To see detailed configuration of a specific profile, provide the profile name when entering the command.

Tunnel profiles provide tunnel parameter values. These are used to configure settings such as tunnel authentication mode and secret, UDP or IP encapsulation, L2TP protocol parameters etc.

SHOW SESSION PROFILE

prol2tp show session profile [<profile-name>]

Displays a list of session profiles or information about a specific session profile. To see detailed configuration of a specific profile, provide the profile name when entering the command.

Session profiles provide session parameter values. These are used to configure settings such as session type, data sequence number enable, allowed framing types etc.

SHOW ETHERNET PROFILE

prol2tp show ethernet profile [<profile-name>]

Displays a list of ethernet profiles or information about a specific ethernet profile. To see detailed configuration of a specific profile, provide the profile name when entering the command.

Ethernet profiles define parameter values for L2TPv3 ethernet pseudowires. Use ethernet profiles to configure interface MTU and network interface parameters, such as bridge association.

SHOW PPP PROFILE

prol2tp show ppp profile [<profile-name>]

Displays a list of ppp profiles or information about a specific ppp profile. To see detailed configuration of a specific profile, provide the profile name when entering the command.

PPP profiles define parameter values for PPP sessions. For most setups, defaults will work fine. However, when certain PPP settings need to be set up, i.e. disabling mschap PPP authentication for some sessions, PPP profiles are useful.

SHOW TUNNEL

prol2tp show tunnel [<tunnel-name>|<@tunnel-id>] [config | status]

Displays a list of tunnels or detailed configuration and status of a specific tunnel. The tunnel is identified by a name (the name it is given in prol2tpd.conf) or its tunnel-id, which is usually assigned by the L2TP protocol. The optional config keyword may be used to suppress detailed status and statistics data from the tunnel dump output. Similarly, the optional status keyword suppresses detailed configuration data from the tunnel dump output. Tunnels can only have names when they are locally created. Tunnels created as a result of a request from a remote peer are marked with a '*' in the first column of the summary listing.

The tunnel summary listing lists some information about each tunnel, namely its tunnel id, the peer tunnel id, local and remote IP addresses and operational state. To dump more detailed configuration of a specific tunnel, simply provide the tunnel name or id with the command.

To distinguish tunnel names from tunnel ids, the @ character is used to prefix tunnel ids. This is needed because it is legal to name a tunnel with a numeric value. Therefore, to display detail about tunnel with tunnel-id 1234, use

# prol2tp show tunnel @1234

not

# prol2tp show tunnel 1234

SHOW SESSION

prol2tp show session [<tunnel-name>|<@tunnel-id>] \
        [<session-name>|<@session-id>] [config | status]

Displays a list of sessions or detailed configuration and status of a specific session. The session is identified by a name (the name it is given in prol2tpd.conf) or its session-id, which is usually assigned by the L2TP protocol. Sessions can only have names when they are locally created. Session names and session ids are scoped by tunnels. Thus, it is possible to have two sessions with id 3456 in different tunnels. The optional config keyword may be used to suppress detailed status and statistics data from the session dump output. Similarly, the optional status keyword suppresses detailed configuration data from the session dump output.

The session summary listing lists some information about each session, namely its session id, the peer session id, session type and operational state. To dump a list of sessions only on a specific tunnel, give the tunnel name or id with the command (but omit the session information). To dump more detailed configuration of a specific session, provide the tunnel name or id and the session name or id with the command. Sessions created as a result of a request from a remote peer are marked with a '*' in the first column of the summary listing.

To distinguish session names from session ids, the @ character is used to prefix session ids. This is needed because it is legal to name a session with a numeric value. Therefore, to display detail about session with session-id 1234, use

# prol2tp show session @4567 @1234

not

# prol2tp show session @4567 1234

SHOW IPPOOL

prol2tp show ippool [<pool-name>]

Show a named ip pool, or list ip pool instances if no pool name is given.

DEBUG COMMANDS

The debug commands supported by prol2tp are listed below.

Debug options are specified as a comma separated list of one or more of:-

protocol             - L2TP protocol events
fsm                  - Finite State Machine events (e.g. state changes)
api                  - Management interface interactions
transport            - Log tunnel transport activity, e.g. packet
                       sequence numbers, packet receive and transmit, to
                       debug tunnel link establishment or failures
data                 - Log L2TP data channel activity. Only L2TP control
                       messages are logged, never user data packets.
ppp                  - Enables trace of PPP packets from the PPP subsystem
avp                  - L2TP Attribute Value Pairs (AVPs).
func                 - Internal functional behavior
system               - Low level system activity, e.g. timers, sockets etc
kernel               - Messages from the kernel's L2TP subsystem
all                  - Special value, meaning all of the above.
none                 - Special value, meaning none of the above.

DEBUG SYSTEM

prol2tp debug <debug-option-list> <on|off>

Enable or disable the specified list of debug message types. Changing this value is equivalent to setting the same value using the debug setting in the system block of the config file.

DEBUG TUNNEL PROFILE

prol2tp debug tunnel profile <name> <on|off>

Enable or disable debug in tunnel instances created using the named tunnel profile.

DEBUG SESSION PROFILE

prol2tp debug session profile <name> <on|off>

Enable or disable debug in session instances created using the named session profile.

DEBUG IPPOOL

prol2tp debug ippool <name> <on|off>

Enable or disable debug of operations to the named IP pool. This may be useful to trace the allocation and release of addresses from the pool.

DEBUG TUNNEL

prol2tp debug tunnel <name|@id> <on|off>

Enable or disable debug messages of the specified tunnel instance. The tunnel must aleady exist. Tunnels may be identified by name or id. Tunnel ids are denoted using an '@' in front of the numeric tunnel id.

DEBUG SESSION

prol2tp debug session <name|@id> <name|@id> <on|off>

Enable or disable debug messages of the specified session instance. The session must already exist. Tunnels and sessions may be identified by name or id. Ids are denoted using an '@' in front of the numeric tunnel or session id.

LOG COMMANDS

ProL2TP has support for a separately configurable, internal log buffer. Debug messages can be configured to be logged there and viewed or cleared using commands defined here. The logging commands supported by prol2tp are listed below.

SHOW LOG

Shows all the messages in the log buffer. The log buffer can be configured to overwrite old messages when it becomes full, or to stop logging when it fills up.

CLEAR LOG

Clears the log buffer.

EXAMPLES



Show system configuration and statistics

# prol2tp show system
L2TP configuration:
  Preferred protocol: L2TPv2
  UDP port: 1701
  Listening on: 192.168.1.12
  max tunnels: 0 (unlimited), max sessions: 0 (unlimited)
  drain tunnels: NO
  deny local tunnel creation: NO, deny remote tunnel creation: NO
  trace flags: PROTOCOL FSM API
L2TP service status:-
  tunnels: 2, sessions: 2

# prol2tp show system statistics
L2TP counters:-
  Total messages sent: 4, received: 10, retransmitted: 0
    illegal: 0, unsupported: 0, ignored AVPs: 0, vendor AVPs: 0
  Setup failures: tunnels: 0, sessions: 0
  Resource failures: control frames: 0, peers: 0
    tunnels: 0, sessions: 0, ppp: 0
  Limit exceeded errors: tunnels: 0, sessions: 0
  Frame errors: short frames: 0, wrong version frames: 0
     unexpected data frames: 0, bad frames: 0
  Internal: authentication failures: 0, message encode failures: 0
     no matching tunnel discards: 0, mismatched tunnel ids: 0
     no matching session_discards: 0, mismatched session ids: 0
     total control frame send failures: 0, event queue fulls: 0

  Message counters:-
         Message          RX Good           RX Bad               TX
           SCCRQ                2                0                0
           SCCRP                0                0                2
           SCCCN                2                0                0
           HELLO                267              0              254
            ICRQ                2                0                0
            ICRP                0                0                2
            ICCN                2                0                0

List tunnel profiles, then show detail of one of them.

# prol2tp show tunnel profile
default five    nine    seven   ten     two
eight   four    one     six     three

# prol2tp show tunnel profile three
Tunnel profile three
  authorization mode NONE, hide AVPs OFF
  hello timeout 60, retry timeout 1, idle timeout 0
  persist pend timeout: 300
  rx window size 10, tx window size 10, max retries 5
  use UDP checksums: ON
  do pmtu discovery: OFF, mtu: 1460
  framing capability: SYNC ASYNC
  bearer capability: DIGITAL ANALOG
  use tiebreaker: OFF
  peer profile: default
  session profile: default
  ppp profile: default

List session profiles, then show detail of one of them.

# prol2tp show session profile
default five    nine    seven   ten     two
eight   four    one     six     three
# prol2tp show session profile nine
Session profile nine
  ppp profile: default
  session type: unspecified
  data sequencing required: OFF
  use data sequence numbers: OFF
  persist pend timeout: 60
  framing types: SYNC ASYNC
  bearer types: DIGITAL ANALOG
  connect speed: 1000000

List ppp profiles, then show detail of one of them.

# prol2tp show ppp profile
default five    nine    seven   ten     two
eight   four    one     six     three

# prol2tp show ppp profile two
Ppp profile two
  mru: 1500, mtu: 1500, mode: SYNC|ASYNC
  allowed authentications: PAP CHAP MSCHAP
  max connect time: 0, max failure count: 10, idle timeout: 0
  multilink: NO, proxy arp: NO
  IP parameters:-
    local address: NOT SET, peer address: NOT SET
    dns addresses: NOT SET / NOT SET
    wins addresses: NOT SET / NOT SET
    use radius: YES
  PAP parameters:-
    max auth requests: 10, restart interval: 3, timeout: 0
  CHAP parameters:-
    interval: 10, max challenge: 10, restart: 3
  LCP parameters:-
    echo failure count: 0, echo interval: 0
    max config requests: 10, max config naks: 10
    max terminate requests: 3, retransmit interval: 3
  IPCP parameters:-
    max config requests: 10, max config naks: 10
    max terminate requests: 3, retransmit interval: 3

List tunnels, then show detail of one of them.

# prol2tp show tunnel
       TunId            Local             Peer    PeerTId       State
*      60676     192.168.1.12     192.168.1.10          8 ESTABLISHED
*      49634     192.168.1.12     192.168.1.11          8 ESTABLISHED

# prol2tp show tunnel @60676 config
Tunnel 60676, from 192.168.1.12 to 192.168.1.10:-
  state: ESTABLISHED
  created at:  Feb 15 17:07:36 2009
  created by admin: NO, tunnel mode: LNS
  peer tunnel id: 8, host name: NOT SET
  UDP ports: local 36638, peer 1701
  authorization mode: NONE, hide AVPs: OFF
  session limit: 0, session count: 1
  tunnel profile: default, peer profile: default
  session profile: default, ppp profile: default
  hello timeout: 60, retry timeout: 1, idle timeout: 0
  rx window size: 10, tx window size: 10, max retries: 5
  use udp checksums: ON
  do pmtu discovery: OFF, mtu: 1460
  framing capability: SYNC ASYNC, bearer capability: DIGITAL ANALOG
  use tiebreaker: OFF
  trace flags: PROTOCOL FSM API
  peer vendor name: Microsoft
  peer protocol version: 1.0, firmware 1280
  peer framing capability: SYNC
  peer bearer capability: NONE
  peer rx window size: 8
  negotiated tx window size: 8

List sessions, then show detail of one of them.

# prol2tp show session
       TunId     SessId PeerSessId Type             Name        State
*      60676      48098          1  PPP                   ESTABLISHED
*      49634       3780          1  PPP                   ESTABLISHED

# prol2tp show session @60676 @48098
Session 48098 on tunnel 60676:-
  type: LNS Incoming Call, state: ESTABLISHED
  created at:  Feb 15 17:07:36 2009
  created by admin: NO, peer session id: 1
  interface name: ppp0
  data sequencing required: OFF
  use data sequence numbers: OFF
  trace flags: PROTOCOL FSM API
  framing types: SYNC ASYNC
  bearer types: DIGITAL ANALOG
  connect speed: 1000000
  use ppp proxy: NO

  Peer configuration data:-
    data sequencing required: OFF
    framing types: SYNC
    bearer types: ANALOG
    connect speed: 54000000
  data rx packets: 1053, rx bytes: 121084, rx errors: 0
  data tx packets: 8, tx bytes: 259, tx errors: 0

List connected users.

# prol2tp show ppp
      TunId      SesId User                              Create Time
*     60676      48098 james                Sun Feb 15 17:07:36 2009
*     49634       3780 chris                Sun Feb 15 18:12:42 2009