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 December 28, 2006 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 . 135Compression and decompression can be enabled by toggling the 136.Vt enableCompression 137and 138.Vt enableDecompression 139fields of the node configuration structure. 140(See below.) 141If 142.Vt enableCompression 143is set to 144.Dv NG_PPP_COMPRESS_SIMPLE , 145then all outgoing frames are sent to the 146.Dv compress 147hook and all packets received on this hook are expected to be 148compressed, so the COMPD tag is put on them unconditionally. 149If 150.Vt enableCompression 151is set to 152.Dv NG_PPP_COMPRESS_FULL , 153then packets received on the 154.Dv compress 155hook are resent as is. 156The compressor node should put the tag, if the packet was compressed. 157If 158.Vt enableDecompression 159is set to 160.Dv NG_PPP_DECOMPRESS_SIMPLE , 161then the node will sent to the 162.Dv decompress 163hook only those frames, that are marked with the COMPD tag. 164If 165.Vt enableDecompression 166is set to 167.Dv NG_PPP_DECOMPRESS_FULL , 168then the node will sent all incoming packets to the 169.Dv decompress 170hook. 171Compression and decompression can be completely disabled by setting the 172.Vt enableCompression 173and 174.Vt enableDecompression 175fields to the 176.Dv NG_PPP_COMPRESS_NONE 177and 178.Dv NG_PPP_DECOMPRESS_NONE , 179respectively. 180.Pp 181Encryption works exactly analogously via the 182.Dv encrypt 183and 184.Dv decrypt 185nodes. 186Data is always compressed before being encrypted, 187and decrypted before being decompressed. 188.Pp 189Only bundle-level compression and encryption is directly supported; 190link-level compression and encryption can be handled transparently 191by downstream nodes. 192.Sh VAN JACOBSON COMPRESSION 193When all of the 194.Dv vjc_ip , 195.Dv vjc_vjcomp , 196.Dv vjc_vjuncomp , 197and 198.Dv vjc_vjip 199hooks are connected, and the corresponding configuration flag is 200enabled, Van Jacobson compression and/or decompression will become active. 201Normally these hooks connect to the corresponding hooks of a single 202.Xr ng_vjc 4 203node. 204The PPP node is compatible with the 205.Dq pass through 206modes of the 207.Xr ng_vjc 4 208node type. 209.Sh BYPASS HOOK 210When a frame is received on a link with an unsupported protocol, 211or a protocol which is disabled or for which the corresponding hook 212is unconnected, the PPP node forwards the frame out the 213.Dv bypass 214hook, prepended with a four byte prefix. 215This first two bytes of 216the prefix indicate the link number on which the frame was received 217(in network order). 218For such frames received over the bundle (i.e., encapsulated in the 219multi-link protocol), the special link number 220.Dv NG_PPP_BUNDLE_LINKNUM 221is used. 222After the two byte link number is the two byte PPP protocol number 223(also in network order). 224The PPP protocol number is two bytes long even if the original frame 225was protocol compressed. 226.Pp 227Conversely, any data written to the 228.Dv bypass 229hook is assumed to be in this same format. 230The four byte header is 231stripped off, the PPP protocol number is prepended (possibly compressed), 232and the frame is delivered over the desired link. 233If the link number is 234.Dv NG_PPP_BUNDLE_LINKNUM 235the frame will be delivered over the multi-link bundle; or, if multi-link 236is disabled, over the (single) PPP link. 237.Pp 238Typically when the controlling entity receives an unexpected packet on the 239.Dv bypass 240hook it responds either by dropping the frame (if it is not ready for 241the protocol) or with an LCP protocol reject (if it does not recognize 242or expect the protocol). 243.Sh MULTILINK OPERATION 244To enable multi-link PPP, the corresponding configuration flag must be set 245and at least one link connected. 246The PPP node will not allow more than 247one link to be connected if multi-link is not enabled, nor will it allow 248certain multi-link settings to be changed while multi-link operation is 249active (e.g., short sequence number header format). 250.Pp 251Since packets are sent as fragments across multiple individual links, 252it is important that when a link goes down the PPP node is notified 253immediately, either by disconnecting the corresponding hook or disabling 254the link via the 255.Dv NGM_PPP_SET_CONFIG 256control message. 257.Pp 258Each link has configuration parameters for latency (specified in 259milliseconds) and bandwidth (specified in tens of bytes per second). 260The PPP node can be configured for 261.Em round-robin 262or 263.Em optimized 264packet delivery. 265.Pp 266When configured for round-robin delivery, the latency and bandwidth 267values are ignored and the PPP node simply sends each frame as a 268single fragment, alternating frames across all the links in the 269bundle. 270This scheme has the advantage that even if one link fails 271silently, some packets will still get through. 272It has the disadvantage 273of sub-optimal overall bundle latency, which is important for 274interactive response time, and sub-optimal overall bundle bandwidth 275when links with different bandwidths exist in the same bundle. 276.Pp 277When configured for optimal delivery, the PPP node distributes the 278packet across the links in a way that minimizes the time it takes 279for the completed packet to be received by the far end. 280This involves taking into account each link's latency, bandwidth, and 281current queue length. 282Therefore these numbers should be configured as accurately as possible. 283The algorithm does require 284some computation, so may not be appropriate for very slow machines 285and/or very fast links. 286.Pp 287As a special case, if all links have identical latency and bandwidth, 288then the above algorithm is disabled (because it is unnecessary) 289and the PPP node simply fragments frames into equal sized portions 290across all of the links. 291.Sh HOOKS 292This node type supports the following hooks: 293.Pp 294.Bl -tag -compact -width vjc_vjuncomp 295.It Dv link<N> 296Individual PPP link number 297.Dv <N> 298.It Dv compress 299Connection to compression engine 300.It Dv decompress 301Connection to decompression engine 302.It Dv encrypt 303Connection to encryption engine 304.It Dv decrypt 305Connection to decryption engine 306.It Dv vjc_ip 307Connection to 308.Xr ng_vjc 4 309.Dv ip 310hook 311.It Dv vjc_vjcomp 312Connection to 313.Xr ng_vjc 4 314.Dv vjcomp 315hook 316.It Dv vjc_vjuncomp 317Connection to 318.Xr ng_vjc 4 319.Dv vjuncomp 320hook 321.It Dv vjc_vjip 322Connection to 323.Xr ng_vjc 4 324.Dv vjip 325hook 326.It Dv inet 327IP packet data 328.It Dv atalk 329AppleTalk packet data 330.It Dv ipx 331IPX packet data 332.It Dv bypass 333Bypass hook; frames have a four byte header consisting of 334a link number and a PPP protocol number. 335.El 336.Sh CONTROL MESSAGES 337This node type supports the generic control messages, plus the following: 338.Bl -tag -width foo 339.It Dv NGM_PPP_SET_CONFIG 340This command configures all aspects of the node. 341This includes enabling 342multi-link PPP, encryption, compression, Van Jacobson compression, and IP, 343IPv6, AppleTalk, and IPX packet delivery. 344It includes per-link configuration, 345including enabling the link, setting latency and bandwidth parameters, 346and enabling protocol field compression. 347Note that no link or functionality 348is active until the corresponding hook is also connected. 349This command takes a 350.Dv "struct ng_ppp_node_conf" 351as an argument: 352.Bd -literal -offset 0n 353/* Per-link config structure */ 354struct ng_ppp_link_conf { 355 u_char enableLink; /* enable this link */ 356 u_char enableProtoComp;/* enable protocol field compression */ 357 u_char enableACFComp; /* enable addr/ctrl field compression */ 358 u_int16_t mru; /* peer MRU */ 359 u_int32_t latency; /* link latency (in milliseconds) */ 360 u_int32_t bandwidth; /* link bandwidth (in bytes/second) */ 361}; 362 363/* Bundle config structure */ 364struct ng_ppp_bund_conf { 365 u_int16_t mrru; /* multilink peer MRRU */ 366 u_char enableMultilink; /* enable multilink */ 367 u_char recvShortSeq; /* recv multilink short seq # */ 368 u_char xmitShortSeq; /* xmit multilink short seq # */ 369 u_char enableRoundRobin; /* xmit whole packets */ 370 u_char enableIP; /* enable IP data flow */ 371 u_char enableIPv6; /* enable IPv6 data flow */ 372 u_char enableAtalk; /* enable AppleTalk data flow */ 373 u_char enableIPX; /* enable IPX data flow */ 374 u_char enableCompression; /* enable PPP compression */ 375 u_char enableDecompression; /* enable PPP decompression */ 376 u_char enableEncryption; /* enable PPP encryption */ 377 u_char enableDecryption; /* enable PPP decryption */ 378 u_char enableVJCompression; /* enable VJ compression */ 379 u_char enableVJDecompression; /* enable VJ decompression */ 380}; 381 382struct ng_ppp_node_conf { 383 struct ng_ppp_bund_conf bund; 384 struct ng_ppp_link_conf links[NG_PPP_MAX_LINKS]; 385}; 386.Ed 387.Pp 388.It Dv NGM_PPP_GET_CONFIG 389Returns the current configuration as a 390.Dv "struct ng_ppp_node_conf" . 391.It Dv NGM_PPP_GET_LINK_STATS 392This command takes a two byte link number as an argument and returns a 393.Dv "struct ng_ppp_link_stat" 394containing statistics for the corresponding link. 395Here 396.Dv NG_PPP_BUNDLE_LINKNUM 397is a valid link number corresponding to the multi-link bundle. 398.It Dv NGM_PPP_GET_LINK_STATS64 399Same as NGM_PPP_GET_LINK_STATS but returns 400.Dv "struct ng_ppp_link_stat64" 401containing 64bit counters. 402.It Dv NGM_PPP_CLR_LINK_STATS 403This command takes a two byte link number as an argument and 404clears the statistics for that link. 405.It Dv NGM_PPP_GETCLR_LINK_STATS 406Same as 407.Dv NGM_PPP_GET_LINK_STATS , 408but also atomically clears the statistics as well. 409.It Dv NGM_PPP_GETCLR_LINK_STATS64 410Same as NGM_PPP_GETCLR_LINK_STATS but returns 411.Dv "struct ng_ppp_link_stat64" 412containing 64bit counters. 413.El 414.Pp 415This node type also accepts the control messages accepted by the 416.Xr ng_vjc 4 417node type. 418When received, these messages are simply forwarded to 419the adjacent 420.Xr ng_vjc 4 421node, if any. 422This is particularly useful when the individual 423PPP links are able to generate 424.Dv NGM_VJC_RECV_ERROR 425messages (see 426.Xr ng_vjc 4 427for a description). 428.Sh SHUTDOWN 429This node shuts down upon receipt of a 430.Dv NGM_SHUTDOWN 431control message, or when all hooks have been disconnected. 432.Sh SEE ALSO 433.Xr netgraph 4 , 434.Xr ng_async 4 , 435.Xr ng_iface 4 , 436.Xr ng_mppc 4 , 437.Xr ng_pppoe 4 , 438.Xr ng_vjc 4 , 439.Xr ngctl 8 440.Rs 441.%A W. Simpson 442.%T "The Point-to-Point Protocol (PPP)" 443.%O RFC 1661 444.Re 445.Rs 446.%A K. Sklower 447.%A B. Lloyd 448.%A G. McGregor 449.%A D. Carr 450.%A T. Coradetti 451.%T "The PPP Multilink Protocol (MP)" 452.%O RFC 1990 453.Re 454.Sh HISTORY 455The 456.Nm 457node type was implemented in 458.Fx 4.0 . 459.Sh AUTHORS 460.An Archie Cobbs Aq archie@FreeBSD.org 461