Perl API modified by Mark R. Bannister

Mark R. Bannister — Wed, 11 Nov 2015 12:00:18 -0000

--- v2
+++ v3
@@ -7,6 +7,14 @@

 * `dbis-cachemgr` must be running.
 * Perl program must have permission to connect to DBIS client socket (default is `/var/run/dbis/client`).
+
+Online documentation is available through `perldoc`, e.g.
+
+~~~~
+$ perldoc DBIS::Client
+$ perldoc DBIS::Client::Options
+$ perldoc DBIS::Client::API
+~~~~

 By default the data is returned by the API as an array of strings in short format.  Here is a simple example that looks up a single host entry:

Perl API modified by Mark R. Bannister

Mark R. Bannister — Wed, 11 Nov 2015 11:52:18 -0000

--- v1
+++ v2
@@ -45,7 +45,6 @@
 use DBIS::Client;
 use DBIS::Client::API;
 use DBIS::Client::Options qw(DBIS_OPT_JSON);
-use JSON;

 # Initialise client object
 my $client = DBIS::Client->new(fpdebug => 1);

Perl API modified by Mark R. Bannister

Mark R. Bannister — Thu, 16 Apr 2015 06:26:35 -0000

Perl API

Introduction

The Perl API is designed to allow DBIS maps to be queried efficiently from within a third party Perl program. The API has the following pre-requisites:

dbis-cachemgr must be running.
Perl program must have permission to connect to DBIS client socket (default is /var/run/dbis/client).

By default the data is returned by the API as an array of strings in short format. Here is a simple example that looks up a single host entry:

#!/usr/bin/perl
use strict;
use warnings;

use DBIS::Client;
use DBIS::Client::API;

# Initialise client object
my $client = DBIS::Client->new(fpdebug => 1);

# Lookup entry in NSS format
my $cmdobj = DBIS::Client::API->gethostbyname("kilcher");
my $result = $client->lookup($cmdobj);
print join("\n", @$result) . "\n";

The output is:

PERL DEBUG: connecting to "/var/run/dbis/client"
PERL DEBUG: sending command: "gethostbyname kilcher\n"
10.11.12.14     kilcher

This output is good for display purposes, but not so good for parsing. If the data is to be parsed, it would be better represented as a Perl array or hash. This can also be achieved, by requesting that the server sends the data to the client in JSON format. Note that the data will be decoded before it is returned from the API:

#!/usr/bin/perl
use strict;
use warnings;

use DBIS::Client;
use DBIS::Client::API;
use DBIS::Client::Options qw(DBIS_OPT_JSON);
use JSON;

# Initialise client object
my $client = DBIS::Client->new(fpdebug => 1);

# Set-up options
my $opts = DBIS::Client::Options->new(format => DBIS_OPT_JSON);

# Lookup full entry
my $cmdobj = DBIS::Client::API->gethostbyname("kilcher");
my $result = $client->lookup($cmdobj, opts => $opts);

use Data::Dumper;
print Dumper($result);

The output is:

PERL DEBUG: connecting to "/var/run/dbis/client"
PERL DEBUG: sending command: "set format=json\ngethostbyname kilcher\n"
PERL DEBUG: decoding JSON
$VAR1 = [
          [
            'rn=kilcher,ou=lab,ou=hosts,o=infra',
            {
              '_cfgmap' => [
                             'cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'
                           ],
              'macAddress' => [
                                '08:00:27:00:50:f2'
                              ],
              'ipv4Address' => [
                                 '10.11.12.14'
                               ],
              'rn' => [
                        'kilcher'
                      ],
              'objectClass' => [
                                 'top',
                                 'ipHostObject',
                                 'ipv4HostObject',
                                 'ieee802Device'
                               ]
            }
          ],
          '1429114785.19419',
          900
        ];

The result is an array containing an array containing a hash. The outermost array contains:

[LDAP search result, time last updated, TTL]

The LDAP search result is itself an array containing:

[DN of entry, dictionary of attributes]

The dictionary of attributes contains the attribute type (key) and a list of values.

If DBIS::Client::API->gethostbyname() were called with no specific key, the entire map will be iterated instead. In this case, if JSON format is requested, the resulting decoded data structure will differ to that of a single value:

PERL DEBUG: connecting to "/var/run/dbis/client"
PERL DEBUG: sending command: "set format=json\ngethostbyname *\n"
PERL DEBUG: decoding JSON
$VAR1 = {
          'None' => [
                      undef,
                      '1429115018.40274',
                      900
                    ],
          'www.aja.com' => [
                             [
                               'cn=peg.aja.com,ou=rfc2307,o=infra',
                               {
                                 '_cfgmap' => [
                                                'cn=hosts-legacy,ou=rfc2307,en=sales.corp,ou=domain-mappings,o=infra'
                                              ],
                                 'bootParameter' => [
                                                      'root=fs:/nfsroot/peg',
                                                      'swap=fs:/nfsswap/peg',
                                                      'dump=fs:/nfsdump/peg'
                                                    ],
                                 'macAddress' => [
                                                   '00:00:92:90:ee:e2'
                                                 ],
                                 'ipv4Address' => [
                                                    '23.0.7.1'
                                                  ],
                                 'cn' => [
                                           'peg.aja.com',
                                           'www.aja.com'
                                         ],
                                 'rn' => [
                                           'peg.aja.com',
                                           'www.aja.com'
                                         ],
                                 'bootFile' => [
                                                 'mach'
                                               ],
                                 'ipHostNumber' => [
                                                     '23.0.7.1'
                                                   ],
                                 'objectClass' => [
                                                    'top',
                                                    'device',
                                                    'ipHost',
                                                    'bootableDevice',
                                                    'ieee802Device',
                                                    'ipv4HostObject',
                                                    'ipHostObject'
                                                  ]
                               }
                             ],
                             '1429115018.40191',
                             900
                           ],
... <snip> ...
          'peg.aja.com' => [
                             [
                               'cn=peg.aja.com,ou=rfc2307,o=infra',
                               {
                                 '_cfgmap' => [
                                                'cn=hosts-legacy,ou=rfc2307,en=sales.corp,ou=domain-mappings,o=infra'
                                              ],
                                 'bootParameter' => [
                                                      'root=fs:/nfsroot/peg',
                                                      'swap=fs:/nfsswap/peg',
                                                      'dump=fs:/nfsdump/peg'
                                                    ],
                                 'macAddress' => [
                                                   '00:00:92:90:ee:e2'
                                                 ],
                                 'ipv4Address' => [
                                                    '23.0.7.1'
                                                  ],
                                 'cn' => [
                                           'peg.aja.com',
                                           'www.aja.com'
                                         ],
                                 'rn' => [
                                           'peg.aja.com',
                                           'www.aja.com'
                                         ],
                                 'bootFile' => [
                                                 'mach'
                                               ],
                                 'ipHostNumber' => [
                                                     '23.0.7.1'
                                                   ],
                                 'objectClass' => [
                                                    'top',
                                                    'device',
                                                    'ipHost',
                                                    'bootableDevice',
                                                    'ieee802Device',
                                                    'ipv4HostObject',
                                                    'ipHostObject'
                                                  ]
                               }
                             ],
                             '1429115018.40191',
                             900
                           ]
        };

This is a hash, where the key in the hash is the key of the entry and the value is the [LDAP search result, time last updated, TTL] array. The None entry represents when the entire map was last updated, i.e. the last time someone iterated through every entry in the map.

There are multiple methods per map. To obtain a full list of available methods and their supported parameters, run:

$ perldoc DBIS::Client::API

Server control messages

It is possible to modify the data that the dbis-cachemgr server sends back to the client. This is achieved using options that are passed through by the DBIS::Client::lookup() method to the server socket.

These messages are set-up in a DBIS::Client::Options object that is passed to the opts parameter to DBIS::Client::initialise() or DBIS::Client::lookup(). For example, to request that the result should be returned as a Perl data type (i.e. JSON format during transfer) and sorted:

#!/usr/bin/perl
use strict;
use warnings;

use DBIS::Client::Options qw(DBIS_OPT_JSON);
my $opts = DBIS::Client::Options->new(format => DBIS_OPT_JSON, sort => 1);
print $opts->get() . "\n";

The supported parameters to DBIS::Client::Options->new() are summarised in the table below.

Keyword	Value	Description
`format`	`DBIS_OPT_NSS`	Change output format to NSS-style. This is the default output style.
`format`	`DBIS_OPT_STR`	Change output format to string representation of Python data type.
`format`	`DBIS_OPT_JSON`	Change output format to JSON. The Perl API will decode the data before returning to the caller.
`format`	`DBIS_OPT_JSON_RAW`	Return raw JSON output.
`format`	`DBIS_OPT_PICKLE`	Change output format to pickled representation of Python data type. Data is returned in this format. This is used primarily by the test suite (written in Python) when it is testing the Perl API.
`format`	`DBIS_OPT_STREAM`	Change output format to binary data stream, the format used by the NSS library.
`getnetgrent_recurse`	`1`	Request that a subsequent `getnetgrent` lookup should recurse member netgroups.
`getnetgrent_recurse`	`0`	Request that a subsequent `getnetgrent` lookup should not recurse member netgroups, i.e. netgroup members will be listed by netgroup name. This is the default.
`sort`	`1`	Result should be sorted.
`sort`	`0`	Result should not be sorted. This is the default.

There is also online help available:

$ perldoc DBIS::Client::Options

For more information on the other components of DBIS, see [Using DBIS].

Recent changes to Perl API

Perl API modified by Mark R. Bannister

Perl API modified by Mark R. Bannister

Perl API modified by Mark R. Bannister

Perl API

Introduction

Server control messages