![]() |
![]() |
![]() |
![]() 3 |
|||||||||||||||||||||||
|
||||||||||||||||||||||||||
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: |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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); |
||||||||||||||||||||||||||
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: |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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: |
|||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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: |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
So the configuration bits we've discussed (with /home/netreg assumed as your $NRHOME): |
||||||||||||||||||||||||||
DocumentRoot /home/netreg/htdocs |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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): |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
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. |
|||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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). |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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.) |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
The attributes we have defined for DHCP servers thus far includes: |
||||||||||||||||||||||||||
|
||||||||||||||||||||||||||
There are a few restrictions that you should keep in mind:
|
||||||||||||||||||||||||||
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). |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||
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. |
||||||||||||||||||||||||||