NetReg: Automated DHCP Registration System

NetReg

Southwestern University

Installation Notes
Let me preface this with "this documentation was written at 4am. Please forgive any typos and let me know if something needs a better explanation."
In the interest of making our source code available as soon as possible, documentation will first be a quick run through of how we set up our registration server. I have done my best to make the code as portable as possible but I make no claim it will work on your network. I have also tried to make the different components of NetReg as modular as possible so upgrading should be as easy as replacing a subroutine or file...server specific code is stored in it's own file. Below is the recipe we used for our registration server (herein known as "netreg").
Requirements:(newer versions may work fine, but these are tested)

Dedicated PC (Pentium 200MHz/1.4G HDD/32M RAM/10BaseT Ethernet Adapter)
NetReg
RedHat Linux 6.0
ISC BIND 8 (version that comes with RH6)
ISC DHCP 3.0b
Apache Web Server 1.3.6
OpenSSL*
Apache+SSL*
PERL 5.005_03 (version that comes with RH6)
libnet-1.0606 module (for PERL Net::FTP)**
POP3Client-2.0 module (for PERL Mail::POP3Client)**
SSH
An FTP or POP server to authenticate against
*Note: An SSL server is only needed if you are concerned with security. The entire system will work fine with just a single standard Apache build.

**Note: You need either the libnet or POP3Client module depending on the type of server you want to authenticate against. We prefer the POP server.
Setting the Stage:
The first step is getting RedHat installed. We did a custom install with just the few things we needed: BIND, PERL...no Xwindows or FTP server. We also chose to build our own Apache server so we did not pick this option through the RedHat installer. First thing we did after installing RedHat was to build SSH and disable Telnet and other unecessary services run via inetd (this is optional but recommended [for all machines :)]). After we had a secure Linux box on our network (with a DNS address configured on our campus primary DNS server), it was time to build the servers. At this point I assume your have PERL installed and libnet or POP3Client module installed.
BIND
First server we setup was BIND. This is where a lot of the *magic* happens. You need to be pretty careful in setting this up. BIND should actually be already built and installed by RedHat so all we need to do is setup it's configuration files. Before we configure named, you MUST tell your other DNS servers that your netreg box will be a "Bogus NameServer" or else bad things happen. We learned this the hard way...somehow netreg started answering requests on our network and confused our real nameservers. You must edit your named.conf (for BIND 8) or named.boot (for BIND 4) like so:
BIND 4, add this to named.boot:

bogusns xxx.xxx.xxx.xxx
BIND 8, add this to named.conf:

server xxx.xxx.xxx.xxx { bogus yes; };
where the x's are your netreg machine's IP.
Now, back to our netreg machine...stick the named.conf provided at /etc/named.conf. Now put the db.root file at /etc/db.root. You will need to edit this file to reflect the name and IP of your netreg box. You should now restart your named with the command "/usr/sbin/ndc restart".
You can test to see if the configuration is working right by doing a ping on anything...it should resolve to your netreg IP address.Example:
[root@netreg /etc]# ping foo PING foo.netreg (161.13.1.175): 56 data bytes 64 bytes from 161.13.1.175: icmp_seq=0 ttl=255 time=0.3 ms 64 bytes from 161.13.1.175: icmp_seq=1 ttl=255 time=0.2 ms 64 bytes from 161.13.1.175: icmp_seq=2 ttl=255 time=0.2 ms --- foo.netreg ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.2/0.2/0.3 ms

Of course the machine 'foo' does not exist...This machine thinks it is a root DNS server and is configured to resolve everything to it's own IP address. Be careful...always remember that DNS on this machine is *special* so use IP's when trying to specify another machine (such as your POP of FTP server later on). This concludes BIND configuration.
DHCP
You should download the latest snapshot of ISC's DHCP version 3 server. At the time of publication, the server was in beta. We have found the server to be very stable even back in alpha. You must use version 3 because it is the only package that allows multiple pools per subnet. A simple
./configure; make; make install
should build it just fine. You should now create a directory
/etc/dhcpd/
This is where you will store your dhcpd.conf files. You should also create the directory
/var/dhcpd/
You will also need to create the file
/var/dhcpd/dhcpd.leases
There doesn't need to be anything in this file now, it just needs to exist. Use the dhcpd.conf we have provided as a template. You will need a temporary (un-registered user) range and a registered user range. Since we have the available IP space, we went ahead and gave out globally-routable IP addresses for the temporary range. You probably want to give out interally-routable IP's instead.

