bpf
v1.3.1
Published
Bindings for eBPF (libbpf)
Downloads
12
Maintainers
Readme
bpf
Node.js bindings to libbpf. BPF is a Virtual Machine (and associated bytecode definition) embedded in the Linux kernel. This module allows you to:
Assemble & compile BPF programs
Use the kernel's
ebpf
interface:- Load programs into the kernel
- Attach them to events
- Create & manipulate eBPF maps
- Other: perf events, check feature availability, pin objects to BPFFS, query program bytecode, BTF data, etc.
Status
Not enough functionality for standalone use yet.
There's a generic API to create (createMap
) and manipulate (IMap
) eBPF maps of any type, including map-in-map support, but only some map types are currently tested. There's no BTF support for now.
It has a raw version (which operates with binary Buffer
s directly), and a high-level version which uses a conversion supplied by the user.
Apart from the generic API, there's a few other sub-APIs for specific map types, such as IArrayMap
for ARRAY
maps. These also have raw and high-level versions.
Usage
There's prebuilds for x86, x64, arm32v7 and arm64v8, so you don't need anything in those cases.
For other archs, libbpf and its dependencies are included so you only need a compiler:
sudo apt install build-essential
Then, install this module:
npm install bpf
libbpf is kernel agnostic, but not all of the exposed features may be supported by the running kernel, even if they are present in the API and typings. This extends to everything (functions, flags, map types, ...). For some notable cases, we make a mention in the docs, but for a full reference of features and their required kernel versions, go here. If a feature isn't supported by your kernel and you try to use it, you'll likely get an EINVAL
error.
Examples
Raw map operations
const bpf = require('bpf')
// Create a HASH map, with 4-byte keys and values
const ref = bpf.createMap({
type: bpf.MapType.HASH,
keySize: 4, valueSize: 4,
maxEntries: 10
})
// Wrap it in `RawMap` to operate with it
const map = new bpf.RawMap(ref)
// Add some entries
const key1 = Buffer.of(0,0,0,1), key2 = Buffer.of(0,0,9,2)
map.set(key1, Buffer.from('abcd'))
map.set(key2, Buffer.from('w00t'))
// Print entries (warning: HASH has no order)
for (const [k, v] of map)
console.log('entry', k.toString('hex'), '=', v.toString('ascii'))
// entry 00000902 = w00t
// entry 00000001 = abcd
map.get(key2) // -> <Buffer 77 30 30 74>
map.delete(key2) // -> true
map.get(key2) // -> undefined
Using conversions
// We'll have NUL-terminated strings as keys, and uint32 values
const ref = bpf.createMap({
type: bpf.MapType.HASH,
keySize: 16, valueSize: 4,
maxEntries: 7
})
// bpf already provides a conversion for uint32, for convenience
// So we only need to write one for the keys
const stringConversion = {
parse: (buf) => {
const size = buf.indexOf(0)
return buf.slice(0, size === -1 ? buf.length : size).toString()
},
format: (buf, x) => {
buf.fill(0)
buf.write(x)
}
}
const map = new bpf.ConvMap(ref, stringConversion, bpf.u32type)
map.set('a cat', 1)
map.set('foo', 3458)
map.set('test', 5)
[...map] // -> [ ['foo', 3458], ['test', 5], ['a cat', 1] ]
Array maps
const doubleConversion = {
parse: (buf) => buf.readDoubleLE(),
format: (buf, x) => buf.writeDoubleLE(x),
}
const ref = bpf.createMap({
type: bpf.MapType.ARRAY,
keySize: 4, // always 4
valueSize: 8,
maxEntries: 5 // array length
})
const array = new bpf.ConvArrayMap(ref, doubleConversion)
// Or equivalently...
const array2 = bpf.createArrayMap(5, 8, doubleConversion)
// Values are initialized to zero
[...array] // -> [ 0, 0, 0, 0, 0 ]
array.set(3, 106.5)
[...array] // -> [ 0, 0, 0, 106.5, 0 ]
Using your own FD
const fd = getMapFDFromSomewhereElse()
// By default it duplicates the FD, leaving the original FD unaffected
const ref = bpf.createMapRef(fd)
ref.fd === fd // -> false
// Use the `transfer` option if you want bpf to take its ownership
const ref2 = bpf.createMapRef(fd, { transfer: true })
ref2.fd === fd // -> true
const map = new RawMap(ref)
// ...
Map-in-map
// our values will be ARRAY maps
const innerParams = {
type: bpf.MapType.ARRAY,
keySize: 4, valueSize: 4,
maxEntries: 5
}
const createInnerMap = () =>
new bpf.ConvArrayMap(bpf.createMap(innerParams), bpf.u32type)
// create an ARRAY_OF_MAPS, passing the inner parameters
const ref = bpf.createMap({
type: bpf.MapType.ARRAY_OF_MAPS,
keySize: 4, valueSize: 4,
maxEntries: 7,
innerMap: innerParams
})
const map = new bpf.ConvMap(ref, bpf.u32type, bpf.u32type)
// the map is initially empty
[...map] // -> []
// to set an entry, pass the FD of a suitable map
const value1 = createInnerMap()
map.set(2, value1.ref.fd)
// when getting, the *ID* will be returned instead
map.get(2) === value1.ref.id // -> true