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