Module: base

Inheritance diagram

Inheritance diagram of pandevice.base

Class Reference

Base object classes for inheritence by other classes

class pandevice.base.PanDevice(hostname, api_username=None, api_password=None, api_key=None, port=443, is_virtual=None, timeout=1200, interval=0.5, *args, **kwargs)[source]

A Palo Alto Networks device

The device can be of any type (currently supported devices are firewall, or panorama). The class handles common device functions that apply to all device types.

Usually this class is not instantiated directly. It is the base class for a firewall.Firewall object or a panorama.Panorama object.

Parameters:
  • hostname – Hostname or IP of device for API connections
  • api_username – Username of administrator to access API
  • api_password – Password of administrator to access API
  • api_key – The API Key for connecting to the device’s API
  • port – Port of device for API connections
  • is_virtual (bool) – Physical or Virtual firewall
  • timeout – The timeout for asynchronous jobs
  • interval – The interval to check asynchronous jobs
ha_peer

The HA peer device of this PanDevice

Type:PanDevice
activate()[source]

Make this PanDevice active and the other passive

activate_feature_using_authorization_code(code)[source]

Updates a license using the given auth code.

Modifies the live device

Parameters:code (str) – The authorization code.
Raises:PanActivateFeatureAuthCodeError
active()[source]

Return the active device in the HA Pair

clock()[source]

Gets the current time on PAN-OS.

Returns:datetime.datetime
commit(sync=False, exception=False, cmd=None, admins=None)[source]

Trigger a commit

Parameters:
  • sync (bool) – Block until the commit is finished (Default: False)
  • exception (bool) – Create an exception on commit errors (Default: False)
  • cmd (str) – Commit options in XML format
  • admins (str/list) – name or list of admins whose changes need to be committed
Returns:

Commit results

Return type:

dict

config_sync_state()[source]

Get the current configuration synchronization state from the live device

Returns:Current configuration sync state, or None if HA is not enabled
Return type:str
config_synced()[source]

Check if configuration is synchronized between HA peers

Returns:True if synchronized, False if not
Return type:bool
classmethod create_from_device(hostname, api_username=None, api_password=None, api_key=None, port=443)[source]

Factory method to create a pandevice.firewall.Firewall or pandevice.panorama.Panorama object from a live device

Connects to the device and detects its type and current state in order to create a PanDevice subclass.

Parameters:
  • hostname – Hostname or IP of device for API connections
  • api_username – Username of administrator to access API
  • api_password – Password of administrator to access API
  • api_key – The API Key for connecting to the device’s API
  • port – Port of device for API connections
Returns:

New subclass instance (Firewall or Panorama instance)

Return type:

PanDevice

fetch_licenses_from_license_server()[source]

Fetches licenses from the license server.

Modifies the live device

Note: For namedtuple objects, you can access the variables via its index like a normal tuple or via name like a class.

Returns:A list of namedtuples of the licenses with the following attributes:
  • feature (str): the feature name
  • description (str): description
  • serial (str): the license’s serial number
  • issued (datetime.date/None): issue date
  • expires (datetime.date/None): expiration date, or None if the license does not expire
  • expired (bool): True if the license is currently expired
  • authcode (str/None): license’s authcode
Return type:list
get_device_version()[source]

Gets the current version on the PanDevice.

ha_pair()[source]

List containing this firewall and its HA peer

Returns:
self and self.ha_peer in a list. If there is not ha_peer, then
a single item list containing only self is returned.
Return type:list
is_active()[source]

Return True if this device is active

map_ha(method_name, *args, **kwargs)[source]

Apply to both devices in HA Pair

Invoke a method of this class on both this instance and its HA peer

Parameters:
  • method_name – The name of the method in this class (or subclass) to invoke
  • *args – Arguments to pass to the method
  • **kwargs – Keyword arguments to pass to the method
Returns:

A tuple of the return values of invoking the method on each device. The first item in the tuple is always from invoking the method on self, and the second item is from invoking the method on the ha_peer. The second item is None if there is no HA Peer.

nearest_pandevice()[source]

The nearest pandevice.base.PanDevice object.

This method is used to determine the device to apply this object to.

