TITLE: USING RWHOIS SERVICE FOR REPORTING IP RE-ASSIGNMENT
VERSION: 0.5
SERVICE: RWHOIS v1.5.9.5
PLATFORM: FreeBSD 6.1-RELEASE-p7 (amd64)
DATE: 20010629
UPDATED: 20060920-2100
AUTHOR: Jeff Neuffer Jr. jneufferjr NO @ SPAM gmail *dot* com
PGP KeyID: 0xDD5D3FB8


NOTE: This how-to tries to detail the initial setup of the rwhois service for the purpose of reporting IP re-assignments. The perspective throughout this document is that of ISP staff personnel. It does not cover all the features/options of the rwhois server. This how-to is a work in progress. If you would like to contribute, please do so.


Some readers submitted notes on Red Hat Linux and SuSE Linux. I've listed those notes where they are applicable.




References and Credit

Reference,
1.  John Newman's "Leaping into rwhois"
http://lists.verisignlabs.com/pipermail/rwhois/1999-September/001450.html
(old link)http://lists.research.netsol.com/pipermail/rwhois/1999-September/000529.html

2.  RWhois mailing lists
http://lists.verisignlabs.com/pipermail/rwhois/

3. American Registry for Internet Numbers (ARIN)
http://www.arin.net

4. Keri Medei's 1999 RWhois howto.  Covers IP and domain setup in rwhois.
http://www.medei.com/keri/files/basicsetup
Note: The link above appears dead; I did not find an obvious reference to RWHOIS on medei.com.

5. RWhois project site
http://www.rwhois.net/


Credit,
20040225 - Benjamin Noggle, section 9.1, note added
20040119 - John Fulton, section 7.3, typos
20020328 - Darek Smehlik, section 4.2b, provided RedHat init script
20020219 - Darek Smehlik, section 5.1, and 5.7: typos



Contents
1. Intro
2. Unpack software
3. Build software
4. Initial server preparation work
5. Create the autharea
6. Test server
7. Add assignment records
8. Add your rwhois server to the "rwhois tree" (register it)
9. Miscellaneous Notes

A) To do
B) Change log





1.  Intro

For the sake of example, the below is for clearification,
- Our company's name is called "ISPWIDGET".
- Our rwhois server is called, "rwhois1.ispwidget.com".
- Customer 1 is called, "company-widget-1".
- Customer 2 is called, "company-widget-2".
- We (ISPWIDGET) has already ben issued it's initial IP allocation, a NETBLOCK of /19


2.  Unpack software

2.1  It's assumed the software has been downloaded already.  If not visit www.rwhois.net and grab yourself a fresh copy. Alternativly, you may choose to build the rwhois server out of the ports collection.  Installation of RWhois from ports is not covered here.  


> tar -zxvf rwhoisd-latest.tar.gz
> cd rwhoisd-1.5.9.5

3.  Build software

3.1  You can look through various options by running ./configure --help .  For my setup I am using the defaults and disableing IPv6 support.  


> ./configure
> make
(compile...compile...)
> su root
(password)
> make install

4.  Initial server preparation work

4.1 Create the user the server will run as.  


> adduser
  Enter username [a-z0-9_-]: rwhois
  Enter full name []: Rwhois Server
  Enter shell csh date no sh tcsh [sh]: no
  Enter home directory (full path) [/home/rwhois]: /nonexistent
  Uid [1001]: 
  Enter login class: default []: 
  Login group rwhois [rwhois]: 
  Login group is ``rwhois''. Invite rwhois into other groups: guest no [no]: 
  Enter password []: dam pwd
  Enter password again []:

  Name:     rwhois
  Password: ****
  Fullname: Rwhois Server
  Uid:      1001
  Gid:      1001 (rwhois)
  Class: 
  Groups:   rwhois 
  HOME:     /nonexistent
  Shell:    /nonexistent
  OK? (y/n) [y]:


4.2a  Create a FreeBSD startup script  


> cd /usr/local/etc/rc.d/
> vi 50rwhoisd.sh

#!/bin/sh
# This script goes in /usr/local/etc/rc.d

case "$1" in
        start)
                if [ -x /usr/local/rwhoisd/etc/rwhoisd ]; then
                        /usr/local/rwhoisd/etc/rwhoisd -c \
                        /usr/local/rwhoisd/rwhoisd.conf > \
                        /dev/null & && echo -n ' rwhoisd'
                fi
                ;;
        stop)
                /usr/bin/killall rwhoisd > /dev/null 2>&1 && echo -n ' rwhoisd'
                ;;
        *)
                echo ""
                echo "Usage: `basename $0` { start | stop }"
                echo ""
                exit 64
                ;;
