Documentation for PythonAPI
17.2.0py1

packetlogic2.pldb.ruleset

This module contains functionality for managing the ruleset on the PacketLogic system.

Do NOT import this module directly. The PLConnection object should be used, e.g:

>>> import packetlogic2
>>> pl = packetlogic2.connect("192.168.1.25", "admin", "pldemo00")
>>> r = pl.Ruleset()

Classes defined here:

  • Ruleset - The Ruleset resource is used for reading and manipulating objects and rules

Ruleset

The Ruleset resource is used for reading and manipulating objects and rules in the PacketLogic ruleset.

See also NetObjects, PortObjects, ProtocolObjects, ServiceObjects, TimeObjects, VlanIdObjects, VlanPrioObjects, PropertyObjects, RewriteObjects, FlagObjects and SystemObjects, MPLSObjects, DSCPObjects, ChannelObjects, ShapingObjects, StatisticsObjects, IpfixObjects, RuleCondition, SessionContextObjects, as well as FwRules and ShapingRules. StatisticsRules.

Inherits from: Resource
Methods:
Deprecated int add(self, path)
Add a Object to the object-tree
remove(self, path)
Removes an Object and all its children
unlink(self, path)
Removes an Object for all firewall and shapingrules
Firewall rules fwrule_add(self, name, action, quick=False, log=False, rewrite_object=0, monitor_iface=0, inject_data='', divert_iface=0, monitor_label='', divert_label='', enrich_object=0, rulecondition=0)
Create a new firewall rule
FwRule fwrule_find(self, name, systemid=None)
Find a firewallrule by name
FwRule fwrule_find_id(self, rule_id, systemid=None)
Find a firewallrule by id
list of FwRule fwrule_list(self)
Return a list of all firewall rules
fwrule_remove(self, rule)
Remove firewall rule
Ipfix objects ipfixobject_add(self, name, templatestring, collectors)
Create a new IpfixObject in pldb
IpfixObject ipfixobject_find(self, name, systemid=None)
Find a ipfix object by its name
IpfixObject ipfixobject_find_id(self, object_id, systemid=None)
Find a ipfix object by its id
list of IpfixObject ipfixobject_list(self)
Return a list of all ipfix objects
ipfixobject_remove(self, object)
Remove ipfix object
Objects plobject.PLObject object_add(self, path)
Add an Object to the object-tree
plobject.PLObject object_find(self, path, systemid=None)
This method finds an object by type and name
plobject.PLObject object_find_id(self, path, object_id, systemid=None)
This method finds a object by type and id number
plobject.PLObject object_get(self, path, systemid=None)
This method gets an object by type and name
list of plobject.PLObject object_list(self, path='/', recursive=True, systemid=None)
Lists all the Objects that match the path
object_remove(self, object)
Removes an Object and all its children
object_unlink(self, path)
Removes an Object for all firewall and shapingrules
Ruleconditions RuleCondition rulecondition_add(self, op, name='')
Create a new RuleCondition in pldb
RuleCondition rulecondition_find(self, name)
Find a rulecondition by name
RuleCondition rulecondition_find_id(self, id)
Find a rulecondition by id
list of RuleCondition rulecondition_list(self)
Returns a list of ruleconditions
Services services_cmd(self, services=[], props=[])
Send services to pldbd
list of str services_list(self)
List all services
list of str services_prop_list(self)
List all properties
Shaping objects ShapingObject shapingobject_add(self, name, inbound=[(0, 0, 0)], outbound=[(0, 0, 0)], bidir=[(0, 0, 0)], split=0, _unused=0, max_connections=0, flags=[], split_argument=0, subscriber_netobject=None, static_split_netobjects=[])
Create a new ShapingObject in pldb
ShapingObject shapingobject_find(self, name, systemid=None)
Find a shaping object by its name
ShapingObject shapingobject_find_id(self, object_id, systemid=None)
Find a shaping object by its id
list of ShapingObject shapingobject_list(self)
Return a list of all shaping objects
shapingobject_remove(self, object)
Remove shaping object
Shaping rules ShapingRule shapingrule_add(self, name, priority=5, precedence=0, fair_factor=1, rulecondition=0)
Create a new shapingrule in pldb
ShapingRule shapingrule_find(self, name, systemid=None)
Find a shapingrule by name
ShapingRule shapingrule_find_id(self, rule_id, systemid=None)
Find a shapingrule by id
list of ShapingRule shapingrule_list(self)
Return a list of all shaping rules
shapingrule_remove(self, rule)
Remove shaping rule
Statistics objects StatisticsObject statisticsobject_add(self, name, total_fields, graph_fields, split, no_root=0, so_root=0, graph_freq=300, min_bytes_in=102400, min_bytes_out=102400)
Create a new StatisticsObject in pldb
StatisticsObject statisticsobject_find(self, name, systemid=None)
Find a statistics object by its name
StatisticsObject statisticsobject_find_id(self, object_id, systemid=None)
Find a statistics object by its id
list of StatisticsObject statisticsobject_list(self)
Return a list of all statistics objects
statisticsobject_remove(self, object)
Remove statistics object
Statistics rules StatisticsRule statisticsrule_add(self, name, rulecondition=0)
Create a new statisticsrule in pldb
StatisticsRule statisticsrule_find(self, name, systemid=None)
Find a statisticsrule by name
StatisticsRule statisticsrule_find_id(self, rule_id, systemid=None)
Find a statisticsrule by id
list of StatisticsRule statisticsrule_list(self)
Return a list of all statistics rules
statisticsrule_remove(self, rule)
Remove statistics rule
Ungrouped read-only list of DivertIface divert_iface_list(self)
Return a list of all divert interfaces
object features_get(self)
Returns a simple object with boolean attributes showing enabled features
read-only list of MonitorIface monitor_iface_list(self)
Return a list of all monitor interfaces
bool refresh(self, force=False, timeout=1.0)
Check for any pending "New data was committed" signals, and invalidate
Inherited from Resource close(self)
Immediately disconnects the resource
commit(self, message='PythonAPI commit')
Store the current transaction to the database
ping(self, string='')
Send a command to server to test if it is up
tuple of (str, int) protocol(self, protocol, strict=False)
Translate protocol name OR number to tuple with name AND number
dict of str:int and int:str protocols_dict(self)
Returns a dictionary with name:nr and nr:name items for IP protocols
rollback(self)
Abort the current transaction and discard the data
wait_for_commit(self, pinginterval=60)
Wait for new data to be committed on resource
list of str xfb_flags_list(self)
List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects
Class Variables:
CONDITION_NETOBJECT_CLIENT Client NetObjects
CONDITION_NETOBJECT_SERVER Server NetObjects
CONDITION_NETOBJECT_HOST Host NetObjects
CONDITION_NETOBJECT_LOCAL Local NetObjects
CONDITION_PORTOBJECT_CLIENT Client PortObjects
CONDITION_PORTOBJECT_SERVER Server PortObjects
CONDITION_SERVICEOBJECT ServiceObjects
CONDITION_VLANIDOBJECT_LVL0 VLANIdObjects level 0
CONDITION_VLANIDOBJECT_LVL0_IN Inbound VLANIdObjects level 0
CONDITION_VLANIDOBJECT_LVL0_OUT Outbound VLANIdObjects level 0
CONDITION_VLANIDOBJECT_LVL1 VLANIdObjects level 1
CONDITION_VLANIDOBJECT_LVL1_IN Inbound VLANIdObjects level 1
CONDITION_VLANIDOBJECT_LVL1_OUT Outbound VLANIdObjects level 1
CONDITION_VLANIDOBJECT_LVL2 VLANIdObjects level 2
CONDITION_VLANIDOBJECT_LVL2_IN Inbound VLANIdObjects level 2
CONDITION_VLANIDOBJECT_LVL2_OUT Outbound VLANIdObjects level 2
CONDITION_VLANIDOBJECT_LVL3 VLANIdObjects level 3
CONDITION_VLANIDOBJECT_LVL3_IN Inbound VLANIdObjects level 3
CONDITION_VLANIDOBJECT_LVL3_OUT Outbound VLANIdObjects level 3
CONDITION_VLANPRIOOBJECT_LVL0 VLANPrioObjects level 0
CONDITION_VLANPRIOOBJECT_LVL0_IN Inbound VLANPrioObjects level 0
CONDITION_VLANPRIOOBJECT_LVL0_OUT Outbound VLANPrioObjects level 0
CONDITION_VLANPRIOOBJECT_LVL1 VLANPrioObjects level 1
CONDITION_VLANPRIOOBJECT_LVL1_IN Inbound VLANPrioObjects level 1
CONDITION_VLANPRIOOBJECT_LVL1_OUT Outbound VLANPrioObjects level 1
CONDITION_VLANPRIOOBJECT_LVL2 VLANPrioObjects level 2
CONDITION_VLANPRIOOBJECT_LVL2_IN Inbound VLANPrioObjects level 2
CONDITION_VLANPRIOOBJECT_LVL2_OUT Outbound VLANPrioObjects level 2
CONDITION_VLANPRIOOBJECT_LVL3 VLANPrioObjects level 3
CONDITION_VLANPRIOOBJECT_LVL3_IN Inbound VLANPrioObjects level 3
CONDITION_VLANPRIOOBJECT_LVL3_OUT Outbound VLANPrioObjects level 3
CONDITION_PROTOCOLOBJECT ProtocolObjects
CONDITION_TIMEOBJECT TimeObjects
CONDITION_BGPOBJECT BGPObjects
CONDITION_ASPATHOBJECT BGPObjects
CONDITION_PROPERTYOBJECT PropertyObjects
CONDITION_SYSTEMOBJECT SystemObjects
CONDITION_FLAGOBJECT FlagObjects
CONDITION_MPLSOBJECT MPLSObjects
CONDITION_MPLSOBJECT_IN Inbound MPLSObjects
CONDITION_MPLSOBJECT_OUT Outbound MPLSObjects
CONDITION_DSCPOBJECT DSCPObjects
CONDITION_DSCPOBJECT_IN Inbound DSCPObjects
CONDITION_DSCPOBJECT_OUT Outbound DSCPObjects
CONDITION_CHANNELOBJECT ChannelObjects
CONDITION_CHANNELOBJECT_IN Inbound ChannelObjects
CONDITION_CHANNELOBJECT_OUT Outbound ChannelObjects
CONDITION_TUNNELLVLOBJECT TunnelLevelObjects
CONDITION_TUNNELTYPEOBJECT TunnelTypeObjects
CONDITION_CONTENTLOGICOBJECT ContentlogicObjects
CONDITION_TAGOBJECT ContentlogicObjects
CONDITION_RULECONDITION RuleConditions
CONDITION_OP_EQ Condition equals
CONDITION_OP_NE Condition does not equal
FWRULE_ACTION_ACCEPT Accept connection
FWRULE_ACTION_REJECT Reject connection
FWRULE_ACTION_DROP Drop connection
FWRULE_ACTION_REWRITE Rewrite connection
FWRULE_ACTION_DIVERT Divert connection
FWRULE_ACTION_INJECT Inject data into connection
FWRULE_ACTION_ENRICH Enrich HTTP request
SPLIT_NONE Split by none
SPLIT_LOCALHOST Split by localhost
SPLIT_HOST_NETOBJECT Split by host netobject
SPLIT_LOCAL_NETOBJECT Split by local netobject
SPLIT_SERVER_NETOBJECT Split by server netobject
SPLIT_CLIENT_NETOBJECT Split by client netobject
SPLIT_CONNECTION Split by connection
SPLIT_SUBSCRIBER Split by subscriber
SPLIT_LOCAL_NETWORKPREFIX Split by local networkprefix
SPLIT_SESSIONCONTEXTOBJECT Split by SessionContextObject
RULECONDITION_AND Rulecondition operator AND
RULECONDITION_OR Rulecondition operator OR
RULECONDITION_NOT Rulecondition operator NOT
Properties:
commitid The CommitID associated with this session

