IPplan - IP address management and tracking

Revision History Revision 4.81 2007-01-23 Revised by: re Revision 2.91 2002-05-17 Revised by: re

IPplan is a free (GPL), web based, multilingual, IP address management and tracking tool written in [1]php 4, simplifying the administration of your IP address space. IPplan goes beyond IP address management including DNS administration, configuration file management, circuit management (customizable via templates) and storing of hardware information (customizable via templates). IPplan can handle a single network or cater for multiple networks and customers with overlapping address space. See the introduction section for more. _________________________________________________________________

Table of Contents

1. [2]Introduction

   1.1. [3]Copyright Information 1.2. [4]Disclaimer 1.3. [5]New Versions 1.4. [6]Credits 1.5. [7]Feedback 1.6. [8]Translations

2. [9]Requirements

   2.1. [10]Databases 2.2. [11]Additional features

3. [12]Installation

   3.1. [13]Customization

4. [14]Downloads, bugs and forums

   4.1. [15]Screenshots

5. [16]Mode of operation

   5.1. [17]Services company 5.2. [18]ISP

6. [19]Concepts

   6.1. [20]Deployment strategy 6.2. [21]Linking addresses

7. [22]Administration

   7.1. [23]Admin user 7.2. [24]Customer access 7.3. [25]Subnet access 7.4. [26]Group authority boundaries

8. [27]Circuit administration, host configuration data and asset information

9. [28]Device configuration file management

10. [29]DNS administration

    10.1. [30]Handling exported zones 10.2. [31]Automatic updating of zone records

11. [32]Dealing with registrars

12. [33]Searching

    12.1. [34]Searching for individual address details 12.2. [35]Searching areas and ranges

13. [36]Config file

14. [37]Importing data

    14.1. [38]TAB delimited data 14.2. [39]Importing using NMAP

15. [40]Templates

    15.1. [41]Customer, Subnet, DNS and IP address templates 15.2. [42]Registrar templates

16. [43]DHCP

17. [44]Triggers

18. [45]External command line poller

19. [46]IP address request system

20. [47]Authentication schemes

21. [48]Problems

22. [49]Limitations

23. [50]Questions and Answers (FAQ)

[51]http://sourceforge.net _________________________________________________________________

1. Introduction

   IPplan is a web based, multilingual, IP address management and tracking tool based on [52]php 4, simplifying the administration of your IP address space. IPplan can handle a single network or cater for multiple networks with overlapping address space.

   Current functionality includes

   • internationalization
   • importing network definitions from routing tables
   • importing definitions from TAB delimited files and [53]NMAP's XML format
   • multiple administrators with different access profiles (per group, allowing access per customer, per network etc.)
   • define address space authority boundaries per group
   • finding free address space across a range
   • split and join networks to make them smaller and larger - ip definitions remain intact
   • display overlapping address space between networks
   • search capabilities
   • an audit log - contents before and after change is logged
   • statistics
   • keeping track of and sending SWIP/registrar information
   • DNS administration (forward and reverse zones, import existing zones via zone transfer)
   • template system to extend IPplan to contain site specific information like circuit data, host configuration data, asset information
   • device configuration file management
   • external stylesheet to change display look
   • triggers - every user event can call a user defined function - useful to execute backend DNS scripts
   • external poller - scan subnets for active addresses to gather usage statistics
   • IP address request system - allows users to request static IP addresses from the database

   Two authentication methods are available - either IPplan's own internal authentication scheme, or alternatively make use of any external Apache authentication module. This includes single sign on systems like SiteMinder or your own scheme based on LDAP, or any other Apache compatible system.

   ---

1.1. Copyright Information

This document is copyrighted (c) 2002 Richard E and is distributed under the terms of the Linux Documentation Project (LDP) license, stated below.

Unless otherwise stated, Linux HOWTO documents are copyrighted by their respective authors. Linux HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.

All translations, derivative works, or aggregate works incorporating any Linux HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the Linux HOWTO coordinator at the address given below. _________________________________________________________________

1.2. Disclaimer

No liability for the contents of this documents can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies, that may of course be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility for that.

All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

Warning

It is strongly recommended to make a backup of your system before major installation or upgrades and to backup at regular intervals. _________________________________________________________________

1.3. New Versions

See the CHANGELOG file for more information. _________________________________________________________________

1.4. Credits

Thanks to [54]ValueHunt Inc. for the use of their layout class used for rendering all HTML pages.

Thanks to [55]AdoDB for the use of their generic database abstraction class.

Thanks to [56]Vex for their Visual Editor for XML used to generate the IPplan documentation.

Thanks to [57]The PHP Layers Menu System for their menu system. _________________________________________________________________

1.5. Feedback

Feedback is most certainly welcome for this document. Without your submissions and input, this document wouldn't exist. Please send your additions, comments and criticisms to the following email address : <[58]ipplan@gmail.com>. _________________________________________________________________

1.6. Translations

