.TH NETSELECT 1 "March 14, 2004" "DEBIAN" \" -*- nroff -*-
.\" Please adjust this date whenever revising the manpage.

.SH NAME
netselect \- choose the fastest server automatically

.SH SYNOPSIS

.B netselect
.RB [ \|\-v\| | \|\-vv\| | \|\-vvv\| | \|\-vvvv\| ]
.\".RB [ \|\-vv\| ]
.RB [ \|\-m
.IR HOPS ]
.RB [ \|\-s
.IR SERVERS\| ]
.RB [ \|\-t
.IR PACKETS\| 
.RB [ \|\-I ]
.RB [ \|\-D ]
.RB [ \|\-4 | \|\-6 ]
.IR host \ ...

.SH DESCRIPTION

.B netselect
determines several facts about all of the hosts given on the command
line, much faster than you would if you manually tried to use
.B ping
and
.BR traceroute .

For each
.IR host ,
.B netselect
figures out the approximate
.B ping
time (though not as accurately as
.B ping
does), the number of network "hops" to
reach the target, and the percentage of
.B ping
requests that got through successfully. Then
.B netselect
calculates the "score" of each operational
.I host 
based on these values.  A lower score is better, in the end it prints
one line showing the server with the best score.

If the DNS name has multiple IP addresses associated with IT
.B netselect
will test each of the IP addresses independently. In this case, 
.B netselect
will report the IP address of the fastest server (unless the \-D option
is used).

If the number of found hosts is not the same as the number requested 
(using \-s),
.BR netselect
will emit a warning message. If no hosts are found at all, the program
will also end with an error return value.

.SH EXAMPLES

.nf
\fB#\fR netselect \-vv ftp.fceia.unr.edu.ar ftp.kulnet.kuleuven.ac.be \\
		 ftp.cdrom.com ftp.debian.org ftp.de.debian.org
.fi

This is the output:

.nf
ftp.fceia.unr.edu.ar         2792 ms  23 hops  100% ok ( 1/ 1) [ 9213]
ftp.kulnet.kuleuven.ac.be    9999 ms  30 hops    0% ok
ftp.cdrom.com                  94 ms   8 hops  100% ok (10/10) [  169]
ftp.debian.org                 46 ms  15 hops  100% ok (10/10) [  115]
ftp.de.debian.org            9999 ms  30 hops    0% ok
  115 ftp.debian.org
.fi

The value in brackets is the "score" of each operational host based on these
values.  A lower score is better.  The last line shows the server with the
best score.  If we had not used '\-vv' on the command line, only this last
line would have been printed.

Note that for ftp.kulnet.kuleuven.ac.be and ftp.de.debian.org in this case,
nothing got through at all.  That indicates that either the host doesn't
exist, or it is down.


.nf
\fB#\fR netselect \-vv http.us.debian.org
.fi

This is the output:

.nf
204.152.191.39               300 ms  17 hops   90% ok ( 9/10) [  899]
35.9.37.225                  9999 ms  30 hops    0% ok
64.50.233.100                9999 ms  30 hops    0% ok
128.30.2.36                  183 ms  15 hops   90% ok ( 9/10) [  510]
149.20.20.135                226 ms  18 hops   90% ok ( 9/10) [  702]
  510 128.30.2.36
.fi

In this case, since the single name has multiple DNS addresses all of the
servers will be tested independently and the fastest server will be provided.

If you notice the above output you will see that the time for some hosts
is 9999 ms. This is typically an indication of remote hosts blocking the
UDP probes 
.B netselect
relies on. To prevent this issue you can use ICMP tests. For example,
repeating the above test using ICMP, that is:

.nf
\fB#\fR netselect \-I \-vv http.us.debian.org
.fi

yields the following output:

.nf
204.152.191.39               291 ms  17 hops  100% ok (10/10) [  785]
35.9.37.225                  180 ms  19 hops   66% ok ( 2/ 3) [  783]
64.50.233.100                140 ms  12 hops  100% ok (10/10) [  308]
128.30.2.36                  182 ms  15 hops  100% ok (10/10) [  455]
149.20.20.135                227 ms  18 hops  100% ok (10/10) [  635]
  308 64.50.233.100
.fi

In this last example the selected server will change since, actually, the
fastest server is one that also actively blocks UDP probes.

You can also use the tag feature based on postpending the server name with
itself so the result includes 
.BR both
the fastest IP address and the original server name. For example,
running a query with tags such as this one:

.nf
\fB#\fR netselect \-I \-vv http.us.debian.org:http.us.debian.org
.fi

will yield output similar to:

.nf
35.9.37.225:http.us.debian.org        9999 ms  30 hops    0% ok
64.50.233.100:http.us.debian.org      9999 ms  30 hops    0% ok
64.50.236.52:http.us.debian.org       9999 ms  30 hops    0% ok
128.30.2.36:http.us.debian.org         189 ms  14 hops   90% ok ( 9/10) [  504]
199.6.12.70:http.us.debian.org         286 ms  17 hops   90% ok ( 9/10) [  858]
  504 128.30.2.36:http.us.debian.org
.fi

Or you can use the \-D option to force 
.BR netselect
to print out only DNS names. For example:

.nf
\fB#\fR netselect \-I \-vv -D ftp.us.debian.org ftp.ru.debian.org
.fi

will yield output similar to:

.nf
128.30.2.36                  186 ms  14 hops  100% ok (10/10) [  446]
199.6.12.70                  294 ms  17 hops   87% ok ( 7/ 8) [  907]
35.9.37.225                  177 ms  19 hops   66% ok ( 2/ 3) [  768]
64.50.233.100                141 ms  12 hops  100% ok (10/10) [  310]
64.50.236.52                 162 ms  13 hops  100% ok (10/10) [  372]
ftp.ru.debian.org            112 ms  18 hops  100% ok (10/10) [  313]
  310 ftp.us.debian.org
.fi

As you can see here, 
.BR netselect
will select a DNS name (in the example 'ftp.us.debian.org') which associated
with multiple IP addresses over other servers as long as there is one
server in the pool faster than others. However, using the DNS name
for a server configuration might lead to actually slower throughput if,
on average, the different IP addresses are not as responsive. In
the above example, 'ftp.ru.debian.org' is second on the list and might be
a better option (again, on average) than 'ftp.us.debian.org'.

.SH OPTIONS
.TP
.B \-v
Verbose mode.  Displays nameserver resolution messages to stderr.  You
probably want this so that you don't get bored waiting for a hundred
name resolutions to finish.

.TP
.B \-vv
Very verbose mode.  Displays nameserver resolution and statistics (not
just scores) to STDERR and STDOUT.

.TP
.B \-vvv
Very very verbose mode.  Everything \-vv prints, plus it print every
packet received as it happens.  Good for debugging or trying to figure
out how it works.

.TP
.B \-vvvv
Very very very verbose mode.  Everything \-vvv prints, plus a trace of
all packets sent.

.TP
.BI \-m\  HOPS
Maximum TTL (time to live).  Don't accept hosts that are further than
.I HOPS
away.

.TP
.BI \-s\  SERVERS
Print this many "top-scoring"
.I SERVERS
at the end of the list.  If
.I SERVERS
is 0, then this disables printing of high scores.

.TP
.BI \-t\  PACKETS
Make sure at least 50% of the hosts get tested with this many
.IR PACKETS .
The more packets you use, the more accurate are the results... and the
longer it takes to run.  The default is 10, which is usually okay.

.TP
.BI \-I
Use ICMP instead of UDP probes. On some occasions (e.g. firewalled hosts)
UDP probes like those used in
.BR traceroute 
will get filtered out and hosts might be perceived as dead. Using this
option will make 
.BR netselect
use ICMP probes instead. 

.TP
.BI \-D
.BR netselect 
provides the IP address of the servers that are tested if the
name resolves to more than one address (i.e. the remote end is using
DNS round-robin). This makes it easier to spot which is the fastest
server of a pool but might not be useful if you wish to configure
a system daemon with the DNS name or if the remote service does not
accept calls to its IP address (as some HTTP servers do). This option
forces 
.BR netselect
to present the final server list using the original DNS name instead
of the IP address if the DNS name resolves to more than one IP address.

.TP
.BI \-4
Restrict address lookups to IPv4 only.

.TP
.BI \-6
Restrict address lookups to IPv6 only.

.SH SEE ALSO
.BR ping (8),
.BR traceroute (8),
.BR netselect-apt (1).

.SH AUTHOR
Avery Pennarun <apenwarr@gmail.com>