Read Me

NexWhoisD v0.1_beta
------------------------------------------------------------------------
Copyright 2008 Matthew Hillman

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
------------------------------------------------------------------------
Project Homepage: http://sourceforge.net/projects/nexwhoisd

1. Important Note
2. Prerequisites
3. Building
4. Installing
5. Configuration
6. Running
7. Known Issues and Beta Limitations
8. Record Type Reference
9. Tips


1. Important Note:
 This software is BETA and as such no guarantees can be made as to its
 stability, though every effort has been taken in design and basic
 testing to ensure the code is fairly secure and robust. Added features
 and some more grace to some parts of the code is planned.


2. Prerequisites:
 * Access to a MySQL database.
 * Thread-safe libmysqlclient_r library.
   The Makefile looks in /usr/include/mysql by default.
   See: http://dev.mysql.com/doc/refman/5.0/en/threaded-clients.html


3. Building:
 In this initial beta release a full configure script etc. has not
 yet been implemented. A simple and rather static Makefile is
 included, but you may need to edit it to work on your system.

 Most people can just give the command "make" to build a server
 executable.


4. Installing:
 You should now set up the MySQL database. Create a database and use the
 stucture provided in structure.sql. Add some test data. In this beta
 version you must add data manually or with your favourite MySQL admin
 tool as there is no admnistration interface yet. You may want to refer to
 the record type reference at the end of this readme.


5. Configuration:
 The configuration file is documented in the sample nexwhoisd.conf file
 provided. By default the server looks for this file in the same directory
 as the server binary, though an alternative can be specified on the
 command line. Run the server with the -h flag for more details.

 The only mandatory configuration is the MySQL access details.


6. Running:
 Simply execute the file built in the building stage. If run as a daemon,
 no init scripts are yet provided to control its functioning, but sending
 SIGTERM will cause the server to gracefully shut down.


7. Known Issues and Beta Limitations:
 * Currently domains can only be registered to an ORG. This will be updated
   to include some more flexible record types.
 * Cannot yet run as root to bind to privileged port and drop privilegeds.
   It is recommended therefore to run the server as an unprivileged user
   on an unprivileged port.


8. Record Type Reference:
 Currently the following record types are supported (these may be improved and
 expanded in later versions):

 Domain Records
   Database table: test_domain
   Fields:
     FIELD          DESCRIPTION                             MAX SIZE
     Domain         Domain name                             200
     Org            Org handle for domain owner             25

 NET Network IP Range Records
   Database table: test_ip_net
     FIELD          DESCRIPTION	                            MAX SIZE
     NetRangeStart  Start of IP range as an int             10
     NetRangeEnd    End of IP range as an int               10
     NetHandle      Unique handle starting with NET-        25
     OrgHandle      Handle of the ORG who owns this NET     25
     TechPOC        Handle of the POC for technical issues  25
     AbusePOC       Handle of the POC for abuse issues      25

 ORG Organisation Records
   Database table: test_org
     FIELD          DESCRIPTION	                            MAX SIZE
     OrgHandle      Unique handle starting with ORG-        25
     OrgName        Name of this organisation               50
     RLContact      Real life contact point for this ORG    100
     OrgPrimaryPoc  Primary POC for this ORG                25

 POC Point-Of-Contact Records
   Database table: test_poc;
   Note: Each POC record may be only part of a whole Point-Of-Contact.
         Multiple entries with the same PocHandle are possible, and serve
         to group all records of a single contact point. Each record then
         contains a string in PocContent which is interpreted according to
         PocType, which can be either 'E' for an email address, 'U' for a
         URL or 'P' for a phone number.
     FIELD          DESCRIPTION	                            MAX SIZE
     PocHandle      Unique handle starting with POC-        25
     PocContent     The contact data for this POC record    100
     PocType        Type of contact point for this record   1


9. Tips:
 * To insert IP addresses, as for NetRangeStart and NetRangeEnd, use MySQL's
   INET_ATON() function like so:

     INSERT INTO example_tbl (example_IP) VALUES (INET_ATON('127.0.0.1'));

 * To get a list of command line options that the server accepts, run the
   server binary with the -h switch.

 * The default configuration file is called nexwhoisd.conf and is assumed
   to be located in the same directory as the server executable.

 * If you encounter errors, check syslog if the server is running as a
   daemon. One common error is when the server is shut down and restarted
   quickly. Due to the way connections are terminated in whois protocol
   sockets can be tied up in TIME_WAIT state for a while, which will
   prevent the server from rebinding that port until TIME_WAIT is cleared.
   This should not take long, so wait a while for the state to clear
   before restarting the server.