add(self, path)

Add a Object to the object-tree. The type and name of the Object is determined by the path.

Returns:
  • id of the newly created object
  • int
Parameters:
  • path (str ) - The path is the new Object to be created. if we want to create a NetObject called Anders under with the NetObject Work as parent you use the path /NetObjects/Work/Anders.
add is deprecated: Port your code to object_add which differs slightly in return value.

close(self)

Immediately disconnects the resource.

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.

commit(self, message='PythonAPI commit')

Store the current transaction to the database.

When you do this PacketLogic will reload the ruleset. This will take a lot of CPU resources from the system, try to do this in batches.

Observe that if you don't commit the changes you've made, no other resource (including the client) will see your changes.

Parameters:
  • message (str) - Message recorded in the commit log. Ignored in v12.1 and earlier.
  • message parameter is ignored in v12.1 firmware and earlier.

divert_iface_list(self)

Return a list of all divert interfaces.

>>> r.divert_iface_list()
[]
Returns:
  • A list of divert interfaces.
  • read-only list of DivertIface
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.2 to v14.0. In 14.1 and newer instead use divert_label.

features_get(self)

Returns a simple object with boolean attributes showing enabled features. The members of the object, that can be True or False, are: bgp, fw, shaping, statistics, connlog (and its alias connsearch), enterprise, monitor, divert and vbs

