NG_PPP(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

ng_ppp 💖 the PPP protocol netgraph node type (this is NG_PPP(4), bestie, from the Kernel Interfaces Manual)

okay so. sit down. grab a snack. we're doing netgraph PPP and honestly? it's giving iconic. ✨

SYNOPSIS 🎀

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

DESCRIPTION 💅

So the ppp node type does the multiplexing for the PPP protocol. That's the whole vibe. But here's the thing — it only deals with packets that actually contain data. All the protocol negotiation and control packets? It doesn't touch those. It forwards them straight to a separate controlling entity, like a user-land daemon. 🫶

And the way that this slaps is that it combines the fast dispatch of kernel implementations with the configuration flexibility of a user-land implementation. Best of both worlds, no cap.

The PPP node type directly supports:

  • multi-link PPP
  • Van Jacobson compression
  • PPP compression
  • PPP encryption
  • and the IP, IPX, and AppleTalk protocols

One single PPP node = one PPP multi-link bundle. That's the mapping, periodt. 👑

There's a separate hook for each PPP link in the bundle, plus a bunch of hooks for the directly supported protocols. For compression and encryption you need separate attached nodes to do the actual work — the node type you use obviously depends on which algorithm got negotiated. There's also a bypass hook which handles any protocol the node doesn't directly support. That includes all the control protocols: LCP, IPCP, CCP, etc. Typically this node gets connected to a user-land daemon via a ng_socket(4) type node. 🦋

ENABLING FUNCTIONALITY ⭐

Generally speaking, the PPP node enables a specific link or functionality when:

  1. a NGM_PPP_SET_CONFIG message has been received which enables it, and
  2. the corresponding hook(s) are connected.

This lets the controlling entity use either method — (a) or (b), or both — to control the node's behavior. And lowkey the cool part: when a link is connected but disabled, traffic can still flow on the link via the bypass hook (see below 👇).

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 gets 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. Don't skip that step, bestie.

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. You can turn compression and decompression on 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 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. Order matters, queen. 👑

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. 📬

That prefix is:

  • the first two bytes = 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.
  • then 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). 🙈

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). So like... set it up right the first time, bestie. 💅

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. Don't leave it hanging. 😭

Each link has configuration parameters for:

  • latency (specified in milliseconds)
  • bandwidth (specified in tens of bytes per second)

The PPP node can be configured for round-robin or optimized packet delivery.

round-robin 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.

  • advantage: even if one link fails silently, some packets will still get through.
  • disadvantage: 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.

optimal delivery ⭐

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. It's giving "why try when it's already perfect". 🎀

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 🎛️

okay so this node type is so chill with the generic control messages — it accepts all of those, plus these extra ones, which are the ones that actually do stuff:

  • NGM_PPP_SET_CONFIG (setconfig) — bestie this is THE one. it configures literally every aspect of the node. we're talking enabling multi-link PPP, encryption, compression, Van Jacobson compression, and IP, IPv6, AppleTalk and IPX packet delivery. it also handles per-link config — enabling the link, setting latency and bandwidth parameters, enabling protocol field compression. 💅
⚠️ huge caveat alert: no link or functionality is active until the corresponding hook is also connected. so like, setting it doesn't do it. connect the hook or it's giving nothing.

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) — hands you the current config back, as a struct ng_ppp_node_conf. it's giving receipts ✨
  • NGM_PPP_GET_LINK_STATS (getstats) — takes a two byte link number as an argument and returns a struct ng_ppp_link_stat stuffed with statistics for that link. oh and heads up, NG_PPP_BUNDLE_LINKNUM is a valid link number that corresponds to the multi-link bundle 👑
  • NGM_PPP_GET_LINK_STATS64 (getstats64) — same as NGM_PPP_GET_LINK_STATS except it returns struct ng_ppp_link_stat64 with 64bit counters. more numbers, no downside 🍓
  • NGM_PPP_CLR_LINK_STATS (clrstats) — takes a two byte link number as an argument and clears the statistics for that link. bye stats 🫶
  • NGM_PPP_GETCLR_LINK_STATS (getclrstats) — same as NGM_PPP_GET_LINK_STATS, but it also atomically clears the statistics too. get it and yeet it in one move, obsessed 😭
  • NGM_PPP_GETCLR_LINK_STATS64 (getclrstats64) — same as NGM_PPP_GETCLR_LINK_STATS but returns struct ng_ppp_link_stat64 with 64bit counters.

also, and this is lowkey the cutest part: this node type also accepts the control messages accepted by the ng_vjc(4) node type. when it receives those, they just get forwarded to the adjacent ng_vjc(4) node, if there is one. super handy when the individual PPP links are able to generate NGM_VJC_RECV_ERROR messages (peep ng_vjc(4) for the description of that) 🌈

🛑 SHUTDOWN 🛑

this node shuts down when it gets a NGM_SHUTDOWN control message, or when all hooks have been disconnected. it's the "everyone left the group chat" situation fr fr 💀

👀 SEE ALSO 👀

📜 HISTORY 📜

the ng_ppp node type was implemented in FreeBSD 4.0. a legend, an icon, the moment ✨

💖 AUTHORS 💖

Archie Cobbs <archie@FreeBSD.org> — thank you for your service, king 👑

and that's the whole page bestie!! this Debian build of the page is dated November 13, 2012, and the source is the Debian ng_ppp(4) manpage — go forth and configure responsibly 🎀💅🦋

📦 where this page comes from