1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
# libbpfgo Upgrade Plan
## Goal
Upgrade `ior` from `github.com/aquasecurity/libbpfgo v0.6.0-libbpf-1.3.0...`
to the latest tagged upstream release `v0.9.2-libbpf-1.5.1`, and align the
repo's Go module, local static-link toolchain checkout, build instructions, and
runtime validation on that same tag.
## Current State
- `go.mod` / `go.sum` now pin
`github.com/aquasecurity/libbpfgo v0.9.2-libbpf-1.5.1`
- `Magefile.go` defaults to the sibling checkout at `../libbpfgo` (local path:
`/home/paul/git/libbpfgo`) and emits rebuild guidance if static
artifacts are missing
- The local checkout is currently ahead of the latest tag:
`v0.9.2-libbpf-1.5.1-23-g9a319d2`
- `README.md`, `AGENTS.md`, and `integrationtests/README.md` now pin the tag,
sync the `libbpf` submodule, and document the rebuild or validation workflow
- Integration coverage now passes again after restoring the legacy
`-flamegraph` / `-name` compatibility path used by the harness to collect
`.ior.zst` artifacts
## Upgrade Target
- Upstream tag: `v0.9.2-libbpf-1.5.1`
- Local checkout to use for static headers/archive:
`/home/paul/git/libbpfgo`
- Repo-relative default checkout path used by `Magefile.go`: `../libbpfgo`
- Override path for local experiments: `LIBBPFGO=/absolute/path/to/libbpfgo`
- Do not target `libbpfgo` `main` as part of this upgrade unless a tagged
release blocker is found
## Pinned Source of Truth
- `go.mod` / `go.sum` pin `github.com/aquasecurity/libbpfgo
v0.9.2-libbpf-1.5.1`
- `README.md`, `AGENTS.md`, and `integrationtests/README.md` document the same
checkout, tag, validation commands, and `make libbpfgo-static` workflow
- `Magefile.go` fails with explicit rebuild guidance when the local
`libbpfgo` checkout is missing the static artifacts that `ior` expects
- `internal/ior.go` preserves the legacy `-flamegraph` / `-name` trace-output
path required by the integration harness while leaving TUI and `-plain`
behavior unchanged
## Breaking-Change Watchpoints
- `v0.8.0-libbpf-1.5` includes a `BPFProg` API alignment change
- `v0.9.1-libbpf-1.5.1` changes `AttachUprobe` /
`AttachURetprobe` signatures
- `libbpf` minimum version moves from `1.3.x` to `1.5.1`
- Static builds require `git submodule update --init --recursive` in the local
`libbpfgo` checkout before `make libbpfgo-static`
`ior` appears to use a narrow subset of APIs:
- module loading (`NewModuleFromFile`, `NewModuleFromBuffer`, `BPFLoadObject`)
- maps (`GetMap`, `SetMaxEntries`, `InitGlobalVariable`)
- ringbuf (`InitRingBuf`)
- program lookup and tracepoint attach (`GetProgram`, `AttachTracepoint`)
The direct API-break risk is therefore expected to be low, but compile/runtime
validation is still required.
## Implementation Workstreams
1. Align the version source of truth
- Pin `go.mod` / `go.sum` to `v0.9.2-libbpf-1.5.1`
- Align the local checkout instructions in `README.md`
- Align `AGENTS.md` and `Magefile.go` guidance with the same tag and rebuild flow
- Ensure the local checkout is reset to the exact tag and rebuilt
2. Rebuild the local static toolchain
- In `/home/paul/git/libbpfgo`:
- `git checkout v0.9.2-libbpf-1.5.1`
- `git submodule update --init --recursive`
- `make libbpfgo-static`
3. Compile and fix `ior`
- Rebuild `ior` against the upgraded wrapper and static `libbpf`
- Fix any compile/API regressions in:
- `internal/ior.go`
- `internal/bpfsetup.go`
- `internal/bpfembed.go`
- any `probemanager` adapter code if signatures changed
4. Validate behavior
- Run `env GOTOOLCHAIN=auto mage world`
- Run root-required `env GOTOOLCHAIN=auto mage integrationTest`
- Specifically verify:
- embedded `ior.bpf.o` loading still works
- tracepoint attach/detach still works
- ring buffer event ingestion still works
- static build/link flags still work with the rebuilt local checkout
5. Finalize docs and rollback guidance
- Document the exact `libbpfgo` tag and rebuild commands
- Mention the local checkout path used by `Magefile.go`
- Add troubleshooting notes for submodule sync / static rebuild failures
- Record the rollback target: `go.mod` pseudo-version
`v0.6.0-libbpf-1.3.0.20240111220235-90dbffffbdab` plus local checkout
commit `90dbffffbdab`
## Validation Result
- `env GOTOOLCHAIN=auto mage world` passed after the pinning commit
`f28dab3`
- `env GOTOOLCHAIN=auto mage integrationTest` passed after compatibility fix
commit `28338f4`
- The embedded-object path is covered by
`env GOTOOLCHAIN=auto TEST_NAME=TestLoadBPFModuleUsesEmbeddedObjectByDefault mage testWithName`
## Troubleshooting
- Missing `bpf/bpf.h` or `libbpf` symbols usually means the sibling checkout is
not at `v0.9.2-libbpf-1.5.1` or was not rebuilt after a `git checkout`.
- Raw `go test` can still fail for packages that import `libbpfgo` because it
does not inherit the `CGO_CFLAGS`, `CGO_LDFLAGS`, and `LIBBPFGO` values that
`Magefile.go` sets up. Use Mage targets for validated flows.
- If integration tests fail immediately with unknown `-flamegraph` /
`-name` flags, rebuild `ior` from a checkout that includes commit `28338f4`.
## Rollback
If the tagged release proves insufficient, revert the `ior` side to
`github.com/aquasecurity/libbpfgo
v0.6.0-libbpf-1.3.0.20240111220235-90dbffffbdab`, reset the sibling checkout,
and rebuild:
```bash
git -C /home/paul/git/libbpfgo checkout 90dbffffbdab
git -C /home/paul/git/libbpfgo submodule update --init --recursive
make -C /home/paul/git/libbpfgo libbpfgo-static
```
## Validation Commands
- `GOTOOLCHAIN=auto mage test`
- `GOTOOLCHAIN=auto mage world`
- `GOTOOLCHAIN=auto mage integrationTest`
## References
- Repo files:
- `go.mod`
- `README.md`
- `AGENTS.md`
- `Magefile.go`
- `internal/ior.go`
- `internal/bpfsetup.go`
- `internal/bpfembed.go`
- Local toolchain checkout:
- `/home/paul/git/libbpfgo`
|
