plugins/network/README.md

0001 Per-process Network Usage Plugin
0002 ================================
0003
0004 This plugin tries to track per-process network usage and feeds that back to
0005 ksysguard. Unfortunately, at the moment there is no unprivileged API available
0006 for this information, so this plugin uses a small helper application to work
0007 around that. The helper uses libpcap to do packet capture. To do the packet
0008 capture it needs `cap_net_raw`, but nothing else. To ensure the helper has
0009 `cap_net_raw`, run `setcap cap_net_raw+ep ksgrd_network_helper` as root.
0010
0011 The helper only tracks TCP and UDP traffic, on IPv4 or IPv6 networks. Only the
0012 beginning of each packet is captured, so we only get the packet headers. These
0013 are processed to extract the source and destination IP address and port, which
0014 are matched with sockets and processes.
0015
0016 The matching uses information parsed from `/proc/net/tcp{,6}` and
0017 `/proc/net/udp{,6}` for the sockets, which are mapped to processes by listing
0018 fds from `/proc/${pid}/fd/` and reading their symlink targets. Entries matching
0019 `socket:[${port}]` are used to track socket to process mapping.
0020
0021 Once mapped, we store how much data was received for each process by
0022 accumulating the packet sizes for each socket. Every second this information is
0023 printed to the helper's stdout using the format
0024 `00:00:00|PID|0000|IN|000|OUT|000` or just `00:00:00` if there was no data that
0025 second. The helper's stdout is read and parsed by the network plugin and fed
0026 into ksysguard.