ebpfmon is a tool for monitoring eBPF programs. It is designed to be used with bpftool from the linux kernel. ebpfmon is a TUI (terminal UI) application written in Go that allows you to do real-time monitoring of eBPF programs.
eBPFmon can be built from source or there is a compiled version of it available in the releases
- bpftool (installed from a package manager or built from source). This is what ebpfmon uses to get information regarding eBPF programs, maps, etc
- libelf
- zlib
- libcap-devel
- libbfd
$ sudo apt install linux-tools-`uname -r` libelf-dev zlib1g-dev libcap-dev binutils-dev$ sudo yum install bpftool elfutils-libelf-devel libcap-devel binutils-devel$ sudo dnf install elfutils-libelf-devel libcap-devel zlib-devel binutils-devel bpftool$ sudo apt install bpftool libelf-dev zlib1g-dev libcap-dev binutils-dev$ ./ebpfmonNOTE: bpftool needs root privileges and so ebpfmon will run sudo bpftool ....
This means you will likely be prompted to enter your sudo password.
First and foremost this tool is written in Go so you will need to have that installed and in your PATH variable. It should work on go 1.18 or later although it's possible it could work on earlier versions. It just hasn't been tested
Next, make sure to install the following dependencies.
- clang
- llvm
Simply run the following commands. This will build the ebpfmon binary in the current directory
$ git clone https://github.com/redcanaryco/ebpfmon.git
$ cd ebpfmon
$ makeThe main view for ebpfmon is the program view. This view shows all the eBPF
programs that are currently loaded on the system. Each pane is selectable and
you can swith between panes by using the tab key. In a given pane you can use
the arrow keys to move the scroll the text or list selection up and down.
For lists such as the programs or maps you can press enter to select. Selecting
a program will populate the other other panes with information about that
program. Selecting a map will switch to a map entry view that shows the entries
for that map.
There are a few keybindings that are available in ebpfmon. These are listed
on the help page which can be access by pressing the F1 key or the ? key
To access the program view regardless of which view you are on you can press Ctrl and e.
To access the bpf feature view regardless of which view you are on you can press Ctrl and f.
To access the map view simply select a map (if one exists) for the current eBPF program. This will populate the map view with the map entries. You can delete map entries by pressing the d key. In the map view you can format the map entry data in various ways. To get to the format section simply press TAB while in the map entry list view. You can then use TAB to move between the different format options. To get back to the map entry list press ESC
You can also edit map entries by pressing ENTER on a selection. In the edit view you can edit the raw byte values of the map key/value. You can ignore the square brackets
To quit the application you can press q or Q
Generally the ESC key should take you back to the previous view you were on. Also, if you are in the help view or error view, pressing escape should return you to the previous window.
Allows you to specify the path to the bpftool binary. This is useful if you have a custom build of bpftool that you want to use. By default it will use the system's bpftool binary. You can also use an environemnt variable. It will look in the following order
- Check if the
-bpftoolargument was speified on the command line - Check if the environment variable
BPFTOOL_PATHis set. - Use the system binary
This argument allows you to specify a file to log to. By default it will log to
./log.txt. This is a great file to check when trying to debug issues with the
application as it will log errors that occured during runtime.
There are some basic tests associated with this project.
To run the tests simply the following command from the root directory of the project
$ go test ./...If you want to use your own bpftool binary you can set the BPFTOOL_PATH environment variable to the path of your bpftool binary. If not it will default to using the system one.
- Frozen Maps: If a map is marked as frozen that means no future syscall invocations may alter the map state of map_fd. Write operations from eBPF programs are still possible for a frozen map. This means that bpftool (which is what is uised by ebpfmon) will not be able to alter the map entries. This is a limitation of bpftool and not ebpfmon.
- Ring buffers: bpftool will likely not get any data when trying to query a map of type ringbuf