{"id":22220979,"url":"https://github.com/nokia/augustus","last_synced_at":"2025-07-27T16:30:54.780Z","repository":{"id":43129248,"uuid":"63856430","full_name":"nokia/Augustus","owner":"nokia","description":null,"archived":false,"fork":false,"pushed_at":"2020-08-03T15:09:45.000Z","size":69,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-14T13:07:11.124Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause-clear","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nokia.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":"2016-07-21T09:34:11.000Z","updated_at":"2024-04-14T13:07:11.125Z","dependencies_parsed_at":"2022-09-22T06:22:02.401Z","dependency_job_id":null,"html_url":"https://github.com/nokia/Augustus","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/nokia%2FAugustus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2FAugustus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2FAugustus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2FAugustus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/Augustus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817164,"owners_count":17824199,"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-12-02T23:11:18.208Z","updated_at":"2024-12-02T23:11:18.994Z","avatar_url":"https://github.com/nokia.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Augustus: DPDK content router\n\nREADME for the DPDK content router\n\n## Requirements\nTo use the DPDK content router you need a machine with:\n * Linux Ubuntu\n * Intel DPDK framework\n * A NIC supported by Intel DPDK\n\nAugustus has been successfully tested with:\n * Ubuntu 14.04 and Ubuntu 16.04 \n * dpdk-2.2.0 and dpdk-16.04 (the last two releases).\n\nHowever, when updating Ubuntu, notice that there are some issues with gcc 5 and the native dpdk config which were fixed post dpdk-2.2.0 \n(https://www.mail-archive.com/ubuntu-bugs@lists.ubuntu.com/msg4943360.html).\n\n## Set up\nTo start, download and install the DPDK library following the DPDK instructions for compiling the target 'x86_64-native-linuxapp-gcc'. \nBefore compiling and running Augustus: \n * insert igb_uio module\n * enable huge pages\n * attach cards to the igb_uio module.\n\nAll these steps can be performed by running the following script, provided by Intel DPDK: `\u003cDPDK_DIR\u003e/tools/setup.sh`\nwhere `\u003cDPDK_DIR\u003e` is the directory where you downloaded Intel DPDK.\nPlease refer to the Intel DPDK manual for further information.\n\n\n## Build\nTo build the DPDK software router, on machines where DPDK is installed, go to the folder where this README file is located \nand run the following commands:\n\n    export export RTE_TARGET=x86_64-native-linuxapp-gcc\n    export export RTE_SDK=\u003cDPDK_DIR\u003e\n\nreplacing `\u003cDPDK_DIR\u003e` with the path where DPDK is located.\n\nThen run:\n\n    make clean\n    make\n\nThese will build the Augustus DPDK content router. The executable file of the content router is located in the `build` directory.\nMake sure to always run `make clean` before `make`.\n\n## Run\nAfter building the content router you can run it with the following command\n\n    sudo build/dpdk-content-router -c COREMASK -n MEM_CHANNEL -- -p PORTMASK -m \"MAC1 MAC2\" [-P] \n    \n    Usage:\t[EAL options] -- Options\n\t\t\n\t\t[EAL options]: -c COREMASK -n MEM_CHANNEL\n\t\tOptions:\n\t\t\t-p PORTMASK:                 Hexadecimal bitmask of ports to configure\\n\"\n\t\t\t-m MAC0 [MAC1 .. MACN]:      list of MAC addresses associated to port0, port1, ..., portN (separated by a space)\\n\"\n\t\t\t-P                           Enable promiscuous mode\\n\"\n\t\t\t--no-numa                    Disable NUMA awareness\\n\"\n\t\t\t-h --help                    Show this help\\n\"\n\t\t\t-v, --version                Show version\\n\",\n    \n    \nExample with 2 ports, 3 cores:\n\n    sudo build/dpdk-content-router -c 0x7 -n 2 -- -p 0x3 -P -m \"5c:b9:01:88:f0:88 5c:b9:01:88:f0:89\"\n    \nAll arguments before the `--` sign are DPDK EAL arguments and those after are arguments specific for the DPDK content \nrouter.\n\nArguments:\n * `COREMASK` is the hexadecimal bitmask of the CPU cores to use in the application.\n * `MEM_CHANNEL` is the number of memory channels used by the DRAM banks. DPDK uses this information to align packet memory\n   buffer in such a way that contiguous packets are allocated in memory regions accessed by different channels. In such a way, \n   prefetching consecutive packets is faster cause different channels are used.\n * `PORTMASK` is the hexadecimal bitmask of enabled Ethernet ports.\n * `P`: if specified, enables promiscuous mode on NICs\n\n# Configuration\nMost of the configurations such as CS, FIB, PIT size, number of buckets, etc. are stored in `defaults.h`\nUse `config.h` to to override default parameters and re-build Augustus to apply the changes.\n\nTo modify FIB use build fib-ctrl. It sends an update command to Augustus from the specified address.\n\nUsage:\n\n\tfib_ctrl -a 'address' -c \"command\"\n\nwhere `command` is of the format `(ADD,CLR,DEL):prefix_name:port_id`\n\t \nExample:\n\n\tsudo build/fib-ctrl -a '127.0.0.1' -c \"ADD:a/b/c/d/e/f/:0\"\n\n## Debug and optimized mode\nThroughout the Augustus code there are some logging macros that print logging information to standard output for debugging \npurposes. These macros are useful when running Augustus with limited load for debugging purposes only. For high speed tests \nthey must be removed. This must be done by compiling the DPDK library with the proper debug level.\n\nTo do so, open the source tree of the DPDK library (the actual DPDK, not Augustus). Move to the config dir and in the \n`common_linuxapp` set `RTE_LOG_LEVEL` to 4 instead of the default 8. Rebuild the DPDK library and rebuild Augustus. That's it.\n\nA good advice is to keep on the target machine several copies of DPDK each compiled with different debug levels and configuration \nand change the value of the RTE_SDK environment variable each time a switch in configuration is required.\n\nA more elegant way but possibly more error-prone is to create a new defconfig file in the config folder for each desired \nconfiguration named \n`defconfig_MYTARGET` and then build DPDK each time specifying `MYTARGET` as value of the `RTE_TARGET` environment variable. In \nthis way there are separate copies only of the build files, not of the source as well, but may generate confusion.\n\nAlso to run the content router in DPDK, you may consider editing the Makefile to use the GCC compiler with the `-O0` argument,\nwhich produced optimized binary code.\n\n## Print and reset stats\nEach core keeps statistics for results collection. Variables storing statistics are local to each thread and, for performance \nreasons, there is no concurrent access control on them, not even atomic read/write operations. Statistics can be printed to \nstandard output or reset when there is no traffic being handled by the content router. This can be done by sending user-specific \nsignals to the content router process.\n\nTo print stats to standard output, send a USR1 signal to the router process. When the process is running, open another terminal \nand type:\n\n    sudo killall -SIGUSR1 dpdk-content-router\n\nThis command will print on the stdout stream attached to the content router, the per-core and cumulative statistics.\n\nTo reset statistics counter, send a USR2 signal instead:\n\n    sudo killall -SIGUSR2 dpdk-content-router \n\n## Build documentation\nEach function, macro, data structure and typedef is documented. Function documentation is present only in the prototype declaration \n(i.e., in header files). The documentation is written in Doxygen format and, using Doxygen, it is possible to build an API definition \nin HTML format. This can be done with the Makefile, by executing:\n\n    make doc\n    \nBefore building docs, be sure to have doxygen installed:\n\n    sudo apt-get install doxygen\n    \n## Caveats\nHere is a list of caveats to be aware of about the implementation of the Augustus DPDK content router.\n * No chaining on the FIB hash-table. Each bucket supports 7 entries. If you use a FIB that overflows a bucket, just create a hash\n   table with more buckets\n * No cryptographic signatures of Interest and Data packets\n * The FIB lookup is very simplistic: the lookup algorithms first checks if there is a match at `num_prefix`, then checks if match\n   at `num_prefix-1` and so forth.\n * If the FIB is modified while Interest packets are being processed, there might be inconsistent behavior as there is no synchronization\n   mechanism implemented to ensure correctness of concurrent lookup and update operations.\n * In order to exploit nic's RSS, name's hash is embedded in the ip destination address (In the future it can be embedded in the UDP port \n   and IP addresses used to identify the port)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Faugustus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Faugustus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Faugustus/lists"}