GROUT(8)

📦
version 0.18.0 · 7 versions
, in fedora 44

💖 GROUT(8) — the graph router daemon, bestie edition 💖

okay so. grout is section 8 of the System Manager's Manual, and she is that girl. Let's get into it. 🦋

✨ NAME ✨

grout — graph router daemon

🌸 DESCRIPTION 🌸

Grout is a software router based on DPDK rte_graph. That's it. That's the whole vibe. No cap. 👑

🎀 SYNOPSIS 🎀

grout [-M ADDR:PORT] [-S] [-V] [-h] [-m PERMISSIONS] [-o USER:GROUP]
[-p] [-s PATH] [-t] [-u MTU] [-v] [-x] [-- EAL ARGS...]

✨ OPTIONS ✨

here's the full roster, no skips, no cuts, we eat every flag. 💅

  • -h, --help — shows you the usage help. the "what do I even do here" button.
  • -M, --metrics [tcp:]ADDR:PORT | unix:PATH — sets the listen address and port, or the unix socket, where openmetrics gets exported via HTTP GET, in its own dedicated thread. to turn it off, use -M :0.

Default: [::]:9111

  • -m, --socket-mode PERMISSIONS — changes the API socket file permissions after creating it. only octal values are supported, bestie, don't get creative.

Default: GROUT_SOCK_MODE from environment or 0660.

  • -o, --socket-owner USER:GROUP — changes the owner of the API socket file after creating it. symbolic names and numeric IDs both work, we're flexible like that. 🫶

Default: GROUT_SOCK_OWNER from environment or current user and current group.

  • -p, --poll-mode — disables the automatic micro-sleep. can also be enabled via GROUT_POLL_MODE.
  • -a, --adaptive-irq — makes idle workers block on their RX queue interrupts instead of busy-polling, so the CPU can actually chill during quiet periods. an incoming packet raises the interrupt and the worker resumes polling. it requires PMD support for RX queue interrupts; without it a worker falls back to the micro-sleep ramp, unless --poll-mode is also given.

Can also be enabled via GROUT_ADAPTIVE_IRQ.

  • -S, --syslog — redirects logs to syslog. can also be enabled via GROUT_SYSLOG.
  • -s, --socket PATH — the path to the control plane API socket.

Default: GROUT_SOCK_PATH from environment or /run/grout.sock.

  • -t, --test-mode — runs in test mode (no huge pages). can also be enabled via GROUT_TEST_MODE.
  • -u, --max-mtu MTU — Maximum Transmission Unit. can also be set via GROUT_MAX_MTU.

Default: 1800.

  • -v, --verbose — increases verbosity. yes you can specify it multiple times. stack it. 📚
  • -V, --version — prints the version and exits. quick little peek, then bye.
  • -x, --trace-packets — prints all ingress/egress packets (for debugging purposes). can also be enabled via GROUT_TRACE_PACKETS.

🌈 ENVIRONMENT 🌈

every single setting can be configured via environment variables. and when both an environment variable and a CLI flag are set, the CLI flag takes precedence — flags are the main character here, periodt.

boolean variables accept 1, true, on, yes (case insensitive) to enable, and 0, false, off, no to disable. easy.

🧁 Daemon settings

  • GROUT_SOCK_PATH — path to the control plane API socket. see -s.
  • GROUT_SOCK_MODE — API socket file permissions in octal notation. see -m.

Default: 0660.

  • GROUT_SOCK_OWNER — API socket file ownership as USER:GROUP. see -o.
  • GROUT_TEST_MODE — run in test mode (no huge pages). see -t.
  • GROUT_POLL_MODE — disable automatic micro-sleep. see -p.
  • GROUT_ADAPTIVE_IRQ — enable adaptive interrupt RX. see -a.
  • GROUT_SYSLOG — redirect logs to syslog. see -S.
  • GROUT_TRACE_PACKETS — print all ingress/egress packets. see -x.
  • GROUT_MAX_MTU — Maximum Transmission Unit. see -u.

