grout - Man Page
graph router daemon
Description
Grout is a software router based on DPDK rte_graph.
Synopsis
grout [-M ADDR:PORT] [-S] [-V] [-h] [-m PERMISSIONS] [-o USER:GROUP] [-p] [-r RATE] [-s PATH] [-t] [-u MTU] [-v] [-x] [-- EAL ARGS...]
Options
- -h, --help
Display usage help.
- -M, --metrics [tcp:]ADDR:PORT | unix:PATH
Set the listen address and port or unix socket where openmetrics will be exported via HTTP GET in a dedicated thread. To disable, use -M :0.
Default: [::]:9111
- -m, --socket-mode PERMISSIONS
Change the API socket file permissions after creating it. Only octal values are supported.
Default: GROUT_SOCK_MODE from environment or 0660.
- -o, --socket-owner USER:GROUP
Change the owner of the API socket file after creating it. Symbolic names and numeric IDs are supported.
Default: GROUT_SOCK_OWNER from environment or current user and current group.
- -p, --poll-mode
Disable automatic micro-sleep. Can also be enabled via GROUT_POLL_MODE.
- -a, --adaptive-irq
Make idle workers block on their RX queue interrupts instead of busy-polling, so the CPU can idle 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.
- -r, --log-rate RATE
Maximum number of rate-limited control plane log messages per second per counter. Only log messages tied to a control plane counter are rate limited; the counters keep accounting for every occurrence. Set to 0 to disable rate limiting. Can also be set via GROUT_LOG_MAX_RATE and changed at runtime with grcli log rate set.
Default: 10.
- -S, --syslog
Redirect logs to syslog. Can also be enabled via GROUT_SYSLOG.
- -s, --socket PATH
Path the control plane API socket.
Default: GROUT_SOCK_PATH from environment or /run/grout.sock.
- -t, --test-mode
Run 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
Increase verbosity. Can be specified multiple times.
- -V, --version
Print version and exit.
- -x, --trace-packets
Print all ingress/egress packets (for debugging purposes). Can also be enabled via GROUT_TRACE_PACKETS.
Environment
All settings can be configured via environment variables. When both an environment variable and a CLI flag are set, the CLI flag takes precedence. Boolean variables accept 1, true, on, yes (case insensitive) to enable and 0, false, off, no to disable.
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_LOG_MAX_RATE
Maximum number of rate-limited control plane log messages per second per counter. See -r.
Default: 10.
- 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.
- 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.
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_CP_MEMPOOL_SIZE [startup only]
Size of the per-interface mbuf pool used for packets exchanged with the control plane TAP/TUN devices (loopback and representor interfaces).
Default: 256.
- 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 --. This is an advanced debugging/development feature that can break things. Use with great care.
See Also
Authors
Created and maintained by Robin Jarry.