echoping/SRC/echoping.1.in

.\" $Id$
.TH echoping 1 "November 22, 1996" "ECHOPING" "echoping"
.SH NAME
echoping \- tests a remote host with TCP or UDP

.SH SYNOPSIS
.B echoping
.RI [-4] 
.RI [-6] 
.RI [-v] 
.RI [-V] 
.RI [-r] 
.RI [-f fill] 
.RI [-t timeout] 
.RI [-c] 
.RI [-d] 
.RI [-u] 
.RI [-s size] 
.RI [-n number] 
.RI [-w delay] 
.RI [-h url]
.RI [-R] 
.RI [-i url] 
.RI [-p priority] 
.RI [-P tos] 
.RI [-C] 
.RI [-S] 
.RI [-A] 
.RI [-a] 
.RI [-m plugin] 
.B hostname
[:port]
[plugin options...]

.SH DESCRIPTION 
.LP
.B echoping
is a small program to test (approximatively) performances 
of a remote Internet host by sending it TCP "echo" packets. It can use other
protocols as well (HTTP - which makes it a good tool to test Web servers, UDP "echo", etc). 
.LP
.B echoping 
simply shows the elapsed time, including the time to set up the TCP 
connection and to transfer the data. Therefore, it is unsuitable to physical
line raw throughput measures (unlike bing or treno). On the other end, the 
action it performs are close from, for instance, a HTTP request and it is meaningful 
to use it (carefully) to measure Web performances.

.SH ARGUMENT
.IP hostname[:port]
Name (or address) of the server to test. For HTTP, you can specify a
port number. For HTTP and IPv6, you can use RFC 2732 syntax (you will
probably need to escape the brackets from the shell). The name can be
an IDN (Unicode domain name).

