Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
WHOSEIP(1)	      User Contributed Perl Documentation	    WHOSEIP(1)

       whoseip - return	information about IP address

       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...]

       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

       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="">

       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 FORMAT below for	a discussion on	how to customize
       output formats.

       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.

	   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

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

       -d, --debug
	   Increase debugging verbosity.

	   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

	   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.

	   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:


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

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

	   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

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

	   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

       -h  Show	a short	usage summary.

	   Show	man page.

	   Show	a concise command line syntax reminder.

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

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

       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:

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

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

	   Ordinal number of the request being served.	Not defined in CGI and
	   FastCGI modes.

	   The input IP	address.

	   The network IP belongs to, as a CIDR.

	   The network,	as a range of IP addresses.

	   Number of IP	addresses in the network.

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

	   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.

	   Time	when the record	entered	the database (if obtained from cache).

	   Cache entry time to live (if	obtained from cache).

	   Whois server	that returned the information.

	   Port	used to	query the whois	server.

	   Name	of the package (whoseip).

	   Whoseip version number.

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

       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.

       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.

       Only IPv4 is supported.

       Sergey Poznyakoff <>

       Hey! The	above document had some	coding errors, which are explained

       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.32.1			  2014-10-19			    WHOSEIP(1)


Want to link to this manual page? Use this URL:

home | help