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