bpf

package
v1.17.0-pre.0 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2024 License: Apache-2.0 Imports: 44 Imported by: 296

Documentation

Overview

Package bpf provides functions that allow golang programs to interact with bpf maps. +groupName=pkg

Index

Constants

View Source 
const (
	EndpointKeyIPv4 uint8 = 1
	EndpointKeyIPv6 uint8 = 2
)

Must be in sync with ENDPOINT_KEY_* in <bpf/lib/common.h>

View Source 
const (
	// Flags for BPF_MAP_CREATE. Must match values from linux/bpf.h
	BPF_F_NO_PREALLOC = 1 << 0
)
View Source 
const (
	// PinAlwaysReplace matches CILIUM_PIN_REPLACE.
	PinReplace = ebpf.PinType(1 << 4)
)

Cilium-specific pinning flags used in bpf C code to request specific pinning behaviour from the agent.

Variables

View Source 
var ErrMapNotOpened = errors.New("BPF map has not been opened")

ErrMapNotOpened is returned when the MapOps is used with a BPF map that is not open yet. In general this should be avoided and the map should be opened in a start hook before the reconciler. If the map won't be used then the reconciler should not be started.

View Source 
var (
	// ErrMaxLookup is returned when the maximum number of map element lookups has
	// been reached.
	ErrMaxLookup = errors.New("maximum number of lookups reached")
)

Functions

func BPFFSRoot added in v0.15.7 

func BPFFSRoot() string

func CheckOrMountFS added in v0.15.7 

func CheckOrMountFS(bpfRoot string)

CheckOrMountFS checks or mounts the BPF filesystem and then opens/creates/deletes all maps which have previously been scheduled to be opened/created/deleted.

If printWarning is set, will print a warning if bpffs has not previously been mounted.

func CiliumPath added in v0.15.7 

func CiliumPath() string

CiliumPath returns the bpffs path to be used for Cilium object pins.

func DisableMapPreAllocation added in v0.15.7 

func DisableMapPreAllocation()

DisableMapPreAllocation disables BPF map pre-allocation as a default setting. Some map types enforces pre-alloc strategy so this does not take effect in that case. Also note that this does not take effect on existing map although could be recreated later when objCheck() runs.

func EnableMapPreAllocation added in v0.15.7 

func EnableMapPreAllocation()

EnableMapPreAllocation enables BPF map pre-allocation on map types that support it. This does not take effect on existing map although some map types could be recreated later when objCheck() runs.

func GetMtime added in v0.9.0 

func GetMtime() (uint64, error)

GetMtime returns monotonic time that can be used to compare values with ktime_get_ns() BPF helper, e.g. needed to check the timeout in sec for BPF entries. We return the raw nsec, although that is not quite usable for comparison. Go has runtime.nanotime() but doesn't expose it as API.

func GetOpenMaps added in v0.15.7 

func GetOpenMaps() []*models.BPFMap

GetOpenMaps returns a slice of all open BPF maps. This is identical to calling GetMap() on all open maps.

func GetPreAllocateMapFlags added in v0.15.7 

func GetPreAllocateMapFlags(t ebpf.MapType) uint32

GetPreAllocateMapFlags returns the map flags for map which use conditional pre-allocation.

func LoadAndAssign 

func LoadAndAssign(to any, spec *ebpf.CollectionSpec, opts *CollectionOptions) (func() error, error)

LoadAndAssign loads spec into the kernel and assigns the requested eBPF objects to the given object. It is a wrapper around LoadCollection. See its documentation for more details on the loading process.

func LoadCollection added in v0.15.7 

func LoadCollection(spec *ebpf.CollectionSpec, opts *CollectionOptions) (*ebpf.Collection, func() error, error)

LoadCollection loads the given spec into the kernel with the specified opts. Returns a function that must be called after the Collection's entrypoints are attached to their respective kernel hooks. This function commits pending map pins to the bpf file system for maps that were found to be incompatible with their pinned counterparts, or for maps with certain flags that modify the default pinning behaviour.

When attaching multiple programs from the same ELF in a loop, the returned function should only be run after all entrypoints have been attached. For example, attach both bpf_host.c:cil_to_netdev and cil_from_netdev before invoking the returned function, otherwise missing tail calls will occur.

The value given in ProgramOptions.LogSize is used as the starting point for sizing the verifier's log buffer and defaults to 4MiB. On each retry, the log buffer quadruples in size, for a total of 5 attempts. If that proves insufficient, a truncated ebpf.VerifierError is returned.

Any maps marked as pinned in the spec are automatically loaded from the path given in opts.Maps.PinPath and will be used instead of creating new ones.

