in Infrastructure

IPAM: Automated assignment

When I left off last time, our team at CoverMyMeds had decided on phpIPAM as the tool to store our IP address information. That decision was made after evaluating several different alternatives. If you look at that post, there were a list of requirements to be satisfied by any solution we implemented. While not implicitly stated, the ability to assign an IP addresses when provisioning a system is part of the integration required. Managing an IP address from system provision to system decommission is what I’m after.

This installment will cover how I arranged for the beginning of that process, building the system with an IP address that is provided from our IPAM system. More specifically, integrating with the automated system build process, removing the requirement to manually find a free IP address.

My first task was to come up with a way to request an IP from phpIPAM and use it for provisioning a new server. When I create a new VMware virtualized server, I create it by running mkvm.rb. This Ruby application takes a number of arguments, one of which is an IP address. By adding a small plugin to mkvm, I will request the IP needed to build a system from phpIPAM.

phpIPAM provides an API framework that includes some instructions and a few examples. By logging into the phpIPAM webUI using an administrative account, you can configure an API for use with automated requests. Navigate to the administration menu and select ‘API management,’ there you will find a button to ‘create an API key.’

The API examples included with phpIPAM require mcrypt software to encrypt and decrypt requests to the API. I chose not to use mcrypt or encryption for the following reasons:

  • The phpIPAM service we run is not available outside our internal network.
  • The API is not shared with anyone other than our infrastructure team.
  • We run Redhat Enterprise Linux and the PHP package does not include mcrypt.
  • We only allow https connections to web services, providing encryption on the wire.

I decided to use a token and API name for authentication; this allows a certain degree of security without adding complexity.

I began with the command line tool curl to send requests to the API and see what was returned by the examples provided. By following the code used to assign an IP from the phpIPAM webUI and digging into the MySQL database backend, I located the function getFirstAvailableIPAddress that takes a phpIPAM defined subnet as an argument. This research helped me to make use of existing code while designing my API code.

The API code to reserve the first free IP address, getFreeIP.php, is available on our GitHub repository. When calling the API code, we need to pass the following parameters:

  • A name for the API, as described above when we created the API endpoint.
  • API token
  • Subnet
  • Host name

The code will return the first free IP address in the subnet requested and reserve that address in phpIPAM. If the host name is already in phpIPAM, the IP address already assigned to that host name will be returned. Here’s an example using Curl:

Automation is the key to having a reliable and reproducible infrastructure. I should only have to think about the end result and have automation in place to carry out the repetitive tasks. My favorite kind of system administrator or engineer is a lazy one; they automate everything that can be automated removing surprises and mistakes.

Make sure to check back for the next installment when I’ll describe how I use Puppet to configure our BIND servers and keep them up to date.

Write a Comment



  1. Hi, I’m trying to use the API on the latest first version of phpIpam and I’m receiving the following

    Fatal error: Call to undefined function getFirstAvailableIPAddress() in /var/www/phpipam/api/getFreeIP.php on line 79

    Any ideas on how to fix?

    Many Thanks

  2. Just for those reading the article who may use RHEL but allow external repositories, or those using CentOS. The php-mcrypt package is available on the EPEL repository.

  3. Hello,
    My request
    failes with the error
    “Fatal error: Class ‘database’ not found in /data/phpipam/functions/functions-network.php on line 1925”.
    Beneath classes I only found class.PDO.php with class Database_PDO but that one won’t work because function getFirstAvailableIPAddress requires getArray which is not defined in class.PDO.php.
    Where can I find the class “database”?

    • Harry,

      I’ll have to dig into this a bit, my first guess would be to double check version of phpIPAM. Right now we are using the stable branch at github. I’ll try and find some time to dig in further tomorrow.

      After looking this over, you may have an old version of the code. Make sure you are using the stable branch here. In this code the Database function is first defined at Let me know if you still have issues.

      • Doug,

        First I upgraded our ipam implementation to version 1.2 rev1.
        Then I have installed the api-functions as described in
        But the function getFreeIP.php didn’t work because he cannot find the function getFirstAvailableIPAddress. Found this function in het file functions-network.php, installed this file in our ipam-functions-folder (downloaded from, and I added “include_once ‘../functions/functions-network.php’;” to api/getFreeIP.php.
        Now the function getFreeIP.php gives the error “Class ‘database’ not found in /data/phpipam/functions/functions-network.php on line 1925”.

        What can I do get it working?

        Kind regards, Harry

        • I think you may have to use the login functions for the base phpIPAM and not my token authentication. At least that was what happened when another person I work with tried to do something other than my base functions.

  4. Hello,

    Have you found a solution, I have also this error :

    Fatal error: Call to undefined function getFirstAvailableIPAddress() in /var/www/phpipam/api/getFreeIP.php on line 79


    Kind regards, Barry


  • {php}IPAM: The API server module and automating IP address reservation – Deans Blog June 12, 2017

    […] in order to approve the pending request. Now this is where I discovered a number of php scripts by Doug Morris that leverage the API framework. In this scenario, getFreeIP.php provides the functionality to […]