Siptrack API (client) examples

A large goal of siptrack is to be easily scriptable. The 'siptracklib' python client library is included with the siptrack package and is intended to be usable to quickly and easily create python scripts that use data from a siptrack server. The siptrack server can also be communicated with directly via an xmlrpc interface, but that is slightly more complicated.

There are two ways to connect to a siptrack server with siptracklib, siptracklib.fconnect, which uses account/configuration information from the siptrack configuration files, and siptracklib.connect, which takes all connection information as parameters.

import siptracklib
st = siptracklib.connect('stserver.example.com', 'username', 'password', use_ssl = True)

---

st = siptracklib.fconnect()

This will return a connection to a siptrack server that can be used for querying, adding/removing entities etc.

Examples of searching the siptrack server:

>>> st.search('test.example.com', include = ['device'])
[siptracklib.device.Device object at 0xb790ea2c]

>>> st.search('192.168')
[ipv4.Network(16:192.168.0.0/16), ipv4.Network(17:192.168.0.0/24),
 ipv4.Network(83:192.168.0.2/32)]

Viewing entity attributes:

>>> d = st.search('test.example.com', include = ['device'])[0]
>>> [(a.name, a.value) for a in d.attributes]
[('name', 'test.example.com'), ('class', 'server'), ('description', 'Test server.'), ('notes', 'This is a test device.\n\n*Textile* wiki markup can be used in this notes field.')]

Listing a devices networks:

>>> d = st.search('test.example.com', include = ['device'])[0]
>>> d.listNetworks()
[ipv4.Network(83:192.168.0.2/32)]

All objects in the siptrack server are stored in a single tree, shaped something like:

view-tree
    views
        counters
        network trees
            networks
        device trees
            device categories
            devices
user managers

All object types can also have attributes as children. Attributes can be accessed via 'attributes', ie.:

>>> d = st.search('test.example.com', include = ['device'])[0]
>>> d.attributes['name']
'text.example.com'
>>> d.attributes['name'] = 'test2.example.com'
>>> d.attributes['name']
'test2.example.com'

Adding and removing objects is also simple, objects are always added directly onto a parent, ie.:

>>> d = st.search('test.example.com', include = ['device'])[0]
>>> d2 = d.add('device')
>>> d2.attributes['name'] = 'interface-1'
>>> d2.delete()

The exception to this is networks, which must be added to the network tree they belong in, and will be placed correctly in the network tree automatically.

>>> nt = st.search('ipv4', include = ['network tree'])[0]
>>> nt
>>> nt.addNetwork('192.168.1.1/32')
ipv4.Network(9:192.168.1.1/32)

Objects can be associated with the 'associate' method, ie.:

>>> d = st.search('test.example.com', include = ['device'])[0]
>>> n = st.search('192.168.1.1/32', include = ['ipv4 network'])
>>> d.associate(n)
>>> list(d.associations)
[ipv4.Network(9:192.168.1.1/32)]
>>> d.disassociate(n)

The .listChildren() method can be used to list an objects children:

>>> st.view_tree.listChildren()
[siptracklib.user.UserManagerLocal object at 0xb799370c, siptracklib.view.View object at 0xb796ca6c]