NAME

SYNOPSIS

DESCRIPTION

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:

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

where TEXT is a human-readable explanatory message.

If the input is invalid, the reply is:

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.

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

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

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:

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

AUTHOR

POD ERRORS

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