Note: Depending on your network configuration, if you disallow IP Broadcasts across subnets or VLANs, you may need to configure your router(s) to forward DHCP broadcasts to your netreg server. On Cisco routers this is done with an ip helper-address.

Once your DHCP server is installed and tested (get machines to try to obtain temporary leases from the netreg server), then you should install a couple scripts:
/usr/sbin/dhcpdctl /usr/local/bin/refresh-dhcpdconf
Since the DHCP server only reads it's conf file when it is started, we need a cron job that checks to see if the server needs to re-read its configuration. The refresh-dhcpdconf script helps do this but cron will need to run this script every minute or two. We have cron running the script every minute as root like so in /var/spool/cron/root:
0-59/1 * * * * /usr/local/bin/refresh-dhcpdconf
Now,
cp /etc/dhcpd/dhcpd.conf /etc/dhcpd/dhcpd.conf.bak cp /etc/dhcpd/dhcpd.conf /etc/dhcpd/dhcpd.conf.new
Within a minute, refresh-dhcpdconf will detect that dhcpd.conf.new is newer than dhcpd.conf and update dhcpd.conf and restart the DHCP server (cat the script to find out what exactly it is doing). The refresh-dhcpdconf script will send its STDOUT to mail, but if you prefer, there are ways of silencing this through cron configuration. At this point, the backend to your registration server is set. Now you need to set up the frontend and administration tools.

Making it all work together:
Apache
Now you should build your apache servers. Don't need to do anything special, as before a
./configure; make; make install
should do the trick. We also decided we wanted the administration portion on a secure server. We installed OpenSSL and built Apache+SSL. You could use just Apache+SSL for both your secure and non-secure websites, but we opted to keep the two separate so we can take down the registration interface without disturbing the administration interface. Use the httpd.conf and httpsd.conf as templates. We're almost home...just need to put the engine in :)
All that remains is the PERL scripts...the brains of the operation. The register.html goes in /usr/local/apache/htdocs/ and gets linked to index.html. This file should be modified to reflect your institution's Usage Policy and web scheme...just have it reflect the location of your register.cgi script (which belongs at /usr/local/apache/cgi-bin/register.cgi). You should also put the variables.pl script in /usr/local/apache/cgi-bin/. Modify the variables.pl to reflect your network settings and paths (the paths should be okay if you used the paths I have specified thus far).
To install the administration interface, create a directory /usr/local/apache/cgi-bin/admin/ and place admin.cgi and subnet.dat here. This directory should be protected by a .htaccess file to prevent just anyone from messing around with your server. You should modify subnet.dat to reflect the subnets you want to manage with the administration interface (these should only be subnets that are using the registration server). Use the subnet.dat provided as a template. You should not need to change anything in admin.cgi (it's best if you don't that way you can just replace the whole file as upgrades become available). You should access the admin.cgi through the secure server (https://).
In Closing:
At this point you should have a working registration server (yes, this was the short version of the INSTALL documentation :). Again, this server was primarily designed for us. I am releasing the code without warranty of any kind in hopes that it may be useful to someone else. I do plan on maintaining the system as much as I can but I do not intend to make this a full-time job.
If you would like to show your appreciation of NetReg, please consider sending me a T-Shirt with your University (or departmental) or Corporarte logo on it :) I wear Large...please send it to:

Peter Valian
Southwestern University
Information Technology Services
Georgetown, Texas 78626

I love to hear success stories, but will also listen to constructive criticism.

