[Maintain-dev] The revised file

Edward Lim limed at onid.orst.edu
Wed Jan 31 13:30:15 PST 2007

Here is the revised file
-------------- next part --------------
---------				  Maintain -- INSTALL					 ---------	 

Installing Maintain:

    This document is intended to get you up and running with Maintain.

    It is also available on the Maintain website, along with more docu-
    mentation and some web links to make your necessary system adjustments
    as easy as possible.


0. Understanding Maintain:

    For information on what Maintain is designed to do, it's highly 
    recommended that you read README.design in the documentation directory
    or on the Maintain website before installing to get an idea of the 
    high-level design of Maintain and how to best leverage it in your 

    Another valuable resource is the whole Maintain community website,
    available under:



1. Required Components:

	Maintain was developed with the following software versions.

    This list does not imply that Maintain won't work under any circumstances
    with software versions less than the ones mentioned. However, running
    Maintain on up-to-date software versions is strongly recommended, and
    older versions than the ones written here are not supported.

		Apache      >=  1.3.29  http://www.apache.org           [1]
		PHP		    >=  4.3     http://www.php.net              [2]
		MySQL       >=  4.1     http://www.mysql.com            [3]
		PHP-LDAP    >=  4.1.2   http://www.php.net
		Perl        >=  5.6.1   http://www.perl.com             [4]
        PHPHTMLLib  >=  2.5.4   http://phphtmllib.newsblob.com/ [5]
		djbdns      >=  1.05    http://cr.yp.to/djbdns.html
		ICS dhcpd   >=  3.0     http://www.isc.org/sw/dhcp/

    [1] Maintain needs a web server capable of executing PHP scripts. But since
    no special abilities of Apache are used, it should also run on any other
    UNIX web server. Please let us know of your success when running it on
    different setups. (You can add something to the user forums on the Maintain

    For security reasons, We recommend use of Apache-ssl or mod_ssl with Apache 
    rather than just plain Apache.
    [2] Currently, Maintain is not compatible with PHP5.
    [3] Maintain was mostly developed on MySQL 4.1, however it also runs on 
    MySQL 5. If you experience any bugs with new versions of MySQL, please let
    us know.
    [4] Since version 3.0, Maintain is fully written in PHP4. However, there
    are small, optional features that require Perl when activated. If you
    want to use them, please make sure you have installed Perl on your Maintain
    box. (When Perl is required, it is mentioned in the respective config file)

    [5] If you have PHPHTMLLib installed, you can link Maintain to your current
    version. If not, there are Maintain downloads available that contain a copy
    of PHPHTMLLib for your convenience.


2. Set up your servers.

2.1 Base System and DHCP/DNS Server Environments

    Maintain is intended to run on GNU/Linux servers. Any flavor/distribution
    should be alright. Even other Unixes (like BSD) might work, but are
    currently unsupported.

    Please make sure that the software versions mentioned above are installed
    on your server(s). For your convenience, we recommend installing the 
    software packages with the package management system provided by your
    Linux distribution (e.g. apt-get, yum, portage etc.).

    The server which Maintain should run on is supposed to have all the tools
    running that are mentioned under "Base" above. Generally spoken, this is
    a regular "LAMP" (Linux, Apache, MySQL, PHP) system.

    Please have a dedicated (empty) MySQL database up and running and a MySQL
    user that has full write access to this database. You will need to enter
    the connection data into the config files later.

    It is recommended to call the database used by Maintain 'maintain'.
    If the default database name is used, configuration will be easier later.

    The DHCP and DNS servers are supposed to have the respective server
    packages running. If you do not need DHCP, for example, you obviously do
    not have to provide that server either. You just won't enable it in 

2.2 PHP Settings

    Some components in Maintain can use more memory than PHP's default memory 
    limit. In case the scripts hit the limit, they will break.
    Therefore, Maintain requires at least a 16 MB memory limit to function

    To do so, become root and edit the file php.ini, which is usually in the
    directory /etc (or /etc/php4 or similar).

    Search for the line:

        memory_limit = 8M      ; Maximum amount of memory a script may consume

    and change it to:

        memory_limit = 16M     ; Maximum amount of memory a script may consume

    It is also recommended that you verify that the magic_quotes_gpc option
    is turned off.  Though having this option on will not hurt Maintain, it
    can lead to forms populating values with excessesive slashes in them to
    the screen.

    Search for the line:

        magic_quotes_gpc = On

    If you choose to deactive this option you will only need to change the
    the word On to Off like so:

        magic_quotes_gpc = Off

    Save the file and restart your webserver (Apache) afterwards.

    Note:   Some linux distributions have two php.ini files, one for the web
            interface and another one for the command line interface.
            In this case, change the setting in both of them.


3. Getting Maintain

    There are several ways to get an instance of Maintain. We highly recommend
    to install a Maintain release, however there are also nightly SVN snapshots
    and a subversion checkout available.

    If you just extracted Maintain and are reading this file in the install
    directory, you may go on with step 4.

3.1. Downloading a Maintain Release

    This is the recommended way of obtaining Maintain:

    Go to the website (maintainproject.osuosl.org), go to the download area
    and fetch the newest release version of Maintain.

3.2. Downloading a Nightly Snapshot

    On the Maintain website, there are also nightly snapshots of the develop-
    ment tree available.

    You may download and extract them just as described in section 3.1 for
    the official releases.

    It is not recommended to run nightly snapshots on production systems.
    Nightly builds may break at any time or do other unintended things and 
    should therefore only be used for development purposes.

3.3. Using the SVN tree

    Maintain is developed in a Subversion revision control environment. 
    You can download, play around with, and modify the whole Maintain source 

    However, we strongly discourage using SVN snapshots in a production 

    Even "worse" than nightly snapshots, SVN checkouts may break at any time,
    do strange things to your system and/or database, or arbitrarily invite
    a family of manatees to a dinner party at your house.

    Therefore, the SVN process is only described in the Maintain hacking

    For more information on hacking Maintain, read the HACKING document in
    the documentation and/or visit the Maintain website.


4. Installing Maintain

    Go to the desired directory where you want to install Maintain.

    Note that it is STRONGLY discouraged to have Maintain lying in your 
    webserver directory (typically /var/www or similar), since people might 
    be able to read important config files otherwise.

    Instead, extract it to a folder that is READABLE by the web server user
    (typically "apache" or "www-data"), but not writable. A good installation
    directory is for example:

        /data/maintain or

    Then extract the file:

        tar xvzf maintain-$version.tar.gz   (for the tar.gz release) or:
        tar xvjf maintain-$version.tar.bz2  (for the tar.bz2 release)
    Afterwards, make the $maintain/htdocs directory available for your web
    server. There are at least two ways to do this:

    1) Symbolic link
    Go into your web server root directory (typically /var/www or similar)
    and make a symbolic link to your Maintain htdocs directory:

        ln -s /opt/maintain/htdocs maintain

    You want to make sure that the option "FollowSymlinks" is set for your
    web server directory, otherwise you will not be able to access the link
    you just created.

    2) Virtual Host
    You may also set up a virtual host pointing to the htdocs directory, so
    that your instance of Maintain can be reached by accessing


    or similar. Setting up virtual hosts is beyond the scope of this document,
    but for Apache, this is a good place to start:

5. Setting Up Maintain

    Now it is time to set up Maintain. You have to edit a few options in the
    main config file before you can run the Maintain installer.

5.0 Descriptions
    $prefix == Location where you extracted maintain
    $web_path == URL of maintain

5.1 Setting up Config Options
    1) Copy $prefix/maintain.cfg.dist to

    2) Edit $prefix/maintain.cfg and configure Maintain.
    The least parts you have to edit are:
    - the prefix and web_path variables
    - the path to your instance of PHPHTMLLib
    - the database information
    To set a variable as false comment it out with a #.
    For the initial setup you must have [Auth] "methods = mysql",
    which is the default.

5.2 Creating the Database Link Files
    If your (empty) maintain database has the name 'maintain', you can skip
    this step.

    Otherwise execute the 'create tables' script as follows

        cd $prefix
        make db

    The script creates the database link scripts needed for Maintain to connect
    to your database. No error messages should occur.

5.3 Setup Wizard

    1) Open a web-browser and go to $web_path, where the Maintain installer
    will welcome you.
    Please follow the instructions given by the installer script to set up
    an initial zone and admin user.
    a) The installer will use the mysql connection information you provided
       in the config file to prepare the initial Maintain database.
       If you skipped step 5.2 but have a database name different than
       'maintain', the installer will ask you to run that step now.
    b) If you had an older version of Maintain running, the Installer script
       will help you to migrate. Please refer to the according documentation 
       in $prefix/documentation/MIGRATE.

    c) The installer will ask you to create an admin password. Keep in mind not
       to do the setup unencryptedly over a public network, if possible, 
       because then your web browser will send the admin password to Maintain 
       in clear text. Maintain encryptedly stores the password afterwards.

    d) At last, you will be asked to make an initial, empty zone to start off
       with. For the concept of zones, refer to documentation/README.design.

