README.sgml

<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article>

  <articleinfo>

    <title>IPplan - IP address management and tracking</title>

    <revhistory>

      <revision><revnumber>4.81</revnumber><date>2007-01-23</date><authorinitials>re</authorinitials><revremark 
      /></revision>

      <revision><revnumber>2.91</revnumber><date>2002-05-17</date><authorinitials>re</authorinitials><revremark 
      /></revision>

    </revhistory>

    <abstract>

      <para>IPplan is a free (GPL), web based, multilingual, IP address 
      management and tracking tool written in 
      <ulink url="http://www.php.net">php 4</ulink>, 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.</para>

    </abstract>

  </articleinfo>

  <para><ulink url="http://sourceforge.net"/></para>

  <sect1 id="intro">

    <title>Introduction</title>

    <para>IPplan is a web based, multilingual, IP address management 
    and tracking tool based on <ulink url="http://www.php.net">php 
    4</ulink>, simplifying the administration of your IP address space. 
    IPplan can handle a single network or cater for multiple networks 
    with overlapping address space.</para>

    <para>

      Current functionality includes
      <itemizedlist>

        <listitem>

          <para>internationalization</para>

        </listitem>

        <listitem>

          <para>importing network definitions from routing tables</para>

        </listitem>

        <listitem>

          <para>importing definitions from TAB delimited files and 
          <ulink url="http://www.insecure.org">NMAP&apos;s</ulink> XML 
          format</para>

        </listitem>

        <listitem>

          <para>multiple administrators with different access profiles 
          (per group, allowing access per customer, per network 
          etc.)</para>

        </listitem>

        <listitem>

          <para>define address space authority boundaries per 
          group</para>

        </listitem>

        <listitem>

          <para>finding free address space across a range</para>

        </listitem>

        <listitem>

          <para>split and join networks to make them smaller and larger 
          - ip definitions remain intact</para>

        </listitem>

        <listitem>

          <para>display overlapping address space between 
          networks</para>

        </listitem>

        <listitem>

          <para>search capabilities</para>

        </listitem>

        <listitem>

          <para>an audit log - contents before and after change is 
          logged</para>

        </listitem>

        <listitem>

          <para>statistics</para>

        </listitem>

        <listitem>

          <para>keeping track of and sending SWIP/registrar 
          information</para>

        </listitem>

        <listitem>

          <para>DNS administration (forward and reverse zones, import 
          existing zones via zone transfer)</para>

        </listitem>

        <listitem>

          <para>template system to extend IPplan to contain site 
          specific information like circuit data, host configuration 
          data, asset information</para>

        </listitem>

        <listitem>

          <para>device configuration file management</para>

        </listitem>

        <listitem>

          <para>external stylesheet to change display look</para>

        </listitem>

        <listitem>

          <para>triggers - every user event can call a user defined 
          function - useful to execute backend DNS scripts</para>

        </listitem>

        <listitem>

          <para>external poller - scan subnets for active addresses to 
          gather usage statistics</para>

        </listitem>

        <listitem>

          <para>IP address request system - allows users to request 
          static IP addresses from the database</para>

        </listitem>

      </itemizedlist>

    </para>

    <para>Two authentication methods are available - either 
    IPplan&apos;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.</para>

    <sect2 id="copyright">

      <title>Copyright Information</title>

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

      <para>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.</para>

      <para>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.</para>

    </sect2>

    <sect2 id="disclaimer">

      <title>Disclaimer</title>

      <para>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.</para>

      <para>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.</para>

      <para>Naming of particular products or brands should not be seen 
      as endorsements.</para>

      <warning>

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

      </warning>

    </sect2>

    <sect2 id="newversions">

      <title>New Versions</title>

      <para>See the CHANGELOG file for more information.</para>

    </sect2>

    <sect2 id="credits">

      <title>Credits</title>

      <para>Thanks to <ulink url="http://www.vhconsultants.com">
      ValueHunt Inc.</ulink> for the use of their layout class used for 
      rendering all HTML pages.</para>

      <para>Thanks to <ulink url="http://adodb.sourceforge.net/">
      AdoDB</ulink> for the use of their generic database abstraction 
      class.</para>

      <para>Thanks to <ulink url="http://vex.sourceforge.net">
      Vex</ulink> for their Visual Editor for XML used to generate the 
      IPplan documentation.</para>

      <para>Thanks to <ulink url="http://phplayersmenu.sourceforge.net">
      The PHP Layers Menu System</ulink> for their menu system.</para>

    </sect2>

    <sect2 id="feedback">

      <title>Feedback</title>

      <para>Feedback is most certainly welcome for this document. 
      Without your submissions and input, this document wouldn&apos;t 
      exist. Please send your additions, comments and criticisms to the 
      following email address : <email>ipplan@gmail.com</email>.</para>

    </sect2>

    <sect2 id="translations">

      <title>Translations</title>

      <para>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.</para>

      <para>Nickola Kolev for the Bulgarian translation - nikky at 
      mnet.bg.</para>

      <para>Conrado Pinto Rebessi for the Brazillian translation - 
      conradopinto at yahoo.com.br</para>

      <para>Tadashi Jokagi for the Japanese transalation - elf2000 at 
      users.sourceforge.net</para>

      <para>Vladimir Leshchenko for the Russian translation - worker at 
      smtn.stavropol.ru </para>

    </sect2>

  </sect1>

  <sect1 id="requirements">

    <title>Requirements</title>

    <para>IPplan requires a working web server installation. Currently 
    the <ulink url="http://httpd.apache.org">Apache</ulink> 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 
    <ulink url="http://httpd.apache.org/docs/windows.html">
    these</ulink> instructions. Or you can use 
    <ulink url="http://www.appservnetwork.com/">AppServ</ulink> or 
    <ulink url="http://www.wampserver.com/en/index.php">
    WampServer</ulink> 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).</para>

    <sect2 id="databases">

      <title>Databases</title>

      <para>IPplan requires a working database installation. The 
      following databases currently work:</para>

      <itemizedlist>

        <listitem>

          <para><ulink url="http://www.mysql.com">MySQL 3.23.15 or 
          higher</ulink> (preferred)</para>

        </listitem>

        <listitem>

          <para><ulink url="http://www.postgresql.org">PostgreSQL 7.1 
          or higher</ulink></para>

        </listitem>

        <listitem>

          <para><ulink url="http://www.oracle.com">Oracle 9i or 
          higher</ulink> (SQL99)</para>

        </listitem>

        <listitem>

          <para>Microsoft SQL server (both 7 and 2000)</para>

        </listitem>

      </itemizedlist>

      <para>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.</para>

      <para>The web scripting language <ulink url="http://www.php.net">
      php 4.1 or higher</ulink> 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.</para>

      <tip>

        <para>IPplan is also known to work in a distributed, replicated 
        MySQL environment with multiple database servers. See 
        <ulink url="http://www.oreilly.com/catalog/hpmysql/chapter/ch07.pdf">
        www.oreilly.com</ulink> for more information.</para>

      </tip>

    </sect2>

    <sect2 id="addons">

      <title>Additional features</title>

      <para>To enable SNMP support, you will require the 
      <ulink url="http://sourceforge.net/projects/net-snmp">
      ucd-snmp</ulink> 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.</para>

    </sect2>

  </sect1>

  <sect1 id="installation">

    <title>Installation</title>

    <para>Follow the instructions for your platform and database in the 
    INSTALL files in the IPplan directory.</para>

    <sect2 id="custom">

      <title>Customization</title>

      <para>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.</para>

    </sect2>

  </sect1>

  <sect1 id="downloads">

    <title>Downloads, bugs and forums</title>

    <para>You can report bugs, contribute to forums and download it 
    <ulink url="http://sourceforge.net/projects/iptrack">here</ulink> 
    and look at the latest 
    <ulink url="http://cvs.sourceforge.net/viewcvs.py/iptrack/ipplan/TODO?view=markup">
    TODO</ulink> and 
    <ulink url="http://cvs.sourceforge.net/viewcvs.py/iptrack/ipplan/CHANGELOG?view=markup">
    CHANGELOG</ulink>.</para>

    <sect2 id="screenshots">

      <title>Screenshots</title>

      <para>You can find some screen shots <ulink url="screenshots">
      here.</ulink></para>

    </sect2>

  </sect1>

  <sect1 id="modes">

    <title>Mode of operation</title>

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

    <sect2 id="mode-services">

      <title>Services company</title>

      <para>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.</para>

    </sect2>

    <sect2 id="mode-isp">

      <title>ISP</title>

      <para>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 
      <ulink url="http://www.arin.net/minutes/tutorials/swipit.htm">
      tutorial</ulink> for more details). All the relevant 
      SWIP/registrar information is entered when the customer is 
      created.</para>

      <para>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 &quot;free&quot; to allow them to be found using 
      the &quot;Find free&quot; 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.</para>

    </sect2>

  </sect1>

  <sect1 id="concepts">

    <title>Concepts</title>

    <para>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 
    <ulink url="http://www.cisco.com/univercd/cc/td/doc/cisintwk/ito_doc/ospf.htm">
    here</ulink>.</para>

    <sect2 id="deployment">

      <title>Deployment strategy</title>

      <para>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.</para>

      <note>

        <para>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.</para>

      </note>

      <para>To handle challenges like NAT or other overlapping address 
      space, you will be required to create multiple autonomous 
      systems. See &apos;Searching&apos; below how to see information 
      across multiple autonomous systems.</para>

    </sect2>

    <sect2 id="linking">

      <title>Linking addresses</title>

      <para>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 
      &quot;Linked address&quot; field. Once the field is completed, 
      you can follow the link. The link also appears on subnet summary 
      pages.</para>

      <para>You can also link many addresses in one go by choosing 
      multiple addresses in the &quot;Select multiple addresses to do a 
      bulk change&quot; window, then completing the &quot;User&quot; 
      field as follows:</para>

      <programlisting>LNKx.x.x.x userinfo</programlisting>
      <para>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.</para>

      <note>

        <para>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 &quot;Find Next Free&quot; address logic 
        of the subnet that the destination address is used.</para>

      </note>

    </sect2>

  </sect1>

  <sect1 id="admin">

    <title>Administration</title>

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

    <sect2 id="admin-user">

      <title>Admin user</title>

      <para>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.</para>

    </sect2>

    <sect2 id="customer-access">

      <title>Customer access</title>

      <para>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.</para>

      <para>When the subnet is created, the creator will choose a 
      subnet admin group.</para>

    </sect2>

    <sect2 id="subnet-access">

      <title>Subnet access</title>

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

      <para>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.</para>

      <para>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.</para>

      <tip>

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

      </tip>

    </sect2>

    <sect2 id="g-a-b">

      <title>Group authority boundaries</title>

      <para>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.</para>

      <note>

        <para>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.</para>

      </note>

      <tip>

        <para>Bounds are also useful to create users that only have 
        read access to the IPplan information. Select the &quot;Read 
        Only&quot; option when creating a new group.</para>

      </tip>

    </sect2>

  </sect1>

  <sect1 id="circuit">

    <title>Circuit administration, host configuration data and asset 
    information</title>

    <para>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 
    &quot;Templates&quot; for further information.</para>

  </sect1>

  <sect1 id="file">

    <title>Device configuration file management</title>

    <para>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.</para>

  </sect1>

  <sect1>

    <title>DNS administration</title>

    <para>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.</para>

    <para><emphasis>Forward Zones:</emphasis></para>

    <para>To create a forward zone, select a customer and select 
    &quot;Add a DNS zone&quot;. 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.</para>

    <para>At this point you have the option of creating a new zone from 
    scratch, cloning (copying) a zone from an already existing zone 
    called &quot;template.com&quot;, 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.</para>

    <para>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 &quot;Create a new customer/autonomous system&quot;) 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.</para>

    <para>The next step is to add individual records to the newly 
    created zone. Do this under the &quot;Zone DNS records&quot; main 
    menu function. Select the customer, select the domain and add a 
    host. The &quot;Host name&quot; refers to the left hand side of a 
    bind zone file, then the type (A, CNAME or MX - more types in 
    future) and the &quot;IP/Hostname&quot; 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.</para>

    <para>In future this will be automatic with options to &quot;Insert 
    before&quot; and &quot;Insert after&quot;. Currently you can 
    renumber the values retaining the order of the entries.</para>

    <para><emphasis>Reverse zones:</emphasis></para>

    <para>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.</para>

    <para>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 &quot;Export zone&quot; option. The output generated is in 
    XML and must then be parsed using and XSLT processor into a format 
    compatible with your DNS server.</para>

    <sect2 id="export">

      <title>Handling exported zones</title>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

      <para>Sample procedure:</para>

      <para>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:</para>

      <para>

        <programlisting>grep -A 1 &apos;&lt;primary&gt;&apos; /tmp/revzone_FS9mEU|grep -v &apos;&lt;primary&gt;&apos;</programlisting>
      </para>

      <para>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&apos;s and passwords during the 
      copy process.</para>

      <para>Processing the file:</para>

      <para>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 ( 
      <ulink url="http://xmlsoft.org/XSLT/">
      http://xmlsoft.org/XSLT/</ulink>) 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.</para>

      <para>A sample command is:</para>

      <para>

        <programlisting>xsltproc bind9_zone.xsl zone_</programlisting>
      </para>

      <para>For sample XML input of:</para>

      <para>

        <programlisting>&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;zone domain=&quot;test.com&quot;&gt;
&lt;soa serialdate=&quot;20040626&quot; serialnum=&quot;04&quot; ttl=&quot;21600&quot; retry=&quot;3600&quot; refresh=&quot;86400&quot; expire=&quot;604800&quot; minimumttl=&quot;21600&quot; email=&quot;&quot; /&gt;
&lt;record&gt;&lt;NS&gt;&lt;iphostname&gt;ns1.example.com&lt;/iphostname&gt;&lt;/NS&gt;&lt;/record&gt;
&lt;record&gt;&lt;NS&gt;&lt;iphostname&gt;ns2.example.com&lt;/iphostname&gt;&lt;/NS&gt;&lt;/record&gt;
&lt;record&gt;&lt;NS&gt;&lt;iphostname&gt;ns3.example.com&lt;/iphostname&gt;&lt;/NS&gt;&lt;/record&gt;
&lt;record&gt;&lt;NS&gt;&lt;iphostname&gt;ns4.example.com&lt;/iphostname&gt;&lt;/NS&gt;&lt;/record&gt;
&lt;record&gt;&lt;A&gt;&lt;host&gt;myhost&lt;/host&gt;&lt;iphostname&gt;10.10.10.1&lt;/iphostname&gt;&lt;/A&gt;&lt;/record&gt;
&lt;record&gt;&lt;CNAME&gt;&lt;host&gt;myhost-alias&lt;/host&gt;&lt;iphostname&gt;myhost&lt;/iphostname&gt;&lt;/CNAME&gt;&lt;/record&gt;
&lt;record&gt;&lt;MX&gt;&lt;host&gt;&lt;/host&gt;&lt;iphostname&gt;mailhost&lt;/iphostname&gt;&lt;/MX&gt;&lt;/record&gt;
&lt;/zone&gt;</programlisting>
      </para>

      <para>Generating output as follows:</para>

      <para>

        <programlisting>$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</programlisting>
      </para>

    </sect2>

    <sect2 id="individual">

      <title>Automatic updating of zone records</title>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

    </sect2>

  </sect1>

  <sect1 id="registrars">

    <title>Dealing with registrars</title>

    <para>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.</para>

    <para>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 &quot;Templates&quot; 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.</para>

  </sect1>

  <sect1 id="searching">

    <title>Searching</title>

    <para>Creating a special customer called &apos;All&apos; allows 
    searching for information across all the available 
    customer/autonomous systems using the &apos;Display subnet&apos; 
    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.</para>

    <tip>

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

    </tip>

    <tip>

      <para>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).</para>

    </tip>

    <sect2 id="individual">

      <title>Searching for individual address details</title>

      <para>Searching can also be done on individual addresses using 
      the &apos;Match any IP address in subnet&apos; option of the 
      &apos;Display subnet information&apos; 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.</para>

      <para>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 &apos;All&apos; 
      customer you will need to click on the relevant customer network 
      you wish to work with.</para>

    </sect2>

    <sect2 id="areas">

      <title>Searching areas and ranges</title>

      <para>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.</para>

      <para>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.</para>

      <note>

        <para>Areas with no attached ranges will not display in the 
        &quot;Area&quot; selection list until ranges are added to the 
        area. Areas with no ranges yeild no search results.</para>

      </note>

    </sect2>

  </sect1>

  <sect1 id="config">

    <title>Config file</title>

    <para>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.</para>

  </sect1>

  <sect1 id="import-data">

    <title>Importing data</title>

    <para>Data can be imported by the admin user via TAB delimited text 
    files or from output generated in XML format by 
    <ulink url="http://www.insecure.org">NMAP</ulink>.</para>

    <sect2 id="tab">

      <title>TAB delimited data</title>

      <para>Network definitions or individual ip records can be 
      imported in TAB delimited format.</para>

      <para>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.</para>

      <para>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.</para>

      <para>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.</para>

      <epigraph>

        <para>See the templates section for details on how the 
        templates work.</para>

      </epigraph>

    </sect2>

    <sect2 id="nmap">

      <title>Importing using NMAP</title>

      <para>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:</para>

      <programlisting> -sP -oX output.xml</programlisting>
      <para>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.</para>

      <para>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.</para>

    </sect2>

  </sect1>

  <sect1 id="templates">

    <title>Templates</title>

    <para>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.</para>

    <sect2 id="iptemplates">

      <title>Customer, Subnet, DNS and IP address templates</title>

      <para>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.</para>

      <para>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:</para>

      <para><varname>Customer pages - custtemplate.xml</varname></para>

      <para><varname>Subnet pages - basetemplate.xml</varname></para>

      <para><varname>DNS forward zones - 
      fwdzonetemplate.xml</varname></para>

      <para><varname>IP address pages - iptemplate.xml</varname></para>

      <para><varname>IP address pages (network address) - 
      iptemplate-network.xml</varname></para>

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

      <para>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&apos;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.</para>

      <para>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.</para>

      <sect3 id="format">

        <title>Format of Customer, Subnet and IP address template 
        files</title>

        <para>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.</para>

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

        <programlisting>&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;TEMPLATE&gt;
    &lt;FIELD&gt;
     &lt;DEFINITION NAME=&quot;info&quot; DESCRIP=&quot;Additional information&quot; TYPE=&quot;T&quot; MAXLENGTH=&quot;10000&quot; SIZE=&quot;80&quot; ROWS=&quot;10&quot; REGEX=&quot;&quot; ERRMSG=&quot;Invalid field: Additional information&quot; /&gt;
    &lt;/FIELD&gt;
