PowerShell – JSON-RPC 2.0 Interaction Connecting SCOM

SCOM is the best monitoring system on this planet but there are also other systems around. You might find yourself in a situation where you need to get some information from the other monitoring system into SCOM. Because there is probably not a supported connector for SCOM available we have to find a way to talk to these systems.

One thing we would have to check if there is an API implemented and how we could probably interact with it. One possible API you will find is JSON-RPC. JSON-RPC is a lightweight remote procedure call protocol which is pretty simple. The general mechanism consists of two peers establishing a data connection. During the lifetime of a connection, peers may invoke methods provided by the other peer. To invoke a remote method, a request is sent. Unless the request is a notification it must be replied to with a response. If you would like to read more about the specification you can find it here.

One monitoring system which has such an API implemented is Zabbix. Zabbix runs on a Linux operating system and can monitor systems like *nix and Windows. For my tests I have downloaded the VHD Zabbix appliance and installed it into a VM on Hyper-V 3.0 which starts immediately. If you need some help and the passwords you will find it here.

Now that we know what JSON-RPC is and what system has such an API implemented we can start playing around. Let’s have a look how a call may look like. Before we can query the system we need to authenticate using a user and password calling a method called user.login…

The result or response is going to look like this…

Notice here the result contains a long string containing numbers and characters. This is the authentication string which we will need in further sessions to call other methods so we don’t have to provide the user and password all the time. As you can see we call a method, submit some parameters (params) and receive a result.

Another request for example to get the users from Zabbix looks like this…

And the response will look like this…

How does this look like if we want to use PowerShell to interact with this API? Tome Tanasovski has published on his blog how to access JSON-RPC using PowerShell. For my example I needed to modify his example and I also wanted to create a script which interacts and returns something meaningful. As a simple example I tried to get the users from Zabbix.

Here the code example:

#URL to JSON-RPC API
$urlJSON = http://192.168.0.203/zabbix/api_jsonrpc.php

#Function to call the JSON-RPC web request
Function CallJSON($url,$object) {
$bytes = [System.Text.Encoding]::ASCII.GetBytes($object)
$web = [System.Net.WebRequest]::Create($url)
$web.Method = “POST”
$web.ContentLength = $bytes.Length
$web.ContentType = “application/json”
$stream = $web.GetRequestStream()
$stream.Write($bytes,0,$bytes.Length)
$stream.close()
$reader = New-Object System.IO.Streamreader -ArgumentList $web.GetResponse().GetResponseStream()
return $reader.ReadToEnd()| ConvertFrom-Json
$reader.Close()
}

#Create authentication JSON object using ConvertTo-JSON
$objAuth = (New-Object PSObject | Add-Member -PassThru NoteProperty jsonrpc ‘2.0’ |
Add-Member -PassThru NoteProperty method ‘user.authenticate’ |
Add-Member -PassThru NoteProperty params @{user=“Admin”;password=“zabbix”} |
Add-Member -PassThru NoteProperty id ‘2’) | ConvertTo-Json

#Call the JSON function with URL and authentication object
$session = CallJSON $urlJSON $objAuth

#$session.result retruns the authentication string which can be used in the next object

#Create the JSON object to call the user.get function and parameter extend
$objUser = (New-Object PSObject | Add-Member -PassThru NoteProperty jsonrpc ‘2.0’ |
Add-Member -PassThru NoteProperty method ‘user.get’ |
Add-Member -PassThru NoteProperty params @{output=“extend”} |
Add-Member -PassThru NoteProperty auth $session.result |
Add-Member -PassThru NoteProperty id ‘2’) | ConvertTo-Json

$user = CallJSON $urlJSON $objUser
$user.result | ft -AutoSize

In example above we need to define the url to the JSON-RPC API. The function takes two parameters the JSON-RPC URL and also the JSON object which has the action / method defined. After the function we create the first JSON object. This object is defined as a custom object in PowerShell and then the appropriate methods and params defined. Notice here the hash table which is being used for the params. This hash table can be extended as you need for your request. Another thing you need to be aware of is the ConvertTo-Json cmdlet which is available and converts the custom object into the appropriate JSON object.

#Create authentication JSON object using ConvertTo-JSON
$objAuth = (New-Object PSObject | Add-Member -PassThru NoteProperty jsonrpc ‘2.0’ |
Add-Member -PassThru NoteProperty method ‘user.authenticate’ |
Add-Member -PassThru NoteProperty params @{user=“Admin”;password=“zabbix”} |
Add-Member -PassThru NoteProperty id ‘2’) | ConvertTo-Json

In the next command we are calling the function CallJSON() and get the output returned in the $session object. The authentication string is in the result property of the $session custom object.

#Call the JSON function with URL and authentication object
$session = CallJSON $urlJSON $objAuth

Now we have the authentication string in $session.result we are going to build our next request which is to get all users created in Zabbix. Therefore we create a new custom object which will be converted into a JSON object using ConvertTo-JSON. This object has the method user.get implemented. Notice in this object I use the $session.result authentication string to authenticate to the server.

#Create the JSON object to call the user.get function and parameter extend
$objUser = (New-Object PSObject | Add-Member -PassThru NoteProperty jsonrpc ‘2.0’ |
Add-Member -PassThru NoteProperty method ‘user.get’ |
Add-Member -PassThru NoteProperty params @{output=“extend”} |
Add-Member -PassThru NoteProperty auth $session.result |
Add-Member -PassThru NoteProperty id ‘2’) | ConvertTo-Json

How do I get this user.get methods? Well you need to check the API documentation of your system to find all the methods and parameters. For my example the user.get method is documented here.

As a last step we just need to call the CallJSON() function again to connect to the server and fire our method against it. The $user object contains in the result object all the user objects. To display those objects a bit more transparent I use format table to display it in a table format.

$user = CallJSON $urlJSON $objUser
$user.result | ft –AutoSize

What you get returned will look like this…

Ok, such a long post and what does this have to do with SCOM? Well think, this is the way you can get all your data you need out of this foreign Linux system in a relatively easy way based on PowerShell. You could build your Orchestrator runbook which will query all the data for example events from Zabbix using the Run .NET activity and then use the Create Alert activity to create the alert in SCOM using the published data from the Run .NET activity. Smells like a homegrown connector ;), cool, huh?

Note: ConvertTo-JSON and ConvertFrom-JSON cmdlets are new in Powershell 3.0. Get more details on TechNet.

Download Example