| # GnuDIP Release 2.3.5 - INSTALL File

### Preliminary Steps

1. Become familiar with the set of low privilege UNIX user IDs used for running daemons on your system.

   Many UNIX systems use a very simple system. There is a user ID named `nobody`. The `nobody` user ID cannot be logged in to. It can only be reached through the "`root`" user ID. It also has its own group. A process running under this ID will only be able to read files that are "world readable", and only able to modify or delete files that are "world writable".

   Within this set up it is common practice to run the BIND `named` daemon as user `nobody`. Also, the sample configuration file that comes with the Apache web server source will run all CGI scripts as user `nobody`.

   Some systems (apparently Red Hat does this) have several "`nobody`" user ID-s. Each daemon that can be run as a low privilege user gets its own user ID.

   In these instructions, we assume that there is a single `nobody` user ID. When we refer to the `nobody` user ID, the reader should substitute the appropriate user ID for the daemon being discussed.

2. Move the directory `gnudip` to `/usr/local` (or `/opt`, or wherever you wish - we will assume `/usr/local` in what follows). If you copy this directory instead, be careful that the file ownerships of the files in the `gnudip/etc/` directory do not change.

### The "MiniDIP" Alternative

> This package includes a bare bones version of GnuDIP with no database or web tool. There is a single configuration file, which includes the list of host names and their passwords.

> The `minidip.pl` Perl script is a `(X)INETD` daemon address update server program. The `miniupdt.pm` Perl script is a CGI address update server program. They use `minidip.conf` in the GnuDIP configuration directory as the configuration file. The `(X)INETD` daemon allow the name of the configuration file to be overridden using command argument.

> The `BIND` setup (this option does not support "back ends" - see below) is the same as for the full GnuDIP software.

> The `(X)INETD` daemon setup is the same as for the standard GnuDIP `(X)INETD` daemon.

> The CGI setup is also the same as for the standard GnuDIP CGI, if it is acceptable to have "`/gnudip/cgi-bin/miniupdt.cgi`" as the URL for the CGI. Otherwise you will need to use "`ScriptAlias`" definitions to suit your needs.

> Combining `minidip.pl` and `miniupdt.pm` with the `multinsupd.pl` script discussed below in "Linking Non-GnuDIP Host Names to a GnuDIP Host Name" can provide a great deal of functionality.

### Upgrading an Existing MySQL Database

1. If you have an existing GnuDIP MySQL database, upgrade this GnuDIP database. Note that there have been no database changes since release 2.3.0.

   Start the MySQL client using:

       # mysql -p

   Follow the contents of `upgrade.mysql` to do the first part the upgrade.

   Or you can read and edit the contents of `upgrade.mysql`, setting the MySQL database name, and then use:

       # mysql -fvp < upgrade.mysql

   The `upgrade.mysql` file is designed to upgrade from either either release 2.1.2 or release 2.2.x when used in this "automatic" way. In the latter case however, some error messages may be produced.

   Scan the GnuDIP database and generate the statements to complete the database upgrade using:

       # /usr/local/gnudip/sbin/gdipdbcnv.pl database localhost user password > myupgrade.mysql

   The arguments are the MySQL database name, the server running MySQL, and the user name and password to connect to MySQL with, respectively. Read and understand the file that `gdipdbcnv.pl` produced:
   - There will be statements to delete and recreate the contents of the `globalprefs` table.

   - If you used `DOMAIN_TYPE='GLOBAL'` in Release 2.1.2 (which is no longer an option - see `release.html`), then the value of the `domain` column will be the empty string for each row of the `users` table. The statements generated by `gdipdbcnv.pl` will replace each such row with several replacement rows - one for each domain.

   When you have examined these MySQL statements, run them using:

       # mysql -p < myupgrade.mysql

### New Database Set Up

1. If you have no existing GnuDIP database and wish to use MySQL, create a new GnuDIP MySQL database.

   Start the MySQL client using:

       # mysql -p

   Follow the contents of `gnudip.mysql` to define the MySQL database and user.

   Or you can read and edit the contents of `gnudip.mysql` setting the MySQL database name, and the user name and password to connect to MySQL with, and then use:

       # mysql -vp < gnudip.mysql

