{"id":17059070,"url":"https://github.com/rjarry/grout","last_synced_at":"2025-06-24T21:41:41.189Z","repository":{"id":229007854,"uuid":"775159681","full_name":"DPDK/grout","owner":"DPDK","description":"grout # a graph router based on DPDK","archived":false,"fork":false,"pushed_at":"2025-06-20T13:33:37.000Z","size":1885,"stargazers_count":37,"open_issues_count":19,"forks_count":17,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-06-20T14:33:36.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DPDK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"licenses/BSD-3-clause.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-20T21:42:05.000Z","updated_at":"2025-06-20T13:26:54.000Z","dependencies_parsed_at":"2024-06-22T06:03:23.661Z","dependency_job_id":"81772ca2-7c94-4d0f-92ca-bdf74513525d","html_url":"https://github.com/DPDK/grout","commit_stats":null,"previous_names":["rjarry/brouter","rjarry/grout"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/DPDK/grout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DPDK%2Fgrout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DPDK%2Fgrout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DPDK%2Fgrout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DPDK%2Fgrout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DPDK","download_url":"https://codeload.github.com/DPDK/grout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DPDK%2Fgrout/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261761682,"owners_count":23205992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T10:32:29.678Z","updated_at":"2025-06-24T21:41:41.134Z","avatar_url":"https://github.com/DPDK.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grout # a graph router based on DPDK\n\n![logo.svg](/docs/logo.svg)\n\n`grout` stands for *Graph Router*. In English, *\"grout\"* refers to thin mortar\nthat hardens to fill gaps between tiles.\n\n`grout` is a DPDK based network processing application. It uses the [rte_graph]\nlibrary for data path processing.\n\nIts main purpose is to simulate a network function or a physical router for\ntesting/replicating real (usually closed source) VNF/CNF behavior with an\nopensource tool.\n\nIt comes with a client library to configure it over a standard UNIX socket and\na CLI that uses that library. The CLI can be used as an interactive shell, but\nalso in scripts one command at a time, or by batches.\n\n[rte_graph]: http://doc.dpdk.org/guides/prog_guide/graph_lib.html\n\n## License\n\n* [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)\n* [GPL-2.0-or-later](https://spdx.org/licenses/GPL-2.0-or-later.html) — only\n  for the `frr` plugin.\n\n## Features\n\n* IPv4 forwarding\n* IPv6 forwarding\n* Multiple VRF domains\n* VLAN sub interfaces\n* IP in IP tunnels\n\n## Quickstart\n\n### Installation\n\nSome nightly packages are available in the [edge] release. For quick\ninstallation on RPM and DEB based distributions.\n\n[edge]: https://github.com/DPDK/grout/releases/tag/edge\n\nExample:\n\n```sh\ndnf install https://github.com/DPDK/grout/releases/download/edge/grout.x86_64.rpm\n```\n\nor\n\n```sh\nwget https://github.com/DPDK/grout/releases/download/edge/grout_amd64.deb\napt install ./grout_amd64.deb\n```\n\n### Host configuration\n\nOnce the package and its dependencies are installed, you need to ensure your\nmachine is setup properly to run DPDK applications.\n\nExample on Intel RHEL/CentOS/Fedora:\n\n```sh\ndnf install driverctl tuned-profiles-cpu-partitioning\n\n# Enable IOMMU on boot.\ngrubby --update-kernel ALL --args \"iommu=pt intel_iommu=on\"\n\n# Reserve hugepages.\ngrubby --update-kernel ALL --args \"default_hugepagesz=1GB hugepagesz=1G hugepages=16\"\n\n# Isolate CPUs for grout datapath (adjust to taste).\necho \"isolated_cores=2-19,22-39\" \u003e /etc/tuned/cpu-partitioning-powersave-variables.conf\necho \"max_power_state=C6|170\" \u003e\u003e /etc/tuned/cpu-partitioning-powersave-variables.conf\ntuned-adm profile cpu-partitioning-powersave\ngrubby --update-kernel ALL --args \"isolcpus=2-19,22-39\"\n\n# Reboot to enable IOMMU and have hugepages reserved.\nsystemctl reboot\n\n# Bind the devices you intend on using with grout to vfio-pci.\n# NB: NVIDIA/Mellanox NICs should remain bound to their default driver.\ndriverctl set-override 0000:8a:00.0 vfio-pci\ndriverctl set-override 0000:8a:00.1 vfio-pci\n```\n\nSee DPDK documentation for more details:\n\n* https://doc.dpdk.org/guides/linux_gsg/sys_reqs.html#running-dpdk-applications\n* https://doc.dpdk.org/guides/linux_gsg/enable_func.html#using-linux-core-isolation-to-reduce-context-switches\n\n### (Re)Start the service\n\n```sh\n# Startup configuration.\ncat \u003e /etc/grout.init \u003c\u003cEOF\nset affinity cpus control 0,1,20,21 datapath 2,22\nadd interface port p0 devargs 0000:8a:00.0 rxqs 1 qsize 2048\nadd interface port p1 devargs 0000:8a:00.1 rxqs 1 qsize 2048\nadd ip address 1.2.3.4/24 iface p0\nadd ip address 4.3.2.1/24 iface p1\nadd ip route 0.0.0.0/0 via 1.2.3.254\nEOF\n\nsystemctl restart grout.service\n```\n\n```console\n[root@grout]$ systemctl status -n40 grout.service\n● grout.service - Graph router daemon\n     Loaded: loaded (/usr/lib/systemd/system/grout.service; enabled; preset: disabled)\n     Active: active (running) since Sat 2024-11-30 10:31:40 CEST; 4s ago\n    Process: 31298 ExecStartPre=/usr/bin/udevadm settle (code=exited, status=0/SUCCESS)\n    Process: 31302 ExecStartPost=/usr/bin/grcli -xef /etc/grout.init (code=exited, status=0/SUCCESS)\n   Main PID: 31299 (grout)\n     Status: \"grout version v0.2-93-gf53240e3750a started\"\n      Tasks: 5 (limit: 195427)\n     Memory: 6.6M\n        CPU: 19.185s\n     CGroup: /system.slice/grout.service\n             └─31299 /usr/bin/grout\n\nNov 30 10:31:31 grout systemd[1]: Starting Graph router daemon...\nNov 30 10:31:31 grout grout[31299]: GROUT: main: starting grout version v0.2-93-gf53240e3750a\nNov 30 10:31:31 grout grout[31299]: GROUT: dpdk_init: DPDK 24.11.0\nNov 30 10:31:31 grout grcli[31302]: + add interface port p0 devargs 0000:8a:00.0 rxqs 1 qsize 2048\nNov 30 10:31:32 grout grout[31299]: GROUT: gr_datapath_loop: [CPU 2] starting tid=31303\nNov 30 10:31:40 grout grcli[31302]: Created interface 1\nNov 30 10:31:32 grout grcli[31302]: + add interface port p1 devargs 0000:8a:00.1 rxqs 1 qsize 2048\nNov 30 10:31:34 grout grout[31299]: GROUT: gr_datapath_loop: [CPU 22] starting tid=31305\nNov 30 10:31:40 grout grcli[31302]: Created interface 2\nNov 30 10:31:40 grout grcli[31302]: + add ip address 172.16.0.2/24 iface p0\nNov 30 10:31:40 grout grcli[31302]: + add ip address 172.16.1.2/24 iface p1\nNov 30 10:31:40 grout grcli[31302]: + add ip route 0.0.0.0/0 via 172.16.1.183\nNov 30 10:31:40 grout systemd[1]: Started Graph router daemon.\n```\n\n### Interact with the CLI\n\nBy default, the CLI will start an interactive shell with command completion:\n\n```console\n[root@grout]$ grcli\nWelcome to the grout CLI.\nUse ? for help and \u003ctab\u003e for command completion.\ngrout# ?\nquit                 Exit the CLI.\nadd                  Create objects in the configuration.\ndel                  Delete objects from the configuration.\nshow                 Display information about the configuration.\nclear                Clear counters or temporary entries.\nset                  Modify existing objects in the configuration.\ngrout# show interface\nNAME  ID  FLAGS       VRF  TYPE  INFO\np0    1   up running  0    port  devargs=0000:8a:00.0 mac=30:3e:a7:0b:eb:c0\np1    2   up running  0    port  devargs=0000:8a:00.1 mac=30:3e:a7:0b:eb:c1\ngrout# show affinity qmap\nIFACE  RXQ_ID  CPU_ID  ENABLED\np0     0       2       1\np1     0       22      1\ngrout# show ip address\nIFACE  ADDRESS\np0     172.16.0.2/24\np1     172.16.1.2/24\ngrout# show ip route\nDESTINATION    NEXT_HOP\n172.16.0.0/24  172.16.0.2\n172.16.1.0/24  172.16.1.2\n0.0.0.0/0      172.16.1.183\ngrout# show nexthop\nVRF  IP            MAC                IFACE  QUEUE  AGE  STATE\n0    172.16.0.2    30:3e:a7:0b:eb:c0  p0     0      0    reachable static local link\n0    172.16.1.2    30:3e:a7:0b:eb:c1  p1     0      0    reachable static local link\n0    172.16.1.183  ??:??:??:??:??:??  ?      0      ?    gateway\ngrout#\n\n```\n\nThe CLI can also be used as a one-shot command (bash-completion is available):\n\n```console\n[root@grout]$ grcli \u003cTAB\u003e\u003cTAB\u003e\nadd                 (Create objects in the configuration.)\nclear               (Clear counters or temporary entries.)\ndel                 (Delete objects from the configuration.)\n-e                  (Abort on first error.)\n--err-exit          (Abort on first error.)\n--help              (Show usage help and exit.)\n-h                  (Show usage help and exit.)\nquit                (Exit the CLI.)\nset                 (Modify existing objects in the configuration.)\nshow                (Display information about the configuration.)\n--socket            (Path to the control plane API socket.)\n-s                  (Path to the control plane API socket.)\n--trace-commands    (Print executed commands.)\n-x                  (Print executed commands.)\n[root@grout]$ grcli show \u003cTAB\u003e\u003cTAB\u003e\ngraph        (Show packet processing graph info.)\ninterface    (Display interface details.)\nip           (Show IPv4 stack details.)\nport         (Display DPDK port information.)\nstats        (Print statistics.)\n[root@grout]$ grcli show stats \u003cTAB\u003e\u003cTAB\u003e\nhardware    (Print hardware stats.)\nsoftware    (Print software stats.)\n[root@grout]$ grcli show stats software\nNODE         CALLS   PACKETS  PKTS/CALL  CYCLES/CALL  CYCLES/PKT\nport_rx     757792  22623757       29.9       1776.4        59.5\nip_input    333675  22623757       67.8       3091.0        45.6\nport_tx     333675  22623757       67.8       1984.2        29.3\neth_input   757792  22623757       29.9        659.7        22.1\neth_output  333675  22623757       67.8       1323.4        19.5\nip_output   333675  22623757       67.8        926.3        13.7\nip_forward  333675  22623757       67.8        691.8        10.2\n```\n\n## Packet graph\n\nDump the packet graph (excluding all error nodes) and convert it to an SVG\nimage.\n\n```console\n[root@grout]$ grcli show graph brief | dot -Tsvg \u003e docs/graph.svg\n```\n\n![docs/graph.svg](/docs/graph.svg)\n\n## Build from source\n\n### Install build dependencies\n\n```sh\ndnf install git gcc make meson ninja-build pkgconf \\\n        python3-pyelftools golang-github-cpuguy83-md2man \\\n        libcmocka-devel libedit-devel libevent-devel numactl-devel \\\n        libsmartcols-devel libarchive-devel rdma-core-devel\n```\n\nor\n\n```sh\napt install git gcc make meson ninja-build pkgconf \\\n        python3-pyelftools go-md2man \\\n        libcmocka-dev libedit-dev libevent-dev libnuma-dev \\\n        libsmartcols-dev libarchive-dev libibverbs-dev\n```\n\nImportant: `grout` requires at least `gcc` 13 or `clang` 15.\n\n### Install development dependencies\n\nIn order to run the `smoke-tests`, `lint`, `check-patches` and `update-graph`\ntargets, you'll need additional packages:\n\n```sh\ndnf install gawk clang-tools-extra jq codespell curl traceroute graphviz ndisc6\n```\n\nor\n\n```sh\napt install gawk clang-format jq codespell curl traceroute graphviz ndisc6\n```\n\n### Build\n\n```\ngit clone https://github.com/DPDK/grout\ncd grout\nmake\n```\n\n### Start the router daemon\n\nThe binaries are located in the build directory:\n\n```console\n[root@dev grout]$ ./build/grout -v -s grout.sock\nINFO: GROUT: dpdk_init: starting grout version v0.2-93-gf53240e3750a\nINFO: GROUT: dpdk_init: DPDK 24.11.0\nINFO: GROUT: dpdk_init: EAL arguments: -l 0 -a 0000:00:00.0 --log-level=*:notice --log-level=grout:info\n...\nINFO: GROUT: listen_api_socket: listening on API socket grout.sock\n```\n\n### Start the CLI\n\n```console\n[root@dev grout]$ ./build/grcli -s grout.sock\nWelcome to the grout CLI.\nUse ? for help and \u003ctab\u003e for command completion.\ngrout#\n```\n\n## Contact\n\n* Mailing list: grout@dpdk.org ([archives](http://mails.dpdk.org/archives/grout/))\n* Slack channel: [#grout @ dpdkproject.slack.com](https://dpdkproject.slack.com/archives/C07NAFWE1MG)\n\n## Contributing\n\nAnyone can contribute to `grout`. See [`CONTRIBUTING.md`](/CONTRIBUTING.md).\n\n## Dependencies\n\n| Name | Type | License | Code |\n|------|------|---------|------|\n| DPDK | Build \u0026 Runtime | BSD-3-Clause | https://git.dpdk.org/dpdk/ |\n| libnuma | Build \u0026 Runtime | LGPL-2.1 | https://github.com/numactl/numactl |\n| libevent | Build \u0026 Runtime | BSD-3-Clause | https://github.com/libevent/libevent |\n| libecoli | Build \u0026 Runtime | BSD-3-Clause | https://git.sr.ht/~rjarry/libecoli |\n| libsmartcols | Build \u0026 Runtime | LGPL-2.1 | https://github.com/util-linux/util-linux/tree/master/libsmartcols |\n| cmocka | Build | Apache-2.0 | https://github.com/clibs/cmocka |\n| meson | Build | Apache-2.0 | https://github.com/mesonbuild/meson |\n| ninja | Build | Apache-2.0 | https://github.com/ninja-build/ninja |\n| go-md2man | Build | MIT | https://github.com/cpuguy83/go-md2man |\n| libasan | Dev | MIT+BSD | https://github.com/gcc-mirror/gcc/tree/master/libsanitizer |\n| clang-format | Dev | MIT+BSD | https://clang.llvm.org/docs/ClangFormat.html |\n\nOptional (compiled with `-Dfrr=enabled`):\n\n| Name | Type | License | Code |\n|------|------|---------|------|\n| FRR  | Build \u0026 Runtime | GPL-2.0-or-later | https://github.com/FRRouting/frr |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjarry%2Fgrout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frjarry%2Fgrout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frjarry%2Fgrout/lists"}