{"id":28446601,"url":"https://github.com/parttimenerd/hello-ebpf","last_synced_at":"2025-06-30T01:31:47.818Z","repository":{"id":211864622,"uuid":"726230927","full_name":"parttimenerd/hello-ebpf","owner":"parttimenerd","description":"Hello eBPF world! Hello Java world! Let's discover eBPF together and write Java user-land library along the way.","archived":false,"fork":false,"pushed_at":"2025-05-13T12:59:45.000Z","size":3871,"stargazers_count":154,"open_issues_count":5,"forks_count":17,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-06T11:07:33.322Z","etag":null,"topics":["ebpf","java","panama"],"latest_commit_sha":null,"homepage":"https://mostlynerdless.de/blog/tag/ebpf/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parttimenerd.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-01T20:24:28.000Z","updated_at":"2025-06-03T11:56:09.000Z","dependencies_parsed_at":"2024-03-11T16:43:10.948Z","dependency_job_id":"b0d81cbf-e2da-4ead-8c82-8dc42e1fd702","html_url":"https://github.com/parttimenerd/hello-ebpf","commit_stats":null,"previous_names":["parttimenerd/hello-ebpf"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/parttimenerd/hello-ebpf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parttimenerd%2Fhello-ebpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parttimenerd%2Fhello-ebpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parttimenerd%2Fhello-ebpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parttimenerd%2Fhello-ebpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parttimenerd","download_url":"https://codeload.github.com/parttimenerd/hello-ebpf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parttimenerd%2Fhello-ebpf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262693204,"owners_count":23349691,"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":["ebpf","java","panama"],"created_at":"2025-06-06T11:07:33.086Z","updated_at":"2025-06-30T01:31:47.802Z","avatar_url":"https://github.com/parttimenerd.png","language":"Java","funding_links":[],"categories":["网络编程"],"sub_categories":["Spring Cloud框架"],"readme":"Hello eBPF\n==========\n\nThere are [user land libraries](https://ebpf.io/what-is-ebpf/#development-toolchains) for [eBPF](https://ebpf.io) that allow you to\nwrite eBPF applications in C++, Rust, Go, Python and even\nLua. But there are none for Java, which is a pity.\nSo... I decided to write my own, which allows you to write\neBPF programs directly in Java.\n\nThis is still in the early stages, but you can already use it for developing small tools\nand more coming in the future.\n\n![Overview images](img/overview.svg)\n\n_Based on the overview from [ebpf.io](https://ebpf.io/what-is-ebpf/), \nduke image from [OpenJDK](https://wiki.openjdk.org/display/duke/Gallery)._\n\nLet's discover eBPF together. Join me on the journey and learn a lot about eBPF and Java along the way.\n\nExample\n-------\nConsider for a brief moment that you want to test how your server application behaves when every third incoming\nnetwork packet is dropped. We can write a simple eBPF program to do this:\n\n```java\n@BPF(license = \"GPL\")\npublic abstract class XDPDropEveryThirdPacket extends BPFProgram implements XDPHook {\n\n  final GlobalVariable\u003c@Unsigned Integer\u003e count = new GlobalVariable\u003c\u003e(0);\n\n  @BPFFunction\n  public boolean shouldDrop() {\n    return count.get() % 3 == 1;\n  }\n\n  @Override // runs directly in the kernel on every incoming packet\n  public xdp_action xdpHandlePacket(Ptr\u003cxdp_md\u003e ctx) {\n    // this code is actually compiled to the C code that is executed in the kernel\n    count.set(count.get() + 1);\n    return shouldDrop() ? xdp_action.XDP_DROP : xdp_action.XDP_PASS;\n  }\n\n  // runs in user land\n  public static void main(String[] args) throws InterruptedException {\n    try (XDPDropEveryThirdPacket program = BPFProgram.load(XDPDropEveryThirdPacket.class)) {\n      // attach the xdpHandlePacket method to the network interface\n      program.xdpAttach(XDPUtil.getNetworkInterfaceIndex());\n      // print the current packet count in a loop\n      while (true) {\n        System.out.println(\"Packet count \" + program.count.get());\n        Thread.sleep(1000);\n      }\n    }\n  }\n}\n```\n\nYou can find this example as [XDPDropEveryThirdPacket.java](bpf-samples/src/main/java/me/bechberger/ebpf/samples/XDPDropEveryThirdPacket.java).\n\nGoals\n-----\nProvide a library (and documentation) for Java developers to explore eBPF and\nwrite their own eBPF programs, like firewalls, directly in Java, using the [libbpf](https://libbpf.readthedocs.io/en/latest/)\nunder the hood.\n\nThe goal is neither to replace existing eBPF libraries nor to provide a higher abstractions.\n\nPrerequisites\n-------------\n\nThese might change in the future, but for now, you need the following:\n\nEither a Linux machine with the following:\n\n- Linux 64-bit (or a VM)\n- Java 22 or later\n- libbpf and bpf-tool\n  - e.g. `apt install libbpf-dev linux-tools-common linux-tools-$(uname -r)` on Ubuntu\n- root privileges (for executing the eBPF programs)\n\n- On Mac OS, you can use the [Lima VM](https://lima-vm.io/) (or use the `hello-ebpf.yaml` file as a guide to install the prerequisites):\n\n```sh\nlimactl start hello-ebpf.yaml --mount-writable\nlimactl shell hello-ebpf sudo bin/install.sh\nlimactl shell hello-ebpf\n\n# You'll need to be root for most of the examples\nsudo -s PATH=$PATH\n```\n\nThe scheduler examples require a 6.12+ kernel (install on ubuntu via the [mainline](https://github.com/bkw777/mainline) tool)\nor a patched 6.11 kernel with the scheduler extensions, you can get it from\n[here](https://launchpad.net/~arighi/+archive/ubuntu/sched-ext-unstable).\nYou might also be able to run [CachyOS](https://cachyos.org/) and install a patched kernel from there.\n\nBlog Posts\n----------\nPosts covering the development of this project:\n\n- Dec 01, 2023: [Finding all used Classes, Methods, and Functions of a Python Module](https://mostlynerdless.de/blog/2023/12/01/finding-all-used-classes-methods-and-functions-of-a-python-module/)\n- Dec 11, 2023: [From C to Java Code using Panama](https://mostlynerdless.de/blog/2023/12/11/from-c-to-java-code-using-panama/)\n- Jan 01, 2024: [Hello eBPF: Developing eBPF Apps in Java (1)](https://mostlynerdless.de/blog/2023/12/31/hello-ebpf-developing-ebpf-apps-in-java-1/)\n- Jan 12, 2024: [Hello eBPF: Recording data in basic eBPF maps (2)](https://mostlynerdless.de/blog/2024/01/12/hello-ebpf-recording-data-in-basic-ebpf-maps-2/)\n- Jan 29, 2024: [Hello eBPF: Recording data in perf event buffers (3)](https://mostlynerdless.de/blog/2024/01/29/hello-ebpf-recording-data-in-event-buffers-3/)\n- Feb 12, 2024: [Hello eBPF: Tail calls and your first eBPF application (4)](https://mostlynerdless.de/blog/2024/02/12/hello-ebpf-tail-calls-and-your-first-ebpf-application-4/)\n- Feb 26, 2024: [Hello eBPF: First steps with libbpf (5)](https://mostlynerdless.de/blog/2024/02/26/hello-ebpf-first-steps-with-libbpf-5/)\n- Mar 12, 2024: [Hello eBPF: Ring buffers in libbpf (6)](https://mostlynerdless.de/blog/2024/03/12/hello-ebpf-ring-buffers-in-libbpf-6/)\n- Mar 22, 2024: [Hello eBPF: Auto Layouting Structs (7)](https://mostlynerdless.de/blog/2024/03/22/hello-ebpf-auto-layouting-structs-7/)\n- Apr 09, 2024: [Hello eBPF: Generating C Code (8)](https://mostlynerdless.de/blog/2024/04/09/hello-ebpf-generating-c-code-8/)\n- Apr 22, 2024: [Hello eBPF: XDP-based Packet Filter (9)](https://mostlynerdless.de/blog/2024/04/22/hello-ebpf-xdp-based-packet-filter-9/)\n- May 21, 2024: [Hello eBPF: Global Variables (10)](https://mostlynerdless.de/blog/2024/05/21/hello-ebpf-global-variables-10/)\n- Jul 02, 2024: [Hello eBPF: BPF Type Format and 13 Thousand Generated Java Classes (11)](https://mostlynerdless.de/blog/2024/07/02/hello-ebpf-bpf-type-format-and-13-thousand-generated-java-classes-11/)\n- Jul 30, 2024: [Hello eBPF: Write your eBPF application in Pure Java (12)](https://mostlynerdless.de/blog/2024/07/30/hello-ebpf-write-your-ebpf-application-in-pure-java-12/)\n- Aug 13, 2024: [Hello eBPF: A Packet Logger in Pure Java using TC and XDP Hooks (13)](https://mostlynerdless.de/blog/2024/08/13/hello-ebpf-a-packet-logger-in-pure-java-using-tc-and-xdp-hooks-13/)\n- Aug 27, 2024: [Hello eBPF: Building a Lightning Fast Firewall with Java \u0026 eBPF (14)](https://mostlynerdless.de/blog/2024/08/27/hello-ebpf-building-a-lightning-fast-firewall-with-java-ebpf-14/)\n- Sep 10, 2024: [Hello eBPF: Collection of Resources for eBPF (14.5)](https://mostlynerdless.de/blog/2024/09/10/hello-ebpf-collection-of-resources-for-ebpf-14-5/)\n- Sep 10, 2024: [Hello eBPF: Writing a Linux scheduler in Java with eBPF (15)](https://mostlynerdless.de/blog/2024/09/10/hello-ebpf-writing-a-linux-scheduler-in-java-with-ebpf-15/)\n- Dec 03, 2024: [Hello eBPF: Control task scheduling with a custom scheduler written in Java (16)](https://mostlynerdless.de/blog/2024/12/03/hello-ebpf-control-task-scheduling-with-a-custom-scheduler-written-in-java-16/)\n\nExamples\n--------\n\nI wrote a few samples that showcase the usage of the library in the [bpf-samples](bpf-samples) module,\nyou can use them as a starting point for your own eBPF programs.\n\n| Inspiration | Name and Java Class                                                                                                        | Description                                                                |\n|-------------|----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|\n|             | [HelloWorld](bpf-samples/src/main/java/me/bechberger/ebpf/samples/HelloWorld.java)                                         | A simple hello world example                                               |\n|             | [LogOpenAt2Call](bpf-samples/src/main/java/me/bechberger/ebpf/samples/LogOpenAt2Calls.java)                                | Logs all openat2 calls                                                     |\n| Ansil H     | [RingSample](bpf-samples/src/main/java/me/bechberger/ebpf/samples/RingSample.java)                                         | Record openat2 calls in a ring buffer                                      |\n|             | [HashMapSample](bpf-samples/src/main/java/me/bechberger/ebpf/samples/HashMapSample.java)                                   | Record openat2 calls in a hash map                                         |\n|             | [XDPDropEveryThirdPacket](bpf-samples/src/main/java/me/bechberger/ebpf/samples/XDPDropEveryThirdPacket.java)               | Use XDP to block every third incoming packet                               |\n| sematext    | [XDPPacketFilter](bpf-samples/src/main/java/me/bechberger/ebpf/samples/XDPPacketFilter.java)                               | Use XDP to block incoming packages from specific URLs in Java              |\n| sematext    | [XDPPacketFilter2](bpf-samples/src/main/java/me/bechberger/ebpf/samples/XDPPacketFilter2.java)                             | The previous example but with the eBPF program as C code                   |\n|             | [TCDropEveryThirdOutgoingPacket](bpf-samples/src/main/java/me/bechberger/ebpf/samples/TCDropEveryThirdOutgoingPacket.java) | Implement a Traffic Control to block every third outgoing packet at random |\n|             | [PacketLogger](bpf-samples/src/main/java/me/bechberger/ebpf/samples/PacketLogger.java)                                     | TC and XDP based packet logger, capturing incoming and outgoing packets    |\n| nfil.dev    | [CGroupBlockHTTPEgress](bpf-samples/src/main/java/me/bechberger/ebpf/samples/CGroupBlockHTTPEgress.java)                   | Block all outgoing HTTP packets using cgroups                              |\n|             | [demo.ForbiddenFile](bpf-samples/src/main/java/me/bechberger/ebpf/samples/demo/ForbiddenFile.java)                         | Block access to a specific file via openat2                                |\n|             | [Firewall](bpf-samples/src/main/java/me/bechberger/ebpf/samples/Firewall.java)                                             | A simple firewall that blocks all incoming packets                         |\n|             | [FirewallSpring](bpf-samples/src/main/java/me/bechberger/ebpf/samples/FirewallSpring.java)                                 | A spring boot based web front-end for the Firewall                         |\n|             | [MinimalScheduler](bpf-samples/src/main/java/me/bechberger/ebpf/samples/MinimalScheduler.java)                             | A minimal Linux scheduler                                                  | \n\nRunning the Examples\n--------------------\nBe sure to run the following in a shell with root privileges that uses JDK 22:\n\n```shell\n# in the project directory\n./run.sh EXAMPLE_NAME\n\n# list all examples\n./run.sh\n```\n\nThis allows you to easily run the example from above:\n\n```\n\u003e ./build.sh\n\u003e  ./run.sh XDPDropEveryThirdPacket\nPacket count 0\nPacket count 2\nPacket count 3\nPacket count 5\nPacket count 6\nPacket count 8\nPacket count 9\nPacket count 11\n```\n\nYou can use the `debug.sh` to run an example with a debugger port open at port 5005.\n\nBuild\n-----\nTo build the project, make sure you have all prerequisites installed, then just run:\n\n```shell\n./build.sh\n```\n\nUsage as a library\n------------------\nThe library is available as a maven package:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eme.bechberger\u003c/groupId\u003e\n    \u003cartifactId\u003ebpf\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.1-scx-enabled-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYou might have to add the https://s01.oss.sonatype.org/content/repositories/releases/ repo:\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003esnapshots\u003c/id\u003e\n        \u003curl\u003ehttps://s01.oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n        \u003creleases\u003e\n            \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/releases\u003e\n        \u003csnapshots\u003e\n            \u003cenabled\u003etrue\u003c/enabled\u003e\n        \u003c/snapshots\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eYou have to copy the .mvn/jvm.config file and add the annotation processor to your project.\u003c/summary\u003e\nTo properly use hello-ebpf as a library, you have to allow the maven compiler to access all the required internal\nAPIs. You can do this by copying the `.mvn/jvm.config` file from this repository to your project.\n\nFurthermore, you have to add the annotation processor to your project:\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n  \u003cartifactId\u003emaven-compiler-plugin\u003c/artifactId\u003e\n  \u003cversion\u003e3.8.0\u003c/version\u003e\n  \u003cconfiguration\u003e\n    \u003cannotationProcessors\u003e\n      \u003cannotationProcessor\u003eme.bechberger.ebpf.bpf.processor.Processor\u003c/annotationProcessor\u003e\n    \u003c/annotationProcessors\u003e\n    \u003ccompilerArgs\u003e\n      \u003carg\u003e-Xplugin:BPFCompilerPlugin\u003c/arg\u003e\n    \u003c/compilerArgs\u003e\n  \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\n\u003c/details\u003e\n\nPlans\n-----\n\nA look ahead into the future, so you know what to expect:\n\n- Implement more features related to libbpf and eBPF\n  - cgroups support\n- More documentation\n- Support for macros\n\nThese plans might change, but I'll try to keep this up to date.\nI'm open to suggestions, contributions, and ideas.\n\nTesting\n-------\nTests are run using [JUnit 5](https://junit.org/junit5/) and `./mvnw test`.\nYou can either run\n\n```shell\n./mvnw test -Dmaven.test.skip=false\n```\n\nor you can run the tests in a container using `testutil/bin/java`: \n\n```shell\n./mvnw test -Djvm=testutil/bin/java -Dmaven.test.skip=false\n```\n\nThis requires [virtme](https://github.com/ezequielgarcia/virtme) (`apt install virtme`), python 3, and docker to be installed.\nYou can run custom commands in the container using `testutil/run-in-container.sh`.\nRead more in the [testutil/README.md](testutil/README.md).\n\nI'm unable to get it running in the CI, so I'm currently running the tests locally.\n\nContributing\n------------\nContributions are welcome; just open an \n[issue](https://github.com/parttimenerd/hello-ebpf/issues/new) or a \n[pull request](https://github.com/parttimenerd/hello-ebpf/pulls).\nDiscussions take place in the [discussions](https://github.com/parttimenerd/hello-ebpf/discussions)\nsection of the GitHub repository.\n\nI'm happy to include more example programs, API documentation, or helper methods,\nas well as links to repositories and projects that use this library.\n\nLicense\n-------\nApache 2.0, Copyright 2023 SAP SE or an SAP affiliate company, Johannes Bechberger and contributors\n\n_This is a side project. The amount of time I can invest might vary over time._","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparttimenerd%2Fhello-ebpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparttimenerd%2Fhello-ebpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparttimenerd%2Fhello-ebpf/lists"}