diff options
-rw-r--r-- | whoseip/whoseip.pl | 178 |
1 files changed, 177 insertions, 1 deletions
diff --git a/whoseip/whoseip.pl b/whoseip/whoseip.pl index 3cfdd83..51ea369 100644 --- a/whoseip/whoseip.pl +++ b/whoseip/whoseip.pl @@ -708,6 +708,115 @@ B<whoiseip> =head1 DESCRIPTION +For each IP address, B<whoseip> returns the country it is located in +(a ISO 3166-1 code), the network it belongs to and the number of addresses +in this network. + +The program can operate in several modes. + +If the program name ends in B<.fcgi> the B<Fast CGI> mode is enabled. +This mode is also enabled if the command line option B<--fastcgi> is +given without arguments, or if the program name ends in one of the +suffixes supplied in its argument (a whitespace-separated list). + +Otherwise, when one or more IP addresses are given in the command line, +B<whoseip> prints the data for each of them on the standard output. +This is B<command line> mode. + +If called without arguments, the program checks if the environment variable +B<GATEWAY_INTERFACE> is defined and contains B<CGI/I<V>> (where I<V> is the +version number). If so, it assumes B<CGI> mode. In this mode, the IP +address to query for is taken from the environment variable QUERY_STRING. +It can contain either IP address alone, or prefixed with B<ip=>. + +If B<GATEWAY_INTERFACE> is not set, the program reads IP addresses from +input (one per line) and prints replies for each of them. This is B<inetd +mode>. + +To summarize: + +=over 4 + +=item 1. + +Start it from the command line with one or more IPs given as arguments, if +you wish to get info about these IPs. + +=item 2. + +Add it to B</etc/inetd.conf> if you want to query it remotely as a service, +e.g.: + + whois stream tcp nowait nobody /usr/bin/whoseip + +=item 3. + +Copy it to your B<cgi-bin> directory to use it with a B<http> server as a +B<CGI>. + +=item 4. + +Link it to B<whoseip.fcgi> to use it as a B<FastCGI> application (or use +the B<--fastcgi> option). + +=back + +Output formats are configurable and depend on the mode B<whoseip> runs +in. In command line and inetd modes, the default output format is: + +=over 4 + +B<OK> I<COUNTRY> I<CIDR> I<RANGE> I<COUNT> + +=back + +where I<COUNTRY> is country code, I<CIDR> is network block in CIDR notation, +I<RANGE> is network block as a range of IP addresses, and I<COUNT> is +number of IP address in the network block. + +If the specified IP address is not found, the reply is + +=over 4 + +B<NO> I<TEXT> + +=back + +where I<TEXT> is a human-readable explanatory message. + +If the input is invalid, the reply is: + +=over 4 + +B<BAD> I<TEXT> + +=back + +In B<CGI> and B<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 B<FORMAT> below for a discussion on how to customize +output formats. + =head1 OPTIONS =over 4 @@ -743,7 +852,11 @@ in B<.fcgi>. =item B<-f>, B<--format=>I<STRING> -Sets output format string. +Sets output format string. If I<STRING> begins with a B<@>, it is +a reference to a named format string (either built-in one or a one +created using the B<--define-format> option), and is replaced with +the value of the format referred to. For example, B<--format=@cgi> +instructs the program to use B<cgi> format. =item B<-F>, B<--formfile>, B<--format-file=>[I<NAME>B<=>]I<FILE> @@ -816,6 +929,69 @@ For example: =head1 FORMAT +Output formats can be redefined using B<--define-format>, B<--format>, +and B<--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 B<--format-file> option) can contain the following macro +references, which are replaced with the corresponding piece of information +on output: + +=over 4 + +=item B<${status}> + +The reply status: B<OK>, if the information has been retrieved, +B<NO>, if it was not, and B<BAD>, if the input was invalid. + +=item B<${diag}> + +Contains explanatory text if B<${status}> is B<NO> or B<BAD>. If +it is B<OK>, this macro is not defined. + +=item B<${term}> + +The input IP address. + +=item B<${cidr}> + +The network IP belongs to, as a B<CIDR>. + +=item B<${range}> + +The network, as a range of IP addresses. + +=item B<${count}> + +Number of IP addresses in the network. + +=item B<${country}> + +ISO 3166-1 code of the country where IP address is located. + +=back + +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: + +=over 4 + +B<$?{I<NAME>}>B<{>I<TEXT-IF-TRUE>B<}>B<{>I<TEXT-IF-FALSE>B<}> + +=back + +Its effect is as follows: if the macro I<NAME> is defined, the +I<TEXT-IF-TRUE> is substituted, otherwise the I<TEXT-IF-FALSE> +is substituted. Conditional expressions can be nested. + +The escape sequences B<\a>, B<\b>, B<\e>, B<\f>, B<\n>, B<\r>, +B<\t>, and B<\v> are replaced according to their traditional +meaning. + =head1 BUGS Only IPv4 is supported. |