Returns:
The PanDevice object closest to this object in
the configuration tree.
Return type:PanDevice
Raises:PanDeviceNotSet – There is no PanDevice object in the tree.
op(cmd=None, vsys=None, xml=False, cmd_xml=True, extra_qs=None, retry_on_peer=False)[source]

Perform operational command on this device

Parameters:
  • cmd (str) – The operational command to execute
  • vsys (str) – Vsys id.
  • xml (bool) – Return value should be a string (Default: False)
  • cmd_xml (bool) – True: cmd is not XML, False: cmd is XML (Default: True)
  • extra_qs – Extra parameters for API call
  • retry_on_peer (bool) – Try on active Firewall first, then try on passive Firewall
Returns:

The result of the operational command. May also return a string of XML if xml=True

Return type:

xml.etree.ElementTree

passive()[source]

Return the passive device in the HA Pair

pending_changes(retry_on_peer=True)[source]

Check if there are pending changes on the live device

Parameters:retry_on_peer (bool) – Try on active Firewall first, if connection error try on passive Firewall
Returns:True if pending changes, False if not
Return type:bool
predefined = None

Predefined object subsystem

See Also: pandevice.predefined

refresh_ha_active()[source]

Refresh which device is active using the live device

Returns:Current HA state of this device
Return type:str
refresh_system_info()[source]

Refresh system information variables.

Variables refreshed:

Returns:version, platform, serial
Return type:namedtuple
refresh_version()[source]

Refresh version of PAN-OS

Version is stored in self.version and returned

Returns:version of PAN-OS
Return type:str
request_license_info()[source]

Returns the licenses currently installed on this device.

Touches the live device

Note: For namedtuple objects, you can access the variables via its index like a normal tuple or via name like a class.

Returns:A list of namedtuples of the licenses with the following attributes:
  • feature (str): the feature name
  • description (str): description
  • serial (str): the license’s serial number
  • issued (datetime.date/None): issue date
  • expires (datetime.date/None): expiration date, or None if the license does not expire
  • expired (bool): True if the license is currently expired
  • authcode (str/None): license’s authcode
Return type:list
request_password_hash(value)[source]

Request a password hash from the live device.

This function does not modify the live device, but it does interact with the live device to generate the password hash.

Parameters:value (str) – The password
Returns:A hashed version of the password provided.
Return type:str
Raises:ValueError – If the password hash is not found.
set_config_changed(scope=None)[source]

Set flag that configuration of this device has changed

This is useful for checking if a commit is necessary by knowing if the configuration was actually changed. This method is already used by every pandevice package method that makes a configuration change. But this method could also by run directly to force a ‘dirty’ configuration state in a PanDevice object.

Parameters:scope – vsys in which configuration was changed, or ‘shared’
set_dns_servers(primary, secondary=None)[source]

Set the device DNS Servers

Convenience method to set the firewall or Panorama dns servers

Parameters:
  • primary (str) – IP address of primary DNS server
  • secondary (str) – IP address of secondary DNS server
set_failed()[source]

Set this PanDevice as a failed HA Peer

API calls will no longer be attempted to this device until one of the following conditions:

  1. self.ha_failed is set to False
  2. self.ha_failed is set to True on the peer device
Returns:The HA Peer device
Return type:PanDevice
set_ha_peers(device)[source]

Establish an HA peer relationship between two PanDevice objects

Parameters:device – The HA peer device
set_hostname(hostname)[source]

Set the device hostname

Convenience method to set the firewall or Panorama hostname

Parameters:hostname (str) – hostname to set (should never be None)
set_ntp_servers(primary, secondary=None)[source]

Set the device NTP Servers

Convenience method to set the firewall or Panorama NTP servers

Parameters:
  • primary (str) – IP address of primary DNS server
  • secondary (str) – IP address of secondary DNS server
synchronize_config()[source]

Force configuration synchronization from this device to its HA peer

syncjob(job_id, sync_all=False, interval=0.5)[source]

Block until job completes and return result

Parameters:
  • job_id (int) – job ID, or response XML from job creation
  • sync_all (bool) – Wait for all devices to complete if commit all operation
  • interval (float) – Interval in seconds to check if job is complete
Returns:

Job result

Return type:

dict

syncreboot(interval=5.0, timeout=600)[source]

Block until reboot completes and return version of device

test_security_policy_match(source, destination, protocol, application=None, category=None, port=None, user=None, from_zone=None, to_zone=None, show_all=False)[source]

