Update TODO based on work for 0.4.1

[python-rwhoisd.git] / README

diff --git a/README b/README
index 762a30f..aaa8895 100644 (file)
--- a/README
+++ b/README
@@ -1,26 +1,53 @@
-WHAT IS IT?
-
-As a programming exercise for learning Python, I wrote a simple rwhois
-server.  It uses in-memory data structures, and it intuits
-the schema based on the data it sees.  The server as input takes a
-schema file, which for now just describes which attributes should be
-indexed (and how), and data files which look much like the C rwhoisd's
-data files.
+WHAT IS THIS?
+
+In 2003, as a programming exercise for learning Python, I wrote a
+simple rwhois server (described in RFC 2167).  It uses in-memory data
+structures, and it intuits the schema based on the data it sees.  The
+server takes as input a schema file, which for now just describes
+which attributes should be indexed (and how), and data files which
+look much like the C rwhoisd's data files.
+
+This version supports a sort of extended query syntax: IP or CIDR
+queries ending in "**" will result in a "subnet" search, where all of
+the found subnets at or below the specified network will be returned.
+Ending a IP or CIDR query with a single "*" will result in a
+"supernet" search, returning all the networks enclosing the queried
+network.  (A plain network query will return the closest enclosing
+network, including matching networks).
+
+It supports (as of v0.4) IPv6 CIDR networks and network blocks, and
+supports indexing network-block type values.  That is, you can index
+values like "10.131.10.0 - 10.131.11.255" and "3ffe:4:5::0 -
+3ffe:4:6::ffff".
 
 REQUIREMENTS
 
-python 2.2 or later
+python 2.2 or later.
 
 INSTALL
 
-For now, just run it from the source directory:
+This can be run from it's source directory, which is a fine way to do
+it.
+
+However, if you wish to install it, as root:
+
+% python setup.py install
+
+This is just using the standard Python distutils, so there is actually
+a great deal of flexibility here.  Try
 
+% python setup.py install --help
+
+to see some of the options available.
 
 RUNNING IT
 
-% tar zxvf python-rwhoisd-0.1.tar.gz
+This is assuming that you are running it from the distribution
+directory.
+
+% tar zxvf python-rwhoisd-0.4.tar.gz
 
-% cd python-rwhoisd-0.1
+% cd python-rwhoisd-0.4
 
 % ./bin/pyrwhoisd sample_data/example_schema \
                   sample_data/example_data &
@@ -28,13 +55,38 @@ RUNNING IT
 Voila!  You should now have some sort of rwhois server running on port
 4321
 
+You can also give it multiple data files:
+
+% ./bin/pyrwhoisd sample_data/example_schema sample_data/*_data &
+
 CONFIGURING IT
 
 Edit rwhoisd/config.py.
-This file is sort of commented as to what you can change.
 
+This file has comments describing options that you can change.
 
 DATA
 
 See the example_schema and example_data files in the sample_data
 directory.
+
+The format of the data files is very similar to the format used by the
+C rwhois server (rwhoisd-1.5.x from www.rwhois.net).  It has the
+following differences, however:
+
+* These files may have records separated by blank lines instead of
+  dashes.
+
+* They are not sensitive to trailing separators (whitespace or dashes)
+
+* They do not have to be arranged in any special manner.  That is, the
+  C rwhoisd forces (or at least encourages) you to arrange your data
+  files into different directories per authority-area.  These can be
+  wherever.
+
+* This server does not support attribute "aliases".
+
+It should be noted that this server in small ways violates the
+description put forth by RFC 2167.  In particular, it does not
+establish independent schemas for each authority area.  There may be
+other violations as well.