The Python API is designed to allow DBIS maps to be queried efficiently from within a third party Python program. The API has the following pre-requisites:
dbis-cachemgr
must be running./var/run/dbis/client
).Online documentation is available through pydoc, e.g.
$ python >>> import dbis.client, dbis.client.api >>> help(dbis.client) >>> help(dbis.client.opts) >>> help(dbis.client.api)
By default the data is returned by the API as a list 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 | #!/usr/bin/python import sys import dbis.client import dbis.client.api as dbisapi # Initialise client object client = dbis.client.initialise(fpdebug=sys.stderr) # Lookup entry in NSS format cmdobj = dbisapi.gethostbyname("kilcher") result = client.lookup(cmdobj) print "\n".join(result) |
The output is:
DEBUG: connecting to /var/run/dbis/client 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 Python tuple or dictionary. This can also be achieved, by requesting that the server sends the data to the client in Python pickle format. Note that the data will be unpickled before it is returned from the API:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | #!/usr/bin/python import sys import dbis.client import dbis.client.api as dbisapi import dbis.client.opts as dbisopts # Initialise client object client = dbis.client.initialise(fpdebug=sys.stderr) # Set-up options opts = dbisopts.Options(format=dbisopts.PICKLE) # Lookup full entry cmdobj = dbisapi.gethostbyname("kilcher") result = client.lookup(cmdobj, opts) print result |
The output is:
DEBUG: connecting to /var/run/dbis/client DEBUG: sending command: 'set format=pickle\ngethostbyname kilcher\n' DEBUG: unpickling result (('rn=kilcher,ou=lab,ou=hosts,o=infra', {'objectClass': ['top', 'ipHostObject', 'ipv4HostObject', 'ieee802Device'], 'ipv4Address': ['10.11.12.14'], 'rn': ['kilcher'], '_cfgmap': ['cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'], 'macAddress': ['08:00:27:00:50:f2']}), 1429078281.088914, 900)
The result is a tuple containing a tuple containing a dictionary. The outermost tuple contains:
(LDAP search result, time last updated, TTL)
The LDAP search result is itself a tuple containing:
(DN of entry, dictionary of attributes)
The dictionary of attributes contains the attribute type (key) and a list of values.
If dbisapi.gethostbyname()
were called with no specific key, the entire map will be iterated instead. In this case, if pickle format is requested, the resulting unpickled data structure will differ to that of a single value:
{None: (None, 1429078604.586754, 900), 'kilcher': (('rn=kilcher,ou=lab,ou=hosts,o=infra', {'_cfgmap': ['cn=hosts,en=sales.corp,ou=domain-mappings,o=infra'], 'ipv4Address': ['10.11.12.14'], 'macAddress': ['08:00:27:00:50:f2'], 'objectClass': ['top', 'ipHostObject', 'ipv4HostObject', 'ieee802Device'], 'rn': ['kilcher']}), 1429078604.585119, 900), ... <snip> ... 'www6.aja.com': (('cn=peg6.aja.com,ou=rfc2307,o=infra', {'_cfgmap': ['cn=hosts-legacy,ou=rfc2307,en=sales.corp, ou=domain-mappings,o=infra'], 'bootFile': ['mach'], 'bootParameter': ['root=fs:/nfsroot/peg', 'swap=fs:/nfsswap/peg', 'dump=fs:/nfsdump/peg'], 'cn': ['peg6.aja.com', 'www6.aja.com'], 'ipHostNumber': ['23:0:7:0:1:2:3:4'], 'ipv6Address': ['23:0:7:0:1:2:3:4'], 'macAddress': ['00:00:92:90:ee:e3'], 'objectClass': ['top', 'device', 'ipHost', 'bootableDevice', 'ieee802Device', 'ipHostObject', 'ipv6HostObject'], 'rn': ['peg6.aja.com', 'www6.aja.com']}), 1429078604.585982, 900)}
This is a dictionary, where the key in the dictionary is the key of the entry and the value is the (LDAP search result, time last updated, TTL)
tuple. 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:
$ python >>> import dbis.client.api >>> help(dbis.client.api)
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.opts.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 Python data type (i.e. pickled during transfer) and sorted:
1 2 3 4 5 | #!/usr/bin/python import dbis.client.opts as dbisopts opts = dbisopts.Options(format=dbisopts.PICKLE, sort=True) print opts.get() |
The supported parameters to dbis.client.opts.Options
are summarised in the table below.
Keyword | Value | Description |
---|---|---|
format |
dbisopts.NSS |
Change output format to NSS-style. This is the default output style. |
format |
dbisopts.STR |
Change output format to string representation of Python data type. |
format |
dbisopts.PICKLE |
Change output format to pickled representation of Python data type. The Python API will unpickle the data before returning to the caller. |
format |
dbisopts.STREAM |
Change output format to binary data stream, the format used by the NSS library. |
format |
dbisopts.JSON |
Change output format to JSON. |
getnetgrent_recurse |
True |
Request that a subsequent getnetgrent lookup should recurse member netgroups. |
getnetgrent_recurse |
False |
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 |
True |
Result should be sorted. |
sort |
False |
Result should not be sorted. This is the default. |
There is also online help available:
$ python >>> import dbis.client.opts >>> help(dbis.client.opts)
For more information on the other components of DBIS, see [Using DBIS].