&lt;/TEMPLATE&gt;</programlisting>
        <para>A field definition to add a select drop down list:</para>

        <para>

          <programlisting>    &lt;FIELD&gt;
     &lt;DEFINITION NAME=&quot;select&quot; TYPE=&quot;S&quot; DESCRIP=&quot;This is select list with two options&quot; DEFAULT=&quot;2&quot;&gt;
       &lt;SELECT OPTION=&quot;Option 1&quot; VAL=&quot;1&quot; /&gt;
       &lt;SELECT OPTION=&quot;Option 2&quot; VAL=&quot;2&quot; /&gt;
     &lt;/DEFINITION&gt;
    &lt;/FIELD&gt;</programlisting>
        </para>

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

        <para><varname>NAME</varname></para>

        <para>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.</para>

        <para><varname>DESCRIP</varname></para>

        <para>This is the description that will be displayed above the 
        field.</para>

        <para><varname>TYPE</varname></para>

        <para>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.</para>

        <para><varname>DEFAULT</varname></para>

        <para>The default value for the field the first time the field 
        is completed.</para>

        <para><varname>MAXLENGTH</varname></para>

        <para>This is the maximum number of characters a field can 
        consist of.</para>

        <para><varname>SIZE</varname></para>

        <para>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.</para>

        <para><varname>ROWS</varname></para>

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

        <para><varname>REGEX</varname></para>

        <para>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</para>

        <programlisting>^[a-zA-Z0-9]$</programlisting>
        <para>ensures that the field only contains numbers and letters. 
        See <link>http://regexlib.com/</link> for more on regular 
        expressions.</para>

        <para>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</para>

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

        <programlisting>^[a-zA-Z\/0-9]$|^$</programlisting>
        <para><varname>ERRMSG</varname></para>

        <para>This is the error message that is displayed if the 
        regular expression match fails.</para>

        <para><emphasis>Default template:</emphasis></para>

        <para>The default template contains one field which is the 
        &quot;Additional information&quot; field of older versions of 
        IPplan. If you do not want this field, change the template or 
        delete the template entirely.</para>

        <para><emphasis>Template rules:</emphasis></para>

        <para>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.</para>

        <note>

          <para>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.</para>

        </note>

      </sect3>

    </sect2>

    <sect2 id="registrartemplates">

      <title>Registrar templates</title>

      <para>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</para>

      <programlisting>&lt;xsl:value-of select=&quot;variable&quot;/&gt;</programlisting>
      <para>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.</para>

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

      <para>

        <programlisting>source      -&gt; the REGISTRY config setting
