| Revision History | ||
|---|---|---|
| Revision 4.02 | 2004-11-20 | Revised by: re |
| Revision 3.50 | 2004-10-24 | Revised by: re |
| Revision 3.20 | 2004-06-26 | Revised by: re |
| Revision 3.01 | 2003-05-21 | Revised by: re |
| Revision 3.00 | 2003-04-21 | Revised by: re |
| Revision 2.99 | 2002-12-17 | Revised by: re |
| Revision 2.92 | 2002-07-04 | 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 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.
IPplan is a web based, multilingual, IP address management and tracking tool based on 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 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
display overlapping address space between networks
search capabilities
an audit log
statistics
keeping track of and sending SWIP/registrar information
DNS administration
template system to extend IPplan to contain site specific information like circuit data, host configuration data, asset information
device configuration file management
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.
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.
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.
You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.
Thanks to ValueHunt Inc. for the use of their layout class used for rendering all HTML pages.
Thanks to AdoDB for the use of their generic database abstraction class.
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 : <richarde@users.sourceforge.net>.
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, French - Auto Translation, German - Auto Translation, Italian - Auto Translation, Norwegian - Auto Translation, Portuguese - Auto Translation and Spanish - Auto Translation.
IPplan requires a working web server installation. Currently the 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 these instructions. Or you can use AppServ which is a complete installation package of Apache, MySQL and PHP for Windows - just add IPplan by following the installation instructions in the IPPLAN-WINDOWS file (part of IPPlan).
IPplan requires a working database installation. The following databases currently work:
MySQL 3.23.15 or higher (preferred)
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 php 4.0.4p1 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.
IPplan is also known to work in a distributed, replicated MySQL environment with multiple database servers. See www.oreilly.com for more information.
To enable SNMP support, you will require the 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.
Follow the instructions for your platform and database in the INSTALL files in the IPplan directory.
You can report bugs, contribute to forums and download it here and look at the latest TODO and CHANGELOG.
There are two modes of operation, one can be classified as a services company and the other as an ISP.
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.
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 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.
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 here.
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 that within a customer or autonomous system, no overlaps are allowed. This follows standard IP address rules. 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.
The access control is divided up into three layers and revolves around the creation of groups:
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.
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.
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.
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 it inaccessible.
Bounds are also useful to create users that only have read access to the IPplan information. Create a very restrictive bound for the group the user belongs to outside your normal address space.
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.
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.
The DNS functions are still BETA and this section will be updated in future.
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. 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 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 should be automatic with options to "Insert before" and "Insert after". Error checking must also be improved.
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 them be parsed using and XSLT processor into a format compatible with your DNS server. See the DNS-USAGE file for more information.
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.
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.
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).
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.
A couple of setting 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.
Data can be imported via TAB delimited text files or from output generated in XML format by 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 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.
Templates for sending information to registrars should be well formed XML stylesheets. See the existing templates in the /ipplan/templates directory for examples and which variables are available. Currently only the xsl:value-of select="variable"/ tag is understood and all other tags are stripped. This is to prevent requiring the XSLT php library. In future XML stylesheets will be supported in full.
The administrator can define a custom template in IPplan to allow the addition of as many custom fields to the ip address records as desired. This functionality allows flexibility in the way data is added to the database. Some uses for this include tracking asset information or WAN circuit information.
Format:
The template is a well formed XML file called iptemplate.xml and should be stored in the /ipplan/users directory. A sample template called iptemplate.xml.sample can be found in this directory.
A second template file called iptemplate-network.xml can also be defined. If this template file exists, different fields can be defined for the first or network address of a subnet. This template can then be used to store things like VLAN numbers, router information and the like. If the iptemplate-network.xml does not exist, then the iptemplate.xml template will be used for network addresses.
The template file must be surrounded with <TEMPLATE> statements. Note that XML tags are case sensitive and must match as per the example. Each field is contained in a <FIELD></FIELD> statement. Each field must have exactly one <DEFINITION> line. Any line with an error will be silently ignore! The following are valid for a definition:
NAMEThis is the field name used internally to track the names of the variables. Can contain letters and numbers only - no spaces or anything else.
DESCRIPThis is the description that will be displayed above the field.
TYPEThis is the type of the field - two type are defined. C for a character field and T for a memo or multi-line field.
MAXLENGTHThis is the maximum number of characters a field can consist of
SIZEThis 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
ROWSThis is the number of rows to display on the screen - only valid for text or multi-line fields.
REGEXThis 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]$|^$
ERRMSGThis 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.
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.
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. Do not place an equivalent file in the admin subdirectory as the admin account cannot be overridden.
Note that the relevant users requiring access to IPplan must still be created via the admin interface, but no password information is required as this is taken care of by the external authenticator. If the user is removed from the external authenticators database, the user will no longer be able to log in to IPplan even if the account still exists. This scheme only handles single signon and password changes, not single point of administration.
External authentication was tested against SiteMinder and the Apache auth_ldap module.
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.
PHP's IP management functions and binary arithmetic functions are seriously broken (see bug report logged) Due to this limitation, the biggest subnet that can be created is limited to 64k.
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 instructions for help.
Note that you cannot place the IPplan directory behind your own .htaccess authentication method as this interferes with IPplan authentication. An alternate method would be to limit access to the part of the web tree where IPplan is installed using the Apache directory allow and deny attributes in the httpd.conf file.
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.
Check the forums on SourceForge too.
This is a collection of the most common questions people have had.
Q: I need to authenticate every page accessed.
A: The realm authentication method used sometimes has problems with broken web browsers (especially the MS variety!). This manifests itself by prompting to authenticate for every page opened. To correct the problem, use a newer version of your browser or better yet, change to something that works like Netscape or Mozilla. There are also issues with browsers that remember passwords - if you have problems, turn this feature off.
Q: I cannot find my data anymore - it has vanished!
A: The access method has changed preventing all user from seeing everything in IPplan. The default is now for users to only see customer info for which they are part of a group that has access to the customer. The user can see everything for all customers if the IPplan administrator makes the user part of a group that can see everything.
Q: Why is IPplan so damn ugly!
A: For two reasons. Firstly if was designed to be functional and not pretty. My time is limited and as any programmer knows, most time is spent on the user interface. I am also no user interface guru. Secondly, nobody has contributed any code to make IPplan look better. If you want it to look better, either help out or go and buy a multi-million $ IP address management system.
A: Internet Explorer does not render HTML pages correctly. Simple things like borders around table cells are ignored (frame=void rules=none border=0). This can be seen on the page headings which look ugly. Your solution would be to get a working browser.
Q: Why is IPplan so damn difficult to learn!
A: Hey, I think it is rather easy and makes perfect sense to me, but then I wrote it! If you find things confusing, either ask in the forums on SourceForge (see elsewhere in the manual), or supply CONSTRUCTIVE tips on how to make it better.
Q: I get messages about "Fatal error: Call to undefined function: pg_connect()" or some other database driver error.
A: This is a php installation issue and has nothing to do with IPplan. Your chosen database driver is not installed/compiled into your copy of php. This is totally dependent on your installation of php and the operating system you are running on. Head over to http://www.php.net and have a look at the php FAQ for answers.
A: This is now tested for in the installation script - make sure that you run the installation script as per the INSTALL and UPGRADE files whenever you make changes to IPplan.
Q: Can I search for which customer uses a particular IP address?
A: Yes. Use the "Display subnet information" search, fill in the IP address into the "Partial subnet address" field, select "Match any IP address in subnet". If you want to search all the customers, you need to create the "all" customer - see elsewhere in the manual how to do that.
Q: I am having trouble uploading large files - "Document contains no data" and other errors.
This can be one of many things, but most likely a configuration setting on the webserver. With Apache (especially on Redhat systems), make sure that you adjust the LimitRequestBody setting in the httpd.conf file - the default setting is 524288 bytes on Redhat systems. This setting can usually be found in /etc/httpd/conf.d/php.conf on late release Redhat systems. Look in the Apache error log for additional hints to the problem and also the PHP manual
You will also need to modify the php.ini settings of post_max_size and upload_max_filesize too.