packetlogic2.pld.pld

Add a dynamic netobject item

Please note that netobject will not be verified with regard to
performance and flexibility when adding to a uncommitted
netobject.

        >>> rt.dyn.add(31682, '127.0.0.1')

@type id: C{int}
@param id: the id number of the netobject to add the item to.

@type ip: C{str}
@param ip: the IP address to add.

@type subscriber: C{str}
@param subscriber: Subscriber name - or empty string to not create subscriber.

@type is_subscriber: C{bool}
@param is_subscriber: is subscriber property - used for subscriber count in statistics.

@type linkspeed_in: C{int}
@param linkspeed_in: linkspeed_in property - used in statistics.

@type linkspeed_out: C{int}
@param linkspeed_out: linkspeed_out property - used in statistics.

@type natcfg: C{str}
@param natcfg: natcfg property - used to config subscribers NAT. Requires v14.0 firmware or newer.

@type properties: C{dict}
@param properties: Dict of properties. Requires v15.1 firmware of newer.
              properties is a dict which may
              contain zero or more of the keys
              rt.dyn.SUBSCRIBER_NAME,
              rt.dyn.IS_SUBSCRIBER,
              rt.dyn.LINKSPEED_IN,
              rt.dyn.LINKSPEED_OUT,
              rt.dyn.NATCFG,
              rt.dyn.USERDATA{1-8}

@raises PLDPermissionError: If the user lacks permission for requested action
@raises PLDServerError: If server reported an error
@raises ValueError: If an invalid IP address is used

List dynamic netobject items.

>>> rt.dyn.list(netobject=300, recurse=True, properties=[rt.dyn.SUBSCRIBER_NAME])
[('10.0.0.2',
  [(339L, [{1: 'User0001'}]),
   (337L, [{1: 'User0001'}])]),
 ('10.0.0.3',
  [(339L, [{1: 'User0002'}]),
   (335L, [{1: 'User0002'}])])]

Remove a dynamic netobject item

>>> rt.dyn.remove(31682, '127.0.0.1')

Removes all orphan dynamic netobject items. An orphan dynamic netobject item is a dynamic netobject item created in a netobject that no longer exists. For example:

>>> rs=pl.Ruleset()
>>> rt=pl.Realtime()
>>> o=rs.object_add("/NetObjects/example")
>>> rs.commit()
>>> # Wait for plrcd to read up the commit

>>> rt.dyn.add(o.id, '127.0.0.1', "subscriber")
True
>>> rs.object_remove(o)
>>> rs.commit()
>>> # Wait for plrcd to read up the commit

>>> rt.dyn.remove_orphans()
1L

Note that created/removed object will not appear/disappear until the change has been committed. Be warned that the following might remove wanted dynamic netobject items:

>>> rs=pl.Ruleset()
>>> rt=pl.Realtime()
>>> o=rs.object_add("/NetObjects/example2")
>>> rt.dyn.add(o.id, '127.0.0.2', "subscriber2")
True
>>> rt.dyn.remove_orphans()
1L

In this example the newly added dynamic netobject item '127.0.0.2' will be removed by remove_orphan() as the parent netobject was not yet committed.

Set multiple dynamic netobject items under a base netobject.

        >>> rt.dyn.set(300, "10.0.0.4", [(339, {rt.dyn.SUBSCRIBER_NAME: 'User0003', rt.dyn.IS_SUBSCRIBER: True}),
        ...                              (337, {rt.dyn.SUBSCRIBER_NAME:'User0003', rt.dyn.IS_SUBSCRIBER: True})])
        >>> rt.dyn.set(300, "10.0.0.3", [])

This function replaces all dynamic netobject items
that exists for the specified ip address in the
netobject tree under the specified base netobject id.

@type baseno: C{int}
@param baseno: the id number of the netobject to operate under.

@type ip: C{str}
@param ip: the ip number to set items for.

@type items: C{sequence} of C{tuples}
@param items: the items to add, each item should be a
              tuple of (netobjectid, properties),
              where properties is a dict which may
              contain zero or more of the keys
              rt.dyn.SUBSCRIBER_NAME,
              rt.dyn.IS_SUBSCRIBER,
              rt.dyn.LINKSPEED_IN,
              rt.dyn.LINKSPEED_OUT
              rt.dyn.NATCFG
              rt.dyn.USERDATA{1-8}

