
			     DOMTOOLS USER MANUAL
		       HIGH-LEVEL NAME SERVER QUERY TOOLS
				 Version 1.5.0
				  01/02/2000
		      Copyright (c) 1993 by Paul A. Balyoz


INTRODUCTION

The commands in this directory allow you to traverse DNS domain hierarchies,
list all hosts (or subdomains) within a given domain, convert host name to
IP address and vice-versa, convert a normal IP address to the "in-addr.arpa."
format and vice-versa, and more.   These commands can be used manually, or
included as building blocks for higher level DNS tools.  Some higher level
tools are included as well; all are described below.


COPYRIGHT NOTICE

The Domtools software package and all scripts, programs and documentation
therein is Copyright (c) 1993 by Paul A. Balyoz, all rights reserved.
You are hereby given permission to run this version of this package
so long as you do not sell it or claim that you wrote it.
All copyright messages must be retained as-is.


EXIT VALUES, OUTPUTS, AND FQDNS

All of the following tools take their input on the command line, and generate
output to stdout.  All of them exit with status 0 upon success, and non-zero
if they fail.  Also, upon failure, the text string "ERROR" is usually output.
Note that the return string may not be enough to determine that an error
occurred for some commands; the exit status should be checked to make sure,
because some tools might generate an actual answer output of "ERROR" for one
reason or another.  All fully qualified domain names (fqdns) used by these
tools will end with a period ("."), which the "ERROR" output does not have.

Unless otherwise specified, all domain names on input are expected to have
a period (".") on the end, and all domain names on output will be the same.


TOOL CATEGORIES

These tools are grouped by level, where level 1 is the lowest.

Level 1	 Basic function tools that compute netmasks, perform address format
	 conversions, and other manipulations that require no name-server usage.

Level 2	 Tools that do simple domain record lookups using dig(1) to get
	 resource records such as A, SOA, NS, PTR, HINFO, TXT, etc.
	 Some tools in this category such as "root" and "netname" appear to have
	 greater functionality, but are really just doing basic queries.
	 Some of these tools have to use other tools in this level.

Level 3	 These tools are complex beasts similar to doc(1) in their capability
	 and output format.  They can often take a long time to run, and
	 lack the ability to recover from some kinds of low-level errors.

The tools from these levels are described in detail below.
To use any of them you must install all of them due to interdependency.


---------------------
--- Level 1 Tools ---
---------------------

NOTE: The localad and localdom tools in this section allow
an optional "@nameserver" argument if you want to force one particular
nameserver to receive all DNS queries.  This is important when running
Domtools behind a firewall, because many of the commands try to talk
directly to authoritative nameservers by default.


addr2mask			Example: addr2mask 134.114.64.5
				Outputs: 255.255.0.0
Returns the default netmask for the IP address given, based on whether the
address is class A, B, or C.  The range of the first octet of the IP
address gives it away:

		IP Range	Netmask		Class
		  1 - 127	255.0.0.0	  A
		128 - 191	255.255.0.0	  B
		192 - 223	255.255.255.0	  C

RFC1101 subnetting resource-records are ignored by this tool.

"ERROR" is returned for any other type.  That is, the first octet must be
within the range 1 through 223 or it is an error.  The network may actually
be subnetted, in which case the netmask would be different than what you get
back from this function.  (See the "netmask" function for help in this case).
If usage is incorrect, a usage message is printed on stderr, with the usual
"ERROR" on stdout.


addr2net			Example: addr2net 134.114.64.5 255.255.255.0
				Outputs: 134.114.64.0
Returns the network portion of the IP address given.  You must pass in the
netmask you want to mask with.  You can derive an appropriate netmask via
the "netmask" or "addr2mask" routines (described elsewhere in this document).
There must be exactly two arguments, each of which must be full 4-octet
decimal values separated by periods, otherwise "ERROR" is returned.


f2iaddr				Example: f2iaddr 134.114.64
				Outputs: 64.114.134.in-addr.arpa.
Returns the inverse address domain name of the network or host IP address
supplied.  This output is always in the "in-addr.arpa." domain.  All octets
are simply reversed and ".in-addr.arpa." is appended to the end.  If usage is
incorrect, a usage message is printed on stderr, with the usual "ERROR" on
stdout.  If any internal error occurs, only "ERROR" is sent to stdout.
The name is short for "forward to inverse address conversion".
The reverse of f2iaddr is i2faddr.


i2faddr				Example: i2faddr 12.64.114.134.in-addr.arpa.
				Outputs: 134.114.64.12
Returns the normal IP network or host address of the inverse one supplied.
Works for network addresses and host addresses.  The ".in-addr.arpa." part
is removed, and then the octets are simply reversed.  If usage is incorrect,
a usage message is printed to stderr, with the usual "ERROR" on stdout.
If any internal error occurs, only "ERROR" is sent to stdout.
The name is short for "inverse to forward address conversion".
The reverse of i2faddr is f2iaddr.


type			Example: type nau.edu.
			Outputs: domain
This command examines whatever network string you hand it and returns one
word describing the type of thing it is.  There are three kinds of things
that this command can distinguish between:

    Type of thing		 Example		Output
    ---------------------------	 ---------------------	-------
    forward IP address		 134.114.64.24		forward
    inverse IP in domain form	 114.134.in-addr.arpa.	inverse
    fully qualified domain name	 pine.cse.nau.edu.	domain


isequal			Example: isequal cse.nau.edu. CSE.Nau.Edu.
			Outputs: true
