How to Setup phpIPAM on Ubuntu 14.04

While it is not essential to have an IPAM server for your home lab we’ve likely all accidentally created duplicate IP address conflicts, especially when I haven’t booted a particular VM in a long time. There are quite a few commercial solutions available, but I wanted to find an open source option. After searching for a while and reading a number of blogs I decided on phpIPAM.

In this post, we will build a single Ubuntu 14.04 server that will host both the phpIPAM application, Apache web server, and MySQL database. In my home lab the Ubuntu VM will run on a VMware ESXi 5.5 host.

Prerequisites

  • VM to serve as the IPAM server, ipam (1 vCPU, 1GB vRAM)
Host FQDN IP Address
ipam ipam.homelab.local 10.1.100.40

Configure IPAM Server Networking

Configure the static IP address that will be used by the IPAM server. I’m using my home lab’s private DNS servers. You’ll want to substitute for your own or you can use Google’s (8.8.8.8 8.8.4.4).

Edit the network interfaces configuration file on the ipam server:

$ sudo vi /etc/network/interfaces

When done editing it should look like:

iface lo inet loopback  
auto lo

# primary network interface
auto eth0  
iface eth0 inet static  
        address 10.1.100.40
        netmask 255.255.255.0
        network 10.1.100.0
        broadcast 10.1.100.255
        gateway 10.1.100.1
        dns-search homelab.local
        dns-nameservers 10.1.100.41 10.1.100.42

Then restart networking:

$ /etc/init.d/networking restart

Install phpIPAM on Ubuntu

Install all of the required packages:

$ sudo apt-get update
$ sudo apt-get -y install apache2 mysql-server php5 php5-gmp php-pear php5-mysql php5-ldap wget

Since MySQL is being installed for the first time you will be prompted to set a password for the MySQL administrative “root” user.

Download the phpIPAM 1.1.010 package:

$ cd /tmp
$ wget http://hivelocity.dl.sourceforge.net/project/phpipam/phpipam-1.1.010.tar

Extract the phpIPAM package into the /ipam sub-directory under the Apache web server root directory:

$ sudo tar -xvf phpipam-1.1.010.tar -C /var/www

Initial Apache Web Server Configuration

By default the Apache installation process creates a default web site (Virtual Host). Since this is not necessary we’ll remove it using the a2dissite companion command that disabled Virtual Hosts by removing the symbolic link from the sites-available to the sites-enabled directories:

$ sudo a2dissite 000-default.conf

phpIPAM uses the Apache Rewrite module, so we’ll make sure it is enabled:

$ sudo a2enmod rewrite

For the changes to take effect we’ll need to restart the Apache web server:

$ service apache2 restart

Create the phpIPAM Virtual Host File

Start by creating a copy of the default Virtual Host installed with Apache to use as a base template:

$ sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/ipam.conf

Open the new file in your editor with root privileges:

$ sudo vim /etc/apache2/sites-available/ipam.conf

We need to modify two directives. The first, called ServerName, establishes the base domain that should match for this virtual host definition. In this example the phpIPAM server’s domain name will be ipam.homelab.local.

ServerName ipam.homelab.local  

The only other thing we need to change for a basic virtual host file is the location of the document root for this domain. We already created the directory we need, so we just need to alter the DocumentRoot directive to reflect the directory we created:

DocumentRoot /var/www/phpipam  

The Virtual Host file should now look like:

<VirtualHost *:80>  
        ServerName ipam.homelab.local
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/phpipam
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>  

Save and close the file.

Similarly to how we used a2dissite to disable an Apache Virtual Host another utility is provided to enable Virtual Hosts called a2ensite. We’ll use this tool to enable the newly created phpIPAM virtual host:

$ sudo a2ensite ipam.conf

Apache needs to be reloaded so that it will re-read its configuration files:

$ sudo service apache2 reload

Complete the phpIPAM Installation

Before we run the phpIPAM installer we need to tell it what database server to connect to, which credentials to use, and what the base URL of the application will be. There is a file called config.php provided with phpIPAM in which you specify these parameters. Edit the file:

$ vim /var/www/phpipam/config.php

By default the file should look like this:

<?php

/*      database connection details
 ******************************/
$db['host'] = "localhost";
$db['user'] = "phpipam";
$db['pass'] = "phpipamadmin";
$db['name'] = "phpipam";

/**
 * php debugging on/off
 *
 * true  = SHOW all php errors
 * false = HIDE all php errors
 ******************************/
$debugging = false;

/**
 *      manual set session name for auth
 *      increases security
 *      optional
 */
$phpsessname = "phpipam";

/**     
 *      BASE definition if phpipam 
 *      is not in root directory (e.g. /phpipam/)
 *
 *  Also change 
 *      RewriteBase / in .htaccess
 ******************************/
