: Multi-config Request (API)
Focus
Focus

Multi-config Request (API)

Table of Contents

Multi-config Request (API)

Use the XML API to complete multiple configurations in one request.
The PAN-OS XML API provides a mechanism to perform multiple configuration API requests within a single transaction. This can be useful to simplify multi-step API configurations.
Below is an example of how a typical multi-config request is structured:
<multi-config> <action id="action-id" xpath="xpath"> <element-xml> </element-xml> </action> <action2 id="action2-id" xpath="xpath"> <element-xml> </element-xml> </action2> <actionN id="actionN-id" xpath="xpath"> <element-xml> </element-xml> </actionN> </multi-config>
The root element, which is denoted above by the multi-config element above, can be any name. The actions can be any of the listed Actions for Modifying a Configuration except complete. The ID attribute is optional and you can use the ID to identify the specific responses to a single node in the request.
This response corresponds with the example above: <response status="success" code="20"><response status="success" code="20" id="action-id"><msg>command succeeded</msg></response><response status="success" code="20" id="action2-id"><msg>command succeeded</msg></response></response>
Besides xpath, other attributes are acceptable, for example: newname for the rename action. The request accepts the element-xml document if you can use an element argument for that particular request.
Consider the following when using the multi-config request type:
  • When a request in the multi-config operation fails, no configuration changes are performed.
  • You can add additional measures by adding the parameter strict-transactional=yes. When set:
    • 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.

Example

To use the multi-config XML-API, you can URL encode an XML document and send it to the firewall. For example this document is saved as multi-config.xml:
<multi-config> <set id="101" xpath="/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/address/entry[@name='addr10']"> <ip-netmask>10.0.0.10</ip-netmask> </set> <set id="102" xpath="/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/address-group/entry[@name='group1']/static"> <member>addr10</member> </set> </multi-config>
This file, can be sent using the following cURL request:
$ curl -ku user:pass https://firewall/api -d type=config -d action=multi-config \ > --data-urlencode element@multi-config.xml
A successful response returns:
<response status="success" code="20"><response status="success" code="20" id="101"><msg>command succeeded</msg></response><response status="success" code="20" id="102"><msg>command succeeded</msg></response></response>
If you set the strict-transactional=yes parameter you may get a different response if there is a commit in progress.
$ curl -ku user:pass https://firewall/api -d type=config -d action=multi-config -d action=multi-config -d strict-transactional=yes\ > --data-urlencode element@multi-config.xml
If you send the above command while another commit is in progress you may receive the following response:
<response status="error" code="15"><msg><line>Commit in Progress or Pending</line></msg></response>