Last Updated: 2000-05-09
=============================

GnuDIP - Version 2.1.2



GnuDIP is released under the GPL. Please see the file COPYING included in this distribution for more information.

Lastest version can always be found at:
http://gnudip.cheapnet.net, ftp.cheapnet.net/pub/gnudip, sunsite.unc.edu/pub/Linux/system/network/daemons

DBI database (Recommend MySQL) and perl DBI is needed to run GnuDIP.
As of version 2.1.x the MD5 module is needed (and included? in this package. See the subdirectory MD5-x.x for more information)
Read README.mysql for further information about the database requirements

*** If you already have a GnuDIP server running be sure to read the UPDATE file for instructions on how to safely migrate to this new version ***


OVERVIEW:

GnuDIP is a DYNDNS (Dynamic DNS) service desiged for an ISP to give its customers a static DNS name without having to give them their own IP address. For those who are familiar with ml.org this is a simple replacement. GnuDIP has 2 main parts on the server side. 1, the daemon that listens for client requests, and 2 the web cgi that is used as the administration tool and as the users tool to manage their own account. It features the ablility to set a URL and have your browser automatically authenticate you and redirect you to that URL.



FEATURES:

   Web configuration - You can use the web tool for all administration of your GnuDIP server 
   Auto URL - Set GnuDIP as your default page and it will automatically authenticate you and redirect you to a page of your choice 
   Use GnuDIP on your main domain - It is possible to use GnuDIP on your main domain without worrying about zonefile corruption 
   Multi-Processed server - GnuDIP features a multi processed server to handle an enormous amount of connections 
   Queuing system - GnuDIP implements a queuing system to handle zonefile updates in order to handle a large amount of updates in a small amount of time 
   Strong Security - All communications between client and server are encrypted using the MD5 algorithm 
   Offline - you can set offline and GnuDIP will not respond with incorrect answers for your hostname
   Self signup - If allowed, users can register themselves as user with no administrator intervention required
   Restrict Usernames - Set a list of usernames you do not want people to register. Wild card matching is supported.
   Custom Login Page - Has the option to read in a page you design and display it on the login page
   Multi-Domain Ready - You can easily add other domains for your GnuDIP server to handle, and magage users for all domains at once, or have individual permissions on each domain



INSTALLATION:

Run "./install" to start the installation script if you have a MySQL database
This will create the right tables discribed in the README.mysql

If setting up manually, verify that /etc/gnudip.conf has the correct values to connect to your database server

Start the server service using the provided S99gnudip script with /path/to/S99gnudip start

Then run the cgi installed into your web servers cgi-bin.
 ex: if your server is www.mydomain.com and you installed the cgi into
     /path/to/webserver/cgi-bin you would then goto http://www.mydomain.com/cgi-bin/gnudip2.cgi

Use the default administrator 'admin' with the default password
'GnuDIP'. Change this as soon as possible via the settings menu.

You will need to set your main GnuDIP domain in the Administration sectionm, other domains can be added via the Domain Management section

The self sign up page is http://www.yourdomain.com/cgi-bin/gnudip2.cgi?action=signup

   
If you for some reason need to debug as users login to your GnuDIP service you can run gdips.pl manually with the -l switch with no file name and messages will be displayed to standard out.



   **Client Only**
If all you are installing is the client utility, just copy gdipc.pl to somewhere in your PATH and run it with -c to create your configuration. If you want to automatically update your hostname apon connecting, add "/path/to/gdipc.pl" to the end of /etc/ppp/ip-up.



IMPORTANT:

  The 'install' script is only compatable with MySQL, so if you are running another database setup must me done by hand.

   Database schema is in the file gnudip2.db.
   Add a user to your database that GnuDIP will use to connect to the database with
   Make sure that user is the same as what is defined in gnudip.conf
   Then place gnudip.conf in /etc
   gnudip-lib.pl should be in either /usr/lib/perl5 or /usr/local/lib/perl5
   The gnudip2.cgi needs to be placed inside your web server cgi-bin
   gdips.pl and gdip-named.pl are the core scripts and usually placed /usr/local/sbin
   gdipc.pl is the client script, and sould be given to your users who wish to have a command line interface
   The S99gnudip can be placed inside the rc.d init scripts directory, or renamed and used manually to stop/start GnuDIP
     




LOCATION OF FILES AFTER INSTALATION (hopfully):

gnudip2.cgi: This needs to be placed in your servers cgi-bin directory if the install scripts where unable to determin your web server directory

gdips.pl: This is put into PREFIX/sbin. If you wish to have the server run on startup place the file S99gnudip-start in the correct system rc directoy

gdipc.pl: This is put into PREFIX/bin. This is the client utility to give to users. They can have this program auto run apon connect by placing the correct entries into their ppp scripts

S99gnudip: This is the file to easily start and stop the gnudip server. It is intended to be placed in a rc.d direcory to start and stop the server on boot time. './install' will ask you if you want to place this in your rc directory and if yes which directory you want to use.



NOTES:

To run the server use the S99gnudip script. Edit to select what user to run the server as.

  Default user is 'nobody'. 
  root is not recommended!



It is recommended that you use a subdomain reserved only for GnuDIP. dyn.example.com.zone can be used as the template for your new GnuDIP subdomain. Just remember to tell your primary server about your subdomain. If you want to run GnuDIP in your servers main domain it is possible to use BIND's $INCLUDE function to include the zone file you choose via the web interface. You just have to set ZONETYPE to INCLUDE in the administration section of the web interface. Then add the following line at the botton of your primary zonefile:

$INCLUDE the_file_defined_via_the_web_interface.zone
(Make sure you delete the SOA record in this file of you choose to do it this way)



It will work with your regular domain, but if you use a separate domain that will avoid any syntax errors and corruption in the zonefile. Also if you use the $INCLUDE method GnuDIP will NOT automatically update your serial for you. This will now affect you if you do not use a secondary for this zone.




QUICK INSTALL:

1: ./install
2: INITRCDIR/S99gnudip start
3: goto http://www.yourserver.com/cgi-bin/gnudip2.cgi and login as 'admin' 'GnuDIP' and select Administrative Settings. Enter settings as descriptions indicate.

(If you chose not to place S99gnudip in your rc.d directory you can rename it and use it manually.)



PROTOCOL:

This is a detailed description of the comminucation between client and server to easily provide a way to write custom client programs or to intergrate client programs into other utilites.


  First step in the process is to somehow read in a username, domain  and password a user wants to use in an attempt to authenticate to a GnuDIP server. One you have this, generate an MD5 haxhashed sum on the password.

  Once the above string has been formed a socket connection to the server is made on port 3495. As soon as the connection is established the server will send over 10 random alpha-numeric characters. Now, take the string from above and append a '.' and the 10 characters to it and re generate the hexhashed string over all of it. This produces a twice MD5 hexhashed string.

  Next we send the string to the server. This comes in the form 

        username:twice_hexhashed_string:domain:0/1 
 
  A 0 at the end tells the server to do a update request, and a 1 at the end tells the server to do an offline request.


  Finally the server will return one of the following codes depending on the validity of the username and password sent.

    0 = Successful update
    1 = Invalid login
    2 = Successful offline




Mike Machado <mike@innercite.com>