See the INSTALL and TRANSLATIONS files on how to enable multilingual support and how to do a translation to your own language. Doing a translation does not require any programming experience. Current languages supported are English, Bulgarian, French - Auto Translation, German - Auto Translation, Italian - Auto Translation, Norwegian - Auto Translation, Portuguese - Auto Translation and Spanish - Auto Translation.

Nickola Kolev for the Bulgarian translation - nikky at mnet.bg.

Conrado Pinto Rebessi for the Brazillian translation - conradopinto at yahoo.com.br

Tadashi Jokagi for the Japanese transalation - elf2000 at users.sourceforge.net

Vladimir Leshchenko for the Russian translation - worker at smtn.stavropol.ru _________________________________________________________________

2. Requirements

   IPplan requires a working web server installation. Currently the [59]Apache web server is preferred, but php as an ISAPI or CGI module on IIS works too

   • follow the appropriate installation instructions in the IPplan directory (INSTALL-IIS+MSSQL). Apache works just fine on Windows platforms too. For installing Apache on a Windows platform, follow [60]these instructions. Or you can use [61]AppServ or [62]WampServer which are complete installation packages for Apache, MySQL and PHP for Windows - just add IPplan by following the installation instructions in the IPPLAN-WINDOWS file (part of IPPlan).

     ---

2.1. Databases

IPplan requires a working database installation. The following databases currently work:

 * [63]MySQL 3.23.15 or higher (preferred)
 * [64]PostgreSQL 7.1 or higher
 * [65]Oracle 9i or higher (SQL99)
 * Microsoft SQL server (both 7 and 2000)

The following may work, but are untested - Sybase. In fact, any database that supports SQL99 compliant joins, in particular LEFT JOIN, should work. See limitations section below for more.

The web scripting language [66]php 4.1 or higher must also be installed as a module in Apache (NOT as a cgi). Php must have the preferred database driver compiled in and enabled. See the respective web sites and installation documents for more detail. IPplan works just fine with a combination of the Apache web server and php on a Windows platform - just read the relevant installation instructions for Windows carefully.

Tip

IPplan is also known to work in a distributed, replicated MySQL environment with multiple database servers. See [67]www.oreilly.com for more information. _________________________________________________________________

2.2. Additional features

To enable SNMP support, you will require the [68]ucd-snmp package installed and configured in your environment. This must also be activated in the php configuration. SNMP support is only required if you wish to read routing tables directly from routers. _________________________________________________________________

3. Installation

   Follow the instructions for your platform and database in the INSTALL files in the IPplan directory.

   ---

3.1. Customization

IPplan is customizable in many ways. See the sections on templates, triggers and pollers. You can also extend the menu system to include your own custom menus for other systems at your site - see the config.php file for an example. _________________________________________________________________

4. Downloads, bugs and forums

   You can report bugs, contribute to forums and download it [69]here and look at the latest [70]TODO and [71]CHANGELOG.

   ---

4.1. Screenshots

You can find some screen shots [72]here. _________________________________________________________________

5. Mode of operation

   There are two modes of operation, one can be classified as a services company and the other as an ISP.

   ---

5.1. Services company

As a services company your primary use of IPplan will be to manage individual IP address records and the address plan of one or more customers. _________________________________________________________________

5.2. ISP

In ISP mode, you will assign blocks of IP address space to your customers. In this mode, you will not be concerned at all with individual IP address records and how the customer breaks down his assigned address space. When you operate as an ISP, you may also generate SWIP/registrar entries, which are only useful if you deal directly with ARIN or any other registrar. (SWIP is enabled in the config.php file, see ARIN [73]tutorial for more details). All the relevant SWIP/registrar information is entered when the customer is created.

When using this mode, I suggest creating a dummy customer which holds all the allocated address space from your regional registrar (ARIN?) already broken up into the various blocks that you will eventually assign to your customers. All these blocks should be called "free" to allow them to be found using the "Find free" menu option. Once you are ready to assign a block, create a new customer with all the relevant SWIP/registrar information completed, go to your dummy customer and move a block of address space to the newly created customer, and finally generate a SWIP/registrar entry for the new block. In this mode areas and ranges are not too relevant except for the dummy customer (see concepts below). You may also need to create a template for your registrar in the templates directory. If you have done this, feel free to contribute it to IPplan. _________________________________________________________________

6. Concepts

   The flow of address management is based on the creation of areas, then ranges which belong to areas, and finally, subnets which belong to ranges. Actually, only subnets are required, but on large networks it makes logical sense to group the network into areas to ease administration and to reduce routing updates on the network. There is a jpeg drawing included with the distribution that graphically shows these relationships. The methodology employed borrows significantly from OSPF routing concepts which are explained more fully [74]here.

   ---

6.1. Deployment strategy

So in a new installation, first create the areas, then create ranges adding them to areas, and finally create subnets. Searching is now a simple matter of selecting an area which will display all the ranges for the area, or selecting no area and simply selecting a range from the total list of ranges, or simply selecting a base network address.

