Menu
▾
▴
Perl API
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-cachemgrmust 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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | #!/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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | #!/usr/bin/perl use strict; use warnings; use DBIS::Client; use DBIS::Client::API; use DBIS::Client::Options qw(DBIS_OPT_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:
1 2 3 4 5 6 7 | #!/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].
