An unprivileged async ICMP library. See the docs for how to use it.

Other related projects

These projects make different tradeoffs and API decisions, and while they didn't meet my needs, they may be of interest.

• surge-ping
• tokio-icmp-echo
• ping-async
• trippy

lib.rs:

An unprivileged async ICMP socket library.

This uses PROT_ICMP sockets, so root is not needed, though on Linux access to that socket type is limited by a sysctl (see Linux link below). Some distros set the sysctl to allow all users access out of the box, while others will need configuration.

See also:

• examples/ping.rs for a ping CLI tool showing how to use this library.
• Linux PROT_ICMP sockets: https://lwn.net/Articles/443051/
• macOS PROT_ICMP sockets: http://www.manpagez.com/man/4/icmp/
• ICMPv4: https://www.rfc-editor.org/rfc/rfc792
• ICMPv6: https://www.rfc-editor.org/rfc/rfc4443

Getting started

• Open an socket::IcmpSocket
• Create a suitable message::IcmpEchoRequest or other impl of message::EncodeIcmpMessage and send it with the socket
• Handle received ICMP messages, either as raw bytes or with message::decode::DecodedIcmpMsg

Examples

Sending a ping:

use std::net;
use async_icmp::{IpVersion, message::IcmpEchoRequest, socket::IcmpSocket};

async fn send_ping() {
    let socket = IcmpSocket::new(IpVersion::V4).unwrap();
    let mut echo = IcmpEchoRequest::new(100, 200, b"data");
    socket.send_to(net::Ipv4Addr::from([127, 0, 0, 1]).into(), &mut echo).await.unwrap();
}

Receving an ICMP message:

use async_icmp::{IpVersion,
    message::{decode::DecodedIcmpMsg, IcmpV4MsgType},
    socket::IcmpSocket};
use std::error;

async fn receive_and_decode() -> Result<(), Box<dyn error::Error>> {
    let s = IcmpSocket::new(IpVersion::V4)?;
    let mut buf = vec![0; 10_000];
    let (msg, _range) = s.recv(&mut buf).await?;
    let decoded = DecodedIcmpMsg::decode(msg)?;
    if decoded.msg_type() == IcmpV4MsgType::SourceQuench as u8 {
        // decode body as source quench
    }
    Ok(())
}