Creating new address in a subnet using {php}IPAM REST API

In previous posts I have discussed phpIPAM which is an open-source IP address management application (IPAM). In this blog, I will discuss interacting with the REST API (version 2.0) to programatically create new IP addresses for a specific subnet.

For the purpose of this article, I will be using the Postman REST client to submit requests and interact with the API and the following variables reference values you will need to replace for your environment if you are replicating the process:

Variable Description Example
{appId} API application identifier dean
{subnet} Subnet in CIDR format
{subnetId} Id of subnet address 3

In order to use the API you will need to authenticate (required for none and SSL) with the username and password and use the HTTP authentication header.

If authentication is successful, you will receive the token to include in the token header for subsequent requests to the API. Also, you will receive the expiry of the token which is set to six hours by default. For each subsequent request to the API the expiration time for the token is reset.

POST api/{appId}/user/

By specifying the authorization type as ‘Basic Authentication’ and specifying a username and password this will generate the required Authorization header for the request by encoding the values to a base64 encoded string.


A status code of ‘200’ will be returned if the authentication attempt is successful, the required token value will also be returned in the response body with the expiration date.

  "code": 200,
  "success": true,
  "data": {
    "token": ".Cy9kljLjG=WIt9i.gmA%tUY",
    "expires": "2016-12-03 13:13:06"
  "time": 5.036

Once the token has been received the cool stuff can now begin and we can start to interact with the API. In the next example, I am going to use a common use case for phpIPAM. I need to request the next available free IP address for a specified subnet and allocate this to a host.

So, lets look at the method we need to use to create a new address from a specified subnet from the addresses section of the documentation

POST  /api/{appId}/addresses/first_free/{subnetId}/

An alternative GET method exists, however whilst this will return the next available IP address it will not create the object for the new IP address in the database.

GET /api/{appId}/addresses/first_free/subnet

From the POST method we need to provide the Id of the subnet we require to create an IP address, therefore prior to invoking the request we need to return this value, by referencing the subnets section of the documentation, the following can be used by providing the subnet in CIDR format.

GET /api/{appId}/subnets/cidr/{subnet}/

In this example I am searching for the subnet containing the CIDR format From the below response body we can retrieve the subnet Id from the data[0].id element and in this example, the subnet Id for the subnet is ‘3’. As you can see from the headers section, I am now specifying the ‘token’ header previously returned from the successful authorization.


  "code": 200,
  "success": true,
  "data": [
      "id": "3",
      "subnet": "",
      "mask": "24",
      "sectionId": "1",
      "description": "Customer 1",
      "linked_subnet": null,
      "firewallAddressObject": null,
      "vrfId": "0",
      "masterSubnetId": "2",
      "allowRequests": "1",
      "vlanId": "0",
      "showName": "1",
      "device": "0",
      "permissions": "{\"3\":\"1\",\"2\":\"2\"}",
      "pingSubnet": "0",
      "discoverSubnet": "0",
      "DNSrecursive": "0",
      "DNSrecords": "0",
      "nameserverId": "0",
      "scanAgent": null,
      "isFolder": "0",
      "isFull": "0",
      "tag": "2",
      "threshold": "0",
      "location": null,
      "editDate": null,
      "links": [
          "rel": "self",
          "href": "/api/dean/subnets/3/"
  "time": 0.002

Now, lets return to creating a new address in the specified subnet with the below request to create a new address in the subnet from the POST method. From the response body, the data element contains the IP address ‘’ created for the subnet.

POST  /api/{appId}/addresses/first_free/3/


  "code": 201,
  "success": true,
  "message": "Address created",
  "id": "34",
  "data": "",
  "time": 0.015

We can also include a request body in the POST method to include information for creating the new IP address in the subnet. The supported parameters are listed for the address controller in the addresses section. In this example, I have included the hostname, description and owner values for the request.


As you can see if you have read the provided API documentation, I am only touching the surface of what is possible by programmatically interacting with the API and how you can leverage this in your automation and orchestration practices.

{php}IPAM: The API server module and automating IP address reservation

I have recently provided articles in regards to the installation and configuration of {php}IPAM IP. One of my use cases for investigating the use of IP address management systems was to provide a API/server module to request an IP address for allocation.

By default, a module is provided to request an IP address by browsing to Administration > IPAM settings > Feature Settings  and enabling the ‘IP request module’.


However, this requires user interaction 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 retrieve the first available IP address for a subnet. In addition the following scripts are available from the repository:

getIPs.php – dump information for a subnet.
removeHost.php – removes IP address information from a subnet for a host.
tokenValid.php – validates API token for requests. ​

In order to  retrieve the first available IP address for a subnet we will also require to validate the API token for the request so we will also need the tokenValid.php file as well. The files should be placed in the ‘/var/www/phpipam/api’ directory.

cd /tmp 
git clone
cd /tmp/api
cp getFreeIP.php tokenValid.php /var/www/phpipam/api

In order to submit a request to the API we need to browse to Administration > IPAM Settings > Feature Settings and enable the API server module. Then browse to Administration > IPAM Settings > API Management to create an API key to which you will specify an application identifier and for this use case set ‘Read’ application permissions.



In order for the API server module to provide data to client requests the php curl and mcrypt extensions are required to be installed, the mcrypt extension enabled and a restart of the Apache Web Server to apply.

sudo apt-get install php5-curl php5-mcrypt
sudo php5enmod mcrypt
sudo service apache2 restart

Now we have enabled API server module, created the API key and placed the script files on the host. We can now send an HTTPS request which requires the following information:

Application Identifier
Application Code

The request will return the first free IP address in for the subnet and reserve the IP address. If an IP address has already been reserved for the hostname, this will be returned. In this example I am submitting a request to reserve an IP address for the hostname ‘server1.dean.local’ in the subnet ‘’ and specifying the owner as ‘deangrant’

curl https://ipam.dean.local/api/getFreeIP.php?apiapp=dean&apitoken=30c13f9d33668a5e13e79a5865dc409f&subnet=

{php}IPAM: Configuring auto discovery and host status checks

So you have configured your IP related settings in {php}IPAM such as sections, subnets and VLANs and invoked the initial scan of your subnet to discover new hosts. Now, we go away and at some point later on login and check your subnet details to which all your hosts are reporting as unreachable.

What is happening here? Don’t worry, by default {php}IPAM will not periodically scan the subnet(s) for discovery and status updates. The installation of {php}IPAM provides a number of scripts to which two of them can perform this function. In order to discover new hosts there is discoveryCheck.php and to obtain the current host status pingCheck.php, which are located at the below locations.


So simply, all we are required to do is create a cron job to schedule the invocation of this script. In my example I will trigger the scripts every 15 minutes.

*/15 * * * * /usr/bin/php /var/www/phpipam/functions/scripts/discoveryCheck.php
*/15 * * * * /usr/bin/php /var/www/phpipam/functions/scripts/pingCheck.php​

There is a prerequiste required for the above, you will need to ensure that each subnet(s) you want to scan has the ‘check hosts status’ and ‘discover new hosts’ enabled in the subnet properties. For validation purposes I would recommend invoking the above scripts manually to ensure you receive expected behaviour.

sudo /usr/bin/php /var/www/phpipam/functions/scripts/discoveryCheck.php
sudo /usr/bin/php /var/www/phpipam/functions/scripts/pingCheck.php​

{php}IPAM: Installation and Configuration on Ubuntu

I was recently evaluating IP address management systems to which I did seem to find a favourite in {php}IPAM which is an open source IP address management system, this is a PHP based application with MySQL database management using jQuery libraries, ajax and some HTML5/CSS3 features. The features list is quite rich and whilst not detailing them in full, satisfied my criteria of functional requirements of providing API and IP request modules in addition to the standard feature set we should look for in an IP address management system.

One of the goals of {php}IPAM is to provide a light IP address management system, and therefore in most use cases all components of the LAMP architecture can be deployed on a single host, in my case this would be Ubuntu 14.04 LTS.

Before installing and configuring {php}IPAM there is a requirement to install the the required packages for the LAMP architecture (Apache, MySQL, PHP) to run the {php]IPAM application. If your are installing a new instance of MySQL you will be prompted to set the password credential for the ‘root’ user during installation.

In my use case I will be leveraging the API module, which also requires the php extensions curl (php5-curl) and mycrypt (php-mcrypt).

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

Now we will need to the download package from the repository, and extract this to the Apache Web Server root directory.

cd /tmp
sudo tar -xvf phpipam- -C /var/www

By default, during installation of Apache, this will create a default web site, we will remove the symbolic link from thefrom sites-available to the sites-enabled directory and then enable the rewrite module and restart the Apache Web Server (apache2) service to apply changes.

sudo a2dissite 000-default.conf
sudo a2enmod rewrite
service apache2 restart 

Now we will create the {php}IPAM virtual host file (/etc/apache2/sites-available/ipam.conf) using a text editor and configure as per the below example. In this example, I will be optionally enabling the SSL engine and specifying the paths to the SSL certificate file, private key and the certificate chain file.

<VirtualHost *:443>
    ServerName ipam.dean.local
     SSLEngine on
     SSLCertificateFile /etc/apache2/ssl/ipam.dean.local.crt
     SSLCertificateKeyFile /etc/apache2/ssl/ipam.dean.local.key
     SSLCertificateChainFile /etc/apache2/ssl/ipam.dean.local.chainfile.crt
     ServerAdmin serveradmin@dean.local
     DocumentRoot /var/www/phpipam
     ErrorLog ${APACHE_LOG_DIR}/error.log
     CustomLog ${APACHE_LOG_DIR}/access.log combined

Once the virtual host file has been created we will enable the site, enable the Apache SSL module and reload Apache to apply the configuration.

sudo a2enmod ssl 
sudo a2ensite ipam.conf
service apache2 restart 

Now we will configure the {php}IPAM database management system, which in this case is MySQL for the connection string, as all the components for the LAMP architecture are installed on a single host we can specify the hostname as ‘localhost’ and set a password for the user ‘phpipam’ to authenticate to the database ‘phpipam’.

$db['host'] = "localhost";
$db['user'] = "phpipam";
$db['pass'] = "enterasecurepassword";
$db['name'] = "phpipam";​

By browsing to the URL, in this example https://ipam.dean.local we may now initialise the {php}IPAM instance from the installation page select ‘Automatic Database Installation’ which will now create the phpipam MySQL database by supplying the MySQL root user credentials. The final step now is to set a site title and URL (you may choose to complete this at a later time), once these settings have been saved the installation is now complete and the {php}IPAM web application is available to accept connections and configure.

For those you still manage allocation of IP addresses by the use of spreadsheet, maybe it time to think about deploying an IP address management system (does not have to be {php}IPAM!), the above steps show {php}IPAM is simple to install and configure, if you have looked through the feature list provides a rich functionality and is an open-source project and through the extended API and IP request modules can integrate with your existing automation/continuous delivery implementations.

The headache of managing IP address allocation (or in fact most things!) in a spreadsheet reminds me of a comment made by Scott Bollinger ‘When the process is manually updating a spreadsheet you’ve already lost.’