This command does a case insensitive compare of two strings passed to it.
This can be used to compare domain names, hostnames, or other items which
may differ in upper/lower case, but are in fact the same host.  The string
"true" is output if the two strings match, or "false" if they do not.
"ERROR" is output if an error occurs (such as incorrect usage).  The exit
value is 0 for true, 1 for false, and 2 for error.


issubdom		Example: issubdom cse.nau.edu. Nau.EDU.
			Outputs: true
This command checks to see if the first argument is a subdomain of the second.
The command outputs "true" if it is a subdomain, or "false" if not.  Identical
strings are considered "false", because a domain is never a subdomain of
itself.  "ERROR" may also be output if an error occurs (such as incorrect
usage).  An exit status of 0 is returned for true, 1 for false, and 2 for error.
This is basically just a case insensitive right-most string comparison.
Therefore it can't tell if you give it a hostname instead of a domain name, nor
can it tell if the sub-domain is within the upper level domain, or somewhere way
below it (i.e. "a.b.c.d.e." and "d.e." yields a result of "true").


netwithzeros		Example: netwithzeros 134.114
			Outputs: 134.114.0.0
Converts a possibly incomplete normal numeric IP address into a full 4-octet
IP address by adding "0" octets to the right-hand side.  Useful for querying
the NIC via "whois" for network ownership information (they require the zeros
in network addresses), and for dealing with RFC1101 host-zero style addresses.
If the "0"s already exist, then the address is passed through unchanged.
"ERROR" will be output if an error occurs, such as incorrect usage.
A value of 0 is returned if the command works, 1 if an error occurred.


netkillzeros		Example: netkillzeros 134.114.0.0
			Outputs: 134.114
Converts a numeric IP address that might have "0" octets in it into a possibly
partial IP address by removing any the "0" octets from the right-hand side.
This reverses the action of the netwithzeros tool.  Not all "0" octets are
removed; just the rightmost ones, for example, "202.0.14.0" becomes "202.0.14",
because that's the network it represents.  If the "0" octets are already
missing, then the address is passed through unchanged.
"ERROR" be output if an error occurs, such as incorrect usage.
A value of 0 is returned if the command works, 1 if an error occurred.


bits2mask		Example: bits2mask 19
			Outputs: 255.255.224.0
Outputs a dotted-quad netmask that fits the number of bits specified
on the command line.  Opposite tool: mask2bits.
"ERROR" is output if an error occurs, such as incorrect usage.
An exit value of 0 is returned if the command works, 1 if an error occurred.


mask2bits		Example: mask2bits 255.255.224.0
			Outputs: 19
Given a dotted-quad netmask, the number of network bits is printed on
standard output.  Opposite tool: bits2mask.
An error is generated if netmask bits are not contiguous.
"ERROR" is output if an error occurs, such as incorrect usage.
An exit value of 0 is returned if the command works, 1 if an error occurred.


ipsort			Example: ... | ipsort | ...
			Outputs: (lines sorted by IP address field)
This tool sorts input lines based on the ordering of network IP addresses.
Input is assumed to be lines whose fields are white-space separated with
the first field being a 4-octet dotted-decimal IP address.  This tool is very
slow because the algorithm is currently a modified bubble sort done in awk!
Ipsort also has a "-u" option that can be used to remove duplicate lines
(like uniq, or the -u option to sort), the entire line is compared with this
option in a case-sensitive way.
Because of the fact that IP addresses have periods within them which could be
misinterpreted as decimal points, the unix "sort" utility cannot be forced to
do a multi-field numeric sort on IP addresses.  You can't even try replacing
the periods with spaces and do 4 levels of numeric sorting, because the unix
"sort" utility doesn't leave presorted lines in proper order.
TODO: Rewrite this in C or Perl.  Make -u option case-insensitive.


domsort			Example: ... | domsort | ...
			Outputs: (lines sorted by domain name field)
This tool sorts input lines based on the ordering of inner domains within
outer domains.  Upper-level domains ("nau.edu") come before lower ones
("cse.nau.edu"), so that all records for each domain are grouped together.
Input is assumed to be lines whose fields are white-space separated with the
first field being the domain name.  The input lines must have the domain names
in the first white-space separated field, with [optionally] anything in
the other fields which is ignored.  Domsort also has a "-u" option that
can be used to remove duplicate lines (like uniq, or the -u option to sort),
the entire line is compared with this option (again, case-insensitively).
The unix "sort" utility cannot be forced to sort a multi-field list of Domain
Names because of the fact that these names are designed with the outer-most
domain on the right instead of the left, and because dots are used to separate
the domain-levels.  (dots are generally considered decimal-points in sort).


basedomain		Example: basedomain cse.nau.edu.
			Outputs: nau.edu.
This tool takes any fully qualified domain name (FQDN) and removes the inner-
most domain portion from it.  This works for any type of domain name (including
reverse in-addr.arpa type domain names).  Asking for the basedomain of the
root domain (".") is an error.  All errors return "ERROR" on stdout, and exit
with a non-zero value.  Successful runs return one line of output and exit with
a zero value.


rndarg			Example: rndarg a b c d
			Outputs: a
				 d
				 c
				 b
Outputs the list of arguments in random order, one per line.  With only
one argument, just that argument is returned.  If no arguments are supplied,
no output is produced.  This is NOT considered an error.  This tool is useful
when obtaining a list of name-servers, so that your software can randomly
choose a nameserver to query.  For example, to distribute the load of queries
over all root domain servers, our tools can try each root domain nameserver
in random order to try to get answers of some kind.  This is a good idea,
especially if any programs developed with these tools become widely used
all over the Internet.