Note

Within a customer or autonomous system, no overlaps of address space is allowed. This follows standard IP addressing rules. You can have overlapping ranges/aggregates, but the default behaviour of ranges also prevents overlaps. This can be changed in the config.php file.

To handle challenges like NAT or other overlapping address space, you will be required to create multiple autonomous systems. See 'Searching' below how to see information across multiple autonomous systems. _________________________________________________________________

6.2. Linking addresses

IP address records can be linked together. This allows one address or multiple addresses to reference another address or addresses. Using this feature allows for the referencing of NATed addresses or having a link to a loopback address of a device. Linking is done on the IP address details page by completing the "Linked address" field. Once the field is completed, you can follow the link. The link also appears on subnet summary pages.

You can also link many addresses in one go by choosing multiple addresses in the "Select multiple addresses to do a bulk change" window, then completing the "User" field as follows: LNKx.x.x.x userinfo

The LNK identifier must be in uppercase, followed by exactly one valid IP address with no spaces, then followed by an optional space and user description. After the page is submitted, the embedded LNK will vanish.

Note

If the destination record of a linked address does not exist, a record will automatically get created pointing back to the source address, but only if the destination subnet exists. This is to signal the "Find Next Free" address logic of the subnet that the destination address is used. _________________________________________________________________

7. Administration

   The access control is divided up into three layers and revolves around the creation of groups:

   ---

7.1. Admin user

Firstly you will need to create users and groups using the admin user defined in the config.php script. The admin user can only be used on the admin pages. Once you are done with the admin functions, you will be required to re-authenticate as one of the newly created users as soon as you access functions on the main index page. _________________________________________________________________

7.2. Customer access

When a customer is created, a group must be assigned to the customer. This will be the customers admin group and all members of this group can create and delete both subnets, ranges, areas and individual IP address records for the customer.

When the subnet is created, the creator will choose a subnet admin group. _________________________________________________________________

7.3. Subnet access

The users assigned to the group that has subnet access can only modify individual IP records for that subnet.

Initially I would create three groups, one group that can create customers, one group that can create subnets, areas and ranges, and another group which can only modify individual IP records. Normally in large networks the people that modify IP records are not the same people that administer routers and configure the IP address space.

If a group is set to see only a particular customer, the same group needs to be used for all operations for the customer. The side effect to this is that the users assigned to the group have full access to the customer and can make any changes to the customers data, including creating and deletion of subnets. This is not ideal and will be changed in future.

Tip

Groups can be created that prevent certain users from changing an administrator defined number of reserved addresses at the start of a subnet. _________________________________________________________________

7.4. Group authority boundaries

Areas of responsibility can be assigned to a group, thus limiting what address space a group can create networks in. The default behavior allows administration anywhere. Care should be taken when using this feature as changing the boundaries at a later stage may orphan some parts of the database and yield data inaccessible.

Note

If a user belongs to multiple groups and one of the groups does not have boundaries defined, then the user is granted all access. Thus boundaries are a sum of all the boundaries the user belongs to.

Tip

Bounds are also useful to create users that only have read access to the IPplan information. Select the "Read Only" option when creating a new group. _________________________________________________________________

8. Circuit administration, host configuration data and asset information

   Using the template capability IPplan can be extended to contain custom information about your site. You can add any number of custom fields for your site. See the section on "Templates" for further information.

   ---

9. Device configuration file management

   Any number of files can be attached to individual IP records. Using this feature, configuration data (text and binary, drawings etc) for devices can be stored and managed by IPplan.

   ---

10. DNS administration

Both forward and reverse zones can be created via the web interface. Zone domains are forward zones - there can be as many forward zones as you like per customer. Each of these can be unique or they can even overlap with other customers.

Forward Zones:

To create a forward zone, select a customer and select "Add a DNS zone". The next screen will allow you to enter information for the new zone. The domain name must be entered as must at least two nameservers.

At this point you have the option of creating a new zone from scratch, cloning (copying) a zone from an already existing zone called "template.com", or importing an existing zone via a zone transfer. If you do a zone transfer, the PRIMARY or SECONDARY DNS servers must be directly contactable from the webserver on which IPplan is running. If the DNS server is not contactable an error will be returned.

If a domain is created from scratch, the domain name must be entered as must at least two upstream DNS servers. The DNS servers are automatically entered for you if the customer record (created via "Create a new customer/autonomous system") contains DNS servers. This is a good way to not have to manually add the DNS servers for each new zone created. The DNS servers can be changed and will be independent per zone created. At the bottom of the Add/Edit screen is place to enter two zone file paths. In future this can be used to determine where the zone must be saved or on what DNS server the zone must be created - currently these fields do nothing.

The next step is to add individual records to the newly created zone. Do this under the "Zone DNS records" main menu function. Select the customer, select the domain and add a host. The "Host name" refers to the left hand side of a bind zone file, then the type (A, CNAME or MX - more types in future) and the "IP/Hostname" refers to the right hand side of the zone file. In future the screen will change depending on the record type you select and more record types will be possible. The sort order determines the placement of the record in the zone and on the screen. This is a number and the default is 9999 or the end of the file. If you want to insert records between other records, work out a numbering plan.

