1 Introduction

These installation and usage instructions (and the associated installation script) are not intended to be generic/specific enough to enable the installation of Netreg in every location. The installation of a registration system requires the dedicated skills and experience of a computer systems engineer or administrator.

Netreg is a system for registering the MAC address of every machine attempting to connect to a network before providing that machine with a valid IP address and DNS entries.

Features:

· The network information for all registered machines is allocated dynamically through DHCP.

· Once a machine is registered, it may move between any subnet on the network without requiring any changes to network settings. (Perfect for laptops).

· Administrators of the network can easily look up useful statistics, such as how many users are currently active.

· Static hosts (*nix servers, printers etc) are easily excluded from the scope of the system.

· Netreg may be deployed over a large period of time, subnet-by-subnet.

· The registration of a user may be set to expire at any date in the future.

· A user may be temporarily blocked from the network. (eg. as a form of punishment).

Technical Details:

· Multiple forms of authentication are supported, including LDAP, Ftp, POP3, and IMAP.

· There are multiple privilege levels and access controls on a per-user basis.

· Netreg is designed to provide a high degree of reliability, through file locking, synchronisation between hosts (requires the use of a database), support of redundant servers in failover pairs.

· Netreg is designed and tested to scale up to several thousands of hosts.
Architecture

A Netreg system involves:

1.A registration server. This computer is typically responsible for running the web server (for registration of users and administration of the system), a hobbled DNS server, and hosting the system database. Currently supported database types are Oracle and postgresql.

2.A primary DNS server for the domain. This server should be configured for dynamic DNS updates as described in rfc2136 . This DNS server is outside the scope of the Netreg product, and configuration of this server is not included in this documentation. It is assumed that you have the knowledge to configure and administer this yourself, although hints and tips may be included.

3.Any number of remote dhcp servers and slave dns servers. The number of servers depends on the size of the network, and the performance/redundancy requirements of the situation.

This documentation assumes that the registration web server is also used to host the Netreg database and to run the hobbled DNS server (a dns server that resolves all requests to the registration server). It is possible to have any other system run the hobbled dns server, and it is also possible to use an existing database installation on another machine if you wish, however, this will require manual configuration of the system yourself.

In this document, the words “dynamic” and ”roaming” all refer to hosts that are known the the Netreg system and are allocated a random IP in the “known-hosts” range. The words “static” and “non-roaming” refers to hosts that will always be given a fixed IP by the dhcp servers.

NOTE: The database is now strictly required (it was optional in some previous versions). Netreg is developed and tested thoroughly with Oracle 9 as the database, but in principal is designed to also work with postgresql. YMMV.

1.2 Overview Diagram

Operation

1.A user connects their machine to the network for the first time (or after changing their network interface), and requests network settings from a DHCP server.

2.The DHCP server realises that the host is unknown, and provides an IP in a designated unregistered range, and provides the hobbled DNS settings.

3.Whenever the host attempts to access any web page, they are shown the Netreg registration page.

4.After registration, the DHCP server provides the client with a valid IP and real DNS settings. The user may move between any of the subnets known to the netreg system, and will receive the settings relevant for that location without needing to register again.

5.The client's hostname remains constant no matter where the machine is moved. The DHCP servers update the hostname into the DNS whenever the client is assigned a new IP.

2 Pre-Installation Preparation

2.1 Required Information

Before proceeding with the installation tasks, you should gather as much information as possible relating to the following topics:

· Knowledge of subnets. You will need to know the number, location, and purpose of each subnet on the network.

· Knowledge of the number and name of each domain/sub-domain used on the network.

· The IP and details of all systems that will require a fixed IP. For example, servers, some printers, other miscellaneous devices.

· The configuration of the current primary DNS server for the network, and the IP's of all slave servers.

· Any existing DHCP servers on the network. These may need to be consolidated into the Netreg system if they are on a Subnet managed by Netreg.

2.2 Planning

The next step of the install procedure is to decide on the number of dhcp/slave dns servers that will be required for the network. Points to consider include:

· The geographical span of the network. For example, if the system is to be used over 2 university campuses, and then it could be a good idea to have 2 sets of dhcp servers.

· Is there a need to run the servers in a failover pair? Netreg supports the failover mode in ISC's dhcpd distribution by default, but will work equally well without it (although the config files generated by the install script will need modification).

· The subnets to be served by each dhcp server. A large number of subnets may require more servers.

The required specs of each server depend on the number of clients they will be servicing. Hardware specification is out-of-scope of this document.
Preparing for Installation

After deciding upon the number of servers required, the operating system for each server needs to be installed. Netreg had been tested on the RedHat Linux distribution, and on Solaris 8/9, but should work on any Posix-like OS. However, the installation script (the ‘install_script’ file) will currently NOT work on any system type other than Solaris or Linux without modification.

There are subtle differences between operating systems that are relevant to Netreg. For example, there are file locking differences between Solaris 8 and 9, and the formats of some commands used by Netreg (eg. ps) are different between Linux and Solaris. As a suggestion, it may be easier to have all servers use the same operating system to ease maintenance.

Only items necessary for the execution of Netreg should be loaded. For example, ssh and Perl are required, no X-Windows, FTP servers, or inetd services will be required. bind9 and dhcp should not be installed through a package management system, but should be build from source (see later in this document).

3 Required Software and Packages

The following software packages must be available for the Netreg installation:

Required ?	Package	Version tested
Required	Netreg	2
Required	Oracle (or postgresql)	9.2.0 (or any current postgresql ver)
Required	mod_perl	1.99_08
Required	Apache	1.3.X, 2.0
Required	ISC Bind	>= 9.2.1
Required	ISC DHCP	3.0.1rc9
Recommended	OpenSSH
Required	Berkely DB	4.1
Required	Perl	5.6, 5.8

Also, you will require at least 1 ftp/pop3/imap/ldap server to authenticate against (there is an authentication type of NONE, but this is NOT to be used for production!)

4 Perl Modules