2. If you have no existing GnuDIP database and wish to use the Linux/UNIX file system, create a new GnuDIP "flat file" database.

   Delete the two UNIX symbolic links `/usr/local/gnudip/lib/dbprefs.pm` and `/usr/local/gnudip/lib/dbusers.pm`. By default these point to `/usr/local/gnudip/lib/dbprefs_mysql.pm` and `/usr/local/gnudip/lib/dbusers_mysql.pm`, respectively, which contain the code to handle MySQL.

   Recreate these links using:

       # ln -s dbprefs_flat.pm /usr/local/gnudip/lib/dbprefs.pm
       # ln -s dbusers_flat.pm /usr/local/gnudip/lib/dbusers.pm

   By default, `dbprefs_flat.pm` uses a file named `/usr/local/gnudip/run/database/globalprefs`, and `dbusers_flat.pm` uses a directory named `/usr/local/gnudip/run/database/users`.

   The directories `/usr/local/gnudip/run/database` and `/usr/local/gnudip/run/database/users` are already set up. These directories must be readable and writable only by the owner and owned by user "`nobody`" (the "`nobody`" that Apache will run the GnuDIP CGI script as - see step one above). The processes that create and update files in these directories will be running as that user.

   These names can be changed in `/usr/local/gnudip/etc/gnudip.conf`.

3. If you have no existing GnuDIP database and wish to use PostgreSQL, create a new GnuDIP PostgreSQL database.

   Delete the three UNIX symbolic links `/usr/local/gnudip/lib/dbcxore.pm`, `/usr/local/gnudip/lib/dbprefs.pm` and `/usr/local/gnudip/lib/dbusers.pm`. By default these point to `/usr/local/gnudip/lib/dbcore_mysql.pm`, `/usr/local/gnudip/lib/dbprefs_mysql.pm` and `/usr/local/gnudip/lib/dbusers_mysql.pm`, respectively, which contain the code to handle MySQL.

   Recreate these links using:

       # ln -s dbcore_pgsql.pm  /usr/local/gnudip/lib/dbcore.pm
       # ln -s dbprefs_pgsql.pm /usr/local/gnudip/lib/dbprefs.pm
       # ln -s dbusers_pgsql.pm /usr/local/gnudip/lib/dbusers.pm

   Start the PostgreSQL client using:

       # psql -U postgres template1

   Follow the contents of `gnudip.pgsql` to define the PostgreSQL database and user.

   Or you can read and edit the contents of `gnudip.pgsql` setting the PostgreSQL database name, and the user name and password to connect to PostgreSQL with, and then use:

       # psql -U postgres template1 -f gnudip.pgsql

4. You may change from one type of GnuDIP database to another by using the scripts `gnudip/sbin/gdipunld.pl` and `gnudip/sbin/gdipreld.pl` to dump and restore your user database:

       # gdipunld.pl -h
       usage: gdipunld.pl [ -h | [ [-o | -a] outfile ] ]
       usage: Dumps the users table to a flat file.
       usage: -h: Print this usage message.
       usage: -o: Specify file to write output to.
       usage: -a: Specify file to append output to.

       # gdipreld.pl -h
       usage: gdipreld.pl [ -h | [ -i infile ] ]
       usage: Loads the users table from a flat file.
       usage: -h: Print this usage message.
       usage: -i: Specify file to read from.

   You will have to re-enter system settings and domains by hand.

### DNS Server Set Up

1. If you are using a legacy version of BIND that cannot be updated using the dynamic DNS protocol by `nsupdate`, or tinydns, you must set up the GnuDIP "back end" scripts. This is discussed in BACKEND.html.

2. Otherwise choose a zone or zones, and get BIND setup for dynamic updates for these zones.

   The description provided in the next four steps shows one way to achieve this for one zone and key. For other configuration options please read the BIND 8 or BIND 9 documentation.

