Name

nsttraceroute — Generate Text, XML, KML and KMZ formats from the network traceroute utility.

Synopsis

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 ]

Description

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

Persisting XML Data

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 ~]# 

Note

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 ~]# 

Options

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.

Files

/usr/share/nsttraceroute

Directory containing resource files used by nsttraceroute.

Environment

TEXTBROWSER

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).

See Also

nstnewscript(l), Network Security Toolkit