func LoadCollectionSpec added in v0.15.7 

func LoadCollectionSpec(path string) (*ebpf.CollectionSpec, error)

LoadCollectionSpec loads the eBPF ELF at the given path and parses it into a CollectionSpec. This spec is only a blueprint of the contents of the ELF and does not represent any live resources that have been loaded into the kernel.

This is a wrapper around ebpf.LoadCollectionSpec that parses legacy iproute2 bpf_elf_map definitions (only used for prog_arrays at the time of writing) and assigns tail calls annotated with `__section_tail` macros to their intended maps and slots.

func LocalMapName added in v0.15.7 

func LocalMapName(name string, id uint16) string

LocalMapName returns the name for a BPF map that is local to the specified ID.

func LocalMapPath added in v0.15.7 

func LocalMapPath(name string, id uint16) string

LocalMapPath returns the path for a BPF map that is local to the specified ID.

func MapPath 

func MapPath(name string) string

MapPath returns a path for a BPF map with a given name.

func MkdirBPF added in v1.15.0 

func MkdirBPF(path string) error

MkdirBPF wraps os.MkdirAll with the right permission bits for bpffs. Use this for ensuring the existence of directories on bpffs.

func NewMapOps added in v1.16.0 

func NewMapOps[KV KeyValue](m *Map) reconciler.Operations[KV]

func OpenOrCreateMap 

func OpenOrCreateMap(spec *ebpf.MapSpec, pinDir string) (*ebpf.Map, error)

OpenOrCreateMap attempts to load the pinned map at "pinDir/<spec.Name>" if the spec is marked as Pinned. Any parent directories of pinDir are automatically created. Any pinned maps incompatible with the given spec are removed and recreated.

If spec.Pinned is 0, a new Map is always created.

func RegisterTablePressureMetricsJob added in v1.16.0 

func RegisterTablePressureMetricsJob[Obj any, Map mapPressureMetricsOps](g job.Group, db *statedb.DB, table statedb.Table[Obj], m Map)

RegisterTablePressureMetricsJob adds a timer job to track the map pressure of a BPF map where the desired state is stored in a StateDB table.

Example usage: 

type myBPFMap struct { *bpf.Map }
cell.Invoke(
  bpf.RegisterTablePressureMetricsJob[MyObj, myBPFMap],
)

func Remove added in v1.15.4 

func Remove(path string) error

Remove path ignoring ErrNotExist.

func TCGlobalsPath added in v0.15.7 

func TCGlobalsPath() string

TCGlobalsPath returns the absolute path to <bpffs>/tc/globals, used for legacy map pin paths. 

func UnpinLink(pin string) error

DetachLink loads and unpins a bpf_link at the given pin path.

Returns os.ErrNotExist if the pin is not found. 

func UpdateLink(pin string, prog *ebpf.Program) error

UpdateLink loads a pinned bpf_link at the given pin path and updates its program.

Returns os.ErrNotExist if the pin is not found.

Updating the link can fail if it is defunct (the hook it points to no longer exists).

Types

type Action added in v0.15.7 

type Action uint8

Action describes an action for map buffer events. 

const (
	// MapUpdate describes a map.Update event.
	MapUpdate Action = iota
	// MapDelete describes a map.Delete event.
	MapDelete
	// MapDeleteAll describes a map.DeleteAll event which is aggregated into a single event
	// to minimize memory and subscription buffer usage.
	MapDeleteAll
)

func (Action) String added in v0.15.7 

func (e Action) String() string

String returns a string representation of an Action.

type BpfMap added in v0.15.7 

type BpfMap interface{}

BpfMap defines the base interface every BPF map needs to implement.

Its main purpose is to register a BPF map via value group `bpf-maps`. See MapOut.

type CollectionOptions added in v1.16.0 

type CollectionOptions struct {
	ebpf.CollectionOptions

	// Replacements for constants defined using the DECLARE_CONFIG macros.
	Constants map[string]uint64

	// Maps to be renamed during loading. Key is the key in CollectionSpec.Maps,
	// value is the new name.
	MapRenames map[string]string
}

type DesiredAction added in v0.15.7 

type DesiredAction uint8

DesiredAction is the action to be performed on the BPF map 

const (
	// OK indicates that to further action is required and the entry is in
	// sync
	OK DesiredAction = iota

	// Insert indicates that the entry needs to be created or updated
	Insert

	// Delete indicates that the entry needs to be deleted
	Delete
)

func (DesiredAction) String added in v0.15.7 

func (d DesiredAction) String() string

type DumpCallback 

type DumpCallback func(key MapKey, value MapValue)

type DumpStats added in v0.15.7 