@raises PLDPermissionError: If the user lacks permission for requested action
@raises PLDUnsupportedInFirmware: If firmware doesn't support this function.
@raises PLDServerError: If server reported an error

Starts a session of following set() operations under a base netobject.

When zero or more set() have been performed and set_end() is called, all dynamic netobject items under the baseno NetObject that were not set by any set() will be removed.

Performing a series of set() operations between a pair of set_begin() and set_end() will make sure that all dynamic netobject items under the baseno NetObject will be exactly defined by the of set() operations.

Note that a new set_begin() can not be issued until the corresponding closing set_end() has been performed.

Also note that all following set() operations must have the same baseno NetObject id as the one provided in set_begin().

Ends a session of set() operations, started by set_begin(), under a base netobject.

When zero or more set() have been performed and set_end() is called all dynamic netobject items under the baseno NetObject that were not set by any set() operation will be removed.

Performing a series of set() operations between a pair of set_begin() and set_end() will make sure that all dynamic NetObject items under the baseno NetObject will be exactly defined by the series of dyn_set() operations.

Find index of key.

Remove a key from the key vault.

Set a key in the key vault to the specified string.

• key must not contain any '' character.

Add a view reporting aggregated data.

Data is aggregated in a tree structure according to the distribution and filter in the specified viewbuilder.

• This function requires v14.1 firmware or newer.

• Using a string as viewbuilder requires v16.0 firmware or newer.

Add a callback to call with channel statistics data while updating.

Add a view reporting all connections matching the filter in specified viewbuilder.

• This function requires v14.1 firmware or newer.

• Using a string as viewbuilder requires v16.0 firmware or newer.

Add a callback to call with realtime filtering rule data while updating.

• This function requires v15.0 firmware or newer.

Add a callback to be called with realtime connection information for all connections on specified host

• This function requires v13.0 firmware or newer.

Add a callback to call with realtime NetObject data while updating.

>>> PATH="/NetObjects/Everyone"
>>> def cb(objs):
...     print "#%d subscribers active under %s" % (len(objs), PATH)
...     # print top10
...     objs.sort(key=lambda no: no.speed[0] + no.speed[1])
...     print "%-40s %9s %9s" % ("# Name", "inkbps", "outkbps")
...     for no in objs[:10]:
...         # convert to kbps
...         inspd = no.speed[0]*8.0/1000
...         outspd = no.speed[1]*8.0/1000
...         print "%-40s %8.2f %8.2f" % (no.name, inspd, outspd)
... 
>>> rt.add_netobj_callback(cb, under=PATH)
>>> rt.update_forever()

• under parameter requires v12.1 firmware or newer.

• When 'under' is used the callback is called with a list of <a href="#module-packetlogic2.pld.pld-RealtimeNetObject">RealtimeNetObject</a>s directly, no <a href="#module-packetlogic2.pld.pld-RealtimeNetObjectTree">RealtimeNetObjectTree</a> intermediate layer.

• include_hosts parameter requires v12.2 firmware or newer.

Add a callback to call with realtime service data while updating.

• This function requires v12.1 firmware or newer.

Add a callback for byte counters.

The signature of the callback should be:

cb(idx, oid, sk, flags, _in, _out)

idx is counter index in PL (i.e a number between 0 and MAX_COUNTERS) oidx is shaping object id sk is split key (i.e netobject id on split-by-netobject, ip on split-by-localhost, subscriber name on split-by-subscriber, and 0 on no split) flags is flags bitmask, if (1<<13) is set it means that this is the last update for this counter, and it will be reset to 0. _in and _out are bytecounters.

• This function requires v12.2 firmware or newer.

Add a callback to call with realtime shapingobject data while updating.

• This function requires v12.2 firmware or newer.

Add a callback to call with system diagnostics data while updating.

• This method only works in v13.0 and earlier. In 13.1 and newer use the SysDiag resource instead.

Add a callback to call after each update is done.

Stop the updating, but keep callback functions.

Like stop_updating but allows resuming updating by calling update_forever again.

Immediately disconnect from packetlogic system.

After this method has been called this object becomes useless.

It may be used to force a disconnect when the garbage collector can't be trusted to do a timely disconnect.

Retrieve revision string for currently loaded drdl ARM.

• This function requires v12.1 firmware or newer.

