This is an old revision of the document!
Network Stack KPI/KBI
This wiki page attempts to identify kernel data structures which, if changed after a .0 release on a branch, may prevent network device drivers, firewall modules, as well as userland monitoring tools, etc, from working properly.
Data structure statuses
The following status options exist for each structure:
Immutable - This data structure must not be changed
The data structure is very sensitive to change, as it may be allocated statically in BSS or on the stack by modules, or directly accessed by userland programs that require it to remain the same length. Changing the size of the structure could lead to (possibly extensive) kernel memory corruption, broken userland monitoring tools, etc.
Padded - Spare fields may be changed as long as the size remains the same
The same as immutable except that spare fields have been added to the structure in order to allow new functionality to be added despite the structure layout being fixed. Care should be taken when using spare fields, especially relating to the lengths of types like long or void *, which may vary by architecture. Likewise, the initialized values of structures may vary based on how the are allocated, so old code may not be aware of new initialization requirements: if allocated in BSS, fields may simply be zeroed, but if on the stack they may contain arbitrary values.
Extendable - New fields may be added at the end of the data structure
These data structures are visible in APIs used by third-party code, but the data structures are always allocated and managed by the base kernel; existing fields can't be changed, but new fields may be added, with caution.
Private - May be changed with (relative) impunity
These data structures are used only inside of the kernel or specific modules, and the layout may be changed without (excessive) concern.
sys
| struct mbuf | Immutable | Extreme caution required. |
| struct sockopt | ||
| struct sockaddr | Immutable | Allocated statically and part of the system call ABI. |
| struct unpcb | ||
| struct xsocket | ||
| struct xunpcb |
net
| Type | Status | Comments |
|---|---|---|
| struct bpf_d | Extendable | Allocated only in bpf.c, but fields accessed by MAC policy modules. |
| struct ifaddr | Immutable | Embedded in other data structures in protocols, such as in_ifaddr, etc. |
| struct ifnet | Padded | Allocated only in if.c, but used in all device drivers, and monitored from userspace via KVM. May now be safe to change this to Extendable. |
| struct netisr_handler | Padded | Allocated statically by protocol modules in BSS, but padded for future growth. |
| struct route | Immutable | Allocated statically in BSS, inside of data structures, and on the stack by protocols, device drivers, etc. |
| struct rtentry |
netinet
| Type | Status | Comments |
|---|
| struct in_addr | ||
| struct in_ifaddr | ||
| struct inpcb | ||
| struct inpcbinfo | Immutable | Embedded in struct vinet; accessed by user monitoring tools via KVM. |
| struct ipq | ||
| struct route_in | ||
| struct sockaddr_in | Immutable | Allocated statically and part of the system call ABI; embedded in other data structures. |
| struct syncache | Extendable | Currently allocated/consumed only in TCP, but user monitoring tools will access it via KVM in the future. |
| struct syncache_head | ||
| struct tcp_hostcache | Extendable | Currently allocated/consumed only in TCP, but user monitoring tools will access it via KVM in the future. |
| struct tcpcb | ||
| struct tcptw | ||
| struct tcp_syncache | Immutable | Embedded in struct vinet; user monitoring tools will access it via KVM in the future. |
| struct udpdb | Private | Currently allocated and accessed only by UDP/UDP6, but may be accessed via KVM by user monitoring tools in the future. |