jwhoisserver :: Java Whois Server

This HowTo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY!

This document referes to JWhoisServer 0.2.0.0.
The newest version of this document may be found at the sourceforge homepage of jwhoisserver

JWhoisServer is hosted on sourceforge All files and documentations may be downloaded from there.

.

Table of contents:

Preface
1. Installation
2. Configure Database
- 2.1 Create Database and User
- 2.2 Configure DB-Settings for JWhoisServer
3. Start and Test it ...
4. Advanced Configuration
5. Notes: java versions
6. Notes: Log Levels
7. Notes: Performance

Preface

JWhoisServer is a a small, fast and highly configurable RFC 3912 compliant whois server written in java and using a RDBMS as a storage engine.

Features:

small and fast
platform independent: (tested on different Linux distributions and MS Windows) it should run everywhere where a java VM is available.
highly configurable: the provided database is only a sample; JWhoisServer can be configured to work on nearly any database structure.
Database environment

Suppoported RDBMS:

mysqldefault
PostgreSQL
firebird2
SQLite3
HSQLDB(standalone or server)

Other may be supported in the future ...

Support for other databases except mysql should be considered as experimental!

Explanations of the syntax conventions used in this document:

simple monotype text is referring to filenames or filesystem-paths
black monotype text on white background marks text of a configuration file
white monotype text on black background marks instructions / commands that must be executed in the shell

1. Installation

1.1 Prerequisites

Running JWhoisServer requires:

Java Runtime developed using sun java 1.4 and 1.5, but it some (more or less) positive tests have been run using gij and other alternative VMs.
log4j java library
mysql-java-connector and / or jdbc drivers for the other supported RDBMS
whois - client (whois, jwhois, ...)

Building JWhoisServer from source additionally requires:

Java compiler (since version 0.0.3.0 jdk 1.5 is required)
ant make tool

jump to the table of contents

1.2 Installation From Source

Download the source-file JWhoisServer-VERSION-src.tar.gz and extract it:

tar xvz -f JWhoisServer-VERSION-src.tar.gz

Change working directory into the build of the extracted source directory:

cd JWhoisServer-VERSION/build

Use the following command to get some help about how to configure the right classpath and install-dirs:

ant help-classpath ant help-install

A comfortably way to configure some parameters may be to edit the file build.properties or to pass them to the ant invocation.
Build and install:

ant -Dpackage.log4j.jar=/usr/share/java/log4j.jar \ -Dpackage.jdbc.mysql.jar=/usr/share/java/mysql-connector.jar \ -Dpackage.installdir.etc=/etc/jwhoisserver \ -Dpackage.installdir.init=/etc/init.d \ jar jar-install

Remark that the install-jar target requires root privileges!

jump to the table of contents

1.3 Installation using .deb-Package

Install required packages:

apt-get install debconf liblog4j1.2-java libmysql-java sun-java5-jre whois debianutils dbconfig-common

If you like JWhoisServer to use a local mysql database, you will have to install mysql-server:

apt-get install mysql-server

Download the .deb-package and install it:

dpkg -i jwhoisserver_VERSION_all.deb

If you decide to use a local database answer yes to the question if dbconfig should automatically configure the database!

jump to the table of contents

1.4 Installation using .rpm-Package

Install all required software using your favorite package manager before you install JWhoisServer!
Download the .rpm-package and install it:

rpm -i jwhoisserver-VERSION.noarch.rpm

1.5 Upgrade

If you installed the .deb-package and choose to let dbconfig do the work for you this step is obsolete for you, so please skip it!

If you upgrade JWhoisServer from a previouse version take a look at the sql-directory for files named update_$version.sql.
$version refers to the previose version of JWhoisServer.
So if you upgrade from 0.1.0.1 to 0.1.0.2 you will have to apply the script update_0.1.0.1.sql.

mysql -u root -p jwhoisserver < update_0.1.0.1.sql

Multiple update-files have to be applied in sequential order starting from the lowest version.
The required SQL-scripts may be found at different locations depending on the installation type:

SRC	sql directory of the extracted source
DEB	/usr/share/doc/jwhoisserver/
RPM	/usr/share/doc/packages/jwhoisserver/

2. Configure Database

JWhoisServer uses a mysql database as storage backend. This requires some additional configuration steps. The description provided here assume that the database will be installed on the same host running JWhoisServer, but you can use a mysql-database running on a remote host.

2.1 Create Database and User

If you installed the .deb-package and choose to let dbconfig do the work for you this step is obsolete for you, so please skip it.
The required SQL-scripts may be found at different locations depending on the installation type:

SRC	sql directory of the extracted source
DEB	/usr/share/doc/jwhoisserver/
RPM	/usr/share/doc/packages/jwhoisserver/

Here a short description of the SQL-scripts:

db.sql: create database
user.sql: create user (you may like to edit this file to create the user with a different password)
struct.sql: database structure (create tables)
data.sql: basic data
optional: test.sql: simple dataset to run first tests
optional: droptables.sql: erase all tables from DB
optional: collate.sql: set charset and collation to UTF8

To create the database, user and table use the following commands:

mysql -u root -p < db.sql mysql -u root -p < user.sql mysql -u root -p jwhoisserver < struct.sql mysql -u root -p jwhoisserver < data.sql

To insert a small dataset for testing, read in test.sql

mysql -u root -p jwhoisserver < test.sql

jump to the table of contents

2.2 Configure DB-Settings for JWhoisServer

To configure JWhoisServer to use the current created database edit the configuration file (default: /etc/jwhoisserver/server.cfg) and adjust the following settings if required (the values shown here are the defaults):

db.type=mysql db.host=localhost db.port= db.name=jwhoisserver db.user=jwhoisserver db.pass=jwhois

For additional settings see: server.cfg or sample.cfg

3. Start and Test it ...

First test if JWhoisServer is configured right by starting JWhoisServer as user root (if you have installed JWhoisServer from source and configured an non-standard bin-directory, you may need to invoke jwhoisserver using the full path):

jwhoisserver

If the server starts fine, try your first query:

whois -h localhost -- test.tld

3.1 init-script for jwhoisserver

If every thing works, you may use the init-script /etc/init.d/jwhoisserver to start and control JWhoisServer:

# /etc/init.d/jwhoisserver Usage: /etc/init.d/jwhoisserver {start|stop|restart|force-reload|status|stats|statistics}

status and stats|statistics require a whois-client in PATH

jump to the table of contents

3.2 Command Line Arguments for jwhoisserver

Command-Line arguments understood by JWhoisServer:

# jwhoisserver -? Java Whois Server 0.2.0.0 (c) 2006 - 2008 Klaus Zerwes zero-sys.net Syntax: jwhoisserver [-h|-?] [-L] [-V] [-p|-m|-j] jwhoisserver [-v|-d|-q] [-c|-x cfg] [-l lcgf] -c cfg run using configuration from file cfg instead of the default: /etc/jwhoisserver/server.cfg -x cfg run using configuration from XML-file cfg (deprecated) -l lcfg run using configuration for log4j from file lcfg instead of the default: /etc/jwhoisserver/log4j.cfg -v verbose -d debug -q quiet -h|-? display help -L display license -V display version -p print configuration -m print configuration as XML (deprecated) -j print a list of supported database types

jump to the table of contents

3.3 Exit Codes of jwhoisserver

0	OK
1	ERROR: syntax error in invocation (wrong argument / missing parameter / ...)
2	ERROR: connection to the db failed
3	ERROR: unable to open socket
10	ERROR: wrong server.bind
11	ERROR: wrong server.port
12	ERROR: syntax error at server.stats.allowfrom
13	ERROR: syntax error at server.html.allowfrom
14	ERROR: syntax error at server.shutdown.allowfrom
15	ERROR: db.objectlookupdefault is set to a value that is not configured as a lookup
16	ERROR: db.objectlookupdefault is unconfigured
17	ERROR: syntax error at server.stats.numformat
18	ERROR: server.stats.numformat not set
21	ERROR: syntax error in config for maxlenght value of a querytype
22	ERROR: syntax error in config for regex value of a querytype
23	ERROR: syntax error in config for lookupallowfrom value of a querytype
24	ERROR: syntax error in config for db.fkey.identify
100	ERROR: error closing socket on shutdown

A up-to-date list may be found in the file EXITCODES.txt

jump to the table of contents

3.4 Syntax of the whois-requests

$ whois -h localhost -- help # HELP # SYNTAX: whois [-h hostname] [-r] [-f] [-T t] key # -r suppress recursion in lookups # -f generate html-formated display (maybe restricted access) # -T t lookup only for specified type t # implemented types: # dn|domain domain (default) # key lookup for key # special keys: # HELP|? display this help # STATUS display status information # STATS display statistical informations (restricted access)

"implemented types" depend on the configuration of JWhoisServer.

4. Advanced Configuration

For a complete List of available configuration properties see sample.cfg and / or the output of jwhoisserver -p

4.1 Advanced Configuration: Main Configuration Properties

JWhoisServer uses so called display-objects.
The starting point for configuring display-objects is the configuration property db.objectlist. This should contain names of possible display-objects (usually tables). To configure multiple display-objects us a list separated by the value of db.listseparator (default: ;).
Example:

