1.\" Copyright (c) 2001-2002 Packet Design, LLC. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, 5.\" use and redistribution of this software, in source or object code 6.\" forms, with or without modifications are expressly permitted by 7.\" Packet Design; provided, however, that: 8.\" 9.\" (i) Any and all reproductions of the source or object code 10.\" must include the copyright notice above and the following 11.\" disclaimer of warranties; and 12.\" (ii) No rights are granted, in any manner or form, to use 13.\" Packet Design trademarks, including the mark "PACKET DESIGN" 14.\" on advertising, endorsements, or otherwise except as such 15.\" appears in the above copyright notice or in the software. 16.\" 17.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND 18.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO 19.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING 20.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED 21.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 22.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, 23.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS 24.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, 25.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE 26.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE 27.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, 28.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL 29.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF 30.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF 31.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 33.\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF 34.\" THE POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" Author: Archie Cobbs <archie@FreeBSD.org> 37.\" 38.\" $FreeBSD$ 39.\" 40.Dd August 2, 2004 41.Dt NG_L2TP 4 42.Os 43.Sh NAME 44.Nm ng_l2tp 45.Nd L2TP protocol netgraph node type 46.Sh SYNOPSIS 47.In sys/types.h 48.In netgraph/ng_l2tp.h 49.Sh DESCRIPTION 50The 51.Nm l2tp 52node type implements the encapsulation layer of the L2TP protocol 53as described in RFC 2661. 54This includes adding the L2TP packet header for outgoing packets 55and verifying and removing it for incoming packets. 56The node maintains the L2TP sequence number state and handles 57control session packet acknowledgment and retransmission. 58.Sh HOOKS 59The 60.Nm l2tp 61node type supports the following hooks: 62.Pp 63.Bl -tag -compact -offset indent -width ".Dv session_hhhh" 64.It Dv lower 65L2TP frames. 66.It Dv ctrl 67Control packets. 68.It Dv session_hhhh 69Session 0xhhhh data packets. 70.El 71.Pp 72L2TP control and data packets are transmitted to, and received from, 73the L2TP peer via the 74.Dv lower 75hook. 76Typically this hook would be connected to the 77.Dv "inet/dgram/udp" 78hook of an 79.Xr ng_ksocket 4 80node for L2TP over UDP. 81.Pp 82The 83.Dv ctrl 84hook connects to the local L2TP management entity. 85L2TP control messages (without any L2TP headers) are transmitted 86and received on this hook. 87Messages written to this hook are guaranteed to be delivered to the 88peer reliably, in order, and without duplicates. 89.Pp 90Packets written to the 91.Dv ctrl 92hook must contain a two byte session ID prepended to the frame 93(in network order). 94This session ID is copied to the outgoing L2TP header. 95Similarly, packets read from the 96.Dv ctrl 97hook will have the received session ID prepended. 98.Pp 99Once an L2TP session has been created, the corresponding session 100hook may be used to transmit and receive the session's data frames: 101for the session with session ID 102.Dv 0xabcd , 103the hook is named 104.Dv session_abcd . 105.Sh CONTROL MESSAGES 106This node type supports the generic control messages, plus the following: 107.Bl -tag -width indent 108.It Dv NGM_L2TP_SET_CONFIG 109This command updates the configuration of the node. 110It takes a 111.Vt "struct ng_l2tp_config" 112as an argument: 113.Bd -literal 114/* Configuration for a node */ 115struct ng_l2tp_config { 116 u_char enabled; /* enables traffic flow */ 117 u_char match_id; /* tunnel id must match 'tunnel_id' */ 118 u_int16_t tunnel_id; /* local tunnel id */ 119 u_int16_t peer_id; /* peer's tunnel id */ 120 u_int16_t peer_win; /* peer's max recv window size */ 121 u_int16_t rexmit_max; /* max retransmits before failure */ 122 u_int16_t rexmit_max_to; /* max delay between retransmits */ 123}; 124.Ed 125.Pp 126The 127.Va enabled 128field enables packet processing. 129Each time this field is changed back to zero the sequence 130number state is reset. 131In this way, reuse of a node is possible. 132.Pp 133The 134.Va tunnel_id 135field configures the local tunnel ID for the control connection. 136The 137.Va match_id 138field determines how incoming L2TP packets with a tunnel ID 139field different from 140.Va tunnel_id 141are handled. 142If 143.Va match_id 144is non-zero, they will be dropped; otherwise, they will be dropped 145only if the tunnel ID is non-zero. 146Typically 147.Va tunnel_id 148is set to the local tunnel ID as soon as it is known and 149.Va match_id 150is set to non-zero after receipt of the SCCRP or SCCCN control message. 151.Pp 152The peer's tunnel ID should be set in 153.Va peer_id 154as soon as it is learned, typically after receipt of a SCCRQ or SCCRP 155control message. 156This value is copied into the L2TP header for outgoing packets. 157.Pp 158The 159.Va peer_win 160field should be set from the 161.Dq "Receive Window Size" 162AVP received from the peer. 163The default value for this field is one; zero is an invalid value. 164As long as 165.Va enabled 166is non-zero, this value may not be decreased. 167.Pp 168The 169.Va rexmit_max 170and 171.Va rexmit_max_to 172fields configure packet retransmission. 173.Va rexmit_max_to 174is the maximum retransmission delay between packets, in seconds. 175The retransmit delay will start at a small value and increase 176exponentially up to this limit. 177The 178.Va rexmit_max 179sets the maximum number of times a packet will be retransmitted 180without being acknowledged before a failure condition is declared. 181Once a failure condition is declared, each additional retransmission 182will cause the 183.Nm l2tp 184node to send a 185.Dv NGM_L2TP_ACK_FAILURE 186control message back to the node that sent the last 187.Dv NGM_L2TP_SET_CONFIG . 188Appropriate action should then be taken to shutdown the control connection. 189.It Dv NGM_L2TP_GET_CONFIG 190Returns the current configuration as a 191.Vt "struct ng_l2tp_config" . 192.It Dv NGM_L2TP_SET_SESS_CONFIG 193This control message configures a single data session. 194The corresponding hook must already be connected before sending this command. 195The argument is a 196.Vt "struct ng_l2tp_sess_config" : 197.Bd -literal 198/* Configuration for a session hook */ 199struct ng_l2tp_sess_config { 200 u_int16_t session_id; /* local session id */ 201 u_int16_t peer_id; /* peer's session id */ 202 u_char control_dseq; /* we control data sequencing? */ 203 u_char enable_dseq; /* enable data sequencing? */ 204 u_char include_length; /* include length field? */ 205}; 206.Ed 207.Pp 208The 209.Va session_id 210and 211.Va peer_id 212fields configure the local and remote session IDs, respectively. 213.Pp 214The 215.Va control_dseq 216and 217.Va enable_dseq 218fields determine whether sequence numbers are used with L2TP data packets. 219If 220.Va enable_dseq 221is zero, then no sequence numbers are sent and incoming sequence numbers 222are ignored. 223Otherwise, sequence numbers are included on outgoing packets and checked 224on incoming packets. 225.Pp 226If 227.Va control_dseq 228is non-zero, then the setting of 229.Va enable_dseq 230will never change except by another 231.Dv NGM_L2TP_SET_SESS_CONFIG 232control message. 233If 234.Va control_dseq 235is zero, then the peer controls whether sequence numbers are used: 236if an incoming L2TP data packet contains sequence numbers, 237.Va enable_dseq 238is set to one, and conversely if an incoming L2TP data packet does not 239contain sequence numbers, 240.Va enable_dseq 241is set to zero. 242The current value of 243.Va enable_dseq 244is always accessible via the 245.Dv NGM_L2TP_GET_SESS_CONFIG 246control message (see below). 247Typically an LNS would set 248.Va control_dseq 249to one while a LAC would set 250.Va control_dseq 251to zero (if the Sequencing Required AVP were not sent), thus giving 252control of data packet sequencing to the LNS. 253.Pp 254The 255.Va include_length 256field determines whether the L2TP header length field is included 257in outgoing L2TP data packets. 258For incoming packets, the L2TP length field is always checked when present. 259.It Dv NGM_L2TP_GET_SESS_CONFIG 260This command takes a two byte session ID as an argument and returns 261the current configuration for the corresponding data session as a 262.Vt "struct ng_l2tp_sess_config" . 263The corresponding session hook must be connected. 264.It Dv NGM_L2TP_GET_STATS 265This command returns a 266.Vt "struct ng_l2tp_stats" 267containing statistics of the L2TP tunnel. 268.It Dv NGM_L2TP_CLR_STATS 269This command clears the statistics for the L2TP tunnel. 270.It Dv NGM_L2TP_GETCLR_STATS 271Same as 272.Dv NGM_L2TP_GET_STATS , 273but also atomically clears the statistics as well. 274.It Dv NGM_L2TP_GET_SESSION_STATS 275This command takes a two byte session ID as an argument and returns a 276.Vt "struct ng_l2tp_session_stats" 277containing statistics for the corresponding data session. 278The corresponding session hook must be connected. 279.It Dv NGM_L2TP_CLR_SESSION_STATS 280This command takes a two byte session ID as an argument and 281clears the statistics for that data session. 282The corresponding session hook must be connected. 283.It Dv NGM_L2TP_GETCLR_SESSION_STATS 284Same as 285.Dv NGM_L2TP_GET_SESSION_STATS , 286but also atomically clears the statistics as well. 287.It Dv NGM_L2TP_SET_SEQ 288This command sets the sequence numbers of a not yet enabled node. 289It takes a 290.Vt "struct ng_l2tp_seq_config" 291as argument, where 292.Va xack 293and 294.Va nr 295respectively 296.Va ns 297and 298.Va rack 299must be the same. 300This option is particularly useful if one receives and processes 301the first packet entirely in userspace and wants to hand over further 302processing to the node. 303.El 304.Sh SHUTDOWN 305This node shuts down upon receipt of a 306.Dv NGM_SHUTDOWN 307control message, or when all hooks have been disconnected. 308.Sh SEE ALSO 309.Xr netgraph 4 , 310.Xr ng_ksocket 4 , 311.Xr ng_ppp 4 , 312.Xr ng_pptpgre 4 , 313.Xr ngctl 8 314.Rs 315.%A W. Townsley 316.%A A. Valencia 317.%A A. Rubens 318.%A G. Pall 319.%A G. Zorn 320.%A B. Palter 321.%T "Layer Two Tunneling Protocol L2TP" 322.%O RFC 2661 323.Re 324.Sh HISTORY 325The 326.Nm l2tp 327node type was developed at Packet Design, LLC, 328.Pa http://www.packetdesign.com/ . 329.Sh AUTHORS 330.An Archie Cobbs Aq archie@packetdesign.com 331