3. Generate the key files required by the `nsupdate` command. This will at the same time generate a "TSIG key" which you will later have to use in configuring the `named` daemon.

   For BIND 8 use "`dnskeygen`" to generate key files. This goes something like this sample:

   >     # dnskeygen -H 128 -h -n gnudip-key
   >     ** Adding dot to the name to make it fully qualified domain name**
   >     Generating 128 bit HMAC-MD5 Key for gnudip-key.

   >     Generated 128 bit Key for gnudip-key. id=0 alg=157 flags=513

   >     # ls
   >     Kgnudip-key.+157+00000.key  Kgnudip-key.+157+00000.private
   >     # cat Kgnudip-key.+157+00000.private
   >     Private-key-format: v1.2
   >     Algorithm: 157 (HMAC)
   >     Key: fegHlhVt3opPIiK8V4cjLw==
   >     # cat Kgnudip-key.+157+00000.key
   >     gnudip-key. IN KEY 513 3 157 fegHlhVt3opPIiK8V4cjLw==

   For BIND 9 use "`dnssec-keygen`" to generate key files. This goes something like this sample:

   >     # dnssec-keygen -a hmac-md5 -b 128 -n HOST gnudip-key
   >     Kgnudip-key.+157+36000
   >     # ls
   >     Kgnudip-key.+157+36000.key  Kgnudip-key.+157+36000.private
   >     # cat Kgnudip-key.+157+36000.private
   >     Private-key-format: v1.2
   >     Algorithm: 157 (HMAC)
   >     Key: fegHlhVt3opPIiK8V4cjLw==
   >     # cat Kgnudip-key.+157+36000.key
   >     gnudip-key. IN KEY 513 3 157 fegHlhVt3opPIiK8V4cjLw==

   For both Bind 8 and 9, examine the files that were generated to determine the key that was generated. In the examples above this key is:

   >     fegHlhVt3opPIiK8V4cjLw==

   You will use this key later to configure your BIND `named` daemon, to control dynamic update access to the GnuDIP dynamic zone.

   Move the key files generated to `/usr/local/gnudip/etc/`. Remove the samples that are already there. These files should not be writable by anyone. These files should be readable only by the owner and owned by user "`nobody`" (the "`nobody`" that Apache will run the GnuDIP CGI script as - see step one above). The `nsupdate` command which will read these files will be running as that user.

4. Update the definition of the "`nsupdate`" parameter in the `/usr/local/gnudip/etc/gnudip.conf` file.

   For BIND 8 follow this sample:

   >     # BIND nsupdate command
   >     nsupdate = /usr/bin/nsupdate -v -k /usr/local/gnudip/etc:gnudip-key.

   Note that the trailing period ("`.`") is required.

   For BIND 9 follow this sample:

   >     # BIND nsupdate command
   >     nsupdate = /usr/bin/nsupdate -v -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private

   > Or you could do:

   >     # BIND nsupdate command
   >     nsupdate = /usr/bin/nsupdate -v
   >     nsupdate = -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private

   Note that parameter names in `gnudip.conf` may appear more than once. The values are concatentated with an intervening blank.

   As shown above, the command line options for `nsupdate` differ between BIND 8 and BIND 9. However, the `nsupdate` standard input commands generated by GnuDIP are compatible with either BIND 8 or BIND 9.

