nsttraceroute — Generate Text, XML, KML and KMZ formats from the network traceroute utility.
nsttraceroute [
-m
ENTRY
| --mode ENTRY
] [
-i
ENTRY
| --interface ENTRY
] [ --trace-type ENTRY
] [
-p
PORT
| --port PORT
] [
-f
INTEGER
| --firsthop INTEGER
] [
-q
INTEGER
| --nqueries INTEGER
] [
-w
INTEGER
| --waittime INTEGER
] [ --maxttl INTEGER
] [ --squeries INTEGER
] [
-d
HOSTNAME|IPv4ADDR
| --host HOSTNAME|IPv4ADDR
] [ --pkt-len INTEGER
] [ --fqdn [true]|false
] [ --persist-xml [true]|false
] [ --force-cat [true]|false
] [ --additional-opts OPTION
] [ --keep [true]|false
] [ --tag ENTRY
] [ --annotation TEXT
] [ --line-width INTEGER
] [ --public-ipaddr-ref [true]|false
] [ --odir DIRECTORY
] [ --rdir DIRECTORY
] [
-h
[true]|false
| --help [true]|false
] [
-H
[true]|false
| --help-long [true]|false
] [
-v
[true]|false
| --verbose [true]|false
] [ --version [true]|false
]
The nsttraceroute script is primarily used with the NST distribution for generating both KML and KMZ documents derived from the traceroute command along with IPv4 Address Geolocations. A traceroute path is produced between the source host, intermediate gateways (hops) and the final destination host which have been successfully Geolocated.
There are several things to consider when using nsttraceroute:
To produce a KML or KMZ document which includes IPv4 Address Geolocations, an appropriate geolocation source for resolving IPv4 Addresses to latitude/longitude coordinates needs to be available.
Currently, the nsttraceroute script can perform geolocations using the "nstipgeolocate" utility which uses Geolocation sources from the GeoIP database: "GeoLiteCity.dat" courtesy of MaxMind, from the Hostip.info web site or from locally configured private IPv4 Address/Network latitude/longitude coordinate locations.
Here is a example of using nsttraceroute to produce a KMZ file to be used with Google Earth:
[root@probe ~]#nsttraceroute -m kmz -f 1 -w 1 -q 3 --rdir /tmp -d 'www.marist.edu' \--odir /mnt/cifs/kml --tag marist --fqdn
When using this script, there are two main stages involved in the production of the final results:
There is the data
production stage which is time consuming and produces
up to 3 XML files. These files end with the
extensions: .nsttraceroute.xml, .geoip.xml,
and .netint.xml. These three files contain
the necessary information to generate all of the various
output formats.
There is the formatting stage, which involves taking information from the various XML files produced in the data stage to produce the desired output. The formatting stage does not take much execution time.
When you run the nsttraceroute command without
the --persist-xml option, it runs through both
the data stage and the formatting
stage to produce the desired output. This has the
following behaviors:
It will take a long time to produce the desired output as the entire data production stage is run.
You will get different results as the underlying traceroute command will be invoked again most likely producing different times and routes.
By specifying the --persist-xml option
along with the --tag TAG option, you can
generate multiple output formats for the information produced by a
single invocation of the data production
stage. For example, the following generates both
a vaisala.traceroute.txt
and vaisala.kmz file using the results of the
same traceroute invocation:
[root@probe ~]# nsttraceroute -m text --persist-xml --tag vaisala -d www.vaisala.com
[root@probe ~]# nsttraceroute -m kmz --persist-xml --tag vaisala -d www.vaisala.com
[root@probe ~]# ls -l /var/nst/ntr/vaisala*
-rw-r--r-- 1 root root 11590 Aug 6 12:03 /var/nst/ntr/vaisala.geoip.xml
-rw-r--r-- 1 root root 183100 Aug 6 12:05 /var/nst/ntr/vaisala.kmz
-rw-r--r-- 1 root root 1668 Aug 6 12:03 /var/nst/ntr/vaisala.netint.xml
-rw-r--r-- 1 root root 12641 Aug 6 12:03 /var/nst/ntr/vaisala.nsttraceroute.xml
-rw-r--r-- 1 root root 1063 Aug 6 12:03 /var/nst/ntr/vaisala.traceroute.txt
[root@probe ~]#
If you run the above commands, you will notice that
the first invocation (which
produces vaisala.traceroute.txt) takes much
longer than the second invocation (which
produces vaisala.kmz). This occurs because
during the first invocation, the three XML
files
(vaisala.nsttraceroute.xml, vaisala.geoip.xml,
and vaisala.netint.xml) needed to be
created. Since, the --persist-xml option was
specified on both invocations, the second invocation used the
existing XML files in the production of
the vaisala.kmz file.
Since the --persist-xml option is almost
always used in conjunction with the --tag TAG
option, the resulting output will not be displayed
on stdout. If you want to force the output
to stdout, you will need to include
the --force-cat option as well:
[root@probe ~]# nsttraceroute -m kmz --persist-xml --tag vaisala -d www.vaisala.com
[root@probe ~]# nsttraceroute -m text --persist-xml --tag vaisala --force-cat
... Text output from traceroute is shown on stdout ...
[root@probe ~]#
The following command line options are available:
-m ENTRY] | [--mode ENTRY]
This option controls what the
nsttraceroute script will do. The following
modes are available: ("text",
"xml", "kml",
"kmz", "kml-maps" and
"kmz-maps"). If you specify
"xml" (the default), it will generate an
XML
(Extensible Markup Language) output format
from the results of running a traceroute
command. Specify "kml" to generate
KML (Keyhole
Markup Language) format output from the results of
running a traceroute command.
KML is a
XML-based language
schema for expressing geographic annotation and visualization on
existing or future Web-based, two-dimensional maps and
three-dimensional Earth browsers
(Geocoding). KML
was developed for use with Google
Earth. Specify "kmz" to generate a
KML document and then
compress it using the zip utility. It is best
to use the "kmz" mode when rendering
nsttraceroute results with Google
Earth. Specify "kml-maps" to
generate KML output for
use with Google Maps. This mode provides
less detailed description information and is more suitable for
rendering with the Google Maps
implementation. Specify "kmz-maps" to
generate a KML document
suitable for Google Maps and then compress
it using the zip utility. Specify
"text" for similar output as if you just ran
the traceroute command by itself.
-i ENTRY] | [--interface ENTRY]
Use this optional parameter to set the interface through which traceroute should send packets. By default, the interface is selected according to the routing table.
--trace-type ENTRY]
Set the trace type and method
used for traceroute with each probe. The
following trace types are available:
("tcp", "icmp",
"udp", "udplite" and
"udpinc"). "tcp" is the
default method and uses the TCP protocol
with the SYN flag set for each probe sent
out. Other trace type methods
include ICMP, UDP
and UDPLITE. Consult
the traceroute manual page for additional
information. Use the
"udpinc" trace type to
increment the destination port number for each probe. The
base port value for this trace
type can be set with the
"--port" option.
-p PORT] | [--port PORT]
For UDP
(--trace-type udp)
and UDPLITE
(--trace-type udplite) tracing, this
value specifies the destination port. The default value
for UDP
and UDPLITE is port:
53 (DNS). If the
traceroute UDPINC
(--trace-type udpinc) method is used,
traceroute will use the destination port
number as a base and will be incremented by each query. The
default base port value
for UDPINC tracing is:
10000. For ICMP
(--trace-type icmp) tracing, this value
specifies the
initial ICMP sequence
number which will be incremented by each query. The default
sequence value
for ICMP tracing is:
1. For TCP
(--trace-type tcp) tracing,
the port value specifies just the constant
destination port to connect to. A default value
for TCP tracing of
port: 80 (HTTP) is
used.
-f INTEGER] | [--firsthop INTEGER]
Use this optional parameter to set the TTL (time-to-live) or Hop value to start with. traceroute will start with 1 if the parameter is not specified. The default value is to start at the first Hop. The minimum value permitted is 1. The maximum value permitted is 64.
-q INTEGER] | [--nqueries INTEGER]
Use this optional parameter to set the number of sequential queries traceroute will use to probe each Gateway Address. The default value is 3 queries. The minimum value permitted is 1. The maximum value permitted is 10.
-w INTEGER] | [--waittime INTEGER]
Use this optional parameter to set the number of seconds traceroute will wait for a response from a query to each Gateway Address. The default value is 5 seconds. The minimum value permitted is 1. The maximum value permitted is 128.
--maxttl INTEGER]
Use this optional parameter to set the maximum number of hops (maximum TTL: time-to-live value) traceroute will probe. The default value is to stop at 30 Hops. The minimum value permitted is 1. The maximum value permitted is 128.
--squeries INTEGER]
Use this optional parameter to set the number of probe packets sent out simultaneously. Sending several probes concurrently can speed up traceroute considerably. The default value of 16 simultaneous probes is used. The minimum value permitted is 1. The maximum value permitted is 128.
-d HOSTNAME|IPv4ADDR] | [--host HOSTNAME|IPv4ADDR]
This is the destination host (IP Address or FQDN) for traceroute to track the route packets.
--pkt-len INTEGER]
Use this optional parameter to set the total size of the probing packet. The specified size can be ignored in some situations or increased up to a minimal value. The default size of 60 octets is used. The minimum value permitted is 1. The maximum value permitted is 9000.
--fqdn [true]|false]
Use this option to try to resolve each IP Address to its Fully Qualified Domain Name (FQDN).
--persist-xml [true]|false]
When this option is specified, the
XML files:
TAG.nsttraceroute.xml,
TAG.geoip.xml and
TAG.netint.xml will be persisted (kept)
and/or re-used. These files contain all of the information
necessary to generate any of the various output formats. If
these XML files already exist, they will be
used to generate the output specified by the "--mode
MODE" option. This makes the script run much quicker
and allows you to format the same data in a different
manner. You typically won't use the "--keep"
option when using this option but you are free to do so. If you
do include the "--keep" option, be aware that
only the newly generated files necessary to satisfy the request
will be kept.
--force-cat [true]|false]
If this option is specified, then the resulting
output file will be dumped to stdout
regardless of the settings of the other command line
options. This allows you to use the --tag
TAG, --keep, and
--persist-xml options without having to worry
about whether or not the final results will be dumped to the
stdout. This option is typically used in
combination with the --persist-xml and
--tag TAG option when you want to force the
output to be dumped to
stdout.
--additional-opts OPTION]
Use this optional parameter to set any additional traceroute options that have not been explicitly provided by the nsttraceroute command. Use double quotes around any provided traceroute options.
--keep [true]|false]
Some modes of operation require that intermediate
files be produced. Normally, these intermediate files are
automatically cleaned up by the script. If the
"--keep" option is specified, then both the
intermediate files and the final mode output file will be
preserved. If the "--keep" option is not
specified then the final generated mode output will be written
to standard out unless the "--tag NAME"
option is used. You will typically want to use the
"--tag NAME" and "--odir
DIR" options when specifying this
option.
--tag ENTRY]
This option is useful when you specify the
"--keep" option. This option sets the prefix
that appears at the start of each intermediate file
generated. For example, if you specify: "--mode kmz
--keep --tag test", they you will get the following
files generated: "test.traceroute.txt",
"test.nsttraceroute.xml",
"test.ip.txt",
"test.geoip.xml", and
"test.kmz". The files will appear under
the " /tmp" directory unless you use the
--odir DIR option to specify a different
output directory. If you omit this option (or specify "AUTO"),
a unique file name will be generated automatically. If you
specify a "--tag NAME" option without the
"--keep" option, then only the
corresponding "--mode" (i.e.,
Text, XML
or KMZ) file will be
generated. If you do not specify both the
"--tag NAME" and the "--keep"
options, then the corresponding "--mode"
(i.e., Text, XML
or KMZ) will be
generated to standard out.
--annotation TEXT]
Use this option to add an
"Annotation" to the
traceroute XML output and
maps. This is used to document the results for historical review
and analysis. Enclose the annotation in single or double quotes.
--line-width INTEGER]
Use this optional parameter to set the line width in pixels for connecting each route segment. This option only pertains to KML document creation. The minimum value permitted is 1. The maximum value permitted is 10.
--public-ipaddr-ref [true]|false]
Use this option to add a public
IP Address reference to the
KML document for access back to the
NST WUI. Detected
"hosts" and "gateways" can
then be used with the included NST
WUI IP networking tools
and utilities. This option only pertains to
KML document creation.
--odir DIRECTORY]
This script may need to generate intermediate files
before the final results are produced. This option enables one
to specify the output directory for files produced by this
script. If omitted, it defaults to:
"/var/nst/ntr". If this directory does not
exist it will be automatically created.
--rdir DIRECTORY]
By default, this script will look for its
associated resource files under:
"/usr/share/nsttraceroute". If these
resource files have been relocated on the file system, use this
option to specify the new location.
-h [true]|false] | [--help [true]|false]
When this option is specified, nsttraceroute will display a short one line description of nsttraceroute, followed by a short description of each of the supported command line options. After displaying this information nsttraceroute will terminate.
-H [true]|false] | [--help-long [true]|false]
This option will attempt to pull up additional
nsttraceroute documentation within a text based
web browser. You can force which browser we use setting the
environment variable TEXTBROWSER, otherwise,
we will search for some common ones.
-v [true]|false] | [--verbose [true]|false]
When you set this option to true, nsttraceroute will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.
--version [true]|false]
If this option is specified, the version number of the script is displayed.