6. First Network Setup

    * See the general use documentation for more information *

    1) Go to the Admin section and create a new IP Block for your
       IP space.  Make sure it's enabled.

    2) Create the first subnet within the bound of your IP Block.
       Assign any DHCP options to this subnet (router & subnet mask)

    3) Create a Master Domain. 
    4) Edit the zone created during setup and add this new domain
       as an allowed domain.

    5) Create a new range that fits inside your subnet.
    6) Assign this new range to your zone. 

    You should now be able to create hosts in this zone and assign them to the
    new range and domain. 


7. Cron Setup

    1) This will depend on your system, setup cron to run
           $prefix/bin/build/all -p
       however often you would like it to build the files. Make sure you edit 

       as well as the individual module config files to reflect the build 

    2) Set up the build modules to perform the "push" step for you (i.e.
       copying the config files to your target servers) or copy them to the
       right destination manually.


8. Installing Maintain on a debian based system

	1) From the above we know that we need Apache, MySQL, PHP4 for maintain to work
	   the following is the name of the packages required for a Debian based system
	   Optional package:
	2) All of these packages can be installed using the apt-get command
			apt-get install  <package name>	
	3) The rest of the install is the same as the above in the documentation. So you can
	   refer above for more information on how to setup maintain.
-------------- next part --------------
Coding Standards for Maintain
Daniel I. Robert <robert at osuosl.org>
1.0, 1 August 2005

Scope and Purpose
In any large, open-source application, coding practices between developers
differ, sometimes wildly.  In an effort to keep Maintain consistent, the project
maintainers have put together criteria that they expect outside contributors to
adhere to.

Who Should Read This Document
All patch submissions, modules, and skins are subject to these guidelines.  The
project managers may reject a code submission purely on the basis that it does
not comply with the guidelines laid out in this document.  Some existing code
in Maintain may not strictly comply due to legacy reasons, and will likely be
changed in future releases.  Consider this a "do as we say and not as we do"
coding standards document.

Source Tree
Please consult the documentation regarding the source code layout to guide you
on where your code belongs in the tree and how to properly lay it out.  Since
Maintain 3.0, there has been a rigid structure defining the proper layout of
code within the source tree.

Text/Code Format
Visible in the xref:header[next section] is the typesetting standards used in
the Maintain source tree.  *Do not use tabs!*  Tabs should be replaced by four
space characters.  The relevant vim settings are given below.  For more
information on this, please see the
coding standards] page.

The following header should be included on all files that are non-trivial.
Documents such as includes or constants definitions do not need such a header
(use of such a header in these documents is, in fact, discouraged).