Test security policy match using the given criteria.

This function will always return a list for its results. If show_all is set to False, then the list will only have one entry in it. The keys in each dict are as follows:

  • name (str): rule’s name
  • index (int): the index of the security rule
  • action (str): the security rule’s action
Parameters:
  • source (str) – Source IP address.
  • destination (str) – Destination IP address.
  • protocol (int) – IP protocol value (1-255).
  • application (str) – Application name.
  • category (str) – Category name.
  • port (int) – Destination port.
  • user (str) – Source user.
  • from_zone (str) – Source zone name.
  • to_zone (str) – Destination zone name.
  • show_all (bool) – Show all potential match rules until first allow.
Returns:

List of dicts

toggle_ha_active()[source]

Switch the active device in this HA Pair

update_connection_method()[source]

Regenerate the xapi object used to connect to the device

This is only necessary if the API key, password, hostname, or other connectivity information in this object has changed. In this case, the xapi object used to communicate with the firewall must be regenerated to use the new connectivity information.

The new xapi is stored in the PanDevice object and returned.

Returns:The xapi object which is also stored in self.xapi.
Return type:XapiWrapper
userid = None

User-ID subsystem

See Also: pandevice.userid

watch_op(cmd, path, value, vsys=None, cmd_xml=True, interval=1.0)[source]

Watch an operational command for an expected value

Blocks script execution until the value exists or timeout expires

Parameters:
  • cmd (str) – Operational command to run
  • path (str) – XPath to the value to watch
  • value (str) – The value expected before method completes
  • vsys (str) – Vsys id for the operational command
  • cmd_xml (bool) – True: cmd is not XML, False: cmd is XML (Default: True)
  • interval (float) – Interval in seconds to check if the value exists
class pandevice.base.PanObject(*args, **kwargs)[source]

Base class for all package objects

This class defines an object that can be placed in a tree to generate configuration.

Parameters:name (str) – The name of this object
uid

The unique identifier for this object if it has one. If it doesn’t have one, then this returns the class name.

Type:str
vsys

The vsys id for this object (eg. ‘vsys2’) or ‘shared’ if no vsys

Type:str
about(parameter=None)[source]

Return information about this object or the given parameter.

If no parameter is specified, then invoking this function is similar to doing vars(obj): it will return a dict of key/value pairs, with the difference being that the keys are all specifically parameters attached to this VersionedPanObject, and the values being what the current settings are for those keys.

If a parameter is specified and this object is connected to a parent PanDevice, then version specific information on the parameter is returned.

If a parameter is specified but this object is not connected to a PanDevice instance, then all versioning information for the given parameter is returned.

Parameters:parameter (str) – The parameter to get info for.
Returns:An informational dict about either the object as a whole or the specified parameter.
Return type:dict
Raises:AttributeError – If a parameter is specified that does not exist on this object.
add(child)[source]

Add a child node to this node

Parameters:child (PanObject) – Node to add as a child
Returns:Child node
Return type:PanObject
apply()[source]

Apply this object to the device, replacing any existing object of the same name

Modifies the live device

apply_similar()[source]

Bulk apply all objects similar to this one.

Modifies the live device

This is similar to apply(), except instead of calling apply only on this object, it calls apply for all objects that share the same xpath as this object, recursively searching the entire object tree from the nearest firewall or panorama instance.

As an example, if you called apply_similar on an object representing ethernet1/5.42, all of the subinterfaces for ethernet1/5 would be included in the resulting XML document, regardless of which vsys those subinterfaces existed in.

Since apply does a replace of the config at the given xpath, please be careful when using this function that all objects, whether they be updated or not, exist in your pandevice object tree.

create()[source]

Create this object on the device

Modifies the live device

This method is nondestructive. If the object exists, the variables are added to the device without changing existing variables on the device. If a variables already exists on the device and this object has a different value, the value on the firewall is changed to the value in this object.

create_similar()[source]

Bulk create all objects similar to this one.

Modifies the live device

This is similar to create(), except instead of calling create only on this object, it calls create for all objects that share the same xpath as this object, recursively searching the entire object tree from the nearest firewall or panorama instance.

As an example, if you called create_similar on an object representing ethernet1/5.42, all of the subinterfaces for ethernet1/5 would be included in the resulting XML document, regardless of which vsys those subinterfaces existed in.

