Free IPAM solution – 3. Enabling REST

Today we will look at how to enable REST on phpIPAM. This is an essential part when integrating with vRealize Orchestrator, since REST is an excellent interface for automation.

REST might scare you at first, but don’t loose faith, you will soon enough begin to like it, when you vRealize the power it brings.

This is an article in a series or articles, about configuring phpIPAM for automation.

If you want to know more about this, you should read the previous articles.

Previous Articles

Free IPAM solution – 1. Installing phpIPAM

Enable SSL on Apache2 (Self-Signed)

Free IPAM solution – 2. Enabling LDAP Authentication

Otherwise just read on.

All the following step presume that you installed phpIPAM like demonstrated in article one on Ubuntu 16.04

First we need to enable the API in phpIPAM.

Setup

Step 1 – Enable API

Enable API in phpIPAM. This is done under the Administration and the phpIPAM Settings section.

Remember to Save.

Step 2 – Install Prerequisites

You also need to install some modules for this to work.

# Command:

apt-get install php7.0-mcrypt php7.0-curl

Next stop is to Allow Override in Apache. This will enable phpIPAM to rewrite all urls, and that is needed to provide the REST interface.
Edit /etc/apache2/sites-enabled/default-ssl.conf
Add a Directory Section somewhere in the file:

Step 3 – Allow URL Rewrite

# /etc/apache2/sites-enabled/default-ssl.conf

<Directory /var/www/html>
 Options FollowSymLinks
 AllowOverride all
 Order allow,deny
 Allow from all
</Directory>

Restart Apache

# Command:

service apache2 restart

Step 4 – Fix API Bug

Turns out that there is a little problem with phpIPAM, and you can spend a lot of time getting the REST interface working if you do not know this.

You need to edit the api index file: /var/www/html/api/v2/index.php. (Bug report can be found here: Link)

Change file line #174 From:

# /var/www/html/api/v2/index.php
$result = $controller->$_SERVER['REQUEST_METHOD'] ();

To:

# /var/www/html/api/v2/index.php
$result = $controller->{$_SERVER['REQUEST_METHOD']} ();

Step 5 – Setup API

Now setup the API under Administration

You can use whatever you want as you App id. I like to use rest, as it will be part of the URL you use.

Step 6 – Add Service Account

To access phpIPAM we need a service account for our automation, as we do not want it to run as Administrator. No one should use the administrator account really, as this will destroy the audit trail. Make accounts for everyone who need to use the system. Preferably enable LDAP authentication, but only if you have enabled SSL with validated certificates.

To create a local service account for vRealize Orchestrator, which we will setup in a later article, go to Administration -> Users and Create user.

Fill in the relevant data, and click Add:

Now you are done setting up phpIPAM REST API, and it is time to test if it works.

You will find the API documentation very useful: http://phpipam.net/api-documentation/

Test REST API

Step 1 – Install Software

For testing I like to use the postman client. It is available as a app in google chrome webshop.

Step 2 – Authentication

First thing we need to do is authentication. This is done with basic authentication, using username and password. Once authenticated you will get an authentication token you can use for subsequent requests.

According to the documentation authorization request should go to https://fqdn/api/<myapi>/user/ <- This last “/” is important, so do not forget it.

I used rest as my app id, so my url is: https://fqdn/api/rest/user/

Documentation also states that a post should be used to get a token, so my request will look like this:

To test REST and your token do the following:

• set Authorization Type back to No Auth
• Copy the token value from the authorization response
• Go to Headers section
• Remove Authorization header
• Add Token header, and set your token as value

NOTICE: If it does now work, and your are not using validated certificate, the reason might be that you did not visit base URL (https://FQDN/) first in Google Chrome. Go to phpIPAM in google chrome and accept the certificate warning. If this is not done, postman will not work.

Step 3 – Make a request

Lets make a request for sections, to see if it works:

• Change your method to Get
• Change your URL to https://fqdn/api/rest/sections/
• Press Send

Great now REST is working and we can begin to automate.

Next step

Integrate phpIPAM with vRealize Orchestrator. I will post an article about this soon.