maint       -&gt; the MAINTAINERID config setting
regid       -&gt; the REGID config setting
password    -&gt; the REGPASS config setting
date        -&gt; todays date in UTC format</programlisting>
      </para>

      <para>in addition to the standard customer page variables:</para>

      <para>

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

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

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

      <para>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.</para>

      <para>Thus the following basetemplate.xml file:</para>

      <para>

        <programlisting>&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;TEMPLATE&gt;
    &lt;FIELD&gt;
     &lt;DEFINITION NAME=&quot;remarks&quot; DESCRIP=&quot;Remarks&quot; TYPE=&quot;C&quot; MAXLENGTH=&quot;100&quot; SIZE=&quot;100&quot; ROWS=&quot;1&quot; REGEX=&quot;&quot; ERRMSG=&quot;RIPE remarks&quot; /&gt;
    &lt;/FIELD&gt;
&lt;/TEMPLATE&gt;</programlisting>
      </para>

      <para>will provide the following additional variable to the 
      registrar template</para>

      <para>

        <programlisting>remarks        -&gt; Remarks field for subnet</programlisting>
      </para>

      <note>

        <para>If there are duplicate variable names defined, the 
        variables in the basetemplate.xml file, then the 
        custtemplate.xml file appearing in the &quot;Additional 
        information&quot; section of the customer and subnet 
        administration pages will have precedence over any standard 
        variables.</para>

      </note>

      <para />

    </sect2>

  </sect1>

  <sect1 id="dhcp">

    <title>DHCP</title>

    <para>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 &apos;DHCPRESERVED&apos; 
    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.</para>

    <para>Multiple address pools can be simulated by adding numbers to 
    the end of the IP address decsriptions eg. &apos;Reserved - DHCP 
    pool 1&apos;. Static assignments are dealt with automatically if an 
    IP address has a valid MAC address assigned.</para>

  </sect1>

  <sect1 id="triggers">

    <title>Triggers</title>

    <para>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.</para>

    <para>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.</para>

    <epigraph>

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

    </epigraph>

  </sect1>

  <sect1 id="poller">

    <title>External command line poller</title>

    <para>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.</para>

    <para>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.</para>

    <para>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).</para>

    <para>

      <programlisting>10.10.10.0/24 
