Crate neli

Type safety for the weary netlink user

Rationale

This crate aims to be a pure Rust implementation that defines the necessary constants and wraps them in enums to distinguish between various categories of constants in the context of netlink.

The project is broken down into the following modules:

• consts - This is where all of the C-defined constants are wrapped into type safe enums for use in the library.
• err - This module contains all of the protocol and library-level errors encountered in the code.
• genl - This code provides parsing for the generic netlink subsystem of the netlink protocol.
• nlattr - This code provides more granular parsing methods for the generic netlink attributes in the context of generic netlink requests and responses.
• nl - This is the top level netlink header code that handles the header that all netlink messages are encapsulated in.
• rtnl - This module is for the routing netlink subsystem of the netlink protocol.
• socket - This provides a socket structure for use in sending and receiving messages and a number of convenience functions for commonly encountered use cases.

Traits

The library at the top level contains the Nl trait which provides a buffer size calculation function, a serialization method, and a deserialization method. It also contains implementations of Nl for common types. The is one additional trait, NlBuf, used in cases where, to deserialize a type, a buffer needs to be provided by the caller function and passed to the callee.

Design decisions

This is a fairly low level library that currently does not have a whole lot of higher level handle-type data structures and relies mostly on the NlSocket struct to provide most of the convenience functions. I hope to add a higher level API by v0.5.0 to ease some of the workflows that have been brought to my attention.

The goal of this library is completeness for handling netlink and am working to incorporate features that will make this library easier to use in all use cases. If you have a use case you would like to see supported, please open an issue on github.

Examples

Examples of working code exist in the examples/ subdirectory on Github. They have a separate Cargo.toml file to provide easy testing and use.

Documentation

Each module has been documented extensively to provide information on how to use the code contained in the module. Pull requests for documentation mistakes, updates, and rewording for clarity is a valuable contribution as this project aims to be as simple to use as possible.

Modules

consts	C constants defined as types
err	Error module This is the module that contains the error types used in neli
genl	Genetlink (generic netlink) header and attribute helpers This module contains generic netlink parsing data structures. This is all handled by the Genlmsghdr header struct which contains all of the information needed for the generic netlink layer.
nl	Top-level netlink header This module contains the top level netlink header code and attribute parsing. Every netlink message will be encapsulated in a top level Nlmsghdr.
nlattr	Netlink attribute handler This module aims to provide simple parsing for generic netlink attributes, including parsing for nested attributes.
rtnl	Route netlink bindings This module provides an implementation of routing netlink structures and the routing attributes that are at the end of most routing netlink responses.
socket	Wrapper for libc sockets This module provides code that glues all of the other modules together and allows message send and receive operations. This module relies heavily on the buffering crate. See buffering for more information on the serialization and deserialization implementations.

Macros

impl_trait	For generating a marker trait that flags a new enum as usable in a field that accepts a generic type. This way, the type can be constrained when the impl is provided to only accept enums that implement the marker trait that corresponds to the given marker trait. The current convention is to use impl_trait to create the trait with the name of the field that is the generic type and then use impl_var_trait to flag the new enum as usable in this field. See the examples below for more details.
impl_var	For naming a new enum, passing in what type it serializes to and deserializes from, and providing a mapping from variants to expressions (such as libc consts) that will ultimately be used in the serialization/deserialization step when sending the netlink message over the wire.
impl_var_trait	For defining a new enum implementing the provided marker trait. It accepts a name for the enum and the target type for serialization and deserialization conversions, as well as value conversions for serialization and deserialization.

Structs

StreamReadBuffer	A stream reader that will allow piece-by-piece reading of a buffer
StreamWriteBuffer	A stream writer that will allow piece-by-piece writing of to a buffer

Constants

MAX_NL_LENGTH

Max supported message length for netlink messages supported by the kernel

Traits

Nl	Trait defining basic actions required for netlink communication. Implementations for basic and neli's types are provided (see below). Create new implementations if you have to work with a Netlink API that uses values of more unusual types.
NlBuf	Deserialize trait that allows a buffer to be passed in so that references with appropriate lifetimes can be returned