3 

 

2   Installation

2.1  Installation Basics

We are going to assume that you know all the requirements (see below) and can get Apache built with SSL and mod_perl, Perl, DBI, and DBD::mysql built, and mysql built, installed, and running. There is extensive documentation with these packages, and we would only be duplicating the work of others. Note that the CPAN module is very useful for getting modules out of CPAN.

Installing NetReg is not an easy task. The installation could be made vastly easier, and telling us about your experiences installing it will be helpful in this regard.

Here's a brief synopsis of the installation:

  1. Review requirements/recommendations
  2. Install the database schema/initial data
  3. Run the netreg-install script to build the NetReg tree
  4. Configure NetReg/NetMon
  5. Configure the web server
  6. Add the DNS zones of your DNS/DHCP servers (including parent zones).
  7. Add the subnets that contain your DNS/DHCP servers.
  8. Make sure to add permissions for the subnets and zones.
  9. Register your DNS and DHCP servers.
  10. Add DNS server configuration groups, zones to the config groups, and nameservers to the zones.
  11. Add the DHCP service, add permissions, and add the DHCP servers to the service.
  12. Test DNS/DHCP output
  13. Add scheduled.pl cronjob.

2.2  Requirements and Recommendations

The following additional software is required (or highly recommended) to run the NetReg/NetMon system. We assume that Perl, MySQL, the DBI modules, and Apache are installed and tested for basic functionality prior to continuing with the installation.

Perl 5.005 or later
www.perl.org
  • We recommend 5.6.1 or later. Less-than-5.6 allowed us to be a little bit sloppier with some references.
  • Has not been tested on perl 5.7 or 6.x.
Apache 1.3.x
www.apache.org
  • Currently running 1.3.20
  • Has not been tested on Apache 2.x.
MySQL 3.23.40+
www.mysql.org
  • Currently using 3.23.40 in production, 3.23.42 is built and will be used here shortly.
  • The system should be able to run on other DBMS; it depends mostly on a few features that may not be supported elsewhere. See below under "Database Notes" for more info.
DBI Perl Module & DBD::mysql
www.cpan.org
  • We use Msql-Mysql-modules-1.2216.
mod-perl 1.26
perl.apache.org
  • Not strictly required, we don't run mod-perl on our devel machines because otherwise a server restart is sometimes required/recommended for testing. But, mod-perl on our production machine greatly increases responsiveness.
Authentication module for Apache
modules.apache.org
  • We use "KWeb", a module that allows Kerberos ticket passing and thus integrates nicely with our campus infrastructure. However, NetReg should be flexible enough to allow for any Apache auth mechanism.
  • We have done some preliminary testing using SSL Client Certificates, but nothing major.
OpenSSL, mod_ssl
www.openssl.org; www.modssl.org
  • We're going to assume that you would prefer to run a system wherein you encrypt the interactions (at very least, the authentication), to prevent information lossage.
  • In particular, if you are planning on using DDNS, we HIGHLY RECOMMEND using encryption, since information lossage in this context can mean people having complete update privileges to your DNS servers.
ISC DHCP Server
www.isc.org
  • NetReg can generate the complete configuration file for your ISC DHCP server.
  • DHCP v3.0+ is recommended; certain DHCP v3-only commands and command syntax is used.
ISC BIND Server
www.isc.org
  • NetReg can generate the named.conf, zone files, and do DDNS updates of ISC Bind 8 and Bind 9 servers.
  • We recommend running DDNS on Bind 9 only.
FPing
www.fping.com
  • Used by NetMon; only needed if you are doing topology-generation
rsync
rsync.samba.org
  • Used on the backend for copying files out to DHCP, DNS servers.
  • Not needed if your NetReg server is also DNS/DHCP.

2.3  Database Installation

The NetReg database schema is located in doc/schema.sql. We have developed an initial set of NetReg data to demonstrate the various areas. This includes the database schema, so you can load both quickly. It's doc/netdb.data. Just do:

% mysql -u root -p < doc/netdb.data

[Assuming you are in the root directory of the source distribution.] You will be prompted for the MySQL root password. Once this is loaded, you should have a new database: netdb.

At this point, NetReg will have enough basic data to give you an idea how things fit together. However, it will not have enough data to grant you access via the web. You should run the netreg-install below, and it will take care of this step.

You will also need to create an initial user in your NetReg database for purpose of allowing you to login. For example, if your username is 'admin' (as Apache would authenticate it), then you should add the initial user by doing:

