{"id":25493818,"url":"https://github.com/bpf-endeavor/servant","last_synced_at":"2026-02-27T00:31:49.621Z","repository":{"id":64907865,"uuid":"428288956","full_name":"bpf-endeavor/Servant","owner":"bpf-endeavor","description":"Servant combines uBPF and AF_XDP. Using it you can write eBPF packet processing programs that run in usersapce.","archived":false,"fork":false,"pushed_at":"2025-02-03T09:23:54.000Z","size":375,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T01:11:14.196Z","etag":null,"topics":["af-xdp","ebpf","ubpf"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bpf-endeavor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2021-11-15T14:07:31.000Z","updated_at":"2025-03-14T02:16:02.000Z","dependencies_parsed_at":"2024-12-19T18:18:49.071Z","dependency_job_id":"a28b1a1c-480d-4b62-bf77-6d5cb434ae58","html_url":"https://github.com/bpf-endeavor/Servant","commit_stats":null,"previous_names":["bpf-endeavor/servant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bpf-endeavor/Servant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpf-endeavor%2FServant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpf-endeavor%2FServant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpf-endeavor%2FServant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpf-endeavor%2FServant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bpf-endeavor","download_url":"https://codeload.github.com/bpf-endeavor/Servant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bpf-endeavor%2FServant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29878986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"ssl_error","status_checked_at":"2026-02-26T23:50:46.793Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["af-xdp","ebpf","ubpf"],"created_at":"2025-02-18T23:17:37.077Z","updated_at":"2026-02-27T00:31:49.525Z","avatar_url":"https://github.com/bpf-endeavor.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Servant\n\nServant combines uBPF and AF\\_XDP. Using it you can write eBPF packet\nprocessing programs that run in usersapce.\n\n\n## Compile\n\n**Install the dependencies:**\n\n* Tested on: Linux kernel 5.13\n* uBPF (custom version)\n* libbpf (commit: f9f6e92458899fee5d3d6c62c645755c25dd502d)\n* llvm 13\n\nYou can look at `/setup.sh`\n\n\n**Compile:**\n\nuse `make` at `/src/` to compile the Servant.\nYou can install Servant's header with `make install`.\n\n\n## Usage\n\n\u003e Enable the Huge page size support.\n\n*Servant Arguments:*\n\n| Arg | Description |\n|-----|-------------|\n| ifname | name of the ethernet interface to attach |\n| qid | queue index for attaching AF\\_XDP |\n| ebpf | path to the ebpf program binary to load |\n| [map] | name of the in kernel map which eBPF program want to access you can also assign the map an index using \"name:index\". This index could be used with `lookup_fast` helper function.|\n| [core] | pin the process to the given CPU core |\n| [xdp-prog] | path to the XDP program. this program should have a map of type `BPF_MAP_TYPE_XSKMAP` named `xsks_map`|\n| [busypoll] | run AF\\_XDP in busy-polling mode |\n| [...] | there are other options (to be complete) |\n\n## Run an example program\n\nThere are some example programs at `/examples`.\n\n```bash\n# map incomming ipv4/udp traffic with destination port of 8080 to queue 2\nsudo ethtool -U \u003ciface\u003e flow-type udp4 dst-port 8080 action 2\ncd ./examples/dump_packet\nmake\n# Run the eBPF program with an AF_XDP socket connected on queue 2\nsudo ../../src/servant \u003cifce\u003e 2 ./ubpf.o\n```\n\nGenerate traffic toward the uBPF program. The packets should be displayed on the\nterminal.\n\nOn the other machine start a netcat and send UDP traffic.\n\n```bash\nnc -u \u003cip address of first machine\u003e 8080\nhello\n```\n\nOut put of uBPF program should be like below\n\n```\n...\nPacket size: 60\nSrc MAC: 3c:fd:fe:56:1:a2\nDest MAC: 3c:fd:fe:55:ff:42\nEther Type: 800\nSrc IP: c0a80102\nDst IP: c0a80101\nTransport: UDP\nSrc PORT: 57300\nDst PORT: 8080\n...\n```\n\n## Example eBPF Program\n\n\nThe structure of the program looks like below.\n\n```c\n#include \u003cservant/servant_engine.h\u003e\n\nint bpf_prog(struct pktctx *ctx)\n{\n\treturn DROP;\n}\n```\n\n**struct pktctx:**\n\nEach eBPF program will receive packets in the following form.\n(look at `/src/include/packet_context.h`)\n\n```c\nstruct pktctx {\n\tvoid *data; // in: start of the packet\n\tvoid *data_end; // in: end of the packet\n\tuint32_t pkt_len; // inout: final length of packet\n\tint32_t trim_head; // out: skip n bytes from the head before sending\n};\n```\n\n**return codes:**\n\nThe eBPF program should return one of the following values.\n\n1. `PASS`: Pass the packet to the network stack.\n1. `DROP`: Drop the packet.\n1. `SEND`: Send the packet on the attached ethernet interface.\n\n\u003e Currently destination of packets injected to the kernel (`PASS`) are hard-coded but this can be solved and is not a limitation.\n\u003e Look at `/src/udp_sock.c`\n\n\n## eBPF Program Helpers\n\nFor list of helper functions defined look at `/src/include/servant_engine.h`\n\n| Helper | Description |\n|--------|-------------|\n| `lookup` | lookup an in kernel map using name of the map |\n| `lookup_fast` | lookup an in kernel map using index of the map (You can define index of each map when starting Servant) |\n| `userspace_lookup` | lookup a userspace map |\n| `userspace_update` | update a usersapce map |\n| `ubpf_get_time_ns` | read clock MONOTONIC value |\n| `ubpf_print` | print messages |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpf-endeavor%2Fservant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbpf-endeavor%2Fservant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbpf-endeavor%2Fservant/lists"}