/* vim: set expandtab tabstop=4 shiftwidth=4 foldmethod=marker: */
// $HeadURL$
// +------------------------------------------------------------------------+
// | Maintain - DNS/DHCP Managment Tool                                     |
// +------------------------------------------------------------------------+
// | Copyright (c) 2005 Open Source University                              |
// +------------------------------------------------------------------------+
// | This program is free software; you can redistribute it and/or          |
// | modify it under the terms of the GNU General Public License            |
// | as published by the Free Software Foundation; either version 2         |
// | of the License, or (at your option) any later version.                 |
// |                                                                        |
// | This program is distributed in the hope that it will be useful,        |
// | but WITHOUT ANY WARRANTY; without even the implied warranty of         |
// | GNU General Public License for more details.                           |
// |                                                                        |
// | You should have received a copy of the GNU General Public License      |
// | along with this program; if not, write to the Free Software            |
// | Foundation, Inc., 59 Temple Place - Suite 330,                         |
// | Boston, MA  02111-1307, USA.                                           |
// +------------------------------------------------------------------------+
// | Author(s): Foobar Johnson <johnsonf at example.com>                       |
// +------------------------------------------------------------------------+
// $Id$

Maintain 3.0 now uses phpDocumentor (phpdoc) for API documentation.  All
classes in Maintain are required to use phpdoc for clarity and to assist other
programmers.  More information on phpDocumentor can be found
link:http://www.phpdoc.org/[at http://www.phpdoc.org/].

phpDocumentor Standards
The page-level docblock for a file should look something as follows (for a file
containing nothing more than a class and some requires)
  * filename.php - defines the {@link classname} class
  * @author author name or $Author$
  * @filesource
  * @package    packagename
  * @subpackage subpackagename
Where 'filename'.php refers to the name of this particular file, and
'classname' is the class defined within it.  The rest of this page block is
literal.  Even though the doc-block for the class should define its own package
and, optionally, subpackage), the page-level docblock should define it as well.
Users with commit rights should leave the @author value as '$Author$', while
independant contributors are encouraged to enter their own names in there, lest
it be overwritten by the committers name.

The Maintain 3.0 API is split into distinct packages and subpackages that
roughtly follow the directory structure.  The hierarchy looks something as
follows (all names are strictly lower-cased):

- bin
- build
- classes
*   auth
*   dao
*   htdocs
*   ui
- htdocs
*   datalists
*   forms
- includes
- modules
*   subpackage for each module
- skins
*   subpackage for each skin

Non-API Documentation
Non-API documentation (such as this document) are written in the AsciiDoc
format.  Maintain has chosen AsciiDoc for its pre-generated readability and
ease of use.  Many Linux distros, such as Debian, have Asciidoc packages
available.  Any non-phpdoc documentation present in a skin, module, etc.,
should be written in this format if possible, and given a `.txt` extension.


Maintain strives to comply with  
link:http://pear.php.net/manual/en/standards.php[PEAR coding standards].

Although Maintain 3.0 is a PHP4 application, the code is becoming increasingly
object-oriented.  As such, we are using nerdyCaps for long variable, method,
and class names.  PHP files containing classes should be cased in the Java
style, i.e. a file containing the class `myClass` should be named `MyClass.php`

The Maintain team does *NOT* believe in the concept of 'self-documenting code'.
Every hacker has written "self-documenting code" only to look back on it a few
weeks later and wonder what on earth they were trying to do.  We hope all
incoming code is clean, well indented, and takes advantage of whitespace, but
the Maintain team insists on actual comments (and comment blocks as needed)
throughout the code base.  Please do not submit any code that is undocumented.


During working hours, we are typically reachable in IRC on the freenode network
in #maintain .  To track svn commits, we have a bot set up in #osuosl-commits
that displays real-time commits for all of the Oregon State's Open Source Lab's
projects.  There is a general mailing list of Maintain discussions.  Please
sign up at

More information about the Maintain-dev mailing list