10.10.11.* 
10.12.12.1</programlisting>
    </para>

    <para>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.</para>

    <para>You can find the location by typing</para>

    <para>

      <programlisting>which php</programlisting>
    </para>

    <para>Next make sure that nmap can be found. Type</para>

    <para>

      <programlisting>which nmap</programlisting>
    </para>

    <para>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.</para>

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

    <para>

      <programlisting>php -q ipplan-poller.php -d</programlisting>
    </para>

    <para>

      <programlisting>ID      Description
2       Test
46      Test customer
47      Test customer 2</programlisting>
    </para>

    <para>Finally run the poller again with the correct command line 
    (assuming you want to update the customer called &quot;Test 
    customer&quot; which has id 46):</para>

    <para>

      <programlisting>php -q ipplan-poller.php -c 46 -f nmap.list</programlisting>
    </para>

    <para>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 &quot;Pol&quot; column on the IPplan display 
    pages.</para>

    <para>

      <programlisting>D polled today 
W polled within last week 
M last month 
Y last year</programlisting>
    </para>

    <para>You can now add the above line to cron to scan certain 
    subnets periodically.</para>

    <para>The following command line options are available with the 
    poller:</para>

    <para>

      <programlisting>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&apos;s
  -f        filename containing list of subnets to scan, one per line in address/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
