Skip to content

Releases: cilium/ebpf

v0.9.2

20 Sep 08:39

Choose a tag to compare

This release contains an important bugfix for users of Program.Test() and .Benchmark(). A kernel change was made that disallows empty packet buffers, with knock-on effects to BPF_PROG_RUN and, as a result, ebpf-go's detection routine for said feature. Users are strongly encouraged to upgrade. See #788 for more details.

The new features.HaveMapFlag() API was merged in this release, congrats @paulcacheux!

Likewise, the link.K(ret)probeMulti() API was added by @mmat11, bringing blazingly-fast bulk kprobe attachments to kernels 5.18 and newer.

Some improvements were made to verifier log handling. The VerifierError.Truncated flag can now reliably be used to determine if a program load should be retried due to the provided buffer size being too small. Use this to retry with incrementally growing log buffers for large or complex programs. The Log* fields in ProgramOptions are now thoroughly documented to this effect.

It also bumps the minimum Go version to 1.18, since 1.19 is now out.

What's Changed

  • run-tests: show curl error messages by @lmb in #738
  • elf_reader: only read data from PROGBITS sections, ignore NOBITS by @ti-mo in #740
  • program: support tracing of kernel modules by @lmb in #737
  • CI: Test against kernel 5.18 by @ti-mo in #668
  • internal: fix VerifierError output with empty log by @lmb in #743
  • elf_reader: Allow strings read-only global data sections by @dylandreimerink in #742
  • CI: expose individual test results by @lmb in #748
  • Fix arm64 testsuite failures by @lmb in #745
  • link: (u|k)probe: don't treat EINVAL as os.ErrNotExist by @ti-mo in #751
  • features: remove EPERM wrapping exception, automatically wrap errors by @ti-mo in #749
  • features: implement probes for StructOps maps and programs by @ti-mo in #746
  • perf add timeout argument by @xpu22 in #736
  • epoll deadline fixups by @lmb in #758
  • prog: unconditionally enable verifier retries, add consts, document LogLevel by @ti-mo in #754
  • program: fix comment typo by @wozniakjan in #764
  • bpf2go: replace deprecated io/ioutil function by @florianl in #762
  • btf: minimal support for BTF_KIND_DECL_TAG and BTF_KIND_TYPE_TAG by @lmb in #747
  • features: add HaveMapFlag API by @paulcacheux in #673
  • Build, test and format with Go 1.19, minimum 1.18 by @ti-mo in #765
  • errors: remove verifier truncation heuristic, rely on ENOSPC by @ti-mo in #756
  • examples: clarify how to rebuild by @lmb in #767
  • feature: define sys.MapFlags and re-export it for map flags feature detection by @paulcacheux in #766
  • cmd/bpf2go: clarify -target usage with bpf_tracing.h by @lmb in #773
  • examples: add sockops example by @BigMikes in #771
  • features: fix incorrect lock in probeMisc by @lmb in #775
  • link: memoize PMU event types read from sysfs by @lmb in #774
  • btf: handle signed enums and fix default signedness by @lmb in #781
  • iter: Add support to load sleepable iterator program type by @olsajiri in #777
  • Correct misleading unpin error in progAttachCgroup by @weiqiangt in #787
  • Fix haveProgTestRun on kernel version 5.15.65 by @player-two in #788
  • Provide 15-byte context inputs to Program.{Run,Benchmark,Test} by @ti-mo in #792
  • link: implement kprobe.multi link by @mmat11 in #716

New Contributors

Full Changelog: v0.9.1...v0.9.2

v0.9.1

19 Jul 10:27

Choose a tag to compare

This is mainly a bugfix release, but a few long-deprecated pieces of API were finally removed after cutting v0.9.0.

These should be trivial to fix up, since they were simply moved or replaced by similar interfaces.

Enjoy!

Breaking Changes

  • Deprecations:
    • ebpf.ErrNotExist was removed, as it was an alias to os.ErrNotExist
    • Map.ID() in favor of Map.Info().ID()
    • Program.ID() in favor of Program.Info().ID()
    • Program.Attach() and .Detach() in favor of link.RawAttachProgram() and link.RawDetachProgram() respectively
    • link.LoadPinned{Cgroup,Iter,RawLink,NetNs,Freplace} in favor of a single link.LoadPinnedLink()
    • link.RawLinkInfo was removed, as it was an alias to link.Info
  • UprobeOptions.Offset is now a relative field, with the new .Address being an absolute offset.