delete()[source]

Delete this object from the firewall

Modifies the live device

delete_similar()[source]

Bulk delete all objects similar to this one.

Modifies the live device

This is similar to delete(), except instead of calling delete only on this object, it calls delete for all objects that share the same xpath as this object, recursively searching the entire object tree from the nearest firewall or panorama instance.

As an example, if you called delete_similar on an object representing ethernet1/5.42, all of the subinterfaces in your pandevice object tree for ethernet1/5 would be removed.

devicegroup()[source]

The nearest pandevice.panorama.DeviceGroup object.

This method is used to determine the device to apply this object to.

Returns:The DeviceGroup object closest to this object in the configuration tree, or None if there is no DeviceGroup in the path to this node.
Return type:DeviceGroup
element(with_children=True, comparable=False)[source]

Construct an ElementTree for this PanObject and all its children

Parameters:
  • with_children (bool) – Include children in element.
  • comparable (bool) – Element will be used in a comparison with another.
Returns:

An ElementTree instance representing the

xml form of this object and its children

Return type:

xml.etree.ElementTree

element_str(pretty_print=False)[source]

The XML representation of this PanObject and all its children.

Parameters:pretty_print (bool) – Return the resulting string pretty_printed with indentation.
Returns:XML form of this object and its children
Return type:str
equal(panobject, force=False, compare_children=True)[source]

Compare this object to another object

Equality of the objects is determined by the XML they generate, not by the values of their variables.

Parameters:
  • panobject (PanObject) – The object to compare with this object
  • force (bool) – Do not raise a PanObjectError if the objects are different classes
  • compare_children (bool) – Not supported in this object, use True
Raises:

PanObjectError – Raised if the objects are different types that would not normally be comparable

Returns:

True if the XML of the objects is equal, False if not

Return type:

bool

extend(children)[source]

Add a list of child nodes to this node

Parameters:children (list) – List of PanObject instances
find(name, class_type=None, recursive=False)[source]

Find an object in the configuration tree by name

Parameters:
  • name (str) – Name of the object to find
  • class_type – Class to look for
  • recursive (bool) – Find recursively (Default: False)
Returns:

The object in the tree that fits the criteria, or None if no object is found

Return type:

PanObject

find_index(name=None, class_type=None)[source]

Finds the first index of the given name and class type.

If name is None, just find the first instance of class_type.

If class_type is unspecified, it defaults to the current class type.

Parameters:
  • name (str) – Name of the child node
  • class_type (class) – Restrict the find to children of this type
Returns:

the index of the first matching child

Return type:

int

find_or_create(name, class_type, *args, **kwargs)[source]

Find an object in the configuration tree by name, and create it if it doesn’t exist

If the object does not exist, it is created and added to the current object.

Parameters:
  • name (str) – Name of the object to find
  • class_type – Class to look for or create
  • *args – Arguments to pass to the __init__ method of class_type
  • *kwargs – Keyworkd arguments to pass to the __init__ method of class_type
Returns:

The object in the tree that fits the criteria, or None if no object is found

Return type:

PanObject

findall(class_type, recursive=False)[source]

Find all objects of a class in configuration tree

Parameters:
  • class_type – Class to look for
  • recursive (bool) – Find recursively (Default: False)
Returns:

List of ‘class_type’ objects

Return type:

list

findall_or_create(class_type, *args, **kwargs)[source]

Find all object in the configuration tree by class, and create a new object if none exist

If no objects of this type exist, one is created and added to the current object.

Parameters:
  • class_type – Class to look for or create
  • *args – Arguments to pass to the __init__ method of class_type
  • *kwargs – Keyworkd arguments to pass to the __init__ method of class_type
Returns:

List of ‘class_type’ objects

Return type:

list

fulltree()[source]

Display a graph of the entire configuration tree

This method is only for use in Jupyder Notebooks

insert(index, child)[source]

Insert a child node at a specific index

This is useful for ordering or reordering security policy rules

Parameters:
  • index (int) – The index where the child obj should be inserted
  • child (PanObject) – Node to add as a child
Returns:

Child node

Return type:

PanObject

move(location, ref=None, update=True)[source]

Moves the current object.

Modifies the live device

This is useful for stuff like moving one security policy above another.

