search

ValentinBELYN / icmplib

Easily forge ICMP packets and make your own ping and traceroute.
GNU Lesser General Public License v3.0
276 stars 45 forks source link
async asyncio icmp ipv4 ipv6 multiping ping python python3 sockets traceroute

readme



icmplib

Features    Installation    Getting started    Documentation    Contributing    Donate    License 

icmplib is a brand new and modern implementation of the ICMP protocol in Python.
Use the built-in functions or build your own, you have the choice!

icmplib 3.0 has been released! See what's new 🎉
statistics


Features


Installation


Getting started

ping

Send ICMP Echo Request packets to a network host.

ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)

Parameters

Return value

Exceptions

Example

>>> from icmplib import ping

>>> host = ping('1.1.1.1', count=10, interval=0.2)

>>> host.address              # The IP address of the host that responded
'1.1.1.1'                     # to the request

>>> host.min_rtt              # The minimum round-trip time in milliseconds
5.761

>>> host.avg_rtt              # The average round-trip time in milliseconds
12.036

>>> host.max_rtt              # The maximum round-trip time in milliseconds
16.207

>>> host.rtts                 # The list of round-trip times expressed in
[ 11.595, 13.135, 9.614,      # milliseconds
  16.018, 11.960, 5.761,      # The results are not rounded unlike other
  16.207, 11.937, 12.098 ]    # properties

>>> host.packets_sent         # The number of requests transmitted to the
10                            # remote host

>>> host.packets_received     # The number of ICMP responses received from
9                             # the remote host

>>> host.packet_loss          # Packet loss occurs when packets fail to
0.1                           # reach their destination. Returns a float
                              # between 0 and 1 (all packets are lost)

>>> host.jitter               # The jitter in milliseconds, defined as the
4.575                         # variance of the latency of packets flowing
                              # through the network

>>> host.is_alive             # Indicates whether the host is reachable
True


multiping

Send ICMP Echo Request packets to several network hosts.

multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)

Parameters

Return value

Exceptions

Example

>>> from icmplib import multiping

>>> hosts = multiping(['10.0.0.5', '127.0.0.1', '::1'])

>>> for host in hosts:
...     if host.is_alive:
...         # See the Host class for details
...         print(f'{host.address} is up!')
...     else:
...         print(f'{host.address} is down!')

# 10.0.0.5 is down!
# 127.0.0.1 is up!
# ::1 is up!


traceroute

Determine the route to a destination host.

The Internet is a large and complex aggregation of network hardware, connected together by gateways. Tracking the route one's packets follow can be difficult. This function uses the IP protocol time to live field and attempts to elicit an ICMP Time Exceeded response from each gateway along the path to some host.

This function requires root privileges to run.

traceroute(address, count=2, interval=0.05, timeout=2, first_hop=1, max_hops=30, fast=False, id=None, source=None, family=None, **kwargs)

Parameters

Return value

Exceptions

Example

>>> from icmplib import traceroute

>>> hops = traceroute('1.1.1.1')

>>> print('Distance/TTL    Address    Average round-trip time')
>>> last_distance = 0

>>> for hop in hops:
...     if last_distance + 1 != hop.distance:
...         print('Some gateways are not responding')
...
...     # See the Hop class for details
...     print(f'{hop.distance}    {hop.address}    {hop.avg_rtt} ms')
...
...     last_distance = hop.distance

# Distance/TTL    Address                 Average round-trip time
# 1               10.0.0.1                5.196 ms
# 2               194.149.169.49          7.552 ms
# 3               194.149.166.54          12.21 ms
# *               Some gateways are not responding
# 5               212.73.205.22           22.15 ms
# 6               1.1.1.1                 13.59 ms


async_ping

Send ICMP Echo Request packets to a network host.

This function is non-blocking.

async_ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs)

Parameters, return value and exceptions

The same parameters, return value and exceptions as for the ping function.

Example

>>> import asyncio
>>> from icmplib import async_ping

>>> async def is_alive(address):
...     host = await async_ping(address, count=10, interval=0.2)
...     return host.is_alive

>>> asyncio.run(is_alive('1.1.1.1'))
True


async_multiping

Send ICMP Echo Request packets to several network hosts.

This function is non-blocking.

async_multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs)

Parameters, return value and exceptions

The same parameters, return values and exceptions as for the multiping function.

Example

>>> import asyncio
>>> from icmplib import async_multiping

>>> async def are_alive(*addresses):
...     hosts = await async_multiping(addresses)
...     
...     for host in hosts:
...         if not host.is_alive:
...             return False
...
...     return True

>>> asyncio.run(are_alive('10.0.0.5', '127.0.0.1', '::1'))
False


Documentation

This page only gives an overview of the features of icmplib.

To learn more about the built-in functions, on how to create your own and handle exceptions, you can click on the following link:

Contributing

Comments and enhancements are welcome.

All development is done on GitHub. Use Issues to report problems and submit feature requests. Please include a minimal example that reproduces the bug.

Donate

icmplib is completely free and open source. It has been fully developed on my free time. If you enjoy it, please consider donating to support the development.

License

Copyright 2017-2023 Valentin BELYN.

Code released under the GNU LGPLv3 license. See the LICENSE for details.