ng_ppp(4)

NAME

ng_ppp - PPP protocol netgraph node type

SYNOPSIS

#include <sys/types.h>
#include <netgraph/ng_ppp.h>

DESCRIPTION

The ppp node type performs multiplexing for the PPP proto
col. It handles only packets that contain data, and forwards protocol nego
tiation and control packets to a separate controlling entity (e.g., a
user-land daemon). This approach combines the fast dispatch of kernel
implementations with the configuration flexibility of a user-land implemen
tations. The PPP node type directly supports multi-link PPP, Van Jacobson
compression, PPP compression, PPP encryption, and the IP, IPX, and Ap
pleTalk protocols. A single PPP node corresponds to one PPP multi-link
bundle.
There is a separate hook for each PPP link in the bundle,
plus several hooks corresponding to the directly supported protocols.
For compression and encryption, separate attached nodes are required to do
the actual work. The node type used will of course depend on the algo
rithm negotiated. There is also a bypass hook which is used to handle
any protocol not directly supported by the node. This includes all of
the control protocols: LCP, IPCP, CCP, etc. Typically this node is con
nected to a user-land daemon via a ng_socket(4) type node.

ENABLING FUNCTIONALITY

In general, the PPP node enables a specific link or func
tionality when (a) a NGM_PPP_SET_CONFIG message has been received which en
ables it, and (b) the corresponding hook(s) are connected. This allows
the controlling entity to use either method (a) or (b) (or both) to control
the node's behavior. When a link is connected but disabled, traffic
can still flow on the link via the bypass hook (see below).

LINK HOOKS

During normal operation, the individual PPP links are con
nected to hooks link0, link1, etc. Up to NG_PPP_MAX_LINKS links are sup
ported. These device-independent hooks transmit and receive full PPP
frames, which include the PPP protocol, address, control, and information
fields, but no checksum or other link-specific fields.
On outgoing frames, when protocol compression has been en
abled and the protocol number is suitable for compression, the protocol
field will be compressed (i.e., sent as one byte instead of two). Either
compressed or uncompressed protocol fields are accepted on incoming
frames. Similarly, if address and control field compression has been enabled
for the link, the address and control fields will be omitted (except for
LCP frames as required by the standards). Incoming frames have the ad
dress and control fields stripped automatically if present.
Since all negotiation is handled outside the PPP node, the
links should not be connected and enabled until the corresponding link
has reached the network phase (i.e., LCP negotiation and authentication have
completed successfully) and the PPP node has been informed of the link
parameters via the NGM_PPP_LINK_CONFIG message.
When a link is connected but disabled, all received frames
are forwarded directly out the bypass hook, and conversely, frames may be
transmitted via the bypass hook as well. This mode is appropriate for
the link authentication phase. As soon as the link is enabled, the
PPP node will begin processing frames received on the link.

COMPRESSION AND ENCRYPTION

Compression is supported via two hooks, compress and decom
press. When enabled and connected, the PPP node writes outgoing frames
on the comp hook and expects to receive back the compressed frame on the
same hook. Similarly, the decompress hook is used to uncompress incom
ing frames when decompression is negotiated (compression and decompression
are independently negotiable). The type of node attached to these
hooks should correspond to the type of compression negotiated, e.g., De
flate, Predictor-1, etc.
Encryption works exactly analogously via the encrypt and de
crypt nodes. Data is always compressed before being encrypted, and de
crypted before being decompressed.
Only bundle-level compression and encryption is directly
supported; linklevel compression and encryption can be handled transparent
ly by downstream nodes.

VAN JACOBSON COMPRESSION

When all of the vjc_ip, vjc_vjcomp, vjc_vjuncomp, and
vjc_vjip hooks are connected, and the corresponding configuration flag is en
abled, Van Jacobson compression and/or decompression will become ac
tive. Normally these hooks connect to the corresponding hooks of a single
ng_vjc(4) node. The PPP node is compatible with the ``pass through''
modes of the ng_vjc(4) node type.

BYPASS HOOK

When a frame is received on a link with an unsupported pro
tocol, or a protocol which is disabled or for which the corresponding
hook is unconnected, the PPP node forwards the frame out the bypass hook,
prepended with a four byte prefix. This first two bytes of the prefix
indicate the link number on which the frame was received (in network or
der). For such frames received over the bundle (i.e., encapsulated in the
multi-link protocol), the special link number NG_PPP_BUNDLE_LINKNUM is
used. After the two byte link number is the two byte PPP protocol number
(also in network order). The PPP protocol number is two bytes long
even if the original frame was protocol compressed.
Conversely, any data written to the bypass hook is assumed
to be in this same format. The four byte header is stripped off, the PPP
protocol number is prepended (possibly compressed), and the frame is de
livered over the desired link. If the link number is NG_PPP_BUN
DLE_LINKNUM the frame will be delivered over the multi-link bundle; or, if multi
link is disabled, over the (single) PPP link.
Typically when the controlling entity receives an unexpected
packet on the bypass hook it responds either by dropping the frame (if
it is not ready for the protocol) or with an LCP protocol reject (if
it does not recognize or expect the protocol).

MULTILINK OPERATION

