-
Notifications
You must be signed in to change notification settings - Fork 2
The database schema is available in the distribution (see doc/schema.sql).
NetReg can be broken into three logical components:
-
Database Schema: NetReg relies on the backend database for every operation, and the schema supports a flexible protections mechanism. We tried to keep the schema as simple as possible, to allow for rapid understanding and modification as needed.
-
NetDB: The CMU::Netdb modules provide an API into the database. They implement the protections checking mechanisms and provide intricate verification and augmentation to data being added or updated.
-
WebInt: The CMU::WebInt modules form the web interface to the database. The web interface uses the CMU::Netdb modules for most database accesses.
This design provides logical delineation points. The Netdb modules, for example, know absolutely nothing about HTML or web pages. At the same time, the WebInt module foists responsibility to the Netdb components for most data verification.
Note that NetReg was designed on top of a MySQL database. MySQL does not support foreign keys, so NetDB functions provide most of the foreign key validation. For this reason, then, you should be very, very careful about updating records in the database directly. For example, if you were to change the IP address of a machine record, the subnet reference in the record may need to be updated.
NetReg is designed with a fairly standard concept of users and groups. Every user that will use NetReg must have an entry in the users table. While we don't use realms, it would be fairly straightforward to support them. UserIDs are authenticated by standard authentication/authorization modules in Apache, and Apache passes the UserID via the REMOTE_USER environment variable. The function CMU::WebInt::helper::getUserInfo is called to retrieve and parse the UserID. In theory, no other components should use REMOTE_USER directly (and this is true of NetReg in the current state).
There are a few special users and groups. Our sample database comes with these users and groups pre-configured to work correctly, but you should take note. First, the netreg user is special. You must grant 'netreg' full, level 9 read/write access to every record of every table. (See Section 6.1.3. for more information.) In several places, we assume 'netreg' has this access to force certain queries or operations to succeed regardless of protections entries. In practice, all of these instances are safe: the system has already determined the user is authorized to perform the operations, and we want to belay any further checking.
Because of the special nature of the 'netreg' user, this user is not actually allowed to use the web interface to the database. This is enforced in CMU::WebInt::helper::db_connect. We recommend not removing this.
The system:anyuser group is not actually a group inasmuch as it does not appear in the groups table. However, it is interpreted by Netdb to represent the group of all users.
The netreg:admins group is distributed in our sample database, however you could easily rename it. In the sample data, members of this group form the elitist group of NetReg users: they have universal access to all sections of the database.
In general, groups take the form of a prefix, a colon, and a name. We use prefixes to logically determine the purpose of a group, and make it consistent with other groups with the same prefix. The current prefixes in use are:
-
netreg: These groups indicate elevated database access. We use a netreg:fullread group, for example, to grant Help Desk users access to view, but not change, all machine registrations.
-
dept: Every machine in NetReg must have one (and only one) department associated with it. Members of the Department group then have the ability to view and update the registrations associated with the department.
-
local: We are using the 'local' prefix to define groups of users with a similar affiliation. In practice, we will have a 'dept:foo' group to define the department administrators for the 'foo' department, and a 'local:foo' group to define the actual users associated with that department. The 'local' groups will be used to restrict registration privileges on certain domains or subnets. The 'local' groups will not have rights on the actual machine registrations, however. We chose the 'local' prefix because the source of data about users in certain groups will come from a simple filesystem based design.
-
ldap: The 'ldap' prefix will be used exactly the same as the 'local' prefix, except the source of data will be our internal LDAP directory.
NetReg boasts a flexible and extendable protections system. It can be frustra ting at times, because you will sometimes receive error messages of the sort "X doesn't exist", when in fact X exists, but you don't have permission to use X (even if you are t he administrator). The protections system was designed to give maximum flexibility in allowing users to add and update machines, while giving administrators finely gr ained controls over what domains, subnets, and so forth users are allowed to register machines on.
All protections are controlled from the 'protections' table in NetReg. We will r efer to each line in this table as one protections entry. Each entry contains:
- Table: The NetReg table this record applies to.
- Table ID: The ID in the specified table that this record applies to.
- Identity: The User or Group this entry gives permissions to.
- Level: The level of access granted the user or group on the Table/Table ID .
- Rights: The rights given the user or group on the Table/Table ID.
The Table and Table ID fields specify the table name and ID wi thin that table that this entry refers to. If the Table ID field is '0', the entry ap plies to all records of that table.
The Identity field specifies the user or group that will be granted rig hts to the specified table and table ID. If the Identity field is positive, it refers t o a User ID (users.id). If the field is negative, it refers to the (positive) Group ID (groups.id). If the field is '0', it is a special case and refers to all users.
The Level field specifies the level of access given to the user(s) on t he specifies table. Most average user permissions are granted at level 1. Administr ative privileges are generally granted at level 9. Department administrators (those in a group with prefix 'dept:') are given additional privileges at level 5. The lev el of privileges works hand-in-hand with the rights (see below). If a user has leve l 1 WRITE access to a machine, for example, they will be allowed to update basic inf ormation, like the MAC Address and Mode of the machine. However, users with level 9 WRITE access will be allowed to change other information, such as the Abuse/Suspended status of the machine, and so forth.
The Rights field specifies the rights granted to the specified users, a t the specified level, to the specified table/table ID. The valid rights are READ, WRITE, and ADD. The READ and WRITE permissions are fairly self-explanatory: if you have READ access to an individual record, or to the entire table, you will be able to read those records at the specified access level. The WRITE permission operates the s ame way.
The ADD permission has different meanings depending upon the table ID. For a table ID of '0' (ie "entire table"), the ADD permission grants you the ability t o add new records to this table. However, with a non-zero table ID, the "ADD" perm ission grants you the ability to use the specified record as a reference in another tab le. For example, the ADD permission on record 24 of the "subnets" table, for identit y 0 (ie all users) enables all users to add machines to subnet #24.
Note that the permissions system is entirely up to the DB interface components (the CMU::Netdb and CMU::WebInt modules) to enforce. In some cases, protections are massaged a bit. For example, the ability to add DHCP options and DNS resources to a machine doesn't require the ADD permission on the machine (only WRITE). We would like to document all of these individual cases, but do not have such documentation now. Doc patches are welcome. :)
The system is designed, however, to make protections implementation fairly straightforward. The list, get, add, modify, and delete functions in CMU::Netdb::primitives are used by most Netdb API functions and implement protections checking at that level.
Note that by design, the DBMS is not performing individual user authorization checking. The actual "user" seen by the DBMS is a single user/password configured. Basically, the implication is: make sure the machine hosting the web server is secure. You should see our section on NetReg Security for more information.
There are six different types of zones represented in NetReg. All have the prefix designator 'fw-' or 'rv-'. The former indicates the zone is a forward zone (ie EXAMPLE.ORG, etc) while the latter indicates a reverse zone (ie 0.128.10.IN-ADDR.ARPA, the zone for reverse lookups of 10.128.0.x IP addresses.)
Within each prefix, there are three suffixes: 'toplevel', 'delegated', or 'permissible'. While NetReg does not strictly enforce where you can have these different suffixes, you should follow these rules for setting up the zones properly:
- Any zone for which you want a zonefile to be generated should be "toplevel".
- Any zone that you do not want a zonefile (ie, the zone is either a sub-domain of a "toplevel" zone, or you otherwise don't control), should be "permissible".
- If you delegate authority for a zone and you control the parent zone, then the zone should be "delegated".
A quick example should lend some clarity. We start at the top of the DNS system.
- Under the root zone (".") you have Top Level Domains (TLDs). These include ORG, NET, EDU, COM, MIL, GOV, a host of country codes, and new TLDs such as AERO, BIZ, MUSEUM, etc. These should all be "fw-permissible", because you don't control them (or if you do, we'd be pleasantly surprised!)
- Under the TLDs are the 2LDs, such as EXAMPLE.ORG, CMU.EDU, etc. Assuming the zone is properly delegated to you, these zones should be "fw-toplevel".
- Under your 2LD, you may have different 3LDs. For example, we have "ANDREW.CMU.EDU" and "CS.CMU.EDU". We control ANDREW, but delegate CS to the Computer Science Department. But, we don't want the ANDREW records in the CMU.EDU zone, to limit the number of changes to CMU.EDU. Thus ANDREW is fw-toplevel, and CS is fw-delegated.
- Under ANDREW.CMU.EDU, we also have the CYERT.ANDREW.CMU.EDU zone. However, while we want to be able to register machines in CYERT.ANDREW.CMU.EDU, we don't care to have a separate zonefile -- the CYERT machines can just appear in the ANDREW zone. Thus, CYERT is "fw-permissible".
Adding a second-level domain (ie EXAMPLE.ORG) requires the parent zone (ie ORG) to exist. The default data supplied contains the top level domains (TLDs): ORG, NET, COM, EDU. If you need to add 2LDs in other TLDs, you will need to manually add the TLD as follows. Connect to your DBMS (ie "mysql -u root -p netdb", and enter your root password). Then enter:
insert into dns_zone (name, type, parent) VALUES ('US', 'fw-permissible', 0);
Substitute the TLD you wish to add for "US" in the previous example. Similarly, you will need to manually add any missing zones
If you are running ISC BIND 8 or earlier, we recommend that you do not setup a name system that involves delegation from one zone to another, where both zones are served by the same nameserver.
Prior to BIND 9, there were some issues involving leakage of zone information between parent and child zones. This could cause incorrect responses, and thus our recommendation. We have a small group of BIND 9 servers for DDNS, but mostly run BIND 8. Thus, we have a group of servers for CMU.EDU and other 2LDs, and another group for ANDREW.CMU.EDU and other 3LDs.
DNS Configuration is controlled through service groups: specifically, the DNS View Definition and DNS Server Group groups.
The DNS View Definition groups are used to specify the parameters of a specific view. Note that the name of the service group is not the name of the view as it will be written in DNS configurations. The attributes of the service are:
-
Server Version: This attribute specifies the version of the software that this view definition applies to. You can have multiple view groups attached as members to a DNS Server Group (see below) with the same view name. The options in the View Group will only be included on servers with a version matching this parameter.
-
DNS Paramater: This attribute allows you to specify free-form text in the view definition.
The DNS Server Group groups are used to specify common settings for a group of zones. The members of the group are:
Zones The zones that are part of this group are added as members. The attributes of the zone membership are:
- Zone In View: Specify a particular view that the zone should be included in. If no views are specified, the zone is included in all views.
- Zone Parameter: You can specify a free-form named configuration parameter to be added in the zone {} block. There is no correctness checking done to these parameters (although the backend servers can validate it prior to reloading the nameserver with named-checkconf.
Machines The machines that are members of service groups are the DNS servers for the zones in the group. The attributes of these service members are:
- Server Version:
- Server Type: This parameter specifies whether the server is a master or a slave for the zones in this
Views Other service groups (specifically the DNS View Groups) can be members of this group as views. The view name is specified by the Service View Name parameter. "default" refers to the global namespace (see below). The Service View Order parameter allows you to control the order in which the views are written to the configuration. This is important, because clients will be presented with the data in the first view that matches (not an aggregation of views they can see, or other metric). The order field is specified as an integer, where '1' is the lowest or "first" view. You could specify the order of two views as '10' and '50', and the view of order '10' will be printed in the configuration first. The behavior of the DNS configuration script with equal orders (ie 10 and 10) is not guaranteed, and you should avoid this case.
Note that you can have a DNS server referenced in multiple server groups -- it might be the master for a set of zones, the slave for others (with specific view configurations), and the slave for yet another set, with other views. The configuration output script will deal intelligently with this situation. In the case of a server referenced in multiple server groups, common view names are combined -- that is, if you have an 'internal' view in one server group, and 'internal' in another, they are treated as being identical.
The special view name default refers to the global option space. For example, our sample data includes special views "view.default.bind8" and "view.default.bind9". When added as members of the service group with name default, the options specified in these views (the "view.default.bind8" view), the parameters are included in the global space.
A core component of NetReg is the definition and configuration of subnets. Specifically, the subnet table stores such information as the subnet's base address, network mask, name, abbreviation, and several other related pieces of information.
While the system does not prevent configuring two overlapping subnets (due to issues involved with moving subnets), you should never configure overlapping subnets.
Users will not be allowed to register any machines on a particular subnet (indeed, they won't even see the subnet) unless they are given ADD permission (level 1) on the subnet. Even system administrators must be given ADD access. Once they begin registration on a subnet, they will only be allowed to register machines in the DNS zones you specify on the subnet screen. They must also have ADD access on the DNS zone. (One exception: If a machine is registered in zone FOO.ORG, and FOO.ORG does not exist as a valid domain on the subnet, users will still be allowed to update other information, such as the MAC address, of this machine, while maintaining the FOO.ORG name. Indeed, WebInt does not actually give them the list of valid zones in this case.
At the bottom of the subnet information page in WebInt is a list of DHCP option for the subnet. Some common DHCP options you will need:
- option routers: Specifies the IP address of the default gateway of this subnet.
- option broadcast-address: Specifies the broadcast address of the subnet.
- option subnet-mask: Specifies the subnet mask handed out to DHCP clients.
In reality, the only piece of information that cannot be gleaned from the subnet configuration is the router address, and even that tends to be fairly standardized. One notion has been to add a WebInt function that automatically adds these common options.
The "networks" concept is redundant, actually. With hundreds of subnets here, including a few that were not entirely contained in a single building (our campus-wide Wireless infrastructure, and DSL connections, for example), the concept of "special" subnets was born. When registering a machine, users begin by selecting either a building, a subnet, or a network. If a network is selected, the system does the appropriate lookup to determine the subnet, and proceeds with registration on that subnet. Every network represents one, and only one, subnet. (Although a subnet could be aliased to multiple network names.)
Shared subnet declarations were initially used as we transitioned from a mostly bridged network to our currently mostly subnetted network. As the configuration was somewhat fixed by the DHCP configuration generation script, this area of NetReg is not completely functional at this time.
While NetReg is certainly useful as a network management tool, much of the design is to facilitate end-user registration of machines (with proper restrictions). You must also register machines that will be used as DNS servers.
Registration of machines is accomplished from the first page of NetReg (by selecting "Register New Machine"). The next screen requests you select the Network, Building, or Subnet to register this machine on. Each machine is registered on one and only one subnet. Users may only register new machines on subnets they have ADD access to.
After selecting the subnet, normal users can select the hostname (and the domain name from a restricted list, based on the users ADD access to the zones and the zone attached to the subnet, via the subnet information page.) Normal users must also select the mode ("static" or "dynamic"), the MAC Address of the machine, and the department to which the machine is affiliated. Once the information is selected, the machine is registered. Machine registration is very complicated; if you are planning on modifying this section of code in any way, we recommend consulting with us first.
Administrative users have additional options (administrative defined as having level 9 ADD access to the entire machine table (tid == 0)). They can specify additional modes: "reserved", "base", "broadcast", or "pool". The modes are defined as:
- static: The basic mode for registering a machine. The IP address is assigned by NetReg at registration time (unless specified by an admin). All static registrations must have a hostname, MAC Address, and IP address.
- dynamic: The basic mode for machines on subnets with IP address pools and obtaining a dynamic IP address (as assigned by the DHCP server). All registrations must have a hostname (note: this is a recent change, not enforced yet) and MAC address. The IP Address will always be '0' (although updating as an Administrator may require you to clear the IP address field first.)
- reserved: The 'reserved' mode is a mode for cases when the administrator wants a partial registration for whatever reason. There is no restriction on IP, MAC Address, or Hostname existence. However, as with all registrations, under no circumstances can you have duplicate IP addresses. (See ANAMEs under DNS Resources if you think you need duplicates.) The IP, MAC, and Hostname fields are treated like other registrations for purposes of duplicate suppression (thus, no duplicate IPs, no duplicate hostnames, and no duplicate MAC address on the same subnet.)
- base: An registration for the base address of a subnet should be set to the "base" mode. MAC Address is not required; IP and Hostname are. These will be handled slightly differently in DHCP and DNS generation.
- broadcast: Similar to 'base', this mode is for addresses that are the broadcast addresses for a subnet.
- pool: Any address defined as a 'pool' address is added to the DHCP configuration file as a valid pool address for the subnet. If the subnet mode is 'restrict', only registered machines with mode 'dynamic' will be allowed to obtain one of these pool address. If the subnet mode is 'permit', ANY machine (registered or not) will be allowed to obtain one of these pool addresses. Pool addresses must have a hostname (for legacy purposes). If you need/want to add a number of pool addresses, see the "Support Utilities" section below.
Administrators can also set the DNS TTL value for the hostname and IP address (separately), as well as update a comment field visible only to them, and/or change the flags. The current machine flags are:
- abuse: This is a flag to indicate the machine has been involved in an abuse incident. When marked "abuse", the owner of the machine cannot update or delete the registration. They cannot see the flag, however they will receive a general "permission denied" message when trying to perform these operations.
- suspend: When set, this flag causes the machine to stop propogating to the DHCP and DNS servers. Generally this is used in conjunction with "abuse", but we could think of situations where you would want control over them individually.
- stolen: When set, any attempt to register a machine with the same MAC Address will cause an alert message to be sent to the administrators (the registration will fail with a "duplicate registration" message).
The DNS options area of the machine information page allows users and administrators to add additional DNS records related to the machine (similar to zone options). To add a particular resource you must have ADD access on the specific DNS record type. There are additional restrictions, as described here. Each record can have a name, rname, TTL, 2 metrics, a port, and/or two text fields. Unless otherwise indicated, you can have multiple DNS records of the same type for the same resource.
- CNAME: A CNAME provides a method for binding a hostname to another host at the time of the DNS request. The name field is the alias hostname (ie WWW.EXAMPLE.ORG) while the rname is the real name of the machine (and CNAMEs will appear on the information page of the rname machine.) Note that a single RR name cannot contain any type other than a CNAME, if one exists. Thus, if you add a CNAME to a zone, the actual record generated will be an "A" record (the standard hostname-to-IP-address record.) Thus CNAMEs are valid on machine, zone, and service records.
- MX: The mail exchanger record is valid for machines, zones, and service records. The name field contains the record to apply the MX to (ie EXAMPLE.ORG), while the 'rname' field indicates the mail exchanger for this record, and rmetric0 supplies the metric weighting (metrics are entirely dependent upon other metrics for the RR to have any meaning.) MX records appear on the information page related to the name field.
- NS: Nameserver records create a delegation point for zones. They are ONLY applicable to zones, and will appear on the information page of the child zone (though the parent zone will identify the NS records which need to exist there). The name field is the zone, while rname indicates the nameserver that is authoritative for the zone.
- TXT: Text records allow for free-form text to be added to a zone. name indicates the machine, zone, or service owning the text record, while text0 stores the free-form text.
- HINFO: The host-info record is similar in nature to the TXT record.
- ANAME: The ANAME record is a creation of our own, and is used to deal with situations that you want multiple hostnames to refer to the same IP address. For example, if you have a registered machine FOO.EXAMPLE.ORG and want BAR.EXAMPLE.ORG to have the same IP address as FOO, then you would add an ANAME to FOO. The name field would be BAR.EXAMPLE.ORG, while the rname field would be FOO.EXAMPLE.ORG. When the zonefile is being written, ANAME records will be looked up by the name field, and an "A" record will be added from the name field to the IP address of the machine in the rname field. You can also use ANAMEs to have simple round-robin load balancing. For example, you could have FOO.EXAMPLE.ORG and BAR.EXAMPLE.ORG, and add ANAMEs to both to WWW.EXAMPLE.ORG. Then WWW.EXAMPLE.ORG would be generated with two "A" records (thus 2 IP addresses). You can even have an ANAME to the name of a pre-existing registration. In this case, you could have WWW.EXAMPLE.ORG registered, and add a registration of BAR.EXAMPLE.ORG with an ANAME to WWW.EXAMPLE.ORG.
- SRV: We designed the system to support SRV records, but are not using any currently, so no documentation is available.
See the section below "Machine DHCP Options" for more information.
DHCP Options can apply to three scopes: "global", "machine", or "subnet". Each is described here.
Some DHCP Options must be enclosed in quotation marks. Otherwise you will end up with a broken or non-functional DHCP configuration file. We would like to make the handling of these options better in the long run (not require quotations in the database, but add them at generation time.)
Global DHCP Options are added to the global section of the DHCP configuration file. We have tried to reduce the number of options added directly via the configuration file generation script, so that everything is controlled via the NetReg database/interface.
The standard database data provided contains a number of example global DHCP options. You can view and modify the options by select the "DHCP" administrative link. The options included are:
- option domain-name: This is the default domain-name passed to clients, in the absence of another. We strongly recommend this domain NOT be a zone that is DDNS-updatable. (See below.) Note that you must include quotations around the domain name.
- option ntp-servers: This option provides clients with your Network Time Protocol servers, if you have any. It also demonstrates that you can specify multiple servers separated by commas (as the DHCP configuration will accept.)
- option netbios-name-servers: This option is used by Windows clients to point at a valid WINS server. See the ISC DHCP man pages for more information.
- option netbios-node-type: A setting of '2' for the node type is the standard we use to point clients at our WINS servers.
- option local-printer-cfg: Recent versions of the ISC DHCP server have changed the method of specifying vendor-specific options. Long term we would like to get DHCP options cleaned up a bit (enabling vendor classes, etc. from NetReg). In the short term, in order to support printer configurations we use the 'option local-printer-cfg', which maps to option 144. The mapping is done here in the global scope by adding a value "code 144 = text" to the name.
- next-server: The Next Server is used to specify the TFTP host for client images.
- ddns-update-style: You should set the update style to "interim"; the DHCP configuration contains more details but this is probably the style you want to use.
The reason that we recommend the default domain-name not be dynamically updatable is due to our policy of not accepting client-supplied hostname information. Windows supplies the "client requested hostname" as that name which is given to the computer. In several cases, users have selected names such as "Bob's Machine", and Windows supplies this hostname, spaces and punctuation included. Thus, we recommend the default domain-name be a zone that is not allowed to be dynamically updatable. If a client, through the proper registration mechanisms, is to be assigned a particular hostname, then the domain-name will be specified for the client explicitly in the DHCP configuration (See the section below under DHCP zone file generation.)
Subnets form a large basis of the DHCP configuration, and logically have options specific to all machines within them. See the section above ("Subnets and Networks") for the typical DHCP options needed. Additional DHCP options for a subnet can be added on the subnet information page, and are passed into the DHCP configuration file verbatim.
Options given for a machine will be added to the DHCP configuration and apply to the machine only. Some typical options include specifying a filename for booting; this option is commonly used by printers and network devices for startup configurations/system images. Note that you also probably want to specify the next-server option globally or for the machine, unless the DHCP server is running an appropriate server for the files. (Though this is outside the scope of this document, we use a next-server and filename options successfully here.)
QuickReg is a new feature as of the 1.1.4 release of the package. This feature enables virtually effortless registration. The benefits in a University environment (such as residential network) are substantial.
The design of the QuickReg system is the following: For each "real" IP subnet, the administrator defines a secondary "registration" subnet, as well as a new subnet share declaration (in NetReg). The subnet share is attached to both the real and registration subnet. The registration subnet is populated with a number of dynamic addresses (using the Bulk IP Registration feature and a mode of 'pool'). The dynamic restriction on the subnet is 'permit', meaning that anyone can get an IP lease on the registration subnet.
The registration subnet might contain DNS settings that point to a nameserver which responds with only a single IP address for any query (thus directing all traffic at the NetReg server; even traffic for www.yahoo.com. The registration subnet is most likely also ACLed to prevent off-campus communication of any form.
When an unregistered machine comes up on the wire, they will receive a lease in the registration subnet and be directed to NetReg. Upon entering NetReg, the system detects they are coming in from a registration subnet. It then queries the DHCP server (using OMAPI) to find the MAC address of the machine.
Once the MAC address and real subnet are determined, the user is presented with a short information screen and taken to a registration page. The user may optionally select a hostname, but the domain name, MAC address, and subnet information are pre-selected. Clicking "Continue" will cause a registration to be entered.
After registration is complete, the system takes some time to propogate the new information to DHCP and DNS. Clients are instructed to restart after 30 minutes. Assuming all is correct, the DHCP servers now return a lease in the real subnet.
An excerpt from the mailing list, where Kevin at CMU describes their QuickReg setup (in this case, a test setup):
Real subnet: 128.2.225.0/24, appropriate ADD access for netreg:admins, default registration mode: static, dynamic allow: restrict. There are 50 pool addresses in this subnet, but they aren't needed with static registrations. The DHCP options are just the standard ones you get if you use the "standard options" link on the subnet page. There was an appropriate domain allowed on the subnet.
Fake subnet: 192.168.12.0/24, protections had ADD for netreg:admins but not needed, default registration mode: dynamic, dynamic allow: permit. There are 50 pool addresses here (defined via the Bulk IP Registration interface, mode "pool"). The DHCP options are standard.
Both subnets were in a single subnet share. The config file bits I got were:
shared-network shared-8 { option domain-name-servers 128.2.32.37, 128.2.4.21, 128.2.64.2;
subnet 128.2.225.0 netmask 255.255.255.0 { max-lease-time 86400; default-lease-time 86400;
option subnet-mask 255.255.255.0; option broadcast-address 128.2.225.255; option routers 128.2.225.1; option domain-name-servers 128.2.64.2, 128.2.32.37, 128.2.4.21; pool { failover peer "dhcp.net.cmu.edu"; max-lease-time 7200; allow members of "quikreg"; range 128.2.225.4 128.2.225.53; } }
subnet 192.168.12.0 netmask 255.255.255.0 { max-lease-time 86400; default-lease-time 86400;
option broadcast-address 192.168.12.255; option routers 192.168.12.1; option subnet-mask 255.255.255.0; option domain-name-servers 128.2.32.37, 128.2.4.21, 128.2.64.2; pool { failover peer "dhcp.net.cmu.edu"; max-lease-time 300; deny dynamic bootp clients; range 192.168.12.4 192.168.12.53; } } } Bringing up an unregistered machine, I went to NetReg (DNS games could be played, but I have no doubt that works regardless of this). Using the 'machine_unreg' QUICKREG_METHOD it pops up some verbiage, you can hit "continue", and get the machine registration page.
CMU/WebInt/config.pm contains some QuickReg configuration variables. If you have the OMAPI::DHCP Perl module (check the mailing list if you can't find it), you can define $HAVE_OMAPI_MODULE = 1, which will make the MAC address lookups slightly faster. Setting it to '0' means it will use the omshell utility.
The $QUICKREG_METHOD variable can be either 'no_regs' or 'machine_unreg'. The former will present the user with the QuickReg form only when the user has no registrations. The latter will present the form when the current machine's MAC address is unregistered.
While in the network realm we tend to think of subnets to logically divide our network, we assumed that our users would first tend to think of networking logically by building. Thus, buildings are a key component of NetReg.
When adding a building, you can then specify the subnets that exist in that building. When users go to register a machine, three options are presented for finding the correct subnet: users can choose the Network (See "Subnets and Networks"), the building, or the subnet. If they select the building and only one subnet exists in the building, the system then presents the registration page for that subnet. Otherwise (if there are more than one subnets in the building), the users can then select from the shorter list of subnets in the building.
Buildings are also used for our outlet activation (See "Cables, Outlets, Activations").
The cables, outlets, and activations areas of NetReg are used at Carnegie Mellon to automate the process of outlet activation. We have two basic types of outlets: those that are pre-connected to a network switch and just need to have the switch port enabled, and those that are terminated in a closet but not connected to an access layer device. The system supports the registration of both types of these outlets (each "outlet" is connected to a "cable" in NetReg-speak). The Activations section provides the technicians that need to physically connect an outlet with a list of pending activation requests.
This section of NetReg is probably the most CMU-specific, as our cable labelling strategy is most likely very different from most. For this and other reasons, the default setting in the configuration file is to disable these areas. If you want to use them, visit the CMU::WebInt::config file. We'd be interested in getting feedback if you are interested in trying.
Services are a relatively new and interesting component of NetReg. We found that several projects now and in the future will require certain data sources. The data sources, for most part, can be described in terms of groups of machines, subnets, or zones, and various attributes. One possible implementation would be to extend NetReg via additional database tables with the required fields for each new project. However, this would be unnecessarily complex when a generic solution could be identified (and, in retrospect, the DNS configuration portion could be redesigned as a service).
Thus, services were designed. Currently only groups of machines are supported, but we'd like to extend this to include groups of subnets, zones, etc. First, you must create a service template. Here, you name the service and define the attributes.
Attributes are where services become very flexible. You define the attribute schema, and it pertains directly to the service template. When defining an attribute specification, you specify:
- The attribute name and description (separately).
- The scope of the attribute. For example, 'service' or 'service_membership'. 'Service' attributes apply to the entire service, while 'service_membership' attributes apply to individual members of services (ie, machines.)
- The maximum number of times it can appear, within the scope. For example, if you set the maxtimes to '1' for a service_membership attribute, it can appear only once (0 or 1 times) for each machine in the service.
- The attribute format. Here, you can define the exact format that the attribute data must follow. This is very similar to defining the format of a database column, but is a meta-format (in that NetReg enforces the formatting and stores the data raw in the database). We support a number of formats, and it would be fairly easy to add new formats:
- int: The attribute must be an integer.
- uint: The attribute must be an unsigned integer. In practice, negative integers will be converted to their absolute value. If the data does not conform to an integer format, though, it will be rejected.
- stringXXX: The data must be a string of length XXX or shorter (so you specify the format as string64 and a maximum length of 64 chars is enforced.)
- ustring: The data can be as long as needed.
- set(X,Y,Z): You can define a free-form set of elements that the attribute can conform to. For example, you could specify: set(dog,cat,turtle). Then, data of dog,cat; dog,turtle; or cat would be acceptable, while dog,horse would be rejected. (Although why an attribute would be used to define animals is unknown.)
- enum(X,Y,Z): Enum() acts like set(), except that the attribute must be one, and only one, of the possible values.
Additionally, attributes are further being used beyond services. We are in the process of adding User Preference screens. In this case, the scope of an attribute specification would be 'users', and the attributes could be added to an individual user.
If you are interested in adding additional attributes format, look in CMU::Netdb::validity to extend the routines which verify that the format is understand, and verify that user data matches the attribute format.
_sys_dberror Currently unused. The plan was to use this table to log errors occurring during execution.
_sys_errors This table can be updated to contain error text presented to users. Text can be customized for the particular error number, the location of the error, or the fields involved in the error. The web interface looks to find the most specific error message for the error, and returns the text.
_sys_info The _sys_info table allows for generic storage of system information. In practice, the table is used by the Scheduling mechanism to store locks with atomicity. The table's schema contains a 'sys_key', and 'sys_value', and contains an index guaranteeing uniqueness of sys_keys.
The only other key we have defined (besides general lock keys) is DB_OFFLINE. If this value is present, the value in sys_value is presented to ALL users when they attempt to login. This is a mechanism for locking out users if you want or need to ensure maintenance can proceed without interruption. Superusers (as defined in WebInt/Config.pm) are not locked out. Note this is only enforced in the web interface.
_sys_scheduled The "scheduling table" is used to keep track of what external processes need to run at various intervals. Every minute, a cron job as user 'netreg' runs support/bin/scheduled.pl. The Scheduler then queries NetReg to see which jobs need to run, runs them, and updates the table to indicate the next time of run. For example, we define DNS and DHCP generation runs take place every 15 minutes, while tasks to load new users once per day.
Unfortunately this table does not have a NetReg interface (except to provide the next run times on the Signoff screen). Eventually one will be added. Such as screen would provide an easy way to update the intervals (currently we just run raw SQL), or to "force" an immediate (or within 60 seconds) run. In this vein, one of Kevin's favorite SQL commands is: update _sys_scheduled set next_run = now() where id = 1;
Over time we have written a number of scripts to deal with maintenance of NetReg. We have documented most of them here. These are all in the support/bin subdirectory. Any of the utilities below that have 'Vars!' in the margin are utilities that you need to configure a bit before using. The configuration is generally a number of variables in the first few lines (after copyrights, etc.) in the utility. If you have questions about configuration of these utilities, please let us know.
Utilities with 'Local!' in the margin are worse than those with 'Vars!'. These are utilities heavily designed for our environment, and are probably most useful to you as a basis for other utilities that perform similar operations. 'Okay!' means we thing (with proper configuration in canonical locations) that it should work nicely for you.
This file is used to copy NetReg output onto AFS, our distributed filesystem. It contains special calls to authenticate as the 'netreg' user to AFS. It could probably be easily rewritten to deal with NFS, but you need to at least review it before using it anywhere, because it tests for existence of a particular file in AFS to determine if AFS is "up".
Bulkupdate allows you to update a number of machine registrations quickly. You supply the operations to the STDIN in the following format:
OperationType,TargetType,Args OR comment lines starting with #
OperationType: delete: delete matching entries, via API calls seperator: change the seperator used for field delimination in the spec file. add: Add an entry to a table
TargetType: delete: table name seperator: new regexp to use for split add: table to add to, only machine supported at present
Args delete: where clause to use for list_ OR just a row ID. seperator: none add: values of the fields for the entry. The form of the values should be fieldname=value. Multiple fields are separated by the current seperator (comma default, changed via 'seperator' command.). Permissions are specified via "perm=groupname PERMS level" i.e. "perm=dept:nginfra READ,WRITE 1" (note that the seperator must not be ',' for that to work)
This is our consistency checker. It has fairly useful comand line help, and is run automatically from scheduled.pl. Depending on the number of errors it finds, you will receive mail at the administrative email address once per day from the consistency checker. The goal is, of course, not to find errors. :)
The consistency checker interfaces with CMU::Netdb::consistency for much of its operations.
This script generates some basic machine information for particular zones on campus; some groups that we delegated zones to needed this information. Could be useful to use as a basis for other similar reports.
This deletes any machines with an 'expires' value of something other than '0' and earlier than today's date. This is used in conjunction with NetMon/NetReg purges, which set the 'expires' field for machines that haven't been seen lately. Run from scheduled.pl.
This script is used interactively to clear out machines on a particular subnet. You must specify the subnet ID (which you can glean from the URL if you are looking at the subnet information; it's the XX in sid=XX.) If you just specify the subnet ID, it will show you all the machines in the subnet that it would otherwise delete. Specify with -yes and it will delete all of these registrations. Specify with -ask and it will prompt with a Yes/No question for each machine, enter 'y' to delete the machine.
This is an easy way to selectively delete a number of machines; we use it to clean up after certain users.
The DHCP configuration file generator. When running interactively, you can specify the -debug option if you just want to see what it's doing. When running in debug mode, it will NOT try copying the configurations out to the servers, and the files will be written to /tmp/dhcp rather than the configured location.
As with all of NetReg, we have tried reducing the amount of CMU-specific code in the DHCP configuration file. The only major element still remaining is a set of configuration information for booting Sun workstations (and beginning a network installation as directed.) This is removed from the package as exported, but will be in our CVS tree. We also include it conditionally, if the script believes it's running on a CMU-configured machine.
Once written, the configuration files are copied to your DHCP servers. You should read the NetReg Output section for more information.
The dns-config script generates the configuration files for your DNS servers, assuming they are properly configured in the DNS area of NetReg. See the NetReg Output section for more details. As with dhcp.pl, the dns-config script can also be run with -debug to enable debugging mode. In this mode, configuration files are written to /tmp/zones.
While DHCP has integrated the transfer process into the actual generation script, DNS invokes a separate script, dns-xfer, to actually handle transferring files (zone files and configurations) to your DNS servers. Again, look towards the NetReg Output section for more information. Configuration information is culled from Netdb::config.
dns.pl is the DNS zonefile generation script. It also uses the DNS utilities to update your dynamic DNS servers as necessary. Again, configuration information is done from Netdb::config and more information in NetReg Output..
The domain-report.pl is a general script for dumping all the machines in given DNS zones. We run this script from domain-reports.sh.
domain-reports is a wrapper around the Perl script of the same name to generate reports about machines in a given DNS zone.
The dump-db script is what we use to do backups. Via cron, once an hour dump-db simply uses mysqldump to create an offline copy of the database. This is fairly fast (the entire database is dumped in a couple seconds) and provides some good short-term history. Long term we would like to incorporate a log of NetReg changes into the database (higher level than just the MySQL update logs). Right now we're average 20MB per dump (including many more cables than are included in the sample data), and about 2GB saving 30 days worth of hourly backups (though they are also copied to tape in that timeperiod).
This is our first test at a load balancing name server that uses Dynamic DNS and configuration information from NetReg. As we get this into production, more documentation will be available. The basic premise is that we'll use multiple A records that are updated fairly frequently using Dynamic DNS, so that load balancing can be done via multiple mechanisms. For example, the DNS::KMemSrv module implements a method for collecting data from our machines.
misc-reports is our script for generating different files that are useful for various tasks. For example, we generate a hosts file (in the format expected by /etc/hosts). We also generate a "bootptab". This is actually a derivative of our old BOOTP server configuration, but many people have taken a liking to the existence of this file, with one line for MAC Address, IP Address, and Hostname. If you find it useful, even better.
The passwd-load script is used to load users from the /etc/passwd (or equivalent) file into NetReg. We don't use their passwords; that must be done via some other mechanism. However, NetReg wants to know the UserID of every person using the system.
The portadmin script is our backend procedure for activating and deactivating outlets via SNMP. Unless you are using the outlet/cable infrastructure.
The ptloader script is our mechanism for loading some groups of users in our AFS cell to the NetReg groups table.
The re_ip code is used to move one subnet to another. It can either pack the hosts into the bottom of the destination subnet, or do a 1 to 1 transfer (preserving the offset into the subnet.) It can also reposition the hosts by a specific offset to free space at the start of the destination subnet and provide a predictable translation. This can also take a file of random IP addresses and move them into the first available space in the new subnet. The file should have one IP address per line, lines starting with a hash are ignored.
This was an older script used to reparent DNS zones when we had some issues with DNS zone parenting. If you believe your DNS zones are mis-parented (still somewhat likely, unfortunately), let us know. Mis-parenting in this case is the dns_zone.parent pointer is incorrect. This can manifest itself as records appearing in the wrong zonefile, etc.
scheduled is the central clearinghouse for running periodic tasks with NetReg. See the NetReg Design section for more details.
service-dump dumps out everything from the service groups to the SERVICE_FILE. Again, look to Netdb::config and the NetReg Output section for more information.
At one point we tried actually keeping the base and broadcast address on every subnet registered, and the set-base-broadcast script is an automated way of registering base/broadcast addresses that are not.
The subnet scan script handles the actual updating of machine records that are being purged for non-activity on the network. This is still in the final stages of development, and more documentation is forthcoming.
The user_sync script is similar to passwd_load in that it syncs the NetReg user database. The difference is that user_sync is designed to use our LDAP database instead of the password file.
The vars.sh file is our attempt at standardizing configuration of support utilities. This file is sourced by other shell scripts as needed, so that duplicate configuration of your NetReg home, for example, is automated. vars should not execute any commands, just set variables.
The vars_l.pm file is our attempt at standardizing configuration of support utilities. This file is used by other Perl scripts as needed, so that duplicate configuration of your NetReg home, for example, is automated. The goal of vars_l.pm is just to allow support utilities to locate CMU::Netdb and the accompanying config module.
[ Contents| First Page | Previous Page | Home | Next Page | Last Page ]
[ 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ]
Copyright © Carnegie Mellon University 2000-2003. All rights reserved.