libpnet / netmap_sys

Rust bindings to netmap.

libpnet

Build Status:

Discussion and support:

• Live chat on IRC - #libpnet on irc.libera.chat
• GitHub Discussions

libpnet provides a cross-platform API for low level networking using Rust.

There are four key components:

• The packet module, allowing safe construction and manipulation of packets;
• The pnet_macros crate, providing infrastructure for the packet module;
• The transport module, which allows implementation of transport protocols;
• The datalink module, which allows sending and receiving data link packets directly.

Why?

There are lots of reasons to use low level networking, and many more to do it using Rust. A few are outlined here:

Developing Transport Protocols

There are usually two ways to go about developing a new transport layer protocol:

• Write it in a scripting language such as Python;
• Write it using C.

The former is great for trying out new ideas and rapid prototyping, however not so great as a real-world implementation. While you can usually get reasonable performance out of these implementations, they're generally significantly slower than an implementation in C, and not suitable for any "heavy lifting".

The next option is to write it in C - this will give you great performance, but comes with a number of other issues:

• Lack of memory safety - this is a huge source of security vulnerabilities and other bugs in C-based network stacks. It is far too easy to forget a bounds check or use a pointer after it is freed.
• Lack of thread safety - you have to be very careful to make sure the correct locks are used, and used correctly.
• Lack of high level abstractions - part of the appeal of scripting languages such as Python is the higher level of abstraction which enables simpler APIs and ease of programming.

Using libpnet and Rust, you get the best of both worlds. The higher level abstractions, memory and thread safety, alongside the performance of C.

Network Utilities

Many networking utilities such as ping and traceroute rely on being able to manipulate network and transport headers, which isn't possible with standard networking stacks such as those provided by std::io::net.

Data Link Layer

It can be useful to work directly at the data link layer, to see packets as they are "on the wire". There are lots of uses for this, including network diagnostics, packet capture and traffic shaping.

Documentation

API documentation for the latest build can be found here: https://docs.rs/pnet/

Usage

To use libpnet in your project, add the following to your Cargo.toml:

[dependencies.pnet]
version = "0.35.0"

libpnet should work with the latest stable version of Rust.

When running the test suite, there are a number of networking tests which will likely fail - the easiest way to workaround this is to run cargo test as a root or administrative user. This can often be avoided, however it is more involved.

Windows

There are three requirements for building on Windows:

• You must use a version of Rust which uses the MSVC toolchain
• You must have WinPcap or npcap installed (tested with version WinPcap 4.1.3) (If using npcap, make sure to install with the "Install Npcap in WinPcap API-compatible Mode")
• You must place Packet.lib from the WinPcap Developers pack in a directory named lib, in the root of this repository. Alternatively, you can use any of the locations listed in the %LIB%/$Env:LIB environment variables. For the 64 bit toolchain it is in WpdPack/Lib/x64/Packet.lib, for the 32 bit toolchain, it is in WpdPack/Lib/Packet.lib.

netmap_sys's Issues

NIOCGREGIF is invalid

The original NIOCGREGIF is defined in netmap_legacy.h as the following:

/*
 * FreeBSD uses the size value embedded in the _IOWR to determine
 * how much to copy in/out. So we need it to match the actual
 * data structure we pass. We put some spares in the structure
 * to ease compatibility with other versions
 */
#define NIOCGINFO	_IOWR('i', 145, struct nmreq) /* return IF info */
#define NIOCREGIF	_IOWR('i', 146, struct nmreq) /* interface register */
#define NIOCCONFIG	_IOWR('i',150, struct nm_ifreq) /* for ext. modules */

The Rust's NIOCREGIF is defined here:

#[cfg(target_os = "linux")]
pub const NIOCREGIF: c_ulong = 3225184658;
#[cfg(target_os = "freebsd")]
pub const NIOCREGIF: c_ulong = 3225184658;

They are different on Linux and libc::ioctl(fd, NIOCREGIF, &mut nmr as *mut nmreq) results in Operation bot supported. Valid NIOCREGIF for Linux is 3225446802, isn't it?

Include LICENSE in the crate

I'm packaging netmap_sys for Fedora. I found that the LICENSE was not included in the crate. It would be good to have the LICENSE in the crate, so that it would be distributed along with the RPM package.

build.rs not working

I'm trying to build this on my local Linux box, and the stuff in build.rs seems to be failing.

First, I think I needed to install clang, which wasn't super-obvious. But even with that done, I still hit this error:

[lars@tux: ~/rustcore] cargo build -v
   Compiling rust-netmap v0.0.4 (https://github.com/libpnet/rust-netmap.git#ab947ee2)
     Running `rustc /tmp/git/checkouts/rust-netmap-2baeba280d3ef56f/master/src/lib.rs --crate-name rust-netmap --crate-type rlib --crate-type dylib -C prefer-dynamic -g --cfg feature="default" --cfg feature="netmap_with_libs" -C metadata=10a85511dfe14665 -C extra-filename=-10a85511dfe14665 --out-dir /mnt/home/vmhome/rustcore/target/deps --emit=dep-info,link -L dependency=/mnt/home/vmhome/rustcore/target/deps -L dependency=/mnt/home/vmhome/rustcore/target/deps -Awarnings -L native=/mnt/home/vmhome/rustcore/target/build/rust-netmap-10a85511dfe14665/out -l static=rust_netmap_user`
error: could not find native static library `rust_netmap_user`, perhaps an -L flag is missing?
Could not compile `rust-netmap`.

Caused by:
  Process didn't exit successfully: `rustc /tmp/git/checkouts/rust-netmap-2baeba280d3ef56f/master/src/lib.rs --crate-name rust-netmap --crate-type rlib --crate-type dylib -C prefer-dynamic -g --cfg feature="default" --cfg feature="netmap_with_libs" -C metadata=10a85511dfe14665 -C extra-filename=-10a85511dfe14665 --out-dir /mnt/home/vmhome/rustcore/target/deps --emit=dep-info,link -L dependency=/mnt/home/vmhome/rustcore/target/deps -L dependency=/mnt/home/vmhome/rustcore/target/deps -Awarnings -L native=/mnt/home/vmhome/rustcore/target/build/rust-netmap-10a85511dfe14665/out -l static=rust_netmap_user` (exit code: 101)

Looking at build.rs, I noticed that /usr/include/net/netmap_user.h does not exist on my netmap-enabled system, but even after making this a symlink to my netmap_user.h, I see this failure.

error: unresolved name `netmap::nm_open`

OK, next issue. I may be too much of a rust newbie here; feel free to tell me.

My main.rs is simply:

extern crate "rust-netmap" as netmap;

fn main() {
    println!("Hello, world!");

    let n = netmap::nm_open("eth1", 0, 0, 0);
}

cargo build fails with

[lars@tux: ~/rustcore] cargo build -v
       Fresh rust-netmap v0.0.4 (https://github.com/libpnet/rust-netmap.git#ab947ee2)
   Compiling rustcore v0.0.1 (file:///mnt/home/vmhome/rustcore)
     Running `rustc src/main.rs --crate-name rustcore --crate-type bin -g --out-dir /mnt/home/vmhome/rustcore/target --emit=dep-info,link -L dependency=/mnt/home/vmhome/rustcore/target -L dependency=/mnt/home/vmhome/rustcore/target/deps --extern rust-netmap=/mnt/home/vmhome/rustcore/target/deps/librust-netmap-10a85511dfe14665.so --extern rust-netmap=/mnt/home/vmhome/rustcore/target/deps/librust-netmap-10a85511dfe14665.rlib -L native=/mnt/home/vmhome/rustcore/target/build/rust-netmap-10a85511dfe14665/out`
src/main.rs:6:10: 6:25 error: unresolved name `netmap::nm_open`
src/main.rs:6   let n = netmap::nm_open("eth1", 0, 0, 0);
                        ^~~~~~~~~~~~~~~
error: aborting due to previous error
Could not compile `rustcore`.

Caused by:
  Process didn't exit successfully: `rustc src/main.rs --crate-name rustcore --crate-type bin -g --out-dir /mnt/home/vmhome/rustcore/target --emit=dep-info,link -L dependency=/mnt/home/vmhome/rustcore/target -L dependency=/mnt/home/vmhome/rustcore/target/deps --extern rust-netmap=/mnt/home/vmhome/rustcore/target/deps/librust-netmap-10a85511dfe14665.so --extern rust-netmap=/mnt/home/vmhome/rustcore/target/deps/librust-netmap-10a85511dfe14665.rlib -L native=/mnt/home/vmhome/rustcore/target/build/rust-netmap-10a85511dfe14665/out` (exit code: 101)

I do have features = ["netmap_with_libs"] in my Cargo.toml, per your README. What am I missing?

nm_desc struct definition is incompatible with netmap >= v1.14 due to change in memsize

in this commit luigirizzo/netmap@142ebbf

the nm_desc struct changed. such that nm_desc.memsize is now a uint64

consequently, anyone using a netmap_user.h after that will get some funky errors when using this library.

Do a new release?

There are useful things like 9d719c9 in master but not released.

Release, please!

It would be great if you published current version on crates.io as it would make compiling libpnet with netmap feature enabled possible on more systems (like mine).