nslookup - domain name and IP address lookup

SYNOPSIS

<nslookup [PARALLEL[=n]] [options] {HOSTS|ADDRS}=$hostOrIp
          [$loopvar ...] [/]>
[  ...
</nslookup>]

or in version 7 and earlier syntax (deprecated; see syntaxversion pragma, here) either:

<nslookup [options] $hostOrIp[ /]>

<nslookup PARALLEL[=n] [options] [HOSTS|ADDRS=]$hostsOrIps
          [$loopvar ...]>
  ...
</nslookup>

DESCRIPTION
The nslookup function can resolve a hostname into an IP address and vice versa. By default (if $hostOrIp is unlabelled), it looks up a hostname by name, returning the decimal/hex IP address corresponding to the host. If given an IP address, however, it will perform a reverse lookup and return the host name for the given IP address. The HOSTS or ADDRS label for $hostOrIp - required in version 8 and later syntax (see syntaxversion pragma, here) - determines by-name or by-address lookup regardless of value(s).

With the looping syntax (end tag given in version 8 and later syntax, or PARALLEL flag in version 7 and earlier) name resolution can occur in parallel, with multiple names resolving simultaneously. Behavior is similar to <fetch PARALLEL> (here), in that n (default all) of the names are resolved at a time, and the results are looped over inside the <nslookup> block, as they are completed. Additional variables, if given after the host names/IP addresses, can be looped over in the same return sequence. $loop and $next are set inside the loop as in fetch.

Options that can be set are:

• BYADDR Deprecated; valid in version 7 and earlier syntax only (use ADDRS= in version 8). Forces all lookups by address, i.e. IP-to-name translation. If a given value doesn't look like an IP address, it is assumed to be a host name already resolved, and is returned as-is. Overrides the HOSTS=/ADDRS= implied setting.

• BYNAME Deprecated; valid in version 7 and earlier syntax only (use HOSTS= in version 8). Forces all lookups by name, i.e. name-to-IP translation. If a given value looks like an IP address, it is assumed to be already translated and is returned as-is. Overrides the HOSTS=/ADDRS= implied setting.

• MTERR Return empty string if name or IP address cannot be resolved. By default, a given value is returned as-is if the lookup fails, so that a bulk translation of addresses, e.g. from a web log, doesn't have to be checked individually for errors when printing results.

• HOSTS=$hosts or ADDRS=$ips Sets the list of names to be looked up. Either by-name or by-address translation is forced accordingly; but the BYNAME/BYADDR flags override this (in version 7 and earlier syntax).

  If just a list of names is given without HOSTS=/ADDRS= or the BYNAME/BYADDR flags (only possible in version 7 and earlier syntax), by-name or by-address translation happens on a per-value basis depending on whether the name looks like an IP address or not.

After each value is resolved (inside the loop, if looping), more information about the lookup can be obtained with the nsinfo function (here), such as the list of aliases (if any), or additional IP addresses. As with all looping statements, <BREAK> can be used inside a looping nslookup to stop pending lookups and end the loop. The urlcp function (here) is used to control various aspects of nslookup behavior.

DIAGNOSTICS
nslookup returns the resolved IP address or domain name, as appropriate. On error, either the original value or an empty string is returned, depending on the MTERR flag.

EXAMPLE
This example prints the distinct hostnames of the last 100 clients to access the web server. It does this by reading the last 100 lines of the transfer log and pulling out the IP addresses, then using nslookup to resolve the names. Note that the list is uniq'd before being passed to nslookup, to avoid duplicate lookups of the same name. Also, the names are resolved only 3 at a time to save traffic on the nameserver(s). Because of the BYADDR flag, any addresses that are already resolved in the log file (i.e. if name lookups were turned on in the server) are passed through as-is:

<readln rev "/usr/local/morph3/transfer.log"/>
<rex ">>=[^\space]+" $ret>          <!-- get the IPs -->
<uniq $ret ICASE><$ip = $ret>       <!-- remove duplicates -->
<nslookup PARALLEL=3 ADDRS=$ip>     <!-- look up 3 at a time -->
  $ret
</nslookup>

By turning off reverse name lookup in the web server and using a script such as this to resolve names only as needed, network traffic can be decreased and web server response time increased.

CAVEATS
The nslookup function was added in version 3.0.951800000 20000228.

As with fetch PARALLEL, it is easy to overload a server with too many requests at once. This is even more true with nslookup, because all those requests are going through the same local nameserver even for different-domain hosts. Use caution with the PARALLEL flag; always given a small number.

Resolved names are not cached (unlike with fetch), so multiple lookups of the same name or IP (e.g. from a web log) are discouraged; use uniq or the like to avoid duplicate lookups and save traffic.

If <urlcp dnsmode sys> is set, lookups are serial even if PARALLEL is set, due to C lib constraints.

SEE ALSO
urlcp, nsinfo, fetch