Provided by: freebsd-manpages_9.2+1-1_all 
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 protocol. It handles only packets that contain data,
and forwards protocol negotiation 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 implementations. The PPP node type directly supports multi-link PPP, Van
Jacobson compression, PPP compression, PPP encryption, and the IP, IPX, and AppleTalk 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 algorithm 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 connected to a user-land daemon
via a ng_socket(4) type node.
ENABLING FUNCTIONALITY
In general, the PPP node enables a specific link or functionality when (a) a NGM_PPP_SET_CONFIG message
has been received which enables 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 connected to hooks link0, link1, etc. Up to
NG_PPP_MAX_LINKS links are supported. 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 enabled 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 address 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 decompress. Compression and decompression can be
enabled by toggling the enableCompression and enableDecompression fields of the node configuration
structure. (See below.) If enableCompression is set to NG_PPP_COMPRESS_SIMPLE, then all outgoing frames
are sent to the compress hook and all packets received on this hook are expected to be compressed, so the
COMPD tag is put on them unconditionally. If enableCompression is set to NG_PPP_COMPRESS_FULL, then
packets received on the compress hook are resent as is. The compressor node should put the tag, if the
packet was compressed. If enableDecompression is set to NG_PPP_DECOMPRESS_SIMPLE, then the node will
sent to the decompress hook only those frames, that are marked with the COMPD tag. If
enableDecompression is set to NG_PPP_DECOMPRESS_FULL, then the node will sent all incoming packets to the
decompress hook. Compression and decompression can be completely disabled by setting the
enableCompression and enableDecompression fields to the NG_PPP_COMPRESS_NONE and NG_PPP_DECOMPRESS_NONE,
respectively.
Encryption works exactly analogously via the encrypt and decrypt nodes. Data is always compressed before
being encrypted, and decrypted before being decompressed.
Only bundle-level compression and encryption is directly supported; link-level compression and encryption
can be handled transparently 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 enabled, Van Jacobson compression and/or decompression will become active.
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 protocol, 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 order). 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
delivered over the desired link. If the link number is NG_PPP_BUNDLE_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 individual links, it is important that when a link
goes down the PPP node is notified 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 (specified 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 silently, some packets will still get through.
It has the disadvantage of sub-optimal overall bundle latency, which is important for interactive
response time, and sub-optimal overall bundle bandwidth when links with different bandwidths exist in the
same bundle.
When configured for optimal delivery, the PPP node distributes 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
appropriate 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 unnecessary) 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
ipv6 IPv6 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 delivery. 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 active
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 milliseconds) */
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 packets */
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 compression */
u_char enableDecompression; /* enable PPP decompression */
u_char enableEncryption; /* enable PPP encryption */
u_char enableDecryption; /* enable PPP decryption */
u_char enableVJCompression; /* enable VJ compression */
u_char enableVJDecompression; /* enable VJ decompression */
};
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 argument 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_GET_LINK_STATS64
Same as NGM_PPP_GET_LINK_STATS but returns struct ng_ppp_link_stat64 containing 64bit counters.
NGM_PPP_CLR_LINK_STATS
This command takes a two byte link number as an argument 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.
NGM_PPP_GETCLR_LINK_STATS64
Same as NGM_PPP_GETCLR_LINK_STATS but returns struct ng_ppp_link_stat64 containing 64bit counters.
This node type also accepts the control messages accepted by the ng_vjc(4) node type. When received,
these messages are simply forwarded to the adjacent ng_vjc(4) node, if any. This is particularly 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.
SEE ALSO
netgraph(4), ng_async(4), ng_iface(4), ng_mppc(4), ng_pppoe(4), ng_vjc(4), ngctl(8)
W. Simpson, The Point-to-Point Protocol (PPP), RFC 1661.
K. Sklower, B. Lloyd, G. McGregor, D. Carr, and T. Coradetti, The PPP Multilink Protocol (MP), RFC 1990.
HISTORY
The ng_ppp node type was implemented in FreeBSD 4.0.
AUTHORS
Archie Cobbs <archie@FreeBSD.org>
Debian September 24, 2012 NG_PPP(4)