Dump the bgp table.

This function is just for debugging purposes. It will return the BGP table in packetlogicd.

• This API is for debugging purpose only and might change without notice.

• The API for this function changed with 14.1 to return both IPv4 and IPv6 prefixes as strings. The return tuple for prefixes contains (depth, prefixstr, path_id, lchildren, rchildren).

Add a dynamic netobject item

Please note that netobject will not be verified with regard to performance and flexibility when adding to a uncommitted netobject.

>>> rt.dyn_add(31682, '127.0.0.1')
True

• subscriber parameter requires v12.0 firmware or newer.

• is_subscriber parameter requires v12.4 firmware or newer.

• linkspeed_in parameter requires v12.4 firmware or newer.

• linkspeed_out parameter requires v12.4 firmware or newer.

• natcfg parameter requires v14.0 firmware or newer.

List all dynamic netobject items

>>> rt.dyn_list()
[(31589, '127.0.0.1'),
 (31576, '192.168.1.1'),
 (31589, '192.168.0.131'),
 (31688, '192.168.0.131'),
 (31577, '192.168.1.1'),
 (31682, '127.0.0.1')]

List all dynamic netobject items including subscriber names

>>> rt.dyn_list()
[(31589, '127.0.0.1', 'User 1'),
 (31576, '192.168.1.1', 'User 123'),
 (31589, '192.168.0.131', 'User 124'),
 (31688, '192.168.0.131', 'User 124'),
 (31577, '192.168.1.1', 'User 123'),
 (31682, '127.0.0.1', 'User 1')]

• This function requires v12.0 firmware or newer.

List all dynamic netobject items matching the specified ipaddress and netmask

This command is NOT supported on system with PacketLogic version v11.359 or earlier. Using it will raise a timeout exception after about a minute.

>>> rt.dyn_list_mask('192.168.0.0', '255.255.252.0')
[(31576, '192.168.1.1'),
 (31589, '192.168.0.131'),
 (31688, '192.168.0.131'),
 (31577, '192.168.1.1'),
 (31682, '192.168.2.33'),
 (31697, '192.168.3.142')]

List dynamic netobject items matching the specified netobject id

This command is NOT supported on system with PacketLogic version v11.359 or earlier. Using it will raise a timeout exception after about a minute.

>>> rt.dyn_list_no(31576)
[(31576, '192.168.1.1'),
 (31576, '192.168.0.131'),
 (31576, '192.168.2.13')]

List dynamic netobject items matching the specified netobject id or an netobject under it.

>>> rt.dyn_list_no_recurse(31576)
[(31576, '192.168.1.1'),
 (31577, '192.168.0.131'),
 (31576, '192.168.2.13')]

• This function requires v13.1 firmware or newer.

Remove a dynamic netobject item

>>> rt.dyn_remove(31682, '127.0.0.1')
True

Set multiple dynamic netobject items under a base netobject.

This function replaces all dynamic netobject items that exists for the specified ip address in the netobject tree under the specified base netobject id.

• This function requires v12.4 firmware or newer.

Return last error message from dyn_add/dyn_remove/dyn_set

>>> rt.dyn_add(19, '10.0.0.1')
True
>>> rt.dyn_add(19, '10.0.0.1')
False
>>> rt.dyn_strerror()
'Item already exists'

• This function requires v12.4 firmware or newer.

Re-enable all rules in given realm.

Disable a rule.

Enable a previously disabled rule.

Force Statistics write to the disk.

• This function requires v12.1 firmware or newer.

Clear the firewall log.

Query the firewall log for a list of entries between two offsets