% mysql -u root -p netdb

Enter your MySQL root password. Then run:

insert into users (name, description) values ('admin', 'Mr. Admin'); insert into memberships (uid, gid) values (2, 1);

2.4  NetReg/NetMon Tree

We have written a script that should help in the installation of NetReg/NetMon. The script, doc/netreg-install.pl, should be run as the root user. If you get a "Command not found" message, run the script using your local path to perl explicitly: perl doc/netreg-install.pl. The script will do the following:

  • Create and populate the NetReg/NetMon tree. We use /home/netreg as the top of this tree. It will be populated with a number of directories. Throughout this document we'll use $NRHOME to refer to this directory.
  • Create passwords for accessing the database. You should make sure MySQL is running prior to running the installation script.

Important!

After running the script, your $NRHOME/stable/netdb will be a link to the netdb directory as you unpacked the distribution. Since we expect most people unpack downloaded software in a relatively temporary location, you probably want to:

  • Remove the $NRHOME/stable/netdb symbolic link
  • Copy the distribution to $NRHOME/stable/netdb.

If you decide to checkout/stay updated to the CVS tree, you can check it out to $NRHOME/stable/netdb and the links from, for example, $NRHOME/lib, will be maintained.

New!

New to version 1.1.6 is the ability for netreg-install.pl to automatically configure the two configuration files for NetReg: lib/CMU/WebInt/config.pm and lib/CMU/Netdb/config.pm. The last step in netreg-install will be a prompt to begin configuring these files. The script is fairly self-explanatory; once complete you'll have the option of having the new configuration written as config.pm.new, or be copied to config.pm itself.

netreg-install.pl now accepts the -config option. When specified, this causes netreg-install to only configure the config.pm files. Note! If you are using a $NRHOME other than /home/netreg, and you are using -config, you'll need to edit the NRHOME variable at the top of netreg-install.pl.

2.5  NetReg/NetMon Configuration

Now that the database and the NetReg tree are installed, you should set to work configuring the components for your environment. It's probably a good time, though, if you are comfortable enough with mysql, to poke around the netdb database.

Moving right along, you should visit $NRHOME/lib/CMU/Netdb/config.pm and $NRHOME/lib/CMU/WebInt/config.pm, if you haven't configured them using netreg-install.pl. Each of these modules contains extensive documentation on how things need to be adjusted. Additionally, the "Configuration" section below also documents the various geek knobs available. We are trying to remove any embedded Carnegie Mellon-specific configuration options from most of the source, and make the various Config.pm modules provide the interface for tweaking these bits.

2.6  Web Server Configuration

NetReg and NetMon aren't very useful without the web front-end, so it's a good idea to get your web server configured at this juncture. We use the Apache web server exclusively; you should be able to use another server without relative difficulty, assuming it supports execution of Perl (CGI) scripts, authentication, SSL, and can pass the authenticated user as an environment variable (or some other generic method.)

We have not tried using Apache 2.x locally; if you have success or failure we'd be interested in knowing.

2.6.1 Apache without mod_perl

The configuration without mod_perl is a little bit simpler, so we'll start without mod_perl, and then it's just a few other directives to get mod_perl involved. We're going to assume the web server on this machine is only going to be serving NetReg/NetMon. If it's not, we'll assume you can make the necessary adjustments.

The basic outline is:

  • Your DocumentRoot is going to be $NRHOME/htdocs. You need a Directory statement for this directory.
  • $NRHOME/htdocs/bin contains the actual hook to start the bulk of the web interfaces, so you'll need another Directory statement to require authentication/SSL to access the bin directory.
  • You need a hook to execute .pl files as cgi scripts. This is done as:
    AddHandler cgi-script .pl
  • index.pl needs to be added as a valid directory index file. This is done as:
    DirectoryIndex index.pl index.html (you should already have a DirectoryIndex statement)

So the configuration bits we've discussed (with /home/netreg assumed as your $NRHOME):

DocumentRoot /home/netreg/htdocs
...
<Directory "/home/netreg/htdocs">
  Options FollowSymLinks ExecCGI

  AllowOverride none
  Order allow,deny
  Allow from all
</Directory>

<Directory "/home/netreg/htdocs/bin">
  Options FollowSymLinks ExecCGI

  SSLRequireSSL

  AuthType Basic
  AuthName NetReg/NetMon
   [[ other auth options, like AuthUserFile, require, etc. ]]
  AllowOverride none
  Order allow,deny
  Allow from all
