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