mailto:valianp@southwestern.edu and mailto:tkw@southwestern.edu
Copyright ©1999-2002 Southwestern University

NetReg	Southwestern University
Installation Notes Let me preface this with "this documentation was written at 4am. Please forgive any typos and let me know if something needs a better explanation." In the interest of making our source code available as soon as possible, documentation will first be a quick run through of how we set up our registration server. I have done my best to make the code as portable as possible but I make no claim it will work on your network. I have also tried to make the different components of NetReg as modular as possible so upgrading should be as easy as replacing a subroutine or file...server specific code is stored in it's own file. Below is the recipe we used for our registration server (herein known as "netreg"). Requirements:(newer versions may work fine, but these are tested) Dedicated PC (Pentium 200MHz/1.4G HDD/32M RAM/10BaseT Ethernet Adapter) NetReg RedHat Linux 6.0 ISC BIND 8 (version that comes with RH6) ISC DHCP 3.0b Apache Web Server 1.3.6 OpenSSL* Apache+SSL* PERL 5.005_03 (version that comes with RH6) libnet-1.0606 module (for PERL Net::FTP) POP3Client-2.0 module (for PERL Mail::POP3Client) SSH An FTP or POP server to authenticate against Note: An SSL server is only needed if you are concerned with security. The entire system will work fine with just a single standard Apache build. Note: You need either the libnet or POP3Client module depending on the type of server you want to authenticate against. We prefer the POP server. Setting the Stage: The first step is getting RedHat installed. We did a custom install with just the few things we needed: BIND, PERL...no Xwindows or FTP server. We also chose to build our own Apache server so we did not pick this option through the RedHat installer. First thing we did after installing RedHat was to build SSH and disable Telnet and other unecessary services run via `inetd` (this is optional but recommended [for all machines :)]). After we had a secure Linux box on our network (with a DNS address configured on our campus primary DNS server), it was time to build the servers. At this point I assume your have PERL installed and libnet or POP3Client module installed. BIND* First server we setup was BIND. This is where a lot of the magic happens. You need to be pretty careful in setting this up. BIND should actually be already built and installed by RedHat so all we need to do is setup it's configuration files. Before we configure `named`, you MUST tell your other DNS servers that your netreg box will be a "Bogus NameServer" or else bad things happen. We learned this the hard way...somehow netreg started answering requests on our network and confused our real nameservers. You must edit your named.conf (for BIND 8) or named.boot (for BIND 4) like so: BIND 4, add this to named.boot: bogusns xxx.xxx.xxx.xxx BIND 8, add this to named.conf: server xxx.xxx.xxx.xxx { bogus yes; }; where the x's are your netreg machine's IP. Now, back to our netreg machine...stick the named.conf provided at /etc/named.conf. Now put the db.root file at /etc/db.root. You will need to edit this file to reflect the name and IP of your netreg box. You should now restart your named with the command "/usr/sbin/ndc restart". You can test to see if the configuration is working right by doing a `ping` on anything...it should resolve to your netreg IP address.Example: [root@netreg /etc]# ping foo PING foo.netreg (161.13.1.175): 56 data bytes 64 bytes from 161.13.1.175: icmp_seq=0 ttl=255 time=0.3 ms 64 bytes from 161.13.1.175: icmp_seq=1 ttl=255 time=0.2 ms 64 bytes from 161.13.1.175: icmp_seq=2 ttl=255 time=0.2 ms --- foo.netreg ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.2/0.2/0.3 ms Of course the machine 'foo' does not exist...This machine thinks it is a root DNS server and is configured to resolve everything to it's own IP address. Be careful...always remember that DNS on this machine is special so use IP's when trying to specify another machine (such as your POP of FTP server later on). This concludes BIND configuration. DHCP You should download the latest snapshot of ISC's DHCP version 3 server. At the time of publication, the server was in beta. We have found the server to be very stable even back in alpha. You must use version 3 because it is the only package that allows multiple pools per subnet. A simple ./configure; make; make install should build it just fine. You should now create a directory /etc/dhcpd/ This is where you will store your dhcpd.conf files. You should also create the directory /var/dhcpd/ You will also need to create the file /var/dhcpd/dhcpd.leases There doesn't need to be anything in this file now, it just needs to exist. Use the dhcpd.conf we have provided as a template. You will need a temporary (un-registered user) range and a registered user range. Since we have the available IP space, we went ahead and gave out globally-routable IP addresses for the temporary range. You probably want to give out interally-routable IP's instead. Note: Depending on your network configuration, if you disallow IP Broadcasts across subnets or VLANs, you may need to configure your router(s) to forward DHCP broadcasts to your netreg server. On Cisco routers this is done with an `ip helper-address`. Once your DHCP server is installed and tested (get machines to try to obtain temporary leases from the netreg server), then you should install a couple scripts: /usr/sbin/dhcpdctl /usr/local/bin/refresh-dhcpdconf Since the DHCP server only reads it's conf file when it is started, we need a cron job that checks to see if the server needs to re-read its configuration. The refresh-dhcpdconf script helps do this but cron will need to run this script every minute or two. We have cron running the script every minute as root like so in /var/spool/cron/root: 0-59/1 * * * * /usr/local/bin/refresh-dhcpdconf Now, cp /etc/dhcpd/dhcpd.conf /etc/dhcpd/dhcpd.conf.bak cp /etc/dhcpd/dhcpd.conf /etc/dhcpd/dhcpd.conf.new Within a minute, refresh-dhcpdconf will detect that dhcpd.conf.new is newer than dhcpd.conf and update dhcpd.conf and restart the DHCP server (cat the script to find out what exactly it is doing). The refresh-dhcpdconf script will send its STDOUT to mail, but if you prefer, there are ways of silencing this through cron configuration. At this point, the backend to your registration server is set. Now you need to set up the frontend and administration tools. Making it all work together: Apache Now you should build your apache servers. Don't need to do anything special, as before a ./configure; make; make install should do the trick. We also decided we wanted the administration portion on a secure server. We installed OpenSSL and built Apache+SSL. You could use just Apache+SSL for both your secure and non-secure websites, but we opted to keep the two separate so we can take down the registration interface without disturbing the administration interface. Use the httpd.conf and httpsd.conf as templates. We're almost home...just need to put the engine in :) All that remains is the PERL scripts...the brains of the operation. The register.html goes in /usr/local/apache/htdocs/ and gets linked to index.html. This file should be modified to reflect your institution's Usage Policy and web scheme...just have it reflect the location of your register.cgi script (which belongs at /usr/local/apache/cgi-bin/register.cgi). You should also put the variables.pl script in /usr/local/apache/cgi-bin/. Modify the variables.pl to reflect your network settings and paths (the paths should be okay if you used the paths I have specified thus far). To install the administration interface, create a directory /usr/local/apache/cgi-bin/admin/ and place admin.cgi and subnet.dat here. This directory should be protected by a .htaccess file to prevent just anyone from messing around with your server. You should modify subnet.dat to reflect the subnets you want to manage with the administration interface (these should only be subnets that are using the registration server). Use the subnet.dat provided as a template. You should not need to change anything in admin.cgi (it's best if you don't that way you can just replace the whole file as upgrades become available). You should access the admin.cgi through the secure server (https://). In Closing: At this point you should have a working registration server (yes, this was the short version of the INSTALL documentation :). Again, this server was primarily designed for us. I am releasing the code without warranty of any kind in hopes that it may be useful to someone else. I do plan on maintaining the system as much as I can but I do not intend to make this a full-time job. If you would like to show your appreciation of NetReg, please consider sending me a T-Shirt with your University (or departmental) or Corporarte logo on it :) I wear Large...please send it to: Peter Valian Southwestern University Information Technology Services Georgetown, Texas 78626 I love to hear success stories, but will also listen to constructive criticism.

mailto:valianp@southwestern.edu and mailto:tkw@southwestern.edu Copyright ©1999-2002 Southwestern University