What's Changed

  • Remove API deprecated in v0.8.0 by @lmb in #684
  • program: Add TestWithOptions() API by @danobi in #647
  • prog: Avoid allocating for ctx if ctx not provided by @danobi in #687
  • btf: add Array.Index by @lmb in #689
  • btf: add btfInt by @lmb in #690
  • Add RelativeOffset field to UprobeOptions struct by @mertyildiran in #682
  • program: remove references from ProgramSpec by @lmb in #679
  • map: suggest incorrect MaxEntries on EINVAL by @markpash in #697
  • internal/sys: regenerate types by @florianl in #700
  • link: close tracefs event if perf event cannot be opened by @nashuiliang in #699
  • Revert ".semaphore - workaround to update ca-certificates before apt-get update" by @lmb in #703
  • run-tests: fix shebang to find bash more reliably by @markpash in #702
  • examples: add map in map example by @markpash in #696
  • btf: fix NewHandleFromID and add test by @lmb in #704
  • sycall should be syscall. by @shepf in #707
  • CI: load bpf_testmod in VM by @lmb in #709
  • internal: make VerifierError more succinct by @lmb in #688
  • examples: add example for XDP by @wedaly in #706
  • btf: simplify loadRawSpec by @lmb in #708
  • Remove 4.4 from CI by @lmb in #710
  • map: Do not chec maxEntries for PerfEventArray map by @olsajiri in #714
  • link/kprobe: skip offset test on kernel version > 5.15 by @mmat11 in #719
  • Avoid leaking fds in test suite and NewMapWithOptions() by @ti-mo in #725
  • btf: Add support for loading split BTF by @brb in #691
  • prog: Allow empty data for prog.Test and prog.Run by @danobi in #685
  • internal: avoid sign extension of Statfs_t.Type on 32 bit arches by @lmb in #727
  • link: unify KprobeOptions.Offset and UprobeOptions.Offset by @lmb in #694
  • collection: close all unassigned resources before returning from LoadAndAssign by @ti-mo in #724
  • btf: add Enum.Size by @lmb in #735
  • btf: use ci-kernels to source kernel BTF by @lmb in #731
  • asm: update BPF built-in functions by @rgo3 in #734
  • program: add getter for btf.Handle by @lmb in #730
  • btf: fix NewHandleFromID for kernel modules by @lmb in #729
  • internal: include previous line on BPF context access error by @lmb in #733

New Contributors

Full Changelog: v0.9.0...v0.9.1

Releasing the BTF package!

25 May 16:02
@lmb lmb

Choose a tag to compare

This release makes package btf public, allowing type information embedded in eBPF ELF objects and vmlinux to be read programmatically from Go. This enables use cases like searching and inspecting the kernel's types and function signatures at runtime, or ensuring alignment between structures defined in Go and C. Package btf stands on its own and does not require adopting other subpackages, potentially making it useful beyond the domain of eBPF. Additionally, parsing BTF was made significantly faster and now consumes less memory.

Note: Modifications to btf.Types are not (yet) reflected in the BTF info loaded into the kernel. This will be implemented in the near future, and will provide the flexibility of, for example, creating maps with arbitrarily crafted key/value type information for pretty-printing map dumps, among many other exciting use cases.

Users of the ringbuf and perf packages can now avoid allocations when reading samples with the addition of ReadInto().

Feature probes for program helpers (features.HaveProgramHelper()) were added, as well as a few miscellaneous probes for large instruction limit, bounded loops and the supported eBPF ISA. This now brings the library mostly on par with bpftool's probing capabilities, except for a few program types that require BTF.

There was also one important bugfix where CO-RE relocations in bpf2bpf subprograms were not applied. Users are strongly encouraged to upgrade.

Enjoy!

Breaking changes

  • Deprecations:
    • CollectionSpec.RewriteMaps is deprecated in favour of CollectionOptions.MapReplacements
    • features.HaveProgType is deprecated in favour of features.HaveProgramType
  • CollectionSpec.BTF is now called CollectionSpec.Types
  • link.K(ret)probe and link.Tracepoint signatures have changed, they now take an additional options parameter. Pass nil to retain the old behaviour.

