1 .\" Copyright (c) 1996-1999 Whistle Communications, Inc.
2 .\" All rights reserved.
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.
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
33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
35 .\" $FreeBSD: src/share/man/man4/ng_ppp.4,v 1.18.2.1 2001/12/21 09:00:51 ru Exp $
36 .\" $Whistle: ng_ppp.8,v 1.3 1999/01/25 23:46:27 archie Exp $
43 .Nd PPP protocol netgraph node type
45 .In netgraph/ppp/ng_ppp.h
49 node type performs multiplexing for the PPP protocol. It handles
50 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). This approach combines the fast dispatch of
53 kernel implementations with the configuration flexibility of a
54 user-land implementations. The PPP node type directly supports
55 multi-link PPP, Van Jacobson compression, PPP compression, PPP
56 encryption, and the IP, IPX, and AppleTalk protocols. A single
57 PPP node corresponds to one PPP multi-link bundle.
59 There is a separate hook for each PPP link in the bundle, plus
60 several hooks corresponding to the directly supported protocols.
61 For compression and encryption, separate attached nodes are required
62 to do the actual work. The node type used will of course depend
63 on the algorithm negotiated. There is also a
65 hook which is used to handle any protocol not directly supported
66 by the node. This includes all of the control protocols: LCP, IPCP,
67 CCP, etc. Typically this node is connected to a user-land daemon
71 .Sh ENABLING FUNCTIONALITY
72 In general, the PPP node enables a specific link or functionality when
74 .Dv NGM_PPP_SET_CONFIG
75 message has been received which enables it, and
76 (b) the corresponding hook(s) are connected.
77 This allows the controlling entity to use either method (a) or (b)
78 (or both) to control the node's behavior.
79 When a link is connected but disabled, traffic can still flow on
84 During normal operation, the individual PPP links are connected to hooks
90 These device-independent hooks transmit and receive full PPP
91 frames, which include the PPP protocol, address, control, and
92 information fields, but no checksum or other link-specific fields.
94 On outgoing frames, when protocol compression
95 has been enabled and the protocol number is suitable for compression,
96 the protocol field will be compressed (i.e., sent as one byte
97 instead of two). Either compressed or uncompressed protocol fields
98 are accepted on incoming frames. Similarly, if address and control
99 field compression has been enabled for the link, the address and
100 control fields will be omitted (except for LCP frames as required
101 by the standards). Incoming frames have the address and control fields
102 stripped automatically if present.
104 Since all negotiation is handled outside the PPP node, the links
105 should not be connected and enabled until the corresponding link
106 has reached the network phase (i.e., LCP negotiation and authentication
107 have completed successfully) and the PPP node has been informed of
108 the link parameters via the
109 .Dv NGM_PPP_LINK_CONFIG
112 When a link is connected but disabled, all received frames are forwarded
115 hook, and conversely, frames may be transmitted via the
117 hook as well. This mode is appropriate for the link authentication phase.
118 As soon as the link is enabled, the PPP node will
119 begin processing frames received on the link.
120 .Sh COMPRESSION AND ENCRYPTION
121 Compression is supported via two hooks,
125 When enabled and connected, the PPP node writes outgoing frames on the
127 hook and expects to receive back the compressed frame on the same hook.
130 hook is used to uncompress incoming frames when decompression is
131 negotiated (compression and decompression are independently negotiable).
132 The type of node attached to these hooks should correspond
133 to the type of compression negotiated, e.g., Deflate, Predictor-1, etc.
135 Encryption works exactly analogously via the
139 nodes. Data is always compressed before being encrypted,
140 and decrypted before being decompressed.
142 Only bundle-level compression and encryption is directly supported;
143 link-level compression and encryption can be handled transparently
145 .Sh VAN JACOBSON COMPRESSION
152 hooks are connected, and the corresponding configuration flag is
153 enabled, Van Jacobson compression and/or decompression will become active.
154 Normally these hooks connect to the corresponding hooks of a single
156 node. The PPP node is compatible with the
162 When a frame is received on a link with an unsupported protocol,
163 or a protocol which is disabled or for which the corresponding hook
164 is unconnected, the PPP node forwards the frame out the
166 hook, prepended with a four byte prefix. This first two bytes of
167 the prefix indicate the link number on which the frame was received
169 For such frames received over the bundle (i.e., encapsulated in the
170 multi-link protocol), the special link number
171 .Dv NG_PPP_BUNDLE_LINKNUM
172 is used. After the two byte link number is the two byte PPP protocol number
173 (also in network order).
174 The PPP protocol number is two bytes long even if the original frame
175 was protocol compressed.
177 Conversely, any data written to the
179 hook is assumed to be in this same format. The four byte header is
180 stripped off, the PPP protocol number is prepended (possibly compressed),
181 and the frame is delivered over the desired link.
182 If the link number is
183 .Dv NG_PPP_BUNDLE_LINKNUM
184 the frame will be delivered over the multi-link bundle; or, if multi-link
185 is disabled, over the (single) PPP link.
187 Typically when the controlling entity receives an unexpected packet on the
189 hook it responds either by dropping the frame (if it's not ready for
190 the protocol) or with an LCP protocol reject (if it doesn't recognize
191 or expect the protocol).
192 .Sh MULTILINK OPERATION
193 To enable multi-link PPP, the corresponding configuration flag must be set
194 and at least one link connected. The PPP node will not allow more than
195 one link to be connected if multi-link is not enabled, nor will it allow
196 certain multi-link settings to be changed while multi-link operation is
197 active (e.g., short sequence number header format).
199 Because packets are sent as fragments across multiple individual links,
200 it is important that when a link goes down the PPP node is notified
201 immediately, either by disconnecting the corresponding hook or disabling
203 .Dv NGM_PPP_SET_CONFIG
206 Each link has configuration parameters for latency (specified in
207 milliseconds) and bandwidth (specified in tens of bytes per second).
208 The PPP node can be configured for
214 When configured for round-robin delivery, the latency and bandwidth
215 values are ignored and the PPP node simply sends each frame as a
216 single fragment, alternating frames across all the links in the
217 bundle. This scheme has the advantage that even if one link fails
218 silently, some packets will still get through. It has the disadvantage
219 of sub-optimal overall bundle latency, which is important for
220 interactive response time, and sub-optimal overall bundle bandwidth
221 when links with different bandwidths exist in the same bundle.
223 When configured for optimal delivery, the PPP node distributes the
224 packet across the links in a way that minimizes the time it takes
225 for the completed packet to be received by the far end. This
226 involves taking into account each link's latency, bandwidth, and
227 current queue length. Therefore these numbers should be
228 configured as accurately as possible. The algorithm does require
229 some computation, so may not be appropriate for very slow machines
230 and/or very fast links.
232 As a special case, if all links have identical latency and bandwidth,
233 then the above algorithm is disabled (because it is unnecessary)
234 and the PPP node simply fragments frames into equal sized portions
235 across all of the links.
237 This node type supports the following hooks:
239 .Bl -tag -compact -width vjc_vjuncomp
241 Individual PPP link number
244 Connection to compression engine
246 Connection to decompression engine
248 Connection to encryption engine
250 Connection to decryption engine
274 AppleTalk packet data
278 Bypass hook; frames have a four byte header consisting of
279 a link number and a PPP protocol number.
282 This node type supports the generic control messages, plus the following:
284 .It Dv NGM_PPP_SET_CONFIG
285 This command configures all aspects of the node. This includes enabling
286 multi-link PPP, encryption, compression, Van Jacobson compression, and IP,
287 AppleTalk, and IPX packet delivery. It includes per-link configuration,
288 including enabling the link, setting latency and bandwidth parameters,
289 and enabling protocol field compression. Note that no link or functionality
290 is active until the corresponding hook is also connected.
292 .Dv "struct ng_ppp_node_config"
294 .Bd -literal -offset 0n
295 /* Per-link config structure */
296 struct 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) */
305 /* Node config structure */
306 struct 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];
325 .It Dv NGM_PPP_GET_CONFIG
326 Returns the current configuration as a
327 .Dv "struct ng_ppp_node_config" .
328 .It Dv NGM_PPP_GET_LINK_STATS
329 This command takes a two byte link number as an argument and returns a
330 .Dv "struct ng_ppp_link_stat"
331 containing statistics for the corresponding link. Here
332 .Dv NG_PPP_BUNDLE_LINKNUM
333 is a valid link number corresponding to the multi-link bundle.
334 .It Dv NGM_PPP_CLR_LINK_STATS
335 This command takes a two byte link number as an argument and
336 clears the statistics for that link.
337 .It Dv NGM_PPP_GETCLR_LINK_STATS
339 .Dv NGM_PPP_GET_LINK_STATS ,
340 but also atomically clears the statistics as well.
343 This node type also accepts the control messages accepted by the
345 node type. When received, these messages are simply forwarded to
348 node, if any. This is particularly useful when the individual
349 PPP links are able to generate
350 .Dv NGM_VJC_RECV_ERROR
355 This node shuts down upon receipt of a
357 control message, or when all hooks have been disconnected.
368 .%T "The Point-to-Point Protocol (PPP)"
377 .%T "The PPP Multilink Protocol (MP)"
383 node type was implemented in
386 .An Archie Cobbs Aq Mt archie@FreeBSD.org