esac

(save and exit)

> chmod 750 50rwhoisd.sh


4.2b  Create a Redhat Linux startup script
(This is provided for the admins who are running a Linux server.  Darek Smehlik contributed this script)


> cd /etc/init.d/
(or)
> cd /etc/rc.d/init.d
> vi rwhoisd


###
#! /bin/bash
#
# rwhoisd          Start/Stop the rhwoisd daemon.
#
#
# processname: rwhoisd
# config: /usr/local/rwhoisd/rwhoisd.conf
# pidfile: /usr/local/rwhoisd/rwhoisd.pid

# Source function library.
. /etc/init.d/functions

RETVAL=0

# See how we were called.
 
prog="rhwoisd"

start() {
        echo -n $"Starting $prog: "
        if [ -x /usr/local/rwhoisd/etc/rwhoisd ]; then
                 daemon /usr/local/rwhoisd/etc/rwhoisd -c
/usr/local/rwhoisd/rwhoisd.conf
        fi


        RETVAL=$?
        echo
        [ $RETVAL -eq 0 ]
        return $RETVAL
}

stop() {
        echo -n $"Stopping $prog: "
        killproc rwhoisd
        RETVAL=$?
        echo
        [ $RETVAL -eq 0 ]
        return $RETVAL
}

rhstatus() {
        status rwhoisd
}

restart() {
        stop
        start
}

reload() {
        echo -n $"Reloading cron daemon configuration: "
        killproc rwhoisd -HUP
        retval=$?
        echo
        return $RETVAL
}

case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  restart)
        restart
        ;;
  reload)
        reload
        ;;
  status)
        rhstatus
        ;;
 # condrestart)
 #       [ -f /usr/local/rwhoisd/rhoisd.pid ] && restart || :
 #       ;;
  *)
        echo $"Usage: $0 {start|stop|status|reload|restart}"
        exit 1
esac

exit $?
###

(save and exit)

> chmod 750 rwhoisd


4.3  Setup the rwhoisd.conf file.  The comments are removed.  For this howto I'm using the below values.  Read your local rwhoisd.conf file for other options/settings.


> cd /usr/local/rwhoisd
> vi rwhoisd.conf

#
# Main RWhois Configuration File
#
# all configuration options have the form <tag>: <value>.
root-dir: /usr/local/rwhoisd
bin-path: bin
auth-area-file: rwhoisd.auth_area
directive-file: rwhoisd.dir
x-directive-file: rwhoisd.x.dir
max-hits-ceiling: 60
register-spool:register_spool
punt-file: rwhoisd.root
local-host: rwhois1.ispwidget.com
local-port: 4321
security-allow: rwhoisd.allow
security-deny: rwhoisd.deny
deadman-time: 200
server-type: standalone
chrooted: YES
userid: rwhois
pid-file: rwhoisd.pid
server-contact: you@ispwidget.com
use-syslog: NO
default-log-file: rwhoisd.log
verbosity: 7 # debug
max-children: 30


4.4  Create needed files.  


> cd /usr/local/rwhoisd
> touch rwhoisd.log
> touch rwhoisd.pid
> touch register_spool


5.  Create the auth-area

5.1  Create the auth-area.  Comment out what is not going to be used. In this case, I commented out everything except what I was creating.    


> cd /usr/local/rwhoisd/
> vi rwhoisd.auth_area

type: master
name: 192.168.192.0/19
data-dir: net-192.168.192.0-19/data
schema-file: net-192.168.192.0-19/schema
soa-file: net-192.168.192.0-19/soa
---



5.2  Create the auth-area directory tree.  


> cd /usr/local/rwhoisd
> cp -R -p net-10.0.0.0-8 net-192.168.192.0-19

(or)

> mkdir \
  net-192.168.192.0-19 \
  net-192.168.192.0-19/attribute_defs \
  net-192.168.192.0-19/data \
  net-192.168.192.0-19/data/network \
  net-192.168.192.0-19/data/org \
  net-192.168.192.0-19/data/referral


5.3  Create the SOA file for the auth-area.  


> cd /usr/local/rwhoisd/net-192.168.192.0-19/
> vi soa

Serial-Number: 20010919000000000
Refresh-Interval: 3600
Increment-Interval: 1800
Retry-Interval: 60
Time-To-Live: 86400
Primary-Server: rwhois1.ispwidget .com:4321
Hostmaster: hostmaster@ispwidget.com