Features

  • features: add misc probes by @florianl in #541
  • bpf2go: generate Go types from BTF by @lmb in #552
  • features: add LinuxVersionCode function to obtain LINUX_VERSION_CODE by @ti-mo in #585
  • link: support bpf perf event link, add bpf_cookies by @mmat11 in #565
  • link/kprobe: Allow . in symbol name by @chenhengqi in #600
  • btf: Implement support for bitfield relocations by @joamaki in #573
  • kprobe: fall back to tracefs if kernel doesn't support dots in PMU symbol by @chenhengqi in #605
  • link/kprobe: specify symbol offset by @xpu22 in #618
  • collection: Add ReplaceMaps to CollectionOptions by @mauriciovasquezbernal in #646
  • fix: support bpf_core_type_exists() by @holyspectral in #655
  • perf, ringbuf: add ReadBuffer mehods by @lmb in #663
  • Make BTF for data sections optional by @ti-mo in #675
  • btf: Add spec types iterator by @brb in #678
  • features: add HaveProgramHelper API by @rgo3 in #375
  • Probe kernel bpf2bpf support by @ti-mo in #657

Bug fixes

  • elf_reader: Fix cgroup/sock_{create,release} program type by @joamaki in #580
  • Execute and test CO-RE relocations of bpf2bpf subprogs by @ti-mo in #590
  • syscalls: omit AttachType field in haveProgAttach by @ti-mo in #652
  • prog: recognize ENOTSUPP in testRun() by @ti-mo in #653
  • Assorted fixes for kernel 4.14 by @ti-mo in #658

Miscellaneous

  • collection: Rename CollectionSpec.BTF to .Types, copy in Copy() by @ti-mo in #581
  • collection: document garbage collection behaviour of *Map and *Program by @ti-mo in #579
  • prog_test: compare BTF program tags instead of raw insns by @ti-mo in #583
  • collection: don't copy btf.Spec in CollectionSpec.Copy() by @ti-mo in #584
  • Moved Instruction.Symbol and Instruction.Reference into per-instruction metadata by @dylandreimerink in #582
  • examples: generate types via bpf2go by @lmb in #575
  • Add Maps to Instruction metadata by @dylandreimerink in #567
  • CI: use Go 1.18 by @lmb in #599
  • examples: include bpf_helpers.h from common.h by @ti-mo in #614
  • examples: add example for CO-RE kernel struct (tcp_sock) by @BigMikes in #602
  • examples: fentry - add comments to illustrate difference with tcprtt by @ti-mo in #615
  • btf: reduce unnecessary copies when parsing BTF by @lmb in #623
  • asm: add Instruction Source metadata by @lmb in #609
  • Memory improvements to loadRawSpec by @paulcacheux in #634
  • btf: split string table ahead of time by @lmb in #637
  • sys: update types by @florianl in #630
  • btf: fix up inflated types immediately if possible by @lmb in #638
  • Go 1.17 by @lmb in #640
  • btf: stop relying on TypeID when printing Types by @lmb in #633
  • link: do not use regexp pkg by @kolyshkin in #642
  • btf: make copying types infallible by @lmb in #631
  • Deprecate CollectionSpec.RewriteMaps() by @ti-mo in #651
  • CI: retry two times on error 42 by @lmb in #654
  • Use instruction metadata to simplify linking and CO-RE relocation by @lmb in #606
  • btf: allow users to obtain COREFixups by @lmb in #661
  • CI: run test suite against LTS kernel 4.14 by @ti-mo in #670
  • btf: introduce Bits type and remove Int.Bits and Int.Offset by @lmb in #660
  • ringbuf: reduce allocations and syscalls by @lmb in #667
  • Export package btf by @lmb in #665
  • btf: don't cache kernel BTF in LoadKernelSpec by @lmb in #676

New Contributors

Full Changelog: v0.8.1...v0.9.0

v0.8.1

14 Feb 10:25
@lmb lmb

Choose a tag to compare

Fixes

  • elf_reader: Fix non-determinism in determining prog type by @joamaki in #549
  • Look for Linux note in all elf note sections instead of just the first one by @paulcacheux in #560
  • btf: remove symbol value bounds check to support vmlinux ELFs by @ti-mo in #555

