Crate getifs

GetIfs

A bunch of cross-platform network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc.

Introduction

A bunch of cross-platform network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc.

Installation

[dependencies]
getifs = "0.3"

Examples

• Fetching all interfaces: examples/interfaces.rs
• Fetching all interface addresses (excluding multicast addrs): examples/addrs.rs
• Fetching all interface multicast addresses: exampels/multicast_addrs.rs
• Fetching gateway addresses: examples/gateway.rs
• Fetching local ip addresses: examples/local_ip_addrs.rs
• Fetching ip addresses by RFC: examples/filter_by_rfc.rs

Details

OS	Approach
Linux (no libc)	socket(AF_NETLINK, SOCK_RAW | SOCK_CLOEXEC, NETLINK_ROUTE)
BSD-like	sysctl
Windows	GetAdaptersAddresses

Why a new network interfaces crate?

When implementing agnostic-mdns (an mDNS crate), I found that Rust was missing a crate to help play with network interfaces and addresses.

All of current network interfaces crates do not support fetching MTU and multicast addresses, and almost all of them are using libc::getifaddrs. This crate tries to avoid unneeded allocation and use more underlying method to achieve the same functionalities.

Hence, getifs is here, which contain a bunch of cross-platform network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc.

Roadmap

• Support fetching routing tables (0.4.0)

Benchmarks

Ubuntu 22.04 ARM64 (Parallel Desktop, 1 CPU, 8GB memory)

MacOS (Apple M1 Max, 32GB)

Sister crates

• iprobe: Probe if the host system supports IPv4, IPv6 and IPv4-mapped-IPv6.
• iprfc: Known RFCs for IP addresses.

Pedigree

• The code in this crate is inspired by Golang’s interface.go and HashiCorp’s go-sockaddr.

License

getifs is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2025 Al Liu.

Re-exports

pub use ipnet;

Modules

probe

IP protocol probing

rfc

Known RFCs for IP addresses

Structs

Flags

Flags represents the interface flags.

Ifv4Addr

An interface IPv4 address.

Ifv4Net

An interface IPv4 network.

Ifv6Addr

An interface IPv6 address.

Ifv6Net

An interface IPv6 network.

Interface

The inferface struct

MacAddr

Represents a physical hardware address (MAC address).

SmolStr

A SmolStr is a string type that has the following properties:

Enums

IfAddr

An interface address.

IfNet

An interface network.

Functions

best_local_addrs

Returns both IPv4 and IPv6 addresses from the interfaces with the best default routes. The “best” interfaces are determined by the routing metrics of default routes.

best_local_ipv4_addrs

Returns the IPv4 addresses from the interface with the best default route. The “best” interface is determined by the routing metrics of default routes (0.0.0.0).

best_local_ipv6_addrs

Returns the IPv6 addresses from the interface with the best default route. The “best” interface is determined by the routing metrics of default routes (::).

gateway_addrs

Returns all gateway IP addresses (both IPv4 and IPv6) configured on the system. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

gateway_addrs_by_filter

Returns all gateway IP addresses (both IPv4 and IPv6) configured on the system that match the given filter. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

gateway_ipv4_addrs

Returns all IPv4 gateway addresses configured on the system. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

gateway_ipv4_addrs_by_filter

Returns all IPv4 gateway addresses configured on the system that match the given filter. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

gateway_ipv6_addrs

Returns all IPv6 gateway addresses configured on the system. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

gateway_ipv6_addrs_by_filter

Returns all IPv6 gateway addresses configured on the system that match the given filter. Only returns addresses from interfaces that have valid routes and excludes any addresses that are not configured as gateways.

get_ip_mtu

Get the MTU of the given IpAddr.

get_ipv4_mtu

Get the MTU of the given Ipv4Addr.

get_ipv6_mtu

Get the MTU of the given Ipv6Addr.

ifindex_to_name

Returns the name of the interface by the given index.

ifname_to_iface

Returns the IPv6 interface of by the given name.

ifname_to_index

Returns the index of the interface by the given name.

ifname_to_v4_iface

Returns the IPv4 interface of by the given name.

ifname_to_v6_iface

Returns the IPv6 interface of by the given name.

interface_addrs

Returns a list of the system’s unicast interface addrs.

interface_addrs_by_filter

Returns a list of the system’s unicast interface addrs.

interface_by_index

Returns the interface specified by index.

interface_by_name

Returns the interface specified by name.

interface_ipv4_addrs

Returns a list of the system’s unicast, IPv4 interface addrs.

interface_ipv4_addrs_by_filter

Returns a list of the system’s unicast, IPv4 interface addrs.

interface_ipv6_addrs

Returns a list of the system’s unicast, IPv6 interface addrs.

interface_ipv6_addrs_by_filter

Returns a list of the system’s unicast, IPv6 interface addrs.

interface_multicast_addrsApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast interface addrs.

interface_multicast_addrs_by_filterApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast interface addrs. The filter is used to determine which multicast addresses to include.

interface_multicast_ipv4_addrsApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast, IPv4 interface addrs.

interface_multicast_ipv4_addrs_by_filterApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast, IPv4 interface addrs. The filter is used to determine which multicast addresses to include.

interface_multicast_ipv6_addrsApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast, IPv6 interface addrs.

interface_multicast_ipv6_addrs_by_filterApple or FreeBSD or Linux or Windows

Returns a list of the system’s multicast, IPv6 interface addrs. The filter is used to determine which multicast addresses to include.

interfaces

Returns a list of the system’s network interfaces.

local_addrs

Returns all IP addresses (both IPv4 and IPv6) from interfaces that have valid routes (excluding loopback). This ensures we only return addresses that can be used for communication.

local_addrs_by_filter

Returns all IP addresses (both IPv4 and IPv6) from interfaces that have valid routes.

local_ipv4_addrs

Returns all IPv4 addresses from interfaces that have valid routes (excluding loopback). This ensures we only return addresses that can be used for communication.

local_ipv4_addrs_by_filter

Returns all IPv4 addresses from interfaces that have valid routes.

local_ipv6_addrs

Returns all IPv6 addresses from interfaces that have valid routes (excluding loopback). This ensures we only return addresses that can be used for communication.

local_ipv6_addrs_by_filter

Returns all IPv6 addresses from interfaces that have valid routes.

private_addrs

Returns all IP addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_addrs).

private_addrs_by_filter

Returns all IP addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_addrs_by_filter).

private_ipv4_addrs

Returns all IPv4 addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_ipv4_addrs).

private_ipv4_addrs_by_filter

Returns all IPv4 addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_ipv4_addrs_by_filter).

private_ipv6_addrs

Returns all IPv6 addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_ipv6_addrs).

private_ipv6_addrs_by_filter

Returns all IPv6 addresses that are part of RFC 6890 (regardless of whether or not there is a default route, unlike public_ipv6_addrs_by_filter).

public_addrs

Returns all IP addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_addrs).

public_addrs_by_filter

Returns all IP addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_addrs_by_filter).

public_ipv4_addrs

Returns all IPv4 addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_ipv4_addrs).

public_ipv4_addrs_by_filter

Returns all IP addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_ipv4_addrs_by_filter).

public_ipv6_addrs

Returns all IPv6 addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_ipv6_addrs).

public_ipv6_addrs_by_filter

Returns all IPv6 addresses that are NOT part of RFC 6890 (regardless of whether or not there is a default route, unlike private_ipv6_addrs_by_filter).

Type Aliases

ParseMacAddrError

Represents an error that occurred while parsing MacAddr.