gobee

BPF 프로그램을 C가 아닌 Go로 작성하세요. gobee는 Go의 엄격한 부분 집합을 BPF C로 트랜스파일하고, 사용자 공간 측을 위한 타입이 있는 Go 바인딩을 생성하며, 실행 중인 커널에 대해 로드를 게이트합니다.

Go 생태계는 BPF를 위한 견고한 사용자 공간 도구를 갖추고 있습니다. 커널 측은 항상 "이제 C로 프로그램을 작성하세요"로 끝났습니다. Aya는 rustc에 새로운 BPF 백엔드를 작성하여 Rust로 eBPF를 가져왔습니다. gobee는 다른 방식으로 접근합니다: C로 트랜스파일하여 clang의 성숙한 백엔드를 재사용합니다.

Go 파일 입력, BPF 프로그램 출력

링 버퍼를 통해 모든 execve를 사용자 공간으로 스트리밍하는 트레이스포인트:

//go:build ignore

package main

import "github.com/boratanrikulu/gobee/bpf"

//bpf:license GPL

type Event struct {
    Pid  uint32
    Comm [16]byte
}

var Events = bpf.RingBuf[Event]{
    MaxEntries: 4096,
}

//bpf:section tracepoint/syscalls/sys_enter_execve
func OnExec(ctx *bpf.ExecveEnterCtx) bpf.TpReturn {
    e, ok := Events.Reserve()
    if !ok {
        return bpf.TpOk
    }
    e.Pid = bpf.GetCurrentPid()
    bpf.GetTaskComm(&e.Comm)
    Events.Submit(e)
    return bpf.TpOk
}

func main() {}

// Code generated by gobee. DO NOT EDIT.

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_core_read.h>

char _license[] SEC("license") = "GPL";

struct Event {
    __u32 Pid;
    __u8 Comm[16];
};

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 4096);
} Events SEC(".maps");

SEC("tracepoint/syscalls/sys_enter_execve")
int OnExec(struct trace_event_raw_sys_enter *ctx) {
    struct Event *e = bpf_ringbuf_reserve(
        &Events, sizeof(struct Event), 0);
    if (!e) {
        return 0;
    }
    e->Pid = (__u32)(
        bpf_get_current_pid_tgid() >> 32);
    bpf_get_current_comm(&e->Comm, 16);
    bpf_ringbuf_submit(e, 0);
    return 0;
}

gobee translate --bindings-dir ./bpf ./bpf/src는 두 파일을 모두 생성하며, 검증기 오류를 Go 라인에 매핑하는 소스맵(events.bpf.c.map)과 사용자 공간 드라이버가 문자열 기반의 coll.Programs["..."] 조회 대신 objs.Events, objs.AttachOnExec()를 작성하고 링 버퍼 페이로드를 직접 bpf.Event(위에서 본 동일한 구조체를 Go로 다시 게시한 것)로 디코딩할 수 있도록 하는 타입이 있는 바인딩 파일(bpf/events_bindings.go)을 생성합니다.

C는 의도적으로 읽기 쉽게 되어 있습니다. gobee가 이상한 것을 내보내면 볼 수 있습니다. 트레이스포인트 + kprobe + XDP가 하나의 바이너리로 결합된 예제는 example/sysmon/을 참조하세요.

비교

이미 C / libbpf 워크플로우에 있다면 gobee가 이를 완전히 대체하려는 것은 아닙니다. 커널 측, 사용자 공간 측, 빌드 파이프라인을 모두 하나의 Go 모듈에 포함시키고 싶은 경우를 위한 것입니다.

현재 지원되는 것

전체 매트릭스(Go 부분 집합, 문, 표현식, 모든 헬퍼, 모든 맵 유형, 모든 지시문)는 docs/status.md를 참조하세요. 빠른 개요:

gobee가 하는 일

• Go 부분 집합을 BPF C로 트랜스파일합니다 (먼저 입력에 대해 go/types를 실행하여 file:line:col에서 오용을 표시).
• .bpf.c 옆에 타입이 있는 <Stem>_bindings.go를 생성합니다: bpf.LoadCounter(spec), objs.PerIface.Lookup(...), objs.AttachAll(ifindex), 그리고 커널 측 구조체 유형과 상수를 Go로 다시 게시.
• LoadAndAssign의 *ebpf.VerifierError를 Go 소스 위치로 자동 주석 처리합니다. 수동 gobee diagnose 파이프가 필요 없음.
• Load<Stem> 내부에서 bpfvet를 실행하여 오래된 커널이 bpf program needs kernel >= 5.8, host is 5.4로 빠르게 실패하도록 함.
• libbpf v1.5.0 헬퍼 세트에 대한 약 200개의 타입이 있는 Go 스텁과 사용자 정의 헬퍼 함수 (static __always_inline으로 생성)를 제공합니다.

gobee가 하지 않는 일

