Merge branch 'release/0.3.1'

Author: btorresgil

HISTORY.rst

@@ -3,10 +3,34 @@
 History
 =======
 
+0.3.1
+-----
+
+Released: 2016-04-12
+
+Status: Alpha
+
+New objects:
+
+* policies.SecurityRule
+* objects.AddressGroup
+
+API changes:
+
+* Changed refresh_all to refreshall and apply_all to applyall
+* Added insert() method to PanObject base class
+
+Fixes:
+
+* Objects can now be added as children of Panorama which will make them 'shared'
+* Fixes for tracebacks
+* Minor fixes to documentation and docstrings
+
 0.3.0
 -----
 
 Released: 2016-03-30
+
 Status: Alpha
 
 * First release on pypi
@@ -17,6 +41,7 @@ Status: Alpha
 -----
 
 Released: 2014-09-17
+
 Status: Pre-alpha
 
 * First release on github

README.rst

@@ -26,6 +26,15 @@ Features
 - Batch User-ID operations
 - Device API exception classification
 
+Status
+------
+
+Palo Alto Networks Device Framework is considered **alpha**. It is fully tested
+and used in many production environments, but it maintains alpha status because
+the API interface could change at any time without notification. Please be
+prepared to modify your scripts to work with each subsequent version of this
+package because backward compatibility is not guaranteed.
+
 Installation
 ------------
 
@@ -61,7 +70,8 @@ A few examples
 --------------
 
 For configuration tasks, create a tree structure using the classes in
-each module. Nodes hierarchy must follow the :ref:`classtree`.
+each module. Nodes hierarchy must follow the model in the
+`Configuration Tree`_.
 
 The following examples assume the modules were imported as such::
 
@@ -88,6 +98,7 @@ Some operational commands have methods to refresh the variables in an object::
 
 
 .. _pan-python: http://github.com/kevinsteves/pan-python
+.. _Configuration Tree: http://pandevice.readthedocs.org/en/latest/configtree.html
 
 .. |pypi| image:: https://img.shields.io/pypi/v/pandevice.svg
     :target: https://pypi.python.org/pypi/pandevice

docs/configtree.py

@@ -34,13 +34,14 @@
 
 
 nodestyle = {
-    'Firewall':  '',
-    'Panorama':  '',
+    #'Firewall':  '',
+    #'Panorama':  '',
     'device':    'fillcolor=lightpink',
     'firewall':  'fillcolor=lightblue',
     'ha':        'fillcolor=lavender',
     'network':   'fillcolor=lightcyan',
     'objects':   'fillcolor=lemonchiffon',
+    'policies':  'fillcolor=lightsalmon',
     'panorama':  'fillcolor=lightgreen',
 }
 

docs/module-policies.rst

@@ -0,0 +1,13 @@
+Module: policies
+================
+
+Inheritance diagram
+-------------------
+
+.. inheritance-diagram:: pandevice.policies
+   :parts: 1
+
+Class Reference
+---------------
+
+.. automodule:: pandevice.policies

docs/moduleref.py

@@ -36,6 +36,7 @@
     'base',
     'errors',
     'objects',
+    'policies',
     'updater',
     'userid',
 ]

docs/reference.rst

@@ -18,6 +18,7 @@ API Reference
    module-network
    module-objects
    module-panorama
+   module-policies
    module-updater
    module-userid
 

docs/usage.rst

@@ -16,9 +16,10 @@ apply for all the examples on this page::
     from pandevice import base
     from pandevice import firewall
     from pandevice import panorama
+    from pandevice import policies
+    from pandevice import objects
     from pandevice import network
     from pandevice import device
-    from pandevice import objects
 
 Create a PanDevice
 ------------------
@@ -73,7 +74,7 @@ Build the configuration tree: ``add()``, ``remove()``, ``find()``, and ``findall
 Push changed configuration to the live device: ``apply()``, ``create()``,
 and ``delete()``
 
-Pull configuration from the live device: ``refresh()``, ``refresh_all_from_device()``
+Pull configuration from the live device: ``refresh()``, ``refreshall()``
 
 There are other useful methods besides these. See :class:`pandevice.base.PanObject` for
 more information.
@@ -126,7 +127,7 @@ device and add them into the configuration tree::
 
     >>> fw.children
     []