type DumpStats struct {
	// Started is the timestamp when the gc run was started.
	Started time.Time

	// Finished is the timestamp when the gc run completed.
	Finished time.Time

	// Lookup is the number of key lookups performed.
	Lookup uint32

	// LookupFailed is the number of key lookups that failed.
	LookupFailed uint32

	// PrevKeyUnavailable is the number of times the previous key was not
	// available.
	PrevKeyUnavailable uint32

	// KeyFallback is the number of times the current key became invalid
	// while traversing and we had to fall back to the previous key.
	KeyFallback uint32

	// MaxEntries is the maximum number of entries in the gc table.
	MaxEntries uint32

	// Interrupted is the number of times the gc run was interrupted and
	// had to start from scratch.
	Interrupted uint32

	// Completed is true when the gc run has been completed.
	Completed bool
}

DumpStats tracks statistics over the dump of a map.

func NewDumpStats added in v0.15.7 

func NewDumpStats(m *Map) *DumpStats

NewDumpStats returns a new stats structure for collecting dump statistics.

func (*DumpStats) Duration added in v0.15.7 

func (d *DumpStats) Duration() time.Duration

Duration returns the duration of the dump.

type EndpointKey added in v0.15.7 

type EndpointKey struct {
	// represents both IPv6 and IPv4 (in the lowest four bytes)
	IP        types.IPv6 `align:"$union0"`
	Family    uint8      `align:"family"`
	Key       uint8      `align:"key"`
	ClusterID uint16     `align:"cluster_id"`
}

EndpointKey represents the key value of the endpoints BPF map

Must be in sync with struct endpoint_key in <bpf/lib/common.h>

func NewEndpointKey added in v0.15.7 

func NewEndpointKey(ip net.IP, clusterID uint16) EndpointKey

NewEndpointKey returns an EndpointKey based on the provided IP address. The address family is automatically detected.

func (EndpointKey) String added in v0.15.7 

func (k EndpointKey) String() string

String provides a string representation of the EndpointKey.

func (EndpointKey) ToIP added in v0.15.7 

func (k EndpointKey) ToIP() net.IP

ToIP converts the EndpointKey into a net.IP structure.

type Event added in v0.15.7 

type Event struct {
	Timestamp time.Time
	// contains filtered or unexported fields
}

Event contains data about a bpf operation event.

func (*Event) GetAction added in v0.15.7 

func (e *Event) GetAction() string

GetAction returns the event action string.

func (Event) GetDesiredAction added in v0.15.7 

func (e Event) GetDesiredAction() DesiredAction

GetDesiredAction returns the desired action enum for an event.

func (Event) GetKey added in v0.15.7 

func (e Event) GetKey() string

GetKey returns the string representation of a event key.

func (Event) GetLastError added in v0.15.7 

func (e Event) GetLastError() error

GetLastError returns the last error for an event.

func (Event) GetValue added in v0.15.7 

func (e Event) GetValue() string

GetValue returns the string representation of a event value. Nil values (such as with deletes) are returned as a canonical string representation.

type EventCallbackFunc added in v0.15.7 

type EventCallbackFunc func(*Event)

EventCallbackFunc is used to dump events from a event buffer.

type Handle added in v0.15.7 

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

Handle allows for handling event streams safely outside of this package. The key design consideration for event streaming is that it is non-blocking. The eventsBuffer takes care of closing handles when their consumer is not reading off the buffer (or is not reading off it fast enough).

func (*Handle) C added in v0.15.7 

func (h *Handle) C() <-chan *Event

Returns read only channel for Handle subscription events. Channel should be closed with handle.Close() function.

func (*Handle) Close added in v0.15.7 

func (h *Handle) Close()

Close allows for safaley closing of a handle.

type KeyValue added in v1.16.0 

type KeyValue interface {
	BinaryKey() encoding.BinaryMarshaler
	BinaryValue() encoding.BinaryMarshaler
}

KeyValue is the interface that an BPF map value object must implement.

The object can either store the key and value directly in struct form and use StructBinaryMarshaler{}, or it can implement conversion to binary form on the fly by implementing BinaryMarshaler by hand.

type Map 

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

func GetMap added in v0.15.7 

func GetMap(name string) *Map

GetMap returns the registered map with the given name or absolute path

func NewMap 

func NewMap(name string, mapType ebpf.MapType, mapKey MapKey, mapValue MapValue,
	maxEntries int, flags uint32) *Map

NewMap creates a new Map instance - object representing a BPF map

func NewMapWithInnerSpec added in v0.15.7 

func NewMapWithInnerSpec(name string, mapType ebpf.MapType, mapKey MapKey, mapValue MapValue,
	maxEntries int, flags uint32, innerSpec *ebpf.MapSpec) *Map