</Directory>
...
DirectoryIndex index.pl index.html
...
AddHandler cgi-script .pl

Your users should be directed to connect to http://machine.name.example.org (substituting your machine name, clearly). The index.pl script in $NRHOME/htdocs will provide some basic instructions to users (and you are encouraged to modify this file appropriately). This, as well as the nc.pl script in $NRHOME/htdocs, also clear users' cookies for your machine. At CMU, our authentication mechanism uses short-life cookies. Clearing the cookies ensures fresh credentials are required when accessing NetReg. nc.pl is the script pointed to by the "Signoff" link in NetReg.

2.6.2 Apache with mod_perl

Adding mod_perl into the equation makes your Apache setup slightly more complicated, but can yield significant benefits in response time. We do not use a DBMS handle cache (due to us wanting to just completely avoid any deadlock issues due to un-released locks, etc.) However, the NetReg modules take a short but appreciable amount of time to load. mod_perl saves both loading time and memory, since we set things up to load all our modules pre-fork, meaning we having one 10MB copy of NetReg in memory rather than 12.

  • Assuming mod_perl is installed with Apache, you should already have:
    LoadModule perl_module libexec/libperl.so
    AddModule mod_perl.c
  • Add an appropriate PerlRequire to pre-load various libraries. Substitute $NRHOME appropriately:
    PerlRequire $NRHOME/lib/startup.pl
  • Add the Perl InitHandler:
    PerlInitHandler Apache::StatINC
  • Setup the perl script handler (from the basic config, remove the AddHandler cgi-script .pl):
    <Files ~ "\.pl">
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options +ExecCGI
    </Files>

2.7  Stop... Beverage Break

You need to edit the $NRHOME/htdocs/index.pl file to make it applicable to your environment. Basically, the first line needs to be changed to point to your Perl interpreter, and you probably want to edit the footer to indicate your name.

Finally, edit $NRHOME/htdocs/bin/netreg.pl and $NRHOME/htdocs/bin/nc.pl to point to your Perl interpreter (first line).

At this point, you should now be able to connect to NetReg, login, and see the initial machine list. Under "Registered machines for", select "NetReg Administrators". After refreshing, you should see a small list of machines. That working, we'll proceed. It's probably a good idea at this point to read parts of "NetReg Design", including "Subnets", "DNS Zones", "DHCP Options", and "Machines".

That being said, it's time for a small break in the installation.

2.8  Add DNS Zones

Now we'll get to work configuring NetReg. The goal will be to get NetReg to the point that your DNS and DHCP is generated. First, you need to add some DNS zones. At this point you'll need to add the zones which contain your DHCP and DNS servers. We'll use EXAMPLE2.ORG for demonstrating this.

If your DNS servers are NS-A.EXAMPLE2.ORG and NS-B.EXAMPLE2.ORG, and DHCP is DHCP.EXAMPLE2.ORG, then you just need to add EXAMPLE2.ORG. Since ORG already exists, you can easily do this (NetReg requires all zones from the root zone to every leaf zone used be registered in the Zones area). If your domain was EXAMPLE.TV, though, you'll need to add the TV zone first. (See the "Zones" section below for more details.)

In this case, you just visit the "Zones" area in NetReg, click "Add Zone", enter EXAMPLE2.ORG as the zone name and a type of 'fw-toplevel'. You also need to define the SOA Email, SOA Host, and other SOA parameters. Your SOA email could be "root.example2.org", for example. Fill in a valid hostname for SOA Host, but it actually doesn't matter. The other fields have recommended values. Leave the "DDNS Auth" field blank.

Once added, you need to add permissions for the zone. Visit the "View/Update Protections" link on the zone information page. From there, you could add 'netreg:admins' with level 9 ADD access, and this would restrict any new registrations in the zone to only members of the netreg:admins group. Alternatively, adding 'system:anyuser' with level 1 ADD would grant anyone the ability to add machines to the zone.

The situation is slightly more complicated if your nameservers are in a child zone to some toplevel zone you control. Everything can be done via the interface, but a picture is likely worth 1000 words here, so here's a diagram of our DNS layout (coming soon):

  • toplevel: Serving CMU.EDU, 'toplevel' is our unpublished master server, 'ns1.net', 'papaya.srv.cs', and 'cucumber.srv.cs', are published as the zone nameservers (all pulling from the master).
  • thirdlevel: Serving ANDREW.CMU.EDU (and other third level zones), 'thirdlevel' is our unpublished master server, 'res-ns', 'weh-ns', and 'campus-ns' are the designated secondaries.
  • "DotCom": We separate "commercial" endeavours of the university into distinct IP and namespace. The 'ns1.cmu.net' nameserver handles these zones. It is a published master, with 'ns2.cmu.net' as the published secondary.