.SH OPTIONS
.IP -v
Verbose
.IP -V
Displays the compiled-in configuration of echoping. Useful for bug reports.
.IP -s\ nnn
Size of the data to send. Large values can produce strange results with
some echo servers.
.IP -n\ nnn
Numbers of repeated tests. With this option, you have also the
minimum, maximum, average and median time, as well as the standard
deviation. The median is the value such that half of the measures are
under it and the other half is above. When you measure highly
variables values, like it is often the case on the whole Internet,
median is better than average to avoid "extreme" values. You can check
the "value" of the average by looking at the standard deviation: very
roughly, if the standard deviation is more than the half of the
average, the average does not mean anything. (See a book about
statistics for the details: the reality is far more complicated.)
.IP -w\ nnn
Number of seconds to wait between two tests (default is one). On
systems which have usleep(), you can write it as a fractional number,
such as 3.14. Otherwise, use integers.
.IP -t\ nnn
Number of seconds to wait a reply before giving up. For TCP, this is the
maximum number of seconds for the whole connection (setup and data exchange).
.IP -u
Use UDP instead of TCP
.IP -d
Use the "discard" service instead of echo
.IP -c
Use the "chargen" service instead of echo
.IP -h\ url
Use the HTTP protocol (instead of echo) for the given URL. If the
hostname is the Web server, the URL has to
be a relative one (for instance '/' or '/pics/foobar.gif') because HTTP 1.0
servers will not understand a request for an absolute URL. If the
hostname is a proxy/cache like Squid, the URL has to
be an absolute one.
.IP -R 
Accept HTTP status codes 3xx (redirections) as normal responses (the
default is to regard them as errors)
.IP -i\ url
Use the ICP protocol (instead of echo) for the given URL. The URL has to
be an absolute one. This is mostly for testing Squid Web proxy/caches.
.IP -A
Force the proxy (if you use one) to ignore the cache
.IP -a
Force the proxy (if you use one) to revalidate data with the original server
.IP -C
Use the SSL/TLS (cryptography) protocol. For HTTP tests only.
.IP -S
Use the SMTP protocol (instead of echo) for the given server.
.IP -r
Use T/TCP (if it has been compiled with it). See the INSTALL file for details.
.IP -4
Use only IPv4 (even if the target machine has an IPv6 address)
.IP -6
Use only IPv6 (even if the target machine has an IPv4 address)
.IP -f\ character
Fill the packet with this character (default is random filling)
.IP -p\ n
Send packets with the socket priority to the integer
.IR n .
The mapping of the socket priority into a network layer or a link
layer priority depends upon the network protocol and link protocol
in use.  For more details see
.B SO_PRIORITY
in
.BR socket(7).
.IP -P\ n
Set the IP type of service octet in the transmitted packets to the
least significant eight bits of the integer
.IR n .
See
.BR ip(7) 
or
.BR ip(4) 
(depending on your Unix). /usr/include/netinet/ip.h may contain
interesting constants for setting Type Of Service.
.IP -m\ plugin
Load the given plugin. The plugin is first
searched in the normal library directories (see 
.BR ld.so(8)
) then in @plugins_dir@. You can type 
.BR ls
in @plugins_dir@ to get an idea of the available plugins. The documentation for a
given plugin is in 
.BR echoping_PLUGINNAME(1)
The plugin-specific options appear
.B after
the hostname.
.SH EXAMPLES
.IP echoping\ \-v\ foobar.example.com
Tests the remote machine with TCP echo (one test).
.IP echoping\ \-n\ 5\ \-w\ 10\ foobar.example.com
Tests the remote machine with TCP echo (five tests, every ten seconds).
.IP echoping\ \-h\ /\ foobar.example.com
Tests the remote Web server and asks its home page. Note you don't
indicate the whole URL.
.IP echoping\ \-h\ http://www.example.com/\ cache.example.com:3128
Tests the remote Web proxy-cache and asks a Web page. Note that you must
indicate the whole URL.
.IP echoping\ -n\ 3\ -m\ whois\ foobar.example.com\ -r\ tao.example.org
Loads the whois plugin and query the host foobar.example.com. "-r
tao.example.org" are options specific to the whois plugin.
.IP echoping\ -u\ \-P\ 0xa0\ foobar.example.com
Sends several UDP Echo packets with an IP Precedence of 5.
.SH IP TYPE OF SERVICE OCTET
The IP packet header contains 8 bits named the "type of service octet".
The value of the octet is set with the
.B \-P
option.  The effects of the octet are defined differently in RFC791
.I "Internet Protocol"
and RFC2474
.IR "Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers".

RFC791 defines
.I Precedence
which has ascending priorities 0 through to 7, and the bits
.IR Delay ,
.IR Throughput ,
.IR Reliability ,
and
.I Cost
which indicates the application's preference for the properties of
the packet's path through the network.
.I Precedence
is in the most significant three bits of the type of service octet,
followed in decending significance order by the
.IR D ,
.IR T ,
.I R
and
.I C
bits.  The least significant bit must be zero.  Only one of the
.IR D ,
.IR T ,
.I R
or
.I C
bits may be set.

RFC2474 defines the Distributed Services Code Point, or
DSCP.
This acts as a selector between 64 possible behaviours that the
network can apply to the packet.  The
.I DSCP
is in the most significant six bits of the type of service octet.
The remaining least significant two bits of the octet must be
zero.

The numeric arguments to
.B -p
and
.B -P
can be in decimal (such as 11), octal (such as 013) or hexadecimal
(such as 0x0b).  So padding decimal arguments with leading zeros will
change the value read.

You may need to be superuser to set some 
.B -p
or
.B -P
values (precedence on Linux, for instance).

.SH BUGS

See the TODO file or SourceForge bug tracking system at
<http://sourceforge.net/bugs/?group_id=4581>.

.SH SEE ALSO
See the README for information about other network measurements programs.

.SH FILES
.IP "\fB@plugins_dir@ \fR" 4
Plugins directory

.SH AUTHOR
Stephane Bortzmeyer <bortz@users.sourceforge.net>