5. Now you must configure the target BIND `named` daemon to contain the key generated above, and also of course your GnuDIP dynamic zone.

   Note that the `named` daemon may run on a different machine than the machine that will run the GnuDIP CGI (and thereby the `nsupdate` command). The `nsupdate` command determines what DNS server to send its update request to by doing a DNS lookup for the "`SOA`" record for the domain name whose information is being updated. The `SOA` record identifies the master DNS server for this domain name. The `nsupdate` command will send the update request to the master DNS server for the domain.

   Recall that the sample TSIG key generated above was:

   >     fegHlhVt3opPIiK8V4cjLw==

   Create a file called `gnudip-keyfile` in your `named` configuration directory. This file should not be writable by anyone. This file should be readable only by the owner and owned by user "`nobody`" (the "`nobody`" that the `named` daemon will run as - see step one above). The file `gnudip-keyfile` should contain something like this sample:

       key gnudip-key {
         algorithm hmac-md5;
         // the TSIG key
         secret "fegHlhVt3opPIiK8V4cjLw==";
       };

   Note that the contents of this file are entirely different from the files created during key generation above. This is not a copy of one of those files. You will have to create this file manually. The sample key "`fegHlhVt3opPIiK8V4cjLw==`" must be replaced by the key that you generated.

   Now you must add a section to define the GnuDIP dynamic zone in your `named.conf` file.

   For BIND 8 the new section would look something like:

   >     // include definition of GnuDIP update key
   >     include "gnudip-keyfile";

   >     // define GnuDIP dynamic DNS zone
   >     zone "dyn.you.net" in {
   >       type master;
   >       file "run/zone-dyn.you.net";
   >       allow-query { any; };
   >       allow-update { key gnudip-key; };
   >     };

   For BIND 9 the new section would look something like:

   >     // include definition of GnuDIP update key
   >     include "gnudip-keyfile";

   >     // define GnuDIP dynamic DNS zone
   >     zone "dyn.you.net" in {
   >       type master;
   >       file "run/zone-dyn.you.net";
   >       allow-query { any; };
   >       update-policy { grant gnudip-key subdomain dyn.you.net; };
   >     };

   In the examples above, note that the string `gnudip-key` refers to the name of the key, whereas the string `gnudip-keyfile` refers to the file containing the syntax to define that key name.

   Notice above that the zone file is in a subdirectory called `run`. This directory should be owned by user "`nobody`" (or whatever user ID `named` runs as) so that `named` may create files in it.

   You can set up `$TTL` and `SOA` values for the dynamic zones by setting up an initial zone file for BIND. BIND will read this the first time, and use the values from the file. Continuing the previous example, for the file `run/zone-dyn.you.net` try something like this sample:

       $TTL 86400 ; default TTL (1 day)
       @          IN SOA   ns.you.net. root.you.net. (
                             0       ; serial
                             3600    ; refresh (1 hour)
                             1800    ; retry (30 minutes)
                             604800  ; expire (1 week)
                             0       ; TTL for NACK-s (0 seconds)
                           )
                  IN NS    ns.you.net.
                  IN A     IP_address

   This zone file should again be owned by user `nobody`, so that `named` may modify it.

   This sample supposes that you want clients to use `dyn.you.net` as the name of the GnuDIP server, in addition to the name of the GnuDIP subdomain. The `A` record is required for this. You will not be allowed to use a `CNAME` record for this, because the name of the record would be the same as the name of the `SOA` record. You can maintain this `A` record using `nsupdate` if the address changes.

   The `SOA` and `NS` records may point into an entirely different domain.

   Note that the base domain `you.net` can be made the GnuDIP dynamic domain if you wish. If the `NS` records point to names within `you.net`, you will need glue records in the usual way.

   Note that the default TTL value in this start up file will not apply to the records added using `nsupdate`. The `nsupdate` command requires a TTL value with each record added. GnuDIP will use a value of zero for this TTL, unless a value is specified in `/usr/local/gnudip/etc/gnudip.conf` (see below).

   You may want to retain a copy of this inital zone file, for use with the `gnudip/sbin/gdipzone.pl` script discussed below.

   Note that if you are the operator of a serious production shop rather than a home hobbiest, you will need to set up BIND to do "dynamic update forwarding" and "incremental zone transfers" to slave DNS servers from the master DNS server. These details are not explained here.