New Contributors

Full Changelog: v0.8.0...v0.8.1

v0.8.0

21 Jan 15:32

Choose a tag to compare

We're happy to announce our first release of 2022!

Breaking Changes

  • Deprecations
    • Deprecate StructOpts and perf.IsClosed() by @ti-mo in #547
  • cmd/bpf2go: strip DWARF info by @lmb in #481
    DWARF info is now stripped from compiled BPF objects by default when using bpf2go, resulting in significant savings in object size. It can be re-enabled if desired.

  • elf_reader: emit UnspecifiedPrograms into CollectionSpec by @ti-mo in #529
    Previously, ProgramSpecs were not emitted to CollectionSpec.Programs if their ELF section names were not recognized.
    This limitation has been lifted: programs that are explicitly assigned to an ELF section will now always appear in the CollectionSpec, though they will all be of type UnspecifiedProgram. The SectionName field was added to help the user determine program types manually.

  • map: make Map.Extra field a pointer to a bytes.Reader by @ti-mo in #546
    A last-minute addition, no longer allocate an empty bytes.Reader for every Map, as this is generally only used when loading legacy programs with iproute2 map definitions. If you're using this field, check for nil before accessing.

Features

  • automatically generate syscall wrappers by @lmb in #425
  • asm: update eBPF built-in functions by @florianl in #459
  • program: add program type syscall by @florianl in #458
  • Add v5.14 to CI builds by @lmb in #462
  • Improve kernel 4.4.x compatibility by @nplanel in #436
  • Add BTFIDLink to support fentry/fexit/fmod_ret/tp_raw/lsm BPF programs by @mehrdadrad in #460
  • link/uprobe: support ref_ctr_offset by @mmat11 in #463
  • Allows user space to update/lookup map elements under bpf_spin_lock by @mehrdadrad in #473
  • Makefile: prefer podman for container engine by @syscll in #480
  • asm: add Instructions.SizeBytes() for convenience and readability by @ti-mo in #492
  • Link: add XDP support by @mehrdadrad in #484
  • link: add LoadPinnedLink by @lmb in #491
  • implement BPF_PROG_BIND_MAP by @florianl in #485
  • use clang 13 by @lmb in #488
  • Read LINUX_VERSION_CODE from vDSO ELF header instead of uname by @brycekahle in #500
  • cmd/bpf2go: infer llvm-strip suffix from clang binary by @lmb in #504
  • Add support for function pointers by @pippolo84 in #499
  • prog: update program types from libbpf by @mehrdadrad in #496
  • btf: rename FindType to TypeByName, add TypesByName and TypeByID methods by @ti-mo in #503
  • btf: support raw BTF in LoadSpecFromReader by @lmb in #520
  • cmd/bpf2go: allow to specify native target by @tklauser in #526
  • asm: Add Jump32 support by @arthurfabre in #514
  • link: expose link info with type-specific information by @mehrdadrad in #509
  • Adopt Go 1.18 fuzzing and fix btf crashes by @lmb in #530
  • elf_reader,btf: support multiple programs per ELF section by @ti-mo in #508
  • Eliminate binary.Read in instruction (un)marshaler by @ti-mo in #532
  • program: retrieve xlated Instructions from Program by @ti-mo in #538
  • Support attaching SocketFilter programs to raw sockets by @folbricht in #540

Bug Fixes

  • CI: add make clean before testdata rebuild by @ti-mo in #450
  • sys: avoid zero fd by @lmb in #454
  • run-tests: don't require CI_MAX_KERNEL_VERSION to be set by @lmb in #470
  • features: fix HaveProgType(ebpf.Syscall) by @rgo3 in #471
  • elf: fix some typos in getProgType by @alxn in #493
  • CI: work around hung agents by @lmb in #516
  • link: switch tests from printk to vprintk symbol by @ti-mo in #518
  • map: allow empty ProgramArray to not be assigned by @lmb in #513
  • prog: don't panic when prog load EPERMs with empty verifier log by @ti-mo in #519
  • map, prog: fix typo in MEMLOCK error string by @tklauser in #527
  • btf: only return exact matches from AnyTypesByName by @lmb in #525
  • Remove BTF type IDs on map creation if not supported by @chenhengqi in #534
  • rlimit: avoid lowering Max rlimit by @ti-mo in #533
  • linker: Allow calling into unimplemented forward function declarations by @ti-mo in #544