You are also going to need reverse zones for the IP ranges that your DNS/DHCP servers are in. If the IP of NS-A.EXAMPLE2.ORG is 192.168.0.4, you need the 0.168.192.IN-ADDR.ARPA zone, as well as the 168.192.IN-ADDR.ARPA and 192.IN-ADDR.ARPA zones. The latter two can be added as type 'rv-permissible', and you don't need to fill in ANY of the SOA values for 'permissible' zones. The former will need to be added 'rv-toplevel' with appropriate values.

Note!

Please see section 4.4.2 of this manual for instructions on adding new top level domains (such as .US, .INFO, etc.) to the system.

2.9  Add Subnets

In the Subnet area of NetReg, you must define all subnets that machines will be registered into. For most registrations, this makes absolute sense. You definitely want subnet definitions for your networks, so that you can hand out DHCP options applicable to the subnet. However, you will also need to add a subnet definition for external networks that you may need to register machines into. For example, if someone wants WWW.FOO.EXAMPLE.ORG (and you own example.org) to be a CNAME to an external machine, such as WWW.BAR.ORG, then you will need to "register" www.bar.org (and add a zone for it). Technically you could register the machine with mode 'reserved', and not specify an IP address. However, we prefer to register the machine correctly and make the "ownership" of the additional record the user that requested the name.

In registering the subnet, specify the subnet name and abbreviation, base address and network mask, and indicate if you want to permit any dynamics on the subnet (allow unregistered machines to get DHCP leases), restrict the dynamics (allow only registered machines to get a dynamic address), or flat-out deny all dynamic IP allocation on the subnet.

The subnet name can be a free-form string (with spaces, etc.) that will be presented to users as the name of the subnet. The abbreviation is a short, 8 character max, no spaces abbreviation. This is used in some output formats -- basically, it provides an easily-parseable and unique identification for the subnet for use in scripts, etc.

The base address and network mask should be specified in dotted-quad format (127.0.0.1 and 255.255.255.0, for example). We would like to include some CIDR notation in the interface at some point, but really you just need to be able to convert between them quickly.

For the time being, you can ignore the purge fields of the NetReg entry. The default values will be supplied, making the subnet un-purgeable. The purge process if done from NetMon, anyway, so unless you configure that portion, it won't mean anything.

After adding a new subnet, the system will dynamically calculate the valid "range of addresses" that will be usable on this subnet, given your base address/network mask. If the range presented differs from what you believe is the valid range, double-check your base and mask. There have been a few cases that we have specified base + mask on an invalid boundary -- ie, you can't start a /26 block on a base address ending in '96'.

If you feel like restricting the number of registrations for a particular user on a given subnet, you can fill in values for the Static or Dynamic quota. Most users are allowed to only add machines with mode 'static' or 'dynamic'. There are other modes, but these are restricted to administrators, and we assume they don't need any help with quotas (in fact, Level 9 ADD on a particular subnet for any user or group is sufficient for bypassing all quota enforcement.) A quota of '0' means 'unlimited'.

Each subnet has a few flags that can be set. Specify 'no_dhcp' if you do NOT want this subnet to appear in your DHCP configuration. Any subnet that you don't control would be a good candidate for this option. The 'no_static' flag disallows any static IP address registration for users without L9 ADD permissions. Make sure your 'Dynamics' setting is 'permit' or 'restrict' if you want normal users to register on this subnet. The 'delegated' flag is purely informational; the Subnet Map report uses this to change the color of these subnets so that you get a nice picture of your IP space allocation.

2.9.1 Subnet Presence (Buildings)

After adding a new subnet (or modifying an existing one), you have a few other administrative tasks that can be done with the subnet. First, if you have any buildings defined, you can add this subnet to a particular building. It can appear in more than one building, but will appear on the subnet list after a user selects "Register New Machine" and selects the building. The "Register" page also gives users the option of selecting the subnet directly, or selecting a "Network" (see below for more information).

2.9.2 Allowed Domains

