1.\" Copyright (c) 1996-1999 Whistle Communications, Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Whistle Communications; 7.\" provided, however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Whistle 11.\" Communications, Inc. trademarks, including the mark "WHISTLE 12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as 13.\" such appears in the above copyright notice or in the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.\" Author: Archie Cobbs <archie@FreeBSD.org> 34.\" 35.\" $FreeBSD: src/share/man/man4/ng_ppp.4,v 1.18.2.1 2001/12/21 09:00:51 ru Exp $ 36.\" $DragonFly: src/share/man/man4/ng_ppp.4,v 1.2 2003/06/17 04:36:59 dillon Exp $ 37.\" $Whistle: ng_ppp.8,v 1.3 1999/01/25 23:46:27 archie Exp $ 38.\" 39.Dd January 19, 1999 40.Dt NG_PPP 4 41.Os 42.Sh NAME 43.Nm ng_ppp 44.Nd PPP protocol netgraph node type 45.Sh SYNOPSIS 46.In netgraph/ng_ppp.h 47.Sh DESCRIPTION 48The 49.Nm ppp 50node type performs multiplexing for the PPP protocol. It handles 51only packets that contain data, and forwards protocol negotiation 52and control packets to a separate controlling entity (e.g., a 53user-land daemon). This approach combines the fast dispatch of 54kernel implementations with the configuration flexibility of a 55user-land implementations. The PPP node type directly supports 56multi-link PPP, Van Jacobson compression, PPP compression, PPP 57encryption, and the IP, IPX, and AppleTalk protocols. A single 58PPP node corresponds to one PPP multi-link bundle. 59.Pp 60There is a separate hook for each PPP link in the bundle, plus 61several hooks corresponding to the directly supported protocols. 62For compression and encryption, separate attached nodes are required 63to do the actual work. The node type used will of course depend 64on the algorithm negotiated. There is also a 65.Dv bypass 66hook which is used to handle any protocol not directly supported 67by the node. This includes all of the control protocols: LCP, IPCP, 68CCP, etc. Typically this node is connected to a user-land daemon 69via a 70.Xr ng_socket 4 71type node. 72.Sh ENABLING FUNCTIONALITY 73In general, the PPP node enables a specific link or functionality when 74(a) a 75.Dv NGM_PPP_SET_CONFIG 76message has been received which enables it, and 77(b) the corresponding hook(s) are connected. 78This allows the controlling entity to use either method (a) or (b) 79(or both) to control the node's behavior. 80When a link is connected but disabled, traffic can still flow on 81the link via the 82.Dv bypass 83hook (see below). 84.Sh LINK HOOKS 85During normal operation, the individual PPP links are connected to hooks 86.Dv link0 , 87.Dv link1 , 88etc. Up to 89.Dv NG_PPP_MAX_LINKS 90links are supported. 91These device-independent hooks transmit and receive full PPP 92frames, which include the PPP protocol, address, control, and 93information fields, but no checksum or other link-specific fields. 94.Pp 95On outgoing frames, when protocol compression 96has been enabled and the protocol number is suitable for compression, 97the protocol field will be compressed (i.e., sent as one byte 98instead of two). Either compressed or uncompressed protocol fields 99are accepted on incoming frames. Similarly, if address and control 100field compression has been enabled for the link, the address and 101control fields will be omitted (except for LCP frames as required 102by the standards). Incoming frames have the address and control fields 103stripped automatically if present. 104.Pp 105Since all negotiation is handled outside the PPP node, the links 106should not be connected and enabled until the corresponding link 107has reached the network phase (i.e., LCP negotiation and authentication 108have completed successfully) and the PPP node has been informed of 109the link parameters via the 110.Dv NGM_PPP_LINK_CONFIG 111message. 112.Pp 113When a link is connected but disabled, all received frames are forwarded 114directly out the 115.Dv bypass 116hook, and conversely, frames may be transmitted via the 117.Dv bypass 118hook as well. This mode is appropriate for the link authentication phase. 119As soon as the link is enabled, the PPP node will 120begin processing frames received on the link. 121.Sh COMPRESSION AND ENCRYPTION 122Compression is supported via two hooks, 123.Dv compress 124and 125.Dv decompress . 126When enabled and connected, the PPP node writes outgoing frames on the 127.Dv comp 128hook and expects to receive back the compressed frame on the same hook. 129Similarly, the 130.Dv decompress 131hook is used to uncompress incoming frames when decompression is 132negotiated (compression and decompression are independently negotiable). 133The type of node attached to these hooks should correspond 134to the type of compression negotiated, e.g., Deflate, Predictor-1, etc. 135.Pp 136Encryption works exactly analogously via the 137.Dv encrypt 138and 139.Dv decrypt 140nodes. Data is always compressed before being encrypted, 141and decrypted before being decompressed. 142.Pp 143Only bundle-level compression and encryption is directly supported; 144link-level compression and encryption can be handled transparently 145by downstream nodes. 146.Sh VAN JACOBSON COMPRESSION 147When all of the 148.Dv vjc_ip , 149.Dv vjc_vjcomp , 150.Dv vjc_vjuncomp , 151and 152.Dv vjc_vjip 153hooks are connected, and the corresponding configuration flag is 154enabled, Van Jacobson compression and/or decompression will become active. 155Normally these hooks connect to the corresponding hooks of a single 156.Xr ng_vjc 4 157node. The PPP node is compatible with the 158.Dq pass through 159modes of the 160.Xr ng_vjc 4 161node type. 162.Sh BYPASS HOOK 163When a frame is received on a link with an unsupported protocol, 164or a protocol which is disabled or for which the corresponding hook 165is unconnected, the PPP node forwards the frame out the 166.Dv bypass 167hook, prepended with a four byte prefix. This first two bytes of 168the prefix indicate the link number on which the frame was received 169(in network order). 170For such frames received over the bundle (i.e., encapsulated in the 171multi-link protocol), the special link number 172.Dv NG_PPP_BUNDLE_LINKNUM 173is used. After the two byte link number is the two byte PPP protocol number 174(also in network order). 175The PPP protocol number is two bytes long even if the original frame 176was protocol compressed. 177.Pp 178Conversely, any data written to the 179.Dv bypass 180hook is assumed to be in this same format. The four byte header is 181stripped off, the PPP protocol number is prepended (possibly compressed), 182and the frame is delivered over the desired link. 183If the link number is 184.Dv NG_PPP_BUNDLE_LINKNUM 185the frame will be delivered over the multi-link bundle; or, if multi-link 186is disabled, over the (single) PPP link. 187.Pp 188Typically when the controlling entity receives an unexpected packet on the 189.Dv bypass 190hook it responds either by dropping the frame (if it's not ready for 191the protocol) or with an LCP protocol reject (if it doesn't recognize 192or expect the protocol). 193.Sh MULTILINK OPERATION 194To enable multi-link PPP, the corresponding configuration flag must be set 195and at least one link connected. The PPP node will not allow more than 196one link to be connected if multi-link is not enabled, nor will it allow 197certain multi-link settings to be changed while multi-link operation is 198active (e.g., short sequence number header format). 199.Pp 200Because packets are sent as fragments across multiple individual links, 201it is important that when a link goes down the PPP node is notified 202immediately, either by disconnecting the corresponding hook or disabling 203the link via the 204.Dv NGM_PPP_SET_CONFIG 205control message. 206.Pp 207Each link has configuration parameters for latency (specified in 208milliseconds) and bandwidth (specified in tens of bytes per second). 209The PPP node can be configured for 210.Em round-robin 211or 212.Em optimized 213packet delivery. 214.Pp 215When configured for round-robin delivery, the latency and bandwidth 216values are ignored and the PPP node simply sends each frame as a 217single fragment, alternating frames across all the links in the 218bundle. This scheme has the advantage that even if one link fails 219silently, some packets will still get through. It has the disadvantage 220of sub-optimal overall bundle latency, which is important for 221interactive response time, and sub-optimal overall bundle bandwidth 222when links with different bandwidths exist in the same bundle. 223.Pp 224When configured for optimal delivery, the PPP node distributes the 225packet across the links in a way that minimizes the time it takes 226for the completed packet to be received by the far end. This 227involves taking into account each link's latency, bandwidth, and 228current queue length. Therefore these numbers should be 229configured as accurately as possible. The algorithm does require 230some computation, so may not be appropriate for very slow machines 231and/or very fast links. 232.Pp 233As a special case, if all links have identical latency and bandwidth, 234then the above algorithm is disabled (because it is unnecessary) 235and the PPP node simply fragments frames into equal sized portions 236across all of the links. 237.Sh HOOKS 238This node type supports the following hooks: 239.Pp 240.Bl -tag -compact -width vjc_vjuncomp 241.It Dv link<N> 242Individual PPP link number 243.Dv <N> 244.It Dv compress 245Connection to compression engine 246.It Dv decompress 247Connection to decompression engine 248.It Dv encrypt 249Connection to encryption engine 250.It Dv decrypt 251Connection to decryption engine 252.It Dv vjc_ip 253Connection to 254.Xr ng_vjc 4 255.Dv ip 256hook 257.It Dv vjc_vjcomp 258Connection to 259.Xr ng_vjc 4 260.Dv vjcomp 261hook 262.It Dv vjc_vjuncomp 263Connection to 264.Xr ng_vjc 4 265.Dv vjuncomp 266hook 267.It Dv vjc_vjip 268Connection to 269.Xr ng_vjc 4 270.Dv vjip 271hook 272.It Dv inet 273IP packet data 274.It Dv atalk 275AppleTalk packet data 276.It Dv ipx 277IPX packet data 278.It Dv bypass 279Bypass hook; frames have a four byte header consisting of 280a link number and a PPP protocol number. 281.El 282.Sh CONTROL MESSAGES 283This node type supports the generic control messages, plus the following: 284.Bl -tag -width foo 285.It Dv NGM_PPP_SET_CONFIG 286This command configures all aspects of the node. This includes enabling 287multi-link PPP, encryption, compression, Van Jacobson compression, and IP, 288AppleTalk, and IPX packet delivery. It includes per-link configuration, 289including enabling the link, setting latency and bandwidth parameters, 290and enabling protocol field compression. Note that no link or functionality 291is active until the corresponding hook is also connected. 292This command takes a 293.Dv "struct ng_ppp_node_config" 294as an argument: 295.Bd -literal -offset 0n 296/* Per-link config structure */ 297struct ng_ppp_link_config { 298 u_char enableLink; /* enable this link */ 299 u_char enableProtoComp;/* enable protocol field compression */ 300 u_char enableACFComp; /* enable addr/ctrl field compression */ 301 u_int16_t mru; /* peer MRU */ 302 u_int32_t latency; /* link latency (in milliseconds) */ 303 u_int32_t bandwidth; /* link bandwidth (in bytes/second) */ 304}; 305 306/* Node config structure */ 307struct ng_ppp_node_config { 308 u_int16_t mrru; /* multilink peer MRRU */ 309 u_char enableMultilink; /* enable multilink */ 310 u_char recvShortSeq; /* recv multilink short seq # */ 311 u_char xmitShortSeq; /* xmit multilink short seq # */ 312 u_char enableRoundRobin; /* xmit whole packets */ 313 u_char enableIP; /* enable IP data flow */ 314 u_char enableAtalk; /* enable AppleTalk data flow */ 315 u_char enableIPX; /* enable IPX data flow */ 316 u_char enableCompression; /* enable PPP compression */ 317 u_char enableDecompression; /* enable PPP decompression */ 318 u_char enableEncryption; /* enable PPP encryption */ 319 u_char enableDecryption; /* enable PPP decryption */ 320 u_char enableVJCompression; /* enable VJ compression */ 321 u_char enableVJDecompression; /* enable VJ decompression */ 322 struct ng_ppp_link_config /* per link config params */ 323 links[NG_PPP_MAX_LINKS]; 324}; 325.Ed 326.Pp 327.It Dv NGM_PPP_GET_CONFIG 328Returns the current configuration as a 329.Dv "struct ng_ppp_node_config" . 330.It Dv NGM_PPP_GET_LINK_STATS 331This command takes a two byte link number as an argument and returns a 332.Dv "struct ng_ppp_link_stat" 333containing statistics for the corresponding link. Here 334.Dv NG_PPP_BUNDLE_LINKNUM 335is a valid link number corresponding to the multi-link bundle. 336.It Dv NGM_PPP_CLR_LINK_STATS 337This command takes a two byte link number as an argument and 338clears the statistics for that link. 339.It Dv NGM_PPP_GETCLR_LINK_STATS 340Same as 341.Dv NGM_PPP_GET_LINK_STATS , 342but also atomically clears the statistics as well. 343.El 344.Pp 345This node type also accepts the control messages accepted by the 346.Xr ng_vjc 4 347node type. When received, these messages are simply forwarded to 348the adjacent 349.Xr ng_vjc 4 350node, if any. This is particularly useful when the individual 351PPP links are able to generate 352.Dv NGM_VJC_RECV_ERROR 353messages (see 354.Xr ng_vjc 4 355for a description). 356.Sh SHUTDOWN 357This node shuts down upon receipt of a 358.Dv NGM_SHUTDOWN 359control message, or when all hooks have been disconnected. 360.Sh SEE ALSO 361.Xr netgraph 4 , 362.Xr ng_async 4 , 363.Xr ng_iface 4 , 364.Xr ng_mppc 4 , 365.Xr ng_pppoe 4 , 366.Xr ng_vjc 4 , 367.Xr ngctl 8 368.Rs 369.%A W. Simpson 370.%T "The Point-to-Point Protocol (PPP)" 371.%O RFC 1661 372.Re 373.Rs 374.%A K. Sklower 375.%A B. Lloyd 376.%A G. McGregor 377.%A D. Carr 378.%A T. Coradetti 379.%T "The PPP Multilink Protocol (MP)" 380.%O RFC 1990 381.Re 382.Sh HISTORY 383The 384.Nm 385node type was implemented in 386.Fx 4.0 . 387.Sh AUTHORS 388.An Archie Cobbs Aq archie@FreeBSD.org 389