Documentation

  • cmd/bpf2go: move doc to README by @lmb in #446

Examples

New Contributors

During this release cycle, we've welcomed the following new contributors:

Thanks to all contributors for your support!

Full Changelog: v0.7.0...v0.8.0

v0.7.0: Honeygopher Edition

11 Oct 12:30

Choose a tag to compare

The cilium/ebpf project now has a mascot, the Honeygopher! Thank you, Vadim Shchekoldin!

New Packages

  • Package ringbuf allows reading from a BPF_MAP_TYPE_RINGBUF map.
  • Package features implements the equivalent of bpftool feature probe for discovering BPF-related kernel features using native Go. Note that support for probing availability of BPF helpers is pending.
  • Package rlimit provides a convenient API to lift the RLIMIT_MEMLOCK constraint on kernels before 5.11.

Breaking Changes

  • Deprecations
    • StructOpts has been changed to alias the new StructOpsMap and will be removed in 0.8.0
      by @ti-mo in #381
    • perf.IsClosed() has been deprecated and will be removed in 0.8.0
      by @lmb in #397
    • Collection.Assign() has been removed after a sunset period
      by @ti-mo in #371

Features

  • elf: support cgroup getsockname/getpeername prog by @zf1575192187 in #350
  • MapType probe API by @rgo3 in #321
  • link/uprobe: support filtering by pid by @mmat11 in #342
  • Add support for freplace programs by @zeffron in #288
  • Export CollectionSpec.ByteOrder by @ti-mo in #361
  • Support ELF map definitions larger than bpf_map_def by @ti-mo in #362
  • Auto-populate tail-call and map-in-map maps from ELF/BTF by @ti-mo in #363
  • features: add HaveProgType API by @rgo3 in #355
  • feature: add call fixups for bpf_probe_read_kernel, etc by @xh4n3 in #367
  • cmd/bpf2go: use Go 1.16 embed to include BPF elfs by @lmb in #327
  • bpf2go: add support for bpf_tracing.h by @lmb in #369
  • features: support get map ids from program. by @arikachen in #391
  • Recognize sk_reuseport programs by @lmb in #393
  • btf: handle float relocation for CO-RE by @lmb in #403
  • Utility function to remove memlock rlimit by @folbricht in #392
  • BPF ring buffer by @mythi in #318

Bug Fixes

  • link/uprobe: handle ENOTSUPP from the kernel's prepare_uprobe() by @ti-mo in #351
  • Mark PerCPUCGroupStorage as per-cpu by @yadutaf in #341
  • link/kprobe: don't redeclare a new variable sp by @guodongzz in #365
  • Fix invalid usage of reflect.SliceHeader by @cuonglm in #376
  • program: don't retrieve map ids by default by @lmb in #395
  • link/uprobe: fix offsets for statically linked binaries by @mmat11 in #385
  • Add sync.Pool to reduce allocations for the default case in unmarshalBytes() by @rockdaboot in #420
  • Fix btf.FindType to avoid copy by @pippolo84 in #424
  • Fix missing close of fds from BPF{ProgLoad,MapCreate} by @pippolo84 in #428
  • Directly handle int32 and int64 types in unmarshalBytes() by @rockdaboot in #427

Examples

  • Add kprobepin example showing how to re-use a pinned map in a BPF prog by @ungureanuvladvictor in #364
  • examples: adapt uretprobe example to the new library version by @mmat11 in #389
  • CI: build examples by @lmb in #390
  • Add a script to update vendored libbpf headers for examples by @markpash in #394
  • Add an example for the RINGBUF map type by @pippolo84 in #412
  • Add a tracepoint example and a percpu example by @hao-lee in #402
  • examples - convert to new rlimit package for memlock removal by @ti-mo in #441

New Contributors

This release saw a record amount of new contributors! We'd like to wish everyone a warm welcome and thank you all for your support!

Full Changelog: v0.6.2...v0.7.0

Wrap SYS_BPF errors, user-provided uprobe offsets, support new map, program and flag types

12 Jul 13:01

Choose a tag to compare

Breaking changes

  • None

