WHOSEIP(1) User Contributed Perl Documentation WHOSEIP(1)NAMEwhoseip - 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
perl v5.20.2 2014-10-19 WHOSEIP(1)
