{"id":13714014,"url":"https://github.com/dropbox/goebpf","last_synced_at":"2025-05-15T19:09:27.290Z","repository":{"id":43298559,"uuid":"167455605","full_name":"dropbox/goebpf","owner":"dropbox","description":"Library to work with eBPF programs from Go","archived":false,"fork":false,"pushed_at":"2024-03-19T15:37:38.000Z","size":1800,"stargazers_count":1148,"open_issues_count":15,"forks_count":86,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-04-08T00:38:51.081Z","etag":null,"topics":["bpf","cats","cats-effect","ebpf","go","golang","golang-library","perfevents","xdp","xdpdump"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dropbox.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}},"created_at":"2019-01-24T23:51:24.000Z","updated_at":"2025-03-25T08:02:27.000Z","dependencies_parsed_at":"2024-06-18T13:48:09.409Z","dependency_job_id":"58494c3b-7e7d-4c57-a2eb-886aecf4cf27","html_url":"https://github.com/dropbox/goebpf","commit_stats":{"total_commits":69,"total_committers":13,"mean_commits":"5.3076923076923075","dds":0.3913043478260869,"last_synced_commit":"e568275f843160ec86c497dc0d8a2cfccacc9c8c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fgoebpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fgoebpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fgoebpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dropbox%2Fgoebpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dropbox","download_url":"https://codeload.github.com/dropbox/goebpf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254404357,"owners_count":22065641,"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":["bpf","cats","cats-effect","ebpf","go","golang","golang-library","perfevents","xdp","xdpdump"],"created_at":"2024-08-02T23:01:50.096Z","updated_at":"2025-05-15T19:09:27.268Z","avatar_url":"https://github.com/dropbox.png","language":"Go","readme":"# Go eBPF\n[![Build Status](https://github.com/dropbox/goebpf/actions/workflows/go.yml/badge.svg)](https://github.com/dropbox/goebpf/actions?query=branch%3Amaster)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dropbox/goebpf)](https://goreportcard.com/report/github.com/dropbox/goebpf)\n[![Documentation](https://godoc.org/github.com/dropbox/goebpf?status.svg)](http://godoc.org/github.com/dropbox/goebpf)\n\nA nice and convenient way to work with `eBPF` programs / perf events from Go.\n\n## Requirements\n- Go 1.11+\n- Linux Kernel 4.15+\n\n## Supported eBPF features\n- eBPF programs\n    - `SocketFilter`\n    - `XDP`\n    - `Kprobe` / `Kretprobe`\n    - `tc-cls` (`tc-act` is partially implemented, currently)\n- Perf Events\n\nSupport for other program types / features can be added in future.\nMeanwhile your contributions are warmly welcomed.. :)\n\n## Installation\n```bash\n# Main library\ngo get github.com/dropbox/goebpf\n\n# Mock version (if needed)\ngo get github.com/dropbox/goebpf/goebpf_mock\n```\n\n## Quick start\nConsider very simple example of Read / Load / Attach\n```go\n    // In order to be simple this examples does not handle errors\n    bpf := goebpf.NewDefaultEbpfSystem()\n    // Read clang compiled binary\n    bpf.LoadElf(\"test.elf\")\n    // Load XDP program into kernel (name matches function name in C)\n    xdp := bpf.GetProgramByName(\"xdp_test\")\n    xdp.Load()\n    // Attach to interface\n    xdp.Attach(\"eth0\")\n    defer xdp.Detach()\n    // Work with maps\n    test := bpf.GetMapByName(\"test\")\n    value, _ := test.LookupInt(0)\n    fmt.Printf(\"Value at index 0 of map 'test': %d\\n\", value)\n```\nLike it? Check our [examples](https://github.com/dropbox/goebpf/tree/master/examples/)\n\n## Perf Events\nCurrently library has support for one, most popular use case of perf_events: where `eBPF` map key maps to `cpu_id`.\nSo `eBPF` and `go` parts actually bind `cpu_id` to map index. It maybe as simple as:\n\n```c\n    // Define special, perf_events map where key maps to CPU_ID\n    BPF_MAP_DEF(perfmap) = {\n        .map_type = BPF_MAP_TYPE_PERF_EVENT_ARRAY,\n        .max_entries = 128,     // Max supported CPUs\n    };\n    BPF_MAP_ADD(perfmap);\n\n    // ...\n\n    // Emit perf event with \"data\" to map \"perfmap\" where index is current CPU_ID\n    bpf_perf_event_output(ctx, \u0026perfmap, BPF_F_CURRENT_CPU, \u0026data, sizeof(data));\n```\n\nAnd the `go` part:\n```go\n    perf, err := goebpf.NewPerfEvents(\"perfmap\")\n    // 4096 is ring buffer size\n    perfEvents, err := perf.StartForAllProcessesAndCPUs(4096)\n    defer perf.Stop()\n\n    for {\n        select {\n            case data := \u003c-perfEvents:\n                fmt.Println(data)\n        }\n    }\n```\nLooks simple? Check our [full XDP dump example](https://github.com/dropbox/goebpf/tree/master/examples/xdp/xdp_dump)\n\n## Kprobes\nLibrary currently has support for `kprobes` and `kretprobes`.\nIt can be as simple as:\n\n```c\n    // kprobe handler function\n    SEC(\"kprobe/guess_execve\")\n    int execve_entry(struct pt_regs *ctx) {\n      // ...\n      buf_perf_output(ctx);\n      return 0;\n    }\n```\nAnd the `go` part:\n```go\n\t// Cleanup old probes\n\terr := goebpf.CleanupProbes()\n\n\t// Attach all probe programs\n\tfor _, prog := range bpf.GetPrograms() {\n\t\terr := prog.Attach(nil)\n\t}\n\n\t// Create perf events\n\teventsMap := p.bpf.GetMapByName(\"events\")\n\tp.pe, err = goebpf.NewPerfEvents(eventsMap)\n\tevents, err := p.pe.StartForAllProcessesAndCPUs(4096)\n\tdefer events.Stop()\n\n\tfor {\n\t\tselect {\n\t\tcase data := \u003c-events:\n\t\t\tfmt.Println(data) // kProbe event\n\t\t}\n\t}\n```\nSimple? Check [exec dump example](https://github.com/dropbox/goebpf/tree/master/examples/kprobe/exec_dump)\n\n## Good readings\n- [XDP Tutorials](https://github.com/xdp-project/xdp-tutorial)\n- [Cilium BPF and XDP Reference Guide](https://docs.cilium.io/en/latest/bpf/)\n- [Prototype Kernel: XDP](https://prototype-kernel.readthedocs.io/en/latest/networking/XDP/index.html)\n- [AF_XDP: Accelerating networking](https://lwn.net/Articles/750845/)\n- [eBPF, part 1: Past, Present, and Future](https://ferrisellis.com/posts/ebpf_past_present_future/)\n- [eBPF, part 2: Syscall and Map Types](https://ferrisellis.com/posts/ebpf_syscall_and_maps/)\n- [Oracle Blog: A Tour of eBPF Program Types](https://blogs.oracle.com/linux/notes-on-bpf-1)\n- [Oracle Blog: eBPF Helper Functions](https://blogs.oracle.com/linux/notes-on-bpf-2)\n- [Oracle Blog: Communicating with Userspace](https://blogs.oracle.com/linux/notes-on-bpf-3)\n","funding_links":[],"categories":["Go","Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fgoebpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdropbox%2Fgoebpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdropbox%2Fgoebpf/lists"}