Features

  • Return friendly error when creating maps with BPF_F_MMAPABLE or BPF_F_INNER_MAP and the kernel doesn't support them.
  • Add support for StructOps, RingBuf, InodeStorage and TaskStorage map types.
  • Support many new BPF program types added over the course of 2019/2020 in the assembler.
  • Detect fentry, fmod_ret and fexit programs by their ELF section names.
  • link: support user-provided offsets for uprobe locations by specifying UprobeOptions.
  • link: support creating bpf_map_elem iterators
  • Wrap and propagate all errors generated by SYS_BPF, allowing the caller to retrieve

Bug Fixes

  • Fix flaky TestMapPin test on Go 1.17beta1

Deprecations

  • ebpf.ErrNotExist is now an alias to os.ErrNotExist and will be removed in a future release.

Examples

  • Docstring fixup in kprobe example

Contributors

Chris Tarazi
Lorenz Bauer
Mattia Meleleo
Mikko Ylinen
Robin Gögge
Tobias Klauser

Thank you for your work!

v0.6.1

11 Jun 13:21

Choose a tag to compare

Breaking changes

  • None

Features

  • link.Raw{At,De}tachProgram now wraps and returns the underlying error returned by the kernel. Note: this is not an API contract, so use at your own discretion. This was added temporarily for kernel feature detection purposes, and a proper feature detection API will replace this in the near future.
  • link.K(ret)probe now automatically prefixes the given symbol with the conventional prefix for syscall wrappers (e.g. __x64_ when running on amd64)

Examples

  • The kprobe example now hooks the sys_execve syscall wrapper by its common name rather than the x64 variant

Contributors

Aleksa Sarai
Lorenz Bauer
Nikolay Nikolaev
Robin Gögge

Thank you for your work!

CO-RE support

28 May 13:02
@lmb lmb

Choose a tag to compare

The library now supports most kinds of CO-RE relocations!

Breaking changes

  • None

Features

  • CO-RE relocations make writing portable kprobes a lot easier. We now have support for a good chunk of them.
  • kretprobes are a little more robust to kernel ABI changes.
  • uprobes and uretprobes are now supported.
  • ProgramOptions has a TargetBTF member which allows specifying a custom target. Use this to support distro kernels that don't have built in BTF.
  • raw_tp and tp_btf sections are now recognised.
  • compatibility with libbpf has increased.
  • PerfEventArray should now be useable without having to change PerfEventArray.MaxEntries.

Examples

  • The uprobe example uses the new API in link.

Contributors

Gilberto Bertin
Lorenz Bauer
Mattia
Mattia Meleleo
nevermosby
Timo Beckers

Thank you for your work!

K(ret)probe and Tracepoint support

08 Apr 15:29
ef54c30

Choose a tag to compare

This release brings support for attaching to k(ret)probes and tracepoints out of the box!
See the kprobe and tracepoint examples.

Breaking changes

  • All LoadPinned*() functions now take LoadPinOptions to control loader behaviour.
    Simply pass nil to load with default options.
    • LoadPinnedMap()
    • LoadPinnedProgram()
    • LoadPinnedCgroup()
    • LoadPinnedIter()
    • LoadPinnedRawLink()
    • LoadPinnedNetNs()

Bug fixes

  • Program.IsPinned() now behaves correctly on maps loaded from bpffs
  • Map.Pin() no longer clobbers the destination file if it already exists

Features

  • Attaching to k(ret)probes and tracepoints can now be done with link.Kprobe(), link.Kretprobe() and link.Tracepoint()
  • Programs of type Kprobe automatically get their KernelVersion fields populated by detecting the kernel version at runtime
  • MapOptions now contains a LoadPinOptions
  • ProgSpec now contains a Flags field, adding support for BPF_F_SLEEPABLE
  • Made BTF map loader more flexible by looping over Vars in a BTF data section
  • Pinned Maps and Programs can now be loaded from bpffs in read-or write-only mode
  • Added golangci-lint project configuration, running in CI

Examples

  • kprobe and tracepoint examples updated to use the new link.Kprobe() and link.Tracepoint() API
  • There is now an example for how to attach eBPF programs to uprobes

Contributors

Aditi Ghag
Florian Lehner
Lorenz Bauer
Mattia Meleleo
Mikko Ylinen
Timo Beckers
Vlad Ungureanu

Thank you for your work!