define('BASE', "/");

?>

You need to set a MySQL username and password that will be used by the phpIPAM application to access its database tables. For simplicity we’ll leave the username as phpipam and set a more secure password. The MySQL instance in this example runs on the same virtual machine as the phpIPAM application, so we’ll leave it as localhost. We’ll use the default phpipam name for the database.

<?php

/*      database connection details
 ******************************/
$db['host'] = "localhost";
$db['user'] = "phpipam";
$db['pass'] = "mysecurepassword";
$db['name'] = "phpipam";

/**
 * php debugging on/off
 *
 * true  = SHOW all php errors
 * false = HIDE all php errors
 ******************************/
$debugging = false;

/**
 *      manual set session name for auth
 *      increases security
 *      optional
 */
$phpsessname = "phpipam";

/**     
 *      BASE definition if phpipam 
 *      is not in root directory (e.g. /phpipam/)
 *
 *  Also change 
 *      RewriteBase / in .htaccess
 ******************************/
define('BASE', "/");

?>

Note that the BASE definition wasn’t be changed since phpIPAM is installed at the root of the Apache web server (e.g. http://ipam.homelab.local/). If you wanted it to be something like http://server.homelab.local/phpipam/ then you would change the line to define('BASE', "/phpipam/");.

Launch your preferred web browser and connect to the newly created phpIPAM instance. In the case of my home lab it is http://ipam.homelab.local.

You should see the following phpIPAM installation page:

Click the Automatic Database Installation button to allow the phpIPAM installer to create the database automatically.

In the MySQL username field enter root. Enter the password you selected during the MySQL installation process in the MySQL password field.

Click the Install phpipam database button.

After a few seconds you should see the Database installed successfully! message.

Click the Continue button.

On the Postinstallation configuration page enter and confirm the password used by the phpIPAM Admin user. Enter a Site Title and Site URL in the associated fields. In my case I used Homelab IPAM and ipam.homelab.local.

Click the Save settings button.

You should see the Settings updated, installation complete! message.

Click the Proceed to login button.

Enable Database Backups

Regardless of the intended purpose I would highly recommend you enable database backups. It is time consuming to enter IP address management information, so why have to do it more than once. Note that the method below is not that secure since it exposes the phpipam MySQL user password. It is entered in the root user’s crontab file, and in the case of my home lab, there is nothing else running on this Ubuntu server.

Edit the root user’s crontab:

$ sudo crontab -e

Add the following to the end of the crontab file to backup the phpIPAM database table every day and keep only the most recent 10 days:

# Backup IP address table, remove backups older than 10 days
@daily /usr/bin/mysqldump -u phpipam -pmysecurepassword phpipam > /var/www/phpipam/db/bkp/phpipam_bkp_$(date +"\%y\%m\%d").db
@daily /usr/bin/find /var/www/phpipam/db/bkp/ -ctime +10 -exec rm {} \;

Save and exit the file.

Login and Basic Configuration

Enter the “Admin” username and password you selected earlier and click the Login button.

Create a New Section

The first thing I like to do is create a new section to store IPAM information about the home lab network. Navigate to Administration > Sections.

Click the Add Section button.

In my example I’m creating a new section with the following details:

Name: Home Lab
Description: Home Lab Network
Parent: Root
Strict Mode: Yes
Show VLANs: Yes
Show VRFs: No
Subnet ordering: Default
Permissions Guests: na
Operators: rw

Click the Add button.

Create VLANs

Next we’ll create a couple VLANs that will be referenced by subnets in our IPAM database. Navigate to Administration > VLANs.

Start by deleting the two existing VLANs that are configured by default.

Click the Add VLAN button and enter a VLAN number, name, and description.

Click the Add button.

Repeat the process for your remaining VLANs that you want to track in phpIPAM.

Create Subnets

Next, we add subnets for the Home Lab section created earlier.

Navigate to Home Lab > Add Subnet.

Enter the subnet in CIDR format (e.g. 10.1.1.0/24), description, VLAN ID, Master Subnet (use “Root subnet” if you aren’t sure), and select subnet options.

Click the Add button to create the subnet.

Repeat the process for your remaining subnets that you want to track in phpIPAM.

Assign Device Values

The way I like to approach assignment of values to the devices I’m tracking in phpIPAM is to scan the subnets by clicking the button below:

It allows you to enter the details of all the devices that respond to ping requests.

There are a lot of other features and capabilities of phpIPAM including an API that can be used to modify the database, but that is beyond the scope of this post.

Summary

This post walks through setting up phpIPAM on an Ubuntu 14.04 instance including the phpIPAM application, Apache web server, and MySQL database. A few basic configuration options are entered post installation. Check out the phpIPAM site for more information.