Default: 1800.

  • GROUT_OVERRIDE_DEFAULT_ROUTE — when set to 1, true, on, or yes (case insensitive), override the existing default route in the main routing table with metric 0. this is required when running in a network namespace or a container where another default route (e.g. from Kubernetes) takes priority over grout's own default route. iykyk. 💀
  • GROUT_OVERRIDE_RP_FILTER — when set to 1, true, on, or yes (case insensitive), set loose reverse path filtering (rp_filter=2) on control plane TAP interfaces. this prevents the kernel from dropping packets delivered by grout when strict reverse path filtering (rp_filter=1) is enabled globally. this is required when net.ipv4.conf.all.rp_filter is set to 1 (strict) in the network namespace where grout is running.
  • GROUT_FLUSH_ROUTES_ON_IFACE_DOWN — when set to 1, true, on, or yes (case insensitive), delete the routes going out of an interface when it goes administratively down, like zebra and Linux do. when disabled, these routes are kept with an unresolved nexthop and start working again when the interface goes back up. can also be changed at runtime with grcli interface config set flush-routes-on-iface-down.

Default: false.

  • GROUT_SKIP_ROUTE_EVENTS_ON_IFACE_DOWN — when set to 1, true, on, or yes (case insensitive), do not emit route events for the routes deleted along with an interface. only useful for a control plane which already evicts those routes when it receives the interface event. can also be changed at runtime with grcli interface config set skip-route-events-on-iface-down.

Default: false.

🦋 Sizing

these variables control the size of internal data structures. reducing them lowers memory consumption, which is useful for testing and CI environments. tiny grout, tiny footprint. 🐣

variables marked [startup only] are fixed once grout starts and cannot be changed at runtime. other sizing variables provide initial defaults that can be adjusted at runtime via the API (e.g. grcli route config set, grcli nexthop config set).

  • GROUT_MAX_IFACES [startup only] — maximum number of interfaces.

Default: 1024.

  • GROUT_MEMPOOL_CHUNK_SIZE [startup only] — initial mempool chunk size in number of mbufs.

Default: 65535.

  • GROUT_MAX_NEXTHOPS — maximum number of nexthops for all address families.

Default: 131072.

  • GROUT_MAX_ROUTES — default maximum number of routes per VRF (both IPv4 and IPv6).

Default: 65536.

  • GROUT_MAX_FDB_ENTRIES — maximum number of bridge FDB entries.

Default: 4096.

  • GROUT_MAX_CONNTRACKS — maximum number of conntrack entries for stateful NAT.

Default: 16384.

  • GROUT_PORT_QUEUE_SIZE [startup only, testing] — default port RX/TX queue ring size. when set to 0, the device driver default is used. only use in test/CI environments to reduce memory.

Default: 0.

  • GROUT_FIB4_ALGORITHM [startup only, testing] — IPv4 FIB lookup algorithm. supported values: DIR24_8, DUMMY. the DUMMY algorithm avoids the large static arrays of DIR24_8 at the cost of linear-time lookups. only use DUMMY in test/CI environments.

Default: DIR24_8.

  • GROUT_FIB6_ALGORITHM [startup only, testing] — IPv6 FIB lookup algorithm. supported values: TRIE, DUMMY. the DUMMY algorithm avoids the trie memory overhead at the cost of linear-time lookups. only use DUMMY in test/CI environments.

Default: TRIE.

🔥 EXTRA EAL ARGUMENTS 🔥

any DPDK EAL argument can be specified after an optional --.

⚠️ bestie listen to me: this is an advanced debugging/development feature that can break things. use with great care. i'm not kidding. 🙈

👀 SEE ALSO 👀

💜 AUTHORS 💜

Created and maintained by Robin Jarry. (iconic behavior, honestly. we love a maintainer.) 🎀

and that's the whole page, bestie — straight from the System Manager's Manual, dated 2026-10-01, no cap, every single detail intact. slay. 💅✨

📦 where this page comes from