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
(setconfig
)
- 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 */
uint16_t mru; /* peer MRU */
uint32_t latency; /* link latency (in milliseconds) */
uint32_t bandwidth; /* link bandwidth (in bytes/sec/10) */
};
/* Bundle config structure */
struct ng_ppp_bund_conf {
uint16_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
(getconfig
)
- Returns the current configuration as a
struct
ng_ppp_node_conf
.
NGM_PPP_GET_LINK_STATS
(getstats
)
- 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
(getstats64
)
- Same as NGM_PPP_GET_LINK_STATS but returns
struct ng_ppp_link_stat64
containing
64bit counters.
NGM_PPP_CLR_LINK_STATS
(clrstats
)
- This command takes a two byte link number as an argument and clears the
statistics for that link.
NGM_PPP_GETCLR_LINK_STATS
(getclrstats
)
- Same as
NGM_PPP_GET_LINK_STATS
, but
also atomically clears the statistics as well.
NGM_PPP_GETCLR_LINK_STATS64
(getclrstats64
)
- 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⟩