{"id":13813199,"url":"https://github.com/eunomia-bpf/bpftime","last_synced_at":"2025-05-14T21:10:36.840Z","repository":{"id":196325396,"uuid":"676866666","full_name":"eunomia-bpf/bpftime","owner":"eunomia-bpf","description":"Userspace eBPF runtime for Observability, Network \u0026 General Extensions Framework","archived":false,"fork":false,"pushed_at":"2025-04-10T17:47:52.000Z","size":15976,"stargazers_count":965,"open_issues_count":75,"forks_count":88,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-04-13T06:19:52.565Z","etag":null,"topics":["ebpf","instrumentation","jit","llvm","runtime","syscall-tracing","uprobes","userspace"],"latest_commit_sha":null,"homepage":"https://eunomia.dev/bpftime/","language":"C++","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/eunomia-bpf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["yunwei37","Officeyutong"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2023-08-10T07:36:11.000Z","updated_at":"2025-04-12T13:38:28.000Z","dependencies_parsed_at":"2023-09-24T13:31:22.149Z","dependency_job_id":"527735ea-90c7-4a4b-9ce2-33f2d0514a1f","html_url":"https://github.com/eunomia-bpf/bpftime","commit_stats":{"total_commits":218,"total_committers":22,"mean_commits":9.909090909090908,"dds":0.5688073394495412,"last_synced_commit":"3f6724b4e06ee24a61f54ed7220fda8110c18349"},"previous_names":["eunomia-bpf/bpftime"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fbpftime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fbpftime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fbpftime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fbpftime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eunomia-bpf","download_url":"https://codeload.github.com/eunomia-bpf/bpftime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248760185,"owners_count":21157302,"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","instrumentation","jit","llvm","runtime","syscall-tracing","uprobes","userspace"],"created_at":"2024-08-04T04:01:07.054Z","updated_at":"2025-04-13T18:30:07.186Z","avatar_url":"https://github.com/eunomia-bpf.png","language":"C++","funding_links":["https://github.com/sponsors/yunwei37","https://github.com/sponsors/Officeyutong"],"categories":["C++"],"sub_categories":[],"readme":"# bpftime: Userspace eBPF runtime for Observability, Network \u0026 General extensions Framework\n\n[![Build and Test VM](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-vm.yml/badge.svg)](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-vm.yml)\n[![Build and test runtime](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-runtime.yml/badge.svg)](https://github.com/eunomia-bpf/bpftime/actions/workflows/test-runtime.yml)\n[![DOI](https://zenodo.org/badge/676866666.svg)](https://doi.org/10.48550/arXiv.2311.07923)\n\n`bpftime` is a High-Performance userspace eBPF runtime and General Extension Framework designed for userspace. It enables faster Uprobe, USDT, Syscall hooks, XDP, and more event sources by bypassing the kernel and utilizing an optimized compiler like `LLVM`.\n\n📦 [Key Features](#key-features) \\\n🔨 [Quick Start](#quick-start) \\\n🔌 [Examples \u0026 Use Cases](#examples--use-cases) \\\n⌨️ [Linux Plumbers 23 talk](https://lpc.events/event/17/contributions/1639/) \\\n📖 [Slides](https://eunomia.dev/bpftime/documents/userspace-ebpf-bpftime-lpc.pdf) \\\n📚 [Arxiv preprint](https://arxiv.org/abs/2311.07923)\n\n[**Checkout our documents in eunomia.dev!**](https://eunomia.dev/bpftime/)\n\nbpftime is not `userspace eBPF VM`, it's a userspace runtime framework includes everything to run eBPF in userspace: `loader`, `verifier`, `helpers`, `maps`, `ufunc` and multiple `events` such as Observability, Network, Policy or Access Control. It has multiple VM backend options support. For eBPF VM only, please see [llvmbpf](https://github.com/eunomia-bpf/llvmbpf).\n\n\u003e ⚠️ **Note**: `bpftime` is currently under active development and refactoring towards v2. It may contain bugs or unstable API. Please use it with caution. For more details, check our [roadmap](#roadmap). We'd love to hear your feedback and suggestions! Feel free to open an issue or [Contact us](#contact-and-citations).\n\n## Why bpftime? What's the design Goal?\n\n- **Performance Gains**: Achieve better performance by `bypassing the kernel` (e.g., via `Userspace DBI` or `Network Drivers`), with more configurable, optimized and more arch supported JIT/AOT options like `LLVM`, while maintaining compatibility with Linux kernel eBPF.\n- **Cross-Platform Compatibility**: Enables `eBPF functionality and large ecosystem` where kernel eBPF is unavailable, such as on older or alternative operating systems, or where kernel-level permissions are restricted, without changing your tool.\n- **Flexible and General Extension Language \u0026 Runtime for Innovation**: eBPF is designed for innovation, evolving into a General Extension Language \u0026 Runtime in production that supports very diverse use cases. `bpftime`'s modular design allows easy integration as a library for adding new events and program types without touching kernel. Wishing it could enable rapid prototyping and exploration of new features!\n\n## Key Features\n\n- **Dynamic Binary rewriting**: Run eBPF programs in userspace, attaching them to `Uprobes` and `Syscall tracepoints`: **No manual instrumentation or restart required!**. It can `trace` or `change` the execution of a function, `hook` or `filter` all syscalls of a process safely, and efficiently with an eBPF userspace runtime. Can inject eBPF runtime into any running process without the need for a restart or manual recompilation.\n- **Performance**: Experience up to a `10x` speedup in Uprobe overhead compared to kernel uprobe and uretprobe. Read/Write userspace memory is also faster than kernel eBPF.\n- **Interprocess eBPF Maps**: Implement userspace `eBPF maps` in shared userspace memory for summary aggregation or control plane communication.\n- **Compatibility**: use `existing eBPF toolchains` like clang, libbpf and bpftrace to develop userspace eBPF application without any modifications. Supporting CO-RE via BTF, and offering userspace `ufunc` access.\n- **Multi JIT Support**: Support [llvmbpf](https://github.com/eunomia-bpf/llvmbpf), a high-speed `JIT/AOT` compiler powered by LLVM, or using `ubpf JIT` and INTERPRETER. The vm can be built as `a standalone library` like ubpf.\n- **Run with kernel eBPF**: Can load userspace eBPF from kernel, and using kernel eBPF maps to cooperate with kernel eBPF programs like kprobes and network filters.\n- **Integrate with AF_XDP or DPDK**: Run your `XDP` network applications with better performance in userspace just like in kernel!(experimental)\n\n## Components\n\n- [`vm`](https://github.com/eunomia-bpf/bpftime/tree/master/vm): The eBPF VM and JIT compiler for bpftime, you can choose from [bpftime LLVM JIT/AOT compiler](https://github.com/eunomia-bpf/llvmbpf) and [ubpf](https://github.com/iovisor/ubpf). The [llvm-based vm](https://github.com/eunomia-bpf/llvmbpf) in bpftime can also be built as a standalone library and integrated into other projects, similar to ubpf.\n- [`runtime`](https://github.com/eunomia-bpf/bpftime/tree/master/runtime): The userspace runtime for eBPF, including the maps, helpers, ufuncs and other runtime safety features.\n- [`Attach events`](https://github.com/eunomia-bpf/bpftime/tree/master/attach): support attaching eBPF programs to `Uprobes`, `Syscall tracepoints`, `XDP` and other events with bpf_link, and also the driver event sources.\n- [`verifier`](https://github.com/eunomia-bpf/bpftime/tree/master/bpftime-verifier): Support using [PREVAIL](https://github.com/vbpf/ebpf-verifier) as userspace verifier, or using `Linux kernel verifier` for better results.\n- [`Loader`](https://github.com/eunomia-bpf/bpftime/tree/master/runtime/syscall-server): Includes a `LD_PRELOAD` loader library in userspace can work with current eBPF toolchain and library without involving any kernel, Another option is [daemon](https://github.com/eunomia-bpf/bpftime/tree/master/daemon) when Linux eBPF is available.\n\n## Quick Start: Uprobe\n\nWith `bpftime`, you can build eBPF applications using familiar tools like clang and libbpf, and execute them in userspace. For instance, the [`malloc`](https://github.com/eunomia-bpf/bpftime/tree/master/example/malloc) eBPF program traces malloc calls using uprobe and aggregates the counts using a hash map.\n\nYou can refer to [eunomia.dev/bpftime/documents/build-and-test](https://eunomia.dev/bpftime/documents/build-and-test) for how to build the project, or using the container images from [GitHub packages](https://github.com/eunomia-bpf/bpftime/pkgs/container/bpftime).\n\nTo get started, you can build and run a libbpf based eBPF program starts with `bpftime` cli:\n\n```console\nmake -C example/malloc # Build the eBPF program example\nexport PATH=$PATH:~/.bpftime/\nbpftime load ./example/malloc/malloc\n```\n\nIn another shell, Run the target program with eBPF inside:\n\n```console\n$ bpftime start ./example/malloc/victim\nHello malloc!\nmalloc called from pid 250215\ncontinue malloc...\nmalloc called from pid 250215\n```\n\nYou can also dynamically attach the eBPF program with a running process:\n\n```console\n$ ./example/malloc/victim \u0026 echo $! # The pid is 101771\n[1] 101771\n101771\ncontinue malloc...\ncontinue malloc...\n```\n\nAnd attach to it:\n\n```console\n$ sudo bpftime attach 101771 # You may need to run make install in root\nInject: \"/root/.bpftime/libbpftime-agent.so\"\nSuccessfully injected. ID: 1\n```\n\nYou can see the output from original program:\n\n```console\n$ bpftime load ./example/malloc/malloc\n...\n12:44:35 \n        pid=247299      malloc calls: 10\n        pid=247322      malloc calls: 10\n```\n\nAlternatively, you can also run our sample eBPF program directly in the kernel eBPF, to see the similar output. This can be an example of how bpftime can work compatibly with kernel eBPF.\n\n```console\n$ sudo example/malloc/malloc\n15:38:05\n        pid=30415       malloc calls: 1079\n        pid=30393       malloc calls: 203\n        pid=29882       malloc calls: 1076\n        pid=34809       malloc calls: 8\n```\n\nSee [eunomia.dev/bpftime/documents/usage](https://eunomia.dev/bpftime/documents/usage) for more details.\n\n## Examples \u0026 Use Cases\n\nFor more examples and details, please refer to [eunomia.dev/bpftime/documents/examples/](https://eunomia.dev/bpftime/documents/examples/) webpage.\n\nExamples including:\n\n- [Minimal examples](https://github.com/eunomia-bpf/bpftime/tree/master/example/minimal) of eBPF programs.\n- eBPF `Uprobe/USDT` tracing and `syscall tracing`:\n  - [sslsniff](https://github.com/eunomia-bpf/bpftime/tree/master/example/sslsniff) for trace SSL/TLS unencrypted data.\n  - [opensnoop](https://github.com/eunomia-bpf/bpftime/tree/master/example/opensnoop) for trace file open syscalls.\n  - More [bcc/libbpf-tools](https://github.com/eunomia-bpf/bpftime/tree/master/example/libbpf-tools).\n  - Run with [bpftrace](https://github.com/eunomia-bpf/bpftime/tree/master/example/bpftrace) commands or scripts.\n- [error injection](https://github.com/eunomia-bpf/bpftime/tree/master/example/error-inject): change function behavior with `bpf_override_return`.\n- Use the eBPF LLVM JIT/AOT vm as [a standalone library](https://github.com/eunomia-bpf/llvmbpf/tree/main/example).\n- Userspace [XDP with DPDK and AF_XDP](https://github.com/userspace-xdp/userspace-xdp)\n\n## In-Depth\n\n### **How it Works**\n\nbpftime supports two modes:\n\n#### Running in userspace only\n\nLeft: original kernel eBPF | Right: bpftime\n\n![How it works](https://eunomia.dev/bpftime/documents/bpftime.png)\n\nIn this mode, bpftime can run eBPF programs in userspace without kernel, so it can be ported into low version of Linux or event other systems, and running without root permissions. It relies on a [userspace verifier](https://github.com/vbpf/ebpf-verifier) to ensure the safety of eBPF programs.\n\n#### Run with kernel eBPF\n\n![documents/bpftime-kernel.png](https://eunomia.dev/bpftime/documents/bpftime-kernel.png)\n\nIn this mode, bpftime can run together with kernel eBPF. It can load eBPF programs from kernel, and using kernel eBPF maps to cooperate with kernel eBPF programs like kprobes and network filters.\n\n#### Instrumentation implementation\n\nCurrent hook implementation is based on binary rewriting and the underly technique is inspired by:\n\n- Userspace function hook: [frida-gum](https://github.com/frida/frida-gum)\n- Syscall hooks: [zpoline](https://www.usenix.org/conference/atc23/presentation/yasukata) and [pmem/syscall_intercept](https://github.com/pmem/syscall_intercept).\n\nThe hook can be easily replaced with other DBI methods or frameworks, or add more hook mechanisms in the future.\n\nSee our draft arxiv paper [bpftime: userspace eBPF Runtime for Uprobe, Syscall and Kernel-User Interactions](https://arxiv.org/abs/2311.07923) for details.\n\n### **Performance Benchmarks**\n\nHow is the performance of `userspace uprobe` compared to `kernel uprobes`?\n\n| Probe/Tracepoint Types | Kernel (ns)  | Userspace (ns) |\n|------------------------|-------------:|---------------:|\n| Uprobe                 | 3224.172760  | 314.569110     |\n| Uretprobe              | 3996.799580  | 381.270270     |\n| Syscall Tracepoint     | 151.82801    | 232.57691      |\n| Manually Instrument    | Not avaliable |  110.008430   |\n\nIt can be attached to functions in running process just like the kernel uprobe does.\n\nHow is the performance of LLVM JIT/AOT compared to other eBPF userspace runtimes, native code or wasm runtimes?\n\n![LLVM jit benchmark](https://github.com/eunomia-bpf/bpf-benchmark/raw/main/example-output/jit_execution_times.png?raw=true)\n\nAcross all tests, the LLVM JIT for bpftime consistently showcased superior performance. Both demonstrated high efficiency in integer computations (as seen in log2_int), complex mathematical operations (as observed in prime), and memory operations (evident in memcpy and strcmp). While they lead in performance across the board, each runtime exhibits unique strengths and weaknesses. These insights can be invaluable for users when choosing the most appropriate runtime for their specific use-cases.\n\nsee [github.com/eunomia-bpf/bpf-benchmark](https://github.com/eunomia-bpf/bpf-benchmark) for how we evaluate and details.\n\nHash map or ring buffer compared to kernel(TODO)\n\nSee [benchmark](https://github.com/eunomia-bpf/bpftime/tree/master/benchmark) dir for detail performance benchmarks.\n\n### Comparing with Kernel eBPF Runtime\n\n- `bpftime` allows you to use `clang` and `libbpf` to build eBPF programs, and run them directly in this runtime, just like normal kernel eBPF. We have tested it with a libbpf version in [third_party/libbpf](https://github.com/eunomia-bpf/bpftime/tree/master/third_party/libbpf). No specify libbpf or clang version needed.\n- Some kernel helpers and kfuncs may not be available in userspace.\n- It does not support direct access to kernel data structures or functions like `task_struct`.\n\nRefer to [eunomia.dev/bpftime/documents/available-features](https://eunomia.dev/bpftime/documents/available-features) for more details.\n\n## Build and test\n\nSee [eunomia.dev/bpftime/documents/build-and-test](https://eunomia.dev/bpftime/documents/build-and-test) for details.\n\n## Roadmap\n\n`bpftime` is continuously evolving with more features in the pipeline:\n\n- [ ] Keep compatibility with the evolving kernel\n- [ ] Refactor for General Extension Framework\n- [ ] Trying to refactor, bug fixing for `Production`.\n- [ ] More examples and usecases:\n  - [X] Userspace Network Driver on userspace eBPF\n  - [X] Hotpatch userspace application\n  - [X] Error injection and filter syscall\n  - [X] Syscall bypassing, batching\n  - [X] Userspace Storage Driver on userspace eBPF\n  - [ ] etc...\n\nStay tuned for more developments from this promising project! You can find `bpftime` on [GitHub](https://github.com/eunomia-bpf/bpftime).\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Contact and citations\n\nHave any questions or suggestions on future development? Free free to open an issue or contact\n\u003cyunwei356@gmail.com\u003e !\n\nOur arxiv preprint: \u003chttps://arxiv.org/abs/2311.07923\u003e\n\n```txt\n@misc{zheng2023bpftime,\n      title={bpftime: userspace eBPF Runtime for Uprobe, Syscall and Kernel-User Interactions}, \n      author={Yusheng Zheng and Tong Yu and Yiwei Yang and Yanpeng Hu and XiaoZheng Lai and Andrew Quinn},\n      year={2023},\n      eprint={2311.07923},\n      archivePrefix={arXiv},\n      primaryClass={cs.OS}\n}\n```\n\n## Acknowledgement\n\neunomia-bpf community is sponsored by [PLCT Lab](https://plctlab.github.io/) from [ISCAS](http://english.is.cas.cn/au/).\n\nThanks for other sponsors and discussions help building this project: [Prof. Marios Kogias](https://marioskogias.github.io/) from Imperial College London, [Prof. Xiaozheng lai](https://www2.scut.edu.cn/cs/2017/0129/c22285a327654/page.htm) from SCUT, [Prof lijun chen](http://www.xiyou.edu.cn/info/2394/67845.htm) from XUPT,\n[Prof. Qi Li](https://sites.google.com/site/qili2012/) from THU [NISL Lab](https://netsec.ccert.edu.cn/en/), and Linux eBPF maintainers in the LPC 23 eBPF track.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feunomia-bpf%2Fbpftime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feunomia-bpf%2Fbpftime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feunomia-bpf%2Fbpftime/lists"}