NG_CAR(4)

💖 NG_CAR(4) — the ng_car manual, but make it cute 💖

okay bestie, gather round, because we're talking about ng_car, aka the Committed Access Rate netgraph node type. she's a traffic-shaping icon and she's about to eat. 🎀

---

✨ NAME ✨

ng_car — Committed Access Rate netgraph node type 🚦

---

🌸 SYNOPSIS 🌸

#include <netgraph/ng_car.h>

that's it. one include. she's low-maintenance like that 💅

---

🦋 DESCRIPTION 🦋

so the car node type limits traffic flowing through it, and she does it with a whole little toolkit:

• Single rate three color marker as described in RFC 2697,
• Two rate three color marker as described in RFC 2698,
• RED-like rate limit algorithm used by Cisco,
• Traffic shaping with RED.

like, pick your fighter. she's versatile. no cap. 👑

---

🪝 HOOKS 🪝

this node type supports the following hooks, bestie:

• upper — Hook leading to upper layer protocols.
• lower — Hook leading to lower layer protocols.

and here's the vibe check on direction, because it matters:

Traffic flowing from upper to lower is considered downstream traffic. Traffic flowing from lower to upper is considered upstream traffic.

remember it, you'll need it for the config struct later. iykyk 😌

---

🎀 MODES OF OPERATION 🎀

each hook can operate in one of the following modes. choose wisely, they all have main character energy but different personalities:

⭐ NG_CAR_SINGLE_RATE

Single rate three color marker as described in RFC 2697. Committed burst packets are counted as green, extended burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR (Committed Information Rate) speed. When it is full, exceeded burst getting refilled.

⭐ NG_CAR_DOUBLE_RATE

Two rate three color marker as described in RFC 2698. Committed burst packets are counted as green, peak burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR speed. Peak burst getting refilled with PIR (Peak Information Rate) speed at the same time.

two rates, running simultaneously, doing the most. we love a multitasker 🫶

⭐ NG_CAR_RED

Similar to NG_CAR_SINGLE_RATE, but with a different understanding of extended burst. When normal burst exceeded and extended burst is used, packets are counted red with probability equal to part of extended burst consumed. Extended burst getting refilled first. When it is full, committed burst getting refilled. This behavior is similar to RED active queue management algorithm.

This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE. she's the considerate friend fr fr 🌸

⭐ NG_CAR_SHAPE

Committed burst packets are counted as green, exceeding packets are delayed by queue with RED management and counted as yellow. Packets dropped by queue counted as red. Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%.

Traffic shaping is much more polite to the TCP traffic than rate limit on links with bandwidth * delay product less than 6-8 TCP segments, but it consumes additional system resources for queue processing. 💀 worth it though.

---

by default, all information rates are measured in bits per second and bursts are measured in bytes. but when the NG_CAR_COUNT_PACKETS option is enabled, rates are measured in packets per second and bursts are in packets. the more you know ✨

---

💌 CONTROL MESSAGES 💌

this node type supports the generic control messages and the following specific messages. let's get into the group chat receipts 📱

• NGM_CAR_SET_CONF (setconf) — Set node configuration to the specified at struct ng_car_bulkconf
• NGM_CAR_GET_CONF (getconf) — Return current node configuration as struct ng_car_bulkconf

and here's the struct, copied exactly, do NOT touch a single character bestie:

struct ng_car_hookconf {
        uint64_t cbs;           /* Committed burst size (bytes) */
        uint64_t ebs;           /* Exceeded/Peak burst size (bytes) */
        uint64_t cir;           /* Committed information rate (bits/s) */
        uint64_t pir;           /* Peak information rate (bits/s) */
        uint8_t  green_action;  /* Action for green packets */
        uint8_t  yellow_action; /* Action for yellow packets */
        uint8_t  red_action;    /* Action for red packets */
        uint8_t  mode;          /* single/double rate, ... */
        uint8_t  opt;           /* color-aware or color-blind */
};

/* possible actions (..._action) */
enum {
    NG_CAR_ACTION_FORWARD = 1,
    NG_CAR_ACTION_DROP
};

/* operation modes (mode) */
enum {
    NG_CAR_SINGLE_RATE = 0,
    NG_CAR_DOUBLE_RATE,
    NG_CAR_RED,
    NG_CAR_SHAPE
};

/* mode options (opt) */
#define NG_CAR_COUNT_PACKETS    2

struct ng_car_bulkconf {
        struct ng_car_hookconf upstream;
        struct ng_car_hookconf downstream;
};

• NGM_CAR_GET_STATS (getstats) — Return node statistics as struct ng_car_bulkstats

and the stats structs, also verbatim, also sacred:

struct ng_car_hookstats {
        uint64_t passed_pkts;   /* Counter for passed packets */
        uint64_t droped_pkts;   /* Counter for dropped packets */
        uint64_t green_pkts;    /* Counter for green packets */
        uint64_t yellow_pkts;   /* Counter for yellow packets */
        uint64_t red_pkts;      /* Counter for red packets */
        uint64_t errors;        /* Counter for operation errors */
};

struct ng_car_bulkstats {
        struct ng_car_hookstats upstream;
        struct ng_car_hookstats downstream;
};

psst — yes, droped_pkts really is spelled like that in the struct. that's not me being quirky, that's canon. leave it alone 🙈

• NGM_CAR_CLR_STATS (clrstats) — Clear node statistics.
• NGM_CAR_GETCLR_STATS (getclrstats) — Atomically return and clear node statistics. ✨atomically✨, she's doing it all in one go, no gaps.

---

🛑 SHUTDOWN 🛑

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

she simply leaves. no drama. iconic exit 💅

---

🌈 EXAMPLES 🌈

okay here's the moment you've been waiting for. let's limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s and incoming packet rate to 5000pps.

/usr/sbin/ngctl -f- <<-SEQ
        mkpeer fxp0: car lower lower
        name fxp0:lower fxp0_car
        connect fxp0: fxp0_car: upper upper
        msg fxp0_car: setconf { downstream={ cir=20000000 cbs=2500000 ebs=2500000 greenAction=1 yellowAction=1 redAction=2 mode=2 } upstream={ cir=5000 cbs=100 ebs=100 greenAction=1 yellowAction=1 redAction=2 mode=2 opt=2 } }
SEQ

look at that heredoc. look at that config. she ate and left no crumbs 🔥

---

👀 SEE ALSO 👀

• netgraph(4)
• ngctl(8)
• J. Heinanen, A Single Rate Three Color Marker, RFC 2697.
• J. Heinanen, A Two Rate Three Color Marker, RFC 2698.

---

🫶 AUTHORS 🫶

• Nuno Antunes <nuno.antunes@gmail.com>
• Alexander Motin <mav@FreeBSD.org>

thank you for your service, legends 👑

---

💀 BUGS 💀

At this moment only DROP and FORWARD actions are implemented.

so like, don't go looking for other actions. they're not there. yet. 🧚

---

and that's the whole page bestie — this one came from the Debian crew, dated November 13, 2012, filed under NG_CAR(4) in the Kernel Interfaces Manual. mwah, go shape some traffic 💖✨