db.objectlist=domain;person;mntnr;nameserver

Each defined display-object may be configured using a subset of properties to db.$OBJECTNAME:

property	description	example
.table	SQL - table name for object; defaults to $OBJECTNAME	db.domain.table=domain
.key	Name of the key (used for key-queries); defaults to ${table}_key	db.domain.key=domain_key
.qfield	Define the query field for non-key-queries. (defaults to $OBJECTNAME)	db.domain.qfield=domain
.display	SQL - field-list used to display this object separated by db.listseparator. (defaults to $OBJECTNAME) The key will allways be included in the query, he output is configurable by .handleprefix	db.domain.display=domain;mntnr_fkey;changed
.displayshort	SQL - field - list used to generate a "non-recursive" display of this object separated by db.listseparator. If not configured, .display will be used. This will be used to generate the display for non-recursive lookups.	domain;'active' AS status
.handleprefix	String as prefix for key to generate unique handle; If this property is set (even if it is a empty string) the key of the object will be displaied prepended by the value of the property. If the property is not configured, the key will be excluded from the output.	db.domain.handleprefix=DMN
.objectlookup	If this object should be a lookup-object (selectable via -T), configure a list of lookup definitions separated by db.listseparator	db.domain.objectlookup=domain;dn
.lookupallowfrom	If this object is configured as a lookup and you like to restrict access to this lookup - type, list the IPs/networks allowd here separated by db.listseparator. IPs/networks may be single host or networks in CIDR (/25) or dotted decimals notation.	db.person.lookupallowfrom=10.10.10.101;192.168.2.0/24
.match	If this object is configured as a lookup you may like to define a regular expression to match a lookup.	db.domain.match= ^[a-z0-9]?+tld$
.maxlength	Maximum allowed length of a lookup.	db.domain.maxlength=255
.match.errorstring	String to be displayed as a error message if a lookup fails to match defined regular expression.	db.domain.match.errorstring=ERROR\r\n
.parent.$PARENTOBJECTNAME	Define a SINGLE fieldname that will be used as a foreign key for the display-object $OBJECTNAME. The data will be displayed inline, that means instead of the defined field using a non-key-query on the object $PARENTOBJECTNAME.	db.domain.parent.nameserver=domain_fkey
.recursecondition	Define a SINGLE fieldname. The field will be added to the query for *$OBJECTNAME* and if the value for the field will not evaluate to "true" or 1 recursion will be disabled.	db.domain.recursecondition=publicviewabledata
.recurse.$RECURSEOBJECTNAME	Define a list of fields; Each field will be handled as a key for *$RECURSEOBJECTNAME* and a new display-object of type $RECURSEOBJECTNAME will be generated using a key-query.	db.domain.recurse.person=holder;admin_c;tech_c;zone_c
.whereaddition	Additional string to be appended to WHERE-part of the query.	db.domain.whereaddition=\ AND disabled \= 0
.tablejoin	Additional string appended after SELECT ... FROM tablename (useful for joins)	db.person.tablejoin= LEFT JOIN country ON country_key\=country_fkey
.matchkey	stupid sql driver: if you use tablename.fieldname in the select statement, getColumnLabel reports only fieldname so we need a special test some times	db.person.matchkey=id

Since version 0.2.0.0 there exists 2 new configuration properties effecting the handling of non-recursive foreign keys:

db.fkey.identify: a string identifying a foreign key column name (defaults to: _fkey)
db.fkey.replace: string (will be used as a replacement for db.fkey.identify) (defaults to empty string)
These properties are considered as experimental and may be changed or removed in the future.

jump to the table of contents

4.2 Configure a additional lookup

Lets assume you want to enable lookups on the person-object from localhost, then you should extend your config:

db.person.objectlookup=person;pn db.person.qfield=name db.person.lookupallowfrom=127.0.0.1

and try it out:

$ whois -h localhost -- -T pn persona non grata This is JWhoisServer serving ccTLD tld Java Whois Server 0.0.3.0 (c) 2006 - 2007 zero-sys.net Klaus Zerwes ... handle: PRSN1 mntnr: MNTNR1 type: PERSON name: persona non grata address: two dead ends pcode: NWR country: AX phone: +77 31 123454321 fax: +77 31 123454321 email: mail@domain.tld changed: 2006-10-14 16:20:00

As you can see the HELP-reply of the server will get automatical updated:

$ whois -h localhost -- help # HELP # SYNTAX: whois [-h hostname] [-r] [-f] [-T t] key # -r suppress recursion in lookups # -f generate html-formated display (maybe restricted access) # -T t lookup for specified type t # implemented types: # dn|domain domain (default) # pn|person person # key lookup for key # special keys: # HELP|? display this help # STATUS display status information # STATS display statistical informations (restricted access)

