aws-ebpf-sdk-go

README

aws-ebpf-sdk-go

Golang based SDK for kernel eBPF operations i.e, load/attach/detach eBPF programs and create/delete/update maps. SDK relies on Unix bpf() system calls.

SDK currently supports -

1. eBPF program types - a. Traffic Classifiers b. XDP c. Kprobes/Kretprobes d. Tracepoint probes
2. Ring buffer (would need kernel 5.10+)

SDK currently do not support -

1. Map in Map
2. Perf buffer

Contributions welcome!

Note: This is the first version of SDK and interface is subject to change so kindly review the release notes before upgrading.

Getting started

How to build SDK?

Run make build-linux - this will build the sdk binary.

How to build elf file?

clang -I../../.. -O2 -target bpf -c <C file> -o <ELF file>

How to use the SDK?

Note: SDK expects the BPF File System (/sys/fs/bpf) to be mounted.

In your application,

1. Get the latest SDK -

GOPROXY=direct go get github.com/aws/aws-ebpf-sdk-go

1. Import the elfparser -

goebpfelfparser "github.com/aws/aws-ebpf-sdk-go/pkg/elfparser"

1. Load the elf -

goebpfelfparser.LoadBpfFile(<ELF file>, <custom pin path>)

On a successful load, SDK returns -

1. loaded programs (includes associated maps)

This is indexed by the pinpath - 

type BpfData struct {
	Program ebpf_progs.BpfProgram       // Return the program
	Maps    map[string]ebpf_maps.BpfMap // List of associated maps
}

1. All maps in the elf file

This is indexed by the map name -

type BpfMap struct {
	MapFD       uint32
	MapID       uint32
	MapMetaData CreateEBPFMapInput
}

Application can specify custom pinpath while loading the elf file.

Maps and Programs pinpath location is not customizable with the current version of SDK and will be installed under the below locations by default -

Program PinPath - "/sys/fs/bpf/globals/aws/programs/"

Map PinPath - "/sys/fs/bpf/globals/aws/maps/"

Map defintion should follow the below definition else the SDK will fail to create the map.

struct bpf_map_def_pvt {
	__u32 type;
	__u32 key_size;
	__u32 value_size;
	__u32 max_entries;
	__u32 map_flags;
	__u32 pinning;
	__u32 inner_map_fd;
};

How to debug SDK issues?

SDK logs are located here /var/log/aws-routed-eni/ebpf-sdk.log.

How to run unit-test

Run sudo make unit-test

Note: you would need to run this on you linux system

How to run functional tests

Go to -

cd test/
sudo make run-test

Security

See CONTRIBUTING for more information.

If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the instructions here or email AWS security directly.

License

This project is licensed under the Apache-2.0 License.