6. If the call to the `nsupdate` command by the GnuDIP CGI script fails for any reason, the precise command that was invoked as well as the input that was passed to it and the output from it will be wriiten to the system log.

   The simplest way to debug your BIND configuration is probably by using `nsupdate`, the `dig` command and the `ping` command at the UNIX command prompt. For example, on the machine where the GnuDIP CGI script and `nsupdate` will run, try:

       # dig tester.dyn.you.net. soa

       ; <<>> DiG 9.1.3 <<>> tester.dyn.you.net. soa
       ;; global options:  printcmd
       ;; Got answer:
       ;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 34673
       ;; flags: qr aa rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0

       ;; QUESTION SECTION:
       ;tester.dyn.you.net.            IN      SOA

       ;; AUTHORITY SECTION:
       dyn.you.net.      0             IN      SOA     you.net. root.you.net. 484 3600 1800 604800 0

       ;; Query time: 8 msec
       ;; SERVER: 192.168.0.2#53(192.168.0.2)
       ;; WHEN: Tue Oct 23 14:47:24 2001
       ;; MSG SIZE  rcvd: 88

       # su - nobody
       # /usr/bin/nsupdate -v -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private
       > update add tester.dyn.you.net. 0 A 127.0.0.1
       >
       > #
       # exit
       # ping tester.dyn.you.net.
       PING tester.dyn.you.net (127.0.0.1): 56 data bytes
       64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.2 ms
       64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.1 ms

       --- tester.dyn.you.net ping statistics ---
       2 packets transmitted, 2 packets received, 0% packet loss
       round-trip min/avg/max = 0.1/0.1/0.2 ms
       #

   In the "`su`" command, the "`nobody`" that the GnuDIP CGI and (X)INETD daemon will run as should be used (see above). You may want to try the `nsupdate` as root first.

   If your `nobody` user is not set up to allow the use of "`su - ...`", you may instead try:

       # sudo -u nobody /usr/bin/nsupdate -v \
                   -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private

   The output from the `dig` command shows that `nsupdate` will send its update request to `you.net`.

   Note that `nsupdate` accumulates update input lines until it sees an empty line. Only then does it do the updates. To stop `nsupdate` use "`Ctrl-D`" to generate an end of file.

   Remember that BIND comes with documentation.

   You may also want to take advantage of the BIND mailing lists or their archives.

### Editing the Configuration File

> Edit `/usr/local/gnudip/etc/gnudip.conf`. There are comments in the sample that is already there.

> In particular, check whether you need a "`-p`" option for the "`logger`" commands in order to ensure that log messages go somewhere acceptable. One user has suggested "`/usr/bin/logger -p local3.err`" for Solaris 8 using the default configuration for syslogd.

> Also, check the path to your sendmail program (or sendmail clone). For example Solaris 8 by default puts sendmail in `/usr/lib/sendmail`.

> A sendmail alias (or clone equivalent) to direct mail for the "return path" user (the GnuDIP "nobody" user unless the sendmail "`-f`" option is used) to `/dev/null` is also a good idea, so returned mail for a bad E-mail address disappears.

> If you already have a `gnudip.conf` file for an existing installation, review the sample `gnudip.conf` file for new parameters.

> Make sure that everything in `/usr/local/gnudip/etc/` is readable only by the owner and owned by user "`nobody`" (the "`nobody`" that Apache will run the GnuDIP CGI script as - see step one above), and not writable by any user.

> You may wish to create a directory `/etc/gnudip`, move (i.e. rename) the directory `/usr/local/gnudip/etc` to `/usr/local/gnudip/etc_orig` (for later reference), and set `/usr/local/gnudip/etc` as a symbolic link to `/etc/gnudip`. Then create your configuration files in `/etc/gnudip`. If you later upgrade, you can then just rename `/usr/local/gnudip/etc` to `/usr/local/gnudip/etc_orig`, and recreate the link. This practice allows the switch to a new release in production environments to consist of two "`mv`" commands and one "`ln`" command, which would take only a few seconds.

### Apache Web Server Set Up

> The instructions here are for Apache. But it should be possible to use the web interface with other servers.

> The user maintenance commands or remote maintenance daemon described below may be used in place of or in addition to the GnuDIP Web interface. However, the HTTP client update interface is incorporated into the web interface. The Apache configuration can be made simpler if only the HTTP client interface is desired. Only the CGI definition statements are required.

1. To run as a standard CGI, add these lines to your Apache configuration file:

       Alias /gnudip/html/ /usr/local/gnudip/html/
       <Location /gnudip/html/>
       Options Indexes
       ReadmeName .README
       HeaderName .HEADER
       RemoveHandler .pl
       RemoveType .pl
       AddType text/plain .pl
       </Location>
       ScriptAlias /gnudip/cgi-bin/ /usr/local/gnudip/cgi-bin/

   The URL for the Web Tool will be:

       http://yourserver/gnudip/cgi-bin/gnudip.cgi

   The self sign up page will be directly available at:

       http://yourserver/gnudip/cgi-bin/gnudip.cgi?action=signup

   Note that this URL is different than the URL for GnuDIP following the installation instructions for Release 2.1.2. Following those instructions the URL would be

       http://yourserver/cgi-bin/gnudip2.cgi

   To provide compatibility copy the perl script `/usr/local/gnudip/cgi-bin/gnudip2.cgi` to the `cgi-bin` directory for your Apache server (or make a symbolic link). This short script will redirect to the new URL. Modify `gnudip2.cgi` to match any change you made to the two Apache configuration lines above.

   Other Apache configurations are possible.

