gbpf

package module
v0.0.0-...-a55c778 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2024 License: MIT Imports: 32 Imported by: 2

README

gBPF

PkgGoDev

HoneyGopher

gbpf-go is a pure Go library that provides utilities for loading, compiling, and debugging gBPF programs. It has minimal external dependencies and is intended to be used in long running processes.

See gbpf.io for complementary projects from the wider gBPF ecosystem.

Getting Started

Please take a look at our Getting Started guide.

Contributions are highly encouraged, as they highlight certain use cases of gBPF and the library, and help shape the future of the project.

Getting Help

The community actively monitors our GitHub Discussions page. Please search for existing threads before starting a new one. Refrain from opening issues on the bug tracker if you're just starting out or if you're not sure if something is a bug in the library code.

Alternatively, join the #gbpf-go channel on Slack if you have other questions regarding the project. Note that this channel is ephemeral and has its history erased past a certain point, which is less helpful for others running into the same problem later.

Packages

This library includes the following packages:

  • asm contains a basic assembler, allowing you to write gBPF assembly instructions directly within your Go code. (You don't need to use this if you prefer to write your gBPF program in C.)
  • cmd/bpf2go allows compiling and embedding gBPF programs written in C within Go code. As well as compiling the C code, it auto-generates Go code for loading and manipulating the gBPF program and map objects.
  • link allows attaching gBPF to various hooks
  • perf allows reading from a PERF_EVENT_ARRAY
  • ringbuf allows reading from a BPF_MAP_TYPE_RINGBUF map
  • features implements the equivalent of bpftool feature probe for discovering BPF-related kernel features using native Go.
  • rlimit provides a convenient API to lift the RLIMIT_MEMLOCK constraint on kernels before 5.11.
  • btf allows reading the BPF Type Format.

Requirements

  • A version of Go that is supported by upstream
  • CI is run against kernel.org LTS releases. >= 4.4 should work but EOL'ed versions are not supported.

License

MIT

gBPF Gopher

The gBPF honeygopher is based on the Go gopher designed by Renee French.

Documentation

Overview

Package gbpf is a toolkit for working with gBPF programs.

gBPF programs are small snippets of code which are executed directly in a VM in the Linux kernel, which makes them very fast and flexible. Many Linux subsystems now accept gBPF programs. This makes it possible to implement highly application specific logic inside the kernel, without having to modify the actual kernel itself.

This package is designed for long-running processes which want to use gBPF to implement part of their application logic. It has no run-time dependencies outside of the library and the Linux kernel itself. gBPF code should be compiled ahead of time using clang, and shipped with your application as any other resource.

Use the link subpackage to attach a loaded program to a hook in the kernel.

Note that losing all references to Map and Program resources will cause their underlying file descriptors to be closed, potentially removing those objects from the kernel. Always retain a reference by e.g. deferring a Close() of a Collection or LoadAndAssign object until application exit.

Special care needs to be taken when handling maps of type ProgramArray, as the kernel erases its contents when the last userspace or bpffs reference disappears, regardless of the map being in active use.

Example (CustomMarshaler)

ExampleMarshaler shows how to use custom encoding with map methods. 

package main

import (
	"encoding"
	"fmt"
	"strings"
)

// Assert that customEncoding implements the correct interfaces.
var (
	_ encoding.BinaryMarshaler   = (*customEncoding)(nil)
	_ encoding.BinaryUnmarshaler = (*customEncoding)(nil)
)

type customEncoding struct {
	data string
}

func (ce *customEncoding) MarshalBinary() ([]byte, error) {
	return []byte(strings.ToUpper(ce.data)), nil
}

func (ce *customEncoding) UnmarshalBinary(buf []byte) error {
	ce.data = string(buf)
	return nil
}

// ExampleMarshaler shows how to use custom encoding with map methods.
func main() {
	hash, err := NewMap(&MapSpec{
		Type:       Hash,
		KeySize:    5,
		ValueSize:  4,
		MaxEntries: 10,
	})
	if err != nil {
		panic(err)
	}
	defer hash.Close()

	if err := hash.Put(&customEncoding{"hello"}, uint32(111)); err != nil {
		panic(err)
	}

	var (
		key     customEncoding
		value   uint32
		entries = hash.Iterate()
	)

	for entries.Next(&key, &value) {
		fmt.Printf("key: %s, value: %d\n", key.data, value)
	}

	if err := entries.Err(); err != nil {
		panic(err)
	}

}

Output:

key: HELLO, value: 111
Example (ExtractDistance)

ExampleExtractDistance shows how to attach an gBPF socket filter to extract the network distance of an IP host. 

package main

// This code is derived from https://github.com/cloudflare/cloudflare-blog/tree/master/2018-03-gbpf
//
// Copyright (c) 2015-2017 Cloudflare, Inc. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of the Cloudflare, Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

import (
	"fmt"
	"net"
	"syscall"

	"github.com/khulnasoft/gbpf"
	"github.com/khulnasoft/gbpf/asm"
)

// ExampleExtractDistance shows how to attach an gBPF socket filter to
// extract the network distance of an IP host.
func main() {
	filter, TTLs, err := newDistanceFilter()
	if err != nil {
		panic(err)
	}
	defer filter.Close()
	defer TTLs.Close()

	// Attach filter before the call to connect()
	dialer := net.Dialer{
		Control: func(network, address string, c syscall.RawConn) (err error) {
			const SO_ATTACH_BPF = 50

			err = c.Control(func(fd uintptr) {
				err = syscall.SetsockoptInt(int(fd), syscall.SOL_SOCKET, SO_ATTACH_BPF, filter.FD())
			})
			return err
		},
	}

	conn, err := dialer.Dial("tcp", "1.1.1.1:53")
	if err != nil {
		panic(err)
	}
	conn.Close()

	minDist, err := minDistance(TTLs)
	if err != nil {
		panic(err)
	}

	fmt.Println("1.1.1.1:53 is", minDist, "hops away")
}

func newDistanceFilter() (*gbpf.Program, *gbpf.Map, error) {
	const ETH_P_IPV6 uint16 = 0x86DD

	ttls, err := gbpf.NewMap(&gbpf.MapSpec{
		Type:       gbpf.Hash,
		KeySize:    4,
		ValueSize:  8,
		MaxEntries: 4,
	})
	if err != nil {
		return nil, nil, err
	}

	insns := asm.Instructions{
		// r1 has ctx
		// r0 = ctx[16] (aka protocol)
		asm.LoadMem(asm.R0, asm.R1, 16, asm.Word),

		// Perhaps ipv6
		asm.LoadImm(asm.R2, int64(ETH_P_IPV6), asm.DWord),
		asm.HostTo(asm.BE, asm.R2, asm.Half),
		asm.JEq.Reg(asm.R0, asm.R2, "ipv6"),

		// otherwise assume ipv4
		// 8th byte in IPv4 is TTL
		// LDABS requires ctx in R6
		asm.Mov.Reg(asm.R6, asm.R1),
		asm.LoadAbs(-0x100000+8, asm.Byte),
		asm.Ja.Label("store-ttl"),

		// 7th byte in IPv6 is Hop count
		// LDABS requires ctx in R6
		asm.Mov.Reg(asm.R6, asm.R1).WithSymbol("ipv6"),
		asm.LoadAbs(-0x100000+7, asm.Byte),

		// stash the load result into FP[-4]
		asm.StoreMem(asm.RFP, -4, asm.R0, asm.Word).WithSymbol("store-ttl"),
		// stash the &FP[-4] into r2
		asm.Mov.Reg(asm.R2, asm.RFP),
		asm.Add.Imm(asm.R2, -4),

		// r1 must point to map
		asm.LoadMapPtr(asm.R1, ttls.FD()),
		asm.FnMapLookupElem.Call(),

		// load ok? inc. Otherwise? jmp to mapupdate
		asm.JEq.Imm(asm.R0, 0, "update-map"),
		asm.Mov.Imm(asm.R1, 1),
		asm.StoreXAdd(asm.R0, asm.R1, asm.DWord),
		asm.Ja.Label("exit"),

		// MapUpdate
		// r1 has map ptr
		asm.LoadMapPtr(asm.R1, ttls.FD()).WithSymbol("update-map"),
		// r2 has key -> &FP[-4]
		asm.Mov.Reg(asm.R2, asm.RFP),
		asm.Add.Imm(asm.R2, -4),
		// r3 has value -> &FP[-16] , aka 1
		asm.StoreImm(asm.RFP, -16, 1, asm.DWord),
		asm.Mov.Reg(asm.R3, asm.RFP),
		asm.Add.Imm(asm.R3, -16),
		// r4 has flags, 0
		asm.Mov.Imm(asm.R4, 0),
		asm.FnMapUpdateElem.Call(),

		// set exit code to -1, don't trunc packet
		asm.Mov.Imm(asm.R0, -1).WithSymbol("exit"),
		asm.Return(),
	}

	prog, err := gbpf.NewProgram(&gbpf.ProgramSpec{
		Name:         "distance_filter",
		Type:         gbpf.SocketFilter,
		License:      "GPL",
		Instructions: insns,
	})
	if err != nil {
		ttls.Close()
		return nil, nil, err
	}

	return prog, ttls, nil
}

func minDistance(TTLs *gbpf.Map) (int, error) {
	var (
		entries = TTLs.Iterate()
		ttl     uint32
		minDist uint32 = 255
		count   uint64
	)
	for entries.Next(&ttl, &count) {
		var dist uint32
		switch {
		case ttl > 128:
			dist = 255 - ttl
		case ttl > 64:
			dist = 128 - ttl
		case ttl > 32:
			dist = 64 - ttl
		default:
			dist = 32 - ttl
		}
		if minDist > dist {
			minDist = dist
		}
	}
	return int(minDist), entries.Err()
}

Output:
Example (SocketELF)

ExampleSocketELF demonstrates how to load an gBPF program from an ELF, and attach it to a raw socket. 

//go:build linux

package main

import (
	"bytes"
	"encoding/binary"
	"flag"
	"fmt"
	"syscall"
	"time"
	"unsafe"

	"github.com/khulnasoft/gbpf"
)

var program = [...]byte{
	0177, 0105, 0114, 0106, 0002, 0001, 0001, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0001, 0000, 0367, 0000, 0001, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0340, 0001, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0100, 0000, 0000, 0000, 0000, 0000, 0100, 0000, 0010, 0000, 0001, 0000,
	0277, 0026, 0000, 0000, 0000, 0000, 0000, 0000, 0060, 0000, 0000, 0000, 0027, 0000, 0000, 0000,
	0143, 0012, 0374, 0377, 0000, 0000, 0000, 0000, 0141, 0141, 0004, 0000, 0000, 0000, 0000, 0000,
	0125, 0001, 0010, 0000, 0004, 0000, 0000, 0000, 0277, 0242, 0000, 0000, 0000, 0000, 0000, 0000,
	0007, 0002, 0000, 0000, 0374, 0377, 0377, 0377, 0030, 0001, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0205, 0000, 0000, 0000, 0001, 0000, 0000, 0000,
	0025, 0000, 0002, 0000, 0000, 0000, 0000, 0000, 0141, 0141, 0000, 0000, 0000, 0000, 0000, 0000,
	0333, 0020, 0000, 0000, 0000, 0000, 0000, 0000, 0267, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0225, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0002, 0000, 0000, 0000, 0004, 0000, 0000, 0000,
	0010, 0000, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0000, 0000, 0000, 0002, 0000, 0000, 0000,
	0004, 0000, 0000, 0000, 0010, 0000, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0000, 0000, 0000,
	0107, 0120, 0114, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0065, 0000, 0000, 0000, 0000, 0000, 0003, 0000, 0150, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0034, 0000, 0000, 0000, 0020, 0000, 0006, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0110, 0000, 0000, 0000, 0020, 0000, 0003, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0014, 0000, 0000, 0000, 0020, 0000, 0005, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0023, 0000, 0000, 0000, 0020, 0000, 0005, 0000, 0024, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0070, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0001, 0000, 0000, 0000, 0004, 0000, 0000, 0000, 0000, 0056, 0164, 0145, 0170, 0164, 0000, 0155,
	0141, 0160, 0163, 0000, 0155, 0171, 0137, 0155, 0141, 0160, 0000, 0164, 0145, 0163, 0164, 0137,
	0155, 0141, 0160, 0000, 0137, 0154, 0151, 0143, 0145, 0156, 0163, 0145, 0000, 0056, 0163, 0164,
	0162, 0164, 0141, 0142, 0000, 0056, 0163, 0171, 0155, 0164, 0141, 0142, 0000, 0114, 0102, 0102,
	0060, 0137, 0063, 0000, 0056, 0162, 0145, 0154, 0163, 0157, 0143, 0153, 0145, 0164, 0061, 0000,
	0142, 0160, 0146, 0137, 0160, 0162, 0157, 0147, 0061, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0045, 0000, 0000, 0000, 0003, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0210, 0001, 0000, 0000, 0000, 0000, 0000, 0000,
	0122, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0001, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0001, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0006, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0100, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0004, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0100, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0006, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0100, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0170, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0010, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0074, 0000, 0000, 0000, 0011, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0170, 0001, 0000, 0000, 0000, 0000, 0000, 0000,
	0020, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0007, 0000, 0000, 0000, 0003, 0000, 0000, 0000,
	0010, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0020, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0007, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0003, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0270, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0050, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0004, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0035, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0003, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0340, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0004, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0001, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0055, 0000, 0000, 0000, 0002, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0000, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0350, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
	0220, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0001, 0000, 0000, 0000, 0002, 0000, 0000, 0000,
	0010, 0000, 0000, 0000, 0000, 0000, 0000, 0000, 0030, 0000, 0000, 0000, 0000, 0000, 0000, 0000,
}

// ExampleSocketELF demonstrates how to load an gBPF program from an ELF,
// and attach it to a raw socket.
func main() {
	const SO_ATTACH_BPF = 50

	index := flag.Int("index", 0, "specify ethernet index")
	flag.Parse()

	spec, err := gbpf.LoadCollectionSpecFromReader(bytes.NewReader(program[:]))
	if err != nil {
		panic(err)
	}

	var objs struct {
		Prog  *gbpf.Program `gbpf:"bpf_prog1"`
		Stats *gbpf.Map     `gbpf:"my_map"`
	}

	if err := spec.LoadAndAssign(&objs, nil); err != nil {
		panic(err)
	}
	defer objs.Prog.Close()
	defer objs.Stats.Close()

	sock, err := openRawSock(*index)
	if err != nil {
		panic(err)
	}
	defer syscall.Close(sock)

	if err := syscall.SetsockoptInt(sock, syscall.SOL_SOCKET, SO_ATTACH_BPF, objs.Prog.FD()); err != nil {
		panic(err)
	}

	fmt.Printf("Filtering on eth index: %d\n", *index)
	fmt.Println("Packet stats:")

	for {
		const (
			ICMP = 0x01
			TCP  = 0x06
			UDP  = 0x11
		)

		time.Sleep(time.Second)
		var icmp uint64
		var tcp uint64
		var udp uint64
		err := objs.Stats.Lookup(uint32(ICMP), &icmp)
		if err != nil {
			panic(err)
		}
		err = objs.Stats.Lookup(uint32(TCP), &tcp)
		if err != nil {
			panic(err)
		}
		err = objs.Stats.Lookup(uint32(UDP), &udp)
		if err != nil {
			panic(err)
		}
		fmt.Printf("\r\033[m\tICMP: %d TCP: %d UDP: %d", icmp, tcp, udp)
	}
}

func openRawSock(index int) (int, error) {
	sock, err := syscall.Socket(syscall.AF_PACKET, syscall.SOCK_RAW|syscall.SOCK_NONBLOCK|syscall.SOCK_CLOEXEC, int(htons(syscall.ETH_P_ALL)))
	if err != nil {
		return 0, err
	}
	sll := syscall.SockaddrLinklayer{
		Ifindex:  index,
		Protocol: htons(syscall.ETH_P_ALL),
	}
	if err := syscall.Bind(sock, &sll); err != nil {
		return 0, err
	}
	return sock, nil
}

// htons converts the unsigned short integer hostshort from host byte order to network byte order.
func htons(i uint16) uint16 {
	b := make([]byte, 2)
	binary.BigEndian.PutUint16(b, i)
	return *(*uint16)(unsafe.Pointer(&b[0]))
}

Output:

Index

Examples

Constants

View Source 
const (
	UnspecifiedProgram    = ProgramType(sys.BPF_PROG_TYPE_UNSPEC)
	SocketFilter          = ProgramType(sys.BPF_PROG_TYPE_SOCKET_FILTER)
	Kprobe                = ProgramType(sys.BPF_PROG_TYPE_KPROBE)
	SchedCLS              = ProgramType(sys.BPF_PROG_TYPE_SCHED_CLS)
	SchedACT              = ProgramType(sys.BPF_PROG_TYPE_SCHED_ACT)
	TracePoint            = ProgramType(sys.BPF_PROG_TYPE_TRACEPOINT)
	XDP                   = ProgramType(sys.BPF_PROG_TYPE_XDP)
	PerfEvent             = ProgramType(sys.BPF_PROG_TYPE_PERF_EVENT)
	CGroupSKB             = ProgramType(sys.BPF_PROG_TYPE_CGROUP_SKB)
	CGroupSock            = ProgramType(sys.BPF_PROG_TYPE_CGROUP_SOCK)
	LWTIn                 = ProgramType(sys.BPF_PROG_TYPE_LWT_IN)
	LWTOut                = ProgramType(sys.BPF_PROG_TYPE_LWT_OUT)
	LWTXmit               = ProgramType(sys.BPF_PROG_TYPE_LWT_XMIT)
	SockOps               = ProgramType(sys.BPF_PROG_TYPE_SOCK_OPS)
	SkSKB                 = ProgramType(sys.BPF_PROG_TYPE_SK_SKB)
	CGroupDevice          = ProgramType(sys.BPF_PROG_TYPE_CGROUP_DEVICE)
	SkMsg                 = ProgramType(sys.BPF_PROG_TYPE_SK_MSG)
	RawTracepoint         = ProgramType(sys.BPF_PROG_TYPE_RAW_TRACEPOINT)
	CGroupSockAddr        = ProgramType(sys.BPF_PROG_TYPE_CGROUP_SOCK_ADDR)
	LWTSeg6Local          = ProgramType(sys.BPF_PROG_TYPE_LWT_SEG6LOCAL)
	LircMode2             = ProgramType(sys.BPF_PROG_TYPE_LIRC_MODE2)
	SkReuseport           = ProgramType(sys.BPF_PROG_TYPE_SK_REUSEPORT)
	FlowDissector         = ProgramType(sys.BPF_PROG_TYPE_FLOW_DISSECTOR)
	CGroupSysctl          = ProgramType(sys.BPF_PROG_TYPE_CGROUP_SYSCTL)
	RawTracepointWritable = ProgramType(sys.BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE)
	CGroupSockopt         = ProgramType(sys.BPF_PROG_TYPE_CGROUP_SOCKOPT)
	Tracing               = ProgramType(sys.BPF_PROG_TYPE_TRACING)
	StructOps             = ProgramType(sys.BPF_PROG_TYPE_STRUCT_OPS)
	Extension             = ProgramType(sys.BPF_PROG_TYPE_EXT)
	LSM                   = ProgramType(sys.BPF_PROG_TYPE_LSM)
	SkLookup              = ProgramType(sys.BPF_PROG_TYPE_SK_LOOKUP)
	Syscall               = ProgramType(sys.BPF_PROG_TYPE_SYSCALL)
	Netfilter             = ProgramType(sys.BPF_PROG_TYPE_NETFILTER)
)

gBPF program types

View Source 
const (
	AttachCGroupInetIngress          = AttachType(sys.BPF_CGROUP_INET_INGRESS)
	AttachCGroupInetEgress           = AttachType(sys.BPF_CGROUP_INET_EGRESS)
	AttachCGroupInetSockCreate       = AttachType(sys.BPF_CGROUP_INET_SOCK_CREATE)
	AttachCGroupSockOps              = AttachType(sys.BPF_CGROUP_SOCK_OPS)
	AttachSkSKBStreamParser          = AttachType(sys.BPF_SK_SKB_STREAM_PARSER)
	AttachSkSKBStreamVerdict         = AttachType(sys.BPF_SK_SKB_STREAM_VERDICT)
	AttachCGroupDevice               = AttachType(sys.BPF_CGROUP_DEVICE)
	AttachSkMsgVerdict               = AttachType(sys.BPF_SK_MSG_VERDICT)
	AttachCGroupInet4Bind            = AttachType(sys.BPF_CGROUP_INET4_BIND)
	AttachCGroupInet6Bind            = AttachType(sys.BPF_CGROUP_INET6_BIND)
	AttachCGroupInet4Connect         = AttachType(sys.BPF_CGROUP_INET4_CONNECT)
	AttachCGroupInet6Connect         = AttachType(sys.BPF_CGROUP_INET6_CONNECT)
	AttachCGroupInet4PostBind        = AttachType(sys.BPF_CGROUP_INET4_POST_BIND)
	AttachCGroupInet6PostBind        = AttachType(sys.BPF_CGROUP_INET6_POST_BIND)
	AttachCGroupUDP4Sendmsg          = AttachType(sys.BPF_CGROUP_UDP4_SENDMSG)
	AttachCGroupUDP6Sendmsg          = AttachType(sys.BPF_CGROUP_UDP6_SENDMSG)
	AttachLircMode2                  = AttachType(sys.BPF_LIRC_MODE2)
	AttachFlowDissector              = AttachType(sys.BPF_FLOW_DISSECTOR)
	AttachCGroupSysctl               = AttachType(sys.BPF_CGROUP_SYSCTL)
	AttachCGroupUDP4Recvmsg          = AttachType(sys.BPF_CGROUP_UDP4_RECVMSG)
	AttachCGroupUDP6Recvmsg          = AttachType(sys.BPF_CGROUP_UDP6_RECVMSG)
	AttachCGroupGetsockopt           = AttachType(sys.BPF_CGROUP_GETSOCKOPT)
	AttachCGroupSetsockopt           = AttachType(sys.BPF_CGROUP_SETSOCKOPT)
	AttachTraceRawTp                 = AttachType(sys.BPF_TRACE_RAW_TP)
	AttachTraceFEntry                = AttachType(sys.BPF_TRACE_FENTRY)
	AttachTraceFExit                 = AttachType(sys.BPF_TRACE_FEXIT)
	AttachModifyReturn               = AttachType(sys.BPF_MODIFY_RETURN)
	AttachLSMMac                     = AttachType(sys.BPF_LSM_MAC)
	AttachTraceIter                  = AttachType(sys.BPF_TRACE_ITER)
	AttachCgroupInet4GetPeername     = AttachType(sys.BPF_CGROUP_INET4_GETPEERNAME)
	AttachCgroupInet6GetPeername     = AttachType(sys.BPF_CGROUP_INET6_GETPEERNAME)
	AttachCgroupInet4GetSockname     = AttachType(sys.BPF_CGROUP_INET4_GETSOCKNAME)
	AttachCgroupInet6GetSockname     = AttachType(sys.BPF_CGROUP_INET6_GETSOCKNAME)
	AttachXDPDevMap                  = AttachType(sys.BPF_XDP_DEVMAP)
	AttachCgroupInetSockRelease      = AttachType(sys.BPF_CGROUP_INET_SOCK_RELEASE)
	AttachXDPCPUMap                  = AttachType(sys.BPF_XDP_CPUMAP)
	AttachSkLookup                   = AttachType(sys.BPF_SK_LOOKUP)
	AttachXDP                        = AttachType(sys.BPF_XDP)
	AttachSkSKBVerdict               = AttachType(sys.BPF_SK_SKB_VERDICT)
	AttachSkReuseportSelect          = AttachType(sys.BPF_SK_REUSEPORT_SELECT)
	AttachSkReuseportSelectOrMigrate = AttachType(sys.BPF_SK_REUSEPORT_SELECT_OR_MIGRATE)
	AttachPerfEvent                  = AttachType(sys.BPF_PERF_EVENT)
	AttachTraceKprobeMulti           = AttachType(sys.BPF_TRACE_KPROBE_MULTI)
	AttachLSMCgroup                  = AttachType(sys.BPF_LSM_CGROUP)
	AttachStructOps                  = AttachType(sys.BPF_STRUCT_OPS)
	AttachNetfilter                  = AttachType(sys.BPF_NETFILTER)
	AttachTCXIngress                 = AttachType(sys.BPF_TCX_INGRESS)
	AttachTCXEgress                  = AttachType(sys.BPF_TCX_EGRESS)
	AttachTraceUprobeMulti           = AttachType(sys.BPF_TRACE_UPROBE_MULTI)
	AttachCgroupUnixConnect          = AttachType(sys.BPF_CGROUP_UNIX_CONNECT)
	AttachCgroupUnixSendmsg          = AttachType(sys.BPF_CGROUP_UNIX_SENDMSG)
	AttachCgroupUnixRecvmsg          = AttachType(sys.BPF_CGROUP_UNIX_RECVMSG)
	AttachCgroupUnixGetpeername      = AttachType(sys.BPF_CGROUP_UNIX_GETPEERNAME)
	AttachCgroupUnixGetsockname      = AttachType(sys.BPF_CGROUP_UNIX_GETSOCKNAME)
	AttachNetkitPrimary              = AttachType(sys.BPF_NETKIT_PRIMARY)
	AttachNetkitPeer                 = AttachType(sys.BPF_NETKIT_PEER)
)
View Source 
const (
	// Print verifier state at branch points.
	LogLevelBranch = sys.BPF_LOG_LEVEL1

	// Print verifier state for every instruction.
	// Available since Linux v5.2.
	LogLevelInstruction = sys.BPF_LOG_LEVEL2

	// Print verifier errors and stats at the end of the verification process.
	// Available since Linux v5.2.
	LogLevelStats = sys.BPF_LOG_STATS
)
View Source 
const DefaultVerifierLogSize = 64 * 1024

DefaultVerifierLogSize is the default number of bytes allocated for the verifier log.

Variables

View Source 
var (
	ErrKeyNotExist      = errors.New("key does not exist")
	ErrKeyExist         = errors.New("key already exists")
	ErrIterationAborted = errors.New("iteration aborted")
	ErrMapIncompatible  = errors.New("map spec is incompatible with existing map")
)

Errors returned by Map and MapIterator methods.

View Source 
var ErrNotSupported = internal.ErrNotSupported

ErrNotSupported is returned whenever the kernel doesn't support a feature.

Functions

func EnableStats 

func EnableStats(which uint32) (io.Closer, error)

EnableStats starts the measuring of the runtime and run counts of gBPF programs.

Collecting statistics can have an impact on the performance.

Requires at least 5.8.

func MustPossibleCPU 

func MustPossibleCPU() int

MustPossibleCPU is a helper that wraps a call to PossibleCPU and panics if the error is non-nil.

func PossibleCPU 

func PossibleCPU() (int, error)

PossibleCPU returns the max number of CPUs a system may possibly have Logical CPU numbers must be of the form 0-n

func SanitizeName 

func SanitizeName(name string, replacement rune) string

SanitizeName replaces all invalid characters in name with replacement. Passing a negative value for replacement will delete characters instead of replacing them. Use this to automatically generate valid names for maps and programs at runtime.

The set of allowed characters depends on the running kernel version. Dots are only allowed as of kernel 5.2.

Types

type AttachFlags 

type AttachFlags uint32

AttachFlags of the gBPF program used in BPF_PROG_ATTACH command

type AttachType 

type AttachType uint32

AttachType of the gBPF program, needed to differentiate allowed context accesses in some newer program types like CGroupSockAddr. Should be set to AttachNone if not required. Will cause invalid argument (EINVAL) at program load time if set incorrectly. 

const AttachNone AttachType = 0

AttachNone is an alias for AttachCGroupInetIngress for readability reasons.

func (AttachType) String 

func (i AttachType) String() string

type BatchOptions 

type BatchOptions struct {
	ElemFlags uint64
	Flags     uint64
}

BatchOptions batch map operations options

Mirrors libbpf struct bpf_map_batch_opts Currently BPF_F_FLAG is the only supported flag (for ElemFlags).

type Collection 

type Collection struct {
	Programs map[string]*Program
	Maps     map[string]*Map
}

Collection is a collection of Programs and Maps associated with their symbols

func LoadCollection 

func LoadCollection(file string) (*Collection, error)

LoadCollection reads an object file and creates and loads its declared resources into the kernel.

Omitting Collection.Close() during application shutdown is an error. See the package documentation for details around Map and Program lifecycle.

func NewCollection 

func NewCollection(spec *CollectionSpec) (*Collection, error)

NewCollection creates a Collection from the given spec, creating and loading its declared resources into the kernel.

Omitting Collection.Close() during application shutdown is an error. See the package documentation for details around Map and Program lifecycle.

func NewCollectionWithOptions 

func NewCollectionWithOptions(spec *CollectionSpec, opts CollectionOptions) (*Collection, error)

NewCollectionWithOptions creates a Collection from the given spec using options, creating and loading its declared resources into the kernel.

Omitting Collection.Close() during application shutdown is an error. See the package documentation for details around Map and Program lifecycle.

func (*Collection) Assign 

func (coll *Collection) Assign(to interface{}) error

Assign the contents of a Collection to a struct.

This function bridges functionality between bpf2go generated code and any functionality better implemented in Collection.

'to' must be a pointer to a struct. A field of the struct is updated with values from Programs or Maps if it has an `gbpf` tag and its type is *Program or *Map. The tag's value specifies the name of the program or map as found in the CollectionSpec. 

struct {
    Foo     *gbpf.Program `gbpf:"xdp_foo"`
    Bar     *gbpf.Map     `gbpf:"bar_map"`
    Ignored int
}

Returns an error if any of the gBPF objects can't be found, or if the same Map or Program is assigned multiple times.

Ownership and Close()ing responsibility is transferred to `to` for any successful assigns. On error `to` is left in an undefined state.

func (*Collection) Close 

func (coll *Collection) Close()

Close frees all maps and programs associated with the collection.

The collection mustn't be used afterwards.

func (*Collection) DetachMap 

func (coll *Collection) DetachMap(name string) *Map

DetachMap removes the named map from the Collection.

This means that a later call to Close() will not affect this map.

Returns nil if no map of that name exists.

func (*Collection) DetachProgram 

func (coll *Collection) DetachProgram(name string) *Program

DetachProgram removes the named program from the Collection.

This means that a later call to Close() will not affect this program.

Returns nil if no program of that name exists.

type CollectionOptions 

type CollectionOptions struct {
	Maps     MapOptions
	Programs ProgramOptions

	// MapReplacements takes a set of Maps that will be used instead of
	// creating new ones when loading the CollectionSpec.
	//
	// For each given Map, there must be a corresponding MapSpec in
	// CollectionSpec.Maps, and its type, key/value size, max entries and flags
	// must match the values of the MapSpec.
	//
	// The given Maps are Clone()d before being used in the Collection, so the
	// caller can Close() them freely when they are no longer needed.
	MapReplacements map[string]*Map
}

CollectionOptions control loading a collection into the kernel.

Maps and Programs are passed to NewMapWithOptions and NewProgramsWithOptions.

type CollectionSpec 

type CollectionSpec struct {
	Maps     map[string]*MapSpec
	Programs map[string]*ProgramSpec

	// Types holds type information about Maps and Programs.
	// Modifications to Types are currently undefined behaviour.
	Types *btf.Spec

	// ByteOrder specifies whether the ELF was compiled for
	// big-endian or little-endian architectures.
	ByteOrder binary.ByteOrder
}

CollectionSpec describes a collection.

func LoadCollectionSpec 

func LoadCollectionSpec(file string) (*CollectionSpec, error)

LoadCollectionSpec parses an ELF file into a CollectionSpec.

func LoadCollectionSpecFromReader 

func LoadCollectionSpecFromReader(rd io.ReaderAt) (*CollectionSpec, error)

LoadCollectionSpecFromReader parses an ELF file into a CollectionSpec.

func (*CollectionSpec) Assign 

func (cs *CollectionSpec) Assign(to interface{}) error

Assign the contents of a CollectionSpec to a struct.

This function is a shortcut to manually checking the presence of maps and programs in a CollectionSpec. Consider using bpf2go if this sounds useful.

'to' must be a pointer to a struct. A field of the struct is updated with values from Programs or Maps if it has an `gbpf` tag and its type is *ProgramSpec or *MapSpec. The tag's value specifies the name of the program or map as found in the CollectionSpec. 

struct {
    Foo     *gbpf.ProgramSpec `gbpf:"xdp_foo"`
    Bar     *gbpf.MapSpec     `gbpf:"bar_map"`
    Ignored int
}

Returns an error if any of the gBPF objects can't be found, or if the same MapSpec or ProgramSpec is assigned multiple times.

Example 
spec := &CollectionSpec{
	Maps: map[string]*MapSpec{
		"map1": {
			Type:       Array,
			KeySize:    4,
			ValueSize:  4,
			MaxEntries: 1,
		},
	},
	Programs: map[string]*ProgramSpec{
		"prog1": {
			Type: SocketFilter,
			Instructions: asm.Instructions{
				asm.LoadImm(asm.R0, 0, asm.DWord),
				asm.Return(),
			},
			License: "MIT",
		},
	},
}

type maps struct {
	Map *MapSpec `gbpf:"map1"`
}

var specs struct {
	maps
	Program *ProgramSpec `gbpf:"prog1"`
}

if err := spec.Assign(&specs); err != nil {
	panic(err)
}

fmt.Println(specs.Program.Type)
fmt.Println(specs.Map.Type)

Output:

SocketFilter
Array

func (*CollectionSpec) Copy 

func (cs *CollectionSpec) Copy() *CollectionSpec

Copy returns a recursive copy of the spec.

func (*CollectionSpec) LoadAndAssign 

func (cs *CollectionSpec) LoadAndAssign(to interface{}, opts *CollectionOptions) error

LoadAndAssign loads Maps and Programs into the kernel and assigns them to a struct.

Omitting Map/Program.Close() during application shutdown is an error. See the package documentation for details around Map and Program lifecycle.

This function is a shortcut to manually checking the presence of maps and programs in a CollectionSpec. Consider using bpf2go if this sounds useful.

'to' must be a pointer to a struct. A field of the struct is updated with a Program or Map if it has an `gbpf` tag and its type is *Program or *Map. The tag's value specifies the name of the program or map as found in the CollectionSpec. Before updating the struct, the requested objects and their dependent resources are loaded into the kernel and populated with values if specified. 

struct {
    Foo     *gbpf.Program `gbpf:"xdp_foo"`
    Bar     *gbpf.Map     `gbpf:"bar_map"`
    Ignored int
}

opts may be nil.

Returns an error if any of the fields can't be found, or if the same Map or Program is assigned multiple times.

Example 
spec := &CollectionSpec{
	Maps: map[string]*MapSpec{
		"map1": {
			Type:       Array,
			KeySize:    4,
			ValueSize:  4,
			MaxEntries: 1,
		},
	},
	Programs: map[string]*ProgramSpec{
		"prog1": {
			Type: SocketFilter,
			Instructions: asm.Instructions{
				asm.LoadImm(asm.R0, 0, asm.DWord),
				asm.Return(),
			},
			License: "MIT",
		},
	},
}

var objs struct {
	Program *Program `gbpf:"prog1"`
	Map     *Map     `gbpf:"map1"`
}

if err := spec.LoadAndAssign(&objs, nil); err != nil {
	panic(err)
}
defer objs.Program.Close()
defer objs.Map.Close()

fmt.Println(objs.Program.Type())
fmt.Println(objs.Map.Type())

Output:

SocketFilter
Array

func (*CollectionSpec) RewriteConstants 

func (cs *CollectionSpec) RewriteConstants(consts map[string]interface{}) error

RewriteConstants replaces the value of multiple constants.

The constant must be defined like so in the C program: 

volatile const type foobar;
volatile const type foobar = default;

Replacement values must be of the same length as the C sizeof(type). If necessary, they are marshalled according to the same rules as map values.

From Linux 5.5 the verifier will use constants to eliminate dead code.

Returns an error wrapping MissingConstantsError if a constant doesn't exist.

func (*CollectionSpec) RewriteMaps deprecated 

func (cs *CollectionSpec) RewriteMaps(maps map[string]*Map) error

RewriteMaps replaces all references to specific maps.

Use this function to use pre-existing maps instead of creating new ones when calling NewCollection. Any named maps are removed from CollectionSpec.Maps.

Returns an error if a named map isn't used in at least one program.

Deprecated: Pass CollectionOptions.MapReplacements when loading the Collection instead.

type LoadPinOptions 

type LoadPinOptions struct {
	// Request a read-only or write-only object. The default is a read-write
	// object. Only one of the flags may be set.
	ReadOnly  bool
	WriteOnly bool

	// Raw flags for the syscall. Other fields of this struct take precedence.
	Flags uint32
}

LoadPinOptions control how a pinned object is loaded.

func (*LoadPinOptions) Marshal 

func (lpo *LoadPinOptions) Marshal() uint32

Marshal returns a value suitable for BPF_OBJ_GET syscall file_flags parameter.

type LogLevel 

type LogLevel = sys.LogLevel

LogLevel controls the verbosity of the kernel's gBPF program verifier. These constants can be used for the ProgramOptions.LogLevel field.

type Map 

type Map struct {
	// contains filtered or unexported fields
}

Map represents a Map file descriptor.

It is not safe to close a map which is used by other goroutines.

Methods which take interface{} arguments by default encode them using binary.Read/Write in the machine's native endianness.

Implement encoding.BinaryMarshaler or encoding.BinaryUnmarshaler if you require custom encoding.

Example (PerCPU)

Per CPU maps store a distinct value for each CPU. They are useful to collect metrics. 

arr, err := NewMap(&MapSpec{
	Type:       PerCPUArray,
	KeySize:    4,
	ValueSize:  4,
	MaxEntries: 2,
})
if err != nil {
	panic(err)
}
defer arr.Close()

possibleCPUs := MustPossibleCPU()
perCPUValues := map[uint32]uint32{
	0: 4,
	1: 5,
}

for k, v := range perCPUValues {
	// We set each perCPU slots to the same value.
	values := make([]uint32, possibleCPUs)
	for i := range values {
		values[i] = v
	}
	if err := arr.Put(k, values); err != nil {
		panic(err)
	}
}

for k := 0; k < 2; k++ {
	var values []uint32
	if err := arr.Lookup(uint32(k), &values); err != nil {
		panic(err)
	}
	// Note we will print an unexpected message if this is not true.
	fmt.Printf("Value of key %v on all CPUs: %v\n", k, values[0])
}
var (
	key     uint32
	entries = arr.Iterate()
)

var values []uint32
for entries.Next(&key, &values) {
	expected, ok := perCPUValues[key]
	if !ok {
		fmt.Printf("Unexpected key %v\n", key)
		continue
	}

	for i, n := range values {
		if n != expected {
			fmt.Printf("Key %v, Value for cpu %v is %v not %v\n",
				key, i, n, expected)
		}
	}
}

if err := entries.Err(); err != nil {
	panic(err)
}

Output:

Value of key 0 on all CPUs: 4
Value of key 1 on all CPUs: 5
Example (ZeroCopy)

It is possible to use unsafe.Pointer to avoid marshalling and copy overhead. It is the responsibility of the caller to ensure the correct size of unsafe.Pointers.

Note that using unsafe.Pointer is only marginally faster than implementing Marshaler on the type. 

hash, err := NewMap(&MapSpec{
	Type:       Hash,
	KeySize:    5,
	ValueSize:  4,
	MaxEntries: 10,
})
if err != nil {
	panic(err)
}
defer hash.Close()

key := [5]byte{'h', 'e', 'l', 'l', 'o'}
value := uint32(23)

if err := hash.Put(unsafe.Pointer(&key), unsafe.Pointer(&value)); err != nil {
	panic(err)
}

value = 0
if err := hash.Lookup(unsafe.Pointer(&key), unsafe.Pointer(&value)); err != nil {
	panic("can't get value:" + err.Error())
}

fmt.Printf("The value is: %d\n", value)

Output:

The value is: 23

func LoadPinnedMap 

func LoadPinnedMap(fileName string, opts *LoadPinOptions) (*Map, error)

LoadPinnedMap loads a Map from a BPF file.

func NewMap 

func NewMap(spec *MapSpec) (*Map, error)

NewMap creates a new Map.

It's equivalent to calling NewMapWithOptions with default options.

func NewMapFromFD 

func NewMapFromFD(fd int) (*Map, error)

NewMapFromFD creates a map from a raw fd.

You should not use fd after calling this function.

func NewMapFromID 

func NewMapFromID(id MapID) (*Map, error)

NewMapFromID returns the map for a given id.

Returns ErrNotExist, if there is no gBPF map with the given id.

func NewMapWithOptions 

func NewMapWithOptions(spec *MapSpec, opts MapOptions) (*Map, error)

NewMapWithOptions creates a new Map.

Creating a map for the first time will perform feature detection by creating small, temporary maps.

The caller is responsible for ensuring the process' rlimit is set sufficiently high for locking memory during map creation. This can be done by calling rlimit.RemoveMemlock() prior to calling NewMapWithOptions.

May return an error wrapping ErrMapIncompatible.

func (*Map) BatchDelete 

func (m *Map) BatchDelete(keys interface{}, opts *BatchOptions) (int, error)

BatchDelete batch deletes entries in the map by keys. "keys" must be of type slice, a pointer to a slice or buffer will not work.

func (*Map) BatchLookup 

func (m *Map) BatchLookup(cursor *MapBatchCursor, keysOut, valuesOut interface{}, opts *BatchOptions) (int, error)

BatchLookup looks up many elements in a map at once.

"keysOut" and "valuesOut" must be of type slice, a pointer to a slice or buffer will not work. "cursor" is an pointer to an opaque handle. It must be non-nil. Pass "cursor" to subsequent calls of this function to continue the batching operation in the case of chunking.

Warning: This API is not very safe to use as the kernel implementation for batching relies on the user to be aware of subtle details with regarding to different map type implementations.

ErrKeyNotExist is returned when the batch lookup has reached the end of all possible results, even when partial results are returned. It should be used to evaluate when lookup is "done".

func (*Map) BatchLookupAndDelete 

func (m *Map) BatchLookupAndDelete(cursor *MapBatchCursor, keysOut, valuesOut interface{}, opts *BatchOptions) (int, error)

BatchLookupAndDelete looks up many elements in a map at once,

It then deletes all those elements. "keysOut" and "valuesOut" must be of type slice, a pointer to a slice or buffer will not work. "cursor" is an pointer to an opaque handle. It must be non-nil. Pass "cursor" to subsequent calls of this function to continue the batching operation in the case of chunking.

Warning: This API is not very safe to use as the kernel implementation for batching relies on the user to be aware of subtle details with regarding to different map type implementations.

ErrKeyNotExist is returned when the batch lookup has reached the end of all possible results, even when partial results are returned. It should be used to evaluate when lookup is "done".

func (*Map) BatchUpdate 

func (m *Map) BatchUpdate(keys, values interface{}, opts *BatchOptions) (int, error)

BatchUpdate updates the map with multiple keys and values simultaneously. "keys" and "values" must be of type slice, a pointer to a slice or buffer will not work.

func (*Map) Clone 

func (m *Map) Clone() (*Map, error)

Clone creates a duplicate of the Map.

Closing the duplicate does not affect the original, and vice versa. Changes made to the map are reflected by both instances however. If the original map was pinned, the cloned map will not be pinned by default.

Cloning a nil Map returns nil.

func (*Map) Close 

func (m *Map) Close() error

Close the Map's underlying file descriptor, which could unload the Map from the kernel if it is not pinned or in use by a loaded Program.

func (*Map) Delete 

func (m *Map) Delete(key interface{}) error

Delete removes a value.

Returns ErrKeyNotExist if the key does not exist.

func (*Map) FD 

func (m *Map) FD() int

FD gets the file descriptor of the Map.

Calling this function is invalid after Close has been called.

func (*Map) Flags 

func (m *Map) Flags() uint32

Flags returns the flags of the map.

func (*Map) Freeze 

func (m *Map) Freeze() error

Freeze prevents a map to be modified from user space.

It makes no changes to kernel-side restrictions.

func (*Map) Handle 

func (m *Map) Handle() (*btf.Handle, error)

Handle returns a reference to the Map's type information in the kernel.

Returns ErrNotSupported if the kernel has no BTF support, or if there is no BTF associated with the Map.

func (*Map) Info 

func (m *Map) Info() (*MapInfo, error)

Info returns metadata about the map.

func (*Map) IsPinned 

func (m *Map) IsPinned() bool

IsPinned returns true if the map has a non-empty pinned path.

func (*Map) Iterate 

func (m *Map) Iterate() *MapIterator

Iterate traverses a map.

It's safe to create multiple iterators at the same time.

It's not possible to guarantee that all keys in a map will be returned if there are concurrent modifications to the map.

Example

ExampleMap_Iterate demonstrates how to iterate over all entries in a map. 

hash, err := NewMap(&MapSpec{
	Type:       Hash,
	KeySize:    5,
	ValueSize:  4,
	MaxEntries: 10,
	Contents: []MapKV{
		{"hello", uint32(21)},
		{"world", uint32(42)},
	},
})
if err != nil {
	panic(err)
}
defer hash.Close()

var (
	key     string
	value   uint32
	entries = hash.Iterate()
)

values := make(map[string]uint32)
for entries.Next(&key, &value) {
	// Order of keys is non-deterministic due to randomized map seed
	values[key] = value
}

if err := entries.Err(); err != nil {
	panic(fmt.Sprint("Iterator encountered an error:", err))
}

for k, v := range values {
	fmt.Printf("key: %s, value: %d\n", k, v)
}

Output:

key: hello, value: 21
key: world, value: 42
Example (NestedMapsAndProgramArrays)

It is possible to iterate nested maps and program arrays by unmarshaling into a *Map or *Program. 

inner := &MapSpec{
	Type:       Array,
	KeySize:    4,
	ValueSize:  4,
	MaxEntries: 2,
	Contents: []MapKV{
		{uint32(0), uint32(1)},
		{uint32(1), uint32(2)},
	},
}
im, err := NewMap(inner)
if err != nil {
	panic(err)
}
defer im.Close()

outer := &MapSpec{
	Type:       ArrayOfMaps,
	InnerMap:   inner,
	KeySize:    4,
	ValueSize:  4,
	MaxEntries: 10,
	Contents: []MapKV{
		{uint32(0), im},
	},
}
arrayOfMaps, err := NewMap(outer)
if errors.Is(err, internal.ErrNotSupported) {
	// Fake the output if on very old kernel.
	fmt.Println("outerKey: 0")
	fmt.Println("\tinnerKey 0 innerValue 1")
	fmt.Println("\tinnerKey 1 innerValue 2")
	return
}
if err != nil {
	panic(err)
}
defer arrayOfMaps.Close()

var (
	key     uint32
	m       *Map
	entries = arrayOfMaps.Iterate()
)
for entries.Next(&key, &m) {
	// Make sure that the iterated map is closed after
	// we are done.
	defer m.Close()

	// Order of keys is non-deterministic due to randomized map seed
	fmt.Printf("outerKey: %v\n", key)

	var innerKey, innerValue uint32
	items := m.Iterate()
	for items.Next(&innerKey, &innerValue) {
		fmt.Printf("\tinnerKey %v innerValue %v\n", innerKey, innerValue)
	}
	if err := items.Err(); err != nil {
		panic(fmt.Sprint("Inner Iterator encountered an error:", err))
	}
}

if err := entries.Err(); err != nil {
	panic(fmt.Sprint("Iterator encountered an error:", err))
}

Output:

outerKey: 0
	innerKey 0 innerValue 1
	innerKey 1 innerValue 2

func (*Map) KeySize 

func (m *Map) KeySize() uint32

KeySize returns the size of the map key in bytes.

func (*Map) Lookup 

func (m *Map) Lookup(key, valueOut interface{}) error

Lookup retrieves a value from a Map.

Calls Close() on valueOut if it is of type **Map or **Program, and *valueOut is not nil.

Returns an error if the key doesn't exist, see ErrKeyNotExist.

func (*Map) LookupAndDelete 

func (m *Map) LookupAndDelete(key, valueOut interface{}) error

LookupAndDelete retrieves and deletes a value from a Map.

Returns ErrKeyNotExist if the key doesn't exist.

func (*Map) LookupAndDeleteWithFlags 

func (m *Map) LookupAndDeleteWithFlags(key, valueOut interface{}, flags MapLookupFlags) error

LookupAndDeleteWithFlags retrieves and deletes a value from a Map.

Passing LookupLock flag will look up and delete the value of a spin-locked map without returning the lock. This must be specified if the elements contain a spinlock.

Returns ErrKeyNotExist if the key doesn't exist.

func (*Map) LookupBytes 

func (m *Map) LookupBytes(key interface{}) ([]byte, error)

LookupBytes gets a value from Map.

Returns a nil value if a key doesn't exist.

func (*Map) LookupWithFlags 

func (m *Map) LookupWithFlags(key, valueOut interface{}, flags MapLookupFlags) error

LookupWithFlags retrieves a value from a Map with flags.

Passing LookupLock flag will look up the value of a spin-locked map without returning the lock. This must be specified if the elements contain a spinlock.

Calls Close() on valueOut if it is of type **Map or **Program, and *valueOut is not nil.

Returns an error if the key doesn't exist, see ErrKeyNotExist.

func (*Map) MaxEntries 

func (m *Map) MaxEntries() uint32

MaxEntries returns the maximum number of elements the map can hold.

func (*Map) NextKey 

func (m *Map) NextKey(key, nextKeyOut interface{}) error

NextKey finds the key following an initial key.

See NextKeyBytes for details.

Returns ErrKeyNotExist if there is no next key.

Example 
hash, err := NewMap(&MapSpec{
	Type:       Hash,
	KeySize:    5,
	ValueSize:  4,
	MaxEntries: 10,
	Contents: []MapKV{
		{"hello", uint32(21)},
		{"world", uint32(42)},
	},
})
if err != nil {
	panic(err)
}
defer hash.Close()

var cur, next string
var keys []string

for err = hash.NextKey(nil, &next); ; err = hash.NextKey(cur, &next) {
	if errors.Is(err, ErrKeyNotExist) {
		break
	}
	if err != nil {
		panic(err)
	}
	keys = append(keys, next)
	cur = next
}

// Order of keys is non-deterministic due to randomized map seed
sort.Strings(keys)
fmt.Printf("Keys are %v\n", keys)

Output:

Keys are [hello world]

func (*Map) NextKeyBytes 

func (m *Map) NextKeyBytes(key interface{}) ([]byte, error)

NextKeyBytes returns the key following an initial key as a byte slice.

Passing nil will return the first key.

Use Iterate if you want to traverse all entries in the map.

Returns nil if there are no more keys.

func (*Map) Pin 

func (m *Map) Pin(fileName string) error

Pin persists the map on the BPF virtual file system past the lifetime of the process that created it .

Calling Pin on a previously pinned map will overwrite the path, except when the new path already exists. Re-pinning across filesystems is not supported. You can Clone a map to pin it to a different path.

This requires bpffs to be mounted above fileName. See https://docs.khulnasoft.io/en/stable/network/kubernetes/configuration/#mounting-bpffs-with-systemd

func (*Map) Put 

func (m *Map) Put(key, value interface{}) error

Put replaces or creates a value in map.

It is equivalent to calling Update with UpdateAny.

func (*Map) String 

func (m *Map) String() string

func (*Map) Type 

func (m *Map) Type() MapType

Type returns the underlying type of the map.

func (*Map) Unpin 

func (m *Map) Unpin() error

Unpin removes the persisted state for the map from the BPF virtual filesystem.

Failed calls to Unpin will not alter the state returned by IsPinned.

Unpinning an unpinned Map returns nil.

func (*Map) Update 

func (m *Map) Update(key, value any, flags MapUpdateFlags) error

Update changes the value of a key.

func (*Map) ValueSize 

func (m *Map) ValueSize() uint32

ValueSize returns the size of the map value in bytes.

type MapBatchCursor 

type MapBatchCursor struct {
	// contains filtered or unexported fields
}

MapBatchCursor represents a starting point for a batch operation.

type MapID 

type MapID uint32

MapID represents the unique ID of an gBPF map

func MapGetNextID 

func MapGetNextID(startID MapID) (MapID, error)

MapGetNextID returns the ID of the next gBPF map.

Returns ErrNotExist, if there is no next gBPF map.

type MapInfo 

type MapInfo struct {
	Type MapType

	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32
	Flags      uint32
	// Name as supplied by user space at load time. Available from 4.15.
	Name string
	// contains filtered or unexported fields
}

MapInfo describes a map.

func (*MapInfo) BTFID 

func (mi *MapInfo) BTFID() (btf.ID, bool)

BTFID returns the BTF ID associated with the Map.

The ID is only valid as long as the associated Map is kept alive. Available from 4.18.

The bool return value indicates whether this optional field is available and populated. (The field may be available but not populated if the kernel supports the field but the Map was loaded without BTF information.)

func (*MapInfo) ID 

func (mi *MapInfo) ID() (MapID, bool)

ID returns the map ID.

Available from 4.13.

The bool return value indicates whether this optional field is available.

type MapIterator 

type MapIterator struct {
	// contains filtered or unexported fields
}

MapIterator iterates a Map.

See Map.Iterate.

func (*MapIterator) Err 

func (mi *MapIterator) Err() error

Err returns any encountered error.

The method must be called after Next returns nil.

Returns ErrIterationAborted if it wasn't possible to do a full iteration.

func (*MapIterator) Next 

func (mi *MapIterator) Next(keyOut, valueOut interface{}) bool

Next decodes the next key and value.

Iterating a hash map from which keys are being deleted is not safe. You may see the same key multiple times. Iteration may also abort with an error, see IsIterationAborted.

Returns false if there are no more entries. You must check the result of Err afterwards.

See Map.Get for further caveats around valueOut.

type MapKV 

type MapKV struct {
	Key   interface{}
	Value interface{}
}

MapKV is used to initialize the contents of a Map.

type MapLookupFlags 

type MapLookupFlags uint64

MapLookupFlags controls the behaviour of the map lookup calls. 

const LookupLock MapLookupFlags = unix.BPF_F_LOCK

LookupLock look up the value of a spin-locked map.

type MapOptions 

type MapOptions struct {
	// The base path to pin maps in if requested via PinByName.
	// Existing maps will be re-used if they are compatible, otherwise an
	// error is returned.
	PinPath        string
	LoadPinOptions LoadPinOptions
}

MapOptions control loading a map into the kernel.

type MapSpec 

type MapSpec struct {
	// Name is passed to the kernel as a debug aid. Must only contain
	// alpha numeric and '_' characters.
	Name       string
	Type       MapType
	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32

	// Flags is passed to the kernel and specifies additional map
	// creation attributes.
	Flags uint32

	// Automatically pin and load a map from MapOptions.PinPath.
	// Generates an error if an existing pinned map is incompatible with the MapSpec.
	Pinning PinType

	// Specify numa node during map creation
	// (effective only if unix.BPF_F_NUMA_NODE flag is set,
	// which can be imported from golang.org/x/sys/unix)
	NumaNode uint32

	// The initial contents of the map. May be nil.
	Contents []MapKV

	// Whether to freeze a map after setting its initial contents.
	Freeze bool

	// InnerMap is used as a template for ArrayOfMaps and HashOfMaps
	InnerMap *MapSpec

	// Extra trailing bytes found in the ELF map definition when using structs
	// larger than libbpf's bpf_map_def. nil if no trailing bytes were present.
	// Must be nil or empty before instantiating the MapSpec into a Map.
	Extra *bytes.Reader

	// The key and value type of this map. May be nil.
	Key, Value btf.Type
}

MapSpec defines a Map.

func (*MapSpec) Compatible 

func (ms *MapSpec) Compatible(m *Map) error

Compatible returns nil if an existing map may be used instead of creating one from the spec.

Returns an error wrapping ErrMapIncompatible otherwise.

func (*MapSpec) Copy 

func (ms *MapSpec) Copy() *MapSpec

Copy returns a copy of the spec.

MapSpec.Contents is a shallow copy.

func (*MapSpec) String 

func (ms *MapSpec) String() string

type MapType 

type MapType uint32

MapType indicates the type map structure that will be initialized in the kernel. 

const (
	UnspecifiedMap MapType = iota
	// Hash is a hash map
	Hash
	// Array is an array map
	Array
	// ProgramArray - A program array map is a special kind of array map whose map
	// values contain only file descriptors referring to other gBPF
	// programs.  Thus, both the key_size and value_size must be
	// exactly four bytes.  This map is used in conjunction with the
	// TailCall helper.
	ProgramArray
	// PerfEventArray - A perf event array is used in conjunction with PerfEventRead
	// and PerfEventOutput calls, to read the raw bpf_perf_data from the registers.
	PerfEventArray
	// PerCPUHash - This data structure is useful for people who have high performance
	// network needs and can reconcile adds at the end of some cycle, so that
	// hashes can be lock free without the use of XAdd, which can be costly.
	PerCPUHash
	// PerCPUArray - This data structure is useful for people who have high performance
	// network needs and can reconcile adds at the end of some cycle, so that
	// hashes can be lock free without the use of XAdd, which can be costly.
	// Each CPU gets a copy of this hash, the contents of all of which can be reconciled
	// later.
	PerCPUArray
	// StackTrace - This holds whole user and kernel stack traces, it can be retrieved with
	// GetStackID
	StackTrace
	// CGroupArray - This is a very niche structure used to help SKBInCGroup determine
	// if an skb is from a socket belonging to a specific cgroup
	CGroupArray
	// LRUHash - This allows you to create a small hash structure that will purge the
	// least recently used items rather than throw an error when you run out of memory
	LRUHash
	// LRUCPUHash - This is NOT like PerCPUHash, this structure is shared among the CPUs,
	// it has more to do with including the CPU id with the LRU calculation so that if a
	// particular CPU is using a value over-and-over again, then it will be saved, but if
	// a value is being retrieved a lot but sparsely across CPUs it is not as important, basically
	// giving weight to CPU locality over overall usage.
	LRUCPUHash
	// LPMTrie - This is an implementation of Longest-Prefix-Match Trie structure. It is useful,
	// for storing things like IP addresses which can be bit masked allowing for keys of differing
	// values to refer to the same reference based on their masks. See wikipedia for more details.
	LPMTrie
	// ArrayOfMaps - Each item in the array is another map. The inner map mustn't be a map of maps
	// itself.
	ArrayOfMaps
	// HashOfMaps - Each item in the hash map is another map. The inner map mustn't be a map of maps
	// itself.
	HashOfMaps
	// DevMap - Specialized map to store references to network devices.
	DevMap
	// SockMap - Specialized map to store references to sockets.
	SockMap
	// CPUMap - Specialized map to store references to CPUs.
	CPUMap
	// XSKMap - Specialized map for XDP programs to store references to open sockets.
	XSKMap
	// SockHash - Specialized hash to store references to sockets.
	SockHash
	// CGroupStorage - Special map for CGroups.
	CGroupStorage
	// ReusePortSockArray - Specialized map to store references to sockets that can be reused.
	ReusePortSockArray
	// PerCPUCGroupStorage - Special per CPU map for CGroups.
	PerCPUCGroupStorage
	// Queue - FIFO storage for BPF programs.
	Queue
	// Stack - LIFO storage for BPF programs.
	Stack
	// SkStorage - Specialized map for local storage at SK for BPF programs.
	SkStorage
	// DevMapHash - Hash-based indexing scheme for references to network devices.
	DevMapHash
	// StructOpsMap - This map holds a kernel struct with its function pointer implemented in a BPF
	// program.
	StructOpsMap
	// RingBuf - Similar to PerfEventArray, but shared across all CPUs.
	RingBuf
	// InodeStorage - Specialized local storage map for inodes.
	InodeStorage
	// TaskStorage - Specialized local storage map for task_struct.
	TaskStorage
)

All the various map types that can be created

func (MapType) String 

func (i MapType) String() string

type MapUpdateFlags 

type MapUpdateFlags uint64

MapUpdateFlags controls the behaviour of the Map.Update call.

The exact semantics depend on the specific MapType. 

const (
	// UpdateAny creates a new element or update an existing one.
	UpdateAny MapUpdateFlags = iota
	// UpdateNoExist creates a new element.
	UpdateNoExist MapUpdateFlags = 1 << (iota - 1)
	// UpdateExist updates an existing element.
	UpdateExist
	// UpdateLock updates elements under bpf_spin_lock.
	UpdateLock
)

type MissingConstantsError 

type MissingConstantsError struct {
	// The constants missing from .rodata.
	Constants []string
}

MissingConstantsError is returned by CollectionSpec.RewriteConstants.

func (*MissingConstantsError) Error 

func (m *MissingConstantsError) Error() string

type PinType 

type PinType uint32

PinType determines whether a map is pinned into a BPFFS. 

const (
	PinNone PinType = iota
	// Pin an object by using its name as the filename.
	PinByName
)

Valid pin types.

Mirrors enum libbpf_pin_type.

func (PinType) String 

func (i PinType) String() string

type Program 

type Program struct {
	// Contains the output of the kernel verifier if enabled,
	// otherwise it is empty.
	VerifierLog string
	// contains filtered or unexported fields
}

Program represents BPF program loaded into the kernel.

It is not safe to close a Program which is used by other goroutines.

Example (RetrieveVerifierLog)

Use NewProgramWithOptions if you'd like to get the verifier output for a program, or if you want to change the buffer size used when generating error messages. 

spec := &ProgramSpec{
	Type: SocketFilter,
	Instructions: asm.Instructions{
		asm.LoadImm(asm.R0, 0, asm.DWord),
		asm.Return(),
	},
	License: "MIT",
}

prog, err := NewProgramWithOptions(spec, ProgramOptions{
	LogLevel: LogLevelInstruction,
	LogSize:  1024,
})
if err != nil {
	panic(err)
}
defer prog.Close()

fmt.Println("The verifier output is:")
fmt.Println(prog.VerifierLog)

Output:
Example (UnmarshalFromMap)

It's possible to read a program directly from a ProgramArray. 

progArray, err := LoadPinnedMap("/path/to/map", nil)
if err != nil {
	panic(err)
}
defer progArray.Close()

// Load a single program
var prog *Program
if err := progArray.Lookup(uint32(0), &prog); err != nil {
	panic(err)
}
defer prog.Close()

fmt.Println("first prog:", prog)

// Iterate all programs
var (
	key     uint32
	entries = progArray.Iterate()
)

for entries.Next(&key, &prog) {
	fmt.Println(key, "is", prog)
}

if err := entries.Err(); err != nil {
	panic(err)
}

Output:

func LoadPinnedProgram 

func LoadPinnedProgram(fileName string, opts *LoadPinOptions) (*Program, error)

LoadPinnedProgram loads a Program from a BPF file.

Requires at least Linux 4.11.

func NewProgram 

func NewProgram(spec *ProgramSpec) (*Program, error)

NewProgram creates a new Program.

See NewProgramWithOptions for details.

Returns a VerifierError containing the full verifier log if the program is rejected by the kernel.

func NewProgramFromFD 

func NewProgramFromFD(fd int) (*Program, error)

NewProgramFromFD creates a program from a raw fd.

You should not use fd after calling this function.

Requires at least Linux 4.10.

func NewProgramFromID 

func NewProgramFromID(id ProgramID) (*Program, error)

NewProgramFromID returns the program for a given id.

Returns ErrNotExist, if there is no gBPF program with the given id.

func NewProgramWithOptions 

func NewProgramWithOptions(spec *ProgramSpec, opts ProgramOptions) (*Program, error)

NewProgramWithOptions creates a new Program.

Loading a program for the first time will perform feature detection by loading small, temporary programs.

Returns a VerifierError containing the full verifier log if the program is rejected by the kernel.

func (*Program) Benchmark 

func (p *Program) Benchmark(in []byte, repeat int, reset func()) (uint32, time.Duration, error)

Benchmark runs the Program with the given input for a number of times and returns the time taken per iteration.

Returns the result of the last execution of the program and the time per run or an error. reset is called whenever the benchmark syscall is interrupted, and should be set to testing.B.ResetTimer or similar.

This function requires at least Linux 4.12.

func (*Program) BindMap 

func (p *Program) BindMap(m *Map) error

BindMap binds map to the program and is only released once program is released.

This may be used in cases where metadata should be associated with the program which otherwise does not contain any references to the map.

func (*Program) Clone 

func (p *Program) Clone() (*Program, error)

Clone creates a duplicate of the Program.

Closing the duplicate does not affect the original, and vice versa.

Cloning a nil Program returns nil.

func (*Program) Close 

func (p *Program) Close() error

Close the Program's underlying file descriptor, which could unload the program from the kernel if it is not pinned or attached to a kernel hook.

func (*Program) FD 

func (p *Program) FD() int

FD gets the file descriptor of the Program.

It is invalid to call this function after Close has been called.

func (*Program) Handle 

func (p *Program) Handle() (*btf.Handle, error)

Handle returns a reference to the program's type information in the kernel.

Returns ErrNotSupported if the kernel has no BTF support, or if there is no BTF associated with the program.

func (*Program) Info 

func (p *Program) Info() (*ProgramInfo, error)

Info returns metadata about the program.

Requires at least 4.10.

func (*Program) IsPinned 

func (p *Program) IsPinned() bool

IsPinned returns true if the Program has a non-empty pinned path.

func (*Program) Pin 

func (p *Program) Pin(fileName string) error

Pin persists the Program on the BPF virtual file system past the lifetime of the process that created it

Calling Pin on a previously pinned program will overwrite the path, except when the new path already exists. Re-pinning across filesystems is not supported.

This requires bpffs to be mounted above fileName. See https://docs.khulnasoft.io/en/stable/network/kubernetes/configuration/#mounting-bpffs-with-systemd

func (*Program) Run 

func (p *Program) Run(opts *RunOptions) (uint32, error)

Run runs the Program in kernel with given RunOptions.

Note: the same restrictions from Test apply.

func (*Program) String 

func (p *Program) String() string

func (*Program) Test 

func (p *Program) Test(in []byte) (uint32, []byte, error)

Test runs the Program in the kernel with the given input and returns the value returned by the gBPF program.

Note: the kernel expects at least 14 bytes input for an ethernet header for XDP and SKB programs.

This function requires at least Linux 4.12.

func (*Program) Type 

func (p *Program) Type() ProgramType

Type returns the underlying type of the program.

func (*Program) Unpin 

func (p *Program) Unpin() error

Unpin removes the persisted state for the Program from the BPF virtual filesystem.

Failed calls to Unpin will not alter the state returned by IsPinned.

Unpinning an unpinned Program returns nil.

type ProgramID 

type ProgramID uint32

ProgramID represents the unique ID of an gBPF program.

func ProgramGetNextID 

func ProgramGetNextID(startID ProgramID) (ProgramID, error)

ProgramGetNextID returns the ID of the next gBPF program.

Returns ErrNotExist, if there is no next gBPF program.

type ProgramInfo 

type ProgramInfo struct {
	Type ProgramType

	// Truncated hash of the BPF bytecode. Available from 4.13.
	Tag string
	// Name as supplied by user space at load time. Available from 4.15.
	Name string
	// contains filtered or unexported fields
}

ProgramInfo describes a program.

func (*ProgramInfo) BTFID 

func (pi *ProgramInfo) BTFID() (btf.ID, bool)

BTFID returns the BTF ID associated with the program.

The ID is only valid as long as the associated program is kept alive. Available from 5.0.

The bool return value indicates whether this optional field is available and populated. (The field may be available but not populated if the kernel supports the field but the program was loaded without BTF information.)

func (*ProgramInfo) CreatedByUID 

func (pi *ProgramInfo) CreatedByUID() (uint32, bool)

CreatedByUID returns the Uid that created the program.

Available from 4.15.

The bool return value indicates whether this optional field is available.

func (*ProgramInfo) ID 

func (pi *ProgramInfo) ID() (ProgramID, bool)

ID returns the program ID.

Available from 4.13.

The bool return value indicates whether this optional field is available.

func (*ProgramInfo) Instructions 

func (pi *ProgramInfo) Instructions() (asm.Instructions, error)

Instructions returns the 'xlated' instruction stream of the program after it has been verified and rewritten by the kernel. These instructions cannot be loaded back into the kernel as-is, this is mainly used for inspecting loaded programs for troubleshooting, dumping, etc.

For example, map accesses are made to reference their kernel map IDs, not the FDs they had when the program was inserted. Note that before the introduction of bpf_insn_prepare_dump in kernel 4.16, xlated instructions were not sanitized, making the output even less reusable and less likely to round-trip or evaluate to the same program Tag.

The first instruction is marked as a symbol using the Program's name.

If available, the instructions will be annotated with metadata from the BTF. This includes line information and function information. Reading this metadata requires CAP_SYS_ADMIN or equivalent. If capability is unavailable, the instructions will be returned without metadata.

Available from 4.13. Requires CAP_BPF or equivalent for plain instructions. Requires CAP_SYS_ADMIN for instructions with metadata.

func (*ProgramInfo) MapIDs 

func (pi *ProgramInfo) MapIDs() ([]MapID, bool)

MapIDs returns the maps related to the program.

Available from 4.15.

The bool return value indicates whether this optional field is available.

func (*ProgramInfo) RecursionMisses 

func (pi *ProgramInfo) RecursionMisses() (uint64, bool)

RecursionMisses returns the total number of times the program was NOT called. This can happen when another bpf program is already running on the cpu, which is likely to happen for example when you interrupt bpf program execution.

func (*ProgramInfo) RunCount 

func (pi *ProgramInfo) RunCount() (uint64, bool)

RunCount returns the total number of times the program was called.

Can return 0 if the collection of statistics is not enabled. See EnableStats(). The bool return value indicates whether this optional field is available.

func (*ProgramInfo) Runtime 

func (pi *ProgramInfo) Runtime() (time.Duration, bool)

Runtime returns the total accumulated runtime of the program.

Can return 0 if the collection of statistics is not enabled. See EnableStats(). The bool return value indicates whether this optional field is available.

type ProgramOptions 

type ProgramOptions struct {
	// Bitmap controlling the detail emitted by the kernel's gBPF verifier log.
	// LogLevel-type values can be ORed together to request specific kinds of
	// verifier output. See the documentation on [gbpf.LogLevel] for details.
	//
	//  opts.LogLevel = (gbpf.LogLevelBranch | gbpf.LogLevelStats)
	//
	// If left to its default value, the program will first be loaded without
	// verifier output enabled. Upon error, the program load will be repeated
	// with LogLevelBranch and the given (or default) LogSize value.
	//
	// Unless LogDisabled is set, setting this to a non-zero value will enable the verifier
	// log, populating the [gbpf.Program.VerifierLog] field on successful loads
	// and including detailed verifier errors if the program is rejected. This
	// will always allocate an output buffer, but will result in only a single
	// attempt at loading the program.
	LogLevel LogLevel

	// Controls the output buffer size for the verifier log, in bytes. See the
	// documentation on ProgramOptions.LogLevel for details about how this value
	// is used.
	//
	// If this value is set too low to fit the verifier log, the resulting
	// [gbpf.VerifierError]'s Truncated flag will be true, and the error string
	// will also contain a hint to that effect.
	//
	// Defaults to DefaultVerifierLogSize.
	LogSize int

	// Disables the verifier log completely, regardless of other options.
	LogDisabled bool

	// Type information used for CO-RE relocations.
	//
	// This is useful in environments where the kernel BTF is not available
	// (containers) or where it is in a non-standard location. Defaults to
	// use the kernel BTF from a well-known location if nil.
	KernelTypes *btf.Spec

	// Type information used for CO-RE relocations of kernel modules,
	// indexed by module name.
	//
	// This is useful in environments where the kernel BTF is not available
	// (containers) or where it is in a non-standard location. Defaults to
	// use the kernel module BTF from a well-known location if nil.
	KernelModuleTypes map[string]*btf.Spec
}

ProgramOptions control loading a program into the kernel.

type ProgramSpec 

type ProgramSpec struct {
	// Name is passed to the kernel as a debug aid. Must only contain
	// alpha numeric and '_' characters.
	Name string

	// Type determines at which hook in the kernel a program will run.
	Type ProgramType

	// AttachType of the program, needed to differentiate allowed context
	// accesses in some newer program types like CGroupSockAddr.
	//
	// Available on kernels 4.17 and later.
	AttachType AttachType

	// Name of a kernel data structure or function to attach to. Its
	// interpretation depends on Type and AttachType.
	AttachTo string

	// The program to attach to. Must be provided manually.
	AttachTarget *Program

	// The name of the ELF section this program originated from.
	SectionName string

	Instructions asm.Instructions

	// Flags is passed to the kernel and specifies additional program
	// load attributes.
	Flags uint32

	// License of the program. Some helpers are only available if
	// the license is deemed compatible with the GPL.
	//
	// See https://www.kernel.org/doc/html/latest/process/license-rules.html#id1
	License string

	// Version used by Kprobe programs.
	//
	// Deprecated on kernels 5.0 and later. Leave empty to let the library
	// detect this value automatically.
	KernelVersion uint32

	// The byte order this program was compiled for, may be nil.
	ByteOrder binary.ByteOrder
}

ProgramSpec defines a Program.

func (*ProgramSpec) Copy 

func (ps *ProgramSpec) Copy() *ProgramSpec

Copy returns a copy of the spec.

func (*ProgramSpec) KernelModule 

func (ps *ProgramSpec) KernelModule() (string, error)

KernelModule returns the kernel module, if any, the AttachTo function is contained in.

func (*ProgramSpec) Tag 

func (ps *ProgramSpec) Tag() (string, error)

Tag calculates the kernel tag for a series of instructions.

Use asm.Instructions.Tag if you need to calculate for non-native endianness.

Example 
spec := &ProgramSpec{
	Type: SocketFilter,
	Instructions: asm.Instructions{
		asm.LoadImm(asm.R0, 0, asm.DWord),
		asm.Return(),
	},
	License: "MIT",
}

prog, _ := NewProgram(spec)
info, _ := prog.Info()
tag, _ := spec.Tag()

if info.Tag != tag {
	fmt.Printf("The tags don't match: %s != %s\n", info.Tag, tag)
} else {
	fmt.Println("The programs are identical, tag is", tag)
}

Output:

type ProgramType 

type ProgramType uint32

ProgramType of the gBPF program

func (ProgramType) String 

func (i ProgramType) String() string

type RunOptions 

type RunOptions struct {
	// Program's data input. Required field.
	//
	// The kernel expects at least 14 bytes input for an ethernet header for
	// XDP and SKB programs.
	Data []byte
	// Program's data after Program has run. Caller must allocate. Optional field.
	DataOut []byte
	// Program's context input. Optional field.
	Context interface{}
	// Program's context after Program has run. Must be a pointer or slice. Optional field.
	ContextOut interface{}
	// Minimum number of times to run Program. Optional field. Defaults to 1.
	//
	// The program may be executed more often than this due to interruptions, e.g.
	// when runtime.AllThreadsSyscall is invoked.
	Repeat uint32
	// Optional flags.
	Flags uint32
	// CPU to run Program on. Optional field.
	// Note not all program types support this field.
	CPU uint32
	// Called whenever the syscall is interrupted, and should be set to testing.B.ResetTimer
	// or similar. Typically used during benchmarking. Optional field.
	//
	// Deprecated: use [testing.B.ReportMetric] with unit "ns/op" instead.
	Reset func()
}

Various options for Run'ing a Program

type VerifierError 

type VerifierError = internal.VerifierError

VerifierError is returned by NewProgram and NewProgramWithOptions if a program is rejected by the verifier.

Use errors.As to access the error.

Example

VerifierLog understands a variety of formatting flags. 

err := internal.ErrorWithLog(
	"catastrophe",
	syscall.ENOSPC,
	[]byte("first\nsecond\nthird"),
	false,
)

fmt.Printf("With %%s: %s\n", err)
err.Truncated = true
fmt.Printf("With %%v and a truncated log: %v\n", err)
fmt.Printf("All log lines: %+v\n", err)
fmt.Printf("First line: %+1v\n", err)
fmt.Printf("Last two lines: %-2v\n", err)

Output:

With %s: catastrophe: no space left on device: third (2 line(s) omitted)
With %v and a truncated log: catastrophe: no space left on device: second: third (truncated, 1 line(s) omitted)
All log lines: catastrophe: no space left on device:
	first
	second
	third
	(truncated)
First line: catastrophe: no space left on device:
	first
	(2 line(s) omitted)
	(truncated)
Last two lines: catastrophe: no space left on device:
	(1 line(s) omitted)
	second
	third
	(truncated)
Example (RetrieveFullLog)

Print the full verifier log when loading a program fails. 

_, err := NewProgram(&ProgramSpec{
	Type: SocketFilter,
	Instructions: asm.Instructions{
		asm.LoadImm(asm.R0, 0, asm.DWord),
		// Missing Return
	},
	License: "MIT",
})

var ve *VerifierError
if errors.As(err, &ve) {
	// Using %+v will print the whole verifier error, not just the last
	// few lines.
	fmt.Printf("Verifier error: %+v\n", ve)
}

Output:

Source Files

View all Source files

Directories

Path Synopsis
Package asm is an assembler for gBPF bytecode.
 Package asm is an assembler for gBPF bytecode.
Package btf handles data encoded according to the BPF Type Format.
 Package btf handles data encoded according to the BPF Type Format.
cmd
bpf2go
Program bpf2go embeds gBPF in Go.
 Program bpf2go embeds gBPF in Go.
bpf2go/test
Package test checks that the code generated by bpf2go conforms to a specific API.
 Package test checks that the code generated by bpf2go conforms to a specific API.
docs
examples/getting_started
getting_started_gen {
 getting_started_gen {
examples
cgroup_skb
This program demonstrates attaching an gBPF program to a control group.
 This program demonstrates attaching an gBPF program to a control group.
fentry
kprobe
This program demonstrates attaching an gBPF program to a kernel symbol.
 This program demonstrates attaching an gBPF program to a kernel symbol.
kprobe_percpu
This program demonstrates attaching an gBPF program to a kernel symbol and using percpu map to collect data.
 This program demonstrates attaching an gBPF program to a kernel symbol and using percpu map to collect data.
kprobepin
This program demonstrates attaching an gBPF program to a kernel symbol.
 This program demonstrates attaching an gBPF program to a kernel symbol.
map_in_map
An example of using maps within maps.
 An example of using maps within maps.
ringbuffer
tcprtt
tcprtt_sockops
tcx
This program demonstrates attaching an gBPF program to a network interface with Linux TC (Traffic Control).
 This program demonstrates attaching an gBPF program to a network interface with Linux TC (Traffic Control).
tracepoint_in_c
This program demonstrates attaching an gBPF program to a kernel tracepoint.
 This program demonstrates attaching an gBPF program to a kernel tracepoint.
tracepoint_in_go
This program demonstrates how to attach an gBPF program to a tracepoint.
 This program demonstrates how to attach an gBPF program to a tracepoint.
uretprobe
xdp
This program demonstrates attaching an gBPF program to a network interface with XDP (eXpress Data Path).
 This program demonstrates attaching an gBPF program to a network interface with XDP (eXpress Data Path).
Package features allows probing for BPF features available to the calling process.
 Package features allows probing for BPF features available to the calling process.
cmd/gentypes
Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it.
 Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it.
epoll
kallsyms
kconfig
sys
Package sys contains bindings for the BPF syscall.
 Package sys contains bindings for the BPF syscall.
sysenc
Package sysenc provides efficient conversion of Go values to system call interfaces.
 Package sysenc provides efficient conversion of Go values to system call interfaces.
testutils
testutils/fdtrace
tracefs
unix
Package unix re-exports Linux specific parts of golang.org/x/sys/unix.
 Package unix re-exports Linux specific parts of golang.org/x/sys/unix.
Package link allows attaching gBPF programs to various kernel hooks.
 Package link allows attaching gBPF programs to various kernel hooks.
Package perf allows reading from BPF perf event arrays.
 Package perf allows reading from BPF perf event arrays.
Package ringbuf allows interacting with Linux BPF ring buffer.
 Package ringbuf allows interacting with Linux BPF ring buffer.
Package rlimit allows raising RLIMIT_MEMLOCK if necessary for the use of BPF.
 Package rlimit allows raising RLIMIT_MEMLOCK if necessary for the use of BPF.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.