</programlisting>
    </para>

    <para>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.</para>

    <note>

      <para>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.</para>

    </note>

  </sect1>

  <sect1>

    <title>IP address request system</title>

    <para>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.</para>

    <para>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.</para>

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

    <para>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.</para>

    <tip>

      <para>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.</para>

    </tip>

    <para>A sample definition for this field is as follows:</para>

    <programlisting>&lt;FIELD&gt;     
 &lt;DEFINITION NAME=&quot;email&quot; DESCRIP=&quot;Email address&quot; TYPE=&quot;C&quot; MAXLENGTH=&quot;100&quot; SIZE=&quot;100&quot; ROWS=&quot;1&quot; DEFAULT=&quot;&quot; REGEX=&quot;&quot; ERRMSG=&quot;Invalid field: Additional information&quot; /&gt;    
&lt;/FIELD&gt;</programlisting>
    <para>See the section on templates for more information.</para>

    <para>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.</para>

  </sect1>

  <sect1>

    <title>Authentication schemes</title>

    <para>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.</para>

    <note>

      <para>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.</para>

    </note>

    <important>

      <para>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.</para>

    </important>

    <para>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.</para>

    <para>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 
    <ulink>http://www.rudedog.org/auth_ldap/1.6/auth_ldap.html</ulink> 
    ensure that the AuthLDAPRemoteUserIsDN is set correctly. You will 
    also need to look at the AuthLDAPGroupAttributeIsDN 
    attribute.</para>

    <para>Read the instructions in config.php carefully for debug 
    tips.</para>

    <para>External authentication was tested against SiteMinder and the 
    Apache <ulink url="http://www.rudedog.org/auth_ldap/">
    auth_ldap</ulink> module. The 
    <ulink url="http://www.ja-sig.org/products/cas/index.html">CAS 
    authentication</ulink> module is also supported - there are special 
    config.php variables to support this configuration.</para>

    <warning>

      <para><emphasis>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.</emphasis></para>

    </warning>

  </sect1>

  <sect1 id="problems">

    <title>Problems</title>

    <itemizedlist>

      <listitem>

        <para>PHP&apos;s IP management functions and binary arithmetic 
        functions are seriously broken (see 
        <ulink url="http://www.php.net/bugs.php?id=10924">bug</ulink> 
        report logged) Due to this limitation, the biggest subnet that 
        can be created is limited to 254k hosts.</para>

      </listitem>

      <listitem>

        <para>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().</para>

      </listitem>

      <listitem>

        <para>SNMP appears to be broken on Redhat 7.2 systems. Try 
        following these 
        <ulink url="https://sourceforge.net/forum/forum.php?thread_id=627391&amp;forum_id=101033">
        instructions</ulink> for help.</para>

      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="limitations">

    <title>Limitations</title>

    <itemizedlist>

      <listitem>

        <para>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.</para>

      </listitem>

      <listitem>

        <para>IPplan can be run with php configured for safe_mode=on 
        and register_globals=off.</para>

      </listitem>

      <listitem>

        <para>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.</para>

      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="faq">

    <title>Questions and Answers (FAQ)</title>

    <para><emphasis>Check the forums on SourceForge 
    too.</emphasis></para>

    <para>The FAQ is no longer maintained in the manual - check online 
    at the <ulink url="http://iptrack.sourceforge.net">IPplan 
    homepage</ulink>.</para>

  </sect1>

</article>