NewMap creates a new Map instance - object representing a BPF map

func OpenMap 

func OpenMap(pinPath string, key MapKey, value MapValue) (*Map, error)

OpenMap opens the map at pinPath.

func (*Map) BatchLookup added in v1.16.0 

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

BatchLookup returns the count of elements in the map by dumping the map using batch lookup.

func (*Map) CheckAndUpgrade added in v0.15.7 

func (m *Map) CheckAndUpgrade(desired *Map) bool

CheckAndUpgrade checks the received map's properties (for the map currently loaded into the kernel) against the desired properties, and if they do not match, deletes the map.

Returns true if the map was upgraded.

func (*Map) Close 

func (m *Map) Close() error

func (*Map) Create added in v0.15.7 

func (m *Map) Create() error

Create is similar to OpenOrCreate, but closes the map after creating or opening it.

func (*Map) CreateUnpinned added in v0.15.7 

func (m *Map) CreateUnpinned() error

CreateUnpinned creates the map without pinning it to the file system.

TODO(tb): Remove this when all map creation takes MapSpec.

func (*Map) Delete 

func (m *Map) Delete(key MapKey) error

Delete deletes the map entry corresponding to the given key.

func (*Map) DeleteAll 

func (m *Map) DeleteAll() error

DeleteAll deletes all entries of a map by traversing the map and deleting individual entries. Note that if entries are added while the taversal is in progress, such entries may survive the deletion process.

func (*Map) Dump 

func (m *Map) Dump(hash map[string][]string) error

Dump returns the map (type map[string][]string) which contains all data stored in BPF map.

func (*Map) DumpAndSubscribe added in v0.15.7 

func (m *Map) DumpAndSubscribe(callback EventCallbackFunc, follow bool) (*Handle, error)

DumpAndSubscribe dumps existing buffer, if callback is not nil. Followed by creating a subscription to the maps events buffer and returning the handle. These actions are done together so as to prevent possible missed events between the handoff of the callback and sub handle creation.

func (*Map) DumpIfExists added in v0.15.7 

func (m *Map) DumpIfExists(hash map[string][]string) error

DumpIfExists dumps the contents of the map into hash via Dump() if the map file exists

func (*Map) DumpReliablyWithCallback added in v0.15.7 

func (m *Map) DumpReliablyWithCallback(cb DumpCallback, stats *DumpStats) error

DumpReliablyWithCallback is similar to DumpWithCallback, but performs additional tracking of the current and recently seen keys, so that if an element is removed from the underlying kernel map during the dump, the dump can continue from a recently seen key rather than restarting from scratch. In addition, it caps the maximum number of map entry iterations at 4 times the maximum map size. If this limit is reached, ErrMaxLookup is returned.

The caller must provide a callback for handling each entry, and a stats object initialized via a call to NewDumpStats().

func (*Map) DumpWithCallback added in v0.15.7 

func (m *Map) DumpWithCallback(cb DumpCallback) error

DumpWithCallback iterates over the Map and calls the given DumpCallback for each map entry. With the current implementation, it is safe for callbacks to retain the values received, as they are guaranteed to be new instances.

TODO(tb): This package currently doesn't support dumping per-cpu maps, as ReadValueSize is always set to the size of a single value.

func (*Map) DumpWithCallbackIfExists added in v0.15.7 

func (m *Map) DumpWithCallbackIfExists(cb DumpCallback) error

DumpWithCallbackIfExists is similar to DumpWithCallback, but returns earlier if the given map does not exist.

func (*Map) FD added in v0.15.7 

func (m *Map) FD() int

func (*Map) Flags added in v0.15.7 

func (m *Map) Flags() uint32

func (*Map) GetModel added in v0.15.7 

func (m *Map) GetModel() *models.BPFMap

GetModel returns a BPF map in the representation served via the API

func (*Map) IsEventsEnabled added in v0.15.7 

func (m *Map) IsEventsEnabled() bool

func (*Map) IsOpen added in v1.16.0 

func (m *Map) IsOpen() bool

IsOpen returns true if the map has been opened.

func (*Map) KeySize added in v0.15.7 

func (m *Map) KeySize() uint32

func (*Map) Lookup 

func (m *Map) Lookup(key MapKey) (MapValue, error)

func (*Map) MaxEntries added in v0.15.7 

func (m *Map) MaxEntries() uint32

func (*Map) Name added in v0.15.7 

func (m *Map) Name() string

Name returns the basename of this map.

func (*Map) NextKey added in v0.15.7 

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

func (*Map) NonPrefixedName added in v0.15.7 