>>> info, results = rt.fwlog_query_offsets (0, 50)
>>> print info
{'logentries': 14054L}
>>> print len(results)
50
>>> for i in results[0:3]:
....:     print i
....:
{'clientport': 39682, 'protocol': 6, 'service': 'Lunarstorm live', 'clienthostname': '', 'serverhostname': '', 'rule': 'Monitor ', 'server': '1.2.3.4', 'client': '5.6.7.8', 'serverport': 8080, 'time': 1138204688, 'type': 0, 'properties': ''}
{'clientport': 55172, 'protocol': 6, 'service': 'HTTP', 'clienthostname': '', 'serverhostname': 'www.google.com', 'rule': 'Log HTTP', 'server': '209.85.129.104', 'client': '192.168.9.174', 'serverport': 80, 'time': 1250775399L, 'type': 0, 'properties': 'File length=0\nServer Hostname=www.google.com\nURL=http://www.google.com/search?q=packetlogic&ie=utf-8&oe=utf-8&aq=t\nRequest method=GET\nDirection=Inbound\nFilename=/search?q=packetlogic&ie=utf-8&oe=utf-8&aq=t\nUser-Agent=Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.0.12) Gecko/2009072221\nTransfer-Encoding=None\nUpload file length=0\n'}
{'clientport': 3252, 'protocol': 6, 'service': 'eDonkey transfer', 'clienthostname': '', 'serverhostname': '', 'rule': 'Monitor ', 'server': '10.10.11.11', 'client': '40.50.60.70', 'serverport': 7804, 'time': 1138204688, 'type': 0, 'properties': ''}

Grab all entries in the firewall log and clear once we get the last batch

>>> l = []
>>> numentries = rt.fwlog_query_offsets(0,0)[0]['logentries']
>>> for x in range(0, numentries, 500):
....:   l += rt.fwlog_query_offsets(x, min(x+500, numentries), no_reverse=True)[1]
....:
>>> l += rt.fwlog_query_offsets(numentries, -1, clear=True, no_reverse=True)[1] # grab entries logged while quering

• clear parameter is not supported on v12.0 firmwares.

• no_reverse parameter is not supported on v12.0 firmwares.

Query the firewall log for a list of entries matching a specific firewall rule

>>> info, results = rt.fwlog_query_rule(58)
>>> print info
{'logentries': 14054L}
>>> print results
[{'client': '10.0.0.2',
  'clienthostname': '',
  'clientport': 2985,
  'properties': '',
  'protocol': 6,
  'rule': 'Monitor ',
  'server': '10.0.1.3',
  'serverhostname': '',
  'serverport': 1512,
  'service': 'Skype',
  'time': 1138204680,
  'type': 0},
 {'client': '1.2.3.4',
  'clienthostname': '',
  'clientport': 3247,
  'properties': '',
  'protocol': 6,
  'rule': 'Monitor ',
  'server': '10.3.2.1',
  'serverhostname': '',
  'serverport': 17561,
  'service': 'Undetermined',
  'time': 1138204680,
  'type': 0},
 {'client': '3.2.1.2',
  'clienthostname': '',
  'clientport': 52263,
  'properties': 'Serverinfo= AAMAILE.int.aalogistik.com Microsoft ESMTP MAIL Service, Version: 6.0.3790.1830 ready at  Wed, 25 Jan 2006 16:57:54 +0100 \n',
  'protocol': 6,
  'rule': 'Monitor ',
  'server': '1.2.4.3',
  'serverhostname': '',
  'serverport': 25,
  'service': 'Undetermined',
  'time': 1138204680,
  'type': 0}]

Query the firewall log for a list between two points in time

>>> info,results = rt.fwlog_query_time_range ("2006-01-01 00:00", "2006-02-02 00:00")
>>> print results[0]
{'clientport': 38742, 'protocol': 6, 'service': 'eDonkey transfer', 'clienthostname': '', 'serverhostname': '', 'rule': 'Monitor ', 'server': '3.3.3.3', 'client': '1.1.1.1', 'serverport': 4662, 'time': 1138204658, 'type': 0, 'properties': ''}

Get channel statistics data once.

(Should not be used simultaneously to add_channels_callback and update_forever)

Get Realtime NetObject data once.

(Should not be used simultaneously to add_netobj_callback and update_forever)

Get Realtime Services data once.

(Should not be used simultaneously to add_service_callback and update_forever)

• This function requires v12.1 firmware or newer.

Get system diagnostics data once.

(Should not be used simultaneously to add_stats_callback and update_forever)

• For firmware version 13.1 and newer this is a compatibility wrapper around pl.SysDiag(). If support for earlier firmwares is not needed using pl.SysDiag() directly is preferred.

Get a ViewBuilder object for creating views.

See ViewBuilder object documentation for details.

• This function requires v14.1 firmware or newer.

Inject a packet.

This function is just for testing purposes.

Reload drdl signatures. For internal use only.

• This function requires v12.1 firmware or newer.

Requests all shaping counters, regardless if they have changed or not.