gensubnetlist	Example: gensubnetlist 134.114.0.0 255.255.0.0 255.255.224.0
		Outputs: 134.114.0.0
			 134.114.32.0
			 134.114.64.0
			 134.114.96.0
			 134.114.128.0
			 134.114.160.0
			 134.114.192.0
			 134.114.224.0
		Example: gensubnetlist 134.114.1.1 255.255.1.1 255.255.193.1
		Outputs: 134.114.1.1
			 134.114.65.1
			 134.114.129.1
			 134.114.193.1
Outputs the complete list of legal subnetwork addresses, one per line.
First and last subnets (all 0-bits and all 1-bits) are permitted.
This tool is useful in trying to figure out what subnets a network can have.
The first argument is the IP network being used.  The second argument is the
netmask for that network (i.e., how many bits of an IP address is the
network portion).  The third argument is the subnetwork mask, that is,
the netmask describing how this network is subnetted.  In the example above,
134.114 is a class-B network, so we use the class-B netmask of
255.255.0.0, and perhaps we know that this network is subnetted with a
netmask of 255.255.224.0.
If an error occurs, "ERROR" is send to stdout, a description of the error
to stderr, and a non-zero exit status is returned.  If success, then the
list of (possibly no) subnet network records is output, and exit value of 0
is returned.  If type netmask == subnetmask, that's an error.
If you pass in a netmask with bits turned on that are off in subnetmask,
that is also an error.  The subnetmask bits don't have to be next to each
other, and don't have to match byte-boundaries.  See second example, above.


geniplist	Example: geniplist 134.114.123.0 255.255.255.248
		Outputs: 134.114.123.1
			 134.114.123.2
			 134.114.123.3
			 134.114.123.4
			 134.114.123.5
			 134.114.123.6
		Example: geniplist 134.114.0.0 255.255.252.252
		Outputs: 134.114.0.1
			 134.114.0.2
			 134.114.0.3
			 134.114.1.0
			 134.114.1.1
			 134.114.1.2
			 134.114.1.3
			 134.114.2.0
			 134.114.2.1
			 134.114.2.2
			 134.114.2.3
			 134.114.3.0
			 134.114.3.1
			 134.114.3.2
Outputs the complete list of host IP addresses, one per line for the
given network or subnet specified on the command line.
The very first and last IPs (all 0-bits and all 1-bits) are not returned,
as they are generally reserved for booting and broadcast addressing.
The first argument is the IP network to use.  The second argument is the
netmask for that network (i.e., how many bits of an IP address is the
network portion).
If an error occurs, "ERROR" is send to stdout, a description of the error
to stderr, and a non-zero exit status is returned.  If success, then the
list of (possibly no) host network records is output, and exit value of 0
is returned.  The netmask bits don't have to be next to each other,
and don't have to match byte-boundaries.  See second example, above.


localad		Example: localad
		Outputs: 134.114.64.24
Prints the IP address of the local computer to stdout and exits 0
if successful.  If unsuccessful in determining the IP address, "ERROR"
is sent to stdout and a non-zero exit value is returned.  This tool uses
many methods in attempting to determine the local IP address, and only
fails if all of the methods fail.  This is a useful tool when you need
a starting point for a network map or something, and don't want to
hard-code your local host and network information.
NOTE: This tool uses tools from level 2.


localdom	Example: localdom
		Outputs: cse.nau.edu.
Prints the domain name of the local computer to stdout and exits 0
if successful.  If unsuccessful in determining the domain name, "ERROR"
is sent to stdout and a non-zero exit value is returned.  The domain name
returned is all of the FQDN minus the hostname.  This tool uses many methods
in attempting to determine the local domain name, and only fails if all of
the methods fail.  This is a useful tool when you need a starting point
for a network map or something, and don't want to hard-code your local
host and network information.
NOTE: This tool uses tools from level 2.


digparse	Example: dig @fire.domtools.com. AXFR domtools.com. \
				+ret=2 +pfset=0x2024 | digparse > file
		Outputs: domtools.com.       SOA    fire.domtools.com. hostmaster.domtools.com.  1998092500 8h3s 1h3s 3w3d 1D
			 domtools.com.       NS     dns.jammed.com.
			 domtools.com.       NS     pine.cse.nau.edu.
			 domtools.com.       NS     fire.domtools.com.
			 domtools.com.       TXT    "Domtools Consulting"
			 domtools.com.       A      207.225.191.12
			 dns.domtools.com.   CNAME  fire.domtools.com.
			 fire.domtools.com.  A      207.225.191.12
Parses the output from DiG into easily parsable resource records.  One record
per line, no comments or blank lines.  Each record contains fully-qualified
domain names for everything.  Digparse knows how to parse DiG 8.1 and older
output formats.  Digparse can handle regular record queries or axfr's.
Digparse will parse all reasonable-looking lines that DiG produces, it
doesn't understand you might only want the ANSWERS section.  The +pfset option
in the example above tells DiG to only output the ANSWERS section.


---------------------
--- Level 2 Tools ---
---------------------

NOTE: All of the tools in this section (except root and nsroot) allow
an optional "@nameserver" argument if you want to force one particular
nameserver to receive all DNS queries.  This is important when running
Domtools behind a firewall, because many of the commands try to talk
directly to authoritative nameservers by default.


ns			Example: ns nau.edu.
			Outputs: sunset.cse.nau.edu.
				 agassiz.cse.nau.edu.
				 rainbow.cse.nau.edu.
				 nauvax.ucc.nau.edu.
				 ccnucb.colorado.edu.
				 pun.cis.ohio-state.edu.
