Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Perl JSON-RPC Client Binding

# Pre-Requirements

The JSON-RPC Perl bindings require the following Perl packages:

- LWP::Protocol::https
- LWP::UserAgent
- HTTP::Request::Common
- URI::Split
- JSON
- JSON::RPC::Common::Marshal::HTTP
- Error
- Data::Dumper
- parent

## Linux

In dnf-based Linux distributions the following command will install the required packages:

dnf install "perl(LWP::Protocol::https)" "perl(LWP::UserAgent)" \
"perl(HTTP::Request::Common)" "perl(URI::Split)" \
"perl(JSON)" "perl(JSON::RPC::Common::Marshal::HTTP)" \
"perl(Error)" "perl(Data::Dumper)" "perl(parent)"

## Windows

There are various Perl distributions available for Windows (see http://perl.org/get.html). The bindings were tested with ActiveState Perl (http://www.activestate.com/activeperl/downloads). After installing ActiveState Perl, the required modules can be installed with the following command:

ppm install LWP::Protocol::https LWP::UserAgent HTTP::Request::Common \
URI::Split JSON JSON::RPC::Common::Marshal::HTTP \
Error Data::Dumper parent

# Authentication

In examples below, replace `my_user` and `my_pass` with Default Credentials of your product, or your own credentials.

# SSL Certificate Verification

All Xerus devices enforce use of HTTPS when accessing the JSON-RPC service. By default, programs written with this client binding try to verify the authenticity of the server when connecting. This requires a valid SSL certificate to be installed on the device. When trying to connect to a device without a valid SSL certificate the client program will terminate with an error message.

It is possible to disable the SSL certificate verification by setting the 4th parameter of `XerusKvm::RPC::Agent()` to `1`.

Code:

my $agent = new XerusKvm::RPC::Agent($url, "my_user", "my_pass", 1)

# Examples

## Configuring the SNMP agent:

use XerusKvm::RPC;
my $agent = new XerusKvm::RPC::Agent('https://my-xerus.example.com', 'my_user', 'my_pass');
my $snmp_proxy = $agent->createProxy('/snmp');
my $config = $snmp_proxy->getConfiguration();
$config->{v2enable} = 0;
$config->{readComm} = 'public';
$config->{writeComm} = 'private';
$snmp_proxy->setConfiguration($config);

# IDL-to-Perl Mapping

## IDL Modules and Perl Package Names

All classes dealing with Xerus™ JSON-RPC communication are located in Perl packages starting with `XerusKvm::RPC`. All named sections in IDL files (`module`, `interface` and `enumeration`) provide a scope for their included identifiers and are added as further components to the Perl package name.

## Interfaces and Methods

IDL interfaces are mapped to Perl proxy classes which provide all methods defined by the IDL interface and its bases. Perl methods require the same number of scalar arguments as defined in the IDL signature. Simple types like integers, strings or enumerations are passed by scalar value; structures, vectors and maps are passed by reference. Output parameters are passed as references to a scalar variable which will be modified to point to the returned value. If the method is declared to have a non-void return type the Perl method will return a single scalar value.

Examples:

# no parameters, no return value
$firmware->reboot();
# two input parameters, integer return value
$ret = $user_manager->createAccount('newuser', 'newpassword');
# one output parameter, integer return value
my $results;
$ret = $diagnostics->listTcpConnections(\$results);

## Structures

IDL structures are mapped as scalar references to Perl hashes. Each element of the structure results in a hash entry whose key is the element identifier and whose value is a Perl scalar. When passing a structure to a method call, additional hash entries are ignored.

Example:

$ssh_settings = {
'allowPasswordAuth' => 1,
'allowPublicKeyAuth' => 0
};
$security->setSSHSettings($ssh_settings);

## Enumerations

Enumerated values are referenced by their fully-qualified name:

my $diag = $agent->createProxy('/diag');
$diag->setLogLevelForAllCtxNames(XerusKvm::RPC::diag::DiagLogSettings::LogLevel::LOG_LEVEL_WARN);

## Vectors

Vectors are mapped as scalar references to Perl lists. Each list entry must be a scalar.

$recipients = [ 'somebody@invalid.com', 'somebody.else@invalid.com' ];
$smtp->testConfiguration($cfg, $recipients);

## Maps

Maps are mapped as scalar references to Perl hashes:

my $dispatcher = $agent->createProxy('/serial');
my $ports = $dispatcher->getPorts();
while (my ($key, $port) = each %$ports) {
print "$key => $port\n";
}

# Exceptions

In case of error conditions during a proxy method call or the `createProxy` function, exceptions will be thrown. They can be caught using the `try` statement from the `Error` Perl module.

The following exceptions are defined:

- `XerusKvm::RPC::HttpException`

  An error occurred during HTTP communication, e.g. in case the connection was refused or the authentication failed. Please check the agent URL, the resource ID and your authentication credentials.

- `XerusKvm::RPC::JsonRpcSyntaxException`

  The response from the server was not a valid JSON object. Please check the agent URL and the resource ID.

- `XerusKvm::RPC::JsonRpcErrorException`

  The method call failed. This should not happen under normal circumstances and indicates a problem on the device.

Example for catching an exception:

use XerusKvm::RPC;
use Error qw(:try);
try {
print "Querying firmware version ... ";
my $agent = new XerusKvm::RPC::Agent('https://my-xerus.example.com', 'my_user', 'my_pass');
my $firmware_proxy = $agent->createProxy('/firmware');
my $version = $firmware_proxy->getVersion();
print "Success\n";
print "Firmware version: $version\n";
} catch XerusKvm::RPC::HttpException with {
my $e = shift;
print "ERROR: ", $e;
};

# XerusKvm::RPC::Agent Method Reference

## Constructor: new XerusKvm::RPC::Agent($url, $user, $password, $no_cert_check)

Creates a new agent.

Parameters:

- $url Base URL of the device (e.g. "https://my-xerus.example.com")
- $user Username (optional, use `undef` to skip to next parameter)
- $password Password (optional, use `undef` to skip to next parameter)
- $no_cert_check Set to `1` to disable TLS certificate check (optional)

If username or password are omitted, it is necessary to call either `set_auth_basic()` or `set_auth_token()` before the first request.

## set_auth_basic($user, $password)

This method enables HTTP basic authentication using username and password.

Parameters:

- $user User Name
- $password Password

## set_auth_token($token)

This method enables HTTP authentication using a session token. A session token can be obtained by calling the `newSession` method of the `session.SessionManager` interface.

Parameters:

- $token Session Token

## timeout($seconds)

Returns the current timeout and optionally sets a new request timeout.

Parameters:

- $seconds New timeout in seconds (optional)

Returns:

- Previous timeout in seconds

## createProxy($rid, $basetype)

Creates a new proxy object for the given resource ID.

This method will query the type information for the specified resource ID and create a proxy object which provides all methods defined in the IDL definition.

Parameters:

- $rid The resource ID, e.g. "/auth/user/my_user"
- $basetype The base type, e.g. "usermgmt.User" (optional)

Returns:

- A new proxy object for the specified resource ID

## set_verbose($verbose)

Enables request tracing. When verbose mode is enabled all JSON-RPC requests and responses will be echoed to the console.

Parameters:

- $verbose `1` to enable verbose mode