Module: base¶
Inheritance diagram¶
Class Reference¶
Base object classes for inheritence by other classes
-
class
panos.base.
OpStateContainer
(obj, config)[source]¶ Container for all opstate namespaces.
The name “opstate” is short for “operational state” and acts as a container for non-configuration functionality to exist.
-
class
panos.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
Updates a license using the given auth code.
Modifies the live device
Parameters: code (str) – The authorization code. Raises: PanActivateFeatureAuthCodeError
-
commit
(sync=False, exception=False, cmd=None, admins=None, sync_all=False)[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
- sync_all (bool) – If this is a Panorama commit, wait for firewalls jobs to finish (Default: False)
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
panos.firewall.Firewall
orpanos.panorama.Panorama
object from a live deviceConnects 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:
-
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
-
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
-
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
panos.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, quote='"')[source]¶ Perform operational command on this device
Operational commands are most any command that is not a debug or config command. These include many ‘show’ commands such as
show system info
.When passing the cmd as a command string (not XML) you must include any non-keyword strings in the command inside double quotes (
"
). Here’s some examples:# The string "facebook-base" must be in quotes because it is not a keyword fw.op('clear session all filter application "facebook-base"') # The string "ethernet1/1" must be in quotes because it is not a keyword fw.op('show interface "ethernet1/1"') # Using an alternative quote character to get DHCP info on ethernet1/1 fw.op('show dhcp client state `ethernet1/1`', quote='`')
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
- quote (str) – The quote character when the supplied cmd is a string and cmd_xml=True
Returns: The result of the operational command. May also return a string of XML if xml=True
Return type: xml.etree.ElementTree
-
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
-
plugins
()[source]¶ Returns plugin information.
- Each dict in the list returned has the following keys:
- name
- version
- release_date
- release_note_url
- package_file
- size
- platform
- installed
- downloaded
Returns: list of dicts
-
predefined
= None¶ Predefined object subsystem
See Also:
panos.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:
- PAN-OS version
- platform
- serial
- content version (if this is a
panos.firewall.Firewall
) - multi_vsys (if this is a
panos.firewall.Firewall
)
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 pan-os-python 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:
- self.ha_failed is set to False
- 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
-
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
-
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:
panos.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
panos.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 pan-os-python 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_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 pan-os-python object tree for ethernet1/5 would be removed.
-
devicegroup
()[source]¶ The nearest
panos.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 comparableReturns: 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:
-
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:
-
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
-
hierarchy_info
()[source]¶ This function returns hierarchical information about this object.
All objects in pan-os-python can be added as children to other objects, so this function details what configurations are valid for this particular object.
Returns: Hierarchy information about this object. Return type: dict
-
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:
-
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 pan-os-python 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 pan-os-python 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 pan-os-python object tree, the parent object must be a rulebase object.
Raises: ValueError
-
nearest_pandevice
()[source]¶ The nearest
panos.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
panos.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 pan-os-python 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 pan-os-python 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
panos.firewall.Firewall
orpanos.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:
- The base tag of root is valid
- The root element must be a valid ElementTree object
- 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
panos.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.
-
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 fullVersionedPanObject
’s XML, then None is returned.Return type: xml.etree.ElementTree
-
parse_value_from_xml_last_tag
(elm, settings, attr)[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.
- attr (str) – For vartype=”attrib”, the attribute name.
Raises: ValueError
– If a param is in an incorrect format.- elm (xml.etree.ElementTree) – The final (deepest) tag in the XML
document passed in to
-
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
panos.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
panos.base.
ValueEntry
(*args, **kwargs)[source]¶ Base class for objects that only have a value element.
-
class
panos.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.
-
class
panos.base.
VersionedPanObject
(*args, **kwargs)[source]¶ Base class for all versioned package objects.
This class is an extention of
panos.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 comparableReturns: True if the XML of the objects is equal, False if not
Return type: bool
-
class
panos.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 theParamPath
object. Thename
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 apath
, then this means that the variable will only be present in the resulting XML if anotherVersionedParamPath
references this parameter in it’spath
.
-
class
panos.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 returnsvalue
.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
panos.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_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 pan-os-python 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:
-