Returns the domain names of all known authoritative name-servers for the zone
specified, one per line.  The first one is often the primary name server,
which you can extract by piping the output through "head -1".  Don't just
depend solely on the first line you get back, because that particular server
is sure to be down at one time or another!  To make your program fail-safe
you should loop through all of the nameservers and try each one.  There's
also a chance that "ns" will fail while "nsroot" will succeed, for instance
when the authoritative zone does not have any NS records for itself (yes,
that happens with improperly configured zone; just so you know it can happen).
So, for fail-safe programs, if you call "ns" and get an error, fall back
by calling "nsroot".  If both fail then that domain is not a zone.  You can
determine what zone a domain is in with the "zone" tool, then call "ns" with
the zone name.  (Remember, NS records are located at the top of each zone,
not necessarily at the top of each domain!)

You can pass the results of this command to the "rndarg" tool to get a
randomly ordered list of nameservers.  That is sometimes preferable to a
semi-ordered list, to distribute the load of queries across all nameservers.
"ns" is basically just an "NS" resource-record query.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


zone			Example: zone some.domain.name.inside.nau.edu.
			Outputs: nau.edu.
Returns the domain name of the zone that this domain belongs to.  If you
pass in a zone name itself, you get back the same name.  The domain name
you pass in can also be that of a host machine, in which case the zone
it belongs to is returned.  This tool should be used before passing
a domain name to the "soa" or "ns" tools, because only zones (should!)
have SOA and NS records.  That is, after all, the definition of a zone,
from the computer's perspective.


root			Example: root
			Outputs: B.ROOT-SERVERS.NET.
			C.ROOT-SERVERS.NET.
			D.ROOT-SERVERS.NET.
			E.ROOT-SERVERS.NET.
			I.ROOT-SERVERS.NET.
			F.ROOT-SERVERS.NET.
			G.ROOT-SERVERS.NET.
			A.ROOT-SERVERS.NET.
			H.ROOT-SERVERS.NET.
Returns a complete list of current root domain name servers.  This is done
by asking host "." for a list of name servers for the zone ".", then
asking each of those in turn until one of them can give us a similar list.
That resulting list is returned.  If none of those root nameservers respond,
this tool fails ("ERROR" is output and non-zero exit status returned).


nsroot			Example: nsroot nau.edu.
			Outputs: rainbow.cse.nau.edu.
				 turing.cse.nau.edu.
				 nauvax.cse.nau.edu.
Returns the domain names of all known authoritative name-servers for the zone
specified, one per line, according to the Internet root domain name servers.
The first one is usually the primary name server, which you can extract by
piping the output through "head -1".  For fail-safe programs, loop through all
of these nameservers and ask each one instead of depending only on the first
(primary) nameserver returned.  This tool only queries the root domain name
server, and may be inappropriate for many "inner" sub-domains.  Most needs
require the "ns" tool, above.  You need to determine what zone a domain is
in with the "zone" tool before calling this one.
You can pass the results of this command to the "rndarg" tool to get a
randomly ordered list of nameservers.  That is sometimes preferable to a
semi-ordered list, to distribute the load of queries across all nameservers.
"nsroot" is basically just an "NS" resource-record query, directed at the root
domain name servers on the Internet.


address			Example: address saddle.cse.nau.edu.
			Outputs: 134.114.64.80
Returns the host's IP address(es) in normal format (four dot-separated decimal
octets) for the host domain name given.  If the host has more than one network
address, all are returned, one per line.  This command basically performs
an "A" resource-record query.  The string "ERROR" is sent to standard output
and a non-zero exit status is returned if the command fails.

The real resource-record name is "A", but command names that short are
a bad choice.  This tool used to be named "ad" but was renamed to something
longer to avoid conflict with user aliases.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.
("yes, we have no bananas!")


ptr			Example: ptr 90.64.114.134.in-addr.arpa.
			Outputs: pine.cse.nau.edu.
Returns the canonical host domain name of the machine pointed to by the
inverse mapping domain name passed in.  This command basically performs
a "PTR" resource-record query.  The string "ERROR" is sent to standard
output and a non-zero exit status is returned if the command fails.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


hinfo			Example: hinfo rainbow.cse.nau.edu.
			Outputs: Sparcstation-1plus SunOS4.1