If this object’s parent is a rulebase object, then this object is also moved to the appropriate position in the local pandevice object tree.

Parameters:
  • location (str) – Any of the following: before, after, top, or bottom
  • ref (PanObject/str) – If location is “before” or “after”, move this object before/after the ref object. If this is a string, then the string should just be the name of the object.
  • update (bool) – If this is set to False, then only move this object in the pandevice object tree, do not actually perform the MOVE operation on the live device. Note that in order for this object to be moved in the pandevice object tree, the parent object must be a rulebase object.
Raises:

ValueError

nearest_pandevice()[source]

The nearest pandevice.base.PanDevice object to.

This method is used to determine the device to apply this object.

Returns:
The PanDevice object closest to this object in
the configuration tree.
Return type:PanDevice
Raises:PanDeviceNotSet – There is no PanDevice object in the tree.
panorama()[source]

The nearest pandevice.panorama.Panorama object.

This method is used to determine the device to apply this object to.

Returns:
The Panorama object closest to this object in the
configuration tree
Return type:Panorama
Raises:PanDeviceNotSet – There is no Panorama object in the tree.
pop(index)[source]

Remove and return the object at an index

Parameters:index (int) – Index of the object to remove and return
Returns:The object removed from the children of this node
Return type:PanObject
refresh(running_config=False, refresh_children=True, exceptions=True, xml=None)[source]

Refresh all variables and child objects from the device.

Parameters:
  • running_config (bool) – Set to True to refresh from the running configuration (Default: False)
  • xml (xml.etree.ElementTree) – XML from a configuration to use instead of refreshing from a live device
  • refresh_children (bool) – Set to False to prevent refresh of child objects (Default: True)
  • exceptions (bool) – Set to False to prevent exceptions on failure (Default: True)
refresh_variable(variable, running_config=False, exceptions=False)[source]

Refresh a single variable of an object.

Don’t use for variables with replacements or selections in path.

Parameters:
  • variable (str) – Variable name to refresh.
  • running_config (bool) – Set to True to refresh from the running configuration (Default: False)
  • exceptions (bool) – Set to False to prevent exceptions on failure (Default: True)
Returns:

New value of the refreshed variable.

Raises:

PanObjectMissing – When the object this variable is connected to does not exist.

classmethod refreshall(parent, running_config=False, add=True, exceptions=False, name_only=False)[source]

Factory method to instantiate class from live device.

This method is a factory for the class. It takes an firewall or Panorama and gets the xml config from the live device. It generates instances of this class for each item this class represents in the xml config. For example, if the class is AddressObject and there are 5 address objects on the firewall, then this method will generate 5 instances of the class AddressObject.

Parameters:
  • parent (PanObject) – A PanDevice, or a PanObject subclass with a PanDevice as its parental root.
  • running_config (bool) – False for candidate config, True for running config.
  • add (bool) – Update the objects of this type in pandevice with the refreshed values.
  • exceptions (bool) – If False, exceptions are ignored if the xpath can’t be found.
  • name_only (bool) – If True, refresh only the name of the object, but not its variables. This results in a smaller response to the API call when only the object name is needed.
Returns:

created instances of class

Return type:

list

refreshall_from_xml(xml, refresh_children=True, variables=None)[source]

Factory method to instantiate class from firewall config.

This method is a factory for the class. It takes an xml config from a firewall and generates instances of this class for each item this class represents in the xml config. For example, if the class is AddressObject and there are 5 address objects on the firewall, then this method will generate 5 instances of the class AddressObject.

Parameters:
  • xml (xml.etree.ElementTree) – A section of XML configuration from a firewall or Panorama. It should not contain the response or result tags.
  • refresh_children (bool) – Refresh children objects or not.
  • variables (iterable) – A list or tuple of the variables to parse from the XML. Note that this is only used when invoked against classes not derived from VersionedPanObject.
Returns:

created instances of class

Return type:

list

remove(child)[source]

Remove the child from this node

Parameters:child (PanObject) – Child to remove
remove_by_name(name, cls=None)[source]

Remove a child node by name

If the class is not specified, then it defaults to type(self).

Parameters:name (str) – Name of the child node
Keyword Arguments:
 cls (class) – Restrict removal to instances of this class
Returns:The removed node, otherwise None
Return type:PanObject
removeall(cls=None)[source]

