Crate async_icmp

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(())
}

Modules

• message
  ICMP message encoding and decoding.
• socket
  ICMP sockets.

Enums

• IpVersion
  The IP version used by a socket.