WHOSEIP(1)

NAME
whoseip - return information about IP address

SYNOPSIS
whoiseip [-dhN] [-F FILE] [-D FILE] [-i FILE] [--cache-file=FILE] [--debug] [--define-format=NAME=TEXT] [--dump=FILE] [--export] [--fastcgi=[SUFFIX...]] [--format=TEXT] [--format-file=[NAME=]FILE] [--formfile=FILE] [--help] [--import] [--ip-list=FILE] [--no-cache] [--single-query] [--usage] [IPADDR...]

DESCRIPTION
For each IP address, whoseip returns the country it is located in (a ISO 3166-1 code), the network it belongs to and the number of addresses in the network.

The program can operate in several modes: as a standalone command line tool, or as a CGI or Fast CGI process.

If the program name ends in .fcgi the Fast CGI mode is enabled. This mode is also enabled if the command line option --fastcgi is given without arguments, or if the program name ends in one of the suffixes supplied in the argument to this option (a whitespace-separated list). In this mode, the IP address to look for is taken from the URI parameter ip. Additional parameter fmt can be used to supply the name of the desired output format. Its value must be either a name of one of the built-in formats, or must be defined using the --define-format option (see below). As a shortcut, the invocation command line containing an IP alone is also recognized.

Otherwise, when one or more IP addresses are given in the command line, whoseip prints the data for each of them on the standard output. This is command line mode.

If called without arguments, the program checks if the environment variable GATEWAY_INTERFACE is defined and contains CGI/V (where V is the version number). If so, it assumes CGI mode. In this mode the command line is parsed the same way as in Fast CGI mode.

If GATEWAY_INTERFACE is not set, the program reads IP addresses from input (one per line) and prints replies for each of them. This is inetd mode.

To summarize:

1.  Start it from the command line with one or more IPs given as arguments, if you wish to get info about these IPs.

2.  Add it to /etc/inetd.conf if you want to query it remotely as a service, e.g.:

        whois stream tcp nowait nobody /usr/bin/whoseip

3.  Copy it to your cgi-bin directory to use it with a http server as a CGI.

4.  Link it to whoseip.fcgi to use it as a FastCGI application (or use the --fastcgi option).

Output formats are configurable and depend on the mode whoseip runs in. In command line and inetd modes, the default output format is:

    OK COUNTRY CIDR RANGE COUNT

where COUNTRY is country code, CIDR is network block in CIDR notation, RANGE is network block as a range of IP addresses, and COUNT is number of IP address in the network block.

If the specified IP address is not found, the reply is

    NO TEXT

where TEXT is a human-readable explanatory message.

If the input is invalid, the reply is:

    BAD TEXT

In CGI and FastCGI modes, the output is represented as XML, as shown in the example below:

    <?xml version="1.0" encoding="US-ASCII"?>
    <whoseip xmlns:whoseip="http://man.gnu.org.ua/8/whoseip">
      <whoseip:status>OK</whoseip:status>
      <whoseip:country>US</whoseip:country>
      <whoseip:cidr>192.0.2.0/24</whoseip:cidr>
      <whoseip:range>192.0.2.0-192.0.2.255</whoseip:range>
      <whoseip:count>255</whoseip:count>
      <whoseip:term>192.0.2.10</whoseip:term>
    </whoseip>

The following example illustrates the reply if the IP is not found:

    <?xml version="1.0" encoding="US-ASCII"?>
    <whoseip xmlns:whoseip="http://man.gnu.org.ua/8/whoseip">
      <whoseip:status>NO</whoseip:status>
      <whoseip:diag>IP unknown</whoseip:diag>
      <whoseip:term>43.0.0.1</whoseip:term>
   </whoseip>

See the section FORMAT below for a discussion on how to customize output formats.

  Caching
To minimize number of queries to external whois servers, it is recommended to use a cache database. It is enabled by using the --cache-file=FILENAME option (or cache-file configuration file statement). A time to live for the cached records can be set using the --cache-ttl option.

OPTIONS

--cache-file=FILE
    Cache retrieved data in file FILE.

-D, --dump=FILE
    Dump the program to FILE. This is normally done to update the built-in server list, e.g.:

         whoseip --ip-list=ip_del_list --dump=whoseip.new

    Note, that --dump must be last option in the command line.

-d, --debug
    Increase debugging verbosity.

--define-format=NAME=TEXT
    Define a named format NAME to be TEXT. Two names are predefined: format cgi is used to respond to CGI or FastCGI requests, and format unix is used when serving requests coming from command line or in inetd mode. See the section FORMAT, for a detailed discussion.

--export
    Export the IP database into portable ASCII dump file. If a single argument is supplied, it gives the name of the output file. In the absence of arguments, standard output is used.

    The created file can be transmitted over the network to hosts of another architecture and used there to recreate the database via whoseip --import.

