Documentation ¶
Overview ¶
Package bpf provides functions that allow golang programs to interact with bpf maps. +groupName=pkg
Index ¶
- Constants
- Variables
- func CheckOrMountFS(bpfRoot string)
- func ConvertKeyValue(bKey []byte, bValue []byte, key MapKey, value MapValue) (MapKey, MapValue, error)
- func CreateMap(mapType MapType, keySize, valueSize, maxEntries, flags, innerID uint32, ...) (int, error)
- func DeleteElement(fd int, key unsafe.Pointer) error
- func DisableMapPreAllocation()
- func EnableMapPreAllocation()
- func Environment() []string
- func FinalizeBPFFSMigration(bpffsPath, elfPath string, revert bool) error
- func GetFirstKey(fd int, nextKey unsafe.Pointer) error
- func GetJtime() (uint64, error)
- func GetMapRoot() string
- func GetMtime() (uint64, error)
- func GetNextKey(fd int, key, nextKey unsafe.Pointer) error
- func GetNextKeyFromPointers(fd int, structPtr unsafe.Pointer, sizeOfStruct uintptr) error
- func GetOpenMaps() []*models.BPFMap
- func GetPreAllocateMapFlags(t MapType) uint32
- func LocalMapName(name string, id uint16) string
- func LocalMapPath(name string, id uint16) string
- func LookupElement(fd int, key, value unsafe.Pointer) error
- func LookupElementFromPointers(fd int, structPtr unsafe.Pointer, sizeOfStruct uintptr) error
- func MapFdFromID(id int) (int, error)
- func MapPath(name string) string
- func MapPrefixPath() string
- func ObjClose(fd int) error
- func ObjGet(pathname string) (int, error)
- func ObjPin(fd int, pathname string) error
- func OpenOrCreateMap(path string, mapType MapType, keySize, valueSize, maxEntries, flags uint32, ...) (int, bool, error)
- func StartBPFFSMigration(bpffsPath, elfPath string) error
- func TestDummyProg(progType ProgType, attachType uint32) error
- func UnpinMapIfExists(name string) error
- func UpdateElement(fd int, mapName string, key, value unsafe.Pointer, flags uint64) error
- func UpdateElementFromPointers(fd int, mapName string, structPtr unsafe.Pointer, sizeOfStruct uintptr) error
- type DesiredAction
- type DumpCallback
- type DumpParser
- type DumpStats
- type EndpointKey
- type Map
- func (m *Map) CheckAndUpgrade(desired *MapInfo) bool
- func (m *Map) Close() error
- func (m *Map) Create() (bool, error)
- func (m *Map) CreateUnpinned() error
- func (m *Map) Delete(key MapKey) error
- func (m *Map) DeleteAll() error
- func (m *Map) Dump(hash map[string][]string) error
- func (m *Map) DumpIfExists(hash map[string][]string) error
- func (m *Map) DumpReliablyWithCallback(cb DumpCallback, stats *DumpStats) error
- func (m *Map) DumpWithCallback(cb DumpCallback) error
- func (m *Map) DumpWithCallbackIfExists(cb DumpCallback) error
- func (m *Map) EndParallelMode()
- func (m *Map) GetFd() int
- func (m *Map) GetModel() *models.BPFMap
- func (m *Map) GetNextKey(key MapKey, nextKey MapKey) error
- func (m *Map) Lookup(key MapKey) (MapValue, error)
- func (m *Map) Name() string
- func (m *Map) NonPrefixedName() string
- func (m *Map) Open() error
- func (m *Map) OpenOrCreate() (bool, error)
- func (m *Map) OpenParallel() (bool, error)
- func (m *Map) Path() (string, error)
- func (m *Map) Reopen() error
- func (m *Map) SilentDelete(key MapKey) (deleted bool, err error)
- func (m *Map) Unpin() error
- func (m *Map) UnpinIfExists() error
- func (m *Map) Update(key MapKey, value MapValue) error
- func (m *Map) WithCache() *Map
- func (m *Map) WithNonPersistent() *Map
- func (m *Map) WithPressureMetric() *Map
- func (m *Map) WithPressureMetricThreshold(threshold float64) *Map
- type MapInfo
- type MapKey
- type MapType
- type MapValidator
- type MapValue
- type ProgType
Constants ¶
const ( // BPF syscall command constants. Must match enum bpf_cmd from linux/bpf.h BPF_MAP_CREATE = 0 BPF_MAP_LOOKUP_ELEM = 1 BPF_MAP_UPDATE_ELEM = 2 BPF_MAP_DELETE_ELEM = 3 BPF_MAP_GET_NEXT_KEY = 4 BPF_PROG_LOAD = 5 BPF_OBJ_PIN = 6 BPF_OBJ_GET = 7 BPF_PROG_ATTACH = 8 BPF_PROG_DETACH = 9 BPF_PROG_TEST_RUN = 10 BPF_PROG_GET_NEXT_ID = 11 BPF_MAP_GET_NEXT_ID = 12 BPF_PROG_GET_FD_BY_ID = 13 BPF_MAP_GET_FD_BY_ID = 14 BPF_OBJ_GET_INFO_BY_FD = 15 BPF_PROG_QUERY = 16 BPF_RAW_TRACEPOINT_OPEN = 17 BPF_BTF_LOAD = 18 BPF_BTF_GET_FD_BY_ID = 19 BPF_TASK_FD_QUERY = 20 // BPF syscall attach types BPF_CGROUP_INET_INGRESS = 0 BPF_CGROUP_INET_EGRESS = 1 BPF_CGROUP_INET_SOCK_CREATE = 2 BPF_CGROUP_SOCK_OPS = 3 BPF_SK_SKB_STREAM_PARSER = 4 BPF_SK_SKB_STREAM_VERDICT = 5 BPF_CGROUP_DEVICE = 6 BPF_SK_MSG_VERDICT = 7 BPF_CGROUP_INET4_BIND = 8 BPF_CGROUP_INET6_BIND = 9 BPF_CGROUP_INET4_CONNECT = 10 BPF_CGROUP_INET6_CONNECT = 11 BPF_CGROUP_INET4_POST_BIND = 12 BPF_CGROUP_INET6_POST_BIND = 13 BPF_CGROUP_UDP4_SENDMSG = 14 BPF_CGROUP_UDP6_SENDMSG = 15 BPF_LIRC_MODE2 = 16 BPF_FLOW_DISSECTOR = 17 BPF_CGROUP_SYSCTL = 18 BPF_CGROUP_UDP4_RECVMSG = 19 BPF_CGROUP_UDP6_RECVMSG = 20 BPF_CGROUP_INET4_GETPEERNAME = 29 BPF_CGROUP_INET6_GETPEERNAME = 30 BPF_CGROUP_INET4_GETSOCKNAME = 31 BPF_CGROUP_INET6_GETSOCKNAME = 32 // Flags for BPF_MAP_UPDATE_ELEM. Must match values from linux/bpf.h BPF_ANY = 0 BPF_NOEXIST = 1 BPF_EXIST = 2 // Flags for BPF_MAP_CREATE. Must match values from linux/bpf.h BPF_F_NO_PREALLOC = 1 << 0 BPF_F_NO_COMMON_LRU = 1 << 1 BPF_F_NUMA_NODE = 1 << 2 // Flags for BPF_PROG_QUERY BPF_F_QUERY_EFFECTVE = 1 << 0 // Flags for accessing BPF object BPF_F_RDONLY = 1 << 3 BPF_F_WRONLY = 1 << 4 // Flag for stack_map, store build_id+offset instead of pointer BPF_F_STACK_BUILD_ID = 1 << 5 )
const ( EndpointKeyIPv4 uint8 = 1 EndpointKeyIPv6 uint8 = 2 )
Must be in sync with ENDPOINT_KEY_* in <bpf/lib/common.h>
Variables ¶
var ErrMaxLookup = errors.New("maximum number of lookups reached")
ErrMaxLookup is returned when the maximum number of map element lookups has been reached.
Functions ¶
func CheckOrMountFS ¶
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 ConvertKeyValue ¶
func ConvertKeyValue(bKey []byte, bValue []byte, key MapKey, value MapValue) (MapKey, MapValue, error)
ConvertKeyValue converts key and value from bytes to given Golang struct pointers.
func CreateMap ¶
func CreateMap(mapType MapType, keySize, valueSize, maxEntries, flags, innerID uint32, path string) (int, error)
CreateMap creates a Map of type mapType, with key size keySize, a value size of valueSize and the maximum amount of entries of maxEntries. mapType should be one of the bpf_map_type in "uapi/linux/bpf.h" When mapType is the type HASH_OF_MAPS an innerID is required to point at a map fd which has the same type/keySize/valueSize/maxEntries as expected map entries. For all other mapTypes innerID is ignored and should be zeroed.
func DeleteElement ¶
DeleteElement deletes the map element with the given key.
func DisableMapPreAllocation ¶
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 ¶
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 Environment ¶
func Environment() []string
Environment returns a list of environment variables which are needed to make BPF programs and tc aware of the actual BPFFS mount path.
func FinalizeBPFFSMigration ¶
FinalizeBPFFSMigration finalizes the migration of an ELF's maps. If revert is true, any pending maps are re-pinned back to their original locations. If revert is false, any pending maps are unpinned (deleted).
Takes a bpffsPath explicitly since it does not necessarily execute within the same runtime as the agent. It is imported from a Cilium cmd that takes its bpffs path from an env.
func GetFirstKey ¶
GetFirstKey fetches the first key in the map. If there are no keys in the map, io.EOF is returned.
func GetJtime ¶
GetJtime returns a close-enough approximation of kernel jiffies that can be used to compare against jiffies BPF helper. We parse it from /proc/timer_list. GetJtime() should be invoked only at mid-low frequencies.
func GetMapRoot ¶
func GetMapRoot() string
func GetMtime ¶
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 GetNextKey ¶
GetNextKey stores, in nextKey, the next key after the key of the map in fd. Deprecated, use GetNextKeyFromPointers
func GetNextKeyFromPointers ¶
GetNextKeyFromPointers stores, in nextKey, the next key after the key of the map in fd. When there are no more keys, io.EOF is returned.
func GetOpenMaps ¶
GetOpenMaps returns a slice of all open BPF maps. This is identical to calling GetMap() on all open maps.
func GetPreAllocateMapFlags ¶
GetPreAllocateMapFlags returns the map flags for map which use conditional pre-allocation.
func LocalMapName ¶
LocalMapName returns the name for a BPF map that is local to the specified ID.
func LocalMapPath ¶
LocalMapPath returns the path for a BPF map that is local to the specified ID.
func LookupElement ¶
LookupElement looks up for the map value stored in fd with the given key. The value is stored in the value unsafe.Pointer. Deprecated, use LookupElementFromPointers
func LookupElementFromPointers ¶
LookupElement looks up for the map value stored in fd with the given key. The value is stored in the value unsafe.Pointer.
func MapFdFromID ¶
MapFdFromID retrieves a file descriptor based on a map ID.
func MapPrefixPath ¶
func MapPrefixPath() string
func OpenOrCreateMap ¶
func StartBPFFSMigration ¶
StartBPFFSMigration the map migration process for a given ELF's maps. When a new ELF contains a map definition that differs from its existing (pinned) counterpart, re-pin it to its current path suffixed by ':pending'. A map's type, key size, value size, flags and max entries are compared to the given spec.
Takes a bpffsPath explicitly since it does not necessarily execute within the same runtime as the agent. It is imported from a Cilium cmd that takes its bpffs path from an env.
func TestDummyProg ¶
TestDummyProg loads a minimal BPF program into the kernel and probes whether it succeeds in doing so. This can be used to bail out early in the daemon when a given type is not supported.
func UnpinMapIfExists ¶
UnpinMapIfExists unpins the given map identified by name. If the map doesn't exist, returns success.
func UpdateElement ¶
UpdateElement updates the map in fd with the given value in the given key. The flags can have the following values: bpf.BPF_ANY to create new element or update existing; bpf.BPF_NOEXIST to create new element if it didn't exist; bpf.BPF_EXIST to update existing element. Deprecated, use UpdateElementFromPointers
Types ¶
type DesiredAction ¶
type DesiredAction int
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 ¶
func (d DesiredAction) String() string
type DumpCallback ¶
type DumpParser ¶
type DumpStats ¶
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 // 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 ¶
NewDumpStats returns a new stats structure for collecting dump statistics.
type EndpointKey ¶
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"` Pad2 uint16 `align:"pad5"` }
EndpointKey represents the key value of the endpoints BPF map
Must be in sync with struct endpoint_key in <bpf/lib/common.h> +k8s:deepcopy-gen=true
func NewEndpointKey ¶
func NewEndpointKey(ip net.IP) EndpointKey
NewEndpointKey returns an EndpointKey based on the provided IP address. The address family is automatically detected.
func (*EndpointKey) DeepCopy ¶
func (in *EndpointKey) DeepCopy() *EndpointKey
DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EndpointKey.
func (*EndpointKey) DeepCopyInto ¶
func (in *EndpointKey) DeepCopyInto(out *EndpointKey)
DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (*EndpointKey) GetKeyPtr ¶
func (k *EndpointKey) GetKeyPtr() unsafe.Pointer
GetKeyPtr returns the unsafe pointer to the BPF key
func (*EndpointKey) GetValuePtr ¶
func (k *EndpointKey) GetValuePtr() unsafe.Pointer
GetValuePtr returns the unsafe pointer to the BPF key for users that use EndpointKey as a value in bpf maps
func (EndpointKey) String ¶
func (k EndpointKey) String() string
String provides a string representation of the EndpointKey.
func (EndpointKey) ToIP ¶
func (k EndpointKey) ToIP() net.IP
ToIP converts the EndpointKey into a net.IP structure.
type Map ¶
type Map struct { MapInfo // NonPersistent is true if the map does not contain persistent data // and should be removed on startup. NonPersistent bool // DumpParser is a function for parsing keys and values from BPF maps DumpParser DumpParser // contains filtered or unexported fields }
func NewMap ¶
func NewMap(name string, mapType MapType, mapKey MapKey, keySize int, mapValue MapValue, valueSize, maxEntries int, flags uint32, innerID uint32, dumpParser DumpParser) *Map
NewMap creates a new Map instance - object representing a BPF map
func NewPerCPUHashMap ¶
func NewPerCPUHashMap(name string, mapKey MapKey, keySize int, mapValue MapValue, valueSize, cpus, maxEntries int, flags uint32, innerID uint32, dumpParser DumpParser) *Map
NewPerCPUHashMap creates a new Map type of "per CPU hash" - object representing a BPF map The number of cpus is used to have the size representation of a value when a lookup is made on this map types.
func OpenMap ¶
OpenMap opens the given bpf map and generates the Map info based in the information stored in the bpf map. *Warning*: Calling this function requires the caller to properly setup the MapInfo.MapKey and MapInfo.MapValues fields as those structures are not stored in the bpf map.
func (*Map) CheckAndUpgrade ¶
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) Create ¶
Create is similar to OpenOrCreate, but closes the map after creating or opening it.
func (*Map) CreateUnpinned ¶
CreateUnpinned creates the map without pinning it to the file system.
func (*Map) DeleteAll ¶
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 ¶
Dump returns the map (type map[string][]string) which contains all data stored in BPF map.
func (*Map) DumpIfExists ¶
DumpIfExists dumps the contents of the map into hash via Dump() if the map file exists
func (*Map) DumpReliablyWithCallback ¶
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 ¶
func (m *Map) DumpWithCallback(cb DumpCallback) error
DumpWithCallback iterates over the Map and calls the given callback function on each iteration. That callback function is receiving the actual key and value. The callback function should consider creating a deepcopy of the key and value on between each iterations to avoid memory corruption.
func (*Map) DumpWithCallbackIfExists ¶
func (m *Map) DumpWithCallbackIfExists(cb DumpCallback) error
DumpWithCallbackIfExists is similar to DumpWithCallback, but returns earlier if the given map does not exist.
func (*Map) EndParallelMode ¶
func (m *Map) EndParallelMode()
EndParallelMode ends the parallel mode of a map
func (*Map) GetNextKey ¶
GetNextKey returns the next key in the Map after key.
func (*Map) NonPrefixedName ¶
func (*Map) Open ¶
Open opens the BPF map. All calls to Open() are serialized due to acquiring m.lock
func (*Map) OpenOrCreate ¶
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.
If the map type is MapTypeLRUHash or MapTypeLPMTrie and the kernel lacks support for this map type, then the map will be opened as MapTypeHash instead. Note that the BPF code that interacts with this map *MUST* be structured in such a way that the map is declared as the same type based on the same probe logic (eg HAVE_LRU_HASH_MAP_TYPE, HAVE_LPM_TRIE_MAP_TYPE).
For code that uses an LPMTrie, the BPF code must also use macros to retain the "longest prefix match" behaviour on top of the hash maps, for example via LPM_LOOKUP_FN() (see bpf/lib/maps.h).
Returns whether the map was deleted and recreated, or an optional error.
func (*Map) OpenParallel ¶
OpenParallel is similar to OpenOrCreate() but prepares the existing map to be faded out while a new map is taking over. This can be used if a map is shared between multiple consumers and the context of the shared map is changing. Any update to the shared map would impact all consumers and consumers can only be updated one by one. Parallel mode allows for consumers to continue using the old version of the map until the consumer is updated to use the new version.
func (*Map) SilentDelete ¶
SilentDelete deletes the map entry corresponding to the given key. If a map entry is not found this returns (true, nil).
func (*Map) UnpinIfExists ¶
UnpinIfExists tries to unpin (remove) the map only if it exists.
func (*Map) WithCache ¶
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) WithNonPersistent ¶
WithNonPersistent turns the map non-persistent and returns the map
func (*Map) WithPressureMetric ¶
WithPressureMetric enables tracking and reporting of this map pressure with threshold 0.
func (*Map) WithPressureMetricThreshold ¶
WithPressureMetricThreshold enables the tracking of a metric that measures the pressure of this map. This metric is only reported if over the threshold.
type MapInfo ¶
type MapInfo struct { MapType MapType MapKey MapKey KeySize uint32 MapValue MapValue // ReadValueSize is the value size that is used to read from the BPF maps // this value and the ValueSize values can be different for MapTypePerCPUHash. ReadValueSize uint32 ValueSize uint32 MaxEntries uint32 Flags uint32 InnerID uint32 OwnerProgType ProgType }
type MapType ¶
type MapType int
MapType is an enumeration for valid BPF map types
const ( MapTypeUnspec MapType = iota MapTypeHash MapTypeArray MapTypeProgArray MapTypePerfEventArray MapTypePerCPUHash MapTypePerCPUArray MapTypeStackTrace MapTypeCgroupArray MapTypeLRUHash MapTypeLRUPerCPUHash MapTypeLPMTrie MapTypeArrayOfMaps MapTypeHashOfMaps MapTypeDevMap MapTypeSockMap MapTypeCPUMap MapTypeXSKMap MapTypeSockHash // MapTypeMaximum is the maximum supported known map type. MapTypeMaximum )
This enumeration must be in sync with enum bpf_map_type in <linux/bpf.h>
func GetMapType ¶
GetMapType determines whether the specified map type is supported by the kernel (as determined by bpftool feature checks), and if the map type is not supported, returns a more primitive map type that may be used to implement the map on older implementations. Otherwise, returns the specified map type.
type MapValidator ¶
type ProgType ¶
type ProgType int
ProgType is an enumeration for valid BPF program types
const ( ProgTypeUnspec ProgType = iota ProgTypeSocketFilter ProgTypeKprobe ProgTypeSchedCls ProgTypeSchedAct ProgTypeTracepoint ProgTypeXdp ProgTypePerfEvent ProgTypeCgroupSkb ProgTypeCgroupSock ProgTypeLwtIn ProgTypeLwtOut ProgTypeLwtXmit ProgTypeSockOps ProgTypeSkSkb ProgTypeCgroupDevice ProgTypeSkMsg ProgTypeRawTracepoint ProgTypeCgroupSockAddr ProgTypeLwtSeg6Local ProgTypeLircMode2 ProgTypeSkReusePort )
This enumeration must be in sync with enum bpf_prog_type in <linux/bpf.h>