jump to the table of contents

4.3 Configure JWhoisServer to run on a different database structure

Using the informations above, you can configure JWhoisServer to run on your own database using your defined data-structure. To be continued ...

5. Notes: java versions

The recommended java runtime to run JWhoisServer is sun jre 1.5 (1.4 works with the restriction that you can not read or print the configuration from / to XML).
Short tests have been (more or less) successful using gij 4.1, SableVM (1.13), JamVM (1.4.4) and kaffe VM (1.1.7).

6. Notes: Log Levels

There are 2 ways to configure the log levels:

using command line args:
1. -v : verbose
2. -d : debug
3. -q : quiet
using configuration properties:
1. server.loglevel.connect
2. server.loglevel.main
3. server.loglevel.db
Example: set server.loglevel.connect=0 to disable logging connections.

7. Notes: Performance

Here are some stats:
(connection-logging disabled!)

OS	CPU	MEM	java version	Notes
Linux (debian 4.0)	AMD-K6-III	512M	Blackdown-1.4.2-03	some test clients running on same device
status of Java Whois Server: uptime: 0 days 18:22:32 (66152 seconds); dbconn:1 mem used / avail / max: 5457 / 7608 / 65088 conn total: 2124260 conn errors: 0 client errors: 1 access violations: 2 regex errors: 167 domain to long: 0 requests recursive: 2123297 requests non-recursive: 748 requests html-formated: 14720 requests stats: 40 requests status: 3 requests help: 2 sql statements: 12740533 sql errors: 0 db errors: 0 average client time: 36.33 (77177962/2124260) average sql time: 1.52 (19389799/12740533)

Microsoft Windows XP pro SP2	AMD-Athlon64-3000+	1G	1.4.2_12	mysql server running on other device
status of Java Whois Server: uptime: 0 days 00:16:40 (1000 seconds); dbconn:1 mem used / avail / max: 1327 / 1984 / 65088 conn total: 157434 conn errors: 0 client errors: 1 access violations: 0 regex errors: 0 requests recursive: 48810 requests non-recursive: 108611 requests html-formated: 2934 requests stats: 12 requests status: 0 requests help: 0 sql statements: 401471 sql errors: 0 db errors: 0 average client time: 4.50 (708418/157433) average sql time: 1.07 (428249/401471)

Microsoft Windows XP pro SP2	AMD-Athlon64-3000+	1G	1.6.0_01	mysql server running on other device
status of Java Whois Server: uptime: 0 days 00:18:26 (1106 seconds); dbconn:1 mem used / avail / max: 3013 / 5056 / 65088 conn total: 174771 conn errors: 0 client errors: 0 access violations: 0 regex errors: 0 requests recursive: 60305 requests non-recursive: 114444 requests html-formated: 3432 requests stats: 20 requests status: 1 requests help: 1 sql statements: 476275 sql errors: 0 db errors: 0 average client time: 4.83 (844203/174770) average sql time: 1.02 (484905/476275)

Linux (debian 4.0) x86_64	2x Intel Xeon 3.00GHz	2G	64-Bit Server VM 1.5.0_10-b03	mysql server running on same device
status of Java Whois Server: uptime: 0 days 00:15:00 (900 seconds); dbconn:1 mem used / avail / max: 57624 / 77952 / 458752 conn total: 607300 conn errors: 0 client errors: 0 access violations: 0 regex errors: 0 requests recursive: 333429 requests non-recursive: 273855 requests html-formated: 141196 requests stats: 14 requests status: 0 requests help: 0 sql statements: 2274430 sql errors: 0 db errors: 0 average client time: 1.65 (1004695/607300) average sql time: 0.12 (271448/2274431)

Linux (debian 4.0) x86_64	2x Intel Xeon 3.00GHz	2G	64-Bit Server VM 1.5.0_10-b03	mysql server running on same device
statistics for Java Whois Server: uptime: 0 days 00:46:48 (2808 seconds); dbconn:1 mem used / avail / max: 59966 / 192448 / 458752 conn total: 2030502 conn errors: 0 client errors: 0 access violations: 0 regex errors: 0 requests recursive: 1109683 requests non-recursive: 920796 requests html-formated: 458405 requests stats: 22 requests status: 0 requests help: 0 sql statements: 7578894 sql errors: 0 db errors: 0 average client time: 1.62 (3295066/2030502) average sql time: 0.12 (901342/7578894)

JWhoisServer Java Whois Server

Installation Guide