NG_PPTPGRE(4)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

💜 NG_PPTPGRE(4) — the ng_pptpgre girlies' manual 💜

okay bestie, pull up a chair, because this is the manual page for ng_pptpgre — a kernel interfaces manual, no cap — and it's actually iconic once you get past the acronyms. let's get into it ✨

🌸 SYNOPSIS 🌸

like, include these first, obviously:

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

🦋 DESCRIPTION 🦋

so the pptpgre node type does Generic Routing Encapsulation (GRE) over IP for the PPTP protocol, exactly as specified by RFC 2637. like, that's the whole vibe. this involves packet encapsulation, sequencing, acknowledgement, and an adaptive timeout sliding window mechanism — yes, all four, she's multitalented 💅

but — and this is important — this node type does not handle any of the TCP control protocol or call negotiation defined by PPTP. not her job, not her problem, periodt.

the way this works is: the node expects to receive complete IP packets, including the IP header, on the "lower" hook — but it transmits outgoing frames without any IP header. asymmetric queen 🎀

typical use? connect the "upper" hook to one of the link hooks of an ng_ppp(4) node, and the "lower" hook to the inet/raw/gre hook of an ng_ksocket(4) node. that's the classic build, iykyk.

🎀 HOOKS 🎀

she supports these hooks, bestie:

  • session_hhhh — Session 0xhhhh data packets to the upper protocol layers
  • upper — same as session_hhhh, but for a single session with configurable cid (legacy ✨)
  • lower — connection to the lower protocol layers

🔥 CONTROL MESSAGES 🔥

this node type supports the generic control messages, plus these bad boys:

  • NGM_PPTPGRE_SET_CONFIG (setconfig) — this command resets and configures the hook for a session. if the corresponding session_hhhh hook is not connected, the upper hook will be configured instead. it takes a struct ng_pptpgre_conf as an argument:
/* Configuration for a session */
struct ng_pptpgre_conf {
    u_char      enabled;          /* enables traffic flow */
    u_char      enableDelayedAck; /* enables delayed acks */
    u_char      enableAlwaysAck;  /* always include ack with data */
    u_char      enableWindowing;  /* enable windowing algorithm */
    uint16_t    cid;              /* my call id */
    uint16_t    peerCid;          /* peer call id */
    uint16_t    recvWin;          /* peer recv window size */
    uint16_t    peerPpd;          /* peer packet processing delay
                                     (in 1/10 of a second) */
};

ok so field by field, because you know I love a breakdown 💖

  • the enabled field enables traffic flow through the node.
  • the enableDelayedAck field enables delayed acknowledgement (maximum 250 milliseconds), which is a genuinely useful optimization and should generally be turned on.
  • the enableAlwaysAck field enables sending acknowledgements with every data packet, which is probably helpful as well. she's thorough like that.

now the spicy one 🌶️ — enableWindowing enables the PPTP packet windowing mechanism specified by the protocol. disabling this will cause the node to violate the protocol, possibly confusing other PPTP peers — but often results in better performance. the windowing mechanism is a design error in the PPTP protocol; L2TP, the successor to PPTP, removes it entirely. so yeah, sometimes breaking the rules is the move, but know that you're doing it 😭

the remaining fields are as supplied by the PPTP virtual call setup process. not our business, we just pass them through 🫶

  • NGM_PPTPGRE_GET_CONFIG (getconfig) — takes a two byte argument as cid and returns the current configuration as a struct ng_pptpgre_conf.
  • NGM_PPTPGRE_GET_STATS (getstats) — this command returns a struct ng_pptpgre_stats containing various node statistics. numbers, we love to see them 📊
  • NGM_PPTPGRE_CLR_STATS (clrstats) — this command resets the node statistics. fresh start energy ✨
  • NGM_PPTPGRE_GETCLR_STATS (getclrstats) — this command atomically gets and resets the node statistics, returning a struct ng_pptpgre_stats. get and clear in one go, efficient icon 👑

💀 SHUTDOWN 💀

this node shuts down upon receipt of a NGM_SHUTDOWN control message, or when both hooks have been disconnected. so if you're like "why is she gone", check your hooks bestie 😭

🌈 SYSCTL VARIABLES 🌈

a set of sysctl(8) variables controls this node's ability to deal with some amount of packet reorder that sometimes happens in transit. and like, packet reorder results in packet drops (unless the order is restored) because PPP protocol can not deliver reordered data. so these matter, fr fr. here they are with their default value and meaning:

  • net.graph.pptpgre.reorder_max: 1 — defines maximum length of the node's private reorder queue used to keep data waiting for late packets. a zero value disables reordering. the default value allows the node to restore the order for two packets swapped in transit. greater values allow the node to deliver packets being late after more packets in sequence — at the cost of increased kernel memory usage. tradeoffs, always tradeoffs 💅
  • net.graph.pptpgre.reorder_timeout: 1 — defines time value in milliseconds used to wait for late packets. she will wait, but she will not wait forever ⏳

🧚 SEE ALSO 🧚

also, the reading list, no skimming 👑:

  • K. Hamzeh, G. Pall, W. Verthein, J. Taarud, W. Little, and G. Zorn, Point-to-Point Tunneling Protocol (PPTP), RFC 2637.
  • S. Hanks, T. Li, D. Farinacci, and P. Traina, Generic Routing Encapsulation over IPv4 networks, RFC 1702.

⭐ HISTORY ⭐

the ng_pptpgre node type was implemented in FreeBSD 4.0. vintage, but make it functional 🎀

🫶 AUTHORS 🫶

Archie Cobbs <archie@FreeBSD.org> — we stan a legend ✨

🙈 BUGS 🙈

ok so this is a real one: the node should not expect incoming GRE packets to have an IP header. this behavior is inherited from the (converse) behavior of raw IP sockets. an intermediate node that strips IP headers in one direction should be used instead. so like, don't come for her, it's a whole inherited situation 💀

and that's the whole page bestie, you're officially certified 🎓💖 this was the Debian build, dated November 4, 2018 — so go forth, configure your sessions, and remember: windowing is a design error but sometimes faster, reordering has a queue, and both hooks disconnected means she's GONE. mwah 💅✨

📦 where this page comes from