(save and exit)


5.4  Create the schema file for the auth-area.  


> cd /usr/local/rwhoisd/net-192.168.192.0-19/
> vi schema

   name: network
   attributedef: net-192.168.192.0-19/attribute_defs/network.tmpl
   dbdir: net-192.168.192.0-19/data/network
   Schema-Version: 20010920000000000
   ---
   name: organization
   attributedef: net-192.168.192.0-19/attribute_defs/org.tmpl
   dbdir: net-192.168.192.0-19/data/org
   #description: Organization object
   Schema-Version: 200109200000000000
   ---
   name: referral 
   attributedef:net-192.168.192.0-19/attribute_defs/referral.tmpl 
   dbdir:net-192.168.192.0-19/data/referral
   Schema-Version: 20010920000000000

(save and exit)


5.5  Create/Copy the attribute files for the auth-area.  


> cd /usr/local/rwhoisd/net-192.168.192.0-19/attribute_defs
> cp ../../net-10.0.0.0-8/attribute_defs/* .
> cp ../../a.com/attribute_defs/org.tmpl .


5.6  Modify files.  


> cd /usr/local/rwhoisd/net-192.168.192.0-19/attribute_defs/
> vi org.tmpl

Under "attribute: Phone", I changed, "is-required: TRUE", to "is-required: FALSE".

(save and exit)
 

> cd /usr/local/rwhoisd/net-192.168.192.0-19/attribute_defs/
> vi network.tmpl
(after "IP-Network" add below)

---
attribute:       IP-Network-Block
attribute-alias: IPNB
description:     IP address range
is-primary-key:  FALSE 
is-required:     TRUE
is-repeatable:   FALSE 
is-multi-line:   FALSE
is-hierarchical: FALSE 
index:           NONE 
type:            TEXT
---

(save and exit)
 

> cd /usr/local/rwhoisd/
> vi rwhoisd.dir

From "register: yes", to "register: no".

(save and exit)



5.7  Create the organizational data for the auth-area. 


> cd /usr/local/rwhoisd/net-192.168.192.0-19/data/org/
> vi your-comp-name.txt

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Org-Name: Ispwidget (Your Company Name)
Street-Address: P.O. Box 0000 
City: Big City
State: NC
Postal-Code: 121212
Country-Code: US
Phone: 123-456-7890
Created: 20010919
Updated: 20020204

(save and exit)



5.8  Create the network data file for the auth-area.  


> cd net-192.168.192.0-19/data/network/
> vi 192.168.192.0-19.txt
 

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Network-Name: ISPWIDGET-192.168.192.0
IP-Network: 192.168.192.0/19
IP-Network-Block: 192.168.192.0 - 192.168.223.255
Organization: Ispwidget (Your Company Name)
Tech-Contact: hostmaster@ispwidget.com
Admin-Contact: ARIN-NIC-HANDLE
Created: 20010919
Updated: 20010924
Updated-By: you@ispwidget.com

(save and exit)


5.9  Initialize the auth-area.  We are going to index our data by hand.  If all goes well, after indexing, a "done." message will appear.  To see all the options you can pass to indexer, issue bin/rwhois_indexer with out any options, and it will print a list of options.  


> cd /usr/local/rwhoisd/
> ./bin/rwhois_indexer -i -s txt
(or)
> bin/rwhois_indexer -i -v -A 192.168.192.0/19 -C network -s txt


 
6.  Test the server 

6.1  Start the server by hand to see that it starts with out errors.  Below are my results.   Depending on how you setup the files for rwhois (if you were root or another user besides the user rwhois), you may need to reset the ownership permissions on all the files.   (Optionaly you could use the startup script to start and stop the service.  I choose to do it by hand until I'm sure everything is in working order.) 

> cd /usr/local/
> chown -R rwhois.rwhois rwhoisd


> cd /usr/local/rwhoisd/
> etc/rwhoisd
debug: reading directive config file (rwhoisd.dir)
debug: reading extended directive config file (rwhoisd.x.dir)
debug: reading auth-area config file (rwhoisd.auth_area)
debug: reading schema for auth-area '192.168.192.0/19'
debug: loading attributes for class 'network' in auth-area '192.168.192.0/19'
debug: loading attributes for class 'organization' in auth-area '192.168.192.0/19'
debug: loading attributes for class 'referral' in auth-area '192.168.192.0/19'
--------------------------------
root-dir:         /usr/local/rwhoisd
auth-area-file:   rwhoisd.auth_area
directive-file:   rwhoisd.dir
x_directive-file: rwhoisd.x.dir
register-spool:   register_spool
security-allow:   rwhoisd.allow
security-deny:    rwhoisd.deny
bin-path:         bin
local-host:        rwhois1.ipswidget.com
local-port:       4321
userid:           rwhois
max-hits-ceiling: 60
max-hits-default: 20
chrooted:         YES
server-type:      DAEMON
pid-file:         rwhoisd.pid
server-contact:   you@domain.com
verbosity-level:  7
use_syslog: NO
default-log-file: rwhoisd.log
--------------------------------


6.2  Check and see if you get a greeting from the server by telneting from another computer.  The result should be something like below.  You can also do this from the server by doing, telnet localhost 4321.

> telnet rwhois1.ipswidget.com 4321

Trying rwhois1.ipswidget.com...
Connected to rwhois1.ipswidget.com .
Escape character is '^]'.
%rwhois V-1.5:003eff:00 rwhois1.ipswidget.com (by Network Solutions, Inc.V-1.5.7.3)


6.3  Stop the server.   (Optionaly you could use the startup script to start and stop the service.  I choose to do it by hand until I'm sure everything is in working order.)

> cd /usr/local/rwhoisd
> kill `cat rwhoisd.pid`





7. Add assignment records

A little background first... for the below assignments, we will have two customers who we will assign address space out of our /19 from ARIN.  Customer one we'll call "company-widget-1" and the other, "company-widget-2".   "Company-widget-1" has asked it's ISP (us) for 6 addresses for it's use (that would be 8 total address or /29.)  "Company-widget-2" has asked it's ISP (us) for a whole class-C of address space, a /24.

7.1  Setup the organizational data for "company-widget-1".


> cd /usr/local/rwhoisd/net-192.168.192.0-19/data/org/
> vi company-widget-1.txt

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Org-Name: company-widget-1
Street-Address: 123 street drive
City: Big City
State: NC
Postal-Code: 131313
Country-Code: US
Phone: 123-456-0987
Created: 20010919
Updated: 20020219

(save and exit)



7.2  Setup the network data file for "company-widget-1".


> cd net-192.168.192.0-19/data/network/
> vi 192.168.201.104-29.txt 

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Network-Name: ISPWIDGET-192.168.201.104
IP-Network: 192.168.201.104/29
IP-Network-Block: 192.168.201.104 - 192.168.201.111
Organization: Company-widget-1
Tech-Contact: hostmaster@ispwidget.com
Admin-Contact: ARIN-NIC-HANDLE
Created: 20010919
Updated: 20020219
Updated-By: you@ispwidget.com

(save and exit)



7.3  Setup the organizational data for "company-widget-2".


> cd /usr/local/rwhoisd/net-192.168.192.0-19/data/org/
> vi company-widget-2.txt

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Org-Name: company-widget-2
Street-Address: 456 street drive
City: Big City
State: NC
Postal-Code: 141414
Country-Code: US
Phone: 123-654-0987
Created: 20010919
Updated: 20020219

(save and exit)



7.4  Setup the network data file for "company-widget-2".


> cd net-192.168.192.0-19/data/network/
> vi 192.168.204.0-24.txt 

ID: NETBLK-ISPWIDGET.192.168.192.0/19
Auth-Area: 192.168.192.0/19
Network-Name: ISPWIDGET-192.168.204.0
IP-Network: 192.168.204.0/24
IP-Network-Block: 192.168.204.0 - 192.168.204.255
Organization: Company-widget-2
Tech-Contact: hostmaster@ispwidget.com
Admin-Contact: ARIN-NIC-HANDLE
Created: 20010919
Updated: 20020219
Updated-By: you@ispwidget.com

(save and exit)



7.5  Update the auth-area with the new assignments.  We are going to index our data by hand.  If all goes well, after indexing, a "done." message will appear.  To see all the options you can pass to indexer, issue bin/rwhois_indexer with out any options, and it will print a list of options.  


> cd /usr/local/rwhoisd/
> bin/rwhois_indexer -v -A 192.168.192.0/19 -C network -s txt



7.6  Perform a query test from another computer.  The result should be a dump of all the records you have created.  You can also do this from the server by doing, telnet localhost 4321.

> telnet  rwhois1.ipswidget.com 4321

Trying rwhois1.ipswidget.com...
Connected to rwhois1.ipswidget.com .
Escape character is '^]'.
%rwhois V-1.5:003eff:00 rwhois1.ipswidget.com (by Network Solutions, Inc.V-1.5.7.3)

-xfer 192.168.192.0/19

%xfer network:Class-Name:network
%xfer network:ID:NETBLK-ISPWIDGET.192.168.192.0/19
%xfer network:Auth-Area:192.168.192.0/19
%xfer network:Network-Name:ISPWIDGET-192.168.192.0/19
%xfer network:IP-Network:192.168.192.0/19
%xfer network:IP-Network-Block:192.168.192.0 - 192.168.223.255
%xfer network:Organization:Ispwidget
%xfer network:Tech-Contact:hostmaster@ispwidget.com
%xfer network:Admin-Contact:ARIN-NIC-HANDLE
%xfer network:Created:20020219
%xfer network:Updated:20020219
%xfer network:Updated-By:you@ispwidget.com
%xfer
%xfer network:Class-Name:network
%xfer network:ID:NETBLK-ISPWIDGET.192.168.192.0/19
%xfer network:Auth-Area:192.168.192.0/19
%xfer network:Network-Name:ISPWIDGET-192.168.201.104
%xfer network:IP-Network:192.168.201.104/29
%xfer network:IP-Network-Block:192.168.201.104 - 192.168.201.111
%xfer network:Organization:Company-widget-1
%xfer network:Tech-Contact:hostmaster@ispwidget.com
%xfer network:Admin-Contact:ARIN-NIC-HANDLE
%xfer network:Created:20020219
%xfer network:Updated:20020219
%xfer network:Updated-By:you@ispwidget.com
%xfer
%xfer network:Class-Name:network
%xfer network:ID:NETBLK-ISPWIDGET.192.168.192.0/19
%xfer network:Auth-Area:192.168.192.0/19
%xfer network:Network-Name:ISPWIDGET-192.168.204.0
%xfer network:IP-Network:192.168.204.0/24
%xfer network:IP-Network-Block:192.168.204.0 - 192.168.204.255
%xfer network:Organization:Company-widget-2
%xfer network:Tech-Contact:hostmaster@ispwidget.com
%xfer network:Admin-Contact:ARIN-NIC-HANDLE
%xfer network:Created:20020219
%xfer network:Updated:20020219
%xfer network:Updated-By:you@ispwidget.com
%xfer
%ok


8. Add your rwhois server to the "rwhois tree" (register it)

8.1  This is done by visiting http://www.arin.net.  Stop by http://www.arin.net/library/ and look for the template section.  You may define your rwhois server when you initially setup your organization with ARIN.  If you are already setup and moving to a rwhois server, you will have to modify your organization data with ARIN.  The templates have detailed instructions at the bottom of them that explain who you should send the email too, and what additional requirements are needed to submit the template.



9. Miscellaneous Notes

9.1  From: Benjamin Noggle  Date: 2/16/2004


Hello,

Thanks for the great howto.  I used it and it worked great.  One problem I had though, was that I installed on a Redhat linux 9 distro, and there locale is different.  Querying for objects was very sporadic and I kept getting "object not found" when the index file referenced my query string.

This has been documented on the mailing list, but since its not searchable it took my a while to find it:
http://lists.verisignlabs.com/pipermail/rwhois/2002-March/001772.html

Its also mentioned a few other times on the list as snagging people.  Hence I would think it be a good thing to add to the howto.

Adding this to the init.d script:
LC_ALL="C"
export LC_ALL

And mentioning to export it during the indexing also.

Thanks,
Benjamin
Liquid Web Inc.




This is a work in progress.  Please report errors, comments to the email address at the top of the page, thank you.

A) To do

- Test build process on FreeBSD 5.x
- Cover registering a new rwhois server with ARIN.  (requested)


B) Change-log (modifications, additions, corrections)

20050624 - Updated PGP KeyID
         - "References and Credit" hyper-links were outdated.

20040302 - Added my PGP KeyID

20040225 - Added section 9
         - Added notes in section 9.1 (Benjamin Noggle)
         - Updated section 8
         - Fixed broken link in reference section

20040119 - Corrected typos in section 7.3 (John Fulton)

20020328 - Added section 4.2b which covers the Redhat Linux init script (Darek Smehlik)
         - Modified the initial comments in section 6.1 and 6.3
         - Added reference to Keri Medei's rwhois howto (1999)
         - Added link to rwhois.net

20020219 - Created contents
         - Re-ordered some sections
         - Created "add assignment records"
         - Created "Intro"
         - Fixed typos in section 5.1 and 5.7