aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2014-10-09 18:56:56 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2014-10-09 18:56:56 +0300
commit16ee098b02aa7a799c632d004f35278a83aec1df (patch)
treecb9bc7c8485de814fbe3185b5fb4374b2fa63c25
parent1fa48747874722e7c2278eb21b851f7e945ff2d2 (diff)
downloaddnstools-16ee098b02aa7a799c632d004f35278a83aec1df.tar.gz
dnstools-16ee098b02aa7a799c632d004f35278a83aec1df.tar.bz2
whoseip: finish the docs.
-rw-r--r--whoseip/whoseip.pl178
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.

Return to:

Send suggestions and report system problems to the System administrator.