Returns:
  • Object with a boolean attribute for each feature.
  • object

fwrule_add(self, name, action, quick=False, log=False, rewrite_object=0, monitor_iface=0, inject_data='', divert_iface=0, monitor_label='', divert_label='', enrich_object=0, rulecondition=0)

Create a new firewall rule.

        >>> r.fwrule_add('Test', r.FWRULE_ACTION_ACCEPT, quick=True)
        <PacketLogic Rule 'Test'>

        >>> rewrite_object_id = r.object_get('/RewriteObjects/Netaccess server').id
        >>> r.fwrule_add('Test', r.FWRULE_ACTION_REWRITE, quick=True, rewrite_object=rewrite_object_id)
        <PacketLogic Rule 'Test'>

        >>> rewrite_object = r.object_get('/RewriteObjects/Netaccess server')
        >>> r.fwrule_add('Test', r.FWRULE_ACTION_REWRITE, quick=True, rewrite_object=rewrite_object)
        <PacketLogic Rule 'Test'>

@type name: C{str}
@param name: The name of the new firewall rule, a rule
with this name must not already exist.

@type action: C{int}
@param action: Action when the rule matches, one of:
FWRULE_ACTION_ACCEPT FWRULE_ACTION_REJECT,
FWRULE_ACTION_DROP, FWRULE_ACTION_REWRITE,
FWRULE_ACTION_DIVERT, FWRULE_ACTION_INJECT, FWRULE_ACTION_ENRICH.

@type quick: C{boolean}
@param quick: Give this rule the quick property.

@type log: C{int}
@param log: Log level to use for this rule. 0 = Off. 1 = Brief. 2 = Verbose

@type rewrite_object: C{int} or L{rewriteobject.RewriteObject}
@param rewrite_object: The id or the actual L{rewriteobject.RewriteObject}
                       describing what to rewrite when
                       this rule matches and action is
                       FWRULE_ACTION_REWRITE.

@type monitor_iface: C{int}
@param monitor_iface: If non zero, packets matching
                      this rule will also be sent to
                      the specified interface id. See
                      L{monitor_iface_list
                      <Ruleset.monitor_iface_list>}.