The Netreg registration and administration pages are implemented in perl. The system has been tested under version 5.6 and 5.8. It probably won't work with older versions of perl, although you may be lucky. There’s no guarantee that Netreg will work under perl v6 either (when/if it is released). The

Before installing the Netreg perl modules and scripts, it is recommended that the following modules are installed first. The easiest installation method is using the perl CPAN module. The CPAN module takes care of nasty dependencies.
Simply type
perl -MCPAN -eshell
(The first time round you'll be asked some configuration type questions).
To install a module (once in the CPAN shell), type (for example)
install Net::FTP

4.1 Required Modules

These modules are required for Netreg to operate.

Module	MASTER ?	SLAVE ?	Comments
DB_File	Yes	No	Interface to the Berkley database routines for storing session details. See http://www.sleepycat.com/
Digest::HMAC_MD5	Yes	Yes	Authentication between the MASTER and SLAVEs
Digest::MD5	Yes	Yes	Required by Digest::HMAC_MD5
Fcntl	Yes	Yes	Normally installed with perl. For file locking.
FindBin	Yes	Yes	Normally installed with perl.
IO::File	Yes	No	Normally installed with perl.
MIME::Base64	Yes	Yes	Used for encoding data sent between the MASTER and Slaves.
POSIX	Yes	Yes	Normally installed with perl. For process handling, forking.
Socket	Yes	Yes	Normally installed with perl.
Apache	Yes	No	mod_perl support.
Bundle::libnet	Yes	No	Authentication methods.
DBD::XXXXXXX	Yes	No	Database connector to match your database type (see optional modules list for supported ones)
DBI	Yes	No	database integration.
Symbol	No	Yes	Normally installed with perl.

4.2 Optional Modules

These modules are highly recommended for use with Netreg, although not strictly necessary.
NOTE: At least 1 authentication method must be installed. (FTP, IMAP, LDAP, or POP3)

Module	MASTER ?	SLAVE ?	Comments
DBD::Pg	Yes	No	Database integration for postgresql
DBD::Oracle	Yes	No	database integration. For Oracle
Net::FTP	Yes	No	Authentication method.
Net::IMAP::Simple	Yes	No	Authentication method.
Net::LDAP	Yes	No	Authentication method. (Also requires Net::LDAPS)
Net::LDAPS	Yes	No	Authentication method. (Also requires Net::LDAP)
Net::POP3Client	Yes	No	Authentication method.

5 Apache Installation

5.1 Building Apache

If you don't use the standard Apache install from a package management system, then you should build your apache server now.

./configure --prefix=/opt/apache2 --enable-ssl --with-mpm=prefork --enable-rewrite --enable-so --enable-cgi
make
make test
make install

Optional, but useful:
ln -s ./apache2 /opt/apache-2.0.X

ln –s ./apache2 /opt/apache

5.2 Building mod_perl

perl Makefile.PL MP_AP_PREFIX=/opt/apache2 MP_INST_APACHE2=1
make
make test
make install

5.3 Apache configuration

The httpd.conf file must be modified for use with Netreg. The install_script utility will install a suitably modified httpd.conf file for use with Apache2 and mod_perl 1.99.

6 Bind Installation

bind should be built and installed on the registration server, primary DNS server, and all slaves in a “chroot”-ed environment. There are a number of public documents on the web on different ways to do this, so they aren't repeated here, however we do make the following recommendations:

· configure/install it into it’s own location with something like:

./configure –prefix=/opt/bind9

· We use /opt/bind9/chroot/ as our chroot directory.

6.1Key setup

Netreg uses the key authentication in ISC's bind9 and dhcp packages. To create the key to be used for Netreg, execute the following command:
dnskeygen -H 128 -z -n DHCP_UPDATER

The key will be placed in a file KDHCP_UPDATER.*.private. Save the "key" value for later use. Ensure that other people cannot access this key. This key should be entered into your primary DNS server’s named.conf to allow remote DDNS updates from your Netreg server/s (both your MASTER and all the SLAVE servers). Read the named.conf man page for more info on how to set this up.

You should also enter this key when prompted by the install_script utility, so that Netreg can communicate with your DDNS servers correctly. The key is also used by Netreg in it’s communication/s between the MASTER and SLAVE Netreg servers.

6.2 Hobbled DNS Settings

The installation script (as described later) should correctly configure the “dodgy” name server on the registration machine to resolve all requests to the same IP. It will also configure an internal “view” which it uses for it’s own purpose as a secondary of the real DNS server, however by design it will not respond to any queries with this view.

6.3 Primary DNS Settings

Although the setup for the DNS server is out-of-scope of Netreg, the following may be used as a template for the "named.conf" file for a primary DNS system.

# 10.0.0.1 here is your “dodgy” DNS server that is on the Netreg MASTER server.

server 10.0.0.1 {

bogus yes;

};

# in the ‘secret’ you should put the key you created above

key DHCP_UPDATER {

Algorithm HMAC-MD5;

secret "Your_key_here";

};

# required so that your DNS can find the rest of the world

zone "." {

type hint;

file "root.cache";

};

zone "0.0.127.in-addr.arpa" {

type master;

file "0.0.127.in-addr.arpa";

};

# for each of your domains, you need a forward and a reverse setup something like this:

zone "domain.com" {

type master;

file "domain.com/root";

allow-update { key DHCP_UPDATER; };

allow-transfer { key DHCP_UPDATER; };

};

zone "0.0.in-addr.arpa" {

type master;

file "0.0.in-addr.arpa/root";

allow-update { key DHCP_UPDATER; };

allow-transfer { key DHCP_UPDATER; };

};

# a few common options…..

options {

directory "/etc/namedb";

recursion yes; // Enables Recursion

allow-recursion { 10.0.0.0/24; };

version "standard";

};

6.4 Slave DNS Settings

Although the setup for the DNS server is out-of-scope of Netreg, the following may be used as a template for the "named.conf" file for a slave DNS system:

# in the ‘secret’ you should put the key you created above

key DHCP_UPDATER {

Algorithm HMAC-MD5;

secret "Put_your_key_here";

};

# here you link the key above with the primary you will communicate with..

server 10.0.0.100 {

transfer-format many-answers;

keys { DHCP_UPDATER; };

};

# a few common options…

options {

directory "/etc/namedb";

allow-query { any; };

allow-recursion { 10.0.0.0/16; };

};

# for each of your domains, you need a forward and a reverse setup something like this:

zone "domain.com" {

type slave;

notify-source { 10.0.0.100; }

file "domain.com";

masters { 10.0.0.100; };

};

zone "0.10.in-addr.arpa" {

type slave;

notify-source { 10.0.0.100; }

file "0.10.in-addr.arpa";

masters { 10.0.0.100; };

};

# required so that your DNS can find the rest of the world

zone "." {

type hint;

file "root.cache";

};

zone "0.0.127.in-addr.arpa" {

type master;

file "0.0.127.in-addr.arpa";

};

7 DHCP Installation

7.1 Installation

You should download the latest snapshot of ISC's DHCP version 3 server. Version 3 must be used because it is the only package that allows multiple pools per subnet. The version should be 3.0rc9 or above. Installation of the server should be as simple as:

./configure
make
make install

The dhcp server must be installed on all remote servers, and also the registration server. The registration server does not require the service to be running, but requires the dhcpd executable for checking the format of configuration files before sending changes to the remote hosts.

The Netreg install_script utility puts all dhcpd configuration files in the /etc/dhcpd/ directory by default. (can be changed at install time if desired). It also links /var/dhcpd to /etc/dhcpd to correct some installation issues with ISC’s assumed setup.

7.2 Config file layout

Netreg splits the dhcpd configuration over several files as follows:

File	Description
dhcpd.conf.failover	Contains the failover peer declaration. This file may be empty if failover mode is not required (but the file MUST exist).
dhcpd.conf.master	Contains any global options and options for each group of hosts. Also includes subnet declarations. Can/Will be edited via the admin web interface of Netreg for everything except the adding of subnets. This file is synchronised between the registration server and all other dhcpd servers. During the synchronisation process, the file is filled out with all hosts in their respective groups.

7.3 Setting up the server

The dhcpd.conf.master file will require hand modification after Netreg is installed. A new section is required for each subnet the dhcpd server will answer requests for (copy and paste the example declarations with the IP's and subnets changed).

The dhcpd.conf.master file defines IP ranges for unregistered hosts. This range may be globally-routable IP addresses or only internally-routable IP's.

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 the server has been started and tested, the refresh-dhcpdconf script should be executed frequently. This script checks for changes to configuration files (dhcpd.conf.master.new), and reloads the dhcpd server as appropriate. This script is designed to be run inside a cron job. Your crontab needs to contain the line:

* * * * * /usr/local/bin/refresh-dhcpdconf > /dev/null 2>&1

8 Netreg Installation

8.1 Install Script Overview

The provided install script attempts to perform the following actions:

· Determine whether the installation is for a registration server or slave,

· Write template configuration files with the correct IP addresses & settings.

· Copy files to their correct locations.

Although the install script has been tested and works quite well, it does not install the Netreg product completely. There are still some manual tasks to perform as outlined in parts of this document.

The install_script is designed to be able to be re-run multiple times (to reinstall a newer/modified or bug-fixed version for example).

Re-running it with “./install_script –auto” will cause it to be run with exactly the same answers to the questions that you provided the previous time you ran it. It just asks whether you are installing a MASTER or a SLAVE server and nothing else.

Re-running it with “./install_script-auto=MASTER” or “./install_script –auto=SLAVE” causes it to behave as per the previous point, except that it becomes a totally hands-off re-installation.

(TODO: what other tasks are required? – eg setup of the SSH keys by running sync_dhcpd_conf.pl and copying known_hosts to ~webuser/.ssh/known_hosts or /etc/sshd/XXXX?)

8.2 Install Script Details

The install script is charged with the responsibility of as correctly as possible determining your requirements for installation of the Netreg product, and after determining the critical site specific settings, installing all the correctly configured files to the right places.

To do this, it asks quite a lot of questions (54 at time of writing when installing on the MASTER). In some cases it will be able to automatically figure out the locations of certain things for itself (and verify with you before continuing), but in others, it wont, and will depend on you to provide the correct information to it.

Thankfully, if you get stuck because you don’t have something that is required (for example a SSH v1 identity and identity.pub file/s for use with Netreg), or for any other reason, you can always cancel the script, solve the problem and re-run it again later without any problems at all.

However, once you have installed Netreg correctly and have made customised changes to any/some of the files that are installed on your system (most notable Variables.pm and dhcpd.conf.master), then it is ESSENTIAL that you backup all these files that you have customised BEFORE you re-install Netreg using the install_script, as it WILL return all files to their just-installed state.

8.3 Installing multiple slaves

The installation script attempts to ease the installation of multiple hosts with similar configurations. After running the installation script on the registration server (also called the MASTER), information required for each slave server installation is automatically generated, and saved into a ./SLAVE/ sub-directory.

To install each slave, copy the ENTIRE Netreg directory (including the SLAVE directory etc) to all slaves, and execute the install_script again, answering the questions where relevant for a slave server installation. To do this ‘copy’, you can either tar up the directory structure and copy the tar file to your slave servers, or as a better alternative in many cases you can NFS export the directory on the master server, and mount that directory on each of the slaves. The second way prevents files getting out-of-synch with each other, and means that your installation files are always kept in just one place.

The install script does not attempt to start DNS and dhcpd services unless requested. These services should be thoroughly tested, and then the appropriate startup script called.

8.4 Configuring the database

The database, tables and schema need to be created by hand using one of the "netreg.*.sql" definitions in the /db/ directory of the installation media. Because of the differences in database management, at this time this step is NOT performed by the install_script utility, and should be done manually.

8.5 Configuring the Netreg interface

You will want to modify the HTML so that it reflects your institution's Usage Policy and web scheme. All institution specific HTML has now been separated from the code entirely, so that you can view the page segments in your /cgi-bin/html/ directory (typically /opt/apache2/cgi-bin/html/ directory post-installation, or ./usr/local/apache/cgi-bin/html/ directory in the installation media prior to installation) , and change these to suite your needs.

If you have different requirements on the type and number of fields that are displayed to users (eg if the person registering a network device will always be the ‘owner’ of that device), then you can also modify the HTML pages, so that <input type=text …> fields are where required changed to <input type=hidden …> or similar. The institution specifics for this are left as an exercise for the administrator/s.

8.6 Configuring system specifics (post-install)

You should review and modify where necessary the installed Variables.pm file to reflect your network/preferred settings and paths. The critical settings will have been populated into the Variables.pm file for you by the install_script utility, but it is still worth reviewing this file and verifying it’s contents.

8.7 Configuring the remote dhcpd manager

The program "dhcpdmanager" is a daemon that just needs to be run once after each server reboot on each slave (dhcpd) server. You will see it as a permanently running process, and it takes 0% of CPU time, and practically no memory for most of the time.(and only a little cpu, when it's actually used).

Sending this server a standard "kill" signal will kill it cleanly. Sending it a HUP signal will cause it to restart itself. It keeps the current (or most recent) process ID (pid) in the file called /etc/dhcpd/daemon.pid.

The dhcpdmanager source will be edited automatically during installation to ensure the "key" (DHCP_UPDATER) is correct. If this is not done, then the registration server will not be able to connect to the remote servers to query them for info.

9 Netreg Interface Overview

The Netreg interface consists of 2 sections - the automatic registration page and the administration interface. Each interface requires a username/password for access, as provided by the systems administrator. Each username/password given may be valid for none, one, or both of the interfaces.

The following features must be enabled in the client's web browser:

· Cookies. Only a temporary session cookie is used (ie. It will not be written to disk).

· Javascript.

· Pop-up windows.

· CSS.

9.1 Automatic (or Simple) Registration Page

Location: /cgi-bin/index.cgi (the page should automatically redirect from other url's).

The automatic registration page allows users of the system to register a host for roaming DHCP without needing to enter details of the computer's MAC address.

Before accessing this page, the following requirements need to be met:

•The computer is set to obtain its IP and DNS settings from the DHCP server.

•The computer has not been previously registered, or its registration has expired.

•The computer is currently connected to a subnet supported by the Netreg system.

Procedure for registering a host

•Turn the machine on. It should obtain a temporary IP allocation from Netreg and DNS server settings. The DNS server will resolve all queries to itself.

•Using a web browser to navigate to any page will, with the assistance of the modified (or “dodgy”) DNS settings, cause you to directed to your Netreg server URL: https://netreg.domain.au/cgi-bin/index.cgi

•Log on to the system.

•Enter the following details:

Compulsory ?	Field	Description
Yes	Asset	A 6 digit asset university asset number for the host that is being registered. Use leading zeros to pad the value to 6 digits. If registering a machine that is not a university asset, then use the administration interface. In environments that do not have equipment assets may choose to use 6 digits from a serial number or similar; or they may choose to modify the html templates to populate this field with default data (using hidden form fields as mentioned earlier in this document).
Yes	Owner	A university staff or student number preceded by the character 's'. Eg. s0123456. The number of the owner of the computer should be used, or, if not applicable, the number of a person responsible for the machine. The number should be left padded with zeros if it is less than 7 digits. If registering a machine that is used by multiple people (such as in a computer lab), privileges may be granted to allow entering a value that does not follow the s-number format. In other environments you may choose to not use this field. The HTML templates can be modified to not display this to the user/s, and instead populate it with default data.
No	Date	An optional value for the automatic expiration of the machine. After the given date, the machine will no longer get registered IP or DNS settings, and will need to re-register. The field must be in the format dd/mm/yyyy. This field is intended to allow short-term access to the university network. If no value is given, then default value of 5 years from the current date is used as it is expected that PC’s will be replaced within 5 years.
Yes	Domain	A drop-down box showing the available domains for the given subnet. The most appropriate domain should be chosen. If no domain in the list is appropriate, then privileges may be given to select from the entire list of university domains. Note: Roaming users may move their machines between subnets freely, including subnets that are not normally valid for the given domain. The computer's domain name will stay fixed to the one chosen here in the Netreg system.
No	Hostname	Hostnames may only be chosen by users with higher privileges. This field may not always be visible. If no hostname is entered (or unavailable for entry), then the default hostname of 'pc' + asset number is used. In the case of assets with multiple network cards, then each subsequent entry will be given 'pc' + asset number + '-' + a unique number. When entering hostnames, do not include the domain name. Eg, to register test.domain.com use 'test' as the hostname and 'domain.com' as the domain.
No	Comments	An optional field for entry of free-text comments. These comments should be brief, relevant, and only used if the information is likely to be needed by users of the Netreg system in the future.

4.Click the 'Accept' button. If an error message appears, then the registration has been unsuccessful. (Note: there is an exception to this. If the error message says that remote hosts could not be contacted, then the registration will be completed when the host is available). Use the back button of the browser to correct any mistakes.

5.Wait up to 1 minute as prompted, and reboot the machine. Rebooting is necessary on Windows 9x computers to obtain new DNS server entries. Manually releasing/renewing the DHCP lease will not work.

6.Log out of the system using the 'Logout' button in the top right hand corner of the page prior to rebooting. The system will automatically log out after being left idle for 1 hour, or when the browser is shut down.

7.The machine is now ready for use on the University network. It may be used immediately on the dhcp failover pair from which the registration was made, and within 15 minutes on all other failover pairs. It will be initially located in the “Roaming:Default” group. Groups are accessible via the “DHCP Options” section of the admin page.

9.2 Administration Page/s (ie Advanced interface)

Location: /cgi-bin/admin/admin.cgi

The administration page allows users of the system to search for information about subnets and hosts, add static/roaming DHCP hosts, add/delete/manage host groups and subnets (except for adding of subnets – yet ED), and to manage dhcp config file options.

Using the registration page

•Use a web browser to navigate to https://netreg.domain.com/cgi-bin/admin/admin.cgi

(Alternatively, you can click on the ‘Administration Interface’ button on the bottom of Simple Registration Page if you prefer)

•Log on to the system (Note: sufficient privileges are required to use the administration interface – see the AUTH types in Variables.pm and in the Database; and in the auth.dat file for access controls.)

•Select any options you require – see below (sections 9.2.1 to 9.2.11).

•Log out of the system using the “Logout” button in the top right hand corner of the page.

9.2.1 Find all computers in a subnet

· Choose the “Subnet Overview” option.

· Click on the subnet you are interested in.

The list displayed is based on the current DHCP leases, with the addition of any known static hosts. Only hosts that hold current dhcp leases will be displayed.

9.2.2 Search for DHCP leases

· Choose the “Search Leases” option.

· Enter a search term. This may be part of a MAC address, IP address, or lease date.

A red dot next to the IP address indicates that it is an “active” lease. There may be more than one active lease for each IP if the dhcp server hasn't cleaned out its leases file (this occurs periodically).

Clicking the mac address will display further information about the host, including its hostname.

9.2.3 Search for information about a host

· Choose the “Search Hosts” option.

· Enter a search item. This may be part of a MAC address, hotname, domain, login name, platform, group or status.

Clicking on the MAC address will display all historically logged information about that MAC address.

Clicking on the group will display the dhcp options for that group (as well as other hosts/groups within the group).

Clicking the “L” next to each host will display lease information for that host (It does a lease search for that host as per 9.2.2)

Clicking on the user (s-number) will open a new window displaying details of that person (eg. phone book entries, if supported by your Netreg installation).

Clicking ‘expire’ will pop-up a new window allowing the host to be expired or locked out (only available for roaming hosts). See 9.2.7

Clicking ‘delete’ will pop-up a new window allowing the host to be deleted (only available for static hosts). See 9.2.6

Clicking the update button will pop-up a new window allowing the host's details to be edited, including being changed to a different host group (See 9.2.11 for more on groups).

9.2.4 Adding a Host via the Admin Interface.

NOTE: Adding Hosts via the administration interface is for advanced setup of hosts, or for adding a host that is not your current host.

If a subnet has been converted to the Netreg system, then all hosts in the subnet should be registered in Netreg, including hosts that do not DHCP. This ensures that the DHCP server will not assign IP's that are reserved for the static hosts.

Adding of static hosts requires different privileges to roaming hosts.

Choose the “DHCP Options” option.

· Navigate to the group in which the host shall reside.

· Click the “Create Host” button.

· Enter the following details:

Compulsory ?	Field	Description
No*	Hostname	When entering hostnames, do not include the domain name. Eg, to register test.domain.com use 'test' as the hostname and 'domain.com' as the domain. * The hostname will default to “pcassetno” if no hostname is entered. Hostnames are required to be entered for non-uni assets.
Yes	Domain	A drop-down box showing the available domains. The most appropriate domain should be chosen.
Yes	IP	The static IP of the host. eg. 123.123.123.123. Checking the “dynamic host” checkbox causes the IP entry to be disabled, and makes that host a roaming/dynamic host.
Yes	MAC	The MAC address of the network interface to be connected to the university network. It should be entered as 6 groupings of hexadecimal digits. Eg. 13:ef:4:08:3d:8f
Yes	Owner	A university staff or student number preceded by the character 's'. Eg. s0123456. The number of the owner of the computer should be used, or, if not applicable, the number of a person responsible for the machine. The number should be left padded with zeros if it is less than 7 digits. If registering a machine that is used by multiple people (such as in a computer lab), privileges may be granted to allow entering a value that does not follow the s-number format.
Yes	Asset number	A 6 digit asset university asset number for the host that is being registered. Use leading zeros to pad the value to 6 digits. If registering a machine that is not a university asset, then check the box marked “Non-University Asset”. Note that extra privileges are required to perform this operation. Standard policies regarding connecting non-uni assets to the network should be followed.
No	Platform	The platform (operating system) the system is running. Choose the most appropriate item from the list, or “other” if nothing is appropriate.
No	MX records	A comma separated list of mail exchanges for the host. It should be in the form of “priority host”. If entered, any current MX records in the DNS system will be deleted, and replaced by the list given. eg. 10 a-host.domain.com,5 another-host.domain.com
No	CNAME records	A comma separated list of common names for the host. If entered, any current CNAME records in the DNS system will be deleted, and replaced by the list given. eg. www100.domain.com,anothername.domain.com
No	Comments	An optional field for entry of free-text comments. These comments should be brief, relevant, and only used if the information is likely to be needed by users of the Netreg system in the future.

Click the 'Confirm' button. If an error message appears, then the “add host” window should pop-up again with the error message displayed.
Once the host is entered, it will be entered into the DNS system immediately, and entered into the DHCP system within 15 minutes (or within 60 seconds if the “Force Update” button is pressed. Note that this may require extra privileges).

9.2.5 Editing a host

To edit an existing host (either static or dynamic), find the host through the “DHCP Options” or “Search Hosts” page, and click the “update” button next to that host. To change the greyed-out field/s (ie MAC address, hostname, domain name) of the host, delete or expire the entry and add a new host.

9.2.6 Deleting a static host

To delete a static host, find the host through the “DHCP Options” or “Search Hosts” page, and click the “delete” button next to that host. A pop-up window will ask if you wish to delete only the IP address from the DNS system, or to delete all records (eg. MX, CNAME, HINFO etc) from the DNS system for that host.

9.2.7 Deleting a dynamic/roaming host

Roaming hosts may either be expired or locked out from the system. Find the host through the “DHCP Options” or “Search Hosts” page. Click the expire button next to the host, and a pop-up window will appear asking for confirmation. If privileges allow, it will ask whether you wish to expire or lock the host. Locking a host requires the entry of a date, after which time the host will be able to register again.

Note: To register a host that has been locked from the system, either wait until the lock has expired, or lock the host from the system again with a date in the past. This will convert the host into the “expired” state.

9.2.8 Adding a DHCP option

DHCP options are added via the “DHCP Options” page. Options may be added that take effect over a selected group of hosts, a subnet, a campus, or all campuses, depending on privilege levels.

Entering an option when viewing a single subnet or group will take effect over that subnet/group and sub-groups. Entering an option at a higher level will have an effect over a recursively larger “tree” of groups and hosts.

To add a DHCP option, type the option name into the “option name” field, and the corresponding value into the “value” field, then click the “Create Option” button. The Netreg system supports all options of the form “option xxx = xxx;” and some special options of the form “xxx = xxx;” (See section 10.9 for adding extra special options).

If any particular text of dhcpd.conf strings are unsupported by Netreg, they are made visible via the “Other DHCP Configuration Info” field at the bottom of the page, and sent to the dhcp servers as-is. If you are unsure if an option of the form “xxx = xxx;” is supported, then enter it in the “Other DHCP Configuration Info” field. The next time Netreg parses the configuration file (ie on the next page reload) any text that is supported by Netreg will appear in the option listings on htat page instead of the ‘Other ..’ field.

9.2.9 Editing a DHCP option

DHCP options are edited via the “DHCP Options” page. Locate the option of interest, and type the new value into the text field where the current value is displayed. Click the “Update” button corresponding the the DHCP option that was edited.

9.2.10 Deleting a DHCP option

DHCP options are deleted via the “DHCP Options” page. Locate the option of interest and click the “Delete” button next to the corresponding option.

9.2.11 Using DHCP Groups

The layout of the DHCP options page directly reflects the dhcpd.conf.master config file. In fact, the code that displays these pages actually parses the dhcpd.conf.master file directly for all the information that is displayed, and modifies that file when changes are made.

It is a hierarchical grouping structure starting with two primary groups below ‘Home’ called “Roaming” and “Non-Roaming”. Below these groups, can be any number of arbitrary groups and subnet declarations according to your policy making and technical requirements.

Typically Subnet declarations should be put somewhere under the Non-Roaming group (either directly, or grouped by location for example), dynamic host records should be put somewhere under the Roaming group (Roaming:Default by default). Static host declarations can be put either inside your non-roaming section inside the relevant ‘subnet’ group declaration, OR alternatively in your ‘roaming’ section in arbitrary groups. This again is a technical/policy decision for your environment.

In the Griffith University environment, we found that the former (ie static hosts are located in the actual subnet declaration) set-up is much easier to manage once you reach more than a few subnets in the installation.

10 Administration Tasks

Unless specified otherwise, or changed in your Netreg installation, all files mentioned in this section are located under /opt/apache2/cgi-bin/ in a typical Netreg installation.

Note: many file locations and system options may be set/viewed in the Variables.pm file after installation.

10.1 Checking system integrity

The utility “check_consistency.pl” is provided to maintain the integrity of the system. It is intended to be executed periodically by the administrators of the Netreg system (ie By cron)

The Netreg system may become inconsistent due to:

· DNS entries being manually edited for static hosts within the Netreg system.

· Dhcp groups being changed manually in the dhcp config files without updating host entries in the database.

· Other unexpected events.

To execute the utility, just type “./check_consistency.pl” in the Netreg directory. It will check the consistency of the database, dhcp, and dns information, and display any errors it finds to the screen. It is up to the user to correct these errors manually if the utility doesn't specifically say “fixed” next to an error.

The most common consistency issue typically encountered is that if a ‘group’ no longer existing in the dhcpd.conf.master config file (typically because it was deleted by an administrator), while still being referred to by host records in the database. If invalid group records are located, the host’s database records are changed to the ‘Roaming:Default’ group, which must always exist.

10.2 Keeping the DHCP configuration synchronised

Netreg requires that the registration server synchronise the dhcpd.conf.master file from the master out to all slave servers on a regular basis.

The utility “sync_dhcp_conf.pl” performs this. It has two responsibilities:

1. Taking a copy of the dhcpd.conf.master file, and populating it with all the host entries from the Netreg database.

2. Distributing this newly populated config file to each of the slave servers registered in the Netreg database.

After installing Netreg (and setting up your slave servers in the database), the administrator should run this script (as root) by hand, and verify that it is able to distribute the files to these slaves without any interaction from the user.

After you have successfully tested that it can run un-attended, the script "sync_dhcp_conf.pl" should be run every 15 minutes in a cron job as root. It is also triggered by the “Force Update” function on the administration web interface.

If synchronisation is not working, then the script should be executed manually to see if it reports any errors. The script should also be tested manually as the webserver user (typically ‘nobody’ or ‘httpd’) Permissions on files in the /etc/dhcpd dirs on the remote hosts may also need to be checked.

NOTE: If you don’t already have all your SSH host keys for all servers defined in all your servers (in the /etc/ssh/ssh_known_hosts file), you may need to do this before the script will work hands-off. Ie: append all the /etc/ssh/ssh_host_dsa_key.pub and /etc/ssh/ssh_host_rsa_key.pub files from all Netreg hosts into the one big file, and copy/save it as /etc/ssh/ssh_known_hosts onto every Netreg host.

For this to work, a user with write access to the /etc/dhcpd/* files on the remote hosts is necessary, and is specified in the Variables.pm file – typically this would be the ‘netreg’ user. This user, and the permissions should be setup for you on the slave servers by the install_script utility.

Note: To protect the performance of the system, only one instance of the utility may be run at a time. If another instance is started, it will wait for the previous instance to complete. If two instances have already been scheduled, then any attempted use of the utility will fail and display an error message.

This script expects a ssh v1 identity file to be present in the cgi-bin directory, as prompted for by the install_script at install time.

10.3 Importing Hosts

The utility “import.pl” is provided to import large lists of hosts into the Netreg system. If the utility detects database errors during the import, then the data will be rolled back and no hosts will be commited. Errors in the input file need to be corrected before the utility is executed again. The import script will also prompt the user after parsing the entire file whether the changes should be commited to the database if errors are not automatically detected.

TODO: Using the batch ID field?

The utility expects to be provided with a filename containing comma-separated values. Each host is on a new line. For example,

$./import data.csv

where data.csv contains multiple lines similar to:

00:00:99:88:77:66,www999,076543,INS,my.domain.com,S,2010-01-01,Solaris 9,,123.123.10.10,

Compulsory ?	Field	Description
Yes	MAC	The MAC address of the network interface to be connected to the university network. It should be entered as 6 groupings of hexadecimal digits. Eg. 13:ef:4:08:3d:8f
Yes	Hostname	When entering hostnames, do not include the domain name. Eg, to register test.domain.com use 'test' as the hostname and 'domain.com' as the domain.
Yes	Asset number	A 6 digit asset university asset number for the host that is being registered. Use leading zeros to pad the value to 6 digits. If registering a machine that is not a university asset, then use the value “-1”.
Yes	Owner	A university staff or student number preceded by the character 's'. Eg. s123456. If registering a machine that is used by multiple people (such as in a computer lab), enter the University division that owns the computer. eg. A school or division abbreviation.
Yes	Domain	The domain the computer is to exist in.
Yes	Status	Either “R” for roaming/dynamic/registered machines, or “S” for static hosts.
Yes	Expiry Date	In the format YYYY-MM-DD. The date at which the host will no longer be registered with the Netreg system.
Yes	Platform	The platform (operating system) the system is running. Eg. “Windows” or “Other”.
No	Comments	An optional field for entry of free-text comments. These comments should be brief, relevant, and only used if the information is likely to be needed by users of the Netreg system in the future. The comment field must not contain commas.
No*	IP	The IP of a static host. eg. “123.123.10.10”. An IP must only be entered if the Status is “S” (static).
No	Group	An optional group to insert this host into. The available groups are listed by the “Dhcp Options” pages of the admin interface. Groups should be delimited using a colon (:). By default each host will be in the “Roaming:Default” group.

10.4 Adding a subnet

To add a subnet to the Netreg system:

1. Stop the webserver (to prevent data corruption).

2.Run the add-subnet.pl script, and answer the questions as appropriate. Important: VERIFY that the script has correctly edited the dhcpd.conf.master file!

What this script does:

· Add a subnet declaration to the dhcpd.conf.master file (something like this):

subnet 123.123.XX.0 netmask 255.255.255.0 {

default-lease-time 28800;

option domain-name-servers 123.123.1.1,123.123.250.10;

max-lease-time 28800;

option routers 123.123.XX.209;

pool {

failover peer "dhcp";

range 123.123.XX.20 123.123.XX.200;

deny dynamic bootp clients;

deny unknown clients;

}

pool {

failover peer "dhcp";

range 123.123.XX.220 123.123.XX.250;

deny dynamic bootp clients;

allow unknown clients;

default-lease-time 240;

option domain-name-servers 123.123.250.1;

max-lease-time 240;

}

· Add the subnet definition to the Netreg database.

· Connect to Oracle (or postgresql).

· Display a list of available campuses by entering:

select distinct campus from campuses;

· Enter the subnet with:

insert into subnets values ('123.123.XX.0','MYMASK','MYCAMPUS','DESC');

where XX is a subnet, MYMASK is a CIDR subnet mask (almost always 24), MYCAMPUS is a value given by the previously shown list of available campuses, and DESC is a description of the subnet.

· Define a range of IP's for unregistered hosts (NOTE: this is the dhcp “range” option in #3).

· Connect to Oracle (or postgresql)

· Enter the range with:

insert into ip_range values ('123.123.XX.220','123.123.XX.250','123.123.XX.0','MASK','Y');

where XX is a subnet and MASK is a CIDR subnet mask (almost always 24).

· Define a method of authentication for the subnet.

· Connect to Oracle (or postgresql)

· Enter the default auth method with

insert into authentication values ('123.123.XX.0','MASK','ldap-auth.domain.com','LDAP');

· Note: Multiple auth methods (such as NONE,IMAP,POP,FTP) are allowed per subnet. If one fails, then the next is attempted.

· Add a list of domains available to the subnet. See section 10.5.

3. Start the webserver.

10.5 Adding a domain

After the domain has been added to the DNS system:

1. Connect to Oracle (or postgresql)

2. For each subnet that the domain is normally used on, enter

insert into subnet_domain values ('123.123.XX.0','MASK','my.domain.com');

10.6 Deleting a domain

1. Connect to Oracle (or postgresql)

2. Enter

select mac from interface where domain = 'my.domain.com');

3. Move all hosts that appear to a new domain (through the admin interface), and execute the above query again to ensure no hosts remain in the domain.

4. Delete the domain with

delete from subnet_domain where domain = 'my.domain.com';

10.7 Add a user

To add a user to the Netreg system (for either registering hosts or administrating the system or both):

1. Add the user into the authentication server defined for the subnet they are to authenticate to. If the user is to authenticate from subnets that are not known to the Netreg system, then also add the user to the global authentication server (as defined in Variables.pm). In most cases the global server and the per-subnet server will be the same LDAP server

ldap-auth.domain.com (in which case the user only needs to be added once).

2. Define the privilege levels for the user in the auth.dat file. (See the comments at the start of the file for details.)

3. Restart the webserver.

10.8 Editing the list of available platform types

1.From the Netreg directory, open the file html/static_addhost.html with a text editor.

2.Search for the line <option value="^PLATFORM">^PLATFORM</option>

3.Edit the list of available platform options under this line.

10.9 Editing the list of known dhcp options

Some ISC dhcpd configuration options require the “option” prefix, while some do not. Entering as an option one that does not require the “option” prefix will cause the dhcp servers to fail, unless Netreg is specifically told about the option. Consult the dhcpd.conf(5) man page for the a list of valid options.

The dhcpd_options.dat file lists options without the “option” prefix. Each option should be separated by a new line.

Note: Valid options that do not require the “option” prefix may be entered into the “Other DHCP Configuration Info” entry fields in the admin page regardless, and will not cause any failure.

10.10 Adding a new DHCP/DNS server to Netreg

Install Netreg on the target machine using the installation instructions

1. Stop the webserver.

2. Connect to Oracle (or postgresql).

3. Execute select distinct campus from campuses;

4. Decide on either an existing campus or a new campus.

5. Execute insert into campuses values ('CAMPUS','SERVER_IP');

6. If the server is on a subnet that is not converted to the Netreg system, then setup a “dummy” subnet declaration. This is necessary so that the dhcp server knows to listen on the network interface.Edit the dhcpd.conf.master file. This declaration should be within an existing group. Locate the group under which the subnet should belong (identified by file comments), then insert the following example text (for a server on the ip “123.123.6.6”)

subnet 123.123.6.6 netmask 255.255.255.255 {

}

7. If the server is on a subnet that is already converted to the Netreg system, then no further changes are necessary.

8. Restart the webserver

10.11 Changing DNS keys

To change the authentication key between all servers:

1. Run the command:

/usr/sbin/dnskeygen -H 128 -z -n DHCP_UPDATER

2. Save the key value listed in the new file KDHCP_UPDATER.*.private.

3. Replace the key in the named.conf file of the primary DNS server.

4. Replace the key in the named.conf files of the secondary DNS servers.

5. Replace the key in the dhcpd.conf.master file on the registration server.

6. Replace the key in the Variables.pm file on the registration server.

7. Replace the key in the /opt/bin/dhcpdmanager files on all Netreg slave servers.

8. Restart all DNS servers, dhcpdmanager servers (/etc/init.d/dhcpd-manager) and the webserver.

11 Troubleshooting Hints

Here's a list of common problems, and their potential solutions:

· permissions on files that prevents 'nobody' or your web server user from writing to certain /etc/dhcpd/ files etc. The install_script uses a "netreg" group to set file permissions correctly, and you may fine that ‘nobody’ needs to be a member of that group.

· missing symbolic links, or bad config/startup scripts , so that dhcpd or bind are a using the wrong config/pid files etc, or the config/startup files are syntactically bad.

· badly written /etc/init.d/ scripts that sometimes kill more than they should (eg the "/etc/init.d/dhcpd" script that should only kill the "dhcpd" server with a "stop" request might also incorrectly kill the "dhcpdmanager" daemon (because it parses the entire process list looking for any process that contains the string 'dhcpd', and kill them all).

· config files being simply wrong, or just-slightly off. (eg in refresh-dhcpdconf defining the dhcpd.pid as being in /var/run, and then in the /etc/init.d/dhcpd defining it as somewhere else). Remember, sometimes servers don't give you the option to specify where you REALLY want certain files to be as it's hard-coded into them at compile time, so you to use sym-links there....that's why I have a few common ones set-up by the install_script.

Useful hints:

· run a "tail -f /var/log/messages" (or on solaris tail -f /var/adm/messages) in one window while setting it all up, and make sure that the servers are all restarting correctly when appropriate.

· If you have perl errors, do the same "tail" as above, but on the apache log file "error_log".

· Check, Double, and triple-check your config files.

· DON’T put comments into the dhcpd.conf.master file (our parser uses comments for it’s own purposes – to name group declarations). This will be fixed in a future version.

12 Development hints:

· During development I always have this command set running in a window: “tail -f /var/log/messages & ; tail -f /opt/apache2/logs/error_log & ; tail –f /tmp/Netreg_errors.log & ; “ so that I can keep an eye on every error the system issues/has in real time.

· FYI: your answers to the questions asked by the install_script are cached in two files: .tmp.default_answers.MASTER and .tmp.default_answers.SLAVE in the installation media directory, so if you forget what you answered when you last installed, you can review these files. If the install_script is giving the wong default answers, it’s because it’s reading old info from these files. Delete them, or correct them, and re-run the install_script.

· During development I work with the UN-installed files (ie a checked-out copy from CVS) as the primary source of information, and regularly find myself running the following command/s after any code changes that I need to test:

“cd path/to/root/of/modified/un-installed/version/netreg ; ./install_script –auto=MASTER ; /etc/init.d/apache stop ; sleep 1 ; env – sh /etc/init.d/apache start ; cd -“

What it does is re-install the entire set of (just updated/modified) files, and restart the webserver (because the application runs as mod_perl, a webserver restart is required when code changes are made). You may need to replace ‘apache’ with ‘httpd’ in your environment.

13 Miscellaneous / Known Issues

13.1 DHCP group naming limitations

All group levels are delimited by colons (:). The system will break if groups are manually created with names that contain spaces, colons, or several other punctuation characters (underscores are OK).

Groups are identified in the dhcpd.conf.master file with comments on the following line. For example, the group group1:group_name would be nested within another group, and look like:

group {

#group_name

Netreg expects that the group “Roaming:Default” is always available. All new registrations are placed into this group by default, and the consistency checker places hosts in unknown groups here.

13.2 Unknown hosts limitations

The number of IP's reserved for unknown hosts generally have a limit of around 30 in our sample config files where the unknown hosts are allocated in the range 220-250. The dhcp servers may allocate multiple IP addresses per machine when they boot up. For example, network card boot roms and Windows will send different client ID's to the dhcp server, and may be given two different IP's.

The number of IP's for unknown hosts will run out rapidly if an entire lab or room of new computers are turned on at once. The IP's of each machine may change often due to their short lease times, and this causes problems if the machine is attempting to register with Netreg (because Netreg may register the wrong machine, causing a “Hardware already registered” error.). Using a lease time of around 4-6 minutes seems to prevent the majority of these problems.

13.3 Restarting Apache (or check your /etc/init.d/ scripts!)

To start the webserver with SSL support, use /etc/init.d/apache stop|start on the registration server. Alternatively, use the command /opt/apache2/bin/httpd -k start -DSSL. Do not use /etc/init.d/apache restart as this may break temporarily break SSL, until the server is “stopped” and “started” again.