Add support for type=config&action=multi-config XML API request which

provides a mechanism to perform multiple configuration API requests
with transactional support.  Effort started by Garfield Freeman
with addition of multi_config() to pan.xapi.

Author: kevinsteves

AUTHORS.rst

@@ -9,3 +9,4 @@ Patches and Suggestions
 - Andrew Stanton
 - Darlene Wong
 - Michael Richardson
+- Garfield Freeman

bin/panxapi.py

@@ -216,6 +216,16 @@ def main():
             print_status(xapi, action)
             print_response(xapi, options)
 
+        if options['multi-config']:
+            action = 'multi-config'
+            if options['ad_hoc'] is not None:
+                extra_qs_used = True
+            xapi.multi_config(element=options['element'],
+                              strict=options['strict'],
+                              extra_qs=options['ad_hoc'])
+            print_status(xapi, action)
+            print_response(xapi, options)
+
         if options['export'] is not None:
             action = 'export'
             if options['ad_hoc'] is not None:
@@ -387,6 +397,8 @@ def parse_opts():
         'rename': False,
         'clone': False,
         'override': False,
+        'multi-config': False,
+        'strict': None,
         'api_username': None,
         'api_password': None,
         'hostname': None,
@@ -424,12 +436,12 @@ def parse_opts():
 
     valid_where = ['after', 'before', 'top', 'bottom']
 
