[−][src]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.netfilter
- Netfilter related protocols (NFLOG, NFQUEUE, CONNTRACK).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 |
genl | Genetlink (generic netlink) header and attribute helpers
This module contains generic netlink parsing data structures. This is all handled by
the |
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 |
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 |
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_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 |
NlBuf | Deserialize trait that allows a buffer to be passed in so that references with appropriate lifetimes can be returned |