   This file documents JWHOIS, a Whois client.

   Copyright (C) 1999  Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   This file documents the GNU jwhois package, en extended Whois client.
This is edition 2.4, for jwhois version 2.4, last updated 28 December
1999.

Introduction
************

   JWHOIS is an Internet Whois client that queries hosts for information
according to RFC 954 - NICNAME/WHOIS. JWHOIS is configured via a
configuration file that contains information about all known Whois
servers.  Upon execution, the host to query is selected based on the
information in the configuration file.

   The configuration file is highly customizable and makes heavy use of
regular expressions.

Invocation
**********

   JWHOIS uses the following command-line options:
`--version'
     Print the program version and licensing information.

`--help'
     Print a usage message summarizing the command-line options.

`-c FILE'

`--config=FILE'
     Reads configuration from FILE instead of from the default system
     global configuration file.

`-h HOST'

`--host=HOST'
     Overrides any specifications in the configuration file and queries
     HOST directly.

`-p PORT'

`--port=PORT'
     Specifies a port number to use when querying a HOST

`-f'

`--force-lookup'
     This option forces the client to look up an entry from the source
     Whois server, even if a current copy is available in the system
     cache.

`-d'

`--disable-cache'
     This disables the cache functionality.

`-v'

`--verbose'
     Enables verbose debugging output where available.

   The query can optionally contain the character `@' followed by a
host name to direct the search to that host. This works exactly like
specifying the host with `--host'.

RIPE Extensions
***************

   RIPE (Réseaux IP Européens) has defined a number of options that can
be used against a RIPE-compatible whois server (ripe.net, apnic.net and
others).  Unfortunately, there is really no way of telling whether a
host we are connecting to is RIPE-compatible or not.  RIPE extensions
are therefore not directly incorporated into the JWHOIS client.  A list
of the options can be found in RIPE Document 157 which you can get from
the RIPE ftp server, <ftp://ftp.ripe.net/ripe/docs/>.

   It is possible to use these options together with JWHOIS by changing
the format of the query slightly. If you were to search for all entries
in the RIPE database which lists the admin-c, tech-c or zone-c as
CO19-RIPE, you could use the following command syntax:

     $ jwhois -h whois.ripe.net -- -i admin-c,tech-c,zone-c CO19-RIPE

   `--' is used to separate the RIPE options from the jwhois options.

Site Configuration
******************

   JWHOIS is configurable via its configuration file, normally called
`jwhois.conf'. This file is looked for in the sysconfdir that was
specified when compiling the program (default is `/usr/local/etc/' on
most systems).

   If no configuration file can be found, JWHOIS will default all
queries to <whois.internic.net>.

   An example configuration file that includes most known Whois servers
can be found in the `example' subdirectory of the official distribution.

   The configuration file is split into a number of blocks. Each block
can contain a number of different options which are explained in the
sections below. You can also get an overview of the syntax by looking
at the example configuration file included in the distribution.

Global
******

   The only available global options are related to the cache features
in jwhois Cache Functionality.  By default, the location of the
configuration file is `/usr/local/var/jwhois.db', but this can be
changed at compile time. The option `cachefile' also changes the
location.

   The default expire time for all cached objects it 7 days (168
hours). this can be changed with the `cacheexpire' option. The value is
the number of hours that objects is considered to be current.

   Example:

     cachefile = "/var/lib/jwhois.db";
     cacheexpire = 168;

Whois-servers
*************

   When making a query, JWHOIS looks at the `whois-servers' block to
determine which host to send the query to. The option `type' can be set
to change between two different kinds of matching; `cidr' or `regex'.

   `regex' matches using standard regular expressions.  `cidr' matches
using CIDR net blocks.

   The value of all objects can take one of two forms. Either a
hostname or the special option `struct'. The later asks JWHOIS to look
at another option block in the configuration file.

   When matching using CIDR net blocks, the key can take the special
value `default' which matches everything.

     whois-servers {
             type = regex;
             ".*-[A-Z]+$" = "struct handles";
             ".*" = "whois.internic.net";
     };
     handles {
             type = regex;
             ".*-RIPE$" = "whois.ripe.net";
             default = "whois.arin.net";
     };

Content-redirect
****************

   `content-redirect' is a special block designed to parse the output
returned by a Whois server looking for special regular expressions and
then sending the same query to the Whois server gotten from the regular
expression.

   The key value is the name of the Whois server that this expression
is applicable to. This is matched using regular expressions. The value
is the regexp that is looked for in the output, with hostname and
optional port number enclosed in so called subexpressions or groups.

     content-redirect {
             ".*" = ".*Whois Server: \\(.*\\)";
     };

Cache Functionality
*******************

   JWHOIS implements support for maintaining a cache of Whois data
received from Whois servers. This is NOT enabled by default but has to
be compiled into the client specifically. The design is such that a
central database is maintained by the client and because all users
should have access to that database, the program must have the
set-group-on-execution bit set and the database must be both read and
writable by the group.

   The configuration options available are CACHEFILE and CACHEEXPIRE
which sets the database filename and the expire time for cached object.
When an object expires from the cache, it is reloaded from the Whois
server the next time it is requested. The expire time is measured in
hours.

Reporting bugs
**************

   Email bug reports to `bug-jwhois@gnu.org'.