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