• clang을 대체하지 않습니다. clang의 BPF 백엔드는 CO-RE, BTF, 검증기 친화적인 코드 생성을 무료로 제공합니다. 이를 다시 구현하는 것은 몇 년이 걸리고 얻는 것이 없습니다.
• cilium/ebpf를 대체하지 않습니다. 생성된 바인딩은 그 위에 있습니다.
• BPF를 숨기지 않습니다. Go 부분 집합은 BPF C 관용구와 1:1로 매핑됩니다. BPF를 알고 있다면 gobee는 얇은 설탕입니다. 모른다면 매뉴얼은 여전히 필수 읽기 자료입니다.
• 사용자를 대신하여 clang을 실행하지 않습니다. 컴파일, 임베딩, 로드는 사용자 책임으로 남습니다. bpf2go와 동일한 패턴입니다.

왜 직접 BPF를 생성하지 않고 트랜스파일하는가?

Go 컴파일러 gc는 LLVM 기반 BPF 백엔드가 없습니다. 하나를 추가하는 것은 수년이 걸리는 컴파일러 프로젝트입니다. rustc는 LLVM 위에 구축되어 있으며 이것이 Aya가 작동하는 이유입니다. 따라서 gobee는 C를 생성하고 clang의 BPF 백엔드를 재사용하여 성숙한 코드 생성, BTF, CO-RE 재배치를 무료로 얻습니다.

빠른 시작

go install github.com/boratanrikulu/gobee/cmd/gobee@latest

cd example/helloworld
make build                     # gobee translate, clang, go build
sudo ./helloworld eth0

BPF 대상을 지원하는 clang이 필요합니다. Linux에서는 배포판 패키지로 제공됩니다. macOS에서는 brew install llvm을 사용하세요. 트랜스파일러 자체는 순수 Go로 작성되어 어디서나 실행됩니다.

프로젝트 레이아웃 (일반적인 경우)

yourproject/
├── bpf/                      # Go 패키지, 프로젝트 어디서든 임포트 가능
│   ├── embed_amd64.go        # //go:embed bin/x86/your.bpf.o
│   ├── embed_arm64.go
│   ├── your_bindings.go      # gobee에 의해 생성됨
│   ├── bin/{x86,arm64}/your.bpf.o
│   └── src/                  # Go 패키지 아님; clang이 여기에 있음
│       ├── your.go           # //go:build ignore: BPF 소스
│       ├── your.bpf.c        # 생성됨
│       ├── Makefile          # 아키텍처별 clang
│       └── vmlinux.h         # 벤더링된 BTF 덤프
├── main.go                   # yourproject/bpf 임포트
└── Makefile

이 분할은 bpf/를 깨끗한 임포트 가능한 Go 패키지로 유지합니다 (Go는 cgo가 아닌 패키지에서 .c 파일을 거부합니다). 커널 소스와 clang 아티팩트는 bpf/src/ 아래 한 단계 더 있습니다.

예제

• example/helloworld/: 표준 XDP 패킷 카운터, ~40줄 BPF, ~80줄 사용자 공간.
• example/sysmon/: 하나의 바이너리에 XDP, 두 개의 트레이스포인트, 하나의 kprobe가 포함되어 있으며 이벤트를 위해 링 버퍼를 공유합니다. 시스템 호출별 타입이 있는 컨텍스트, 사용자 정의 헬퍼 함수, AttachAll 단축키를 보여줍니다.

CI

GitHub Actions는 모든 푸시마다 네 가지 레이어를 실행합니다:

1. go test, go vet, 트랜스파일러 골든 테스트
2. 적용 범위 매트릭스: 모든 맵 유형과 //bpf:section 종류에 대해 최소한 하나의 예제
3. 모든 큐레이팅된 예제의 clang 컴파일, 그리고 bpfvet 이식성 보고서
4. 실제 커널 검증기 수락: 각 .bpf.o에 대한 ebpf.NewCollectionWithOptions (Ubuntu 24.04 러너, 커널 6.x)

문서

• docs/design.md: 아키텍처 및 근거
• docs/go-subset.md: BPF 소스 파일에서 허용되는 Go 구문
• docs/directives.md: //bpf:* 참조
• docs/status.md: 지원 매트릭스 (단일 진실 공급원)

도구 체인

• gobee 바이너리는 어디서나 빌드됩니다 (순수 Go, CGO 없음).
• .bpf.o 컴파일에는 BPF 대상을 지원하는 clang이 필요합니다. Apple 번들 clang에는 포함되어 있지 않습니다. macOS에서는 brew install llvm을 사용하거나 Linux VM 내에서 빌드하세요.
• 아티팩트 실행에는 Linux arm64 또는 amd64가 필요합니다.

영감

• Solod: 이 패턴이 작동함을 증명한 Go-to-C 트랜스파일러.
• Aya: gobee가 추구하는 사용성을 가진 Rust eBPF 프레임워크.

라이선스

MIT. LICENSE를 참조하세요.

Copyright (c) 2026 Bora Tanrikulu <[email protected]>