@type inject_data: C{str}
@param inject_data: The content that shall be injected for
                    FWRULE_ACTION_INJECT rules. The
                    content is usually a HTTP 307
                    redirect response.

@type divert_iface: C{int}
@param divert_iface: Interface to divert packets to when
                     using FWRULE_ACTION_DIVERT. See
                     L{divert_iface_list
                     <Ruleset.divert_iface_list>}. For
                     use with 14.0 and earlier
                     only. For 14.1 and newer use
                     divert_label instead.

@type monitor_label: C{str]
@param monitor_label: Label to monitor packets to when monitor_iface
                      is set to the index of the "Label" interface.

@type divert_label: C{str}
@param divert_label: Label to divert packets to when using FWRULE_ACTION_DIVERT.

@type enrich_object: C{int} or L{enrichobject.EnrichObject}
@param enrich_object: The id or the actual L{enrichobject.EnrichObject}
                       describing what to enrich when
                       this rule matches and action is
                       FWRULE_ACTION_ENRICH.

@returns: Created firewall rule.
@rtype: L{FwRule <plrule.FwRule>}

@raises PLDBUnsupportedInFirmware: If inject_divert_iface/monitor_label/divert_label arguments are used and firmware doesn't support them.

@attention: divert_iface parameter is replaced with divert_label in firmware v14.1 and newer.
@attention: monitor_label parameter requires v14.1 firmware or newer.
@attention: divert_label parameter requires v14.1 firmware or newer.

fwrule_find(self, name, systemid=None)

Find a firewallrule by name

>>> r.fwrule_find("allow all")
<PacketLogic Rule 'allow all'>
Returns:
  • Firewall rule or None if not found.
  • FwRule
Parameters:
  • name (str) - The name of the firewall rule.

fwrule_find_id(self, rule_id, systemid=None)

Find a firewallrule by id

>>> r.fwrule_find_id(14)
<PacketLogic Rule 'allow all'>
Returns:
  • Firewall rule or None if not found.
  • FwRule
Parameters:
  • rule_id (int) - The id of the firewall rule.

fwrule_list(self)

Return a list of all firewall rules.