2. The web tool will run under mod_perl Apache::Registry.

   To use mod_perl, instead of the lines described above, add these lines to your Apache configuration file:

       Alias /gnudip/html/ /usr/local/gnudip/html/
       <Location /gnudip/html/>
       Options Indexes
       ReadmeName .README
       HeaderName .HEADER
       RemoveHandler .pl
       RemoveType .pl
       AddType text/plain .pl
       </Location>
       Alias /gnudip/cgi-bin/ /usr/local/gnudip/cgi-bin/
       <Location /gnudip/cgi-bin/>
       SetHandler perl-script
       PerlHandler Apache::Registry
       Options +ExecCGI
       PerlSendHeader On
       </Location>

3. The web tool will run under FastCGI using `mod_fastcgi` and `FCGI.pm`.

   To use FastCGI, instead of the lines described above, add these lines to your Apache configuration file:

       Alias /gnudip/html/ /usr/local/gnudip/html/
       <Location /gnudip/html/>
       Options Indexes
       ReadmeName .README
       HeaderName .HEADER
       RemoveHandler .pl
       RemoveType .pl
       AddType text/plain .pl
       </Location>
       Alias /gnudip/cgi-bin/ /usr/local/gnudip/fcgi-bin/
       <Location /gnudip/cgi-bin/>
       SetHandler fastcgi-script
       Options +ExecCGI
       </Location>

   When running under mod_perl or FastCGI, adding the line "`persistance = YES`" to gnudip.conf will cause the web tool to use persistant database connections, and to retain the contents of gnudip.conf, the preferences from the `globalprefs` table and the list of domains from the `domains` table, and any other configuration files in memory, rather than re-accessing these files or tables. Make sure that persistance is not on when configuring your system while running under mod_perl or FastCGI.

### Customizing the Web Interface

1. The parameters `header_file` and `trailer_file` in gnudip.conf specify a file of HTML to be included at the top and bottom of each HTML page, respectively. An example of what can be done using these files is provided.

2. The parameters `URL_sendURL`, `URL_self_signup` and `URL_delthisuser` in gnudip.conf specify URL-s which should take the place of the "Forgotten Password", "Self Registration" and "Delete Current User" form buttons. See the comments in gnudip.conf for more information.

3. The parameters `no_robots_prfx` and `no_robots_imgcmd` in gnudip.conf must be correctly specified in order to user the GnuDIP feature to suppress automated abuse of "Self Registration", "Forgotten Password" and "Change E-mail Address". See the comments in gnudip.conf. If you have ImageMagick installed then the sample/default text image generation script should work for you.

   Once you have ensured the defaults will work, or provided and alternative image generation script, you can turn this option on in "System Settings" in the web interface.

   Without this, the GnuDIP Web Interface is vulnerable to being used as the "man in the middle" for an E-mail bombardment attack.

   A program can "GET" and "POST" the pages that send an E-mail repeatedly to send an E-mail bombardment to a third party. The bombardment will seem to come from the GnuDIP site.

### (X)INETD Daemon Set Up

1. Add an entry to `/etc/services` like this sample:

       gnudip          3495/tcp

2. If you use the `xinetd` replacement for `inetd`, add an entry to `/etc/xinetd.conf` like this sample:

       service gnudip
       {
       	flags       = REUSE
       	socket_type = stream
       	protocol    = tcp
       	wait        = no
       	user        = nobody
       	server      = /usr/local/gnudip/sbin/gdipinet.pl
       	bind        = 0.0.0.0
               only_from   = 192.168.0.0/24
               only_from   += 127.0.0.1
               only_from   += 24.64.0.0/13
               only_from   += 64.5.210.224/31
               only_from   += 64.5.221.128/27
       }

   You should of course choose values for "`only_from`" that are appropriate to your circumstances. You may want to just leave these lines out.

   Note that the "`nobody`" user ID used here should be the same one Apache will run the GnuDIP CGI script as (see step one above).

   If you have XINETD with TCP wrappers compiled in, make an entry in `/etc/hosts.allow` like this sample:

       gdipinet.pl: 24.64.0.0/255.248.0.0        \
                    64.5.210.224/255.255.255.232 \
                    64.5.221.128/255.255.255.160

   For early releases of XINETD with TCP wrappers, you must use the service name instead of the process/program name, as follows:

       gnudip: 24.64.0.0/255.248.0.0        \
               64.5.210.224/255.255.255.232 \
               64.5.221.128/255.255.255.160

   If you left out "`only_from`" above, then you would instead use a line like:

       gdipinet.pl: ALL

   or for early releases of XINETD

       gnudip: ALL

