Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  WHOSEIP (1)

.ds Aq ’


whoseip - return information about IP address



<B>whoiseipB> [<B>-dhNB>] [<B>-FB> FILE] [<B>-DB> FILE] [<B>-iB> FILE] [<B>--cache-file=B>FILE] [<B>--debugB>] [<B>--define-format=B>NAME<B>=B>TEXT] [<B>--dump=B>FILE] [<B>--exportB>] [<B>--fastcgi=B>[SUFFIX...]] [<B>--format=B>TEXT] [<B>--format-file=B>[NAME<B>=B>]FILE] [<B>--formfile=B>FILE] [<B>--helpB>] [<B>--importB>] [<B>--ip-list=B>FILE] [<B>--no-cacheB>] [<B>--single-queryB>] [<B>--usageB>] [IPADDR...]


For each IP address, <B>whoseipB> 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 <B>CGIB> or <B>Fast CGIB> process.

If the program name ends in <B>.fcgiB> the <B>Fast CGIB> mode is enabled. This mode is also enabled if the command line option <B>--fastcgiB> 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 <B>URIB> parameter <B>ipB>. Additional parameter <B>fmtB> 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 <B>--define-formatB> 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, <B>whoseipB> prints the data for each of them on the standard output. This is <B>command lineB> mode.

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

If <B>GATEWAY_INTERFACEB> is not set, the program reads IP addresses from input (one per line) and prints replies for each of them. This is <B>inetd modeB>.

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 <B>/etc/inetd.confB> 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 <B>cgi-binB> directory to use it with a <B>httpB> server as a <B>CGIB>.
4. Link it to <B>whoseip.fcgiB> to use it as a <B>FastCGIB> application (or use the <B>--fastcgiB> option).
Output formats are configurable and depend on the mode <B>whoseipB> 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 <B>CGIB> and <B>FastCGIB> modes, the output is represented as XML, as shown in the example below:

    <?xml version="1.0" encoding="US-ASCII"?>
    <whoseip xmlns:whoseip="">

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

    <?xml version="1.0" encoding="US-ASCII"?>
    <whoseip xmlns:whoseip="">
      <whoseip:diag>IP unknown</whoseip:diag>

See the section <B>FORMATB> below for a discussion on how to customize output formats.


To minimize number of queries to external <B>whoisB> servers, it is recommended to use a cache database. It is enabled by using the <B>--cache-file=B>FILENAME<B>B> option (or <B>cache-fileB> configuration file statement). A <B>time to liveB> for the cached records can be set using the <B>--cache-ttlB> option.


<B>--cache-file=B>FILE Cache retrieved data in file FILE.
<B>-DB>, <B>--dump=B>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

Note, that <B>--dumpB> must be last option in the command line.

<B>-dB>, <B>--debugB> Increase debugging verbosity.
<B>--define-format=B>NAME<B>=B>TEXT Define a named format NAME to be TEXT. Two names are predefined: format <B>cgiB> is used to respond to <B>CGIB> or <B>FastCGIB> requests, and format <B>unixB> is used when serving requests coming from command line or in inetd mode. See the section <B>FORMATB>, for a detailed discussion.
<B>--exportB> 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 <B>whoseip --importB>.

<B>--fastcgi=B>[SUFFIX...] When used without argument, forces <B>FastCGIB> 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 <B>.fcgiB>.

<B>-fB>, <B>--format=B>STRING Sets output format string. If STRING begins with a <B>@B>, it is a reference to a named format string (either built-in one or a one created using the <B>--define-formatB> option), and is replaced with the value of the format referred to. For example, <B>--format=@cgiB> instructs the program to use <B>cgiB> format.
<B>-FB>, <B>--formfileB>, <B>--format-file=B>[NAME<B>=B>]FILE Read output format string from FILE. If NAME is supplied, assign the format string to the named format. See the section <B>FORMATB>, for a detailed discussion.
<B>-iB>, <B>--ip-list=B>FILE Read the table of <B>whoisB> servers from FILE. Each line in FILE must have the following format:


Comments are introduced with a <B>#B> sign. Empty lines are ignored.

Without this option, <B>whoseipB> uses the built-in list of servers.

<B>--importB> 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 <B>whoseipB> database dump, as produced by <B>whoseip --exportB>.
<B>-NB>, <B>--no-cacheB> Disable caching (this is the default).
<B>--single-queryB> This option is valid only in <B>inetd modeB>. It instructs <B>whoseipB> to terminate after replying to the first query.
The following options cause the program to display informative text and exit:
<B>-hB> Show a short usage summary.
<B>--helpB> Show man page.
<B>--usageB> Show a concise command line syntax reminder.


If the file <B>/etc/whoseip.confB> exists, it is read before processing command line options. If the environment variable <B>WHOSEIP_CONFB> is set, its value is used as the file name, instead of <B>/etc/whoseip.confB>.

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 <B>#B> 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 <B>--B>. 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\
    { "status": "${status}", \
    $?{diag}{"diag": "${diag}"}{\
     "country": "${country}",\
     "cidr": "${cidr}",\
     "range": "${range}",\
     "count": "${count}"}\
    $?{term}{, "term": "${term}" } }\n


Output formats can be redefined using <B>--define-formatB>, <B>--formatB>, and <B>--format-fileB> command line options, or corresponding configuration file keywords.

The format string supplied with this options (or in the input file, in case of the <B>--format-fileB> option) can contain the following macro references, which are replaced with the corresponding piece of information on output:
<B>${status}B> The reply status: <B>OKB>, if the information has been retrieved, <B>NOB>, if it was not, and <B>BADB>, if the input was invalid.
<B>${diag}B> Contains explanatory text if <B>${status}B> is <B>NOB> or <B>BADB>. If it is <B>OKB>, this macro is not defined.
<B>${item}B> Ordinal number of the request being served. Not defined in <B>CGIB> and <B>FastCGIB> modes.
<B>${term}B> The input IP address.
<B>${cidr}B> The network IP belongs to, as a <B>CIDRB>.
<B>${range}B> The network, as a range of IP addresses.
<B>${count}B> Number of IP addresses in the network.
<B>${country}B> ISO 3166-1 code of the country where IP address is located.
<B>${source}B> Where the information was obtained from. <B>QUERYB>, if it was retrieved from a remote <B>whoisB> server and <B>CACHEB>, if it was read from the cache database.
<B>${timestamp}B> Time when the record entered the database (if obtained from cache).
<B>${ttl}B> Cache entry time to live (if obtained from cache).
<B>${server}B> Whois server that returned the information.
<B>${port}B> Port used to query the whois server.
<B>${package}B> Name of the package (<B>whoseipB>).
<B>${version}B> <B>WhoseipB> 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 <B>\aB>, <B>\bB>, <B>\eB>, <B>\fB>, <B>\nB>, <B>\rB>, <B>\tB>, and <B>\vB> are replaced according to their traditional meaning.


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 <B>FastCGI modeB> has been requested, but the <B>FCGIB> module couldn’t be loaded.
73 Can’t create output file.


Only IPv4 is supported.


Sergey Poznyakoff <>


Hey! <B>The above document had some coding errors, which are explained below:B>
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
Search for    or go to Top of page |  Section 1 |  Main Index

perl v5.20.3 WHOSEIP (1) 2014-10-19

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.