-    >>> objects.AddressObject.refresh_all_from_device(fw, add=True)
+    >>> objects.AddressObject.refreshall(fw, add=True)
     >>> fw.children
     [<pandevice.objects.AddressObject object at 0x108080e90>,
      <pandevice.objects.AddressObject object at 0x108080f50>,
@@ -142,6 +143,105 @@ It's also possible to refresh the variables of an existing object::
     >>> adserver.value
     "4.4.4.4"
 
+Connecting with Panorama
+------------------------
+
+Making changes to Panorama is always done the same way, with a connection to Panorama.
+But, there are a different methods to make local changes to a Firewall.
+
+**Method 1: Connect to the Firewall and Panorama directly**
+
+When making changes to Panorama, connect to Panorama.
+When making changes to the Firewall, connect directly to the Firewall.
+
+.. graphviz::
+
+   digraph directconnect {
+      graph [rankdir=LR, fontsize=10, margin=0.001];
+      node [shape=box, fontsize=10, height=0.001, margin=0.1, ordering=out];
+      "python script" -> "Panorama";
+      "python script" -> "Firewall";
+      Panorama [style=filled];
+      Firewall [style=filled];
+   }
+
+This method is best in the following cases:
+
+- Firewall managment IP is accessible to the script
+- The credentials for both devices are known
+- The permissions/role for the user are set on both devices
+- The serial of the firewall is unknown, but the management IP is known
+
+To use this method:
+
+1. Create a :class:`pandevice.firewall.Firewall` instance and a
+   :class:`pandevice.panorama.Panorama` instance.
+2. In both instances, set the 'hostname' attribute and either the
+   'api_key' or the 'api_username' and 'api_password' attributes.
+
+Example::
+
+    # Instantiate a Firewall with hostname and credentials
+    fw = firewall.Firewall("10.0.0.1", "admin", "mypassword")
+    # Instantiate a Panorama with hostname and credentials
+    pano = panorama.Panorama("10.0.0.5", "admin", "mypassword")
+    # Change to Firewall
+    fw.add(objects.AddressObject("Server", "2.2.2.2")).create()
+    # Change to Panorama
+    pano.add(panorama.DeviceGroup("CustomerA")).create()
+
+In this example, the address object is added to the Firewall directly, without
+any connection to Panorama. Then a device-group is created on Panorama directly,
+without any connection to the Firewall.
+
+**Method 2: Connect to Firewall via Panorama**
+
+When making changes to the Firewall, connect to Panorama which
+will proxy the connection to the Firewall. Meaning all connections
+are to Panorama.
+
+.. graphviz::
+
+   digraph directconnect {
+      graph [rankdir=LR, fontsize=10, margin=0.001];
+      node [shape=box, fontsize=10, height=0.001, margin=0.1, ordering=out];
+      "pandevice script" -> "Panorama" -> "Firewall";
+      Panorama [style=filled];
+      Firewall [style=filled];
+   }
+
+This method is best in the following cases:
+
+- The Firewall management IP is unknown or not rechable from the script
+- You only store one set of credentials (Panorama)
+- The serial of the firewall is known or can be determined from Panorama
+
+To use this method:
+
+1. Create a :class:`pandevice.firewall.Firewall` instance and a
+   :class:`pandevice.panorama.Panorama` instance.
+2. In the Panorama instance, set the 'hostname' attribute and either the
+   'api_key' or the 'api_username' and 'api_password' attributes.
+3. In the Firewall instance, set the 'serial' attribute.
+4. Add the Firewall as a child of Panorama, or as a child of a DeviceGroup under Panorama.
+
+Example::
+
+    # Instantiate a Firewall with serial
+    fw = firewall.Firewall(serial="0002487YR3880")
+    # Instantiate a Panorama with hostname and credentials
+    pano = panorama.Panorama("10.0.0.5", "admin", "mypassword")
+    # Add the Firewall as a child of Panorama
+    pano.add(fw)
+    # Change to Firewall via Panorama
+    fw.add(objects.AddressObject("Server", "2.2.2.2")).create()
+    # Change to Panorama directly
+    pano.add(panorama.DeviceGroup("CustomerA")).create()
+
+In this example, both changes are made with connections to Panorama. First, the
+address object is added to the Firewall by connecting to Panorama which proxies the
+API call to the Firewall. Then a device-group is created on Panorama directly.
+
 Working with virtual systems
 ----------------------------
 
@@ -150,7 +250,7 @@ instance represents a single context firewall, or 'vsys1' on a multi-vsys firewa
 
 When working with a firewall with multi-vsys mode enabled, there are two methods to work with vsys:
 
-**Method 1**: A different Firewall instance for each vsys
+**Method 1: A different Firewall instance for each vsys**
 
 Each Firewall object has a 'vsys' attribute which is assigned the vsys id.  For example::
 
@@ -166,7 +266,7 @@ To create or delete an entire vsys, use the create_vsys() and delete_vsys() meth
     fw_vsys2.create_vsys()
     fw_vsys3.delete_vsys()
 
-**Method 2**: A single Firewall instance with Vsys child instances
+**Method 2: A single Firewall instance with Vsys child instances**
 
 Create Vsys instances and add them to a 'shared' PanDevice::
 

pandevice/__init__.py

@@ -24,7 +24,7 @@
 
 __author__ = 'Brian Torres-Gil'
 __email__ = 'btorres-gil@paloaltonetworks.com'
-__version__ = '0.3.0'
+__version__ = '0.3.1'
 
 
 import logging