3. Or make an equivalent entry in `/etc/inetd.conf` like this sample:

       gnudip	stream	tcp	nowait	nobody	/usr/sbin/tcpd	/usr/local/gnudip/sbin/gdipinet.pl

   Note that the tokens are separated by tab characters.

   Note that the "`nobody`" user ID used here should be the same one Apache will run the GnuDIP CGI script as (see step one above).

   Make an entry in `/etc/hosts.allow` like this sample:

       gdipinet.pl: 24.64.0.0/255.248.0.0        \
                    64.5.210.224/255.255.255.232 \
                    64.5.221.128/255.255.255.160

   If you are not imposing access restrictions, then you would instead use a line like:

       gdipinet.pl: ALL

4. If you have restricted the IP addresses for `gdipinet.pl` using `/etc/xinetd.conf` and/or `/etc/hosts.allow`, you may want to restrict the IP addresses for this port in your firewall too.

5. We assume in what follows that you have added /usr/local/gnudip/sbin to your `PATH` environment variable.

6. Check that the `logger` command used by the (X)INETD script has been correctly defined by using `gnudip/sbin/gdipinet.pl` at the command line. This should go something like this:

       # su - nobody
       # gdipinet.pl
       Could not get IP address of client
       # exit

   Here, the "`nobody`" that the (X)INETD daemon will run as should be used (see above).

   If your `nobody` user is not set up to allow the use of "`su - ...`", you may instead try:

       # pushd /tmp
       # sudo -u nobody gdipinet.pl
       Could not get IP address of client
       # popd

   Ensure that the message "`Could not get IP address of client`" also appears in your system log.

   This test is important. The (X)INETD daemon has no other way to report errors.

   Also, note that the `gdipinet.pl` script suppresses Perl warning and error messages (that is "STDERR") shortly after it starts, since under (X)INETD these would get sent to the network client. It is however possible to capture these for trouble shooting:

       # gdipinet.pl -h
       usage: gdipinet.pl [ -h | -e STDERR_file ]
       usage: GnuDIP (X)INETD Daemon.
       usage: -h: Print this usage message.
       usage: -e: Specify filename prefix for STDERR output. The file name
       usage:     will be this prefix followed by the process ID.

   You could for example use "`gdipinet.pl -e /tmp/gdipinet_STDERR_`".

### Configure the Web Interface

1. Create an administrative user for gnudip using `gnudip/sbin/gdipadmin.pl`:

       # gdipadmin.pl -h
       usage: gdipadmin.pl [ -h | [ -u ] userid password ]
       usage: Add GnuDIP administrative user "user" with password "password".
       usage: -h: Print this usage message.
       usage: -u: Update user if it already exists.

   If you are using the "flat file" GnuDIP database, then before running `gdipadmin.pl` do:

       # su - nobody

   Here, the same "`nobody`" as used for the CGI scripts and the (X)INETD daemon should be used (see step one above). This will ensure that the file that is created is owned by user "`nobody`", and can be used by these GnuDIP scripts.

   If your `nobody` user is not set up to allow the use of "`su - ...`", you may instead try:

       # pushd /tmp
       # sudo -u nobody gdipadmin.pl ...
       # popd

   Note that administrative users cannot be used as dynamic host names. Unlike "host" users, they do not exist only within a particular domain. Any user name you use for an administrative user will become "reserved", and unavailable as a dynamic host name.

