github.com/cilium/ebpf@v0.10.0/README.md (about)

     1  # eBPF
     2  
     3  [![PkgGoDev](https://pkg.go.dev/badge/github.com/cilium/ebpf)](https://pkg.go.dev/github.com/cilium/ebpf)
     4  
     5  ![HoneyGopher](.github/images/cilium-ebpf.png)
     6  
     7  ebpf-go is a pure Go library that provides utilities for loading, compiling, and
     8  debugging eBPF programs. It has minimal external dependencies and is intended to
     9  be used in long running processes.
    10  
    11  See [ebpf.io](https://ebpf.io) for complementary projects from the wider eBPF
    12  ecosystem.
    13  
    14  ## Getting Started
    15  
    16  A small collection of Go and eBPF programs that serve as examples for building
    17  your own tools can be found under [examples/](examples/).
    18  
    19  Contributions are highly encouraged, as they highlight certain use cases of
    20  eBPF and the library, and help shape the future of the project.
    21  
    22  ## Getting Help
    23  
    24  The community actively monitors our [GitHub Discussions](https://github.com/cilium/ebpf/discussions) page.
    25  Please search for existing threads before starting a new one. Refrain from
    26  opening issues on the bug tracker if you're just starting out or if you're not
    27  sure if something is a bug in the library code.
    28  
    29  Alternatively, [join](https://ebpf.io/slack) the
    30  [#ebpf-go](https://cilium.slack.com/messages/ebpf-go) channel on Slack if you
    31  have other questions regarding the project. Note that this channel is ephemeral
    32  and has its history erased past a certain point, which is less helpful for
    33  others running into the same problem later.
    34  
    35  ## Packages
    36  
    37  This library includes the following packages:
    38  
    39  * [asm](https://pkg.go.dev/github.com/cilium/ebpf/asm) contains a basic
    40    assembler, allowing you to write eBPF assembly instructions directly
    41    within your Go code. (You don't need to use this if you prefer to write your eBPF program in C.)
    42  * [cmd/bpf2go](https://pkg.go.dev/github.com/cilium/ebpf/cmd/bpf2go) allows
    43    compiling and embedding eBPF programs written in C within Go code. As well as
    44    compiling the C code, it auto-generates Go code for loading and manipulating
    45    the eBPF program and map objects.
    46  * [link](https://pkg.go.dev/github.com/cilium/ebpf/link) allows attaching eBPF
    47    to various hooks
    48  * [perf](https://pkg.go.dev/github.com/cilium/ebpf/perf) allows reading from a
    49    `PERF_EVENT_ARRAY`
    50  * [ringbuf](https://pkg.go.dev/github.com/cilium/ebpf/ringbuf) allows reading from a
    51    `BPF_MAP_TYPE_RINGBUF` map
    52  * [features](https://pkg.go.dev/github.com/cilium/ebpf/features) implements the equivalent
    53    of `bpftool feature probe` for discovering BPF-related kernel features using native Go.
    54  * [rlimit](https://pkg.go.dev/github.com/cilium/ebpf/rlimit) provides a convenient API to lift
    55    the `RLIMIT_MEMLOCK` constraint on kernels before 5.11.
    56  
    57  ## Requirements
    58  
    59  * A version of Go that is [supported by
    60    upstream](https://golang.org/doc/devel/release.html#policy)
    61  * Linux >= 4.9. CI is run against kernel.org LTS releases. 4.4 should work but is
    62    not tested against.
    63  
    64  ## Regenerating Testdata
    65  
    66  Run `make` in the root of this repository to rebuild testdata in all
    67  subpackages. This requires Docker, as it relies on a standardized build
    68  environment to keep the build output stable.
    69  
    70  It is possible to regenerate data using Podman by overriding the `CONTAINER_*`
    71  variables: `CONTAINER_ENGINE=podman CONTAINER_RUN_ARGS= make`.
    72  
    73  The toolchain image build files are kept in [testdata/docker/](testdata/docker/).
    74  
    75  ## License
    76  
    77  MIT
    78  
    79  ### eBPF Gopher
    80  
    81  The eBPF honeygopher is based on the Go gopher designed by Renee French.