pax_global_header00006660000000000000000000000064141777756750014544gustar00rootroot0000000000000052 comment=95994f6b4c4a00010cb96854b28bc097370c4070 icmplib-3.0.3/000077500000000000000000000000001417777567500131665ustar00rootroot00000000000000icmplib-3.0.3/CHANGELOG.md000066400000000000000000000171461417777567500150100ustar00rootroot00000000000000# Changelog All notable changes to this project will be documented in this file. ## [v3.0.3](https://github.com/ValentinBELYN/icmplib/releases/tag/v3.0.3) - 2022-02-06 - Add the `sock` property to the `ICMPSocket` class. ## [v3.0.2](https://github.com/ValentinBELYN/icmplib/releases/tag/v3.0.2) - 2021-10-31 - Add support for IPv6 addresses with zone index. - The `payload` property of an `ICMPRequest` now returns a random value if the payload is not defined instead of `None`. - Optimize imports. ## [v3.0.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v3.0.1) - 2021-08-14 - Make the `SocketPermissionError` more explicit when the OS does not allow instantiation of unprivileged sockets. - Delete unnecessary properties from exceptions. - Improve SEO on GitHub. ## [v3.0.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v3.0.0) - 2021-06-01 **icmplib 3.0 is here! :rocket:** - The library is now asynchronous! - Introduce new functions: `async_ping`, `async_multiping` and `async_resolve`. - Add a new `AsyncSocket` class to make an ICMP socket asynchronous. - Rewrite models: - All the properties of `Host` and `Hop` classes are now lazy. - Add new properties to the `Host` and `Hop` classes: you can retrieve the list of round-trip times and calculate the jitter. - Add the metaclass `__str__` to visualize the results more easily. - Rewrite the `ping`, `multiping` and `traceroute` functions: - The identifier of ICMP requests is now handled automatically by the library. - Add the ability to set the address family if a hostname or an FQDN is specified. - A new implementation is used for the `multiping` function. It should be more reliable. - The `multiping` function is now in a dedicated module. - Rewrite the documentation to help you get started with icmplib. - Improve the `resolve` function to return all IP addresses found. - Add the `is_hostname` function to check if a string is a hostname or an FQDN. - Delete the experimental class `BufferedSocket`, replaced by `AsyncSocket`. - Performance and compatibility improvement. - Many other small changes and fixes. Special thanks to [@JonasKs](https://github.com/JonasKs) and [@bdraco](https://github.com/bdraco) for their suggestions, advice and feedback! > Python 3.7 or later is now required. ## [v2.1.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v2.1.1) - 2021-03-21 - :bug: Revert changes made to the `traceroute` function due to a bug. > This version is the last of the 2.x branch. See you soon for the release of icmplib 3.0! ## [v2.1.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v2.1.0) - 2021-03-20 - Add a `family` parameter to the `resolve` function to define the address family. - Improve the reliability of the results of the `traceroute` function. ## [v2.0.2](https://github.com/ValentinBELYN/icmplib/releases/tag/v2.0.2) - 2021-02-07 - Rename the default branch from `master` to `main`. - Add more details about the `privileged` parameter in the `README` file (part 2). - :bug: Fix a bug preventing the `traceroute` function to work with IPv6 addresses (part 2). ## [v2.0.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v2.0.1) - 2020-12-12 - Handle `EACCES` errors at sockets level. - Add some details about the `privileged` parameter in the `README` file. - :bug: Fix a bug preventing the `traceroute` function to work with IPv6 addresses. ## [v2.0.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v2.0.0) - 2020-11-15 **icmplib 2.0 is here! :rocket:** - New library architecture. - Add a new `multiping` function. This function will be faster and more memory efficient. - Add the ability to use the library without root privileges. - Add the ability to set a source IP address for sending your ICMP packets. - Add a `first_hop` parameter to the `traceroute` function to set the initial time to live value ([@scoulondre](https://github.com/scoulondre)). - Add two new exceptions: - `NameLookupError`: raised when the requested name does not exist or cannot be resolved. - `SocketAddressError`: raised when the requested address cannot be assigned to the socket. - Add a new `BufferedSocket` class (experimental) to send several packets simultaneously without waiting for a response. - The `receive` method of sockets can receive all incoming packets. - Throw new exceptions when instantiating sockets, sending and receiving packets. - Improve the `resolve` function: - A `NameLookupError` is now raised if the requested name does not exist or cannot be resolved. - Improve compatibility with Linux, macOS and Windows. - Delete deprecated properties. - Update docstrings, examples and documentation. > Compatibility with existing programs is maintained. ## [v1.2.2](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.2.2) - 2020-10-10 - Add support for hostnames and FQDN resolution to IPv6 addresses. - Performance improvement. ## [v1.2.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.2.1) - 2020-09-26 - :bug: Fix an issue in the `traceroute` function which gave the wrong value for the `avg_rtt` property ([@patrickfnielsen](https://github.com/patrickfnielsen)). ## [v1.2.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.2.0) - 2020-09-12 - Add the ability to modify the traffic class of ICMP packets. - Add new optional parameters to the `traceroute` function. - Add a new exception `SocketUnavailableError` when an action is performed while a socket is closed. - Add a warning message on deprecated properties. - Explicit closure of sockets on built-in functions. - :bug: Fix a bug when ICMP responses are not correctly formatted (part 2). ## [v1.1.3](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.1.3) - 2020-09-03 - :bug: Fix a bug when ICMP responses are not correctly formatted. ## [v1.1.2](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.1.2) - 2020-08-29 - :bug: Fix a compatibility issue. ## [v1.1.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.1.1) - 2020-07-10 - :bug: Fix a bug when the source host does not have an IP address. ## [v1.1.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.1.0) - 2020-06-25 - Add support for odd size payloads. - Normalize the names of variables and properties: - `ICMPReply` class: the `received_bytes` property is deprecated. Use `bytes_received` instead. - `Host` and `Hop` classes: the `transmitted_packets` property is deprecated. Use `packets_sent` instead. - `Host` and `Hop` classes: the `received_packets` property is deprecated. Use `packets_received` instead. - Normalize docstrings. - Optimizations. ## [v1.0.4](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.0.4) - 2020-06-14 - Add the `is_closed` property to the `ICMPSocket` class. - Round round-trip time values by default. - Add an index for examples. - :bug: Fix a bug in the `multiping` function where the `id` parameter was ignored. - :bug: Fix a bug in the `ICMPSocket` class when instantiated without root privileges. ## [v1.0.3](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.0.3) - 2020-05-09 - Add the ability to customize the payload. - Improve the `ping` and `multiping` functions: - You can pass arguments to the `ICMPRequest` object using keywords arguments `**kwargs`. - Update some docstrings. - Add new examples. ## [v1.0.2](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.0.2) - 2019-10-20 - Change the license. This project now uses the more permissive license LGPLv3. ## [v1.0.1](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.0.1) - 2019-10-07 - Add some examples. - Rename `model.py` to `models.py`. - Update setup keywords. ## [v1.0.0](https://github.com/ValentinBELYN/icmplib/releases/tag/v1.0.0) - 2019-09-29 - :tada: Initial release. icmplib-3.0.3/LICENSE000066400000000000000000000167441417777567500142070ustar00rootroot00000000000000 GNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. 0. Additional Definitions. As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. "The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. 1. Exception to Section 3 of the GNU GPL. You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. 2. Conveying Modified Versions. If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. 3. Object Code Incorporating Material from Library Header Files. The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the object code with a copy of the GNU GPL and this license document. 4. Combined Works. You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the Combined Work with a copy of the GNU GPL and this license document. c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. d) Do one of the following: 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) 5. Combined Libraries. You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 6. Revised Versions of the GNU Lesser General Public License. The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library. icmplib-3.0.3/README.md000066400000000000000000000454621417777567500144600ustar00rootroot00000000000000


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 - :deciduous_tree: **Ready-to-use:** icmplib offers ready-to-use functions such as the most popular ones: `ping`, `multiping` and `traceroute`. An extensive documentation also helps you get started. - :gem: **Modern:** This library uses the latest mechanisms offered by Python 3.6/3.7+ and is fully object-oriented. - :rocket: **Fast:** Each class and function has been designed and optimized to deliver the best performance. Some functions are also asynchronous like the `async_ping` and `async_multiping` functions. You can ping the world in seconds! - :zap: **Powerful:** Use the library without root privileges, set the traffic class of ICMP packets, customize their payload, send broadcast requests and more! - :nut_and_bolt: **Evolutive:** Easily build your own classes and functions with `ICMPv4` and `ICMPv6` sockets. - :fire: **Seamless integration of IPv6:** Use IPv6 the same way you use IPv4. - :beer: **Cross-platform:** Optimized for Linux, macOS and Windows. The library automatically manages the specificities of each system. - :metal: **No dependency:** icmplib is a pure Python implementation of the ICMP protocol. It does not rely on any external dependency.
## Installation - **Install icmplib** The recommended way to install icmplib is to use `pip3`: ```shell $ pip3 install icmplib ``` *Since icmplib 3, Python 3.7 or later is required to use the library.*
*If you are using Python 3.6 and you cannot update it, you can still install icmplib 2.* - **Import basic functions** ```python from icmplib import ping, multiping, traceroute, resolve ``` - **Import asynchronous functions** ```python from icmplib import async_ping, async_multiping, async_resolve ``` - **Import sockets (advanced)** ```python from icmplib import ICMPv4Socket, ICMPv6Socket, AsyncSocket, ICMPRequest, ICMPReply ``` - **Import exceptions** ```python from icmplib import ICMPLibError, NameLookupError, ICMPSocketError from icmplib import SocketAddressError, SocketPermissionError from icmplib import SocketUnavailableError, SocketBroadcastError, TimeoutExceeded from icmplib import ICMPError, DestinationUnreachable, TimeExceeded ``` *Import only what you need.*
## Getting started ### ping Send ICMP Echo Request packets to a network host. ```python ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs) ``` #### Parameters - `address` The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address. - Type: `str` - `count` The number of ping to perform. - Type: `int` - Default: `4` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `1` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `id` The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default. - Type: `int` - Default: `None` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `privileged` When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. [Learn more about the `privileged` parameter.] *Only available on Unix systems. Ignored on Windows.* - Type: `bool` - Default: `True` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A `Host` object containing statistics about the desired destination:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive` #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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. ```python multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs) ``` #### Parameters - `addresses` The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in [`resolve`] function. - Type: `list[str]` - `count` The number of ping to perform per address. - Type: `int` - Default: `2` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `0.5` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `concurrent_tasks` The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system. - Type: `int` - Default: `50` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `privileged` When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. [Learn more about the `privileged` parameter.] *Only available on Unix systems. Ignored on Windows.* - Type: `bool` - Default: `True` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A list of `Host` objects containing statistics about the desired destinations:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive` The list is sorted in the same order as the addresses passed in parameters. #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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.* ```python 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 - `address` The IP address, hostname or FQDN of the host to reach. For deterministic behavior, prefer to use an IP address. - Type: `str` - `count` The number of ping to perform per hop. - Type: `int` - Default: `2` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `0.05` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `first_hop` The initial time to live value used in outgoing probe packets. - Type: `int` - Default: `1` - `max_hops` The maximum time to live (max number of hops) used in outgoing probe packets. - Type: `int` - Default: `30` - `fast` When this option is enabled and an intermediate router has been reached, skip to the next hop rather than perform additional requests. The `count` parameter then becomes the maximum number of requests in the event of no response. - Type: `bool` - Default: `False` - `id` The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every traceroute process. The library handles this identifier itself by default. - Type: `int` - Default: `None` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A list of `Hop` objects representing the route to the desired destination. A `Hop` has the same properties as a `Host` object but it also has a `distance`:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`, `distance` The list is sorted in ascending order according to the distance, in terms of hops, that separates the remote host from the current machine. Gateways that do not respond to requests are not added to this list. #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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.* ```python 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 ```python >>> 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.* ```python 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 ```python >>> 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: - :rocket: [Documentation] ## 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. - :tada: [Donate via PayPal] ## License Copyright 2017-2022 Valentin BELYN. Code released under the GNU LGPLv3 license. See the [LICENSE] for details. [Learn more about the `privileged` parameter.]: docs/6-use-icmplib-without-privileges.md [Documentation]: docs [GitHub]: https://github.com/ValentinBELYN/icmplib [Issues]: https://github.com/ValentinBELYN/icmplib/issues [Donate via PayPal]: https://paypal.me/ValentinBELYN [LICENSE]: LICENSE [`ping`]: #ping [`multiping`]: #multiping [`ICMPv4Socket`]: docs/3-sockets.md#ICMPv4Socket [`ICMPv6Socket`]: docs/3-sockets.md#ICMPv6Socket [`NameLookupError`]: docs/4-exceptions.md#NameLookupError [`ICMPSocketError`]: docs/4-exceptions.md#ICMPSocketError [`SocketAddressError`]: docs/4-exceptions.md#SocketAddressError [`SocketPermissionError`]: docs/4-exceptions.md#SocketPermissionError [`resolve`]: docs/5-utilities.md#resolve icmplib-3.0.3/docs/000077500000000000000000000000001417777567500141165ustar00rootroot00000000000000icmplib-3.0.3/docs/1-installation.md000066400000000000000000000026161417777567500173040ustar00rootroot00000000000000# Installation ## Requirements - Since icmplib 3, Python 3.7 or later is required to use the library. - If you are using Python 3.6 and you cannot update it, you can still install icmplib 2. - icmplib has been optimized to run on the most popular operating systems such as Linux, macOS and Windows. ## Installation and update - **Install** The recommended way to install icmplib is to use `pip3`: ```shell $ pip3 install icmplib ``` - **Update** Before updating icmplib, take care to read the release notes carefully to avoid any incompatibilities with your applications. ```shell $ pip3 install --upgrade icmplib ``` ## Imports Add the following instructions into your project to import icmplib (only import what you need): - **Basic functions** ```python from icmplib import ping, multiping, traceroute, resolve ``` - **Asynchronous functions** ```python from icmplib import async_ping, async_multiping, async_resolve ``` - **Sockets (advanced)** ```python from icmplib import ICMPv4Socket, ICMPv6Socket, AsyncSocket, ICMPRequest, ICMPReply ``` - **Exceptions** ```python from icmplib import ICMPLibError, NameLookupError, ICMPSocketError from icmplib import SocketAddressError, SocketPermissionError from icmplib import SocketUnavailableError, SocketBroadcastError, TimeoutExceeded from icmplib import ICMPError, DestinationUnreachable, TimeExceeded ``` icmplib-3.0.3/docs/2-functions.md000066400000000000000000000352211417777567500166120ustar00rootroot00000000000000# Built-in functions ### ping Send ICMP Echo Request packets to a network host. ```python ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs) ``` #### Parameters - `address` The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address. - Type: `str` - `count` The number of ping to perform. - Type: `int` - Default: `4` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `1` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `id` The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default. - Type: `int` - Default: `None` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `privileged` When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. [Learn more about the `privileged` parameter.] *Only available on Unix systems. Ignored on Windows.* - Type: `bool` - Default: `True` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A `Host` object containing statistics about the desired destination:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive` #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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. ```python multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs) ``` #### Parameters - `addresses` The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in [`resolve`] function. - Type: `list[str]` - `count` The number of ping to perform per address. - Type: `int` - Default: `2` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `0.5` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `concurrent_tasks` The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system. - Type: `int` - Default: `50` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `privileged` When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. [Learn more about the `privileged` parameter.] *Only available on Unix systems. Ignored on Windows.* - Type: `bool` - Default: `True` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A list of `Host` objects containing statistics about the desired destinations:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive` The list is sorted in the same order as the addresses passed in parameters. #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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.* ```python 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 - `address` The IP address, hostname or FQDN of the host to reach. For deterministic behavior, prefer to use an IP address. - Type: `str` - `count` The number of ping to perform per hop. - Type: `int` - Default: `2` - `interval` The interval in seconds between sending each packet. - Type: `int` or `float` - Default: `0.05` - `timeout` The maximum waiting time for receiving a reply in seconds. - Type: `int` or `float` - Default: `2` - `first_hop` The initial time to live value used in outgoing probe packets. - Type: `int` - Default: `1` - `max_hops` The maximum time to live (max number of hops) used in outgoing probe packets. - Type: `int` - Default: `30` - `fast` When this option is enabled and an intermediate router has been reached, skip to the next hop rather than perform additional requests. The `count` parameter then becomes the maximum number of requests in the event of no response. - Type: `bool` - Default: `False` - `id` The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every traceroute process. The library handles this identifier itself by default. - Type: `int` - Default: `None` - `source` The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. - Type: `str` - Default: `None` - `family` The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. - Type: `int` - Default: `None` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `traffic_class` The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Return value - A list of `Hop` objects representing the route to the desired destination. A `Hop` has the same properties as a `Host` object but it also has a `distance`:
`address`, `min_rtt`, `avg_rtt`, `max_rtt`, `rtts`, `packets_sent`, `packets_received`, `packet_loss`, `jitter`, `is_alive`, `distance` The list is sorted in ascending order according to the distance, in terms of hops, that separates the remote host from the current machine. Gateways that do not respond to requests are not added to this list. #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. - [`SocketPermissionError`] If the privileges are insufficient to create the socket. - [`SocketAddressError`] If the source address cannot be assigned to the socket. - [`ICMPSocketError`] If another error occurs. See the [`ICMPv4Socket`] or [`ICMPv6Socket`] class for details. #### Example ```python >>> 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.* ```python 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 ```python >>> 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.* ```python 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 ```python >>> 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 ``` [`ping`]: #ping [`multiping`]: #multiping [`ICMPv4Socket`]: 3-sockets.md#ICMPv4Socket [`ICMPv6Socket`]: 3-sockets.md#ICMPv6Socket [`NameLookupError`]: 4-exceptions.md#NameLookupError [`ICMPSocketError`]: 4-exceptions.md#ICMPSocketError [`SocketAddressError`]: 4-exceptions.md#SocketAddressError [`SocketPermissionError`]: 4-exceptions.md#SocketPermissionError [`resolve`]: 5-utilities.md#resolve [Learn more about the `privileged` parameter.]: 6-use-icmplib-without-privileges.md icmplib-3.0.3/docs/3-sockets.md000066400000000000000000000317341417777567500162630ustar00rootroot00000000000000# Sockets and classes If you want to create your own functions and classes using the ICMP protocol, you can use the [`ICMPv4Socket`] (for IPv4 only) and the [`ICMPv6Socket`] (for IPv6 only). These classes have many methods and properties in common. They manipulate [`ICMPRequest`] and [`ICMPReply`] objects. ``` ┌──────────────────┐ ┌─────────────────┐ send(...) │ ICMPv4Socket │ receive() ┌─────────────────┐ │ ICMPRequest │ ────────────> │ or │ ────────────> │ ICMPReply │ └─────────────────┘ │ ICMPv6Socket │ └─────────────────┘ └──────────────────┘ ``` ### ICMPRequest A user-created object that represents an ICMP Echo Request. ```python ICMPRequest(destination, id, sequence, payload=None, payload_size=56, ttl=64, traffic_class=0) ``` #### Parameters and properties - `destination` The IP address of the host to which the message should be sent. - Type: `str` - `id` The identifier of the request. Used to match the reply with the request. In practice, a unique identifier is used for every ping process. On Linux, this identifier is automatically replaced if the request is sent from an unprivileged socket. - Type: `int` - `sequence` The sequence number. Used to match the reply with the request. Typically, the sequence number is incremented for each packet sent during the process. - Type: `int` - `payload` The payload content in bytes. A random payload is used by default. - Type: `bytes` - Default: `None` - `payload_size` The payload size. Ignored when the `payload` parameter is set. - Type: `int` - Default: `56` - `ttl` The time to live of the packet in terms of hops. - Type: `int` - Default: `64` - `traffic_class` The traffic class of the ICMP packet. Provides a defined level of service to the packet by setting the DS Field (formerly TOS) or the Traffic Class field of the IP header. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. *Only available on Unix systems. Ignored on Windows.* - Type: `int` - Default: `0` #### Properties only - `time` The timestamp of the ICMP request. Initialized to zero when creating the request and replaced by the `send` method of an ICMP socket with the time of sending. - Type: `float`
### ICMPReply A class that represents an ICMP reply. Generated from an ICMP socket. ```python ICMPReply(source, family, id, sequence, type, code, bytes_received, time) ``` #### Parameters and properties - `source` The IP address of the host that composes the ICMP message. - Type: `str` - `family` The address family. Can be set to `4` for IPv4 or `6` for IPv6 addresses. - Type: `int` - `id` The identifier of the reply. Used to match the reply with the request. - Type: `int` - `sequence` The sequence number. Used to match the reply with the request. - Type: `int` - `type` The type of ICMP message. - Type: `int` - `code` The ICMP error code. - Type: `int` - `bytes_received` The number of bytes received. - Type: `int` - `time` The timestamp of the ICMP reply. - Type: `float` #### Methods - `raise_for_status()` Throw an exception if the reply is not an ICMP Echo Reply. Otherwise, do nothing. - Raises [`DestinationUnreachable`]: If the destination is unreachable for some reason. - Raises [`TimeExceeded`]: If the time to live field of the ICMP request has reached zero. - Raises [`ICMPError`]: Raised for any other type and ICMP error code, except ICMP Echo Reply messages.
### ICMPv4Socket Class for sending and receiving ICMPv4 packets. ```python ICMPv4Socket(address=None, privileged=True) ``` #### Parameters - `source` The IP address from which you want to listen and send packets. By default, the socket listens on all interfaces. - Type: `str` - Default: `None` - `privileged` When this option is enabled, the socket fully manages the exchanges and the structure of the ICMP packets. Disable this option if you want to instantiate and use the socket without root privileges and let the kernel handle ICMP headers. *Only available on Unix systems. Ignored on Windows.* - Type: `bool` - Default: `True` #### Methods - `__init__(address=None, privileged=True)` *Constructor. Automatically called: do not call it directly.* - Raises [`SocketPermissionError`]: If the privileges are insufficient to create the socket. - Raises [`SocketAddressError`]: If the requested address cannot be assigned to the socket. - Raises [`ICMPSocketError`]: If another error occurs while creating the socket. - `__enter__()` Return this object. - `__exit__(type, value, traceback)` Call the `close` method. - `__del__()` *Destructor. Automatically called: do not call it directly.* Call the `close` method. - `send(request)` Send an ICMP request message over the network to a remote host. This operation is non-blocking. Use the `receive` method to get the reply. - Parameter `request` ([`ICMPRequest`]): The ICMP request you have created. If the socket is used in non-privileged mode on a Linux system, the identifier defined in the request will be replaced by the kernel. - Raises [`SocketBroadcastError`]: If a broadcast address is used and the corresponding option is not enabled on the socket (ICMPv4 only). - Raises [`SocketUnavailableError`]: If the socket is closed. - Raises [`ICMPSocketError`]: If another error occurs while sending. - `receive(request=None, timeout=2)` Receive an ICMP reply message from the socket. This method can be called multiple times if you expect several responses as with a broadcast address. - Parameter `request` ([`ICMPRequest`]): The ICMP request to use to match the response. By default, all ICMP packets arriving on the socket are returned. - Parameter `timeout` (`int` or `float`): The maximum waiting time for receiving the response in seconds. Default to `2`. - Raises [`TimeoutExceeded`]: If no response is received before the timeout specified in parameters. - Raises [`SocketUnavailableError`]: If the socket is closed. - Raises [`ICMPSocketError`]: If another error occurs while receiving. Returns an [`ICMPReply`] object representing the response of the desired destination or an upstream gateway. - `close()` Close the socket. It cannot be used after this call. #### Properties only - `sock` Return the underlying socket or `None` if the socket is closed. This property should only be used if the feature you want is not yet implemented. Some changes made to this socket may cause unexpected behavior or be incompatible with later versions of the library. Prefer to use the other methods and properties defined within this class if possible. - Type: `socket.socket` or `None` - `address` The IP address from which the socket listens and sends packets. Return `None` if the socket listens on all interfaces. - Type: `str` - `is_privileged` Indicate whether the socket is running in privileged mode. - Type: `bool` - `is_closed` Indicate whether the socket is closed. - Type: `bool` #### Properties and setters - `blocking` Set the blocking or non-blocking mode of the socket. - Type: `bool` - Default: `False` - `broadcast` Enable or disable the broadcast support on the socket. - Type: `bool` - Default: `False`
### ICMPv6Socket Class for sending and receiving ICMPv6 packets. ```python ICMPv6Socket(address=None, privileged=True) ``` #### Methods and properties The same methods and properties as for the [`ICMPv4Socket`] class, except the `broadcast` property.
### AsyncSocket A wrapper for ICMP sockets which makes them asynchronous. ```python AsyncSocket(icmp_sock) ``` #### Parameters - `icmp_sock` An ICMP socket. Once the wrapper is instantiated, this socket should no longer be used directly. - Type: [`ICMPv4Socket`] or [`ICMPv6Socket`] #### Methods The same methods as for the underlying ICMP socket, except: - `receive(request=None, timeout=2)` This function is now non-blocking. It must be awaited. - `detach()` Detach the socket from the wrapper and return it. The wrapper cannot be used after this call but the socket can be reused for other purposes. - `close()` Detach the underlying socket from the wrapper and close it. Both cannot be used after this call. #### Properties The same properties as for the underlying ICMP socket, except: - `is_closed` Indicate whether the underlying socket is closed or detached from this wrapper. - Type: `bool`
### Examples #### Sockets in action ```python from icmplib import * def one_ping(address, timeout=2, id=PID): # Create an ICMP socket sock = ICMPv4Socket() # Create an ICMP request # See the 'ICMPRequest' class for details request = ICMPRequest( destination=address, id=id, sequence=1) try: sock.send(request) # If the program arrives in this section, it means that the # packet has been transmitted. reply = sock.receive(request, timeout) # If the program arrives in this section, it means that a # packet has been received. The reply has the same identifier # and sequence number that the request but it can come from # an intermediate gateway. reply.raise_for_status() # If the program arrives in this section, it means that the # destination host has responded to the request. except TimeoutExceeded as err: # The timeout has been reached print(err) except DestinationUnreachable as err: # The reply indicates that the destination host is unreachable print(err) except TimeExceeded as err: # The reply indicates that the time to live exceeded in transit print(err) except ICMPLibError as err: # All other errors print(err) # Automatic socket closure (garbage collector) ``` #### Verbose ping ```python from icmplib import * from time import sleep def verbose_ping(address, count=4, interval=1, timeout=2, id=PID): # A payload of 56 bytes is used by default. You can modify it using # the 'payload_size' parameter of your ICMP request. print(f'PING {address}: 56 data bytes\n') # We detect the socket to use from the specified IP address if is_ipv6_address(address): sock = ICMPv6Socket() else: sock = ICMPv4Socket() for sequence in range(count): # We create an ICMP request request = ICMPRequest( destination=address, id=id, sequence=sequence) try: # We send the request sock.send(request) # We are awaiting receipt of an ICMP reply reply = sock.receive(request, timeout) # We received a reply # We display some information print(f' {reply.bytes_received} bytes from ' f'{reply.source}: ', end='') # We throw an exception if it is an ICMP error message reply.raise_for_status() # We calculate the round-trip time and we display it round_trip_time = (reply.time - request.time) * 1000 print(f'icmp_seq={sequence} ' f'time={round(round_trip_time, 3)} ms') # We wait before continuing if sequence < count - 1: sleep(interval) except TimeoutExceeded: # The timeout has been reached print(f' Request timeout for icmp_seq {sequence}') except ICMPError as err: # An ICMP error message has been received print(err) except ICMPLibError: # All other errors print(' An error has occurred.') print('\nCompleted.') verbose_ping('1.1.1.1') # PING 1.1.1.1: 56 data bytes # # 64 bytes from 1.1.1.1: icmp_seq=0 time=12.061 ms # 64 bytes from 1.1.1.1: icmp_seq=1 time=12.597 ms # 64 bytes from 1.1.1.1: icmp_seq=2 time=12.475 ms # 64 bytes from 1.1.1.1: icmp_seq=3 time=10.822 ms # # Completed. ``` [`ICMPRequest`]: #ICMPRequest [`ICMPReply`]: #ICMPReply [`ICMPv4Socket`]: #ICMPv4Socket [`ICMPv6Socket`]: #ICMPv6Socket [`ICMPSocketError`]: 4-exceptions.md#ICMPSocketError [`SocketAddressError`]: 4-exceptions.md#SocketAddressError [`SocketPermissionError`]: 4-exceptions.md#SocketPermissionError [`SocketUnavailableError`]: 4-exceptions.md#SocketUnavailableError [`SocketBroadcastError`]: 4-exceptions.md#SocketBroadcastError [`TimeoutExceeded`]: 4-exceptions.md#TimeoutExceeded [`ICMPError`]: 4-exceptions.md#ICMPError [`DestinationUnreachable`]: 4-exceptions.md#DestinationUnreachable [`TimeExceeded`]: 4-exceptions.md#TimeExceeded icmplib-3.0.3/docs/4-exceptions.md000066400000000000000000000035731417777567500167720ustar00rootroot00000000000000# Exceptions The library contains many exceptions to adapt to your needs: ``` ICMPLibError ├─ NameLookupError ├─ ICMPSocketError │ ├─ SocketAddressError │ ├─ SocketPermissionError │ ├─ SocketUnavailableError │ ├─ SocketBroadcastError │ └─ TimeoutExceeded │ └─ ICMPError ├─ DestinationUnreachable │ ├─ ICMPv4DestinationUnreachable │ └─ ICMPv6DestinationUnreachable │ └─ TimeExceeded ├─ ICMPv4TimeExceeded └─ ICMPv6TimeExceeded ``` ### ICMPLibError Exception class for the icmplib package. ### NameLookupError Raised when the requested name does not exist or cannot be resolved. This concerns both Fully Qualified Domain Names and hostnames. ### ICMPSocketError Base class for ICMP sockets exceptions. ### SocketAddressError Raised when the requested address cannot be assigned to the socket. ### SocketPermissionError Raised when the privileges are insufficient to create the socket. ### SocketUnavailableError Raised when an action is performed while the socket is closed. ### SocketBroadcastError Raised when a broadcast address is used and the corresponding option is not enabled on the socket. ### TimeoutExceeded Raised when a timeout occurs on a socket. ### ICMPError Base class for ICMP error messages. ### DestinationUnreachable Base class for ICMP Destination Unreachable messages. Destination Unreachable message is generated by the host or its inbound gateway to inform the client that the destination is unreachable for some reason. ### TimeExceeded Base class for ICMP Time Exceeded messages. Time Exceeded message is generated by a gateway to inform the source of a discarded datagram due to the time to live field reaching zero. A Time Exceeded message may also be sent by a host if it fails to reassemble a fragmented datagram within its time limit. icmplib-3.0.3/docs/5-utilities.md000066400000000000000000000064521417777567500166240ustar00rootroot00000000000000# Utilities ### resolve Resolve a hostname or FQDN to an IP address. Depending on the name specified in parameters, several IP addresses may be returned. This function relies on the DNS name server configured on your operating system. ```python resolve(name, family=None) ``` #### Parameters - `name` A hostname or a Fully Qualified Domain Name (FQDN). - Type: `str` - `family` The address family. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first for compatibility reasons (A DNS lookup) before searching for IPv6 addresses (AAAA DNS lookup). - Type: `int` - Default: `None` #### Return value - A list of IP addresses corresponding to the name passed as a parameter. #### Exceptions - [`NameLookupError`] If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. #### Example ```python >>> from icmplib import resolve >>> resolve('one.one.one.one') ['1.0.0.1', '1.1.1.1'] >>> resolve('localhost') ['127.0.0.1'] >>> resolve('ipv6.google.com') ['2a00:1450:4007:813::200e'] ```
### async_resolve Resolve a hostname or FQDN to an IP address. Depending on the name specified in parameters, several IP addresses may be returned. This function relies on the DNS name server configured on your operating system. *This function is non-blocking.* ```python async_resolve(name, family=None) ``` #### Parameters, return value and exceptions The same parameters, return values and exceptions as for the [`resolve`](#resolve) function. #### Example ```python >>> import asyncio >>> from icmplib import async_resolve >>> asyncio.run(async_resolve('one.one.one.one')) ['1.0.0.1', '1.1.1.1'] >>> asyncio.run(async_resolve('localhost')) ['127.0.0.1'] >>> asyncio.run(async_resolve('ipv6.google.com')) ['2a00:1450:4007:813::200e'] ```
### is_hostname Indicate whether the specified name is a hostname or an FQDN. ```python is_hostname(address) ``` #### Example ```python >>> from icmplib import is_hostname >>> is_hostname('one.one.one.one') True >>> is_hostname('localhost') True >>> is_hostname('127.0.0.1') False >>> is_hostname('2a00:1450:4007:813::200e') False ```
### is_ipv4_address Indicate whether the specified address is an IPv4 address. This function does not perform a strict checking. Its does not check if each byte of the IP address is within the allowed range. This function has been designed to be fast. ```python is_ipv4_address(address) ``` #### Example ```python >>> from icmplib import is_ipv4_address >>> is_ipv4_address('one.one.one.one') False >>> is_ipv4_address('localhost') False >>> is_ipv4_address('127.0.0.1') True >>> is_ipv4_address('2a00:1450:4007:813::200e') False ```
### is_ipv6_address Indicate whether the specified address is an IPv4 address. This function does not perform a strict checking. Its does not check if each byte of the IP address is within the allowed range. This function has been designed to be fast. ```python is_ipv6_address(address) ``` #### Example ```python >>> from icmplib import is_ipv6_address >>> is_ipv6_address('one.one.one.one') False >>> is_ipv6_address('localhost') False >>> is_ipv6_address('127.0.0.1') False >>> is_ipv6_address('2a00:1450:4007:813::200e') True ``` [`NameLookupError`]: 4-exceptions.md#NameLookupError icmplib-3.0.3/docs/6-use-icmplib-without-privileges.md000066400000000000000000000023721417777567500226700ustar00rootroot00000000000000# Use icmplib without root privileges - **Step 1: adapt your code** To use icmplib without root privileges, you must set the `privileged` parameter to `False` on the [`ping`] and [`multiping`] functions, as well as their asynchronous variants and the low level classes. By disabling this parameter, icmplib let the kernel handle some parts of the ICMP headers. The [`traceroute`] function does not have this parameter. It should always be run as root to receive ICMP Time Exceeded messages from gateways. - **Step 2: allow this feature on your operating system** On some Linux systems, you must allow this feature: ```shell $ echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee -a /etc/sysctl.conf $ sudo sysctl -p ``` You can check the current value with the following command: ```shell $ sysctl net.ipv4.ping_group_range net.ipv4.ping_group_range = 0 2147483647 ``` *Since Ubuntu 20.04 LTS, this manipulation is no longer necessary.* [Read more about `ping_group_range` on www.kernel.org] [`ping`]: 2-functions.md#ping [`multiping`]: 2-functions.md#multiping [`traceroute`]: 2-functions.md#traceroute [Read more about `ping_group_range` on www.kernel.org]: https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt icmplib-3.0.3/docs/README.md000066400000000000000000000034411417777567500153770ustar00rootroot00000000000000# Documentation **[Installation](1-installation.md)** - [Requirements](1-installation.md#requirements) - [Installation and update](1-installation.md#installation-and-update) - [Imports](1-installation.md#imports) **[Built-in functions](2-functions.md)** - [`ping`](2-functions.md#ping) - [`multiping`](2-functions.md#multiping) - [`traceroute`](2-functions.md#traceroute) - [`async_ping`](2-functions.md#async_ping) - [`async_multiping`](2-functions.md#async_multiping) **[Sockets and classes](3-sockets.md)** - [`ICMPRequest`](3-sockets.md#ICMPRequest) - [`ICMPReply`](3-sockets.md#ICMPReply) - [`ICMPv4Socket`](3-sockets.md#ICMPv4Socket) - [`ICMPv6Socket`](3-sockets.md#ICMPv6Socket) - [`AsyncSocket`](3-sockets.md#AsyncSocket) - [Examples](3-sockets.md#examples) **[Exceptions](4-exceptions.md)** - [`ICMPLibError`](4-exceptions.md#ICMPLibError) - [`NameLookupError`](4-exceptions.md#NameLookupError) - [`ICMPSocketError`](4-exceptions.md#ICMPSocketError) - [`SocketAddressError`](4-exceptions.md#SocketAddressError) - [`SocketPermissionError`](4-exceptions.md#SocketPermissionError) - [`SocketUnavailableError`](4-exceptions.md#SocketUnavailableError) - [`SocketBroadcastError`](4-exceptions.md#SocketBroadcastError) - [`TimeoutExceeded`](4-exceptions.md#TimeoutExceeded) - [`ICMPError`](4-exceptions.md#ICMPError) - [`DestinationUnreachable`](4-exceptions.md#DestinationUnreachable) - [`TimeExceeded`](4-exceptions.md#TimeExceeded) **[Utilities](5-utilities.md)** - [`resolve`](5-utilities.md#resolve) - [`async_resolve`](5-utilities.md#async_resolve) - [`is_hostname`](5-utilities.md#is_hostname) - [`is_ipv4_address`](5-utilities.md#is_ipv4_address) - [`is_ipv6_address`](5-utilities.md#is_ipv6_address) **[Use icmplib without root privileges](6-use-icmplib-without-privileges.md)** **[Examples](../examples)** icmplib-3.0.3/examples/000077500000000000000000000000001417777567500150045ustar00rootroot00000000000000icmplib-3.0.3/examples/README.md000066400000000000000000000037471417777567500162760ustar00rootroot00000000000000# Examples ## Built-in functions - [ping](ping.py) - [multiping](multiping.py) - [traceroute](traceroute.py) ## Sockets (advanced) - [verbose-ping](verbose_ping.py) This example shows how to reproduce the ping command using sockets of `icmplib`. *Output:* ```console PING 1.1.1.1: 56 data bytes 64 bytes from 1.1.1.1: icmp_seq=0 time=12.061 ms 64 bytes from 1.1.1.1: icmp_seq=1 time=12.597 ms 64 bytes from 1.1.1.1: icmp_seq=2 time=12.475 ms 64 bytes from 1.1.1.1: icmp_seq=3 time=10.822 ms Completed. ``` - [verbose-traceroute](verbose_traceroute.py) This example shows how to reproduce the traceroute command. *Output:* ```console Traceroute to ovh.com (198.27.92.1): 56 data bytes, 30 hops max 1 192.168.0.254 192.168.0.254 9.86 ms 2 194.149.164.56 194.149.164.56 4.61 ms 3 213.186.32.181 be100-159.th2-1-a9.fr.eu 11.97 ms 4 94.23.122.146 be102.rbx-g1-nc5.fr.eu 15.81 ms 5 * * * 6 37.187.231.75 be5.rbx-iplb1-a70.fr.eu 17.12 ms 7 198.27.92.1 www.ovh.com 10.87 ms Completed. ``` - [broadcast-ping](broadcast_ping.py) This example shows how to enable the broadcast support on a socket. *Output:* ```console PING 255.255.255.255: 56 data bytes 64 bytes from 10.0.0.17: icmp_seq=0 time=1.065 ms 64 bytes from 10.0.0.40: icmp_seq=0 time=1.595 ms 64 bytes from 10.0.0.41: icmp_seq=0 time=9.471 ms 64 bytes from 10.0.0.17: icmp_seq=1 time=0.983 ms 64 bytes from 10.0.0.40: icmp_seq=1 time=1.579 ms 64 bytes from 10.0.0.41: icmp_seq=1 time=9.345 ms 64 bytes from 10.0.0.17: icmp_seq=2 time=0.916 ms 64 bytes from 10.0.0.40: icmp_seq=2 time=2.031 ms 64 bytes from 10.0.0.41: icmp_seq=2 time=9.554 ms 64 bytes from 10.0.0.17: icmp_seq=3 time=1.112 ms 64 bytes from 10.0.0.40: icmp_seq=3 time=1.384 ms 64 bytes from 10.0.0.41: icmp_seq=3 time=9.565 ms Completed. ``` icmplib-3.0.3/examples/broadcast_ping.py000066400000000000000000000054441417777567500203440ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: broadcast ping (advanced) PING 255.255.255.255: 56 data bytes 64 bytes from 10.0.0.17: icmp_seq=0 time=1.065 ms 64 bytes from 10.0.0.40: icmp_seq=0 time=1.595 ms 64 bytes from 10.0.0.41: icmp_seq=0 time=9.471 ms 64 bytes from 10.0.0.17: icmp_seq=1 time=0.983 ms 64 bytes from 10.0.0.40: icmp_seq=1 time=1.579 ms 64 bytes from 10.0.0.41: icmp_seq=1 time=9.345 ms 64 bytes from 10.0.0.17: icmp_seq=2 time=0.916 ms 64 bytes from 10.0.0.40: icmp_seq=2 time=2.031 ms 64 bytes from 10.0.0.41: icmp_seq=2 time=9.554 ms 64 bytes from 10.0.0.17: icmp_seq=3 time=1.112 ms 64 bytes from 10.0.0.40: icmp_seq=3 time=1.384 ms 64 bytes from 10.0.0.41: icmp_seq=3 time=9.565 ms Completed. ''' from icmplib import ICMPv4Socket, ICMPRequest from icmplib import ICMPLibError, TimeoutExceeded, PID def broadcast_ping(address, count=4, timeout=1, id=PID): # A payload of 56 bytes is used by default. You can modify it using # the 'payload_size' parameter of your ICMP request. print(f'PING {address}: 56 data bytes\n') # Broadcast is only possible in IPv4 sock = ICMPv4Socket() # We allow the socket to send broadcast packets sock.broadcast = True for sequence in range(count): # We create an ICMP request request = ICMPRequest( destination=address, id=id, sequence=sequence) try: # We send the request sock.send(request) while 'we receive replies': # We are awaiting receipt of an ICMP reply. If there is # no more responses, the 'TimeoutExceeded' exception is # thrown and the loop is stopped. reply = sock.receive(request, timeout) # We calculate the round-trip time round_trip_time = (reply.time - request.time) * 1000 # We display some information print(f' {reply.bytes_received} bytes from ' f'{reply.source}: icmp_seq={sequence} ' f'time={round(round_trip_time, 3)} ms') except TimeoutExceeded: # The timeout has been reached # We use this exception to break the while loop pass except ICMPLibError: # All other errors print(' An error has occurred.') print('\nCompleted.') # Limited broadcast broadcast_ping('255.255.255.255') # Directed broadcast # broadcast_ping('192.168.0.255') icmplib-3.0.3/examples/multiping.py000066400000000000000000000020611417777567500173650ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: multiping ''' from icmplib import resolve, multiping addresses = [ # IPv4 addresses '1.1.1.1', '8.8.8.8', '10.0.0.100', '10.0.0.200', # IPv6 addresses '::1', # Hostnames and Fully Qualified Domain Names (FQDNs) are allowed but # not recommended. You can easily retrieve their IP address by # calling the built-in 'resolve' function. For deterministic # behavior, prefer to use an IP address. 'github.com' ] hosts = multiping(addresses, count=2, timeout=1) hosts_alive = [] hosts_dead = [] for host in hosts: if host.is_alive: hosts_alive.append(host.address) else: hosts_dead.append(host.address) print(hosts_alive) # ['1.1.1.1', '8.8.8.8', '::1', '140.82.121.4'] print(hosts_dead) # ['10.0.0.100', '10.0.0.200'] icmplib-3.0.3/examples/ping.py000066400000000000000000000030421417777567500163120ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: ping ''' from icmplib import ping host = ping('1.1.1.1', count=10, interval=0.5, timeout=1) # The IP address of the host that responded to the request print(host.address) # '1.1.1.1' # The minimum round-trip time in milliseconds print(host.min_rtt) # 5.761 # The average round-trip time in milliseconds print(host.avg_rtt) # 12.036 # The maximum round-trip time in milliseconds print(host.max_rtt) # 16.207 # The list of round-trip times expressed in milliseconds print(host.rtts) # [ 11.595010757446289, 13.135194778442383, 9.614229202270508, # 16.018152236938477, 11.960029602050781, 5.761146545410156, # 16.207218170166016, 11.937141418457031, 12.098073959350586 ] # The number of requests transmitted to the remote host print(host.packets_sent) # 10 # The number of ICMP responses received from the remote host print(host.packets_received) # 9 # Packet loss occurs when packets fail to reach their destination # Returns a float between 0 and 1 (all packets are lost) print(host.packet_loss) # 0.1 # The jitter in milliseconds, defined as the variance of the latency of # packets flowing through the network # At least two ICMP responses are required to calculate the jitter print(host.jitter) # 4.575 # Indicates whether the host is reachable print(host.is_alive) # True icmplib-3.0.3/examples/traceroute.py000066400000000000000000000020071417777567500175320ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: traceroute ''' from icmplib import traceroute hops = traceroute('1.1.1.1', timeout=1, fast=True) print(hops) # [ , , # , , # ] last_distance = 0 for hop in hops: if last_distance + 1 != hop.distance: print(' * Some gateways are not responding') print(f' {hop.distance:<2} {hop.address:15} ' f'{hop.avg_rtt} ms') last_distance = hop.distance # 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 icmplib-3.0.3/examples/verbose_ping.py000066400000000000000000000050421417777567500200410ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: verbose ping (advanced) PING 1.1.1.1: 56 data bytes 64 bytes from 1.1.1.1: icmp_seq=0 time=12.061 ms 64 bytes from 1.1.1.1: icmp_seq=1 time=12.597 ms 64 bytes from 1.1.1.1: icmp_seq=2 time=12.475 ms 64 bytes from 1.1.1.1: icmp_seq=3 time=10.822 ms Completed. ''' from time import sleep from icmplib import ICMPv4Socket, ICMPv6Socket, ICMPRequest from icmplib import ICMPLibError, ICMPError, TimeoutExceeded from icmplib import PID, is_ipv6_address def verbose_ping(address, count=4, interval=1, timeout=2, id=PID): # A payload of 56 bytes is used by default. You can modify it using # the 'payload_size' parameter of your ICMP request. print(f'PING {address}: 56 data bytes\n') # We detect the socket to use from the specified IP address if is_ipv6_address(address): sock = ICMPv6Socket() else: sock = ICMPv4Socket() for sequence in range(count): # We create an ICMP request request = ICMPRequest( destination=address, id=id, sequence=sequence) try: # We send the request sock.send(request) # We are awaiting receipt of an ICMP reply reply = sock.receive(request, timeout) # We received a reply # We display some information print(f' {reply.bytes_received} bytes from ' f'{reply.source}: ', end='') # We throw an exception if it is an ICMP error message reply.raise_for_status() # We calculate the round-trip time and we display it round_trip_time = (reply.time - request.time) * 1000 print(f'icmp_seq={sequence} ' f'time={round(round_trip_time, 3)} ms') # We wait before continuing if sequence < count - 1: sleep(interval) except TimeoutExceeded: # The timeout has been reached print(f' Request timeout for icmp_seq {sequence}') except ICMPError as err: # An ICMP error message has been received print(err) except ICMPLibError: # All other errors print(' An error has occurred.') print('\nCompleted.') verbose_ping('1.1.1.1') icmplib-3.0.3/examples/verbose_traceroute.py000066400000000000000000000076741417777567500212760ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ Example: verbose traceroute (advanced) Traceroute to ovh.com (198.27.92.1): 56 data bytes, 30 hops max 1 192.168.0.254 192.168.0.254 9.86 ms 2 194.149.164.56 194.149.164.56 4.61 ms 3 213.186.32.181 be100-159.th2-1-a9.fr.eu 11.97 ms 4 94.23.122.146 be102.rbx-g1-nc5.fr.eu 15.81 ms 5 * * * 6 37.187.231.75 be5.rbx-iplb1-a70.fr.eu 17.12 ms 7 198.27.92.1 www.ovh.com 10.87 ms Completed. ''' from socket import getfqdn from time import sleep from icmplib import ICMPv4Socket, ICMPv6Socket, ICMPRequest from icmplib import ICMPLibError, TimeoutExceeded, TimeExceeded from icmplib import PID, resolve, is_hostname, is_ipv6_address def verbose_traceroute(address, count=2, interval=0.05, timeout=2, id=PID, max_hops=30): # We perform a DNS lookup if a hostname or an FQDN is passed in # parameters. if is_hostname(address): ip_address = resolve(address)[0] else: ip_address = address # A payload of 56 bytes is used by default. You can modify it using # the 'payload_size' parameter of your ICMP request. print(f'Traceroute to {address} ({ip_address}): ' f'56 data bytes, {max_hops} hops max\n') # We detect the socket to use from the specified IP address if is_ipv6_address(ip_address): sock = ICMPv6Socket() else: sock = ICMPv4Socket() ttl = 1 host_reached = False while not host_reached and ttl <= max_hops: for sequence in range(count): # We create an ICMP request request = ICMPRequest( destination=ip_address, id=id, sequence=sequence, ttl=ttl) try: # We send the request sock.send(request) # We are awaiting receipt of an ICMP reply reply = sock.receive(request, timeout) # We received a reply # We display some information source_name = getfqdn(reply.source) print(f' {ttl:<2} {reply.source:15} ' f'{source_name:40} ', end='') # We throw an exception if it is an ICMP error message reply.raise_for_status() # We reached the destination host # We calculate the round-trip time and we display it round_trip_time = (reply.time - request.time) * 1000 print(round(round_trip_time, 2), 'ms') # We can stop the search host_reached = True break except TimeExceeded as err: # An ICMP Time Exceeded message has been received # The message was probably generated by an intermediate # gateway reply = err.reply # We calculate the round-trip time and we display it round_trip_time = (reply.time - request.time) * 1000 print(round(round_trip_time, 2), 'ms') sleep(interval) break except TimeoutExceeded: # The timeout has been reached and no host or gateway # has responded after multiple attempts if sequence >= count - 1: print(f' {ttl:<2} * * *') except ICMPLibError: # Other errors are ignored pass ttl += 1 print('\nCompleted.') # This function supports both FQDNs and IP addresses. See the 'resolve' # function for details. verbose_traceroute('ovh.com') icmplib-3.0.3/icmplib/000077500000000000000000000000001417777567500146055ustar00rootroot00000000000000icmplib-3.0.3/icmplib/__init__.py000066400000000000000000000027541417777567500167260ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' from .sockets import ICMPv4Socket, ICMPv6Socket, AsyncSocket from .models import ICMPRequest, ICMPReply, Host, Hop from .ping import ping, async_ping from .multiping import multiping, async_multiping from .traceroute import traceroute from .exceptions import * from .utils import is_hostname, is_ipv4_address, is_ipv6_address from .utils import PID, resolve, async_resolve __author__ = 'Valentin BELYN' __copyright__ = 'Copyright 2017-2022 Valentin BELYN' __license__ = 'GNU Lesser General Public License v3.0' __version__ = '3.0.3' __build__ = '220206' icmplib-3.0.3/icmplib/exceptions.py000066400000000000000000000136721417777567500173510ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' class ICMPLibError(Exception): ''' Exception class for the icmplib package. ''' class NameLookupError(ICMPLibError): ''' Raised when the requested name does not exist or cannot be resolved. This concerns both Fully Qualified Domain Names and hostnames. ''' def __init__(self, name): message = f'The name \'{name}\' cannot be resolved' super().__init__(message) class ICMPSocketError(ICMPLibError): ''' Base class for ICMP sockets exceptions. ''' class SocketAddressError(ICMPSocketError): ''' Raised when the requested address cannot be assigned to the socket. ''' def __init__(self, address): message = f'The requested address ({address}) cannot be ' \ 'assigned to the socket' super().__init__(message) class SocketPermissionError(ICMPSocketError): ''' Raised when the privileges are insufficient to create the socket. ''' def __init__(self, privileged): if privileged: message = 'Root privileges are required to create the socket' else: message = 'A prior configuration of your OS is required ' \ 'to use ICMP sockets without root privileges. ' \ 'Read more on https://github.com/ValentinBELYN' \ '/icmplib' super().__init__(message) class SocketUnavailableError(ICMPSocketError): ''' Raised when an action is performed while the socket is closed. ''' def __init__(self): message = 'The socket can no longer be used after its closure' super().__init__(message) class SocketBroadcastError(ICMPSocketError): ''' Raised when a broadcast address is used and the corresponding option is not enabled on the socket. ''' def __init__(self): message = 'Broadcast is not allowed: ' \ 'please use the \'broadcast\' property to allow it' super().__init__(message) class TimeoutExceeded(ICMPSocketError): ''' Raised when a timeout occurs on a socket. ''' def __init__(self, timeout): message = f'The timeout has been reached ({timeout}s)' super().__init__(message) class ICMPError(ICMPLibError): ''' Base class for ICMP error messages. ''' def __init__(self, message, reply): super().__init__(message) self._reply = reply @property def reply(self): return self._reply class DestinationUnreachable(ICMPError): ''' Base class for ICMP Destination Unreachable messages. Destination Unreachable message is generated by the host or its inbound gateway to inform the client that the destination is unreachable for some reason. ''' _CODES = {} def __init__(self, reply): if reply.code in self._CODES: message = self._CODES[reply.code] else: message = f'Destination unreachable, bad code: {reply.code}' super().__init__(message, reply) class ICMPv4DestinationUnreachable(DestinationUnreachable): _CODES = { 0: 'Destination network unreachable', 1: 'Destination host unreachable', 2: 'Destination protocol unreachable', 3: 'Destination port unreachable', 4: 'Fragmentation needed and DF set', 5: 'Source route failed', 6: 'Destination network unknown', 7: 'Destination host unknown', 8: 'Source host isolated', 9: 'Destination network prohibed', 10: 'Destination host prohibed', 11: 'Destination network unreachable for ToS', 12: 'Destination host unreachable for ToS', 13: 'Packet filtered', 14: 'Precedence violation', 15: 'Precedence cutoff' } class ICMPv6DestinationUnreachable(DestinationUnreachable): _CODES = { 0: 'No route to destination', 1: 'Communication with destination administratively prohibited', 2: 'Beyond scope of source address', 3: 'Address unreachable', 4: 'Port unreachable', 5: 'Source address failed ingress/egress policy', 6: 'Reject route to destination' } class TimeExceeded(ICMPError): ''' Base class for ICMP Time Exceeded messages. Time Exceeded message is generated by a gateway to inform the source of a discarded datagram due to the time to live field reaching zero. A Time Exceeded message may also be sent by a host if it fails to reassemble a fragmented datagram within its time limit. ''' _CODES = {} def __init__(self, reply): if reply.code in self._CODES: message = self._CODES[reply.code] else: message = f'Time exceeded, bad code: {reply.code}' super().__init__(message, reply) class ICMPv4TimeExceeded(TimeExceeded): _CODES = { 0: 'Time to live exceeded', 1: 'Fragment reassembly time exceeded' } class ICMPv6TimeExceeded(TimeExceeded): _CODES = { 0: 'Hop limit exceeded', 1: 'Fragment reassembly time exceeded' } icmplib-3.0.3/icmplib/models.py000066400000000000000000000313251417777567500164460ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' from .exceptions import * from .utils import random_byte_message class ICMPRequest: ''' A user-created object that represents an ICMP Echo Request. :type destination: str :param destination: The IP address of the host to which the message should be sent. :type id: int :param id: The identifier of the request. Used to match the reply with the request. In practice, a unique identifier is used for every ping process. On Linux, this identifier is automatically replaced if the request is sent from an unprivileged socket. :type sequence: int :param sequence: The sequence number. Used to match the reply with the request. Typically, the sequence number is incremented for each packet sent during the process. :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type ttl: int, optional :param ttl: The time to live of the packet in terms of hops. Default to 64. :type traffic_class: int, optional :param traffic_class: The traffic class of the ICMP packet. Provides a defined level of service to the packet by setting the DS Field (formerly TOS) or the Traffic Class field of the IP header. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. ''' __slots__ = '_destination', '_id', '_sequence', '_payload', \ '_payload_size', '_ttl', '_traffic_class', '_time' def __init__(self, destination, id, sequence, payload=None, payload_size=56, ttl=64, traffic_class=0): if payload: payload_size = len(payload) self._destination = destination self._id = id & 0xffff self._sequence = sequence & 0xffff self._payload = payload self._payload_size = payload_size self._ttl = ttl self._traffic_class = traffic_class self._time = 0 def __repr__(self): return f'' @property def destination(self): ''' The IP address of the host to which the message should be sent. ''' return self._destination @property def id(self): ''' The identifier of the request. Used to match the reply with the request. ''' return self._id @property def sequence(self): ''' The sequence number. Used to match the reply with the request. ''' return self._sequence @property def payload(self): ''' The payload content in bytes. Return a random payload if not defined. ''' return self._payload or random_byte_message(self._payload_size) @property def payload_size(self): ''' The payload size. ''' return self._payload_size @property def ttl(self): ''' The time to live of the packet in terms of hops. ''' return self._ttl @property def traffic_class(self): ''' The traffic class of the packet. ''' return self._traffic_class @property def time(self): ''' The timestamp of the ICMP request. Initialized to zero when creating the request and replaced by the `send` method of an ICMP socket with the time of sending. ''' return self._time class ICMPReply: ''' A class that represents an ICMP reply. Generated from an ICMP socket. :type source: str :param source: The IP address of the host that composes the ICMP message. :type family: int :param family: The address family. Can be set to `4` for IPv4 or `6` for IPv6 addresses. :type id: int :param id: The identifier of the reply. Used to match the reply with the request. :type sequence: int :param sequence: The sequence number. Used to match the reply with the request. :type type: int :param type: The type of ICMP message. :type code: int :param code: The ICMP error code. :type bytes_received: int :param bytes_received: The number of bytes received. :type time: float :param time: The timestamp of the ICMP reply. ''' __slots__ = '_source', '_family', '_id', '_sequence', '_type', \ '_code', '_bytes_received', '_time' def __init__(self, source, family, id, sequence, type, code, bytes_received, time): self._source = source self._family = family self._id = id self._sequence = sequence self._type = type self._code = code self._bytes_received = bytes_received self._time = time def __repr__(self): return f'' def raise_for_status(self): ''' Throw an exception if the reply is not an ICMP Echo Reply. Otherwise, do nothing. :raises DestinationUnreachable: If the destination is unreachable for some reason. :raises TimeExceeded: If the time to live field of the ICMP request has reached zero. :raises ICMPError: Raised for any other type and ICMP error code, except ICMP Echo Reply messages. ''' if self._family == 6: if self._type == 1: raise ICMPv6DestinationUnreachable(self) if self._type == 3: raise ICMPv6TimeExceeded(self) else: if self._type == 3: raise ICMPv4DestinationUnreachable(self) if self._type == 11: raise ICMPv4TimeExceeded(self) if (self._family == 4 and self._type != 0 or self._family == 6 and self._type != 129): message = f'Error type: {self._type}, code: {self._code}' raise ICMPError(message, self) @property def source(self): ''' The IP address of the host that composes the ICMP message. ''' return self._source @property def id(self): ''' The identifier of the reply. Used to match the reply with the request. ''' return self._id @property def sequence(self): ''' The sequence number. Used to match the reply with the request. ''' return self._sequence @property def type(self): ''' The type of ICMP message. ''' return self._type @property def code(self): ''' The ICMP error code. ''' return self._code @property def bytes_received(self): ''' The number of bytes received. ''' return self._bytes_received @property def time(self): ''' The timestamp of the ICMP reply. ''' return self._time class Host: ''' A class that represents a host. It simplifies the use of the results from the `ping`, `multiping` and `traceroute` functions. :type address: str :param address: The IP address of the host that responded to the request. :type packets_sent: int :param packets_sent: The number of packets transmitted to the destination host. :type rtts: list[float] :param rtts: The list of round-trip times expressed in milliseconds. ''' __slots__ = '_address', '_packets_sent', '_rtts' def __init__(self, address, packets_sent, rtts): self._address = address self._packets_sent = packets_sent self._rtts = rtts def __repr__(self): return f'' def __str__(self): return f' {self._address}\n' + '-' * 60 + '\n' \ f' Packets sent: {self._packets_sent}\n' \ f' Packets received: {self.packets_received}\n' \ f' Packet loss: {self.packet_loss * 100}%\n' \ f' Round-trip times: {self.min_rtt} ms / ' \ f'{self.avg_rtt} ms / {self.max_rtt} ms\n' \ f' Jitter: {self.jitter} ms\n' + '-' * 60 @property def address(self): ''' The IP address of the host that responded to the request. ''' return self._address @property def min_rtt(self): ''' The minimum round-trip time in milliseconds. ''' if not self._rtts: return 0.0 return round(min(self._rtts), 3) @property def avg_rtt(self): ''' The average round-trip time in milliseconds. ''' if not self._rtts: return 0.0 return round(sum(self._rtts) / len(self._rtts), 3) @property def max_rtt(self): ''' The maximum round-trip time in milliseconds. ''' if not self._rtts: return 0.0 return round(max(self._rtts), 3) @property def rtts(self): ''' The list of round-trip times expressed in milliseconds. ''' return self._rtts @property def packets_sent(self): ''' The number of requests transmitted to the remote host. ''' return self._packets_sent @property def packets_received(self): ''' The number of ICMP responses received from the remote host. ''' return len(self._rtts) @property def packet_loss(self): ''' Packet loss occurs when packets fail to reach their destination. Return a `float` between 0 and 1 (all packets are lost). ''' if not self._packets_sent: return 0.0 return round(1 - len(self._rtts) / self._packets_sent, 2) @property def jitter(self): ''' The jitter in milliseconds, defined as the variance of the latency of packets flowing through the network. At least two ICMP responses are required to calculate the jitter. ''' sum_deltas = 0.0 num_deltas = len(self._rtts) - 1 if num_deltas < 1: return 0.0 for i in range(num_deltas): sum_deltas += abs(self._rtts[i] - self._rtts[i + 1]) return round(sum_deltas / num_deltas, 3) @property def is_alive(self): ''' Indicate whether the host is reachable. Return a `boolean`. ''' return len(self._rtts) > 0 class Hop(Host): ''' A class that represents a hop. It extends the `Host` class and adds some features for the `traceroute` function. :type address: str :param address: The IP address of the gateway or host that responded to the request. :type packets_sent: int :param packets_sent: The number of packets transmitted to the destination host. :type rtts: list[float] :param rtts: The list of round-trip times expressed in milliseconds. :type distance: int :param distance: The distance, in terms of hops, that separates the remote host from the current machine. ''' __slots__ = '_address', '_packets_sent', '_rtts', '_distance' def __init__(self, address, packets_sent, rtts, distance): super().__init__(address, packets_sent, rtts) self._distance = distance def __repr__(self): return f'' def __str__(self): return f' #{self._distance:<2} {super().__str__()[2:]}' @property def distance(self): ''' The distance, in terms of hops, that separates the remote host from the current machine. ''' return self._distance icmplib-3.0.3/icmplib/multiping.py000066400000000000000000000237441417777567500172010ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' import asyncio from .ping import async_ping async def async_multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs): ''' Send ICMP Echo Request packets to several network hosts. This function is non-blocking. :type addresses: list[str] :param addresses: The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in `async_resolve` function. :type count: int, optional :param count: The number of ping to perform per address. Default to 2. :type interval: int or float, optional :param interval: The interval in seconds between sending each packet. Default to 0.5. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving a reply in seconds. Default to 2. :type concurrent_tasks: int, optional :param concurrent_tasks: The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system. Default to 50. :type source: str, optional :param source: The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function. :type family: int, optional :param family: The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. :type privileged: bool, optional :param privileged: When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. Advanced (**kwags): :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type traffic_class: int, optional :param traffic_class: The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. :rtype: list[Host] :returns: A list of `Host` objects containing statistics about the desired destinations. The list is sorted in the same order as the addresses passed in parameters. :raises NameLookupError: If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the source address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs. See the `ICMPv4Socket` or `ICMPv6Socket` class for details. Usage:: >>> import asyncio >>> from icmplib import async_multiping >>> hosts = asyncio.run(async_multiping(['10.0.0.5', '::1'])) >>> for host in hosts: ... if host.is_alive: ... print(f'{host.address} is up!') ... else: ... print(f'{host.address} is down!') 10.0.0.5 is down! ::1 is up! See the `Host` class for details. ''' loop = asyncio.get_running_loop() tasks = [] tasks_pending = set() for address in addresses: if len(tasks_pending) >= concurrent_tasks: _, tasks_pending = await asyncio.wait( tasks_pending, return_when=asyncio.FIRST_COMPLETED) task = loop.create_task( async_ping( address=address, count=count, interval=interval, timeout=timeout, source=source, family=family, privileged=privileged, **kwargs)) tasks.append(task) tasks_pending.add(task) await asyncio.wait(tasks_pending) return [task.result() for task in tasks] def multiping(addresses, count=2, interval=0.5, timeout=2, concurrent_tasks=50, source=None, family=None, privileged=True, **kwargs): ''' Send ICMP Echo Request packets to several network hosts. :type addresses: list[str] :param addresses: The IP addresses of the hosts to which messages should be sent. Hostnames and FQDNs are allowed but not recommended. You can easily retrieve their IP address by calling the built-in `resolve` function. :type count: int, optional :param count: The number of ping to perform per address. Default to 2. :type interval: int or float, optional :param interval: The interval in seconds between sending each packet. Default to 0.5. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving a reply in seconds. Default to 2. :type concurrent_tasks: int, optional :param concurrent_tasks: The maximum number of concurrent tasks to speed up processing. This value cannot exceed the maximum number of file descriptors configured on the operating system. Default to 50. :type source: str, optional :param source: The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destinations. This parameter should not be used if you are passing both IPv4 and IPv6 addresses to this function. :type family: int, optional :param family: The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. :type privileged: bool, optional :param privileged: When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. Advanced (**kwags): :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type traffic_class: int, optional :param traffic_class: The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. :rtype: list[Host] :returns: A list of `Host` objects containing statistics about the desired destinations. The list is sorted in the same order as the addresses passed in parameters. :raises NameLookupError: If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the source address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs. See the `ICMPv4Socket` or `ICMPv6Socket` class for details. Usage:: >>> from icmplib import multiping >>> hosts = multiping(['10.0.0.5', '127.0.0.1', '::1']) >>> for host in hosts: ... if host.is_alive: ... 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! See the `Host` class for details. ''' return asyncio.run( async_multiping( addresses=addresses, count=count, interval=interval, timeout=timeout, concurrent_tasks=concurrent_tasks, source=source, family=family, privileged=privileged, **kwargs)) icmplib-3.0.3/icmplib/ping.py000066400000000000000000000240111417777567500161120ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' import asyncio from time import sleep from .sockets import ICMPv4Socket, ICMPv6Socket, AsyncSocket from .models import ICMPRequest, Host from .exceptions import ICMPLibError from .utils import * def ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs): ''' Send ICMP Echo Request packets to a network host. :type address: str :param address: The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address. :type count: int, optional :param count: The number of ping to perform. Default to 4. :type interval: int or float, optional :param interval: The interval in seconds between sending each packet. Default to 1. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving a reply in seconds. Default to 2. :type id: int, optional :param id: The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default. :type source: str, optional :param source: The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. :type family: int, optional :param family: The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. :type privileged: bool, optional :param privileged: When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. Advanced (**kwags): :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type traffic_class: int, optional :param traffic_class: The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. :rtype: Host :returns: A `Host` object containing statistics about the desired destination. :raises NameLookupError: If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the source address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs. See the `ICMPv4Socket` or `ICMPv6Socket` class for details. Usage:: >>> from icmplib import ping >>> host = ping('1.1.1.1') >>> host.avg_rtt 13.2 >>> host.is_alive True See the `Host` class for details. ''' if is_hostname(address): address = resolve(address, family)[0] if is_ipv6_address(address): _Socket = ICMPv6Socket else: _Socket = ICMPv4Socket id = id or unique_identifier() packets_sent = 0 rtts = [] with _Socket(source, privileged) as sock: for sequence in range(count): if sequence > 0: sleep(interval) request = ICMPRequest( destination=address, id=id, sequence=sequence, **kwargs) try: sock.send(request) packets_sent += 1 reply = sock.receive(request, timeout) reply.raise_for_status() rtt = (reply.time - request.time) * 1000 rtts.append(rtt) except ICMPLibError: pass return Host(address, packets_sent, rtts) async def async_ping(address, count=4, interval=1, timeout=2, id=None, source=None, family=None, privileged=True, **kwargs): ''' Send ICMP Echo Request packets to a network host. This function is non-blocking. :type address: str :param address: The IP address, hostname or FQDN of the host to which messages should be sent. For deterministic behavior, prefer to use an IP address. :type count: int, optional :param count: The number of ping to perform. Default to 4. :type interval: int or float, optional :param interval: The interval in seconds between sending each packet. Default to 1. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving a reply in seconds. Default to 2. :type id: int, optional :param id: The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every ping process. On Linux, this identifier is ignored when the `privileged` parameter is disabled. The library handles this identifier itself by default. :type source: str, optional :param source: The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. :type family: int, optional :param family: The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. :type privileged: bool, optional :param privileged: When this option is enabled, this library fully manages the exchanges and the structure of ICMP packets. Disable this option if you want to use this function without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. Advanced (**kwags): :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type traffic_class: int, optional :param traffic_class: The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. :rtype: Host :returns: A `Host` object containing statistics about the desired destination. :raises NameLookupError: If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the source address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs. See the `ICMPv4Socket` or `ICMPv6Socket` class for details. Usage:: >>> import asyncio >>> from icmplib import async_ping >>> host = asyncio.run(async_ping('1.1.1.1')) >>> host.avg_rtt 13.2 >>> host.is_alive True See the `Host` class for details. ''' if is_hostname(address): address = (await async_resolve(address, family))[0] if is_ipv6_address(address): _Socket = ICMPv6Socket else: _Socket = ICMPv4Socket id = id or unique_identifier() packets_sent = 0 rtts = [] with AsyncSocket(_Socket(source, privileged)) as sock: for sequence in range(count): if sequence > 0: await asyncio.sleep(interval) request = ICMPRequest( destination=address, id=id, sequence=sequence, **kwargs) try: sock.send(request) packets_sent += 1 reply = await sock.receive(request, timeout) reply.raise_for_status() rtt = (reply.time - request.time) * 1000 rtts.append(rtt) except ICMPLibError: pass return Host(address, packets_sent, rtts) icmplib-3.0.3/icmplib/sockets.py000066400000000000000000000613101417777567500166330ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' import socket, asyncio from struct import pack, unpack from time import time from .models import ICMPReply from .exceptions import * from .utils import PLATFORM_LINUX, PLATFORM_MACOS, PLATFORM_WINDOWS class ICMPSocket: ''' Base class for ICMP sockets. :type address: str, optional :param address: The IP address from which you want to listen and send packets. By default, the socket listens on all interfaces. :type privileged: bool, optional :param privileged: When this option is enabled, the socket fully manages the exchanges and the structure of the ICMP packets. Disable this option if you want to instantiate and use the socket without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the requested address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs while creating the socket. ''' __slots__ = '_sock', '_address', '_privileged' _IP_VERSION = -1 _ICMP_HEADER_OFFSET = -1 _ICMP_HEADER_REAL_OFFSET = -1 _ICMP_CODE_OFFSET = _ICMP_HEADER_OFFSET + 1 _ICMP_CHECKSUM_OFFSET = _ICMP_HEADER_OFFSET + 2 _ICMP_ID_OFFSET = _ICMP_HEADER_OFFSET + 4 _ICMP_SEQUENCE_OFFSET = _ICMP_HEADER_OFFSET + 6 _ICMP_PAYLOAD_OFFSET = _ICMP_HEADER_OFFSET + 8 _ICMP_ECHO_REQUEST = -1 _ICMP_ECHO_REPLY = -1 def __init__(self, address=None, privileged=True): self._sock = None self._address = address # The Linux kernel allows unprivileged users to use datagram # sockets (SOCK_DGRAM) to send ICMP requests. This feature is # now supported by the majority of Unix systems. # Windows is not compatible. self._privileged = privileged or PLATFORM_WINDOWS try: self._sock = self._create_socket( socket.SOCK_RAW if self._privileged else socket.SOCK_DGRAM) if address: self._sock.bind((address, 0)) except OSError as err: if err.errno in (1, 13, 10013): raise SocketPermissionError(privileged) if err.errno in (-9, 49, 99, 10049, 11001): raise SocketAddressError(address) raise ICMPSocketError(str(err)) def __enter__(self): ''' Return this object. ''' return self def __exit__(self, type, value, traceback): ''' Call the `close` method. ''' self.close() def __del__(self): ''' Call the `close` method. ''' self.close() def _create_socket(self, type): ''' Create and return a new socket. Must be overridden. ''' raise NotImplementedError def _set_ttl(self, ttl): ''' Set the time to live of every IP packet originating from this socket. Must be overridden. ''' raise NotImplementedError def _set_traffic_class(self, traffic_class): ''' Set the DS Field (formerly TOS) or the Traffic Class field of every IP packet originating from this socket. Must be overridden. ''' raise NotImplementedError def _checksum(self, data): ''' Compute the checksum of an ICMP packet. Checksums are used to verify the integrity of packets. ''' sum = 0 data += b'\x00' for i in range(0, len(data) - 1, 2): sum += (data[i] << 8) + data[i + 1] sum = (sum & 0xffff) + (sum >> 16) sum = ~sum & 0xffff return sum def _create_packet(self, id, sequence, payload): ''' Build an ICMP packet from an identifier, a sequence number and a payload. This method returns the newly created ICMP header concatenated to the payload passed in parameters. ''' checksum = 0 # Temporary ICMP header to compute the checksum header = pack('!2B3H', self._ICMP_ECHO_REQUEST, 0, checksum, id, sequence) checksum = self._checksum(header + payload) # Definitive ICMP header header = pack('!2B3H', self._ICMP_ECHO_REQUEST, 0, checksum, id, sequence) return header + payload def _parse_reply(self, packet, source, current_time): ''' Parse an ICMP reply from bytes. This method returns an `ICMPReply` object or `None` if the reply cannot be parsed. ''' # On Linux, the IP header is missing when a datagram socket is # used (SOCK_DGRAM). To keep the same behavior on all operating # systems including macOS which has this header, we add a # padding of the size of the missing IP header. if not self._privileged and PLATFORM_LINUX: packet = b'\x00' * self._ICMP_HEADER_OFFSET + packet bytes_received = len(packet) - self._ICMP_HEADER_OFFSET if len(packet) < self._ICMP_CHECKSUM_OFFSET: return None type, code = unpack('!2B', packet[ self._ICMP_HEADER_OFFSET: self._ICMP_CHECKSUM_OFFSET]) if type != self._ICMP_ECHO_REPLY: packet = packet[ self._ICMP_PAYLOAD_OFFSET - self._ICMP_HEADER_OFFSET + self._ICMP_HEADER_REAL_OFFSET:] if len(packet) < self._ICMP_PAYLOAD_OFFSET: return None id, sequence = unpack('!2H', packet[ self._ICMP_ID_OFFSET: self._ICMP_PAYLOAD_OFFSET]) return ICMPReply( source=source, family=self._IP_VERSION, id=id, sequence=sequence, type=type, code=code, bytes_received=bytes_received, time=current_time) def send(self, request): ''' Send an ICMP request message over the network to a remote host. This operation is non-blocking. Use the `receive` method to get the reply. :type request: ICMPRequest :param request: The ICMP request you have created. If the socket is used in non-privileged mode on a Linux system, the identifier defined in the request will be replaced by the kernel. :raises SocketBroadcastError: If a broadcast address is used and the corresponding option is not enabled on the socket (ICMPv4 only). :raises SocketUnavailableError: If the socket is closed. :raises ICMPSocketError: If another error occurs while sending. ''' if not self._sock: raise SocketUnavailableError try: sock_destination = socket.getaddrinfo( host=request.destination, port=None, family=self._sock.family, type=self._sock.type)[0][4] packet = self._create_packet( id=request.id, sequence=request.sequence, payload=request.payload) self._set_ttl(request.ttl) self._set_traffic_class(request.traffic_class) request._time = time() self._sock.sendto(packet, sock_destination) # On Linux, the ICMP request identifier is replaced by the # kernel with a random port number when a datagram socket is # used (SOCK_DGRAM). So, we update the request created by # the user to take this new identifier into account. if not self._privileged and PLATFORM_LINUX: request._id = self._sock.getsockname()[1] except PermissionError: raise SocketBroadcastError except OSError as err: raise ICMPSocketError(str(err)) def receive(self, request=None, timeout=2): ''' Receive an ICMP reply message from the socket. This method can be called multiple times if you expect several responses as with a broadcast address. :type request: ICMPRequest, optional :param request: The ICMP request to use to match the response. By default, all ICMP packets arriving on the socket are returned. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving the response in seconds. Default to 2. :rtype: ICMPReply :returns: An `ICMPReply` object representing the response of the desired destination or an upstream gateway. See the `ICMPReply` class for details. :raises TimeoutExceeded: If no response is received before the timeout specified in parameters. :raises SocketUnavailableError: If the socket is closed. :raises ICMPSocketError: If another error occurs while receiving. ''' if not self._sock: raise SocketUnavailableError self._sock.settimeout(timeout) time_limit = time() + timeout try: while True: response = self._sock.recvfrom(1024) current_time = time() packet = response[0] source = response[1][0] if current_time > time_limit: raise socket.timeout reply = self._parse_reply( packet=packet, source=source, current_time=current_time) if (reply and not request or reply and request.id == reply.id and request.sequence == reply.sequence): return reply except socket.timeout: raise TimeoutExceeded(timeout) except OSError as err: raise ICMPSocketError(str(err)) def close(self): ''' Close the socket. It cannot be used after this call. ''' if self._sock: self._sock.close() self._sock = None @property def sock(self): ''' Return the underlying socket (`socket.socket` object) or `None` if the socket is closed. This property should only be used if the feature you want is not yet implemented. Some changes made to this socket may cause unexpected behavior or be incompatible with later versions of the library. Prefer to use the other methods and properties defined within this class if possible. ''' return self._sock @property def blocking(self): ''' Indicate whether the socket is in blocking mode. Return a `boolean`. ''' return self._sock.getblocking() @blocking.setter def blocking(self, enable): return self._sock.setblocking(enable) @property def address(self): ''' The IP address from which the socket listens and sends packets. Return `None` if the socket listens on all interfaces. ''' return self._address @property def is_privileged(self): ''' Indicate whether the socket is running in privileged mode. Return a `boolean`. ''' return self._privileged @property def is_closed(self): ''' Indicate whether the socket is closed. Return a `boolean`. ''' return self._sock is None # Echo Request and Echo Reply messages RFC 792 # # 0 1 2 3 # 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Type | Code | Checksum | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Identifier | Sequence Number | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Data ... # +-+-+-+-+- # # ICMPv4 Error message RFC 792 # # 0 1 2 3 # 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Type | Code | Checksum | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Unused / Depends on the error | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Internet Header + 64 bits of Original Data Datagram | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ class ICMPv4Socket(ICMPSocket): ''' Class for sending and receiving ICMPv4 packets. :type address: str, optional :param address: The IP address from which you want to listen and send packets. By default, the socket listens on all interfaces. :type privileged: bool, optional :param privileged: When this option is enabled, the socket fully manages the exchanges and the structure of the ICMP packets. Disable this option if you want to instantiate and use the socket without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the requested address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs while creating the socket. ''' __slots__ = '_sock', '_address', '_privileged' _IP_VERSION = 4 _ICMP_HEADER_OFFSET = 20 _ICMP_HEADER_REAL_OFFSET = 20 _ICMP_CODE_OFFSET = _ICMP_HEADER_OFFSET + 1 _ICMP_CHECKSUM_OFFSET = _ICMP_HEADER_OFFSET + 2 _ICMP_ID_OFFSET = _ICMP_HEADER_OFFSET + 4 _ICMP_SEQUENCE_OFFSET = _ICMP_HEADER_OFFSET + 6 _ICMP_PAYLOAD_OFFSET = _ICMP_HEADER_OFFSET + 8 _ICMP_ECHO_REQUEST = 8 _ICMP_ECHO_REPLY = 0 def _create_socket(self, type): ''' Create and return a new socket. ''' return socket.socket( family=socket.AF_INET, type=type, proto=socket.IPPROTO_ICMP) def _set_ttl(self, ttl): ''' Set the time to live of every IP packet originating from this socket. ''' self._sock.setsockopt( socket.IPPROTO_IP, socket.IP_TTL, ttl) def _set_traffic_class(self, traffic_class): ''' Set the DS Field (formerly TOS) of every IP packet originating from this socket. Only available on Unix systems. Ignored on Windows. ''' # Not available on Windows if PLATFORM_WINDOWS: return self._sock.setsockopt( socket.IPPROTO_IP, socket.IP_TOS, traffic_class) @property def broadcast(self): ''' Indicate whether broadcast support is enabled on the socket. Return a `boolean`. .. note:: To enable broadcast support: icmp_socket.broadcast = True ''' return self._sock.getsockopt( socket.SOL_SOCKET, socket.SO_BROADCAST) > 0 @broadcast.setter def broadcast(self, enable): self._sock.setsockopt( socket.SOL_SOCKET, socket.SO_BROADCAST, enable) # Echo Request and Echo Reply messages RFC 4443 # # 0 1 2 3 # 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Type | Code | Checksum | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Identifier | Sequence Number | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Data ... # +-+-+-+-+- # # ICMPv6 Error message RFC 4443 # # 0 1 2 3 # 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Type | Code | Checksum | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Unused / Depends on the error | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # | Original packet without exceed the minimum IPv6 MTU | # +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ # Windows IPv6 compatibility if PLATFORM_WINDOWS: socket.IPPROTO_IPV6 = 41 socket.IPPROTO_ICMPV6 = 58 class ICMPv6Socket(ICMPSocket): ''' Class for sending and receiving ICMPv6 packets. :type address: str, optional :param address: The IP address from which you want to listen and send packets. By default, the socket listens on all interfaces. :type privileged: bool, optional :param privileged: When this option is enabled, the socket fully manages the exchanges and the structure of the ICMP packets. Disable this option if you want to instantiate and use the socket without root privileges and let the kernel handle ICMP headers. Default to True. Only available on Unix systems. Ignored on Windows. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the requested address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs while creating the socket. ''' __slots__ = '_sock', '_address', '_privileged' _IP_VERSION = 6 _ICMP_HEADER_OFFSET = 0 _ICMP_HEADER_REAL_OFFSET = 40 _ICMP_CODE_OFFSET = _ICMP_HEADER_OFFSET + 1 _ICMP_CHECKSUM_OFFSET = _ICMP_HEADER_OFFSET + 2 _ICMP_ID_OFFSET = _ICMP_HEADER_OFFSET + 4 _ICMP_SEQUENCE_OFFSET = _ICMP_HEADER_OFFSET + 6 _ICMP_PAYLOAD_OFFSET = _ICMP_HEADER_OFFSET + 8 _ICMP_ECHO_REQUEST = 128 _ICMP_ECHO_REPLY = 129 def _create_socket(self, type): ''' Create and return a new socket. ''' return socket.socket( family=socket.AF_INET6, type=type, proto=socket.IPPROTO_ICMPV6) def _set_ttl(self, ttl): ''' Set the time to live of every IP packet originating from this socket. ''' # Not available on macOS when the privileged param. is disabled if PLATFORM_MACOS and not self._privileged: return self._sock.setsockopt( socket.IPPROTO_IPV6, socket.IPV6_UNICAST_HOPS, ttl) def _set_traffic_class(self, traffic_class): ''' Set the Traffic Class field of every IP packet originating from this socket. Only available on Unix systems. Ignored on Windows. ''' # Not available on Windows if PLATFORM_WINDOWS: return # Not available on macOS when the privileged param. is disabled if PLATFORM_MACOS and not self._privileged: return self._sock.setsockopt( socket.IPPROTO_IPV6, socket.IPV6_TCLASS, traffic_class) class AsyncSocket: ''' A wrapper for ICMP sockets which makes them asynchronous. :type icmp_sock: ICMPSocket :param icmp_sock: An ICMP socket. Once the wrapper is instantiated, this socket should no longer be used directly. ''' __slots__ = '_icmp_sock' def __init__(self, icmp_sock): self._icmp_sock = icmp_sock self._icmp_sock.blocking = False def __getattr__(self, name): ''' Return the specified attribute of the underlying ICMP socket. ''' if not self._icmp_sock: raise SocketUnavailableError return getattr(self._icmp_sock, name) def __enter__(self): ''' Return this object. ''' return self def __exit__(self, type, value, traceback): ''' Call the `close` method. ''' self.close() def __del__(self): ''' Call the `close` method. ''' self.close() async def receive(self, request=None, timeout=2): ''' Receive an ICMP reply message from the socket. This method can be called multiple times if you expect several responses as with a broadcast address. This method is non-blocking. :type request: ICMPRequest, optional :param request: The ICMP request to use to match the response. By default, all ICMP packets arriving on the socket are returned. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving the response in seconds. Default to 2. :rtype: ICMPReply :returns: An `ICMPReply` object representing the response of the desired destination or an upstream gateway. See the `ICMPReply` class for details. Unlike the `reveive` method of synchronous ICMP sockets, the returned `ICMPReply` object does not specify the IP address of the host that replied to the request message. :raises TimeoutExceeded: If no response is received before the timeout specified in parameters. :raises SocketUnavailableError: If the socket is closed. :raises ICMPSocketError: If another error occurs while receiving. ''' if not self._icmp_sock or not self._icmp_sock._sock: raise SocketUnavailableError loop = asyncio.get_running_loop() time_limit = time() + timeout remaining_time = timeout try: while True: packet = await asyncio.wait_for( loop.sock_recv(self._icmp_sock._sock, 1024), remaining_time) current_time = time() if current_time > time_limit: raise asyncio.TimeoutError reply = self._parse_reply( packet=packet, source=None, current_time=current_time) if (reply and not request or reply and request.id == reply.id and request.sequence == reply.sequence): return reply remaining_time = time_limit - current_time except asyncio.TimeoutError: raise TimeoutExceeded(timeout) except OSError as err: raise ICMPSocketError(str(err)) finally: if isinstance(loop, asyncio.SelectorEventLoop): loop.remove_reader(self._icmp_sock._sock) def detach(self): ''' Detach the socket from the wrapper and return it. The wrapper cannot be used after this call but the socket can be reused for other purposes. ''' icmp_sock = self._icmp_sock if self._icmp_sock: self._icmp_sock = None return icmp_sock def close(self): ''' Detach the underlying socket from the wrapper and close it. Both cannot be used after this call. ''' if self._icmp_sock: self.detach().close() @property def is_closed(self): ''' Indicate whether the underlying socket is closed or detached from this wrapper. Return a `boolean`. ''' return self._icmp_sock is None icmplib-3.0.3/icmplib/traceroute.py000066400000000000000000000164221417777567500173410ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' from time import sleep from .sockets import ICMPv4Socket, ICMPv6Socket from .models import ICMPRequest, Hop from .exceptions import TimeExceeded, ICMPLibError from .utils import * def traceroute(address, count=2, interval=0.05, timeout=2, first_hop=1, max_hops=30, fast=False, id=None, source=None, family=None, **kwargs): ''' 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. :type address: str :param address: The IP address, hostname or FQDN of the host to reach. For deterministic behavior, prefer to use an IP address. :type count: int, optional :param count: The number of ping to perform per hop. Default to 2. :type interval: int or float, optional :param interval: The interval in seconds between sending each packet. Default to 0.05. :type timeout: int or float, optional :param timeout: The maximum waiting time for receiving a reply in seconds. Default to 2. :type first_hop: int, optional :param first_hop: The initial time to live value used in outgoing probe packets. Default to 1. :type max_hops: int, optional :param max_hops: The maximum time to live (max number of hops) used in outgoing probe packets. Default to 30. :type fast: bool, optional :param fast: When this option is enabled and an intermediate router has been reached, skip to the next hop rather than perform additional requests. The `count` parameter then becomes the maximum number of requests in the event of no response. Default to False. :type id: int, optional :param id: The identifier of ICMP requests. Used to match the responses with requests. In practice, a unique identifier should be used for every traceroute process. The library handles this identifier itself by default. :type source: str, optional :param source: The IP address from which you want to send packets. By default, the interface is automatically chosen according to the specified destination. :type family: int, optional :param family: The address family if a hostname or FQDN is specified. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first before searching for IPv6 addresses. Advanced (**kwags): :type payload: bytes, optional :param payload: The payload content in bytes. A random payload is used by default. :type payload_size: int, optional :param payload_size: The payload size. Ignored when the `payload` parameter is set. Default to 56. :type traffic_class: int, optional :param traffic_class: The traffic class of ICMP packets. Provides a defined level of service to packets by setting the DS Field (formerly TOS) or the Traffic Class field of IP headers. Packets are delivered with the minimum priority by default (Best-effort delivery). Intermediate routers must be able to support this feature. Only available on Unix systems. Ignored on Windows. :rtype: list[Hop] :returns: A list of `Hop` objects representing the route to the desired destination. The list is sorted in ascending order according to the distance, in terms of hops, that separates the remote host from the current machine. Gateways that do not respond to requests are not added to this list. :raises NameLookupError: If you pass a hostname or FQDN in parameters and it does not exist or cannot be resolved. :raises SocketPermissionError: If the privileges are insufficient to create the socket. :raises SocketAddressError: If the source address cannot be assigned to the socket. :raises ICMPSocketError: If another error occurs. See the `ICMPv4Socket` or `ICMPv6Socket` class for details. Usage:: >>> from icmplib import traceroute >>> hops = traceroute('1.1.1.1') >>> last_distance = 0 >>> for hop in hops: ... if last_distance + 1 != hop.distance: ... print('Some gateways are not responding') ... ... print(f'{hop.distance} {hop.address} {hop.avg_rtt} ms') ... ... last_distance = hop.distance 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 See the `Hop` class for details. ''' if is_hostname(address): address = resolve(address, family)[0] if is_ipv6_address(address): _Socket = ICMPv6Socket else: _Socket = ICMPv4Socket id = id or unique_identifier() ttl = first_hop host_reached = False hops = [] with _Socket(source) as sock: while not host_reached and ttl <= max_hops: reply = None packets_sent = 0 rtts = [] for sequence in range(count): request = ICMPRequest( destination=address, id=id, sequence=sequence, ttl=ttl, **kwargs) try: sock.send(request) packets_sent += 1 reply = sock.receive(request, timeout) rtt = (reply.time - request.time) * 1000 rtts.append(rtt) reply.raise_for_status() host_reached = True except TimeExceeded: sleep(interval) except ICMPLibError: break if reply: hop = Hop( address=reply.source, packets_sent=packets_sent, rtts=rtts, distance=ttl) hops.append(hop) ttl += 1 return hops icmplib-3.0.3/icmplib/utils.py000066400000000000000000000122021417777567500163140ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' import socket, asyncio from threading import Lock from sys import platform from os import getpid from re import match from random import choices from .exceptions import NameLookupError PID = getpid() PLATFORM_LINUX = platform == 'linux' PLATFORM_MACOS = platform == 'darwin' PLATFORM_WINDOWS = platform == 'win32' _lock_id = Lock() _current_id = PID def random_byte_message(size): ''' Generate a random byte sequence of the specified size. ''' sequence = choices( b'abcdefghijklmnopqrstuvwxyz' b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' b'1234567890', k=size) return bytes(sequence) def unique_identifier(): ''' Generate a unique identifier between 0 and 65535. The first number generated will be equal to the PID + 1. ''' global _current_id with _lock_id: _current_id += 1 _current_id &= 0xffff return _current_id def resolve(name, family=None): ''' Resolve a hostname or FQDN to an IP address. Depending on the name specified in parameters, several IP addresses may be returned. This function relies on the DNS name server configured on your operating system. :type name: str :param name: A hostname or a Fully Qualified Domain Name (FQDN). :type family: int, optional :param family: The address family. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first for compatibility reasons (A DNS lookup) before searching for IPv6 addresses (AAAA DNS lookup). :rtype: list[str] :returns: A list of IP addresses corresponding to the name passed as a parameter. :raises NameLookupError: If the requested name does not exist or cannot be resolved. ''' try: if family == 6: _family = socket.AF_INET6 else: _family = socket.AF_INET lookup = socket.getaddrinfo( host=name, port=None, family=_family, type=socket.SOCK_DGRAM) return [address[4][0] for address in lookup] except OSError: if not family: return resolve(name, 6) raise NameLookupError(name) async def async_resolve(name, family=None): ''' Resolve a hostname or FQDN to an IP address. Depending on the name specified in parameters, several IP addresses may be returned. This function relies on the DNS name server configured on your operating system. This function is non-blocking. :type name: str :param name: A hostname or a Fully Qualified Domain Name (FQDN). :type family: int, optional :param family: The address family. Can be set to `4` for IPv4 or `6` for IPv6 addresses. By default, this function searches for IPv4 addresses first for compatibility reasons (A DNS lookup) before searching for IPv6 addresses (AAAA DNS lookup). :rtype: list[str] :returns: A list of IP addresses corresponding to the name passed as a parameter. :raises NameLookupError: If the requested name does not exist or cannot be resolved. ''' try: if family == 6: _family = socket.AF_INET6 else: _family = socket.AF_INET loop = asyncio.get_running_loop() lookup = await loop.getaddrinfo( host=name, port=None, family=_family, type=socket.SOCK_DGRAM) return [address[4][0] for address in lookup] except OSError: if not family: return await async_resolve(name, 6) raise NameLookupError(name) def is_hostname(name): ''' Indicate whether the specified name is a hostname or an FQDN. Return a `boolean`. ''' pattern = r'(?i)^([a-z0-9-]+|([a-z0-9_-]+[.])+[a-z]+)$' return match(pattern, name) is not None def is_ipv4_address(address): ''' Indicate whether the specified address is an IPv4 address. Return a `boolean`. ''' pattern = r'^([0-9]{1,3}[.]){3}[0-9]{1,3}$' return match(pattern, address) is not None def is_ipv6_address(address): ''' Indicate whether the specified address is an IPv6 address. Return a `boolean`. ''' return ':' in address icmplib-3.0.3/media/000077500000000000000000000000001417777567500142455ustar00rootroot00000000000000icmplib-3.0.3/media/icmplib-logo.png000066400000000000000000000245331417777567500173370ustar00rootroot00000000000000PNG  IHDR8sRGB)IDATxEEH%tH=R%&Hҥ N?{ܲ{痝9so(@d 2 D"@d 2 D"30E E 0\(a`<=|G0/zVC:&ezv=x ?)N1,6s(c`+<$u:C FzΡβO =^t,h:KuD͑1vZ+υhQdu ]/jQsd| I:EӖυhQdy l*B=7ΡQ"]ǀ6F߷c;kOABa?{H9-Vq Q]q%4/@-ޕOz+]^%ugH(7t}j%25 $uW_:ݤNx+2P9:I $uq Q=q#-N#I˪Z$nӰT; ȯ=GT{e4U lb{g2+72PH1lNakJl'pe #x tBf`Z A& k->4 s'3R%P*} ^0iEPX_+WH õ`p۟e:tȏ' 4=}WUzDdij;~RfM QC#ӛlB 1Ի9X*+I8!lIK^6Sk˪UCNķwiyhǑ6)euO'j鵓Kzz}o@; >hӄI:!9e~:HZ^9x-dCjaթUJ. /YޏLI@ Py'$f ;䧖T瀣A#Ix*sauaDVQ=$6:)/4Km)i>8QifTٻٳ"*~- %QtغBoc+}y*S KZ5[<_P SNu4A͢Lk B5j~pp ^NiM[жՒ(]Us2r|LJ?#g=XVdN*%ZzTMfY"=fC(Jd&U rF/MσF; Jd.Y uؠ3wxh>%Jd 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D"@d 2 D~07>&3Эc<   f Q_GwxxlQn _灬Vfk( *l;#_%PX^ޣοPF2'>ZeOH׬rhgGRf&ԸQ*€F 48}{N|\W>foqD9OmM^q(>ItkYNl==#ix+Hax}VDa@6_U͉۫1 p>RTs.=Ȟ4{N/A$1cH[XE%ol8|ؘ#^˯YD7zq=<@IM}Oex=}sr8ܨU#1? ieV2 } /Mȟ67N:fŞ76O);Og1Q'[֭ovTw TڛUڍD4 :FZ2 7(*r9?JhC%=6uh͵Qg)V='_ (^T/blB3SO(Dؓ,s.mQF`6U~}Nۓr^ۇ7dt iCCݺ+[ܒ(ؑ, icr2afXuַ!ͭZ.wd V/ʞq}%:?GZ;U-~wm縶ny#d𹨋8*g9_ z~[=䝪3+=yg HѨ[DVNͥ:eVA$,^ڼ/o}l*[5tGvJݡC_PtМ6%8ԥ4*NfSxm=L:YOwgwd~T;n#z}ӣR(K+\,IM(<Ԫ3&8;oiͿNY @du)uJ}OW#+Zy[l\0h)& ,(OϚw O7,CW=Kv9EN'إ}7l愰B]MZBuO9wIM(}:.a~ rӣƔe&{Ӏ2ma-iÝsw|O1wwrb,}?ڙ!}#{H;P,Q.'H8YDr,˞W_Ѣv}bFd,ɫ%ȃN~<++)MaI ʣeFٷ_ˉӪ'Ah8i*wsB>NlAD |U3]WFρu]a>g8yxڗr w+/~8Yd%2g(py! :N\<k(){L{37 &e}CsHfYEUD1 (ӧ]'F&K t|K<̀-, _ tLU+-|^okUF~n}.z.Yf-nq8.'zgK{Z8Gכ|=>u27p^!wf2(VYD9Jim( Sݲ{崯ۭNF"=us_ اuuӗwR%Paпֵ?^P_s/iIot4[D}͝gd> dZ(|FW{iy0XW_: e^'?̙/ oS-AyVEQ ‚*S\S缈ݫ27tc ~J/P&kҮNKċk9}X94ؿdiCEWdЯBcU K!efE,]xtZtpv"2־(j_9!7>{Uc >7j3Din8Y2EA:0 yEVN'g˫rb*]HXҗguG$&?H/}K3:t=?;}'ww_A}/ 1؇`[Q2:yإ׊wDm=}>W  #i(U{U`@3MgUKCAa8;F/"S8خk#4p473 pG][DG֏F?Zh^8,cZ)ӧEÀ/AF 좥/`(shGlalRDէ"> (r\Ėҗ] 'Ku`#0(L!kf!~H^;v^eӒ`9m}=QTkϭKïp_!` n QookNz{NrD'Ud(li0+"[P3QKe{Vg9hK/:w@->M#J23]GBշy^eӠӧ/JF ֽ~*ʆyh?3mJDm&Ώ<`I^r%6#NWQ)OA#zQr20%DU:otC:]~,x9r몃N6eׂ+otXP_,nDXF7!:uf;@5gkpW-e専6\QPߕNlfYZtD(HF"-mq!3[@'\90k=Q'/AmL-D_#oonh٦ [֡B5 ; :#)ڈ <,5&tcX#:FfGFa5$5Dm+VH?j٣λ(X,U֦O3rY41MΞ 8;>=鳝9m"3:MNѻ}_^7S*렌2+F 蠡K9[4,^i`+Ph?VTrô۝o.*<hYd nUXKuD52f<ċl{g?)O\,_w(1h嵄.lE7XC}X#xp (t8 ZFv^GRCokċE1+Φ (K!~}+9ۤo Vw嵔/hd<Fa=a3N0h*ɬ~4}tBQoNb\mSY˓}TY׋j+/K#Z`TX$Xmw}!4;]i& 6zl*Sffku6u%fkkfP+q-:5tG6M퐡Tr.'Zqn:h,@~rXn#R au<2?&G,{Քa0(%9,:mD'o7@+dF^uLte0ڶF~@1:u/LC@Сf߁ ?,Mv噎Wz QF؍{ʹQ&`y6e0ӌ-No`u(7i&Ǝy"۹ޯk7H ,ʬ(С}P7-wt6Ag\Q.규)|В0D`?G|@?ٲ , +mW ^Z[Urq5z"xز7׾ee@#Dۀէ:̠,K-eK%:UcV* j̼D/sO#=i e*}ĖQf(DC j?PG|HtBu}h󯥷Hнj,}׌8=>(hbəX: ~D:u\d%Hr.,Wljw@KDz0'Aa~@Ԟ*yB)-hp+^?&'_XM{UE0~`W}0 -:؞ EN웴Z4s)$sC %mCe1,w Dm3<@%)>|Fi-OZ$ioPOd/uTge z EK@sRB3Iƣe$<X>p2>D2'ϸh&pAL=W``u ۰֮Ea=]^Ӥ- Dj20;<@/Mj.ٍGlO6hN |#ڲv5IH}ùeّ Іy`6QWW-wdžo^%=6"2g*:SDHkVlR"Ö4Jd5E{NZlWڳϐJ DR1HttZ4Cd)(NA*`%2G74,5Hr"$]l'Xk/i+ٌ1hZdh1!ffEf 6Q7j߂iA-lr6cҪL38 !{vj}f,'1@H) 酞ˆ534{`( D)/P3{Wbxu&opE| #y_55I˺IY[,`Aķl2[5"kDcU;f[WA#;5$u4jldw| ho=fCc!!^:XGI.JXhTC4=|'QYa阡?T{ʹjef@'-@ J>nt|jb20@QNdg@_7X>]E,Q&ĘӁ}!BW(305Iv9ꚔY*`;GkPxHlUu(^@Y$Zdz1|wHĀ:~ KWx铌/aڮ@f@n4&5.XdZZSP k'V9 jgl 郎H:Nq, wҸXw2%@?Jj|!M˯SF`hh=wpDZʀ~Sw$I˗Is k@3DKLuK(c`&LV,|ug4>}WE߇i @F:9`w.Q 9Gvupr^& 7 k[0*Kz9)Z},wUZ/)4x2O5G\>IQ>-%S*YI(@d 2 D"@d 2 D"r0Ia CIENDB`icmplib-3.0.3/setup.cfg000066400000000000000000000022471417777567500150140ustar00rootroot00000000000000[metadata] name = icmplib version = 3.0.3 description = The power to forge ICMP packets and do ping and traceroute. keywords = icmp, sockets, ping, multiping, traceroute, async, asyncio, ipv4, ipv6, python, python3 author = Valentin BELYN author_email = valentin-hello@gmx.com long_description = file: README.md long_description_content_type = text/markdown url = https://github.com/ValentinBELYN/icmplib license = GNU Lesser General Public License v3.0 license_file = LICENSE classifiers = Development Status :: 5 - Production/Stable Intended Audience :: Developers License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+) Operating System :: OS Independent Programming Language :: Python Programming Language :: Python :: 3 Programming Language :: Python :: 3 :: Only Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 Programming Language :: Python :: 3.9 Programming Language :: Python :: 3.10 Topic :: Software Development :: Libraries Topic :: Software Development :: Libraries :: Python Modules [options] packages = icmplib python_requires = >=3.7 icmplib-3.0.3/setup.py000066400000000000000000000017501417777567500147030ustar00rootroot00000000000000''' icmplib ~~~~~~~ The power to forge ICMP packets and do ping and traceroute. https://github.com/ValentinBELYN/icmplib :copyright: Copyright 2017-2022 Valentin BELYN. :license: GNU LGPLv3, see the LICENSE for details. ~~~~~~~ This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see . ''' from setuptools import setup setup(name='icmplib')