Returns the two host information fields (CPU and OS, respectively) all on
one line, for the host domain-name passed in.  No delimiter marks are added
around the two output fields, so if there are any embedded spaces in either
field, you won't be able to tell where one field ends and the next begins.
Therefore we recommend that you do not use any whitespace in either field.
(This is a bug in DiG's output for HINFO records).  The hinfo tool
basically just does an "HINFO" resource-record query.  The string "ERROR"
is sent to standard output and a non-zero exit status is returned if
the command fails.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.

uinfo			Example: uinfo somehost.dom.ain.
			Outputs: <text string similar to the txt tool>
Returns the contents of the UINFO record associated with the domain name given.
You can assume the entire line of output up to the newline is one complete
UINFO record.  Multiple lines implies multiple UINFO records.
The string "ERROR" is sent to standard output and a non-zero exit status
is returned if the command fails.  You should really check the return value
to see if an error occurred, since it is technically possible to have the
contents of a UINFO record be set to the string "ERROR"!

Note:	You must be running a version of BIND that can handle UINFO records,
	and your DiG must be able to handle it.

Note2:	Double quotes will always be displayed on output regardless of whether
	your version of DiG is an old one that doesn't add quotes, or a new one
	that does.

This tool silently follows CNAME records.



soa			Example: soa nau.edu.
			Outputs: rainbow.cse.nau.edu. root.rainbow.cse.nau.edu.\
				1000300 10800 3600 250000 86400
	      (the backslash is mine; each record is printed all on one line)
Returns the Start Of Authority information for the zone passed in.  Output
consists of seven fields all on one line, namely: origin, mail address,
serial number, refresh, retry, expire, and minimum time-to-live.  These fields
are space-separated.  You should determine what zone a domain is in with the
"zone" tool before calling this one.  (SOA records are located at the top of
each zone, not necessarily at the top of each domain).  This command is
basically just an "SOA" resource-record query.  The string "ERROR" is sent to
standard output and a non-zero exit status is returned if the command fails.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


txt			Example: txt pab.people.nau.edu.
			Outputs: "Paul Balyoz, (602) 523-2088, NAU box 15600"
Returns the contents of the TXT record associated with the domain name given.
You can assume the entire line of output up to the newline is one complete
TXT record.  Multiple lines implies multiple TXT records.
The string "ERROR" is sent to standard output and a non-zero exit status
is returned if the command fails.  You should really check the return value
to see if an error occurred, since it is technically possible to have the
contents of a TXT record be set to the string "ERROR"!

Note:	You must be running a version of BIND that can handle TXT records,
	such as version 4.8.3 or later, and your DiG must be able to handle it.

Note2:	Double quotes will always be displayed on output regardless of whether
	your version of DiG an old one that doesn't add quotes, or a new one
	that does.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


any			Example: any rainbow.cse.nau.edu.
			Outputs: A 134.114.64.24
				 HINFO SUN-4/75 SunOS
				 WKS 134.114.64.24 udp echo time domain
				 WKS 134.114.64.24 tcp echo ftp telnet \
				    smtp time domain finger
	      (the backslash is mine; each record is printed all on one line)
Returns the names of all resource records associated with the domain name
given, followed by each record's contents, one record per line.
The string "ERROR" is sent to standard output and a non-zero exit status
is returned if the command fails.
Returns all resource records available from the first authoritative
nameserver that responds.  If there are any embedded spaces in the data
of HINFO records, you won't be able to tell where the CPU field ends
and the OS field begins (see "hinfo" tool).

This tool silently follows CNAME records.


wks			Example: wks rainbow.cse.nau.edu.
			Outputs: 134.114.64.24 udp echo time domain
				 134.114.64.24 tcp echo ftp telnet \
				    smtp time domain finger
	      (the backslash is mine; each record is printed all on one line)
Returns the contents of all Well Known Software (WKS) records associated with
the domain name given.  No extra delimiters surround the record on output;
you can assume the entire line of output up to the newline is one complete
record.  The string "ERROR" is sent to standard output and a non-zero exit
status is returned if the command fails.  Returns all resource records
available from the first authoritative nameserver that responds.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


mx			Example: mx nau.edu.
			Outputs: 10 nauvax.ucc.nau.edu.
				 20 sunset.cse.nau.edu.
				 30 pine.cse.nau.edu.
Returns the contents of all Mail Exchange (MX) records associated with the
domain name given.  No extra delimiters surround the record on output;
you can assume the entire line of output up to the newline is one complete
record.  The string "ERROR" is sent to standard output and a non-zero exit
status is returned if the command fails.  Returns all resource records
available from the first authoritative nameserver that responds.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


cname			Example: cname rain.cse.nau.edu.
			Outputs: rainbow.cse.nau.edu.
Performs a CNAME resource record lookup on the domain name given.  If the
domain name given is not the canonical name of the host (i.e. has a CNAME
record instead), this tool returns the canonical domain name (the domain name
which the CNAME points to).  If the domain name given _is_ the canonical
domain name already or if the domain name given is not known, this tool
returns ERROR and a non-zero exit value.  The CNAME record is not followed,
as with other resource-record tools (address, ptr, hinfo, ...).


axfr			Example: axfr nau.edu.
			Outputs: (entire dump of that zone, one resource-
				 record per line, in the format:
					dom.ain. RRTYPE rrdata ...
				 )
Displays the entire zone specified on the command line, in a parsable
format that has one resource-record per line, in this form:
		dom.ain. RRTYPE rrdata ...
for example:
		nau.edu. SOA sunset.cse.nau.edu. root.sunset.cse.nau.edu. \
			 1000325 10800 3600 250000 86400
		nau.edu. NS sunset.cse.nau.edu.
		nau.edu. MX 10 134.114.64.70
		nau.edu. MX 20 134.114.64.24
		cse.nau.edu. NS sunset.cse.nau.edu.
		cse.nau.edu. A 134.114.64.70
		cse.nau.edu. MX 10 134.114.64.70
		...
(The backslash is mine; each record is really printed all on one line)

When Domtools is installed, the administrator can choose to configure axfr
to keep a cache of all zones it transfers in a special directory,
so that it can use the cached version for subsequent axfr queries for
the same zone.  If the SOA version number matches the current version,
you get the cached file, otherwise the newer zone info is obtained.
This speeds up axfr when asked for a zone it's already cached.
The zone cache directory holds two things: zone files (default), and
subdirectories containing zone files (when a particular nameserver is
specified with "@" arg, all zones transferred from that nameserver are
stored in a subdirectory).  The subdirectories are necessary to group all
zones transferred from a particular nameserver together.  If you specify
a nameserver, you want to see only zone data that came from that nameserver,
and no others.


nsap			Example: nsap somehost.dom.ain.
			Outputs: NSAP 0x47.0005.80.005a00.0000.0001.e133.ffffff000161.00
Returns the OSI NSAP address(es) in hexadecimal format for the host domain name
given.  If the host has more than one address, all are returned, one per line.
This command basically performs an "NSAP" resource-record query.  The string
"ERROR" is sent to standard output and a non-zero exit status is returned if
the command fails.  For info on NSAP records, see RFC 1706.

This tool silently follows CNAME records.

No output lines and no error means an authoritative nameserver told us
there are no records of this type for the given domain name.


gw			Example: gw 134.114.64
			Outputs: (list of all gateway hosts)
Generates a list of all machines that are gateways into the network specified,
one per line, full domain name format.  Some domain administrators do not
use gateway records even though they are supposed to.  In this case "ERROR"
is output.  "gw" just returns PTR records for the in-addr of the address.
Note: Specify only the octets that are part of the network; this tool
      doesn't analyze the address you give to extract only the network portion.
      Use the addr2net tool before calling this tool, if needed.
Note: This is now a symlink to the netname tool, below, since the algorithm
      is identical.


netname			Example: netname 134.114.64
			Outputs: csenet.nau.edu.
Returns the network's name record in full domain format.  Only works for
domains that observe the RFC1101 extensions.  If record not found, "ERROR"
is returned.  This is just a PTR query for the in-addr of the address.
Note: Specify only the octets that are part of the network; this program
      doesn't analyze the address you give to extract only the network portion.
      Use the addr2net tool before calling this tool, if needed.


subnetmask		Example: subnetmask 134.114
			Outputs: 255.255.255.0
Returns the network's subnetmask record, if any exists.  Only works for
domains that observe the RFC1101 extensions.  If record not found, "ERROR"
is returned along with an exit status of 1.  This means that this network
is not subnetted further, or that the domain database doesn't have the
(_strongly_ recommended) RFC1101 subnetting extensions.  This is not a
recursive query, only the network specified is checked.  For recursive
traversal (such as for finding the subnetmask of a host IP address),
see the "netmask" tool instead.
See also the "network" tool for multilevel subnetting.
Note: Specify only the octets that are part of the network; this program
      doesn't analyze the address you give to extract only the network portion.
      You can use the addr2net tool before calling subnetmask, if needed.


network			Example: network 134.114.64.23
			Outputs: 134.114.64.0
Returns the network (or subnetwork) which the address belongs to.  If the domain
database for that network observes the RFC1101 subnetting extensions, they
are taken into consideration; otherwise the default subnet mask is used,
according to what network class the IP address belongs to (A, B, C, ...).
In case of a problem, "ERROR" is sent to stdout, with an exit status of 1.
If all goes OK, the answer is returned on stdout, and exit value is 0.
This tool is similar to calling "addr2net" with the IP address and the output
of the "netmask" tool; however, we don't actually use either of these to do
the job.


netmask			Example: netmask 134.114.64.23
			Outputs: 255.255.255.0
Returns the netmask of the network (or subnetwork) which the address belongs to.
You may use a network address (less than four octets is allowed, it adds "0"
octets to the right side) or a host IP address.  Recursively follows those
RFC1101 subnetting RRs.

If the domain database for that network observes the RFC1101 subnetting
extensions, they are taken into consideration; otherwise the default subnet mask
is returned, according to what network class the IP address belongs to (A, B, C,
...).  In case of a problem, "ERROR" is sent to stdout, with an exit status of 1.
If all goes OK, the answer is returned on stdout and the exit value is 0.


subdom			Example: subdom nau.edu.
			Outputs: cba.nau.edu.
				 glg.nau.edu.
				 ...
Returns a list of fully-qualified subdomains within this domain.  No sub-
subdomains within these subdomains are listed unless the -r (recursive) flag
is specified.  If recursion is specified then the output also contains the
name of the specified domain as well (the find(1) command acts similarly).
Each entry is printed on a separate line.  Recursive traversal is depth-first,
and is much slower than non-recursive.  All output domain names are in domain
name sorted order.


subzone			Example: subzone nau.edu.
			Outputs: cba.nau.edu.
				 glg.nau.edu.
				 ...
Returns a list of fully-qualified subzones within this zone.  No subsubzones
within these subzones are listed unless the -r (recursive) flag is specified.
If recursion is specified then the output also contains the name of the
specified zone as well (the find(1) command acts similarly).
Each entry is printed on a separate line.  Recursive traversal is depth-first,
and is much slower than non-recursive.  All output zone names are in domain
name sorted order.
Bug:	all letters get converted to lower-case, although their case should
	probably stay however it was when received from the name-server.


hosts			Example: hosts aa.nau.edu.
			Outputs: pc1.aa.nau.edu.
				 pc2.aa.nau.edu.
				 ...
Returns the complete list of fully-qualified host names inside the domain
name passed in, one fully qualified domain name per line on output.  Coupled
with the "subdom" tool above, you can recursively traverse an entire domain
hierarchy and display or examine all the hosts on all branches therein.
Note, however, that an entry for "localhost" may be included in the output
for each domain, if it exists (some people don't like that).

A "host" is defined as any record in the database whose domain name contains
the domain name given on the command line (i.e. "aa.nau.edu"), with exactly
one extra element on the left end (i.e. "pc1.aa.nau.edu").  You can restrict
the type of records examined to be only "A" resource records with the
"-a" option.

The "-r" option means recursion, in which case "hosts" will recursively
traverse the given domain and all subdomains, printing all hosts it finds
along the way.


---------------------
--- Level 3 Tools ---
---------------------

NOTE: All of the tools in this section allow an optional
"@nameserver" argument if you want to force one particular
nameserver to receive all DNS queries.  This is important when running
Domtools behind a firewall, because many of the commands try to talk
directly to authoritative nameservers by default.


soalist			Example: soalist nau.edu.
			Outputs: (SOA records from each authoritative nameserver for nau.edu.)
This tool tells DNS admins what nameservers are supposed to be authoritative for
their domain, according to its parent domain.  It also tells what SOA record
each of those nameservers have, so you can see if the version numbers are
identical on all of them or not.

If you give it the root domain ("."), it actually asks the root name servers,
since there's no "parent" above the root domain.


cachebuild		Example: cachebuild > root.cache
			Outputs: (builds an up-to-date root nameserver cache file)
This tool queries root domain name servers for a complete list of root
domain name servers, and generates a new BIND root.cache file for you.
It's always a good idea to inspect the resulting file yourself before
installing it in your nameserver database directory.  And be sure to
save a copy of your old root.cache file, just in case!  Sometimes this
root nameserver cache file is referred to as named.ca or named.root .

Output format now looks just like named.root file you can download from the
Internic FTP site.  Use "-o" if you want the old output format where
records were grouped by type (all NS recs together, followed by A recs).

If you call cachebuild from cron or at, be sure to set the PATH environment
variable to all the bin directories it needs to run, particularly the domtools
bin directory.


makestatic		Example: makestatic nau.edu. /public/nau
			Outputs: (builds hosts, networks, netmasks files)
This is a higher-level tool that runs the hosttbl, networktbl, and
netmasktbl scripts (see below).  It can be run from cron on a regular
interval, such as every night.  It's _NOT_ a good idea to automatically
install the resulting files into your /etc directory; do that part by hand
after inspecting the file yourself.  If one of the files was improperly built
due to a bug, it could prevent your computer from functioning properly
(or even from booting)!

If you call this from cron or at, be sure to set the PATH environment
variable to all the bin directories it needs to run, including the domtools
bin directory.


hosttbl			Example: hosttbl nau.edu.
			Outputs: (/etc/hosts compatible file)
Generates a table of host information in the format of the static host file
that some Unix machines use in place of name-service, generated from name-
server queries in all subdomains within the domain specified, complete with
comments, whitespace, and static entries that you can set up ahead of time.
This is a very useful tool if you have some computers that still require a
static host table (can't use the BIND name resolver).  You must run this on
a host that CAN do name-service, then copy the resulting static host table
to the appropriate machine(s).  It also should be noted that many hosts
which DO have name-resolving capabilities have to set up their network
interface during reboot using the static host table, so it really pays off
to keep that file up to date with the output from a tool like this!

This tool takes an optional argument before the domain name, which is an
integer number 0 or larger known as the "alias level".  The alias level
is the number of domain-levels of host aliases you want included with
the output.  It's easier to explain by example:

    COMMAND:			WOULD PRINT LINES LIKE:
    hosttbl 0 cse.nau.edu.	134.114.64.70  pine.cse.nau.edu
    hosttbl 1 cse.nau.edu.	134.114.64.70  pine.cse.nau.edu  pine
    hosttbl 2 cse.nau.edu.	134.114.64.70  pine.cse.nau.edu  pine.cse

The default alias level is set at installation time (see Makefile).

This tool attempts to do the Right Thing -- both CNAMEs and A resource
records are added as entries in the host table.  For example, the records:
	rainbow.cse.nau.edu.	IN	A	134.114.64.24
	rai			IN	CNAME	rainbow.cse.nau.edu.
	rain			IN	CNAME	rainbow.cse.nau.edu.
would generate one line in /etc/hosts that looks like:
	134.114.64.24	rainbow.cse.nau.edu		rainbow rai rain
This way the fully qualified domain name is the preferred spelling, while
there are three accepted abbreviations that should work as well.  Now you
can use any of these host name forms with the usual networking commands
(rcp, rsh, rlogin, telnet, ftp, sendmail, etc.) on systems that do not have
a domain name resolver.

The table is output by alphabetical sub-domain groups, each one separated by
a few lines of comments.  Within each sub-domain all the hosts, their IP
addresses and name aliases are printed one host per line, sorted by IP
address.  Hosts with multiple IP addresses are given separate lines for
each IP address like they should.

There are header and footer files which contain static information that
is to be included at the top and bottom of the final hosts table.  It can
include things like comments and other things that don't change very often
(or can't be discovered by this tool).

One macro substitution is done within the header and footer files: any
occurrence of the string "TIMEDATE" will be replaced with the output of
the "date" shell command.  This helps keep track of when the table was
generated.  See the sample header and footer files.


networktbl		Example: networktbl nau.edu.
			Outputs: (/etc/networks compatible file)
Generates a table of network information in the format of the static networks
file that some Unix machines use in place of name-service, generated from
nameserver queries about the networks and their subnetworks, complete with
comments, whitespace, and static entries that you can set up ahead of time.
This is a very useful tool if you have some computers that still require
a static network table (can't use the BIND name resolver).  You must run
this on a host that CAN do name-service, then copy the resulting static
network table to the appropriate machine(s).  It also should be noted that
some hosts which DO have name-resolving capabilities have to set up their
network interface and/or routing tables during boot using the static
networks table.

The table is output in order by network address, with an optional comment
preceding each line.  If the network is subnetted and has the proper
optional records as defined by RFC1101, then each subnet is printed and
traversed recursively, as deep as necessary.  Without RFC1101 records,
we cannot tell if/how you subnet your networks, so we assume your networks
are not subnetted.  The optional comment line above each entry comes from
a special subdomain you can set up within your domain name space.
See the Makefile and README for more info on this.

There are header and footer files which contain static information that
is to be included at the top and bottom of the final networks table.
It can include things like comments, the localhost network, and other things
that don't change very often (or can't be discovered by this tool).

One macro substitution is done within the header and footer files: any
occurrence of the string "TIMEDATE" will be replaced with the output of
the "date" shell command.  This helps keep track of when the table was
generated.  See the sample header and footer files.

The default output format looks like this:
			naunet		134.114

There are a few options to control the input and output formats.
Here is a list of the command-line options:
	-d	Input argument is a domain name (default).
	-n	Input argument is a network IP address.
	-h	Output should include host-aliasing.  This basically
		adds a third field to each output line, so long as the
		name of the network has the word "net" on the end,
		and adds a hyphen to the name just before the "net" part.
		For example, output would now look like:
			naunet		134.114		nau-net
	-x	Output should include a comment line above each data line
		that describes the network in English, taken from special
		TXT RRs in your domain tree.  Makefile's NETWORKSDOM macro
		defines if -x can be used or not.
		(This method began use at N.A.U. because some old non-BIND
		name-resolvers particularly in certain non-Unix environments
		got confused and couldn't interpret resource records beyond
		the first TXT record it encountered).

If hosttbl works for you but networktbl or netmasktbl do not, you need
to implement parts of RFC1101 in your DNS database.  These tools depend on
finding a PTR record for the domain name you pass in, i.e. "foo.com.",
that's how they start analyzing your network to generate /etc/network-like
output.  Read RFC1101 section 4 for details.


netmasktbl		Example: netmasktbl nau.edu.
			Outputs: (/etc/netmasks compatible file)
Generates a table of network information in the format of the static subnet
masks file that some Unix machines use (particularly SunOS), generated from
nameserver queries about the networks and their subnetmasks, complete with
comments, whitespace, and static entries that you can set up ahead of time.
This is a very useful tool if you have some computers that still require
a static network table (can't use the BIND name resolver).  You must run
this on a host that CAN do name-service, then copy the resulting static
netmasks table to the appropriate machine(s).  It also should be noted
that some hosts which DO have name-resolving capabilities may have to set up
their network interface and/or routing tables during boot using this static
netmasks table.

The table is output in order by network address, with an optional comment
preceding each line.  If the network is subnetted and has the proper
optional records as defined by RFC1101, then each subnet is printed and
traversed recursively, as deep as necessary.  Without RFC1101 records,
we cannot tell if/how you subnet your networks, so we assume they are
not subnetted.  The optional comment line above each entry comes from
a special subdomain you can set up within your domain name space.
See the Makefile and README for more info on this.

There are header and footer files which contain static information that
is to be included at the top and bottom of the final netmasks table.
It can include things like comments and other things that don't change very
often (or can't be discovered by this tool).

One macro substitution is done within the header and footer files: any
occurrence of the string "TIMEDATE" will be replaced with the output of
the "date" shell command.  This helps keep track of when the table was
generated.  See the sample header and footer files.

There are a few options to control the input and output formats.
Here is a list of the command-line options:
	-d	Input argument is a domain name (default).
	-n	Input argument is a network IP address.
	-x      Output should include a comment line above each data line
		that describes the network in English, taken from special
		TXT RRs in your domain tree.  Makefile's NETWORKSDOM macro
		defines if -x can be used or not.
		(This method began use at N.A.U. because some old non-BIND
		name-resolvers particularly in certain non-Unix environments
		got confused and couldn't interpret resource records beyond
		the first TXT record it encountered).

If hosttbl works for you but networktbl or netmasktbl do not, you need
to implement parts of RFC1101 in your DNS database.  These tools depend on
finding a PTR record for the domain name you pass in, i.e. "foo.com.",
that's how they start analyzing your network to generate /etc/network-like
output.  Read RFC1101 section 4 for details.


check1101		Example: check1101 nau.edu.
			Outputs: Doc-like verbose output.
Traverses a domain hierarchy examining only the RFC1101 proposed records.
See sections 3 and 4 of that document.  If you are trying to maintain these
records at your site, this is, to my knowledge, the only way you can verify your
configuration.  None of the NIS (a.k.a. "Yellow Pages") portions of RFC1101
have been implemented in this tool yet.


siteinfo		Example: siteinfo nau.edu.
			Outputs: Lots of information about the site in English.
Performs various types of domain name service queries in order to tell you
all kinds of information about the site.  It tells specifics about the site
domain, such as if it has MX, A, CNAME, NS records (and what they are),
it checks to see if the site supports RFC1101 extensions (which are strongly
recommended but not required), which host is the primary master nameserver
for the domain, who is the contact person for the domain, etc.

You can supply a longer domain name, such as that of a host, as in:
	siteinfo rainbow.cse.nau.edu.
Siteinfo will use just the last two domain name elements to work with.



NOTES AND WARNINGS

These tools rely heavily on the output format of the DiG utility version 2.x
or 8.x.  Do not depend totally on the output of the tools in this package
when making decisions about domain name information.  Always verify your
findings yourself using nslookup or DiG when something looks wrong.

None of the peripheral files (filenames *.awk, *.perl) need to be dealt with
directly by the user.  Just the files installed in the bin directory are
the ones you run.  See the Makefile's "install" section on what gets put in
the "bin" and "lib" directories.

None of these scripts should ever be setuid or setgid!  They do need to
be readable and executable by everyone.  You should also make your DiG program
be executable by everyone.  No special privileges are needed by any tools
in this package.

--
Paul Balyoz,  Unix Sysadmin and Programmer
Domtools Consulting                           pab@domtools.com
Phoenix Arizona, USA                          pbalyoz@jammed.com
