share/man/man4/ng_ppp.4

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