When I talked to you - IPAM users, I've heard many times that one of the typical tasks of IP address management is obtaining available IP address(es) for selected subnet. This is tricky if you use spreadsheets and share it with more people (you never know if the doc is in sync and if you won't create IP address conflict).

 

You also voted for similar feature - IP Request Form on Twhack. Where one of the scenarios is ask & approve assignment of first available address in subnet.

 

In this post, I'd like to unveil an IPAM API method that can give you one or more Available IP Address in a subnet.

 

What we need in order to accomplish this trick:

 

  1. IPAM 4.0 (could be an Eval)
  2. Latest version of Orion SDK installed on the IPAM server.
  3. Access to Windows PowerShell (could be applied on Python, Perl or VBScript as well)
  4. User and Password into IPAM
  5. Ten minutes of your time :-)

 

Install and configure your IPAM

Simple start, install and configure your IPAM. It must contain at least one subnet with IP addresses and their statuses inside:

 

Install your Orion SDK

Orion SDK will provide API access to IPAM database via secure methods. I don't expect any single problem during install process (link for download). My recommendation is to install as local Administrator.

If you run into any problem, please speak up in this forum on Thwack.

 

Open your PowerShell window

And now the real fun begins. Run your PowerShell Window and make sure that Orion SDK was successfully registered:

Type this command: Get-PSSnapin | where {$_.Name -eq "SwisSnapin"}) and hit enter key.

The result should looks like this:

 

If you didn't get this, simple type following command (will add PowerShell snappin from SDK)

Add-PSSnapin "SwisSnapin"


Now you have to setup connection to your database/IPAM.

Type in following commands and change your $hostname to domain name or IP address of your IPAM, $username to the username you want to use for connection and $password to your password (like $password = "solarwinds"). If you are using Eval of IPAM and running the script from the same machine, keep it as it is below.


$hostname = "localhost"

$username = "admin"

$password = New-Object System.Security.SecureString  

$cred = New-Object -typename System.Management.Automation.PSCredential -argumentlist $username, $password

$swis = Connect-Swis -host $hostname -cred $cred

 

OK, so we set up the connection, and now we can call an API method and get information about available IP Address. You also need to know the name of the subnet from where you want to get free IP Address. In our example I'll use "DEV" name (see screenshot above). Type in the command below and hit enter key:

 

Get-SwisData $swis 'SELECT TOP 1 I.Status, I.DisplayName FROM IPAM.IPNode I WHERE Status=2 AND I.Subnet.DisplayName = ''DEV'''

 

Et voila:

 

As you may see we got first free available IP Address as 10.140.126.4 with status "2" (Available") which corresponds to my sample IPAM data:

OK so that's good, but I don't assume that you'll want to run such background script every time you want to get your first available IP Address. You can certainly save the whole script into a file and then run it just by simple click (feel free to download my example).

 

The result of the "Get-SwisData" is stored in DataSet - .NET object which you may use for further processing. For example, you can store the results to the file or you can call it from the web service or helpdesk system.

 

If you want to iterate via IP addresses in the result, you may use this powershell query (useful when getting more than 1 free IP address or you want to run the query for more subnets):


$addresses = Get-SwisData $swis 'SELECT TOP 1 I.Status, I.DisplayName FROM IPAM.IPNode I WHERE Status=2 AND I.Subnet.DisplayName = ''DEV'''


foreach($address in $addresses)

{

     write-host "Free IP Address is" $address.DisplayName

}

blogpost foreach.png

We can slightly modify SWQL query and populate subnet address and CIDR next to the available IP Address (by the way, this is the beauty of SWQL language, you don't have to use JOINs in many cases, simply use dot notation in order to list properties of related entity - in this case "Subnet"):

 

$addressesWithSubnets = SELECT R.Address as SubnetAddress, R.CIDR, R.FriendlyName, R.PercentUsed,

(SELECT TOP 1 I2.IpAddress FROM IPAM.IPNode as I2 WHERE I2.Status=2 AND I2.SubnetId = R.GroupID ) AS FreeIpAddress

FROM IPAM.GroupReport as R WHERE R.GroupType='8'

 

Where GroupTyp=8 means type "subnets" (not supernets or DHCP scopes,etc.)


Then the result may look like this:

subnets-script.png

 

I can iterate through the $addressesWithSubnet variable and do whatever I need witch each record, for example send email, send data into help desk, update database (custom property) or store it into a file.

 

The interesting option is create a webservice that can call this IPAM powershell script with attribute "subnet name". Then you can ask for first available IP address from anywhere.

 

Example where simply writing each row to the console output:

list of subnets.png

Download the full script.

 

Example of .NET webservice that can call our PowerShell script:


[WebMethod]

//When calling the method put the path to our script file as parameter to the method GetFreeAvailableAddress.

//For example: c:\script\getFreeIP.ps

//Feel free to add exception handling you prefer.


public void GetFreeAvailableAddress(string script)
{
  
RunspaceConfiguration rC = RunspaceConfiguration.Create();

  
Runspace runspace = RunspaceFactory.CreateRunspace(rC);
   runspace
.Open();

  
RunspaceInvoke scriptInvoker = new RunspaceInvoke(runspace);

  
Pipeline pipelineCommand = runspace.CreatePipeline();
   pipelineCommand
.Commands.AddScript(script);

  
// execute the script
   pipelineCommand
.Invoke();
}

 

Integration with SAM (Server and Application Monitor)

One of the easiest way to get Powershell script monitored by Orion web interface is via SAM (try eval if you don't have it). SAM can monitor powershell scripts and show the results on the web very simply.

 

I had to just re-format the output of my PowerShell script and then define new PowerShell template in SAM so it can transfer the data from script on web.

There is a very nice article about how to add Script Monitor into SAM. So I'll skip this phase and just summarize that what you need to do on your Script side, is populate data you want to show via two specific messages:

Detail Type

Required

Meaning

Statistic

Yes

A numeric value used to determine how the monitor compares to its set thresholds. This must be an integer value, (negative numbers are supported).

Statistic.Name1: 123

Statistic.Name2: 456

Message

No

An error or information message to be displayed in the monitor status details. Note: Multi-line messages are supported. To use this functionality print each line using a separate command. For example:
Message.Name1: abc

Message.Name2: def

and it must end by "Exit(0)" statement.

 

I modified our script in order to produce messages that are parsed properly by SAM (how to add add new SAM template). The template show you percentage used of IP address per subnet and also first free IP Address for each subnet.


Section added


Write-Host "Message.$($freeIP.FriendlyName): Subnet: $($freeIP.SubnetAddress)/$($freeIP.CIDR) named: $($freeIP.FriendlyName) has this available IP  ADDRESS$($freeIP.FreeIPAddress)";   

Write-Host "Statistic.$($freeIP.FriendlyName): $($freeIP.PercentUsed)";

 

Feel free to download SAM template from here. Wondering how the result looks like on the web? Here it goes:

utilization.png

statistics comments.png

 

Let me know if you have any questions and don't be intimidated by our API, it's very easy to use.