To enable multi-link PPP, the corresponding configuration
flag must be set and at least one link connected. The PPP node will not
allow more than one link to be connected if multi-link is not enabled,
nor will it allow certain multi-link settings to be changed while multi
link operation is active (e.g., short sequence number header format).
Since packets are sent as fragments across multiple individ
ual links, it is important that when a link goes down the PPP node is no
tified immediately, either by disconnecting the corresponding hook or
disabling the link via the NGM_PPP_SET_CONFIG control message.
Each link has configuration parameters for latency (speci
fied in milliseconds) and bandwidth (specified in tens of bytes per
second). The PPP node can be configured for round-robin or optimized
packet delivery.
When configured for round-robin delivery, the latency and
bandwidth values are ignored and the PPP node simply sends each frame as
a single fragment, alternating frames across all the links in the
bundle. This scheme has the advantage that even if one link fails silent
ly, some packets will still get through. It has the disadvantage of sub
optimal overall bundle latency, which is important for interactive re
sponse time, and sub-optimal overall bundle bandwidth when links with differ
ent bandwidths exist in the same bundle.
When configured for optimal delivery, the PPP node dis
tributes the packet across the links in a way that minimizes the time it takes
for the completed packet to be received by the far end. This involves
taking into account each link's latency, bandwidth, and current queue
length. Therefore these numbers should be configured as accurately as
possible. The algorithm does require some computation, so may not be ap
propriate for very slow machines and/or very fast links.
As a special case, if all links have identical latency and
bandwidth, then the above algorithm is disabled (because it is unneces
sary) and the PPP node simply fragments frames into equal sized portions
across all of the links.

HOOKS

This node type supports the following hooks:

link<N> Individual PPP link number <N>
compress Connection to compression engine
decompress Connection to decompression engine
encrypt Connection to encryption engine
decrypt Connection to decryption engine
vjc_ip Connection to ng_vjc(4) ip hook
vjc_vjcomp Connection to ng_vjc(4) vjcomp hook
vjc_vjuncomp Connection to ng_vjc(4) vjuncomp hook
vjc_vjip Connection to ng_vjc(4) vjip hook
inet IP packet data
atalk AppleTalk packet data
ipx IPX packet data
bypass Bypass hook; frames have a four byte header
consisting of a: link number and a PPP protocol number.

CONTROL MESSAGES

This node type supports the generic control messages, plus
the following:
NGM_PPP_SET_CONFIG: This command configures all aspects of the node. This; includes
enabling multi-link PPP, encryption, compression, Van; Jacobson compression, and IP, IPv6, AppleTalk, and IPX packet de; livery. It
includes per-link configuration, including enabling the; link, setting latency and bandwidth parameters, and enabling; protocol field
compression. Note that no link or functionality is ac; tive until the
corresponding hook is also connected. This command; takes a struct
ng_ppp_node_conf as an argument:; /* Per-link config structure */
struct ng_ppp_link_conf {
u_char enableLink; /* enable this link */
u_char enableProtoComp;/* enable protocol field

compression */
u_char enableACFComp; /* enable addr/ctrl field

compression */
u_int16_t mru; /* peer MRU */
u_int32_t latency; /* link latency (in mil

liseconds) */
u_int32_t bandwidth; /* link bandwidth (in

bytes/second) */; };; /* Bundle config structure */
struct ng_ppp_bund_conf {
u_int16_t mrru; /* multilink peer

MRRU */
u_char enableMultilink; /* enable multilink

*/
u_char recvShortSeq; /* recv multilink

short seq # */
u_char xmitShortSeq; /* xmit multilink

short seq # */
u_char enableRoundRobin; /* xmit whole pack

ets */
u_char enableIP; /* enable IP data

flow */
u_char enableIPv6; /* enable IPv6 data

flow */
u_char enableAtalk; /* enable AppleTalk

data flow */
u_char enableIPX; /* enable IPX data

flow */
u_char enableCompression; /* enable PPP com

pression */
u_char enableDecompression; /* enable PPP de

compression */
u_char enableEncryption; /* enable PPP en

cryption */
u_char enableDecryption; /* enable PPP de

cryption */
u_char enableVJCompression; /* enable VJ com

pression */
u_char enableVJDecompression; /* enable VJ decom

pression */; };; struct ng_ppp_node_conf {
struct ng_ppp_bund_conf bund;
struct ng_ppp_link_conf links[NG_PPP_MAX_LINKS];; };
NGM_PPP_GET_CONFIG: Returns the current configuration as a struct; ng_ppp_node_conf.
NGM_PPP_GET_LINK_STATS: This command takes a two byte link number as an argu; ment and returns
a struct ng_ppp_link_stat containing statistics for the; corresponding link. Here NG_PPP_BUNDLE_LINKNUM is a valid link; number corresponding to the multi-link bundle.
NGM_PPP_CLR_LINK_STATS: This command takes a two byte link number as an argu; ment and clears
the statistics for that link.
NGM_PPP_GETCLR_LINK_STATS: Same as NGM_PPP_GET_LINK_STATS, but also atomically; clears the
statistics as well.
This node type also accepts the control messages accepted by
the ng_vjc(4) node type. When received, these messages are sim
ply forwarded to the adjacent ng_vjc(4) node, if any. This is particular
ly useful when the individual PPP links are able to generate
NGM_VJC_RECV_ERROR messages (see ng_vjc(4) for a description).

SHUTDOWN

This node shuts down upon receipt of a NGM_SHUTDOWN control
message, or when all hooks have been disconnected.

HISTORY

The ng_ppp node type was implemented in FreeBSD 4.0.

AUTHORS

Archie Cobbs <archie@FreeBSD.org>
BSD August 2, 2004

docs.sk

comprehensive documentation repository

See also

ng_ppp(4)

NAME

SYNOPSIS

DESCRIPTION

ENABLING FUNCTIONALITY

LINK HOOKS

COMPRESSION AND ENCRYPTION

VAN JACOBSON COMPRESSION

BYPASS HOOK

MULTILINK OPERATION

HOOKS

CONTROL MESSAGES

SHUTDOWN

SEE ALSO

HISTORY

AUTHORS