197cbe82bSArchie Cobbs.\" Copyright (c) 2001-2002 Packet Design, LLC. 297cbe82bSArchie Cobbs.\" All rights reserved. 397cbe82bSArchie Cobbs.\" 497cbe82bSArchie Cobbs.\" Subject to the following obligations and disclaimer of warranty, 597cbe82bSArchie Cobbs.\" use and redistribution of this software, in source or object code 697cbe82bSArchie Cobbs.\" forms, with or without modifications are expressly permitted by 797cbe82bSArchie Cobbs.\" Packet Design; provided, however, that: 897cbe82bSArchie Cobbs.\" 997cbe82bSArchie Cobbs.\" (i) Any and all reproductions of the source or object code 1097cbe82bSArchie Cobbs.\" must include the copyright notice above and the following 1197cbe82bSArchie Cobbs.\" disclaimer of warranties; and 1297cbe82bSArchie Cobbs.\" (ii) No rights are granted, in any manner or form, to use 1397cbe82bSArchie Cobbs.\" Packet Design trademarks, including the mark "PACKET DESIGN" 1497cbe82bSArchie Cobbs.\" on advertising, endorsements, or otherwise except as such 1597cbe82bSArchie Cobbs.\" appears in the above copyright notice or in the software. 1697cbe82bSArchie Cobbs.\" 1797cbe82bSArchie Cobbs.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND 1897cbe82bSArchie Cobbs.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO 1997cbe82bSArchie Cobbs.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING 2097cbe82bSArchie Cobbs.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED 2197cbe82bSArchie Cobbs.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 2297cbe82bSArchie Cobbs.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, 2397cbe82bSArchie Cobbs.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS 2497cbe82bSArchie Cobbs.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, 2597cbe82bSArchie Cobbs.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE 2697cbe82bSArchie Cobbs.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE 2797cbe82bSArchie Cobbs.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, 2897cbe82bSArchie Cobbs.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL 2997cbe82bSArchie Cobbs.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF 3097cbe82bSArchie Cobbs.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF 3197cbe82bSArchie Cobbs.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 3297cbe82bSArchie Cobbs.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 3397cbe82bSArchie Cobbs.\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF 3497cbe82bSArchie Cobbs.\" THE POSSIBILITY OF SUCH DAMAGE. 3597cbe82bSArchie Cobbs.\" 36c40d6a17SRuslan Ermilov.\" Author: Archie Cobbs <archie@FreeBSD.org> 3797cbe82bSArchie Cobbs.\" 3897cbe82bSArchie Cobbs.\" $FreeBSD$ 3997cbe82bSArchie Cobbs.\" 40*c60bda17SJoel Dahl.Dd November 13, 2012 4197cbe82bSArchie Cobbs.Dt NG_L2TP 4 4297cbe82bSArchie Cobbs.Os 4397cbe82bSArchie Cobbs.Sh NAME 4497cbe82bSArchie Cobbs.Nm ng_l2tp 4597cbe82bSArchie Cobbs.Nd L2TP protocol netgraph node type 4697cbe82bSArchie Cobbs.Sh SYNOPSIS 47fbad9e2dSRuslan Ermilov.In sys/types.h 4897cbe82bSArchie Cobbs.In netgraph/ng_l2tp.h 4997cbe82bSArchie Cobbs.Sh DESCRIPTION 5097cbe82bSArchie CobbsThe 51c40d6a17SRuslan Ermilov.Nm l2tp 5297cbe82bSArchie Cobbsnode type implements the encapsulation layer of the L2TP protocol 5397cbe82bSArchie Cobbsas described in RFC 2661. 5497cbe82bSArchie CobbsThis includes adding the L2TP packet header for outgoing packets 5597cbe82bSArchie Cobbsand verifying and removing it for incoming packets. 5697cbe82bSArchie CobbsThe node maintains the L2TP sequence number state and handles 5797cbe82bSArchie Cobbscontrol session packet acknowledgment and retransmission. 5897cbe82bSArchie Cobbs.Sh HOOKS 5997cbe82bSArchie CobbsThe 60c40d6a17SRuslan Ermilov.Nm l2tp 6197cbe82bSArchie Cobbsnode type supports the following hooks: 62*c60bda17SJoel Dahl.Bl -tag -width ".Va session_hhhh" 63*c60bda17SJoel Dahl.It Va lower 64c40d6a17SRuslan ErmilovL2TP frames. 65*c60bda17SJoel Dahl.It Va ctrl 66c40d6a17SRuslan ErmilovControl packets. 67*c60bda17SJoel Dahl.It Va session_hhhh 68c40d6a17SRuslan ErmilovSession 0xhhhh data packets. 6997cbe82bSArchie Cobbs.El 7097cbe82bSArchie Cobbs.Pp 7197cbe82bSArchie CobbsL2TP control and data packets are transmitted to, and received from, 7297cbe82bSArchie Cobbsthe L2TP peer via the 7397cbe82bSArchie Cobbs.Dv lower 7497cbe82bSArchie Cobbshook. 7597cbe82bSArchie CobbsTypically this hook would be connected to the 7697cbe82bSArchie Cobbs.Dv "inet/dgram/udp" 7797cbe82bSArchie Cobbshook of an 7897cbe82bSArchie Cobbs.Xr ng_ksocket 4 7997cbe82bSArchie Cobbsnode for L2TP over UDP. 8097cbe82bSArchie Cobbs.Pp 8197cbe82bSArchie CobbsThe 8297cbe82bSArchie Cobbs.Dv ctrl 8397cbe82bSArchie Cobbshook connects to the local L2TP management entity. 8497cbe82bSArchie CobbsL2TP control messages (without any L2TP headers) are transmitted 8597cbe82bSArchie Cobbsand received on this hook. 8697cbe82bSArchie CobbsMessages written to this hook are guaranteed to be delivered to the 8797cbe82bSArchie Cobbspeer reliably, in order, and without duplicates. 8897cbe82bSArchie Cobbs.Pp 8997cbe82bSArchie CobbsPackets written to the 9097cbe82bSArchie Cobbs.Dv ctrl 9197cbe82bSArchie Cobbshook must contain a two byte session ID prepended to the frame 9297cbe82bSArchie Cobbs(in network order). 9397cbe82bSArchie CobbsThis session ID is copied to the outgoing L2TP header. 9497cbe82bSArchie CobbsSimilarly, packets read from the 9597cbe82bSArchie Cobbs.Dv ctrl 9697cbe82bSArchie Cobbshook will have the received session ID prepended. 9797cbe82bSArchie Cobbs.Pp 9897cbe82bSArchie CobbsOnce an L2TP session has been created, the corresponding session 9997cbe82bSArchie Cobbshook may be used to transmit and receive the session's data frames: 10097cbe82bSArchie Cobbsfor the session with session ID 10197cbe82bSArchie Cobbs.Dv 0xabcd , 10297cbe82bSArchie Cobbsthe hook is named 10397cbe82bSArchie Cobbs.Dv session_abcd . 10497cbe82bSArchie Cobbs.Sh CONTROL MESSAGES 10597cbe82bSArchie CobbsThis node type supports the generic control messages, plus the following: 106*c60bda17SJoel Dahl.Bl -tag -width foo 107*c60bda17SJoel Dahl.It Dv NGM_L2TP_SET_CONFIG Pq Ic setconfig 10897cbe82bSArchie CobbsThis command updates the configuration of the node. 10997cbe82bSArchie CobbsIt takes a 110c40d6a17SRuslan Ermilov.Vt "struct ng_l2tp_config" 11197cbe82bSArchie Cobbsas an argument: 112c40d6a17SRuslan Ermilov.Bd -literal 11397cbe82bSArchie Cobbs/* Configuration for a node */ 11497cbe82bSArchie Cobbsstruct ng_l2tp_config { 11597cbe82bSArchie Cobbs u_char enabled; /* enables traffic flow */ 11697cbe82bSArchie Cobbs u_char match_id; /* tunnel id must match 'tunnel_id' */ 1176b99842aSEd Schouten uint16_t tunnel_id; /* local tunnel id */ 1186b99842aSEd Schouten uint16_t peer_id; /* peer's tunnel id */ 1196b99842aSEd Schouten uint16_t peer_win; /* peer's max recv window size */ 1206b99842aSEd Schouten uint16_t rexmit_max; /* max retransmits before failure */ 1216b99842aSEd Schouten uint16_t rexmit_max_to; /* max delay between retransmits */ 12297cbe82bSArchie Cobbs}; 12397cbe82bSArchie Cobbs.Ed 12497cbe82bSArchie Cobbs.Pp 12597cbe82bSArchie CobbsThe 12697cbe82bSArchie Cobbs.Va enabled 12797cbe82bSArchie Cobbsfield enables packet processing. 12897cbe82bSArchie CobbsEach time this field is changed back to zero the sequence 129c40d6a17SRuslan Ermilovnumber state is reset. 130c40d6a17SRuslan ErmilovIn this way, reuse of a node is possible. 13197cbe82bSArchie Cobbs.Pp 13297cbe82bSArchie CobbsThe 13397cbe82bSArchie Cobbs.Va tunnel_id 13497cbe82bSArchie Cobbsfield configures the local tunnel ID for the control connection. 13597cbe82bSArchie CobbsThe 13697cbe82bSArchie Cobbs.Va match_id 13797cbe82bSArchie Cobbsfield determines how incoming L2TP packets with a tunnel ID 13897cbe82bSArchie Cobbsfield different from 13997cbe82bSArchie Cobbs.Va tunnel_id 14097cbe82bSArchie Cobbsare handled. 14197cbe82bSArchie CobbsIf 14297cbe82bSArchie Cobbs.Va match_id 14397cbe82bSArchie Cobbsis non-zero, they will be dropped; otherwise, they will be dropped 14497cbe82bSArchie Cobbsonly if the tunnel ID is non-zero. 14597cbe82bSArchie CobbsTypically 14697cbe82bSArchie Cobbs.Va tunnel_id 14797cbe82bSArchie Cobbsis set to the local tunnel ID as soon as it is known and 14897cbe82bSArchie Cobbs.Va match_id 14997cbe82bSArchie Cobbsis set to non-zero after receipt of the SCCRP or SCCCN control message. 15097cbe82bSArchie Cobbs.Pp 15197cbe82bSArchie CobbsThe peer's tunnel ID should be set in 15297cbe82bSArchie Cobbs.Va peer_id 15397cbe82bSArchie Cobbsas soon as it is learned, typically after receipt of a SCCRQ or SCCRP 15497cbe82bSArchie Cobbscontrol message. 15597cbe82bSArchie CobbsThis value is copied into the L2TP header for outgoing packets. 15697cbe82bSArchie Cobbs.Pp 15797cbe82bSArchie CobbsThe 15897cbe82bSArchie Cobbs.Va peer_win 15997cbe82bSArchie Cobbsfield should be set from the 160c40d6a17SRuslan Ermilov.Dq "Receive Window Size" 16197cbe82bSArchie CobbsAVP received from the peer. 16297cbe82bSArchie CobbsThe default value for this field is one; zero is an invalid value. 16397cbe82bSArchie CobbsAs long as 16497cbe82bSArchie Cobbs.Va enabled 16597cbe82bSArchie Cobbsis non-zero, this value may not be decreased. 16697cbe82bSArchie Cobbs.Pp 16797cbe82bSArchie CobbsThe 16897cbe82bSArchie Cobbs.Va rexmit_max 16997cbe82bSArchie Cobbsand 17097cbe82bSArchie Cobbs.Va rexmit_max_to 17197cbe82bSArchie Cobbsfields configure packet retransmission. 17297cbe82bSArchie Cobbs.Va rexmit_max_to 17397cbe82bSArchie Cobbsis the maximum retransmission delay between packets, in seconds. 17497cbe82bSArchie CobbsThe retransmit delay will start at a small value and increase 17597cbe82bSArchie Cobbsexponentially up to this limit. 17697cbe82bSArchie CobbsThe 17797cbe82bSArchie Cobbs.Va rexmit_max 17897cbe82bSArchie Cobbssets the maximum number of times a packet will be retransmitted 17997cbe82bSArchie Cobbswithout being acknowledged before a failure condition is declared. 18097cbe82bSArchie CobbsOnce a failure condition is declared, each additional retransmission 18197cbe82bSArchie Cobbswill cause the 182c40d6a17SRuslan Ermilov.Nm l2tp 18397cbe82bSArchie Cobbsnode to send a 184*c60bda17SJoel Dahl.Dv NGM_L2TP_ACK_FAILURE Pq Ic ackfailure 18597cbe82bSArchie Cobbscontrol message back to the node that sent the last 18697cbe82bSArchie Cobbs.Dv NGM_L2TP_SET_CONFIG . 18797cbe82bSArchie CobbsAppropriate action should then be taken to shutdown the control connection. 188*c60bda17SJoel Dahl.It Dv NGM_L2TP_GET_CONFIG Pq Ic getconfig 18997cbe82bSArchie CobbsReturns the current configuration as a 190c40d6a17SRuslan Ermilov.Vt "struct ng_l2tp_config" . 191*c60bda17SJoel Dahl.It Dv NGM_L2TP_SET_SESS_CONFIG Pq Ic setsessconfig 19297cbe82bSArchie CobbsThis control message configures a single data session. 19397cbe82bSArchie CobbsThe corresponding hook must already be connected before sending this command. 19497cbe82bSArchie CobbsThe argument is a 195c40d6a17SRuslan Ermilov.Vt "struct ng_l2tp_sess_config" : 196c40d6a17SRuslan Ermilov.Bd -literal 19797cbe82bSArchie Cobbs/* Configuration for a session hook */ 19897cbe82bSArchie Cobbsstruct ng_l2tp_sess_config { 1996b99842aSEd Schouten uint16_t session_id; /* local session id */ 2006b99842aSEd Schouten uint16_t peer_id; /* peer's session id */ 201*c60bda17SJoel Dahl u_char control_dseq; /* whether we control data sequencing */ 202*c60bda17SJoel Dahl u_char enable_dseq; /* whether to enable data sequencing */ 203*c60bda17SJoel Dahl u_char include_length; /* whether to include length field */ 20497cbe82bSArchie Cobbs}; 20597cbe82bSArchie Cobbs.Ed 20697cbe82bSArchie Cobbs.Pp 20797cbe82bSArchie CobbsThe 20897cbe82bSArchie Cobbs.Va session_id 20997cbe82bSArchie Cobbsand 21097cbe82bSArchie Cobbs.Va peer_id 211c40d6a17SRuslan Ermilovfields configure the local and remote session IDs, respectively. 21297cbe82bSArchie Cobbs.Pp 21397cbe82bSArchie CobbsThe 21497cbe82bSArchie Cobbs.Va control_dseq 21597cbe82bSArchie Cobbsand 21697cbe82bSArchie Cobbs.Va enable_dseq 21797cbe82bSArchie Cobbsfields determine whether sequence numbers are used with L2TP data packets. 21897cbe82bSArchie CobbsIf 21997cbe82bSArchie Cobbs.Va enable_dseq 22097cbe82bSArchie Cobbsis zero, then no sequence numbers are sent and incoming sequence numbers 22197cbe82bSArchie Cobbsare ignored. 22297cbe82bSArchie CobbsOtherwise, sequence numbers are included on outgoing packets and checked 22397cbe82bSArchie Cobbson incoming packets. 22497cbe82bSArchie Cobbs.Pp 22597cbe82bSArchie CobbsIf 22697cbe82bSArchie Cobbs.Va control_dseq 22797cbe82bSArchie Cobbsis non-zero, then the setting of 22897cbe82bSArchie Cobbs.Va enable_dseq 22997cbe82bSArchie Cobbswill never change except by another 23097cbe82bSArchie Cobbs.Dv NGM_L2TP_SET_SESS_CONFIG 23197cbe82bSArchie Cobbscontrol message. 23297cbe82bSArchie CobbsIf 23397cbe82bSArchie Cobbs.Va control_dseq 23497cbe82bSArchie Cobbsis zero, then the peer controls whether sequence numbers are used: 23597cbe82bSArchie Cobbsif an incoming L2TP data packet contains sequence numbers, 23697cbe82bSArchie Cobbs.Va enable_dseq 23797cbe82bSArchie Cobbsis set to one, and conversely if an incoming L2TP data packet does not 23897cbe82bSArchie Cobbscontain sequence numbers, 23997cbe82bSArchie Cobbs.Va enable_dseq 24097cbe82bSArchie Cobbsis set to zero. 24197cbe82bSArchie CobbsThe current value of 24297cbe82bSArchie Cobbs.Va enable_dseq 24397cbe82bSArchie Cobbsis always accessible via the 24497cbe82bSArchie Cobbs.Dv NGM_L2TP_GET_SESS_CONFIG 24597cbe82bSArchie Cobbscontrol message (see below). 24697cbe82bSArchie CobbsTypically an LNS would set 24797cbe82bSArchie Cobbs.Va control_dseq 24897cbe82bSArchie Cobbsto one while a LAC would set 24997cbe82bSArchie Cobbs.Va control_dseq 25097cbe82bSArchie Cobbsto zero (if the Sequencing Required AVP were not sent), thus giving 25197cbe82bSArchie Cobbscontrol of data packet sequencing to the LNS. 25297cbe82bSArchie Cobbs.Pp 25397cbe82bSArchie CobbsThe 25497cbe82bSArchie Cobbs.Va include_length 25597cbe82bSArchie Cobbsfield determines whether the L2TP header length field is included 25697cbe82bSArchie Cobbsin outgoing L2TP data packets. 25797cbe82bSArchie CobbsFor incoming packets, the L2TP length field is always checked when present. 258*c60bda17SJoel Dahl.It Dv NGM_L2TP_GET_SESS_CONFIG Pq Ic getsessconfig 25997cbe82bSArchie CobbsThis command takes a two byte session ID as an argument and returns 26097cbe82bSArchie Cobbsthe current configuration for the corresponding data session as a 261c40d6a17SRuslan Ermilov.Vt "struct ng_l2tp_sess_config" . 26297cbe82bSArchie CobbsThe corresponding session hook must be connected. 263*c60bda17SJoel Dahl.It Dv NGM_L2TP_GET_STATS Pq Ic getstats 2644807330cSBjoern A. ZeebThis command returns a 265c40d6a17SRuslan Ermilov.Vt "struct ng_l2tp_stats" 2664807330cSBjoern A. Zeebcontaining statistics of the L2TP tunnel. 267*c60bda17SJoel Dahl.It Dv NGM_L2TP_CLR_STATS Pq Ic clrstats 2684807330cSBjoern A. ZeebThis command clears the statistics for the L2TP tunnel. 269*c60bda17SJoel Dahl.It Dv NGM_L2TP_GETCLR_STATS Pq Ic getclrstats 27097cbe82bSArchie CobbsSame as 27197cbe82bSArchie Cobbs.Dv NGM_L2TP_GET_STATS , 27297cbe82bSArchie Cobbsbut also atomically clears the statistics as well. 273*c60bda17SJoel Dahl.It Dv NGM_L2TP_GET_SESSION_STATS Pq Ic getsessstats 2744807330cSBjoern A. ZeebThis command takes a two byte session ID as an argument and returns a 2754807330cSBjoern A. Zeeb.Vt "struct ng_l2tp_session_stats" 2764807330cSBjoern A. Zeebcontaining statistics for the corresponding data session. 2774807330cSBjoern A. ZeebThe corresponding session hook must be connected. 278*c60bda17SJoel Dahl.It Dv NGM_L2TP_CLR_SESSION_STATS Pq Ic clrsessstats 2794807330cSBjoern A. ZeebThis command takes a two byte session ID as an argument and 2804807330cSBjoern A. Zeebclears the statistics for that data session. 2814807330cSBjoern A. ZeebThe corresponding session hook must be connected. 282*c60bda17SJoel Dahl.It Dv NGM_L2TP_GETCLR_SESSION_STATS Pq Ic getclrsessstats 2834807330cSBjoern A. ZeebSame as 2844807330cSBjoern A. Zeeb.Dv NGM_L2TP_GET_SESSION_STATS , 2854807330cSBjoern A. Zeebbut also atomically clears the statistics as well. 286*c60bda17SJoel Dahl.It Dv NGM_L2TP_SET_SEQ Pq Ic setsequence 2871e031324SBjoern A. ZeebThis command sets the sequence numbers of a not yet enabled node. 2881e031324SBjoern A. ZeebIt takes a 2891e031324SBjoern A. Zeeb.Vt "struct ng_l2tp_seq_config" 2901e031324SBjoern A. Zeebas argument, where 2911e031324SBjoern A. Zeeb.Va xack 2921e031324SBjoern A. Zeeband 2931e031324SBjoern A. Zeeb.Va nr 2941e031324SBjoern A. Zeebrespectively 2951e031324SBjoern A. Zeeb.Va ns 2961e031324SBjoern A. Zeeband 2971e031324SBjoern A. Zeeb.Va rack 2981e031324SBjoern A. Zeebmust be the same. 2991e031324SBjoern A. ZeebThis option is particularly useful if one receives and processes 3001e031324SBjoern A. Zeebthe first packet entirely in userspace and wants to hand over further 3011e031324SBjoern A. Zeebprocessing to the node. 30297cbe82bSArchie Cobbs.El 30397cbe82bSArchie Cobbs.Sh SHUTDOWN 30497cbe82bSArchie CobbsThis node shuts down upon receipt of a 30597cbe82bSArchie Cobbs.Dv NGM_SHUTDOWN 30697cbe82bSArchie Cobbscontrol message, or when all hooks have been disconnected. 30797cbe82bSArchie Cobbs.Sh SEE ALSO 30897cbe82bSArchie Cobbs.Xr netgraph 4 , 30997cbe82bSArchie Cobbs.Xr ng_ksocket 4 , 31097cbe82bSArchie Cobbs.Xr ng_ppp 4 , 3113ac17febSRuslan Ermilov.Xr ng_pptpgre 4 , 31297cbe82bSArchie Cobbs.Xr ngctl 8 31397cbe82bSArchie Cobbs.Rs 31497cbe82bSArchie Cobbs.%A W. Townsley 31597cbe82bSArchie Cobbs.%A A. Valencia 31697cbe82bSArchie Cobbs.%A A. Rubens 31797cbe82bSArchie Cobbs.%A G. Pall 31897cbe82bSArchie Cobbs.%A G. Zorn 31997cbe82bSArchie Cobbs.%A B. Palter 32097cbe82bSArchie Cobbs.%T "Layer Two Tunneling Protocol L2TP" 32197cbe82bSArchie Cobbs.%O RFC 2661 32297cbe82bSArchie Cobbs.Re 32397cbe82bSArchie Cobbs.Sh HISTORY 32497cbe82bSArchie CobbsThe 325c40d6a17SRuslan Ermilov.Nm l2tp 326c40d6a17SRuslan Ermilovnode type was developed at Packet Design, LLC, 327c40d6a17SRuslan Ermilov.Pa http://www.packetdesign.com/ . 32897cbe82bSArchie Cobbs.Sh AUTHORS 32997cbe82bSArchie Cobbs.An Archie Cobbs Aq archie@packetdesign.com 330