{"id":14128171,"url":"https://github.com/emmericp/MoonGen","last_synced_at":"2025-08-03T22:32:28.634Z","repository":{"id":21218778,"uuid":"24532417","full_name":"emmericp/MoonGen","owner":"emmericp","description":"MoonGen is a fully scriptable high-speed packet generator built on DPDK and LuaJIT. It can saturate a 10 Gbit/s connection with 64 byte packets on a single CPU core while executing user-provided Lua scripts for each packet. Multi-core support allows for even higher rates. It also features precise and accurate timestamping and rate control.","archived":false,"fork":false,"pushed_at":"2023-11-23T12:59:13.000Z","size":21116,"stargazers_count":1049,"open_issues_count":80,"forks_count":235,"subscribers_count":66,"default_branch":"master","last_synced_at":"2024-11-30T02:48:46.086Z","etag":null,"topics":["dpdk","lua","packet-generator"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emmericp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-27T13:28:04.000Z","updated_at":"2024-11-29T15:37:05.000Z","dependencies_parsed_at":"2022-07-27T02:02:04.403Z","dependency_job_id":null,"html_url":"https://github.com/emmericp/MoonGen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2FMoonGen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2FMoonGen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2FMoonGen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2FMoonGen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emmericp","download_url":"https://codeload.github.com/emmericp/MoonGen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228571844,"owners_count":17938772,"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":["dpdk","lua","packet-generator"],"created_at":"2024-08-15T16:01:21.783Z","updated_at":"2024-12-07T06:30:58.320Z","avatar_url":"https://github.com/emmericp.png","language":"Lua","funding_links":[],"categories":["Lua","Resources"],"sub_categories":["Miscellaneous"],"readme":"### TL;DR\nLuaJIT + DPDK = fast and flexible packet generator for 10 Gbit/s Ethernet and beyond.\nMoonGen uses hardware features for accurate and precise latency measurements and rate control.\n\nSkip to [Installation](#installation) and [Usage](#using-moongen) if you just want to send some packets.\n\nDetailed evaluation: [Paper](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015.pdf) (IMC 2015, [BibTeX entry](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015-BibTeX.txt))\n\n# MoonGen Packet Generator\n\nMoonGen is a scriptable high-speed packet generator built on [libmoon](https://github.com/libmoon/libmoon).\nThe whole load generator is controlled by a Lua script: all packets that are sent are crafted by a user-provided script.\nThanks to the incredibly fast LuaJIT VM and the packet processing library DPDK, it can saturate a 10 Gbit/s Ethernet link with 64 Byte packets while using only a single CPU core.\nMoonGen can achieve this rate even if each packet is modified by a Lua script. It does not rely on tricks like replaying the same buffer.\n\nMoonGen can also receive packets, e.g., to check which packets are dropped by a\nsystem under test. As the reception is also fully under control of the user's\nLua script, it can be used to implement advanced test scripts. E.g. one can use\ntwo instances of MoonGen that establish a connection with each other. This\nsetup can be used to benchmark middle-boxes like firewalls.\n\nMoonGen focuses on four main points:\n\n* High performance and multi-core scaling: \u003e 20 million packets per second per CPU core\n* Flexibility: Each packet is crafted in real time by a user-provided Lua script\n* Precise and accurate timestamping: Timestamping with sub-microsecond precision on commodity hardware\n* Precise and accurate rate control: Reliable generation of arbitrary traffic patterns on commodity hardware\n\nYou can have a look at [our slides from a talk](https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/Slides.pdf) or read [our paper](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015.pdf) [1] for a more detailed discussion of MoonGen's internals.\n\n\n# Architecture\n\nMoonGen is built on [libmoon](https://github.com/libmoon/libmoon), a Lua wrapper for DPDK.\n\n\nUsers can write custom scripts for their experiments. It is recommended to make use of hard-coded setup-specific constants in your scripts. The script is the configuration, it is beside the point to write a complicated configuration interface for a script.\nAlternatively, there is a simplified (and less powerful) command-line interface available for quick tests.\n\nThe following diagram shows the architecture and how multi-core support is handled.\n\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Architecture\" src=\"https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture.png\" srcset=\"https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture.png 1x, https://raw.githubusercontent.com/emmericp/MoonGen/master/doc/img/moongen-architecture@2x.png 2x\"/\u003e\n\u003c/p\u003e\n\nExecution begins in the *master task* that must be defined in the userscript.\nThis task configures queues and filters on the used NICs and then starts one or more *slave tasks*.\n\nNote that Lua does not have any native support for multi-threading.\nMoonGen therefore starts a new and completely independent LuaJIT VM for each thread.\nThe new VMs receive serialized arguments: the function to execute and arguments like the queue to send packets from.\nThreads only share state through the underlying library.\n\nThe example script [quality-of-service-test.lua](https://github.com/emmericp/MoonGen/blob/master/examples/quality-of-service-test.lua?ts=4) shows how this threading model can be used to implement a typical load generation task.\nIt implements a QoS test by sending two different types of packets and measures their throughput and latency. It does so by starting two packet generation tasks: one for the background traffic and one for the prioritized traffic.\nA third task is used to categorize and count the incoming packets.\n\n\n# Hardware Timestamping\nIntel commodity NICs from the igb, ixgbe, and i40e families support timestamping in hardware for both transmitted and received packets.\nThe NICs implement this to support the IEEE 1588 PTP protocol, but this feature can be used to timestamp almost arbitrary UDP packets.\nMoonGen achieves a precision and accuracy of below 100 ns.\n\nUse ``test-timestamping-capabilities.lua`` in ``examples/timestamping-tests`` to test your NIC's timestamping capabilities.\n\nA more detailed evaluation can be found in [our paper](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015.pdf) [1].\n\n\n# Installation\n\n1. Install the dependencies (see below)\n2. ./build.sh\n3. sudo ./bind-interfaces.sh\n4. sudo ./setup-hugetlbfs.sh\n5. sudo ./build/MoonGen examples/l3-load-latency.lua 0 1\n\nNote: You need to bind NICs to DPDK to use them. `bind-interfaces.sh` does this for all unused NICs (no routing table entry in the system).\nUse `libmoon/deps/dpdk/usertools/dpdk-devbind.py ` to manage NICs manually.  \nIf you have secure boot enabled (by default in ubuntu 20.04 LTS), you will get a permission denied error on the insmod command of the kernel module when running `sudo ./bind-interfaces.sh`. You can temporarely disable secure boot on ubuntu with the steps described [here](https://wiki.ubuntu.com/UEFI/SecureBoot/DKMS) to permit the unsigned driver to load.\n\n\n## Dependencies\n* gcc \u003e= 4.8\n* make\n* cmake\n* libnuma-dev\n* kernel headers (for the DPDK igb-uio driver)\n* lspci (for `dpdk-devbind.py`)\n* [additional dependencies](https://github.com/libmoon/libmoon/blob/master/install-mlx.md) for Mellanox NICs\n\nRun the following command to install these on Debian/Ubuntu:\n\n```\nsudo apt-get install -y build-essential cmake linux-headers-`uname -r` pciutils libnuma-dev\n```\n\n# Using MoonGen\n\nYou have to write a simple script for your use case.\nThe example [l3-load-latency.lua](https://github.com/emmericp/MoonGen/blob/master/examples/l3-load-latency.lua) is a good starting point as it makes use of a lot of different features of MoonGen.\n\n\n## Simple CLI\nThe simplest way to get started is using the [simple command line interface](https://github.com/emmericp/MoonGen/blob/master/interface/README.md). For example:\n\n    sudo ./moongen-simple start load-latency:0:1:rate=10Mp/s,time=3m\n    \nThis sends packets with a rate of 10 million packets per second for 3 minutes from port 0 to port 1 and outputs the latency at the end of the run. Available DPDK ports are printed on startup.\n\n`load-latency` is a *flow* that is defined in `flows/examples.lua`.\nHave a look at this file to see how flows are defined. You can add your own flow definitions to any file in the `flows` subdirectory.\nRun `./moongen-simple list` to see all available flows.\nIt's also helpful to run a flow with `debug` instead of `start` to print packet contents instead of sending them.\n\nSee the [documentation for the simple CLI](https://github.com/emmericp/MoonGen/blob/master/interface/README.md) for more details and instructions.\nYou can also check the `help` command or run any subcommand with `-h`.\n\nThis API comes with a small performance overhead compared to the full API.\nYou can enable multi-threading on a single port by specifying the same port multiple times separated with commas.\n\n## Using the full API\nUsing the full API gives you complete control over MoonGen, this is recommended for more complex test setups.\nThis means that you'll have to write a custom script to use MoonGen in this mode.\n\nMoonGen comes with examples in the examples folder which can be used as a basis for custom scripts.\nReading the example script [l3-load-latency.lua](https://github.com/emmericp/MoonGen/blob/master/examples/l3-load-latency.lua?ts=4) or [quality-of-service-test.lua](https://github.com/emmericp/MoonGen/blob/master/examples/quality-of-service-test.lua?ts=4) is a good way to learn more about our scripting API as these scripts uses most features of MoonGen.\n\nYou can run a script like this:\n\n    ./build/MoonGen ./examples/l3-load-latency.lua 0 1\n\nThe two command line arguments are the transmission and reception ports, see script (or run with `-h`) for CLI parameter handling.\nMoonGen prints all available ports on startup, so adjust this if necessary.\n\nYou can also check out the examples of the [libmoon](https://github.com/libmoon/libmoon) project.\nAll libmoon scripts are also valid MoonGen scripts as MoonGen extends libmoon.\n\n# Frequently Asked Questions\n\n### Which NICs do you support?\nBasic functionality is available on all [NICs supported by DPDK](http://dpdk.org/doc/nics).\nHardware timestamping is currently supported and tested on Intel igb, ixgbe, and i40e NICs. However, support for specific features vary between models.\nUse ``test-timestamping-capabilities.lua`` in ``examples/timestamping-tests`` to find out what your NIC supports.\nHardware rate control is supported and tested on Intel ixgbe and i40e NICs.\n\n### What's the difference between MoonGen and libmoon?\nMoonGen builds on [libmoon](https://github.com/libmoon/libmoon) by extending it with features for packet generators such as software rate control and software timestamping.\n\nIf you want to write a packet generator or test your application: use MoonGen.\nIf you want to prototype DPDK applications: use [libmoon](https://github.com/libmoon/libmoon).\n\n\n# References\n[1] Paul Emmerich, Sebastian Gallenmüller, Daniel Raumer, Florian Wohlfart, and Georg Carle. MoonGen: A Scriptable High-Speed Packet Generator, 2015. IMC 2015. [Available online](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015.pdf).  [BibTeX](http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/MoonGen_IMC2015-BibTeX.txt).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmericp%2FMoonGen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femmericp%2FMoonGen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmericp%2FMoonGen/lists"}