2. In the next step, or any time you encounter a problem with the web tool, remember to check the system log for error messages from GnuDIP. If the Web Tool encounters any difficulties using the `logger` command, error messages will be written to the Apache error log.

   In particular, look in the system log or Apache error log for error messages if you get an error from the web tool like this:

   ## Error: GnuDIP Configuration or Interface Problem An internal GnuDIP operation has failed, due to a configuration error, or the failure of a system service required by GnuDIP. Please report this problem to your administrator if it persists.

3. Go to the Web Tool and login as this new user.

   Using "Administrative Settings", add more configuration stuff. There are explanations on the page. In particular, you will need to set your main GnuDIP domain here.

   If you want more than one domain, use "Add Domain" to add them.

   If you did not enable self registration for users, use "Add User" to add users.

4. If in the future you ever remove a domain, or turn off wildcards or mail exchangers, you should use the script `gnudip/sbin/gdipdbfix.pl` to bring the user database into agreement with the new configuration options:

       # gdipdbfix.pl -h
       usage: gdipdbfix.pl [ -h ]
       usage: Scans the database and modifies or deletes users in
       usage: the user database in order to be consistent with the
       usage: set of domains and the administrative settings.
       usage: -h: Print this usage message.

### Keeping DNS in Sync with the Database

> You may want to use the script `gnudip/sbin/gdipzone.pl` in a weekly or monthly scheduled job to reload the zone files from scratch:

>     # gdipzone.pl -h
>     usage: gdipzone.pl [ -h | [ -o outfile ] [domain] ]
>     usage: Scans the database and generates nsupdate input to create zone
>     usage: records. Scans for all domains unless "domain" is specified.
>     usage: -h: Print this usage message.
>     usage: -o: Specify file to write output to.

> Following the example above, the process would be:

> - shutdown `named` using "`ndc stop`" for BIND 8 or "`rndc stop`" for BIND 9.

> - for BIND 9, delete the file `run/zone-dyn.you.net.jnl`

>   Make certain the "`rndc stop`" worked before you do this!!!

> - replace the file `run/zone-dyn.you.net` with an initial zone file like the one used above

> - restart `named`

> - run `nsupdate` using the output from `gdipzone.pl` as input

### Purging Unused User Names

> You may want to use the script `gnudip/sbin/gdipdlet.pl` in a nightly or weekly scheduled job to delete database rows and any zone records for users whose IP address has not been updated for a specified number of days.

>     # gdipdlet.pl -h
>     usage: gdipdlet.pl [ -h | [ -d ] [ -o outfile ] days ]
>     usage: Generates the nsupdate input needed to delete zone records
>     usage: not updated within "days" days. Optionally, it also
>     usage: deletes the user from the database.
>     usage: -h: Print this usage message.
>     usage: -d: Delete users from the database.
>     usage: -o: Specify file to write output to.

### User Maintenance Commands

> There are four line commands that may be useful for user maintenance from the command line or scripts. These are described in `maintenance_commands.html`.

### Remote Maintenance Daemon

> There is also an (X)INETD daemon that may be used to provide the same capabilities as the user maintenance commands via a network protocol. This is described in `remote.html`.

### Linking Non-GnuDIP Host Names to a GnuDIP Host Name

> You may want to use the script `gnudip/sbin/multinsupd.pl` to filter the commands being passed to the `nsupdate` command, in order to insert non-GnuDIP aliases for GnuDIP host names. See the comments in the script, as well as the example and comments in `gnudip/etc/gnudip.conf`, `gnudip/etc/minidip.conf` and `gnudip/etc/multinsupd.conf`.

> This script goes some distance towards addressing the item "A Mechanism to Link Non-GnuDIP Host Names to a GnuDIP Host Name" in `TODO.html`.

### -T, -w, "use warnings;" and All That

> Perl fans may notice that the code does not use "-T" or "-w" on the "shebang" line. Nor is "use warnings;" used. This is deliberate. These options are helpful in testing, but a great maintenance nuisance when used in publicly released software.

> If you want to add these, go ahead. If you get warning or error messages, fix the problem and submit a patch to the mailing list, explaining what release of Perl you are using, and any upgrades you have made to the core Perl modules. While you are at it, perhaps you should ask in your E-mail about joining the GnuDIP support team.