Copyright 2001 Michael Grant. All rights reserved. 

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

 1.Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 2.Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided
   with the distribution.

THIS SOFTWARE IS PROVIDED BY MICHAEL GRANT ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MICHAEL GRANT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

The views and conclusions contained in the software and
documentation are those of the authors and should not be
interpreted as representing official policies, either expressed or
implied, of Michael Grant.

------------------------------------------------------------------------------

Congratulations, you have downloaded the Name Service Editor, a set of
perl cgi scripts which will enable you to allow others to manage their
own primaries and secondaries on your system without having to give
them root access.

These perl scripts depend on several things:

  - That you have a web server which can run it.  It was tested with
    Apache.

  - That you can configure your web server to authenticate users who
    access this script.  This was tested with Basic Authentication.

  - That you have Bind version 8 or 9

  - That you have cgi-lib.pl from http://cgi-lib.berkeley.edu/

  - That you either install named-reload (supplied as C source) or
    write your own script to send the proper signal to named or call ndc
    (or rndc in version 9) to reload the conf file and print any
    messages on stdout.  named-reload has an advantage that it
    "scrapes" the logs for any output when named is reloaded.

This was written and tested on FreeBSD 4.4/5 running Apache 1.3 using
Perl 5.005_03 and named 9.2.0.  It was also tested using named version
8.

Setup:
------

1) Install primary.pl and secondary.pl into your cgi-bin directory.

2) Install cgi-lib.pl in your cgi-bin directory
   from http://cgi-lib.berkeley.edu/

3) Create an authorization for the script which requires a user
   to type a username/password.  In Apache, your VirtualHost
   definition might look like this:

   <VirtualHost 10.20.30.40>
       ServerAdmin webmaster@some.domain
       DocumentRoot /usr/local/www/docs/some.domain
       ServerName some.domain
       ServerAlias some.domain www.some.domain
       <Files secondary.pl>
	   AuthName "Secondary Editor"
	   AuthType Basic
	   AuthUserFile /usr/local/www/cgi-bin/users
	   require valid-user
       </Files>
   </VirtualHost>

   see http://httpd.apache.org/docs/mod/mod_auth.html

   Then you would use htpasswd -c /usr/local/www/cgi-bin/users someone
   to create and add user's to this file.

   WARNING: Don't just follow these instructions blindly!  You should
   fully understand what you are doing.  When you add a user to this
   file, you are letting them do something on your system.  You are
   extending a level of trust to them.  Do not do this lightly.

   Secure http (https) is recommended as passwords with this type of
   auth are not encrypted.

5) Create two directories: webprimary and websecondary in your namedb
directory.

   Make sure that your web server can read and write to this
   directory, for example:

   mkdir /etc/named/webprimary
   mkdir /etc/named/websecondary
   chown apache /etc/named/webprimary/ /etc/named/websecondary/

4) Add "include" statements to your named.conf like this:

   include "/etc/named/websecondary/webprimary.inc";
   include "/etc/named/websecondary/websecondary.inc";

   Make sure webprimary.inc and websecondary.inc exist or named will
   complain.  (The script will create them if they're not there the
   first time you run it).  They can be empty.  Make sure the web
   server can read and write them.  The scripts will add lines to this
   file when a new user is added to the system.

   touch /etc/named/websecondary/websecondary.inc
   chown apache /etc/named/websecondary/websecondary.inc
   touch /etc/named/websecondary/webprimary.inc
   chown apache /etc/named/websecondary/webprimary.inc

6) Edit named-reload.c and make sure the messages file where named
   logs to and named's pid file are correct.  To compile, type:

   make

   Put the program named-reload in /usr/local/sbin/ and make sure
   it's chowned to the user bind runs as and is set-uid.  You may want 
   to set up a group permission so that not just anybody can run
   named-reload.  

   make install

7) Lastly, edit the top of primary.pl and secondary.pl and make sure
the path names match reality for your system.

To test:
--------

   Point a web browser at https://your.domain/cgi-bin/primary.pl or
   https://your.domain/cgi-bin/secondary.pl

To add a new user to the system:
--------------------------------

1) simply add a password entry for them, for example:

   htpasswd -c /usr/local/www/cgi-bin/users someone

To delete a user from the system:
---------------------------------

1) remove their password from the AuthUserFile you specified, for
example: /usr/local/www/cgi-bin/users

2) remove their line from the websecondary.inc and/or webprimary.inc
file.  For example, remove the following line:

   include "/usr/local/etc/namedb/websecondary/someone";

3) remove their corresponding include file.  For example:

   rm /usr/local/etc/namedb/websecondary/someone

Todo: 
-----
      - an admin page to add/delete users
      - an more automated way to configure the scripts
      - combining primary.pl and secondary.pl into one general purpose
        script
      - deal with reverse dns (in-addr.arpa domain).

Known limitations:
------------------
      - If you delete a domain and then reinstate it, the old zone
        data is still there.  This is either a bug or a feature
	depending on your point of view.

      

If you find bugs or need help, send mail to websecondary@grant.org.