Within a given subnet, we only allow machine registrations (including by administrators) on domains that are defined on the Subnet Information page. This provides some consistency in registrations. Note that users are presented with a drop-down box of valid domains when registering their machine. They will only see domains for which they have permission to add machines into. Thus, most users at CMU will see 2 or 3 (at most) domains for their registrations, while we register network gear in a different domain. This domain is also a valid domain for the subnet.

2.9.3 DHCP Options

The subnet information page is also the location for adding subnet-specific DHCP options. You can select 'Set Standard Options' under the DHCP Options section to automatically add the most common options for a subnet (such as router, broadcast address, etc.)

2.9.4 Protections

After adding a subnet, you will need to specify some protections to allow registrations in this subnet. The method is similar to specifying the protections on zones: namely, 'netreg:admins' with Level 9 ADD would be the default to allow administrators registration on the subnet. 'system:anyuser' at Level 1 ADD would grant registration privileges to any user.

2.10  Register DNS/DHCP Servers

Before proceeding, you should register all of your DNS and DHCP servers. This will require the zones to be present (with proper permissions) and the subnets to exist. You can register them as type 'reserved' if you do not know/care about the hardware address, or 'static' if you have this information.

2.11  DNS Configuration

Now that your nameservers are completely registered, it's time to create DNS configuration groups. For information on doing this, see the DNS section later in this manual.

2.12  DHCP Configuration

We use the new "Service" area to specify some parameters for your DHCP configuration. The sample data includes a "DHCP Server Pool" specification. In the service area, go ahead and add a service of type "DHCP Server Pool". This just requires specifying the name you want -- we use 'dhcp.net.cmu.edu'. After adding a DHCP service, you want to add your DHCP servers into the service. Once this is complete, you should add the attributes for the servers and the group.

2.12.1 DHCP Service Attributes

The attributes we have defined for DHCP servers thus far includes:

  • Dynamic Master Port: Specifies the port to use on your master server in a failover configuration. The default is 519, and the scope is the service group.
  • Dynamic Secondary Port: Specifies the port ot use on your secondary server in a failover configuration. The default is 520, and the scope is the service group.
  • File Type: This per-machine attribute specifies if you want a 'static' file (which contains only fixed-address and subnet declarations -- no pools), or a 'dynamic' file (which contains all the pools, etc.)
  • Dynamic Failover: This can be set to 'master', 'secondary', or 'neither' on a per-machine basis. This defines the servers involved in the default failover configuration.

There are a few restrictions that you should keep in mind:

  • You can only have one dynamic server, or two dynamic servers configured as failover peers, answering your DHCP requests on a given wire. You could have multiple DHCP servers, although NetReg isn't quite designed for that (it's something we'd like to see in the future).
  • Only one server can be a failover master, and one a failover secondary.

2.13  Test DNS/DHCP Output

On your NetReg server, you can become the netreg user (or whatever user you specified in the installation and are running your scheduled scripts as) to test the DNS/DHCP output. First, make the following directories: /tmp/zones, /tmp/dhcp. Go into your $NRHOME/bin directory, and run ./dhcp.pl -debug, ./dns.pl -debug, and ./dns-config.pl -debug. This should create the requisite files in /tmp that you can then verify for accuracy. Namely, you should have a named.conf.FOO for each nameserver, a dhcpd.conf.FOO for each DHCP server, and a zone file for each zone configuration (name: EXAMPLE.ORG.zone).

2.14  Activate Scheduler

At this time, you also need to think about creating a cron job for running scheduled NetReg operations. In reality, you probably want to hold off doing this until you update the proto data. But it logically fits here, so:

We have a cronjob that runs the $NRHOME/bin/scheduled.pl script every minute. While there aren't always things that need to happen every minute, the scheduled keeps track of all the different periodic operations and launches them as necessary. So it's more or less a mini-crond/mini-atd.

You want to add this cron job as user netreg, or another user of your choice. We do not recommend you run the job as: root, whatever user your DBMS (ie MySQL) runs as, or the user that your web server runs as. Implicitly we're also recommending that your DBMS and web server run as different non-root users. The theory here is that a compromise/exploit of one of the individual components does not mean you have an immediate compromise of other components.

2.15  Done...

The NetReg installation is now done. You probably want to read the rest the NetReg Design section a few times. If you are interested in granting users access to register machines, you will need to come up with a method of loading the allowed users (see "passwd-load.pl" in the "Support Utilities" section). NetReg requires some tedious initial configuration (and we're trying to reduce the amount of that..), but once running it is fairly self-sufficient.