• This function requires v12.2 firmware or newer.

Requests all shaping counters for a specific subscriber, regardless if they have changed or not.

• This function requires v15.Z firmware or newer.

Stop the updating and clear callback functions.

Start updating.

This method will enter a loop that requests updates every 5 seconds (or other interval specified by the interval argument). Updates are sent to the callback functions registered with methods named add_*_callback (among others add_service_callback, add_channels_callback and add_update_done_callback). To break out of the updating loop call the stop_updating method.

List available vbs objects

>>> rt.vbs_list()
[('00E081600B81', 24, 'VBS low', 1),
 ('00E081600B81', 74, 'VBS medium', 1),
 ('00E081600B81', 26, 'VBS max', 1)]

• This function isn't supported in v12.0 and v12.1 firmwares.

Query vbs data from a specific vbs object

>>> rt.vbs_query('0010F3067C3A', 24)
[{'bidirectional': 0L,
  'bidirectional speed': 0,
  'extra': -183572567,
  'id': 24,
  'inbound': 0L,
  'inbound speed': 0,
  'machineid': '0010F3067C3A',
  'name': 'VBS Grund',
  'outbound': 0L,
  'outbound speed': 0,
  'splitname': '169.231.14.245'}]

• This function isn't supported in v12.0 and v12.1 firmwares.

• In v12.2 firmware or newer the <code>machineid</code> argument is ignored.

• In v12.2 firmware or newer bidirectional VBS isn't supported, therefore the 'bidirectional' value returned is always 0.

Reset vbs accounting data for a vbs object.

• This function isn't supported in v12.0 and v12.1 firmwares.

Set transfer to the specified value. Can only be used on object without sliding window (duration=1).

• This function does not exist in v12.0 firmware or newer.

Run virtual connection ruleset checker.

>>> rt.vcrc({'serverip':'192.168.9.1'})

>>> rt.vcrc({'serverip': '192.168.9.1',
            'service': 'HTTP',
            'vlan': 1234})

>>> rt.vcrc({'serverip':'217.73.103.54'})
{'fwrules': [(60L, 2031L), (63L, 2031L)], 'shapingrules': [(65L, 2031L),
(66L, 1903L)], 'monitor_iface': 0L, 'fwrule': 63, 'ruleset_state': 3,
'test_id': 1L, 'rewrite_obj': 0L}

Waits for a ruleset of 'commitid' to be loaded and compiled by plrcd. wait_for_ruleset() will return when plrcd sees a commitid that is at least as new as 'commitid' given. If plrcd already has loaded or loads a newer commitid than the given 'commitid' it will also return with True.

Typical use:

>>> # Add Test netobject to pldb
>>> test = rs.object_add("/NetObjects/Test")
>>> commitid = rs.commit()
>>> # Wait for Test netobject to be visible in plrcd
>>> rt.wait_for_ruleset(commitid)
>>> # Add a dynnetobj item in plrcd under Test netobject
>>> rt.dyn.add(test.id, "10.0.0.1")

• This function requires v14.0 firmware or newer.

Find a single Realtime NetObject with the given full path.

Return a list of Realtime NetObject data, matching the given path, and optional recursive flag.

Add a distribution to the view.

Adds the specified field as a sub-distribution of current distribution.

>>> v = rt.get_view_builder()
>>> v.filter_out("Service", "QUIC")
>>> v.distribution("Server Hostname")
>>> v.distribution("NetObject Level", "DHCP/By MAC")
>>> v.distribution("Local Host")

Print a human readable representation of available filters and fields to stdout.

Add a filter to the view.

Makes filter only include connections where the property specified by key is one of the specified values. The key can be either string or a tuple containing additional arguments to the filter.

>>> v = rt.get_view_builder()
>>> v.filter(("Incoming VLAN Id", "1"), 100)
>>> v.filter(("Session Context", "myschema/mycolumn"), xyz,)
>>> v.filter("Host", "10.0.0.1")
>>> v.filter("Server Port", 443)

Add a filter to exclude traffic from the view.

Makes filter exclude connections where the property specified by key is one of the specified values. The key can be either string or a tuple containing additional arguments to the filter.

>>> v = rt.get_view_builder()
>>> v.filter("Host", "10.0.0.1")
>>> v.filter("Server Port", 443)
>>> v.filter_out("Service", "SSL v3")