--fastcgi=[SUFFIX...]
    When used without argument, forces FastCGI mode. If an argument is given, it is treated as a whitespace-separated list of suffixes. In this case, FastCGI mode is enabled if the program name ends in one of these suffixes.

    If this option is not given, FastCGI is enabled if the program name ends in .fcgi.

-f, --format=STRING
    Sets output format string. If STRING begins with a @, it is a reference to a named format string (either built-in one or a one created using the --define-format option), and is replaced with the value of the format referred to. For example, --format=@cgi instructs the program to use cgi format.

-F, --formfile, --format-file=[NAME=]FILE
    Read output format string from FILE. If NAME is supplied, assign the format string to the named format. See the section FORMAT, for a detailed discussion.

-i, --ip-list=FILE
    Read the table of whois servers from FILE. Each line in FILE must have the following format:

    CIDR SERVER

    Comments are introduced with a # sign. Empty lines are ignored.

    Without this option, whoseip uses the built-in list of servers.

--import
    Import data from the file given as the first argument into the database. If no argument is given, read from standard input. The input must be a valid whoseip database dump, as produced by whoseip --export.

-N, --no-cache
    Disable caching (this is the default).

--single-query
    This option is valid only in inetd mode. It instructs whoseip to terminate after replying to the first query.

The following options cause the program to display informative text and exit:

-h  Show a short usage summary.

--help
    Show man page.

--usage
    Show a concise command line syntax reminder.

CONFIGURATION FILE
If the file /etc/whoseip.conf exists, it is read before processing command line options. If the environment variable WHOSEIP_CONF is set, its value is used as the file name, instead of /etc/whoseip.conf.

The file is read line by line. Long lines can be split over several physical lines by inserting a backslash followed by a newline. Empty lines are ignored. Comments are introduced with the # character. Anything following it up to the logical line is ignored.

Each non-empty line must contain a single long command line option, without the leading --. Arguments must be separated from options with an equals sign, optionally surrounded with whitespace.

For example:

    # Assume FastCGI if the program name ends in one of these
    # suffixes
    fastcgi = .fcgi .pl
    # Define output format for CGI and FastCGI modes
    define-format  =  cgi=Content-Type: application/json\n\
    \n\
    { "status": "${status}", \
    $?{diag}{"diag": "${diag}"}{\
     "country": "${country}",\
     "cidr": "${cidr}",\
     "range": "${range}",\
     "count": "${count}"}\
    $?{term}{, "term": "${term}" } }\n

FORMAT
Output formats can be redefined using --define-format, --format, and --format-file command line options, or corresponding configuration file keywords.

The format string supplied with this options (or in the input file, in case of the --format-file option) can contain the following macro references, which are replaced with the corresponding piece of information on output:

${status}
    The reply status: OK, if the information has been retrieved, NO, if it was not, and BAD, if the input was invalid.

${diag}
    Contains explanatory text if ${status} is NO or BAD. If it is OK, this macro is not defined.

${item}
    Ordinal number of the request being served. Not defined in CGI and FastCGI modes.

${term}
    The input IP address.

${cidr}
    The network IP belongs to, as a CIDR.

${range}
    The network, as a range of IP addresses.

${count}
    Number of IP addresses in the network.

${country}
    ISO 3166-1 code of the country where IP address is located.

${source}
    Where the information was obtained from. QUERY, if it was retrieved from a remote whois server and CACHE, if it was read from the cache database.

${timestamp}
    Time when the record entered the database (if obtained from cache).

${ttl}
    Cache entry time to live (if obtained from cache).

${server}
    Whois server that returned the information.

${port}
    Port used to query the whois server.

${package}
    Name of the package (whoseip).

${version}
    Whoseip version number.

If a macro is not defined, the corresponding reference expands to empty string.

Conditional expressions evaluate depending on whether a macro is defined. The syntax of a conditional expression is:

    $?{NAME}{TEXT-IF-TRUE}{TEXT-IF-FALSE}

Its effect is as follows: if the macro NAME is defined, the TEXT-IF-TRUE is substituted, otherwise the TEXT-IF-FALSE is substituted. Conditional expressions can be nested.

The escape sequences \a, \b, \e, \f, \n, \r, \t, and \v are replaced according to their traditional meaning.

EXIT CODES

0   Normal termination.

64  Command line usage error.

65  Input data format error.

66  Input file cannot be opened.

70  Internal software error (please report that!)

72  Critical OS file is missing. Usually that means that FastCGI mode has been requested, but the FCGI module couldn't be loaded.

73  Can't create output file.

BUGS
Only IPv4 is supported.

AUTHOR
Sergey Poznyakoff <gray@gnu.org>

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 1495:
    Expected text after =item, not a number

Around line 1499:
    Expected text after =item, not a number

Around line 1503:
    Expected text after =item, not a number

Around line 1507:
    Expected text after =item, not a number

Around line 1511:
    Expected text after =item, not a number

Around line 1516:
    Expected text after =item, not a number