In future this will be automatic with options to "Insert before" and "Insert after". Currently you can renumber the values retaining the order of the entries.

Reverse zones:

To create reverse zones is very much like creating a forward zone, except that there are no detail records. All that is required is to create a starting address and mask. The actual reverse records are extracted based on the start and mask from the IP records when you create a subnet and add records to the subnet. The field used is the host name field and all invalid information in this field will be ignored with a warning.

Once your forward and reverse zones are created, each time a change is made you will be required to export the zone by clicking on the "Export zone" option. The output generated is in XML and must then be parsed using and XSLT processor into a format compatible with your DNS server. _________________________________________________________________

10.1. Handling exported zones

The zone files are created in the directory specified by the DNSEXPORTPATH variable in the config.php file. The files are in XML format and are created when a user hits the Export option either on the DNS page or Reverse zone page. The files have a format of zone_ or revzone_ followed by the zone name followed by a trailing unique identifier, which is operating system dependent. The file has a .xml extension.

If a template is attached to the forward zone, the template fields will also appear in the exported XML file with tag names the same as the template field names.

These files must be processed using a XML stylesheet processor into a format suitable for your DNS server, and then placed into the correct location and activated by your DNS server. This is beyond the scope of IPplan and will require custom scripts for your installation. Contributions are welcome.

Sample procedure:

You will require a script for your environment that periodically runs to check for new zone files that have been added to the output directory. You will probably use cron to do this. Once your script finds a file, you can extract the file paths saved in IPplan using a simple grep:

grep -A 1 '' /tmp/revzone_FS9mEU|grep -v ''

This gives me the primary file path. Once you have the destination path, process the file and copy the output by whatever means your environment uses to the target DNS server. I would suggest using scp with a public key on the remote server to prevent having to type in user id's and passwords during the copy process.

Processing the file:

