{"id":15190163,"url":"https://github.com/redcanaryco/oxidebpf","last_synced_at":"2025-10-02T05:30:29.228Z","repository":{"id":40561824,"uuid":"369593882","full_name":"redcanaryco/oxidebpf","owner":"redcanaryco","description":"A Rust library for managing eBPF programs.","archived":true,"fork":false,"pushed_at":"2024-02-26T16:51:20.000Z","size":213,"stargazers_count":116,"open_issues_count":0,"forks_count":13,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-01-21T10:36:30.827Z","etag":null,"topics":["ebpf","rust-crate"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/oxidebpf","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redcanaryco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-05-21T16:27:14.000Z","updated_at":"2024-11-06T06:38:36.000Z","dependencies_parsed_at":"2024-02-26T18:02:05.805Z","dependency_job_id":"87c89f90-1236-425a-a662-e62e6c5a7539","html_url":"https://github.com/redcanaryco/oxidebpf","commit_stats":{"total_commits":123,"total_committers":13,"mean_commits":9.461538461538462,"dds":0.5040650406504066,"last_synced_commit":"4f2ae2da4d46c906e0d1d4221a45c5a1de2858b0"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/redcanaryco/oxidebpf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redcanaryco%2Foxidebpf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redcanaryco%2Foxidebpf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redcanaryco%2Foxidebpf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redcanaryco%2Foxidebpf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redcanaryco","download_url":"https://codeload.github.com/redcanaryco/oxidebpf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redcanaryco%2Foxidebpf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277958673,"owners_count":25905750,"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","status":"online","status_checked_at":"2025-10-02T02:00:08.890Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","rust-crate"],"created_at":"2024-09-27T20:05:27.675Z","updated_at":"2025-10-02T05:30:28.909Z","avatar_url":"https://github.com/redcanaryco.png","language":"Rust","funding_links":[],"categories":["eBPF Workflow: Tools and Utilities","Rust","eBPF 工作流：工具和实用程序"],"sub_categories":["oxidebpf"],"readme":"# oxidebpf\n\n`oxidebpf` is a permissive licensed Rust library for managing eBPF programs.\n\n## Motivation\n\nThe motivation behind `oxidebpf` is to create a permissive licensed Rust library\nfor managing long-running eBPF programs that operate in as many environments\nas possible. Doing this required breaking some pre-set patterns on how eBPF\napplications are developed and deployed. We wanted to be able to easily deploy\nan eBPF solution that worked on as many distributions as possible; without forcing\nthe user to have a tool-chain present. Users typically just want a product to do\nthe thing - without a bunch of additional setup or maintenance. This library\nhelped us realize that goal - and we are sharing it openly.\n\nInitially this library meets our current eBPF requirements, so its not a fully\nflushed out eBPF implementation. Contributions are very much welcome, and we will\nslowly be adding to the feature list over time.\n\n## Goals\n\nWe want `oxidebpf` to meet the following goals.\n\n*  Permissive licensed with no GPL dependencies.\n*  Support custom CO-RE eBPF\n*  Run eBPF programs on Linux 4.4+\n*  Written in pure Rust, or as close to pure Rust as possible.\n*  Minimal dependencies, pull in the bare minimum set of dependencies required\nto achieve our desired functionality.\n\n# Requirements\n\nA set of Linux environments are provided for building and testing, with dependencies\nlisted in their `bootstrap.sh` scripts. In general, you will want:\n\n```\n$ sudo apt-get install build-essential clang llvm libclang-dev linux-tools-oem \\\n  linux-tools-(kernel version)-generic\n```\n\nAdditionally, you will need cargo installed. The `cargo-with` package is recommended\nfor debugging and testing. It allows you to trace BPF calls during tests by running\n`cargo with \"strace -vfe bpf\" -- test`.\n\n# Getting Started\n\nHere's some quick steps to get you started right away.\n\n1. Add `oxidebpf` to your `Cargo.toml`, if you wish to use perfmaps you should\nalso add `crossbeam-channel`.\n2. Use the `ProgramBlueprint` to load your compiled eBPF object file with\nmaps and programs.\n3. Create a `Program` for each program you intend to load, with options set.\n4. Create a `ProgramVersion` with your programs. You may create\nmultiple `ProgramVersion`s, representing different sets of\nprograms. For example, programs intended to run on different kernel versions.\n5. Create a `ProgramGroup`.\n6. Give the `ProgramGroup` your `ProgramVersions` and `ProgramBlueprint`, and\ntell it to start loading. It will attempt each `ProgramVersion` in order until\none successfully loads on the current kernel. If it cannot load any program\nversion, it will return an error composed of the underlying errors for each\n`ProgramVersion`.\n\n```rust\nlet program = PathBuf::from(env!(\"CARGO_MANIFEST_DIR\"))\n    .join(\"test\")\n    .join(format!(\"test_program_{}\", std::env::consts::ARCH));\nlet program_blueprint =\n    ProgramBlueprint::new(\u0026std::fs::read(program).expect(\"Could not open file\"), None)\n        .expect(\"Could not open test object file\");\nlet mut program_group = ProgramGroup::new();\nlet (tx, rx) = crossbeam_channel::bounded(1024);\n\nprogram_group.load(\n    program_blueprint,\n    vec![ProgramVersion::new(vec![\n        Program::new(\n            \"test_program_map_update\",\n            vec![\"do_mount\"],\n        )\n        .syscall(true),\n        Program::new(\"test_program\", vec![\"do_mount\"]).syscall(true),\n    ])],\n    || (tx, PerfBufferSize::Total(4096))),\n).expect(\"Could not load programs\");\n\n// read from rx any events from a perfmap in the loaded program version\n\n```\n\nNote: this expects the presence of a `test_program_[arch]` binary in a `test` subfolder\nof your project, where `[arch]` is the architecture of your system.\n\n## Building\n\nThe project includes several Vagrantfiles which are set up to build and test the library.\n\n```\n$ cd vagrant/ubuntu_20.04\n$ vagrant up\n$ vagrant ssh\n$ cd oxidebpf\n$ cargo build\n```\n\nIf you want to build locally, check the `bootstrap.sh` file for the Vagrantfile most\nsimilar to your system. This file will include build and test dependencies for the\ndistribution.\n\n## Testing\n\n1. Run `docker-compose run --rm test-builder` from the `test/` directory to build the BPF test application. For additional options for RHEL builds, see `test/README.md`.\n2. Run tests with `cargo test`. To trace BPF syscalls as they occur, run\n   the tests with `cargo with \"strace -fe bpf\" -- test` (depends on `cargo-with`, included in\n   vagrant bootstrap by default).\n\nNote: some tests will require root privileges to pass. Other tests require a single-threaded context\nto pass. To test consistently, try running: `sudo -E /path/to/your/.cargo/bin/cargo test -- --test-threads=1`.\nFor convenience, you can alias this as `alias scargo=\"sudo -E $HOME/.cargo/bin/cargo\"` and run tests with\n`scargo test -- --test-threads=`.\n\n# Features\n\n## Metrics\n\n`oxidebpf` has a (disabled by default) feature called `metrics`. When\nenabled it will use the [metrics] crate to propagate internal metrics\nrelated to the ebpf maps. These are the `metrics` that `oxidebpf`\ncurrently reports on:\n\n* `perfmap.unread_size_pct`: A histogram of how much of the perfmap\n  buffer has not been read. This is emitted right after polling the\n  perf map file descriptors but before reading from them. This is only\n  emitted by perfmaps that woke up during the epoll, if a perfmap\n  never gets data then it will not report by this metric. The map name\n  and cpu are reported as labels. A `describe_histogram!` is also\n  emitted for this metric to tell reporters that this is a percentage\n  unit. This can be used to set up histogram buckets.\n\n* `perfmap.buffer_size_kb`: A gauge of how much memory (in KB) is\n  being allocated for the data portion of the perfmap buffer. Note\n  that an extra page is always allocated for metadata. This is emitted\n  immediately prior to the creation of the map. The map name is\n  reported as a label.\n\n* `perfmap.num_buffers`: A gauge of how many buffers are being\n  allocated for a perfmap. This is also the number of online cpus that\n  oxidebpf detected. This is emitted immediately prior to the creation\n  of the perf map. The map name is reported as a label.\n\n* `perfmap.channel.full`: A counter of how many times we tried to send\n  a dropped message across the user provided channel for perfmaps but\n  failed due to it being full. The map name is reported as a label.\n\nAdding or removing metrics will not be considered a breaking change at\nthis point but we may reconsider this decision in the future as we\nstabilize what metrics seem the most useful\n\n[metrics]: https://docs.rs/metrics/latest/metrics/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredcanaryco%2Foxidebpf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredcanaryco%2Foxidebpf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredcanaryco%2Foxidebpf/lists"}