func (m *Map) NonPrefixedName() string

func (*Map) Open 

func (m *Map) Open() error

Open opens the BPF map. All calls to Open() are serialized due to acquiring m.lock

func (*Map) OpenOrCreate 

func (m *Map) OpenOrCreate() error

OpenOrCreate attempts to open the Map, or if it does not yet exist, create the Map. If the existing map's attributes such as map type, key/value size, capacity, etc. do not match the Map's attributes, then the map will be deleted and reopened without any attempt to retain its previous contents. If the map is marked as non-persistent, it will always be recreated.

Returns whether the map was deleted and recreated, or an optional error.

func (*Map) Path added in v0.15.7 

func (m *Map) Path() (string, error)

Path returns the path to this map on the filesystem.

func (*Map) Recreate added in v0.15.7 

func (m *Map) Recreate() error

Recreate removes any pin at the Map's pin path, recreates and re-pins it.

func (*Map) SilentDelete added in v0.15.7 

func (m *Map) SilentDelete(key MapKey) (deleted bool, err error)

SilentDelete deletes the map entry corresponding to the given key. If a map entry is not found this returns (false, nil).

func (*Map) Type added in v0.15.7 

func (m *Map) Type() ebpf.MapType

func (*Map) Unpin added in v0.15.7 

func (m *Map) Unpin() error

Unpin attempts to unpin (remove) the map from the filesystem.

func (*Map) UnpinIfExists added in v0.15.7 

func (m *Map) UnpinIfExists() error

UnpinIfExists tries to unpin (remove) the map only if it exists.

func (*Map) Update 

func (m *Map) Update(key MapKey, value MapValue) error

func (*Map) UpdatePressureMetricWithSize added in v0.15.7 

func (m *Map) UpdatePressureMetricWithSize(size int32)

UpdatePressureMetricWithSize updates map pressure metric using the given map size.

func (*Map) ValueSize added in v0.15.7 

func (m *Map) ValueSize() uint32

func (*Map) WithCache added in v0.15.7 

func (m *Map) WithCache() *Map

WithCache enables use of a cache. This will store all entries inserted from user space in a local cache (map) and will indicate the status of each individual entry.

func (*Map) WithEvents added in v0.15.7 

func (m *Map) WithEvents(c option.BPFEventBufferConfig) *Map

WithEvents enables use of the event buffer, if the buffer is enabled. This stores all map events (i.e. add/update/delete) in a bounded event buffer. If eventTTL is not zero, than events that are older than the TTL will periodically be removed from the buffer. Enabling events will use aprox proportional to 100MB for every million capacity in maxSize.

TODO: The IPCache map have many periodic update events added by a controller for entries such as the 0.0.0.0/0 range. These fill the event buffer with possibly unnecessary events. We should either provide an option to aggregate these events, ignore hem from the ipcache event buffer or store them in a separate buffer.

func (*Map) WithGroupName added in v1.15.0 

func (m *Map) WithGroupName(group string) *Map

func (*Map) WithPressureMetric added in v0.15.7 

func (m *Map) WithPressureMetric() *Map

WithPressureMetric enables tracking and reporting of this map pressure with threshold 0.

func (*Map) WithPressureMetricThreshold added in v0.15.7 

func (m *Map) WithPressureMetricThreshold(threshold float64) *Map

WithPressureMetricThreshold enables the tracking of a metric that measures the pressure of this map. This metric is only reported if over the threshold.

type MapKey 

type MapKey interface {
	fmt.Stringer

	// New must return a pointer to a new MapKey.
	New() MapKey
}

type MapOut added in v0.15.7 

type MapOut[T any] struct {
	cell.Out

	Map    T
	BpfMap BpfMap `group:"bpf-maps"`
}

MapOut ensures that maps are created before the datapath loader is invoked.

func NewMapOut added in v0.15.7 

func NewMapOut[T any](m T) MapOut[T]

type MapValue 

type MapValue interface {
	fmt.Stringer

	// New must return a pointer to a new MapValue.
	New() MapValue
}

type StructBinaryMarshaler added in v1.16.0 

type StructBinaryMarshaler struct {
	Target any // pointer to struct
}

StructBinaryMarshaler implements a BinaryMarshaler for a struct of primitive fields. Same caviats apply as with cilium/ebpf when using a struct as key or value. Example usage: 

func (x *X) Key() encoding.BinaryMarshaler {
  return StructBinaryMarshaler{x}
}

func (StructBinaryMarshaler) MarshalBinary added in v1.16.0 

func (m StructBinaryMarshaler) MarshalBinary() ([]byte, error)

Source Files

View all Source files

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.