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