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 April 22, 2002 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 netgraph/ng_l2tp.h 48.Sh DESCRIPTION 49The 50.Nm ng_l2tp 51node type implements the encapsulation layer of the L2TP protocol 52as described in RFC 2661. 53This includes adding the L2TP packet header for outgoing packets 54and verifying and removing it for incoming packets. 55The node maintains the L2TP sequence number state and handles 56control session packet acknowledgment and retransmission. 57.Sh HOOKS 58The 59.Nm ng_l2tp 60node type supports the following hooks: 61.Pp 62.Bl -tag -compact -offset 3n -width session_hhhh 63.It Dv lower 64L2TP frames 65.It Dv ctrl 66Control packets 67.It Dv session_hhhh 68Session 0xhhhh data packets 69.El 70.Pp 71L2TP control and data packets are transmitted to, and received from, 72the L2TP peer via the 73.Dv lower 74hook. 75Typically this hook would be connected to the 76.Dv "inet/dgram/udp" 77hook of an 78.Xr ng_ksocket 4 79node for L2TP over UDP. 80.Pp 81The 82.Dv ctrl 83hook connects to the local L2TP management entity. 84L2TP control messages (without any L2TP headers) are transmitted 85and received on this hook. 86Messages written to this hook are guaranteed to be delivered to the 87peer reliably, in order, and without duplicates. 88.Pp 89Packets written to the 90.Dv ctrl 91hook must contain a two byte session ID prepended to the frame 92(in network order). 93This session ID is copied to the outgoing L2TP header. 94Similarly, packets read from the 95.Dv ctrl 96hook will have the received session ID prepended. 97.Pp 98Once an L2TP session has been created, the corresponding session 99hook may be used to transmit and receive the session's data frames: 100for the session with session ID 101.Dv 0xabcd , 102the hook is named 103.Dv session_abcd . 104.Sh CONTROL MESSAGES 105This node type supports the generic control messages, plus the following: 106.Bl -tag -width xx 107.It Dv NGM_L2TP_SET_CONFIG 108This command updates the configuration of the node. 109It takes a 110.Li "struct ng_l2tp_config" 111as an argument: 112.Bd -literal -offset 0n 113/* Configuration for a node */ 114struct ng_l2tp_config { 115 u_char enabled; /* enables traffic flow */ 116 u_char match_id; /* tunnel id must match 'tunnel_id' */ 117 u_int16_t tunnel_id; /* local tunnel id */ 118 u_int16_t peer_id; /* peer's tunnel id */ 119 u_int16_t peer_win; /* peer's max recv window size */ 120 u_int16_t rexmit_max; /* max retransmits before failure */ 121 u_int16_t rexmit_max_to; /* max delay between retransmits */ 122}; 123.Ed 124.Pp 125The 126.Va enabled 127field enables packet processing. 128Each time this field is changed back to zero the sequence 129number state is reset. In this way, reuse of a node is possible. 130.Pp 131The 132.Va tunnel_id 133field configures the local tunnel ID for the control connection. 134The 135.Va match_id 136field determines how incoming L2TP packets with a tunnel ID 137field different from 138.Va tunnel_id 139are handled. 140If 141.Va match_id 142is non-zero, they will be dropped; otherwise, they will be dropped 143only if the tunnel ID is non-zero. 144Typically 145.Va tunnel_id 146is set to the local tunnel ID as soon as it is known and 147.Va match_id 148is set to non-zero after receipt of the SCCRP or SCCCN control message. 149.Pp 150The peer's tunnel ID should be set in 151.Va peer_id 152as soon as it is learned, typically after receipt of a SCCRQ or SCCRP 153control message. 154This value is copied into the L2TP header for outgoing packets. 155.Pp 156The 157.Va peer_win 158field should be set from the 159.Dq Receive Window Size 160AVP received from the peer. 161The default value for this field is one; zero is an invalid value. 162As long as 163.Va enabled 164is non-zero, this value may not be decreased. 165.Pp 166The 167.Va rexmit_max 168and 169.Va rexmit_max_to 170fields configure packet retransmission. 171.Va rexmit_max_to 172is the maximum retransmission delay between packets, in seconds. 173The retransmit delay will start at a small value and increase 174exponentially up to this limit. 175The 176.Va rexmit_max 177sets the maximum number of times a packet will be retransmitted 178without being acknowledged before a failure condition is declared. 179Once a failure condition is declared, each additional retransmission 180will cause the 181.Nm ng_l2tp 182node to send a 183.Dv NGM_L2TP_ACK_FAILURE 184control message back to the node that sent the last 185.Dv NGM_L2TP_SET_CONFIG . 186Appropriate action should then be taken to shutdown the control connection. 187.It Dv NGM_L2TP_GET_CONFIG 188Returns the current configuration as a 189.Dv "struct ng_l2tp_config" . 190.It Dv NGM_L2TP_SET_SESS_CONFIG 191This control message configures a single data session. 192The corresponding hook must already be connected before sending this command. 193The argument is a 194.Li "struct ng_l2tp_sess_config" : 195.Bd -literal -offset 0n 196/* Configuration for a session hook */ 197struct ng_l2tp_sess_config { 198 u_int16_t session_id; /* local session id */ 199 u_int16_t peer_id; /* peer's session id */ 200 u_char control_dseq; /* we control data sequencing? */ 201 u_char enable_dseq; /* enable data sequencing? */ 202 u_char include_length; /* include length field? */ 203}; 204.Ed 205.Pp 206The 207.Va session_id 208and 209.Va peer_id 210fields configure the local and remote session ID's, respectively. 211.Pp 212The 213.Va control_dseq 214and 215.Va enable_dseq 216fields determine whether sequence numbers are used with L2TP data packets. 217If 218.Va enable_dseq 219is zero, then no sequence numbers are sent and incoming sequence numbers 220are ignored. 221Otherwise, sequence numbers are included on outgoing packets and checked 222on incoming packets. 223.Pp 224If 225.Va control_dseq 226is non-zero, then the setting of 227.Va enable_dseq 228will never change except by another 229.Dv NGM_L2TP_SET_SESS_CONFIG 230control message. 231If 232.Va control_dseq 233is zero, then the peer controls whether sequence numbers are used: 234if an incoming L2TP data packet contains sequence numbers, 235.Va enable_dseq 236is set to one, and conversely if an incoming L2TP data packet does not 237contain sequence numbers, 238.Va enable_dseq 239is set to zero. 240The current value of 241.Va enable_dseq 242is always accessible via the 243.Dv NGM_L2TP_GET_SESS_CONFIG 244control message (see below). 245Typically an LNS would set 246.Va control_dseq 247to one while a LAC would set 248.Va control_dseq 249to zero (if the Sequencing Required AVP were not sent), thus giving 250control of data packet sequencing to the LNS. 251.Pp 252The 253.Va include_length 254field determines whether the L2TP header length field is included 255in outgoing L2TP data packets. 256For incoming packets, the L2TP length field is always checked when present. 257.It Dv NGM_L2TP_GET_SESS_CONFIG 258This command takes a two byte session ID as an argument and returns 259the current configuration for the corresponding data session as a 260.Dv "struct ng_l2tp_sess_config" . 261The corresponding session hook must be connected. 262.It Dv NGM_L2TP_GET_STATS 263This command takes a two byte session ID as an argument and returns a 264.Dv "struct ng_l2tp_stats" 265containing statistics for the corresponding data session. 266The corresponding session hook must be connected. 267.It Dv NGM_L2TP_CLR_STATS 268This command takes a two byte session ID as an argument and 269clears the statistics for that data session. 270The corresponding session hook must be connected. 271.It Dv NGM_L2TP_GETCLR_STATS 272Same as 273.Dv NGM_L2TP_GET_STATS , 274but also atomically clears the statistics as well. 275.El 276.Pp 277.Sh SHUTDOWN 278This node shuts down upon receipt of a 279.Dv NGM_SHUTDOWN 280control message, or when all hooks have been disconnected. 281.Sh SEE ALSO 282.Xr netgraph 4 , 283.Xr ng_ksocket 4 , 284.Xr ng_ppp 4 , 285.Xr ng_pptp 4 , 286.Xr ngctl 8 287.Rs 288.%A W. Townsley 289.%A A. Valencia 290.%A A. Rubens 291.%A G. Pall 292.%A G. Zorn 293.%A B. Palter 294.%T "Layer Two Tunneling Protocol L2TP" 295.%O RFC 2661 296.Re 297.Sh HISTORY 298The 299.Nm 300node type was developed at Packet Design, LLC. 301.Dv "http://www.packetdesign.com/" 302.Sh AUTHORS 303.An Archie Cobbs Aq archie@packetdesign.com 304