-    short_options = 'de:gksS:U:C:A:o:l:h:P:K:xpjrXHGDt:T:'
+    short_options = 'de:gksS:U:C:A:o:M:l:h:P:K:xpjrXHGDt:T:'
     long_options = ['version', 'help',
                     'ad-hoc=', 'modify', 'validate', 'force', 'partial=',
                     'sync', 'vsys=', 'src=', 'dst=', 'move=', 'rename',
                     'clone', 'override=', 'export=', 'log=', 'recursive',
-                    'cafile=', 'capath=', 'ls', 'serial=',
+                    'strict=', 'cafile=', 'capath=', 'ls', 'serial=',
                     'group=', 'merge', 'nlogs=', 'skip=', 'filter=',
                     'interval=', 'timeout=',
                     'stime=', 'pcapid=', 'text',
@@ -512,6 +524,15 @@ def parse_opts():
         elif opt == '--override':
             options['override'] = True
             options['element'] = get_element(arg)
+        elif opt == '-M':
+            options['multi-config'] = True
+            options['element'] = get_element(arg)
+        elif opt == '--strict':
+            if arg in ['yes', 'no']:
+                options['strict'] = True if arg == 'yes' else False
+            else:
+                print('--strict must be yes|no', file=sys.stderr)
+                sys.exit(1)
         elif opt == '-l':
             try:
                 (options['api_username'],
@@ -858,6 +879,8 @@ def usage():
     --rename              rename object at xpath to dst
     --clone               clone object at xpath, src xpath
     --override element    override template object at xpath
+    -M element            multi-config XML element
+    --strict yes|no       multi-config strict-transactional
     --vsys vsys           VSYS for dynamic update/partial commit/
                           operational command/report
     -l api_username[:api_password]

doc/pan.xapi.rst

@@ -282,6 +282,27 @@ override(xpath=None, element=None)
  Only certain nodes in the Network and Device categories can
  be overridden.
 
+multi_config(element=None, strict=None)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ The multi_config() method performs the ``action=multi-config`` device
+ configuration API request with the **element** and optional
+ **strict-transactional** argument.  multi_config() is used to perform
+ multiple configuration API requests with transactional support.
+
+ When a request in the multi-config operation fails, no configuration
+ changes are performed.
+
+ When **strict** is set to *True* the **strict-transactional** API
+ request argument is set to *yes* and additional checks are performed:
+
+ - When a commit operation is active or a commit is pending, the
+   operation will fail.
+
+ - When there are uncommitted changes for the user performing the
+   operation, they will be rolled back before performing the
+   multi-config operation.
+
 user_id(cmd=None, vsys=None)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -653,6 +674,9 @@ SEE ALSO
  PAN-OS and Panorama API Guide
   https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-panorama-api.html
 
+ PAN-OS XML API multi-config Request
+  https://gist.github.com/kevinsteves/c175854d44324f5c0a006798929e1a76
+
 AUTHORS
 =======
 

doc/panxapi.rst

@@ -63,6 +63,8 @@ SYNOPSIS
     --rename              rename object at xpath to dst
     --clone               clone object at xpath, src xpath
     --override element    override template object at xpath
+    -M element            multi-config XML element
+    --strict yes|no       multi-config strict-transactional
     --vsys vsys           VSYS for dynamic update/partial commit/
                           operational command/report
     -l api_username[:api_password]
@@ -353,6 +355,27 @@ DESCRIPTION
   **element** can be an XML string, a path to a file containing XML,
   or the value **-** to specify the XML is on *stdin*.
 
+ ``-M`` *element*
+  Performs the ``action=multi-config`` device configuration API
+  request with the **element** and optional **strict-transactional**
+  argument.  ``multi-config`` is used to perform multiple
+  configuration API requests with transactional support.
+
+  **element** can be an XML string, a path to a file containing XML,
+  or the value **-** to specify the XML is on *stdin*.
+
+ ``--strict`` *yes|no*
+  When **--strict** is *yes* the **strict-transactional**
+  ``multi-config`` API request argument is set to *yes* and additional
+  checks are performed:
+
+  - When a commit operation is active or a commit is pending, the
+    operation will fail.
+
+  - When there are uncommitted changes for the user performing the
+    operation, they will be rolled back before performing the
+    multi-config operation.
+
  ``--vsys`` *vsys*
   Specify optional **vsys** for dynamic update (**-U**), partial vsys
   commit (**--partial** vsys), commit-all (**-A**) and operational
@@ -722,6 +745,9 @@ SEE ALSO
  PAN-OS and Panorama API Guide
   https://docs.paloaltonetworks.com/pan-os/10-2/pan-os-panorama-api.html
 
+ PAN-OS XML API multi-config Request
+  https://gist.github.com/kevinsteves/c175854d44324f5c0a006798929e1a76
+
  PAN-OS XML API Labs with pan-python
   http://api-lab.paloaltonetworks.com/
 

lib/pan/xapi.py

@@ -395,6 +395,30 @@ def __get_response_msg(self):
                         lines.append(elem2.text)
             return '\n'.join(lines) if lines else None
 
+        # multi-config responses have nested response tags under the
+        # main response tag
+        path = './response'
+        elem = self.element_root.findall(path)
+        if len(elem) > 0:
+            self._log(DEBUG2, 'path: %s', path)
+            for resp in elem:
+                attributes = ''
+                for x in ['status', 'code', 'id']:
+                    if x in resp.attrib:
+                        attributes += '%s="%s" ' % (x, resp.attrib[x])
+                msg = resp.find('./msg')
+                if msg is None:
+                    lines.append(attributes.rstrip())
+                    continue
+                line = msg.find('./line')
+                if line is not None and line.text is not None:
+                    lines.append(attributes + line.text)
+                elif msg.text is not None:
+                    lines.append(attributes + msg.text)
+                elif attributes:
+                    lines.append(attributes.rstrip())
+            return '\n'.join(lines) if lines else None
+
         return None
 
     # XXX store tostring() results?
@@ -734,6 +758,14 @@ def override(self, xpath=None, element=None, extra_qs=None):
             query['element'] = element
         self.__type_config('override', query, extra_qs)
 
+    def multi_config(self, element=None, strict=None, extra_qs=None):
+        query = {}
+        if element is not None:
+            query['element'] = element
+        if strict is not None:
+            query['strict-transactional'] = 'yes' if strict else 'no'
+        self.__type_config('multi-config', query, extra_qs)
+
     def __type_config(self, action, query, extra_qs=None):
         self.__set_api_key()
         self.__clear_response()