STING PING (SPING) README ------------------------- $Id: README 149 2007-10-31 04:55:43Z szander $ OVERVIEW -------- sping is a tool for pinging hosts and measuring hop count and round trip time (RTT) to the pinged host. It can also perform reverse DNS lookups for the specified IP addresses. Pinging ------- sping can ping hosts using ICMP ECHO packets, as well as sending TCP SYNs on configurable ports. To have full control of the packets sent sping uses raw sockets. For each host pinged sping runs through up to three phases: 1) Ping host Send a number of probes to the host until it responds. First sping will send an ICMP ECHO packet, then TCP SYN packets on the configured ports. The probing is sequentially, sping will always send a probe and then wait for an answer or a timeout before sending the next probe. sping uses the default time-to-live (TTL) for probe packets in this phase. If sping is executed with the one-shot option (-o), it stops after receiving a response or a timeout. Otherwise, it proceeds to phase 2 and 3. 2) Confirm number of hops If a response was received in phase 1 sping estimates the number of hops based on the reply packet's TTL value and typical initial TTL values. It then tries to confirm the estimate by pinging the host again with the probe's TTL set to estimated number of hops + 1, using the same type of probe that generated a response in phase 1. Normally, the host should respond. If it does not, the first estimate of the hop count was wrong and sping will continue to probe the host with TTL increased by one and so on, until a response is received. (A more efficient search method is work in progress.) 3) Identify gateway Ping host again with TTL set to estimated number of hops. This should cause the host's gateway to respond with an ICMP TTL exceeded response, which allows sping to record the gateway's IP address. sping can perform many subsequent pings if necessary. The -c option can be used to specify the number of pings per pinged hosts. The option is useful if one wants to measure reachability and/or RTT over some time. The -i option can be used to specify the time between pings in seconds, and hence also the timeout. The -t option can be used to specify a different timeout for the first ping (by default the -i value will be used for the first ping). The -P option can be used to specify whether sping shall use ICMP, TCP or both for probing. If TCP probing is used the -p option can be used to specify a list of ports. The -s option can be used to specify the source port for TCP probing. To probe addresses of a specified subnet in bit-reverse order use the -x switch. To probe addresses of a specified subnet in random order use the -y switch (this feature hasn't been tested sufficiently and is considered experimental). The -I switch allows to explicitly specify the outgoing interface. sping tries to guess the interface (usually it will use the first available interface), but with the -I switch it can be forced to use a specific interface. (The reason for the existence of this switch is that sping uses raw sockets.) The IPv4 addresses or networks to be pinged are specified at the end of the command line after all options. Alternatively, they can be specified in a file. Destinations file ----------------- A destinations file is a text file with as many rows as destinations. Each row has three columns: destination IP, protocol ("icmp", "tcp", "both" or "-"), and a comma-separated list of ports for TCP or "-". "-" means use the values from the command line options -P and -p or if these are not specified sping will use ICMP and TCP, and ping TCP port 22 only. The following is shows an example destinations.txt: --------------------------- 192.168.10.1 - - 192.168.10.2 - - 192.168.10.3 tcp 22,80,1111 --------------------------- Reverse DNS ----------- After the pinging is complete sping performs a reverse DNS lookup to get the DNS name for the pinged host, unless reverse DNS is disabled with the -n option (or sping was compiled without libadns). sping can be used solely for obtaining reverse DNS names. If the -O option is used sping will not ping, but only do reverse DNS lookups. Filtering --------- If the -D option is used to specify a delegated file, sping will only ping IP addresses that have been allocated (according to the RIR's delegated data). Each line of the delegated file has the following format: apnic|AU|ipv4|1.0.0.0|256|20110811|allocated Column 4 specifies the first IPv4 address of a network and column 5 specifies the number of addresses the network has. Other columns are not used by sping, please refer to the definition of delegated files for a full explanation of the format. The combined delegated file can be downloaded for example from here: http://bgp.potaroo.net:/stats/nro/delegated The -u option can be used to ping unallocated addresses if a delegated file is specified with -D. The -E option allows to specify IP addresses (networks) that are never pinged. Currently, the format is the same as the delegated file (again only column 4 and column 5 are actually used by sping). By default sping will not ping private (e.g. 10.0.0.0/8) or multicast/experimental address ranges (224.0.0.0 -- 255.255.255.255). Using the -d option allows to ping these. The exclusion list can be updated during runtime by sending a SIGHUP to sping. The delegated list cannot be updated at runtime currently. The -S option can be used to ping a uniform random sample of all IPv4 addresses specified. Notes ----- sping computes the RTT based on the kernel packet timestamps of the probe packet sent and the corresponding answer packet received. Note that sping can only get the kernel timestamps for sent packets if compiled with pcap support (see INSTALL). Without pcap it will simple use sent timestamps taken in userspace when the send() system call is invoked. sping can ping and/or reverse DNS many hosts in parallel. To not overwhelm the network with traffic sping has some limitations on how many hosts it pings at a time. These limits sping has some limitations on how many hosts it pings at a time. These limits sping has some limitations on how many hosts it pings at a time. These limits are currently not configurable, but constants can be changed in the source code. As said above, sping probes each host sequentially meaning it sends a probe packet, waits for an answer or a timeout to occur. If there was no answer it will send the next probe packet and so on. sping also performs a reverse DNS lookup and outputs the DNS name for a pinged host (if any). sping does not support IPv6. Output ------ The output of sping looks like this if the destination responds: 192.168.10.42 192.168.10.42 myserver.example.com icmp 468,456 63 1 192.168.0.1 255 0 The fields are pinged IP, responding IP, DNS name, responding protocol and port, round-trip-times (in micro seconds), TTL of response at pinging host and estimated hop count, gateway IP (different subnet) or "local" (same subnet), TTL of Time-to- live exceed message from gateway and estimated hop count to gateway. If a destination does not respond the output looks like this: 192.168.10.42 - myserver.example.com noresp The first three fields are the pinged IP, responding IP, and DNS name as above. The last field is a short error string, which is based on an error number (running sping with -r option results in getting the numbers instead of strings). If an ICMP Destination Unreachable message was received the error number is the ICMP error code (ranging from 0--15). Otherwise, if there was no response and no ICMP Destination Unreachable message the error code is 16. If sping is compiled without DNS (libadns) it will always return "-" as DNS name. The -r option can be used to produce a shorter version of the output. By default sping outputs the results for responding and non-responding hosts. If the -N option is used sping will only output the results for responding hosts (note that responding here means the host may send a ping reply or an ICMP error). The -v option can be used to get more output, including debug output. PACKAGE CONTENTS ---------------- The directory structure is: sping-0.1/. Makefiles and documentation sping-0.1/sping Source code and man page EXAMPLE USAGE ------------- Running sping requires root permissions. Ping IP address 192.168.10.42 using ICMP and TCP (port 22 and 80): # sping -P both -p 22,80 -v 192.168.10.42 Ping a whole /24 subnet with ICMP and TCP: # sping -P both -p 22,80 -v 192.168.10.0/24 Ping all IP addresses specified in destinations.txt with ICMP and TCP: # sping -P both -p 22,80 -v destinations.txt Perform only reverse DNS lookups for specified destinations: # sping -O destinations.txt Ping all allocated IPv4 addresses (except the excluded ones) with ICMP in bit-reverse order and only output data for responding IPs in short form (no reverse DNS): # sping -i 1 -t 2 -D delegated -E excluded.txt -P icmp -r -n -N -o -x 0.0.0.0/0 LICENSE ------- Copyright (c) 2011-2012 Centre for Advanced Internet Architectures, Swinburne University of Technology. Author: Sebastian Zander (szander@swin.edu.au) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. 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 General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ACKNOWLEDGEMENTS ---------------- Parts of the code are based on the tool cprobe developed by Sebastian Zander (http://caia.swin.edu.au/cv/szander/cprobe/skew_probing.html). The code for reading delegated data and performing IP lookups against it is based on Net-Patricia (net.doit.wisc.edu/~plonka/Net-Patricia) written by Dave Plonka, which is partially based on code from MRT developed by the University of Michigan, Merit Network, Inc., and their contributors. CONTACT ------- If you have any questions or want to report any bugs please contact Sebastian Zander (szander@swin.edu.au). Centre for Advanced Internet Architectures Swinburne University of Technology Melbourne, Australia CRICOS number 00111D http://www.caia.swin.edu.au