A sample XSLT stylesheet can be found in the contrib directory to transform the forward zone XML (files starting with zone_) into a bind8 or higher compatible zone file. I use xsltproc from the libxslt package ( [75]http://xmlsoft.org/XSLT/) which should be installed on most modern linux systems. A different stylesheet (.xsl file) will be required for each DNS server system that you use - I have no intention of writing style sheets for all the various DNS servers out there, but you are more than welcome to send me style sheets for different DNS servers to be included with IPplan.

A sample command is:

xsltproc bind9_zone.xsl zone_

For sample XML input of:

Generating output as follows:

$ORIGIN test.com. $TTL 86400 @ IN SOA test.com. dnsadmin.test.com. ( 2004062604 ; serial 21600 ; refresh 3600 ; retry 604800 ; expire 21600 ) ; minimum TTL

    IN      NS      ns1.example.com.
    IN      NS      ns2.example.com.
    IN      NS      ns3.example.com.
    IN      NS      ns4.example.com.

myhost IN A 10.10.10.1 myhost-alias IN CNAME myhost IN MX 10 mailhost _________________________________________________________________

10.2. Automatic updating of zone records

IP subnet records (which equate to zone PTR records) and forward zone A records will automatically get syncronised and updated provided a number of criteria are fulfilled.

If a DNS A record is created or updated, and there is exactly one A record across all the customers zones matching one IP subnet record, then the IP record hostname field will be updated with the A record hostname field.

If an IP record hostname field is updated, then the zone A record field will be updated if there is exactly one A record matching the IP record across all the customers zones.

If an IP record hostname field is updated and a matching A record cannot be found, then an A record will automatically be created in the matching domain provided there is only one matching domain. This will only happen if the DNSAUTOCREATE setting is TRUE in config.php.

Under all the above conditions a warning message will be displayed stating that an update occured. The appropriate log entries will be made and triggers will fire. _________________________________________________________________

11. Dealing with registrars

Registrars are interacted with by email. IPplan can manage all the records and manage all the fields and data required to generate the registrar updates, no matter what the registrar is (ARIN, RIPE, APNIC etc). Before these functions will work, the correct config variables need to be set - these include the REGENABLED, MAINTAINERID, REGISTRY, REGEMAIL etc. Only users belonging to the customer admin group can send these updates. Additional fields can be added to the IPplan display pages if required, and these fields are also available to the registrar templates.

To generate updates, the required registrar template is selected. IPplan includes a limited number of templates, but these are fully customizable and simple to create and modify - see the section on "Templates" later in the manual. Once the template is selected, the fields from the database are substituted into the template file and the output is displayed on the screen. The user then selects which updates should be sent to the registrar. The selected updates are then sent via email and the date the updates were sent are recorded in the IPplan database. _________________________________________________________________

12. Searching

Creating a special customer called 'All' allows searching for information across all the available customer/autonomous systems using the 'Display subnet' function. This special customer can contain areas and ranges that limit the scope of searches, just like normal customers. Using this feature allows a user to see the entire network picture in one view.

Tip

When creating new subnets, it is also beneficial to create unused subnets with a a description of either 'free' or 'spare'. These can be searched for at a later stage using the 'Find Free' function.

Tip

It may also be beneficial to give ASE (Autonomous System External, networks not local to yours) a special handle like EXTERNAL so that they can be searched for at a later stage. These networks often appear in routing tables as static routes to third parties (not via the Internet). _________________________________________________________________

12.1. Searching for individual address details

Searching can also be done on individual addresses using the 'Match any IP address in subnet' option of the 'Display subnet information' option. This is useful for finding which networks, either for a single customer, or for all customers an IP address belongs to. Using this option makes it easy to find the offending network in a complaint situation if you are an ISP.

If matching by IP address, you will automatically jump to the IP address edit page if the search is unique and matches only one subnet from one customer. If you use the 'All' customer you will need to click on the relevant customer network you wish to work with. _________________________________________________________________

12.2. Searching areas and ranges

You can also create areas and ranges to search across only certain address space ranges. Areas are containers for ranges. Selecting an area that has ranges attached will search only in those ranges. Select an area and not selecting a range will search across all the ranges in the area.

Depending on what settings have been selected in the config.php file, ranges may either never overlap (the default), have overlaps within an area only, or overlap in anyway, including having duplicate ranges.

Note

Areas with no attached ranges will not display in the "Area" selection list until ranges are added to the area. Areas with no ranges yeild no search results. _________________________________________________________________

13. Config file

A a number of settings that can be changed in the config.php file. These include the database connection information, admin user and password, and the number of lines displayed in tables. See the comments in the config.php file for more details. _________________________________________________________________

14. Importing data

Data can be imported by the admin user via TAB delimited text files or from output generated in XML format by [76]NMAP. _________________________________________________________________

14.1. TAB delimited data

Network definitions or individual ip records can be imported in TAB delimited format.

The order of columns for network definitions or subnet descriptions are (three columns required): The first column contains the IP base address, the second the description and the third the mask either in dotted decimal format or in bit format.

The order of columns for importing IP records should be (six columns required): The first column contains the IP address, the second the user, the third the location, the fourth the description, the fifth the hostname and the sixth the telephone number.

If you have more than six columns, the remaining columns will be entered into the user defined fields specified in the template. The order will be the order the fields are defined in the XML template file.

See the templates section for details on how the templates work. _________________________________________________________________

14.2. Importing using NMAP

A typical application for this would be to obtain data for networks that there are no records for. NMAP would be used to obtain the host info of all the addresses that are active on the network. Once this is done, the data can be read into IPplan. The NMAP parameters required by IPplan to generate a valid import file are: Â -sP -oX output.xml

To speed up the process, you can add -n to not resolve host names. The import process also understands the -O operating system detection parameter. To use -O, you will need to drop the -sP parameter. Using -O increases scanning time significantly.

As of version 3.93 of nmap, the -sP option also returns the MAC address which will be recorded in the MAC address field of the subnet IP record. MAC addresses only appear if the scan was done using root user - thus the MAC address will not appear if nmap was executed through php and the webserver. You can set the S bit on the nmap binary, but this is not advised due to security concerns. _________________________________________________________________

15. Templates

Various forms of templates are available. These include templates that add additional, custom fields to the IPplan display pages (different templates can be added to the customer, subnet and ip address record pages), and templates that then munipulate the data contained in the IPplan databases to generate output for various registrars. All of these templates are fully administrator customizable with display fields added to customer and subnet pages automatically available in output templates used to generate registrar updates. _________________________________________________________________

15.1. Customer, Subnet, DNS and IP address templates

The administrator can define a custom template in IPplan to allow the addition of as many custom fields to the customer, subnet, DNS forward zones and ip address record pages as the administrator wishes. This functionality allows flexibility in the way data is added to the database. Some uses for these templates include tracking asset information or WAN circuit information, the management of DHCP address space, dealing with additional and ever changing registrar requirements.

As mentioned there are different template files for the customer, subnet, DNS and IP address pages. The template for each of these pages has a different name:

Customer pages - custtemplate.xml

Subnet pages - basetemplate.xml

DNS forward zones - fwdzonetemplate.xml

IP address pages - iptemplate.xml

IP address pages (network address) - iptemplate-network.xml

A sample template called iptemplate.xml.sample can be found in the /ipplan/templates/display directory.

If a template called called iptemplate-network.xml exists, then this template will be used for network addresses (the first address of the subnet). This is useful to define subnet wide information like VLAN id's, telco line numbers, router configurations etc. If the iptemplate-network.xml does not exist, then the iptemplate.xml template will be used for network addresses.

The above templates are generic and act across all customers, and thus all fields are the same for all customers. Unique templates can be created per customer by adding the customer id to the template name. To obtain the customer id (a number), use the Admin/Maintenance function within IPplan. To create a unique IP address template for customer id 25, place a template file called iptemplate-25.xml in the /ipplan/templates/display directory. This template will override the default template for customer 25 only. _________________________________________________________________

15.1.1. Format of Customer, Subnet and IP address template files

The templates are well formed XML files with a .xml extension and should be stored in the /ipplan/templates/display directory. You should use the xmllint tool to test the XML file before using it with IPplan - no errors should be returned.

The standard iptemplate.xml file adds a free form text field to all the ip address record pages and has this definition:

A field definition to add a select drop down list:

<FIELD>
 <DEFINITION NAME="select" TYPE="S" DESCRIP="This is select list with two o

ptions" DEFAULT="2">

The template file must be surrounded with statements. Note that XML tags are case sensitive and must match as per the example. Each field is contained in a statement. Each field must have exactly one line. Any line with an error will be silently ignore! The following are valid for a definition:

NAME

This is the field name used internally to track the names of the variables. Can contain letters and numbers only - no spaces or anything else.

DESCRIP

This is the description that will be displayed above the field.

TYPE

This is the type of the field. C for a character field and T for a memo or multi-line field, S for a select drop down list.

DEFAULT

The default value for the field the first time the field is completed.

MAXLENGTH

This is the maximum number of characters a field can consist of.

SIZE

This is the display length of the field on the screen - if SIZE is less than MAXLENGTH, the field will scroll. SIZE may not be more than MAXLENGTH.

ROWS

This is the number of rows to display on the screen - only valid for text or multi-line fields.

REGEX

This is a regular expression to test validity of the entered information. To test a field, use ^ and $ to signify the start and end of the field, so something like ^[a-zA-Z0-9]$

ensures that the field only contains numbers and letters. See http://regexlib.com/ for more on regular expressions.

Regular expressions are PERL compatible and use a / character as the delimiter, thus if you want to match on a /, you will need to escape the /. So to match a letter, / and a number, this is the expression ^[a-zA-Z/0-9]$

Regular expression | can be used for multiple matches. Thus the following will match a field or a blank entry ^[a-zA-Z/0-9]$|^$

ERRMSG

This is the error message that is displayed if the regular expression match fails.

Default template:

The default template contains one field which is the "Additional information" field of older versions of IPplan. If you do not want this field, change the template or delete the template entirely.

Template rules:

If you delete the template all fields will vanish and cannot be accessed. IP records that have been completed with fields from a template will not be lost, but records that do not have template fields cannot have template fields added until the template is either restored or similar fields are added.

Note

Deleting fields from a template results in existing fields in the database with template data using a default field definition. The data is not lost. It is not a good idea to modify or change the template on a production system. Plan the template fields carefully before implementing. _________________________________________________________________

15.2. Registrar templates

Templates for sending information to registrars should be well formed XML stylesheets. See the existing templates in the /ipplan/templates directory for examples. Currently only the <xsl:value-of select="variable"/>

tag is understood and all other XML tags are stripped, thus only variable substitution is done. This is to prevent requiring the XSLT php library to be compiled in. In future XML stylesheets will be supported in full.

There are a number of special variables available during the registrar output process which are defined in the config.php file:

source -> the REGISTRY config setting maint -> the MAINTAINERID config setting regid -> the REGID config setting password -> the REGPASS config setting date -> todays date in UTC format

in addition to the standard customer page variables:

ntsnum -> starting of IP address range ntenum -> end of IP address range ntname -> network name as defined in the subnet description field DNS: hname1 -> DNS hostname 1 ipaddr1 -> Primary DNS server hname2 -> DNS hostname 2 ipaddr2 -> Secondary DNS server hname3 -> DNS hostname 3 ipaddr3 -> Third DNS server . . . hname10 -> DNS hostname 10 ipaddr10 -> Thenth DNS server

Contact: org -> Organization street -> Street city -> City state -> State zipcode -> Zip code/Postal code country -> Two letter country code

Technical contact: nichandl -> Nickname/handle lname -> Lastname fname -> Firstname mname -> Middle name torg -> Organization tstreet -> Street tcity -> City tstate -> State tzipcode -> Zip code/Postal code tcntry -> Two letter country code phne -> Phone number mbox -> Email address

Plus any variables defined in a customer template (custtemplate.xml) and also the subnet template (basetemplate.xml) as described above will also be available. The names of the variables will be the same as defined in the customer template.

Thus the following basetemplate.xml file:

will provide the following additional variable to the registrar template

remarks -> Remarks field for subnet

Note

If there are duplicate variable names defined, the variables in the basetemplate.xml file, then the custtemplate.xml file appearing in the "Additional information" section of the customer and subnet administration pages will have precedence over any standard variables. _________________________________________________________________

16. DHCP

A special sample template called basetemplate.xml.dhcp can be used in place of the basetemplate.xml file to provide DHCP support. This template works in conjunction with the DHCP export function of IPplan. For a DHCP export to work, the subnet must have the correct template, the subnet must be marked as DHCP and subnet address descriptions must start with the 'DHCPRESERVED' config.php variable. Once an export has been initiated, the resulting output must be processed via an XML parser just like any other export function of IPplan.

Multiple address pools can be simulated by adding numbers to the end of the IP address decsriptions eg. 'Reserved - DHCP pool 1'. Static assignments are dealt with automatically if an IP address has a valid MAC address assigned. _________________________________________________________________

17. Triggers

Every database event (create a customer, update an ip record, export a DNS zone file etc) in IPplan can trigger an external user defined function or script. This is useful to update and external system like a DNS server once something in IPplan has changed.

You will be required to write your own custom script to do the required action. This script will be called from the user_trigger() function in the ipplanlib.php script. See the comments of this function for more details.

A list of all the IPplan triggers and what information is passed to the user_trigger() function can be found in the TRIGGERS file. _________________________________________________________________

18. External command line poller

The poller allows you to periodically scan subnets for addresses that are active on the network. This information is then logged in the IPplan database and will appear on the display subnet page. You can find the poller script in the IPplan contrib directory.

The scans are done using nmap, thus large networks can be scanned rapidly. Subnets that are to be scanned get entered into a plain text file, so maintenance is easy. Polling can be automated by adding the poller to cron.

Firstly, you will need to create a file containing a list of networks/addresses that you would like to poll. The file is a text file with one address per line in the any format that the nmap command understands (type nmap -h for more info).

10.10.10.0/24 10.10.11.* 10.12.12.1

Once you have created your file you will need to make sure the poller is configured correctly. Edit the poller file and change the path at the top to the correct place where the command line php can be found on your system.

You can find the location by typing

which php

Next make sure that nmap can be found. Type

which nmap

and either update the NMAP statement in the IPplan config.php file, or uncomment the NMAP define at the top of ipplan-poller.php and update to reflect the correct path to nmap. This define will override whatever is in config.php allowing a different NMAP to be used. You may also leave config.php blank to prevent scanning from within the IPplan web frontend.

Now run the ipplan-poller.php file with the -d option, or navigate to the admin->maintenance page. This will dump a list of customers and customer id's. You need to find the id of the customer you want to update:

php -q ipplan-poller.php -d

ID Description 2 Test 46 Test customer 47 Test customer 2

Finally run the poller again with the correct command line (assuming you want to update the customer called "Test customer" which has id 46):

php -q ipplan-poller.php -c 46 -f nmap.list

If the configuration is correct and there are no errors, there should be no output - the database is updated silently in the background. Any address that was successfully polled will now have a key in the "Pol" column on the IPplan display pages.

D polled today W polled within last week M last month Y last year

You can now add the above line to cron to scan certain subnets periodically.

The following command line options are available with the poller:

IPplan poller v1.0

-h this message! -q suppress check if tool is executed from the command line -d dump a list of customers and customer id's -f filename containing list of subnets to scan, one per line in addres s/bits format see the NMAP manpage for examples -hostnames resolve and populate hostnames -time timestamps the scan at start and completion -a create auditlog entries for newly added records

-c customer id to update

example: php ipplan-poller.php -d php ipplan-poller.php -time -hostnames -f /tmp/nmap.lst -c 1

Using the -hostnames option will query the DNS when polling addresses and update the host name field within IPplan with the DNS name. Note that using this option could significantly increase polling time, especially with incorrectly configured DNS servers. Use the -time option to determine impact of using the -hostnames option.

Note

Security: You should use a different user and password to access the database using the command line poller. I suggest creating a user that can only SELECT, UPDATE and INSERT into the ipaddr table, and SELECT from the base and customer tables. See your database administrator or manual for more details. _________________________________________________________________

19. IP address request system

IPplan has a request feature whereby users can request individual IP addresses by completing a form. This form is then submitted into the IPplan database and via email to an administrator or help desk account for processing. When the administrator processes the request, all outstanding requests for a particular customer/AS will appear on the IP address modify screen. The administrator picks the relevant address from the list and all the fields are automatically completed with the request details. The administrator can then change some of the fields details before submitting. When the form is submitted, the request is deleted.

Up to 100 outstanding requests can be active at one time (this is configurable by changing a variable at the start of the requestip.php script). This is to prevent denial of service on the database as the request page is not authenticated. Excess junk requests can be cleared via an admin only option on the maintenance page.

Request email addresses are set in the config file. The list of visible customers/AS's that addresses can be requested for are also set via config options. The default is that addresses can be requested for all customers.

The request page also has the top menu structure disabled by default (this can be enabled by changing a variable at the start of the requestip.php script). Disabling the menu allows the page to be used as a generic request page on a sites intranet server without confusing regular users with menu options they cannot use or access.

Tip

If an email field exists in the iptemplate.xml file, this field will be used to popup an email window, allowing the newly actioned requested address to be emailed back to the requester. The email window will only display after Submit has been pressed and the user has entered a valid email address.

A sample definition for this field is as follows:

See the section on templates for more information.

If a valid email address is found in the above field you will be given the option to email the details back to the requester. The gateways are site specific and can vary - manual completion of this field is required unless one of the subnet addresses has a description field starting with GW. This address will then be used as the gateway address in the email. _________________________________________________________________

20. Authentication schemes

IPplan supports either its own internal authentication scheme, or an external scheme based on the Apache webservers authentication modules. To use an external scheme, change the setting in the config.php file. Next, place the relevant .htaccess file in the IPplan user subdirectory (/ipplan/user). Do not place an equivalent file in the admin subdirectory as the admin account cannot be overridden.

Note

When using the external authentication method, IPplan never prompts for a userid and password. It is the responsibility of the external module to do the prompting, if any. IPplan uses the credentials supplied and matches them to the IPplan userid records to determine if access should be granted.

Important

The relevant users requiring access to IPplan must still be created via the IPplan admin interface, but no password information is required as this is overridden by the external authenticator.

If the user is removed from the external authenticators database (ldap, radius etc), the user will no longer be able to log in to IPplan even if the account still exists in IPplan. This scheme only handles single signon and password changes, not single point of administration.

Make sure that the external authenticator only returns the userid in the php REMOTE_USER variable. Ldap (or auth_ldap) by default will return the entire DN, but this can be configured to return only the userid. From the auth_ldap docs at [77]http://www.rudedog.org/auth_ldap/1.6/auth_ldap.html ensure that the AuthLDAPRemoteUserIsDN is set correctly. You will also need to look at the AuthLDAPGroupAttributeIsDN attribute.

Read the instructions in config.php carefully for debug tips.

External authentication was tested against SiteMinder and the Apache [78]auth_ldap module. The [79]CAS authentication module is also supported - there are special config.php variables to support this configuration.

Warning

THE HTTP BASIC AUTHENTICATION SCHEME DOES NOT ENCRYPT USER-IDS AND PASSWORDS TRANSMITTED TO THE WEBSERVER - IT IS RECOMMENDED THAT IPPLAN IS INSTALLED ON AN SSL PROTECTED WEBSERVER ON PRODUCTION SYSTEMS. _________________________________________________________________

21. Problems

    • PHP's IP management functions and binary arithmetic functions are seriously broken (see [80]bug report logged) Due to this limitation, the biggest subnet that can be created is limited to 254k hosts.
    • This brokenness also prevents the use of the ip2long() and long2ip() functions introduced with php 4.x. I have used php only functions called inet_aton() and inet_ntoa().
    • SNMP appears to be broken on Redhat 7.2 systems. Try following these [81]instructions for help.

    ---

22. Limitations

    • Due to the authentication scheme used, only the Apache web server is supported currently. PHP installed under IIS as a cgi is reported to work too.
    • IPplan can be run with php configured for safe_mode=on and register_globals=off.
    • IPplan was developed using MySQL as a database. Using other databases require workarounds for some functionality which is not optimal. During my own tests, speed was visibly faster using MySQL.

    ---

23. Questions and Answers (FAQ)

Check the forums on SourceForge too.

The FAQ is no longer maintained in the manual - check online at the [82]IPplan homepage.

References

1. http://www.php.net/
2. http://sourceforge.net/
3. http://www.php.net/
4. http://www.insecure.org/
5. http://www.vhconsultants.com/
6. http://adodb.sourceforge.net/
7. http://vex.sourceforge.net/
8. http://phplayersmenu.sourceforge.net/
9. mailto:ipplan@gmail.com
10. http://httpd.apache.org/
11. http://httpd.apache.org/docs/windows.html
12. http://www.appservnetwork.com/
13. http://www.wampserver.com/en/index.php
14. http://www.mysql.com/
15. http://www.postgresql.org/
16. http://www.oracle.com/
17. http://www.php.net/
18. http://www.oreilly.com/catalog/hpmysql/chapter/ch07.pdf
19. http://sourceforge.net/projects/net-snmp
20. http://sourceforge.net/projects/iptrack
21. http://cvs.sourceforge.net/viewcvs.py/iptrack/ipplan/TODO?view=markup
22. http://cvs.sourceforge.net/viewcvs.py/iptrack/ipplan/CHANGELOG?view=markup
23. file://localhost/home/richarde/public_html/iptrackdev/ipplan/screenshots
24. http://www.arin.net/minutes/tutorials/swipit.htm
25. http://www.cisco.com/univercd/cc/td/doc/cisintwk/ito_doc/ospf.htm
26. http://xmlsoft.org/XSLT/
27. http://www.insecure.org/
28. file://localhost/home/richarde/public_html/iptrackdev/ipplan/README.html
29. http://www.rudedog.org/auth_ldap/
30. http://www.ja-sig.org/products/cas/index.html
31. http://www.php.net/bugs.php?id=10924
32. https://sourceforge.net/forum/forum.php?thread_id=627391&forum_id=101033
33. http://iptrack.sourceforge.net/