Remove all children of a type

Not recursive.

Parameters:cls (class) – The class of objects to remove
Returns:List of PanObjects that were removed
Return type:list
rename(new_name)[source]

Change the name of this object.

Modifies the live device

NOTE: This does not change any references that may exist in your pandevice object hierarchy, but it does update the name of the object itself.

Parameters:new_name (str) – The new UID for this object.
retrieve_panos_version()[source]

Gets the panos_version of the closest PanDevice.

If this object is not attached to a PanDevice, then a very large number is returned to ensure that the newest version of the object and xpath is presented to the user.

Returns:The version as (x, y, z)
Return type:tuple
tree()[source]

Display a graph of the configuration tree

The tree includes this object and its children, recursively.

This method is only for use in Jupyder Notebooks

uid

Returns the unique identifier of this object as a string.

update(variable)[source]

Change the value of a variable

Modifies the live device

Do not attempt this on an element variable (|) or variable with replacement {{}} If the variable’s value is None, then a delete API call is attempted.

Parameters:variable (str) – The name of an instance variable to update on the device
classmethod variables()[source]

Defines the variables that exist in this object. Override in each subclass.

vsys

Return the vsys for this object

Traverses the tree to determine the vsys from a pandevice.firewall.Firewall or pandevice.device.Vsys instance somewhere before this node in the tree.

Returns:The vsys id (eg. vsys2)
Return type:str
xml_merge(root, elements)[source]

Merges other elements into the root element.

This differs from xml_combine in a few important ways:

  1. The base tag of root is valid
  2. The root element must be a valid ElementTree object
  3. Individual Nones in the elements iterable are ignored
Parameters:
  • root (xml.etree.ElementTree) – The root element.
  • elements (iterable) – Other xml.etree.ElementTree instances (or None) that should be merged into root as well.
Returns:

The final merged root element.

Return type:

xml.etree.ElementTree

xpath(root=None)[source]

Return the full xpath for this object

Xpath in the form: parent’s xpath + this object’s xpath + entry or member if applicable.

Parameters:root – The root to use for this object (default: this object’s root)
Returns:The full xpath to this object
Return type:str
xpath_nosuffix()[source]

Return the xpath without the suffix

This is used by refreshall().

Returns:The xpath without entry or member on the end
Return type:str
xpath_short(root=None)[source]

Return an xpath for this object without the final segment

Xpath in the form: parent’s xpath + this object’s xpath. Used for set API calls.

Parameters:root – The root to use for this object (default: this object’s root)
Returns:The xpath without the final segment
Return type:str
class pandevice.base.ParamPath(param, path=None, vartype=None, condition=None, values=None, exclude=False)[source]

Configuration parameter within the object.

Parameters:
  • param (str) – The name of the instance parameter in the class
  • path – The relative xpath to the variable.
  • vartype – The type of variable (None, ‘member’, ‘entry’, ‘yesno’, ‘int’, ‘exist’).
  • condition (dict) – Other settings that must be true for this param to appear in the XML. The keys of the condition should be other parameter names, with the value being what the necessary value of that parameter should be.
  • values (list) – Valid values this param can be set to. This is not enforced in any way from the user’s perspective when setting parameters, but these values are referenced when parsing any XML returned from a live device.
  • exclude (bool) – Exclude this param from the resultant XML.
about(version_header=None)[source]

Returns information about this ParamPath as a dict.

element(elm, settings, comparable=False)[source]

Create the xml.etree.ElementTree for this parameter.

Parameters:
  • elm (xml.etree.ElementTree) – the root node for which to append onto this param’s XML.
  • settings (dict) – All parameter settings for the VersionedPanObject.
  • comparable (bool) – Make necessary adjustments to the XML for comparison’s sake.
Returns:

The elm passed in, modified to contain this parameter in the XML. If this param should not be contained in the full VersionedPanObject’s XML, then None is returned.

Return type:

xml.etree.ElementTree

parse_value_from_xml_last_tag(elm, settings)[source]

Actually do the parsing for this parameter.

The value parsed is saved into the settings dict.

Parameters:
  • elm (xml.etree.ElementTree) – The final (deepest) tag in the XML document passed in to parse_xml() that contains the actual value to parse out for this parameter.
  • settings (dict) – The dict where the parsed value will be saved.
Raises:

ValueError – If a param is in an incorrect format.

parse_xml(xml, settings, possibilities)[source]

Parse the XML to find this parameter’s value.

Both this parameter, and any other parameters that may be discovered during the parsing of this parameter, will be saved in the settings dict passed in to this function.

Parameters:
  • xml (xml.etree.ElementTree) – The XML to parse.
  • settings (dict) – Current known values for this object’s parameters.
  • possibilities (dict) – A dict where the key is a parameter’s name, and the value is a list of strings that that param could be in the XML.
class pandevice.base.ParentAwareXpath[source]

Class to handle xpaths of objects.

Some objects have a different xpath based on where in the tree they are located. This class allows you configure various xpaths that can vary both on version and what the parent class is.

If no explicit parent is specified, then the global parent of `None’ is assumed.

add_profile(version=None, value=None, parents=None, parent_param=None, parent_param_values=None)[source]

Adds support for the given versions, specific to the parents.

If no parents are specified, then a parent of None is assumed, which is the global parent type.

Version support per parent must be in ascending order.

Parameters:
  • version (str) – The version number (default: ‘0.0.0’).
  • value (str) – The xpath setting.
  • parents (list/tuple) – The parent classes this version/value is valid for.
  • parent_param (str) – Parent param to key off of.
  • parent_param_values (list) – Values of the parent param to key off of.
class pandevice.base.ValueEntry(*args, **kwargs)[source]

Base class for objects that only have a value element.

class pandevice.base.VarPath(path, variable=None, vartype=None, default=None, xmldefault=None, condition=None, order=100)[source]

Configuration variable within the object

Parameters:
  • path (str) – The relative xpath to the variable
  • variable (str) – The name of the instance variable in the class
  • vartype (str) – The type of variable (None, ‘member’, ‘entry’, ‘bool’, ‘int’, ‘exist’, ‘none’)
  • default – The default value if no value is specified during __init__ of the object
  • xmldefault (bool) – The default value if no value exists in the xml from a device
  • condition (str) – In the format othervariable:value where this variable is only considered if othervariable equals value
  • order (int) – The order of this variable relative to other variables in this constructor of the class that contains this variables. Defaults to 100, set variable order to less than or greater than 100 to alter the order of the variables.
about()[source]

Returns information about this VarPath as a dict.

class pandevice.base.VersionedPanObject(*args, **kwargs)[source]

Base class for all versioned package objects.

This class is an extention of pandevice.base.PanObject that supports versioning.

Parameters:
  • name (str) – The name of this object.
  • *args – Variable length list of values to initialize this object.
  • **kwargs – Keyword args to initialize this object.
uid

The unique identifier for this object if it has one. If it doesn’t have one, then this returns the class name.

Type:str
vsys

The vsys id for this object (e.g. ‘vsys2’) or ‘shared’ if no vsys.

Type:str
XPATH

The xpath for this object, based on where in the tree it currently resides, as well as the versioning.

Type:str
element(with_children=True, comparable=False)[source]

Return an xml.etree.ElementTree for this object and its children.

Parameters:
  • with_children (bool) – Include the children objects.
  • comparable (bool) – Element will be used in a comparison with another.
Returns:

xml.etree.ElementTree for this object.

equal(panobject, force=False, compare_children=True)[source]

Compare this object to another object

Equality of the objects is determined by the XML they generate, not by the values of their variables.

Parameters:
  • panobject (VersionedPanObject) – The object to compare with this object
  • force (bool) – Do not raise a PanObjectError if the objects are different classes
  • compare_children (bool) – Include children of the PanObject in the comparison
Raises:

PanObjectError – Raised if the objects are different types that would not normally be comparable

Returns:

True if the XML of the objects is equal, False if not

Return type:

bool

parse_xml(xml)[source]

Parse the given XML into this object’s parameters.

Parameters:xml (xml.etree.ElementTree) – The XML to parse values from.
class pandevice.base.VersionedParamPath(name, default=None, version=None, **kwargs)[source]

A wrapper class for ParamPath objects.

Specifying any kwargs will be interpreted as args for the first profile to add for this parameter. If there are no kwargs specified, then any version that may or may not have been passed in is ignored.

The values stored in each profile added are the kwargs used to initialize the ParamPath object. The name should not be specified, as that will be passed in positionally for you.

Parameters:
  • name (str) – The parameter name. Any hyphens in the name are replaced with underscores, as hyphens are not a valid variable character.
  • default – The default value this parameter should take when the user is creating a VersionedPanObject, but doesn’t specify a value.
  • version (str) – A version string like ‘1.2.3’ or None. If the version is None, then the version is set to ‘0.0.0’.
  • **kwargs – Various ParamPath parameters for the given version.
add_profile(version=None, **kwargs)[source]

Add support for version version.

Parameters:
  • version (str) – The version to add support for. If this is unspecified, then the version defaults to ‘0.0.0’.
  • **kwargs – The various ParamPath arguments to use for the given version. Note that if your kwargs do not contain a path, then this means that the variable will only be present in the resulting XML if another VersionedParamPath references this parameter in it’s path.
class pandevice.base.VersionedStubs[source]
add_profile(version=None, *paths)[source]

Adds the following stubs for the specified version.

Parameters:
  • version (str) – The version to add support for.
  • *paths (str) – Variable length arg list of paths for this version.
class pandevice.base.VersioningSupport[source]

A class that supports getting version specific values of something.

Versions of the value are added in ascending order using add_profile(), then can be retrieved by using _get_versioned_value(). You can specify how the retrieved value is cast by overriding _cast_version_value().

add_profile(version=None, value=None)[source]

Add support for version version that returns value.

Version support must be added in ascending order.

Parameters:
  • version (str) – The version to add support for. If this is unspecified, then the version defaults to ‘0.0.0’.
  • value – The value to be retrieved for this version.
Raises:

ValueError – If the given version is lower than the most recent version.

class pandevice.base.VsysOperations(*args, **kwargs)[source]

Modify PanObject methods to set vsys import configuration.

XPATH_IMPORT

Returns the version specific xpath import for this object.

apply()[source]

Apply this object to the device, replacing any existing object of the same name

Modifies the live device

create()[source]

Create this object on the device

Modifies the live device

This method is nondestructive. If the object exists, the variables are added to the device without changing existing variables on the device. If a variables already exists on the device and this object has a different value, the value on the firewall is changed to the value in this object.

create_import(vsys=None)[source]

Create a vsys import for the object

Parameters:vsys (str) – Override the vsys
delete()[source]

Delete this object from the firewall

Modifies the live device

delete_import(vsys=None)[source]

Delete a vsys import for the object

Parameters:vsys (str) – Override the vsys
classmethod refreshall(parent, running_config=False, add=True, exceptions=False, name_only=False, matching_vsys=True)[source]

Factory method to instantiate class from live device.

This method is a factory for the class. It takes an firewall or Panorama and gets the xml config from the live device. It generates instances of this class for each item this class represents in the xml config. For example, if the class is AddressObject and there are 5 address objects on the firewall, then this method will generate 5 instances of the class AddressObject.

Parameters:
  • parent (PanObject) – A PanDevice, or a PanObject subclass with a PanDevice as its parental root.
  • running_config (bool) – False for candidate config, True for running config.
  • add (bool) – Update the objects of this type in pandevice with the refreshed values.
  • exceptions (bool) – If False, exceptions are ignored if the xpath can’t be found.
  • name_only (bool) – If True, refresh only the name of the object, but not its variables. This results in a smaller response to the API call when only the object name is needed.
Returns:

created instances of class

Return type:

list

set_vsys(vsys_id, refresh=False, update=False, running_config=False, return_type='object')[source]

Set the vsys for this interface.

Creates a reference to this interface in the specified vsys and removes references to this interface from all other vsys. The vsys will be created if it doesn’t exist.

Parameters:
  • vsys_id (str) – The vsys id to set for this object (eg. vsys2)
  • refresh (bool) – Refresh the relevant current state of the device before taking action (Default: False)
  • update (bool) – Apply the changes to the device (Default: False)
  • running_config (bool) – If refresh is True, refresh from the running configuration (Default: False)
  • return_type (str) – Specify what this function returns, can be either ‘object’ (the default) or ‘bool’. If this is ‘object’, then the return value is the device.Vsys in question. If this is ‘bool’, then the return value is a boolean that tells you about if the live device needs updates (update=False) or was updated (update=True).
Returns:

The vsys for this interface after the operation completes

Return type:

Vsys