>>> r.fwrule_list()
[<PacketLogic Rule '<PacketLogic Rule 'allow all'>, <PacketLogic Rule 'nxs_accept'>, <PacketLogic Rule 'Allow all DHCP'>, <PacketLogic Rule 'Netaccess redirect'>, <PacketLogic Rule 'Netaccess DHCP'>, <PacketLogic Rule 'Netaccess'>]
Returns:
  • A list of firewall rules.
  • list of FwRule

fwrule_remove(self, rule)

Remove firewall rule

>>> r.fwrule_add('Example', r.FWRULE_ACTION_ACCEPT, quick=True)
<PacketLogic Rule 'Example'>
>>> r.fwrule_remove('Example')
>>> rule = r.fwrule_add('Example', r.FWRULE_ACTION_ACCEPT, quick=True)
>>> r.fwrule_remove(rule)
Parameters:
  • rule (str or plrule.FwRule ) - The name or actual rule to be removed.
Exceptions raised:
  • ValueError - If firewall rule is not found

ipfixobject_add(self, name, templatestring, collectors)

Create a new IpfixObject in pldb

>>> s = pl.Ipfix()
>>> r.ipfixobject_add('Test Ipfix', '150,151', '[192.168.0.1,127.0.0.1]:1234')
<PacketLogic IpfixObject 'Test Ipfix'>
Parameters:
  • name (str) - Name of the new object
  • templatestring (str) - String describing what data is to be exported. For a list of values, see the PIC Product Guide.
  • collectors (str) - Comma separated list of ipfix collectors and a port.
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v15.0 firmware or newer.
  • collectors parameter requires v16.0 firmware or newer.

ipfixobject_find(self, name, systemid=None)

Find a ipfix object by its name

>>> r.ipfixobject_find('Test Ipfix')
<PacketLogic IpfixObject>
Returns:
Parameters:
  • name (str) - Name of ipfix object to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v15.0 firmware or newer.

ipfixobject_find_id(self, object_id, systemid=None)

Find a ipfix object by its id

>>> r.ipfixobject_find_id(83)
<PacketLogic IpfixObject>
Returns:
Parameters:
  • object_id (int) - Id of ipfix object to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v15.0 firmware or newer.

ipfixobject_list(self)

Return a list of all ipfix objects.

>>> r.ipfixobject_list()
[<PacketLogic IpfixObject>,
 <PacketLogic IpfixObject>]
Returns:
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v15.0 firmware or newer.

ipfixobject_remove(self, object)

Remove ipfix object

>>> r.ipfixobject_add("Example")
<PacketLogic IpfixObject ('Example')>
>>> r.ipfixobject_remove("Example")
>>> object = r.ipfixobject_add("Example")
>>> r.ipfixobject_remove(object)
Parameters:
  • object (str or ipfixobject.StatisticObject ) - The name or actual rule to be removed.
Exceptions raised:
  • ValueError - If ipfix object is not found
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v15.0 firmware or newer.

monitor_iface_list(self)

Return a list of all monitor interfaces.

>>> r.monitor_iface_list()
[<PacketLogic Monitor Interface 'PCAP Writer'>, <PacketLogic Monitor Interface 'DHCP Snooper'>, <PacketLogic Monitor Interface 'RADIUS Snooper'>, <PacketLogic Monitor Interface 'PCAP-2 Writer'>]
Returns:
  • A list of monitor interfaces.
  • read-only list of MonitorIface

object_add(self, path)

Add an Object to the object-tree. The type and name of the Object is determined by the path.

Returns:
  • A plobject.PLObject subclass.
  • plobject.PLObject
Parameters:
  • path (str ) - The path is the new Object to be created. if we want to create a NetObject called Anders under with the NetObject Work as parent you use the path /NetObjects/Work/Anders.
Exceptions raised:
  • RuntimeError - "Unknown object item type": for invalid type of object. Should never happen unless e.g two api-versions are mixed up.

object_find(self, path, systemid=None)

This method finds an object by type and name.

>>> r.object_find('/NetObjects/TestObject')
<PacketLogic NetObject 'TestObject' '/NetObjects'>
>>> print r.object_find('/NetObjects/DoesNotExist')
None

It is a synonym for object_get, that soon will be deprecated.

Returns:
  • Object if found, else None
  • plobject.PLObject
Parameters:
  • path (str) - a path string (i.e. /NetObjects/Corporate)
  • systemid (str ) - Get object with specified systemid if specified, otherwise default to local object.
Exceptions raised:
  • RuntimeError - "Unknown object item type": for invalid type of object. Should never happen unless e.g two api-versions are mixed up.

object_find_id(self, path, object_id, systemid=None)

This method finds a object by type and id number.

>>> r.object_find_id('/NetObjects', 31573)
<PacketLogic NetObject 'TestObject' '/NetObjects'>
>>> print r.object_find_id('/NetObjects', 7777777)
None
Returns:
  • A plobject.PLObject subclass.
  • plobject.PLObject
Parameters:
  • path (str) - a path string (i.e. /NetObjects)
  • object_id (int) - ID number of the Object. Could be found by examining the id property of any plobject.PLObject implementation.
  • systemid (str ) - Get object with specified systemid if specified, otherwise default to local object.
Exceptions raised:
  • RuntimeError - "Unknown object item type": for invalid type of object. Should never happen unless e.g two api-versions are mixed up.

object_get(self, path, systemid=None)

This method gets an object by type and name.

>>> r.object_get('/NetObjects/TestObject')
<PacketLogic NetObject 'TestObject' '/NetObjects'>
>>> r.object_get('/NetObjects/TestObject')
<PacketLogic NetObject 'TestObject' '/NetObjects'>

It will soon be deprecated in favour for the synonym object_find.

Returns:
  • Object if found, else None
  • plobject.PLObject
Parameters:
  • path (str) - a path string (i.e. /NetObjects/Corporate)
  • systemid (str ) - Get object with specified systemid if specified, otherwise default to local object.
Exceptions raised:
  • RuntimeError - "Unknown object item type": for invalid type of object. Should never happen unless e.g two api-versions are mixed up.

object_list(self, path='/', recursive=True, systemid=None)

Lists all the Objects that match the path.

>>> r.object_list('/NetObjects')
[<PacketLogic NetObject 'Netaccess Kunder' '/NetObjects'>, <PacketLogic NetObject 'Netaccess allowed servers' '/NetObjects'>,
<PacketLogic NetObject 'nxs' '/NetObjects'>, <PacketLogic NetObject 'DummyPlaceholder' '/NetObjects'>,
<PacketLogic NetObject 'nxs_Bandbredd 2000' '/NetObjects/nxs'>, <PacketLogic NetObject 'TestObject' '/NetObjects'>,
<PacketLogic NetObject 'TestNetobject' '/NetObjects'>, <PacketLogic NetObject 'TestNetobject-Deuxe' '/NetObjects'>,
<PacketLogic NetObject 'NetintactTest' '/NetObjects'>, <PacketLogic NetObject 'Kruken' '/NetObjects/nxs'>,
<PacketLogic NetObject 'nxs_1M [3]' '/NetObjects/nxs'>, <PacketLogic NetObject 'nxs_4Mbit [2]' '/NetObjects/nxs'>,
<PacketLogic NetObject 'nxs_256kbit [1]' '/NetObjects/nxs'>]
Returns:
  • A list of plobject.PLObject subclassed objects.
  • list of plobject.PLObject
Parameters:
  • path (str ) - The path of Objects you want to list. E.g. if you want to list all the NetObjects set the path to /NetObjects. This will recursively list all NetObjects (if you don't touch the recursive parameter). You can also specify the path deeper into the tree, i.e. /NetObjects/work will list all NetObjects with the object work as parent. Listing a path below the first level will include the named object itself in the result - e.g listing /ServiceObjects will list all objects _below_ /ServiceObjects but listing /ServiceObjects/foo will include foo in the result.
  • recursive (boolean ) - This specifies if the list should be recursively done. When set to False it will only list the items on the current level of path.
  • systemid (str ) - If specified limits the list to only include objects with the specified systemid.
Exceptions raised:
  • RuntimeError - "Unknown object item type": for invalid type of object. Should never happen unless e.g two api-versions are mixed up.

object_remove(self, object)

Removes an Object and all its children.

Note that object_unlink only unlinks the current object, while object_remove also removes children. To both unlink and remove and object, you will need to call unlink for all children too.

>>> r.object_add("/NetObjects/Example")
>>> r.object_remove("/NetObjects/Example")
>>> obj = r.object_add("/NetObjects/Example")
>>> r.object_remove(obj)
Parameters:
  • object (str or plobject.PLObject ) - The Object to be removed or the full path.

object_unlink(self, path)

Removes an Object for all firewall and shapingrules.

Note that object_unlink only unlinks the current object, while object_remove also removes children. To both unlink and remove and object, you will need to call unlink for all children too.

This method replaces unlink that will soon be deprecated.

Parameters:
  • path (str) - The Object to be removed.

ping(self, string='')

Send a command to server to test if it is up.

protocol(self, protocol, strict=False)

Translate protocol name OR number to tuple with name AND number. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

An unknown protocol will be translated to e.g '#7' or -1, unless strict is set to True, in which case ValueError is raised for unknown protocols.

Returns:
  • Tuple with name and nr of specified protocol.
  • tuple of (str, int)
Parameters:
  • protocol (int, str or a ProtocolObject Item) - Name or number of an IP protocol
  • strict (bool) - If True, ValueError is raised for an unknown protocol, if False (default), an unknown protocol translates to number -1 or name '#7' (where 7 is the supplied unknown protocol number).

protocols_dict(self)

Returns a dictionary with name:nr and nr:name items for IP protocols. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

Returns:
  • Dict with name:nr and nr:name items for IP protocols.
  • dict of str:int and int:str

refresh(self, force=False, timeout=1.0)

Check for any pending "New data was committed" signals, and invalidate cached objects and rules if it occurs, or force them to be invalidated with force=True. Returns True if such an exception occured (and was trapped), otherwise false. Any other exception than the PLDBError "New data comitted" or timeout will not be trapped.

>>> rs.refresh(); rs.object_add('/NetObjects/TestObject'); rs.commit()
True
<PacketLogic NetObject 'TestObject' '/NetObjects'>
Returns:
  • True if a "New data was committed" signal was seen, otherwise False.
  • bool
Parameters:
  • force (bool) - If set to True the cache in the API of rules and objects will be marked dirty, forcing them to be reread from the PacketLogic system upon the next query, even if no "New data was comitted" signal occured.
  • timeout (float) - Seconds to wait for any data to arrive from the PacketLogic. Since we typically check for "New data was commited" that already are pending, this can be short, and default is one second. Zero is not allowed, and will silently be changed to 0.1

remove(self, path)

Removes an Object and all its children.

Parameters:
  • path (str ) - The Object to be removed.
remove is deprecated: Renamed to object_remove Using this method issues a deprecation warning after 11.0beta5.

rollback(self)

Abort the current transaction and discard the data.

This will also automatically happen if your connection drops or that you exit the program without commit.

Exceptions raised:
  • resource.PLDBError - If the rollback command failed.

rulecondition_add(self, op, name='')

Create a new RuleCondition in pldb

>>> rs.rulecondition_add(rs.RULECONDITION_AND, "tesla")
<PacketLogic RuleCondition '11' 'tesla'>
Returns:
  • Created ruleconditions
  • RuleCondition
Parameters:
  • op () - Type of operator, one of: RULECONDITION_AND, RULECONDITION_OR, RULECONDITION_NOT
  • name (str) - Name of the new object
  • This function requires v16.0 firmware or newer.

rulecondition_find(self, name)

Find a rulecondition by name

>>> rs.rulecondition_find("nisse")
<PacketLogic RuleCondition '1' 'nisse'>
Returns:
  • Found ruleconditions
  • RuleCondition
Exceptions raised:
  • ValueError - If rulecondition is not found
  • This function requires v16.0 firmware or newer.

rulecondition_find_id(self, id)

Find a rulecondition by id

>>> rs.rulecondition_find_id(1)
<PacketLogic RuleCondition '1' 'nisse'>
Returns:
  • Found ruleconditions
  • RuleCondition
Exceptions raised:
  • ValueError - If rulecondition is not found
  • This function requires v16.0 firmware or newer.

rulecondition_list(self)

Returns a list of ruleconditions

>>> rs.rulecondition_list()
[<PacketLogic RuleCondition '2' 'polgara'>,
<PacketLogic RuleCondition '1' 'nisse'>]
Returns:
  • List of ruleconditions
  • list of RuleCondition
  • This function requires v16.0 firmware or newer.

services_cmd(self, services=[], props=[])

Send services to pldbd

Sets stringtable for services and properties. Do NOT use this unless you know exactly what you are doing.

Parameters:
  • services (list of str) - List of services
  • props (list of str) - List of service properties

services_list(self)

List all services

Returns:
  • List of services
  • list of str

services_prop_list(self)

List all properties.

Returns:
  • List of service properties
  • list of str

shapingobject_add(self, name, inbound=[(0, 0, 0)], outbound=[(0, 0, 0)], bidir=[(0, 0, 0)], split=0, _unused=0, max_connections=0, flags=[], split_argument=0, subscriber_netobject=None, static_split_netobjects=[])

Create a new ShapingObject in pldb

>>> r.shapingobject_add("Unlimited")
<PacketLogic ShapingObject ('Unlimited', limits=<inbound=<Unlimited>, outbound=<Unlimited>, bidir=<Unlimited>>, split=0, max_connections=0, flags=[])>
>>> so = r.shapingobject_add("Per host 1Mbps", split=r.SPLIT_LOCALHOST)
>>> so.limits.inbound.bps = 1000000
>>> so.limits.outbound.bps = 1000000
>>> so
<PacketLogic ShapingObject ('Per host 1Mbps', limits=<inbound=<bps=1000000>, outbound=<bps=1000000>, bidir=<Unlimited>>, split=1, max_connections=0, flags=[])>
Returns:
Parameters:
  • name (str) - Name of the new object
  • inbound (list of tuple) - list of limits for incoming traffic, where each limit is (max_transfer, max_packets, max_speed) max_transfer must be 0 (unlimited) on the last entry in the list.
  • outbound (list of tuple) - same as inbound but for outgoing traffic
  • bidir (list of tuple) - same as inbound but for both directions
  • split (int) - Type of split, one of: SPLIT_NONE, SPLIT_LOCALHOST, SPLIT_HOST_NETOBJECT, SPLIT_LOCAL_NETOBJECT, SPLIT_SERVER_NETOBJECT, SPLIT_CLIENT_NETOBJECT, SPLIT_CONNECTION, SPLIT_SUBSCRIBER, SPLIT_LOCAL_NETWORKPREFIX, SPLIT_SESSIONCONTEXTOBJECT
  • max_connections (int) - Limit number of connections, or 0 for unlimited.
  • flags (list of str) - List of the flags to set, if any. Flags can be any combination of: 'brown', 'host_fairness'
  • split_argument (int) - NetObject to use for subscriber names used for split-by-subscriber, or prefix length for split-by-localnetworkprefix or SessionContextObject for SPLIT_SESSIONCONTEXTOBJECT
Exceptions raised:
  • PLDBUnsupportedInFirmware - If split_argument arguments are used and firmware doesn't support them.
  • split_argument parameter requires v13.1 firmware or newer.

shapingobject_find(self, name, systemid=None)

Find a shaping object by its name

>>> r.shapingobject_find('Unlimited')
<PacketLogic ShapingObject ('Unlimited', limits=<inbound=<Unlimited>, outbound=<Unlimited>, bidir=<Unlimited>>, split=0, max_connections=0, flags=[])>
Returns:
Parameters:
  • name (str) - Name of shaping object to find

shapingobject_find_id(self, object_id, systemid=None)

Find a shaping object by its id

>>> r.shapingobject_find_id(83)
<PacketLogic ShapingObject ('Unlimited', limits=<inbound=<Unlimited>, outbound=<Unlimited>, bidir=<Unlimited>>, split=0, max_connections=0, flags=[])>
Returns:
Parameters:
  • object_id (int) - Id of shaping object to find

shapingobject_list(self)

Return a list of all shaping objects.

>>> r.shapingobject_list()
[<PacketLogic ShapingObject ('Unlimited', limits=<inbound=<Unlimited>, outbound=<Unlimited>, bidir=<Unlimited>>, split=0, max_connections=0, flags=[])>,
 <PacketLogic ShapingObject ('Per host 1Mbps', limits=<inbound=<bps=1000000>, outbound=<bps=1000000>, bidir=<Unlimited>>, split=1, max_connections=0, flags=[])>]
Returns:

shapingobject_remove(self, object)

Remove shaping object

>>> r.shapingobject_add("Example")
<PacketLogic ShapingObject ('Example', limits=<inbound=<Unlimited>, outbound=<Unlimited>, bidir=<Unlimited>>, split=0, max_connections=0, flags=[])>
>>> r.shapingobject_remove("Example")
>>> object = r.shapingobject_add("Example")
>>> r.shapingobject_remove(object)
Parameters:
  • object (str or plrule.FwRule ) - The name or actual rule to be removed.
Exceptions raised:
  • ValueError - If shaping object is not found

shapingrule_add(self, name, priority=5, precedence=0, fair_factor=1, rulecondition=0)

Create a new shapingrule in pldb

>>> r.shapingrule_add('Example')
<PacketLogic Rule 'Example'>
>>> r.shapingrule_add('Example2', priority=20)
<PacketLogic Rule 'Example2'>
Returns:
Parameters:
  • name (str) - Name of the new rule
  • priority (int) - Priority of packets matching this rule
  • precedence (int) - This rule's precedence
  • fair_factor (int) - Fairness factor

shapingrule_find(self, name, systemid=None)

Find a shapingrule by name

>>> r.shapingrule_find('Example')
<PacketLogic Rule 'Example'>
Returns:
Parameters:
  • name (str) - Name of shaping rule to find

shapingrule_find_id(self, rule_id, systemid=None)

Find a shapingrule by id

>>> r.shapingrule_find(27)
<PacketLogic Rule 'Example'>
Returns:
Parameters:
  • rule_id (int) - Id of shaping rule to find

shapingrule_list(self)

Return a list of all shaping rules.

>>> r.shapingrule_list()
[<PacketLogic Rule 'Example'>, <PacketLogic Rule 'Example2'>]
Returns:

shapingrule_remove(self, rule)

Remove shaping rule

>>> r.shapingrule_add('Example')
<PacketLogic Rule 'Example'>
>>> r.shapingrule_remove('Example')
>>> rule = r.shapingrule_add('Example')
>>> r.shapingrule_remove(rule)
Parameters:
Exceptions raised:
  • ValueError - If shaping rule is not found

statisticsobject_add(self, name, total_fields, graph_fields, split, no_root=0, so_root=0, graph_freq=300, min_bytes_in=102400, min_bytes_out=102400)

Create a new StatisticsObject in pldb

>>> s = pl.Statistics()
>>> r.statisticsobject_add('Test Statistics', 
    s.TOTALFIELD_BYTES_IN | s.TOTALFIELD_BYTES_OUT,
    s.GRAPHFIELD_BPS_IN | s.GRAPHFIELD_BPS_OUT | s.GRAPHFIELD_CPS,
    "(NEO:2(SEO))")
<PacketLogic StatisticsObject 'Test Statistics'>
Returns:
Parameters:
  • name (str) - Name of the new object
  • total_fields (int) - Bitmask of fields to store total values for.
  • graph_fields (int) - Bitmask of fields to store graphs for.
  • split (str) - String describing distribution to use.
  • no_root (int) - ID of NetObject to use as root.
  • so_root (int) - ID of ServiceObject to use as root.
  • graph_freq (int) -
  • min_bytes_in (int) - Threshold for inbound values. Values below this threshold are not stored.
  • min_bytes_out (int) - Threshold for outbound values. Values below this threshold are not stored.
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsobject_find(self, name, systemid=None)

Find a statistics object by its name

>>> r.statisticsobject_find('Test Statistics')
<PacketLogic StatisticsObject>
Returns:
Parameters:
  • name (str) - Name of statistics object to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsobject_find_id(self, object_id, systemid=None)

Find a statistics object by its id

>>> r.statisticsobject_find_id(83)
<PacketLogic StatisticsObject>
Returns:
Parameters:
  • object_id (int) - Id of statistics object to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsobject_list(self)

Return a list of all statistics objects.

>>> r.statisticsobject_list()
[<PacketLogic StatisticsObject>,
 <PacketLogic StatisticsObject>]
Returns:
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsobject_remove(self, object)

Remove statistics object

>>> r.statisticsobject_add("Example")
<PacketLogic StatisticsObject ('Example')>
>>> r.statisticsobject_remove("Example")
>>> object = r.statisticsobject_add("Example")
>>> r.statisticsobject_remove(object)
Parameters:
  • object (str or statisticsobject.StatisticObject ) - The name or actual rule to be removed.
Exceptions raised:
  • ValueError - If statistics object is not found
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsrule_add(self, name, rulecondition=0)

Create a new statisticsrule in pldb

>>> r.statisticsrule_add('Example')
<PacketLogic Rule 'Example'>
>>> r.statisticsrule_add('Example2', priority=20)
<PacketLogic Rule 'Example2'>
Returns:
Parameters:
  • name (str) - Name of the new rule
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsrule_find(self, name, systemid=None)

Find a statisticsrule by name

>>> r.statisticsrule_find('Example')
<PacketLogic Rule 'Example'>
Returns:
Parameters:
  • name (str) - Name of statistics rule to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsrule_find_id(self, rule_id, systemid=None)

Find a statisticsrule by id

>>> r.statisticsrule_find(27)
<PacketLogic Rule 'Example'>
Returns:
Parameters:
  • rule_id (int) - Id of statistics rule to find
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsrule_list(self)

Return a list of all statistics rules.

>>> r.statisticsrule_list()
[<PacketLogic Rule 'Example'>, <PacketLogic Rule 'Example2'>]
Returns:
Exceptions raised:
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

statisticsrule_remove(self, rule)

Remove statistics rule

>>> r.statisticsrule_add('Example')
<PacketLogic Rule 'Example'>
>>> r.statisticsrule_remove('Example')
>>> rule = r.statisticsrule_add('Example')
>>> r.statisticsrule_remove(rule)
Parameters:
Exceptions raised:
  • ValueError - If statistics rule is not found
  • PLDUnsupportedInFirmware - If firmware doesn't support this function.
  • This function requires v12.0 firmware or newer.

unlink(self, path)

Removes an Object for all firewall and shapingrules.

This method will soon be deprecated. Use synonym object_unlink instead.

Parameters:
  • path (str) - The Object to be removed.

wait_for_commit(self, pinginterval=60)

Wait for new data to be committed on resource.

This method returns as soon as the server signals that another client has committed new data to the resource. It also periodically tests the connection to the server. If connection is broken (or any other error happens) an exception is raised.

Parameters:
  • pinginterval (int) - Interval used to check if connection still is alive.

xfb_flags_list(self)

List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects.

Returns:
  • List of XFB flags
  • list of str

commitid

The CommitID associated with this session. (14.0 or newer only)