Crate neli[−][src]
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:
attr
- This defines a generic interface for netlink attributes (both generic and routing netlink attributes).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.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.
Nl
trait
lib.rs
at the top level contains the Nl
trait which
provides buffer size calculation functions, a serialization
method, and a deserialization method. It also contains
implementations of Nl
for common types.
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
and
NlSocketHandle
structs
to provide most of the convenience functions. I hope to add a
higher level API sometime in the v0.5.x
releases 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.
Workflows seem to usually follow a pattern of socket creation,and then either sending and receiving messages in request/response formats:
use neli::{ consts::{genl::*, nl::*, socket::*}, err::NlError, genl::{Genlmsghdr, Nlattr}, nl::{Nlmsghdr, NlPayload}, socket::NlSocketHandle, types::{Buffer, GenlBuffer}, }; const GENL_VERSION: u8 = 1; fn request_response() -> Result<(), NlError> { let mut socket = NlSocketHandle::connect( NlFamily::Generic, None, &[], )?; let attrs: GenlBuffer<Index, Buffer> = GenlBuffer::new(); let genlhdr = Genlmsghdr::new( CtrlCmd::Getfamily, GENL_VERSION, attrs, ); let nlhdr = { let len = None; let nl_type = GenlId::Ctrl; let flags = NlmFFlags::new(&[NlmF::Request, NlmF::Dump]); let seq = None; let pid = None; let payload = NlPayload::Payload(genlhdr); Nlmsghdr::new(len, nl_type, flags, seq, pid, payload) }; socket.send(nlhdr)?; // Do things with multi-message response to request... let mut iter = socket.iter::<Genlmsghdr<CtrlCmd, CtrlAttr>>(false); while let Some(Ok(response)) = iter.next() { // Do things with response here... } // Or get single message back... let msg = socket.recv::<Nlmsg, Genlmsghdr<CtrlCmd, CtrlAttr>>()?; Ok(()) }
or a subscriptions to a stream of event notifications from netlink:
use std::error::Error; use neli::{ consts::{genl::*, socket::*}, err::NlError, genl::Genlmsghdr, socket, }; fn subscribe_to_mcast() -> Result<(), Box<dyn Error>> { let mut s = socket::NlSocketHandle::connect( NlFamily::Generic, None, &[], )?; let id = s.resolve_nl_mcast_group( "my_family_name", "my_multicast_group_name", )?; s.add_mcast_membership(&[id])?; for next in s.iter::<Genlmsghdr<u8, u16>>(true) { // Do stuff here with parsed packets... // like printing a debug representation of them: println!("{:?}", next?); } Ok(()) }
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
attr | Shared attribute code for all types of netlink attributes. |
consts | High level notes |
err | This is the module that contains the error types used in |
genl | This module contains generic netlink parsing data structures.
This is all handled by the |
iter | Module for iteration over netlink responses |
nl | This module contains the top level netlink header code. Every
netlink message will be encapsulated in a top level |
rtnl | This module provides an implementation of routing netlink structures and the routing attributes that are at the end of most routing netlink responses. |
socket | This module provides code that glues all of the other modules together and allows message send and receive operations. |
types | Module containing various types used across the various netlink
structures used in |
utils | A module containing utilities for working with constructs like bitflags and other low level operations. |
Macros
deserialize | This macro can be used to declaratively define deserialization for a struct. |
deserialize_type_size | This macro calculates size from
|
drive_deserialize | This macro can be used to deserialize a single field in a struct. |
drive_serialize | This macro can be used to serialize a single field in a struct. |
impl_flags | Implement a container for bit flag enums where the set of flags will be condensed into a single value. |
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 parameter can be constrained by a trait bound to only accept enums that implement the marker trait. |
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. |
log | Logging mechanism for neli for debugging |
serialize | This macro can be used to declaratively define serialization for a struct. |
Structs
BeU64 | A |
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 |