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