jethrogb / netlink

netlink libraries for rust

netlink-rs

This project aims at providing building blocks for the netlink protocol (see man 7 netlink).

The netlink protocol is huge but the some subprotocols are widely used:

• the generic netlink protocol, used to create custom IPCs
• the rtnetlink protocol (see man 7 rtnetlink), for manipulating the network stack
• the audit protocol to interact with Linux audit system
• the sock_diag protocol (see man 7 sock_diag) to monitor sockets

Organization

• the netlink_sys crate provides netlink sockets. Integration with mio and tokio is optional.
• Each netlink protocol has a netlink-packet-<protocol_name> crate that provides the packets for this protocol:
  • netlink-packet-route provides RtnlMessage which represents messages for the route protocol
  • netlink-packet-audit provides AuditMessage which represents messages for the audit protocol
• the netlink-packet-core is the glue for all the other netlink-packet-* crates. I provides a unique NetlinkMessage<T> type that represent any netlink message for any sub-protocol.
• the netlink_proto crate an asynchronous implementation of the netlink protocol. It only depends on netlink-packet-core for the NetlinkMessage type and netlink-sys for the socket.
• the rtnetlink crate provides higher level abstraction for the route protocol (see man 7 rtnetlink). This is probably what users want to use, if they want to manipulate IP addresses, route tables, etc.
• the audit crate provides higher level abstractions for the audit protocol.

Other netlink projects in rust

• https://github.com/jbaublitz/neli: the main alternative to these crates, as it is actively developed.
• Other but less actively developed alternatives:
  • https://github.com/achanda/netlink
  • https://github.com/polachok/pnetlink
  • https://github.com/crhino/netlink-rs
  • https://github.com/carrotsrc/rsnl
  • https://github.com/TaborKelly/nl-utils

Other non-rust netlink projects

• libnl: netlink implementation in C. Very complete with awesome documentation.
• pyroute2: a very complete and readable implementation in pure python.
• netlink: a very complete and very actively maintained go project, seems to be widely used.

Credits

My main resource so far has been the source code of pyroute2 and netlink a lot. These two projects are great, and very nicely written. As someone who does not read C fluently, and that does not know much about netlink, they have been invaluable.

I'd also like to praise libnl for its documentation. It helped me a lot in understanding the protocol basics.

The whole packet parsing logic is inspired by @whitequark excellent blog posts (part 1, part 2 and part 3, although I've only really used the concepts described in the first blog post). These ideas are also being used in @m-labs's smoltcp project.

Thanks also to the people behing tokio, especially @carllerche, for the amazing tool they are building, and the support they provide. The project structure and code quality are mind blowing, and some parts of this projects are basically rip-offs from tokio's source code

Finally, thanks to the Rust community, which helped me on multiple occasions

Other resources I particularly appreciated:

• https://www.linuxjournal.com/article/7356
• https://medium.com/@mdlayher/linux-netlink-and-go-part-1-netlink-4781aaeeaca8