Before working with Maintain development there are some simple but essential steps to installing and running Maintain.

This page will help:

1. Install basic LAMP components
2. Set up the server
   • Base System and DHCP/DNS
   • PHP Settings
3. Install Maintain
4. Set up Maintain
   • MySQL Config File Changes
   • Database Setup/Maintain Setup Wizard
5. Automation and Clean-Up
   • Network Changes
   • Cron Setup

Required Components

Maintain was written with these software versions.

This list does not imply Maintain will not run on older software versions, however, use of up-to-date software is highly recommended. Older software versions will not be supported.

Base:

• Apache >= 1.3.29 1
• PHP >= 4.3 2
  • PHP-LDAP >= 4.1.2
  • PHPHTMLLib >= 2.5.4 3
• MySQL >= 4.1 4
• Perl >= 5.6.1 5

DNS:

• djbdns >= 1.05

DHCP:

• ICS dhcpd >= 3.0

Notes
1: Maintain must be able to execute PHP scripts but no abilities unique to Apache are in use. Maintain should run on any other UNIX webserver.
For security reasons, we recommend using Apache-ssl or mod_sal with Apache.

2: Currently Maintain is not compatible with PHP5.

3: If you already have PHPHTMLLib installed, you can link your current version to Maintain. If not, there are Maintain downloads available with PHPHTMLLib built in.

4: While Maintain was developed using MySQL 4.1, it also runs on MySQL 5. If you experience bugs, please report them.

5: Maintain 3.0 and greater are fully written in PHP4, however, some small features may require Perl when activated. If Perl is required, it will be specified in the config file.

Setting up DHCP/DNS and PHP

Base System and DHCP/DNS Server Environments

Maintain is intended to run on and GNU/Linux box regardless of distrobution, it should also run on other Unix systems though they are unsupported.

Install all required software listed in Required Components. Using the distrobution's built in package mannager is highly reccomended (apt-get, yum, portage, etc.). The final goal is to have a standard LAMP(Linux, Apache, MySQL, PHP) system.

Set up a dedicated MySQL database as well as a MySQL user for Maintain with full write access. You will want to enter this connection data in the config files later. Though not necessary, it is reccomended that the database used for Maintain is named 'maintain'. It is the default database name and will make configuration easier.

The DHCP and DNS servers are supposed to have their respective server packages running, however, if you do not need certain services you won't need to provide that server. For example, if you don't need DHCP obviously DHCP doesn't need to be running. You just won't enable it in Maintain.

The DHCP and DNS servers are supposed to have their respective server packages running, however, if you do not need certain services you won't need to provide that server. For example, if you don't need DHCP obviously DHCP doesn't need to be running. You just won't enable it in Maintain.

PHP Settings

Some components in Maintain will need to use more than PHP's default memory limit. If any given script hits the memory limit it will break; with this in mind, Maintain requires at least a 16MB memory limit to run properly.

To change the PHP memory limit become root and edit the php.ini file. It will usually be located in /etc (/etc/php4).

Search for the line:
memory_limit = 8M
Change it to:
memory_limit = 16M

It is also reccomended that magic_quotes_gpc be turned off. While Maintain will run with this option enabled, it can lead to forms populating the screen with garbage values.

Search for the line:
magic_quotes_gpc = on
Change it to:
magic_quotes_gpc = off

Save the file and restart Apache for changes to take effect.

Note Sometimes there are two php.ini files, one for the web interface and one for the command line. If this is the case make these changes in both files.

Installing Maintain

There are several ways of getting Maintain. While it is strongly recommended Maintain be installed completely, nightly SVN snapshots and a subversion checkout are available in the downloads section of the Maintain website.

To download Maintain visit [the Maintain project website] and fetch the newest version.

Go to the directory where you want to install Maintain.

It is strongly discouraged to install Maintain directly into your web server directory (typically /var/www or similar) since that may allow anyone to read important config files.
Instead, extract it to a folder that is READABLE by the web server user (typically "apache" or "www-data"), but not writable. Good installation directories are, for example:
/data/maintain
or
/opt/maintain

Once in the proper directory, extract one of these files:
tar xvzf maintain-$version.tar.gz (for the tar.gz release)
tar xvjf maintain-$version.tar.bz2 (for the tar.bz2 release)

Now make the Maintain directory htdocs available to the web server. The two most common ways to do this are with a symbolic link or with a virtual host.

Symbolic Link
Go into the server root directory (again this will be /var/www or similar) and make a symbolic link to your Maintain htdocs directory. To do this you need to be the super user and the option "FollowSymlinks" is set for your web server directory, otherwise you will not be able to access the link you just created.

ln -s /opt/maintain/htdocs maintain

Note Maintain isn't necessarily located in /opt this directory will be wherever you chose to extract it. The same applies for any command with maintain file paths.

Virtual Host
Another path is creating a virtual host pointing to the htdocs directory so your maintain installation can be reached thorough some arbitrary web location such as http://maintain.something.com.

If you'd like to know more about setting up virtual hosting through Apache check out http://httpd.apache.org/docs/2.0/vhosts/.

Setting Up Maintain

First things first, for the duration of this section the path at which your extraction of Maintain is located will be referred to as $prefix and the physical URL in which Maintain is viewable will be referred to as $web.

Config File Changes

Make the premade config file be active.

cp $prefix/config/maintain.cfg.dist $prefix/config/maintain.cfg

Edit the maintain.cfg file with the following:
Go through and replace all of the capitalized PREFIX and WEB_PATH place holders with their actual values.
Replace the place holder for PHPHTMLLib with the actual path to /phphtmllib.
Enable/Disable relevant database information.

To set a variable as false, just comment out the line with #.
Do not change "methods = mysql", it is a default setting that is required for the initial setup.

Make sure the database link files are accurate. If you used "maintain" as the new database name all relevant default values will be fine. If not execute:

cd $prefix
make db

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

Maintain Setup Wizard

Now Maintain should be available for graphical web setup. Go to the URL assigned to your copy of Maintain and the setup guide should display automatically. Now follow the install script to set up the initial zone and admin user.

1. The installer will use the mySQL connection configuration information provided in the config file prepared in the previous step to setup the initial Maintain database.
   If you didn't setup the config file or have another non 'maintain' database set up, the installer will ask you to set that up now.
2. If you're running an old version of Maintain the installer will migrate the information from the previous install. See $prefix/documentation/MIGRATE for more information.
3. Follow the prompt to create an admin password. Remember to avoid this step on unencrypted public networks to maintain security. If your connection is not encrypted your password will be entered into maintain as plain text.
4. Finally the new empty zone can be created and used.

Note: For more information about zones check out $prefix/documentation/README.design

Setting Automation and Clean-Up

Lastly, some preferences need to be set on the network itself and cron should be set up. At this point we're getting more into general use so start referring to the general use documentation.

For network settings:

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. Then 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. Assign this new range to your zone.

Now you can create hosts in this zone and assign them to the new range and domain for use with Maintain.

For Cron Setup:

1. This will vary slightly by system but setup cron to run

   $prefix/bin/cron.php -p
   

2. Now edit the maintain.cfg file to specify how often you would like it to build the files. You will also need to modify the individual module config files to reflect the build setup.
3. 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.