PANOS and

Panorama
XMLAPIUsage
Guide
Version7.1

ContactInformation
CorporateHeadquarters:

PaloAltoNetworks
4401GreatAmericaParkway
SantaClara,CA95054
https://www.paloaltonetworks.com/company/contactsupport

AboutthisGuide
ThisAPIreferenceguidecoversthefeaturesandusageofthePANOSXMLAPI.Foradditionalinformation,refer
tothefollowingresources:

ForinformationonhowtoconfigureothercomponentsinthePaloAltoNetworksNextGenerationSecurity
Platform,gototheTechnicalDocumentationportal:https://www.paloaltonetworks.com/documentationor
searchthedocumentation.

Foraccesstotheknowledgebase,discussionforums,andvideos,refertohttps://live.paloaltonetworks.com.

Forcontactingsupport,forinformationonsupportprograms,tomanageyouraccountordevices,ortoopena
supportcase,refertohttps://www.paloaltonetworks.com/support/tabs/overview.html.

ForthemostcurrentPANOSandPanorama7.1releasenotes,goto
https://www.paloaltonetworks.com/documentation/71/panos/panosreleasenotes.html.

Toprovidefeedbackonthedocumentation,pleasewritetousat:[email protected].

PaloAltoNetworks,Inc.
www.paloaltonetworks.com
2016PaloAltoNetworks,Inc.PaloAltoNetworksisaregisteredtrademarkofPaloAltoNetworks.Alistofourtrademarkscanbefound
athttps://www.paloaltonetworks.com/company/trademarks.html.Allothermarksmentionedhereinmaybetrademarksoftheir
respectivecompanies.
RevisionDate:September21,2016

2 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

TableofContents
AboutthePANOSXMLAPI........................................... 5
PANOSXMLAPIComponents...................................................... 6
StructureofaPANOSXMLAPIRequest.............................................. 7
APIAuthenticationandSecurity .................................................. 7
XMLandXPath................................................................. 8
XPathNodeSelection ........................................................... 8

GetStartedwiththePANOSXMLAPI ................................. 11
EnableAPIAccess .................................................................12
GetYourAPIKey .................................................................13
MakeYourFirstAPICall ...........................................................14
ExploretheAPI ...................................................................15
UsetheAPIBrowser ...........................................................15
UsetheCLItoFindXMLAPISyntax .............................................18
UsetheWebInterfacetoFindXMLAPISyntax ...................................19

PANOSXMLAPIUseCases .......................................... 21
UpgradeaFirewalltotheLatestPANOSVersion(API) ................................22
ShowandManageGlobalProtectUsers(API) .........................................25
QueryaFirewallfromPanorama(API) ...............................................27
UpgradePANOSonMultipleHAFirewallsthroughPanorama(API) .....................29

PANOSXMLAPIRequestTypes ...................................... 35
PANOSXMLAPIRequestTypesandActions ........................................36
RequestTypes ................................................................36
ConfigurationActions ..........................................................36
AsynchronousandSynchronousRequeststothePANOSXMLAPI .....................38
Configuration(API)................................................................39
GetActiveConfiguration .......................................................40
GetCandidateConfiguration ....................................................41
SetConfiguration ..............................................................42
EditConfiguration.............................................................43
DeleteConfiguration ...........................................................44
RenameConfiguration..........................................................44
CloneConfiguration............................................................44
MoveConfiguration............................................................45
OverrideConfiguration .........................................................45
MultiMoveorMultiCloneConfiguration.........................................46
ViewConfigurationNodeValuesforXPath .......................................46

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 3

TableofContents

CommitConfiguration(API) ......................................................... 47
Commit ....................................................................... 47
Commitall.................................................................... 48
RunOperationalModeCommands(API) .............................................. 49
GetReports(API) .................................................................. 50
DynamicReports .............................................................. 50
PredefinedReports............................................................. 51
CustomReports ............................................................... 51
ExportFiles(API) .................................................................. 53
ExportPacketCaptures ......................................................... 53
ExportCertificatesandKeys .................................................... 54
ExportTechnicalSupportData .................................................. 55
ImportFiles(API).................................................................. 57
ImportingBasics............................................................... 57
ImportFiles ................................................................... 58
RetrieveLogs(API)................................................................. 59
ApplyUserIDMappingandPopulateDynamicAddressGroups(API).................... 61
GetVersionInfo(API).............................................................. 64

PANOSXMLAPIErrorCodes.........................................65

4 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

AboutthePANOSXMLAPI
ThePANOSandPanoramaXMLAPIallowsyoutomanagefirewallsandPanoramathroughaprogrammatic
XMLbasedAPI.UsethisAPItoaccessandmanageyourfirewallthroughathirdpartyservice,application,
orscript.
ThePANOSXMLAPIusesatreeofXMLnodestomapfirewallorPanoramafunctionality.TomakeanAPI
request,youmustspecifytheXPath(XMLPathLanguage)totheXMLnodethatcorrespondstoaspecific
settingoraction.XPathallowsyoutonavigatethroughthehierarchicalXMLtreestructureforfirewallsand
Panorama.
UsethePANOSXMLAPItoautomatetaskssuchas:

create,update,andmodifyfirewallandPanoramaconfigurations

executeoperationalmodecommands,suchasrestartthesystemorvalidateconfigurations

retrievereports

manageusersthroughUserID

updatedynamicobjectswithouthavingtomodifyorcommitnewconfigurations

BecausePANOSXMLAPIfunctionalitymirrorsthatofthewebinterfaceandCLI,familiarizeyourselfwith
both.ReadingrelevantportionsofthePANOSAdministratorsGuidewillhelpyougetabetter
understandingoffirewallfunctionalitiesthattheAPIcanaccess.Youshouldalsobeknowledgeableabout
webserviceAPIs,HTTP,XML,andXPath.

PANOSXMLAPIComponents

StructureofaPANOSXMLAPIRequest

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 5

PANOSXMLAPIComponents

AboutthePANOSXMLAPI

PANOSXMLAPIComponents
ThePANOSXMLAPIoffersanumberofcomponentstoautomateaccessandconfigurationofPaloAlto
NetworksfirewallsandPanorama.
Feature

Description

FullaccesstoPANOS
functionality

ThePAN0SXMLAPIallowsyoutoaccessalmostallofthefunctionalitynormally
providedthroughthefirewallwebinterfaceandCLI.

Secureauthenticationand UseyouradministrativeusernameandpasswordtogenerateanAPIkeyto
accessusingAPIkeyand authenticateAPIcalls.GranularrolesallowyoutograntAPIaccesstospecific
functionalityincludingreports,logs,andoperationalmodecommands.
adminroles
OptionstoviewXML
syntaxthroughAPI
browser,CLIandweb
interfacedebugmode

ToexploreallvariousfunctionsoftheAPI,youcanusetheAPIbrowserthroughthe
firewallwebinterface.YoucanalsoenabledebugmodethroughtheCLItoseethe
APIequivalentofCLIcommands.

6 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

AboutthePANOSXMLAPI

StructureofaPANOSXMLAPIRequest

StructureofaPANOSXMLAPIRequest
AnAPIrequesttypicallycomprisesofanumberofparameters,asshownintheexamplebelow:
https://<firewall>/api/?type=type&action=action&xpath=xpath&key=apikey

APIkey(key=):TheAPIkeyallowsyoutoauthenticateyourselftotheAPIwhenmakingrequests.Learn
aboutAPIAuthenticationandSecurityandhowtoGetYourAPIKey.
Requesttype(type=):BecausetheXMLAPIallowsyoutoperformwidearrayofrequests,youmustfirst
specifythetypeofrequestyouwant,rangingfromconfigurationtooperation,importingtoexporting,
andfromreportstouserid.LearnmoreaboutRequestTypes.
Action(action=):Whentherequesttypeisconfig(configuration)orop(operationalmodecommand),you
mustalsospecifyanassociatedaction,suchasedit,delete,ormove.LearnmoreaboutConfiguration
Actions.

XMLandXPathelements(xpath=orcmd=):Whenusingconfigurationoroperationalmodecommandsonthe
firewall,youjusteitherincludetheXMLorXPathspecifyingthespecificXMLnode.LearnmoreaboutXML
andXPathandXPathNodeSelection.
YoucanmakerequeststothePANOSXMLAPIusingtheGETorPOSTmethod.UseaPOSTrequestwhen
youaresendinglargeamountsofformdata,orwhenyouarepassingnonASCIIcharacters.SomeAPI
requests,suchasimportingfiles,requirePOST.UseaGETrequestwhenpassingstringsintheRequestURL.
WhenusingtheGETmethod,appendthequerystringtotherequestURLasaURLencodedparameter
string:
GET /api/?type=keygen&user=username&password=password
WhenusingthePOSTmethod,passtheparametersintherequestbody.Inthisexample,therequestbody
includesthelogincredentials:
POST /api/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
password=password&user=username&type=keygen

APIAuthenticationandSecurity
Bydefault,allAPIrequestsmustbemadeoverHTTPS.Additionally,youmustGetYourAPIKeyandinclude
itintherequesttoauthenticateyourAPIrequests.Alternatively,youcanuseBasicAuthenticationwithyour
admincredentialsbypassingtheBase64encodedusername:passwordinaAuthorizationheaderfield:
Authorization: Basic amJPbLxpbw9UaTpXb3JrKjIwMDA=
YoucannotusebasicauthenticationwhenyouGetYourAPIKey.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 7

StructureofaPANOSXMLAPIRequest

AboutthePANOSXMLAPI

XMLandXPath
ThePANOSXMLAPIusesXMLforbothrequestsandresponses.Whenmakingrequests,constructan
HTTPSGETorPOSTrequestwiththecorrecttypeandactionalongwiththecorrectXPath.Hereisan
exampleAPIrequest:
https://<firewall>/api/?type=config&action=show&key=APIkey&xpath=/config/devices/entry
/vsys/entry/rulebase/security
EnsureyoureplacevariablessuchashostnameandAPIkeywiththeIPaddressorhostnameofyourfirewall
orPanoramaandAPIkey,respectively.
Whenmakingconfigurationrequests(type=config),youcanuseXPath,asyntaxforselectingnodesfrom
withinanXMLdocument.UsetheXPathtoisolateandmodifyportionsofyourconfiguration.TheXML
configurationwithinPANOSusesfourdifferenttypesofnodesasshownhere:
<users>
<entry name="admin">
<permissions>
<role-based>
<superuser>yes</superuser>
</role-based>
</permissions>
</entry>
<entry name="guest">
<permissions>
<role-based>
<custom>
<profile>NewUser</profile>
</custom>
</role-based>
</permissions>
</entry>
</users>

Rootnodesaretoplevelnodeswithnoparent.Requestingtherootnodereturnsallchildelements.
Elementnodesrepresentcontainersofinformation.Elementnodescancontainotherelementnodesor
simplyactasacontainerofinformation.Example:<permissions></permissions>

Attributenode:Nodesthatcontainname/valuepairssuchas:<entry name="admin"></entry>

Textnodescontainplaintextsuchas:<superuser>yes</superuser>

ExploretheAPIwiththeAPIbrowser,CLI,ordebugconsoletolearnhowtoconstructXMLrequests.

XPathNodeSelection
TherearevariouswaystoselecttheXPathforAPIrequests.
Thesimplestistousethelocationpathoftheresource.Forexample,toselectuserswithinyour
managementconfiguration,usethefollowingpath:
/config/mgt-config/users

8 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

AboutthePANOSXMLAPI

StructureofaPANOSXMLAPIRequest

ThispathselectsthefollowingXMLnodethatincludesalistofusers:
<users>
<entry name="admin">
<permissions>
<role-based>
<superuser>yes</superuser>
</role-based>
</permissions>
</entry>
<entry name="guest">
<permissions>
<role-based>
<custom>
<profile>NewUser</profile>
</custom>
</role-based>
</permissions>
</entry>
</users>
Perhapsyouwanttoselectaspecificnode,suchasthesuperusertextnodeasshowninthisdiagram:

Toselectbasedonthetextvalueofanelementyoucansearch,usesyntaxsimilartothefollowingexample:
/config/mgt-config/users/entry/permissions/role-based/superuser[text()='yes']
Thispathshowsonlythespecificnodethatcontainsthesuperuserwithatextvalueofyes:
<superuser>yes</superuser>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 9

StructureofaPANOSXMLAPIRequest

10 PANOSandPanorama7.1XMLAPIUsageGuide

AboutthePANOSXMLAPI

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI
TousethePANOSXMLAPI,firstuseyouradmincredentialstogetanAPIkeythroughthekeygencommand
type.YoucanthenusetheAPIkeytotestasimplecall.
ThisguidetestsAPIrequestsusingcURLcommands.However,youcanuseotherAPItesting
toolssuchasPostmanandRESTClienttotestAPIrequests.

EnableAPIAccess

GetYourAPIKey

MakeYourFirstAPICall

ExploretheAPI

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 11

EnableAPIAccess

GetStartedwiththePANOSXMLAPI

EnableAPIAccess
TheAPIsupportsthefollowingtypesofAdministratorsandAdminroles:

Dynamicroles:Superuser,Superuser(readonly),Deviceadmin,Deviceadmin(readonly),Vsysadmin,
Vsysadmin(readonly)
RolebasedAdmins:Device,Vsys,Panorama.

AdminRoleprofilesenableordisablefeaturesonthemanagementinterfacesofthefirewallorPanorama,
XMLAPI,webinterface,andCLI.FormoredetailsonAdministrativeRoles,seethePANOSAdminstrators
Guide.
Asabestpractice,setupaseparateadminaccountforXMLAPIaccess.

EnableAPIAccess
Step1

SelectanAdminRoleprofile.

GotoDevice>Admin Rolesandselectorcreateanadminrole.

Step2

Selectfeaturesavailabletotheadmin
role.

1.

SelecttheXML API tab.

2.

EnableordisableXMLAPIfeaturesfromthelist,suchas
Report,Log,andConfiguration.

3.

SelectOKtoconfirmyourchange.

Step3

Assigntheadminroletoanadministrator SeeConfigureanAdministrativeAccount.
account.

12 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI

GetYourAPIKey

GetYourAPIKey
TousetheAPI,generatetheAPIkeyrequiredforauthenticatingAPIcalls.Requestparametersshouldbe
URLencodedwhenusedinHTTPrequests.
GetYourAPIKey
Step1

TogenerateanAPIkey,makeaURLrequesttothefirewallshostnameorIPaddressesusingthe
administrativecredentialsandtype=keygen:

curl -X GET 'https://firewall/api/?type=keygen&user=username&password=password'

AsuccessfulAPIcallreturnsstatus="success"alongwiththeAPIkeywithinthekeyelement:

<response status="success">
<result>
<key>gJlQWE56987nBxIqyfa62sZeRtYuIo2BgzEA9UOnlZBhU</key>
</result>
</response>
Step2

(Optional)RevokeanAPIkey.
YoucanchoosetorevokeandthenchangeanAPIkeyassociatedwithanadministratoraccountbychanging
thepasswordassociatedwiththeadministratoraccount.AnyAPIkeysthatweregeneratedusingtheprevious
credentialswouldnolongerbevalid.
GeneratinganAPIkeyusingthesameadministratoraccountcredentialsreturnsuniqueAPIkeyseverytime,
andallofthekeysarevalid.

ChangethemasterpasswordonyourfirewallinordertogenerateauniqueAPIkey.Ifyouhave
notchangedthefirewallmasterkeyfromthedefault,allfirewallswiththesame
username/passwordwillreturnthesameAPIkey.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 13

MakeYourFirstAPICall

GetStartedwiththePANOSXMLAPI

MakeYourFirstAPICall
GetYourAPIKeytomakeyourfirstcalltothePANOSXMLAPI.
MakeYourFirstAPICall
Step1

MakeacURLcalltogetsysteminformation,whichreturnstheIPaddress,hostname,andmodelofyour
firewall.BesuretoincludetheAPIkey:

curl
'https://firewall//api/?type=op&cmd=<show><system><info></info></system></show>&key=a
pikey'
Step2

Confirmthattheresponsetotheaboverequestlookssimilartothis:

<response status="success">
<result>
<system>
<hostname>firewall</hostname>
<ip-address>10.27.0.8</ip-address>
<netmask>255.255.254.0</netmask>
<default-gateway>10.27.0.1</default-gateway>
<is-dhcp>no</is-dhcp>
<ipv6-address>unknown</ipv6-address>
<ipv6-link-local-address>fe80::21b:17dd:dedf:c04a/64</ipv6-link-local-address>
<ipv6-default-gateway />
<mac-address>00:1b:17:ff:c0:4a</mac-address>
<time>Wed Feb 10 13:03:32 2016</time>
<uptime>1 days, 19:35:51</uptime>
<devicename>firewall</devicename>
<family>3000</family>
<model>PA-3020</model>
<serial>001901000114</serial>
<sw-version>7.1.</sw-version>
<global-protect-client-package-version>2.0.0</global-protect-client-package-version>
<app-version>557-3138</app-version>
<app-release-date>2016/02/09 16:56:02</app-release-date>
<av-version>2261-2700</av-version>
<av-release-date>2016/02/09 15:26:53</av-release-date>
<threat-version>557-3138</threat-version>
<threat-release-date>2016/02/09 16:56:02</threat-release-date>
<wf-private-version>0</wf-private-version>
<wf-private-release-date>unknown</wf-private-release-date>
<url-db>paloaltonetworks</url-db>
<wildfire-version>27518-28208</wildfire-version>
<wildfire-release-date>2016/01/08 11:08:16</wildfire-release-date>
<url-filtering-version>2016.01.08.407</url-filtering-version>
<global-protect-datafile-version>1452328885</global-protect-datafile-version>
<global-protect-datafile-release-date>2016/01/09 08:41:25</global-protect-datafile-release-date>
<logdb-version>7.0.9</logdb-version>
<platform-family>3000</platform-family>
<vpn-disable-mode>off</vpn-disable-mode>
<multi-vsys>on</multi-vsys>
<operational-mode>normal</operational-mode>
</system>
</result>
</response>

14 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI

ExploretheAPI

ExploretheAPI
ThereareseveralwaysyoucanexploretheAPIandlearnhowtoconstructyourXMLrequests:

UsetheAPIBrowser

UsetheCLItoFindXMLAPISyntax

UsetheWebInterfacetoFindXMLAPISyntax

UsetheAPIBrowser
EachfirewallandPanoramaprovidesanAPIbrowserthatisaccessiblefromyourwebbrowser.TheAPI
browserletsyounavigatethroughandviewthecorrespondingXPathandAPIURL.
UsetheAPIBrowsertoExploretheAPI
Step1

Launchthewebinterface.

1.

UseawebbrowsertonavigatetotheactualFQDNorIP
addressofyourfirewall:

https://firewall/
2.
Step2

LaunchtheAPIBrowser.

Loginwithyouradministratorcredentialswhenpromptedto
logintothewebinterface.

GototheAPIbrowserURLonyourfirewall:

https://firewall/api

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 15

ExploretheAPI

GetStartedwiththePANOSXMLAPI

UsetheAPIBrowsertoExploretheAPI(Continued)
Step3

Drilldowntoarequest.

WhenyoufirstopentheAPIbrowser,theavailableRequestTypes
display.
1.

Selectoneoftherequesttypestodrilldowntothenextlevel
oftheXPath.LetsstartwithConfigurationCommands,which
equatestotype=report:

2.

Drilldownfurtheruntilyouselectarequestthatyouwantto
test.

16 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI

ExploretheAPI

UsetheAPIBrowsertoExploretheAPI(Continued)
Step4

Testarequest.

3.

SelecttheURLtothentestthatrequestinthebrowser.

ThebrowsershowstheresultingXMLresponseinthebrowser:

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 17

ExploretheAPI

GetStartedwiththePANOSXMLAPI

UsetheAPIBrowsertoExploretheAPI(Continued)
AlongwiththeURL,theAPIbrowseralsoprovidestheXPathas
necessary,asshownhereforadescriptionofapredefined
application:

UsetheCLItoFindXMLAPISyntax
AnothermethodtodeterminetheappropriateXMLsyntaxandXPathforyourAPIcallsisthroughthe
commandlineinterface(CLI).Thismethodworksfortype=opandtype=configAPIcalls.
UsetheCLItoenabledebugmodeandthenruntheCLIcommandtoreceivethecorrespondingXMLand
XPathintheresponse.
UsetheCLItoFindXMLAPISyntaxandXPath
Step1

AccesstheCLI.

UseanSSHclientorterminaltoaccessyourfirewallorPanorama
CLI.Formoreinformation,learnhowtoaccesstheCLIonyour
firewallorPanorama.

Step2

Enabledebugmode.

Enterthefollowingcommand:

debug cli on
Step3

RunaCLIcommand.

EnterandrunaCLIcommand.Example:
test url http://paloaltonetworks.com
<request cmd="op" cookie="7581536015878829"
uid="1206"><operations><test><url>http://paloaltonetw
orks.com</url></test></operations></request>

18 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI

ExploretheAPI

UsetheCLItoFindXMLAPISyntaxandXPath(Continued)
Step4

Usetheresultingresponsetocreatean UsethecmdvalueandtheXMLelementswithintheoperations
APIcall.
tagtoformtheAPIcall:

https://firewall/api/?type=op&cmd=<test><url>htt
p://paloaltonetworks.com</url></test>&key=apikey
DependingontheCLIcommand,theXMLtagvaluesforcmd
willvary.Forexample,hereisaCLIcommandforshowing
firewallinformation:run show system info
ThecorrespondingAPIcalllookslikethis:

https://firewall/api/?type=op&cmd=<show><system>
<info></info></system></show>&key=apikey

UsetheWebInterfacetoFindXMLAPISyntax
YoucanusethewebinterfacealongwiththeavailabledebugconsoletoexploretheXMLandXPath
necessaryforyourAPIcalls.
Firstlogintothewebinterfaceandthenopenaseparatewindowwhereyoucanviewthecorresponding
XMLandXPath.
UsetheWebInterfaceandDebugConsoletoFindXMLAPISyntaxandXPath
Step1

Launchthewebinterface.

LaunchawebbrowserandenterthefirewallsIPaddressor
hostname.Enteryourusercredentials.

Step2

Launchthedebugconsole.

Inaseparatewebbrowserwindowortab,launchthedebug
console:

http://firewall/debug

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 19

ExploretheAPI

GetStartedwiththePANOSXMLAPI

UsetheWebInterfaceandDebugConsoletoFindXMLAPISyntaxandXPath(Continued)
Step3

Performtheactionyouwanttoreplicate Inthewebbrowser,navigatetothemenuanditemoractionthat
throughtheAPI.
youwanttoperform.

ToaidinfindingtherelevantXML,selectClearinthedebug
consolejustbeforeyouselectthefinalmenuoraction.
Step4

ViewtheresultingXMLsyntaxinthe
debugconsole.

Inthedebugconsole,selectRefreshandthennavigatethroughthe
consoletothesyntaxrelatedtoyourchoiceoraction:

ExampleXMLwithindebugconsole:

<request cmd="op" cookie="3885378180190727">

<operations xml="yes">
<show>
<system>
<info/>
</system>
</show>
</operations>
</request>
ThecorrespondingAPIcalllookslikethis:

https://firewall/api/?type=op&cmd=<show><system>
<info></info></system></show>&key=apikey

20 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases
ThefollowingusecaseshighlighttheuseofthePANOSXMLAPI,eithertoreducerepetitivestepsorto
automatetasksnormallyyouperformthroughthewebinterfaceorCLI.

UpgradeaFirewalltotheLatestPANOSVersion(API)

ShowandManageGlobalProtectUsers(API)

QueryaFirewallfromPanorama(API)

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 21

UpgradeaFirewalltotheLatestPANOSVersion(API)

PANOSXMLAPIUseCases

UpgradeaFirewalltotheLatestPANOSVersion(API)
YoucanusethePANOSXMLAPItoupdateyourfirewallwiththelatestPANOSandContentRelease
versions.
UpgradeaFirewalltotheLatestPANOSVersion
Step1

Downloadthelatestcontentupdate.

Usethefollowingrequesttofirstdownloadthelatestcontent
update:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><con
tent><upgrade><download><latest/>
</download></upgrade></content></request>&key=ap
ikey'
Ifsuccessful,theresponsecontainsajobidthatyoucanuseto
checkonthestatusofyourrequest.
<response status="success" code="19">
<result>
<msg>
<line>Download job enqueued with jobid 2</line>
</msg>
<job>2</job>
</result>
</response>
Step2

Checkonthecontentdownloadstatus.

Usethejobidtoensurethatthecontentdownloadcompletes
successfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=2&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step3

Installthelatestcontentupdate.

Usethefollowingrequesttoinstallthenewlydownloadedcontent:

curl -X GET
'https://firewall/api/?type=op&cmd<request><cont
ent><upgrade><install>
<version>latest</version></install></upgrade></c
ontent></request>key=apikey'
Ifsuccessful,theresponsecontainsajobidthatyoucanuseto
checkonthestatusofyourrequest.
<response status="success" code="19">
<result>
<msg>
<line>Content install job enqueued with jobid
3</line>
</msg>
<job>3</job>
</result>
</response>

22 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

UpgradeaFirewalltotheLatestPANOSVersion(API)

UpgradeaFirewalltotheLatestPANOSVersion(Continued)
Step4

Checkonthecontentinstallationstatus. Usethejobidtoensurethatthecontentinstallationcompletes
successfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=3&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step5

CheckforthelatestPANOSsoftware
update.

AfterinstallingthelatestContentReleaseupdate,checkforthe
latestavailablePANOSsoftwareupdates:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><sys
tem><software><check></check>
</software></system></request>&key=apikey'
Intheresponse,thefirstentryisthelatestversionofPANOS:

<response status="success">
<result>
<sw-updates last-updated-at="2015/10/20
14:16:30">
<msg />
<versions>
>
<version>7.1.0</version>
<filename>PanOS_3000-7.1.0-c65</filename>
<size>720</size>
<size-kb>737504</size-kb>
<released-on>2015/10/20 13:23:11</released-on>
...
Step6

DownloadthelatestPANOSsoftware
update.

1.

Inthiscase,thelatestversionis7.1.0c65,sodownloadthat
version:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><sys
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.

Usethejobid intheresponsetoensurethatthe
systemupdatedownloadcompletessuccessfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=318&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step7

InstallthelatestPANOSsoftware
update.

Toinstallthelatestsystemupdate,includetheversionina
softwareinstallrequest:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><sys
tem><software><install><version>7.1.0-c65</versi
on></install></software></system></request>&key=
apikey'

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 23

UpgradeaFirewalltotheLatestPANOSVersion(API)

PANOSXMLAPIUseCases

UpgradeaFirewalltotheLatestPANOSVersion(Continued)
Step8

Checkonthesoftwareinstallation
status.

Usethejobidintheresponsetoensurethatthesystemupdate
installssuccessfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=320&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step9

Rebootthefirewall.

Afterthesystemupdateinstallssuccessfully,trigger:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><res
tart><system></system></restart>
</request>&key=apikey'

24 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

ShowandManageGlobalProtectUsers(API)

ShowandManageGlobalProtectUsers(API)
OnecommonuseofthePANOSXMLAPIistomanageGlobalProtectusers.UsingtwoAPIrequests,you
canviewandthendisconnectaGlobalProtectuserwhohasbeenloggedinfortoolong.
ShowandManageGlobalProtectUsers
Step1

ViewallGlobalProtectusers.

MakearequesttoviewallGlobalProtectusers:

curl -X GET
'https://firewall/api/?type=op&cmd=<show><global
-protect-gateway><current-user/>
</global-protect-gateway></show>&key=apikey'
Theresponsecontainsalistofusersalongwithrelatedinformation
includingIPaddresses,logins,andclientinformation:

<response status="success">
<result>
<domain />
<islocal>yes</islocal>
<username>dward</username>
<computer>Dans iPhone</computer>
<client>Apple iOS 8.1.2</client>
<vpn-type>Device Level VPN</vpn-type>
<virtual-ip>192.168.2.1</virtual-ip>
<public-ip>166.173.63.240</public-ip>
<tunnel-type>SSL</tunnel-type>
<login-time>Jan.22 01:50:36</login-time>
<login-time-utc>1421916636</login-time-utc>
<lifetime>2592000</lifetime>
</entry>
</result>
</response>
The<login-time-utc>fieldisthelogindate/timeinUNIXtime
format(numberofsecondselapsedsince00:00:001Jan1970).To
findthelistofusers,filtertheoutputforthisfieldandcomparethe
login-time-utcvaluetocurrentdateandtime(oranotherdate
andtime).

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 25

ShowandManageGlobalProtectUsers(API)

PANOSXMLAPIUseCases

ShowandManageGlobalProtectUsers(Continued)
Step2

DisconnectaGlobalProtectuser.

Uponidentifyingtheuserthatyouwanttodisconnect,senda
requestthatincludestheGlobalProtectgateway,username,
computer,andaforce-logoutreason:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><glo
bal-protect-gateway><client-logout>
<gateway>Home-N</gateway><user>dward</user><re
ason>force-logout</reason>
<computer>Dans%20iPhone</computer></client-lo
gout></global-protect-gateway>
</request>&key=apikey'
Asuccessfulresponseshowsthattheuserhasbeensuccessfully
disconnected:

<response status="success">
<result>
<response status="success">
<gateway>Home-N</gateway>
<domain>(null)</domain>
<user>dward</user>
<computer>Dans iPhone</computer>
</response>
</result>
</response>

26 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

QueryaFirewallfromPanorama(API)

QueryaFirewallfromPanorama(API)
ThetargetparameteronPanoramaallowsyoutoredirectqueriestoamanagedfirewall.Redirectingqueries
tofirewallshelpstoreducetimeandthenumberofstepsrequiredtoissuerepetitivecommands.Usingthe
scriptinglanguageoryourchoice,youcanstorefirewallserialnumbersandusethemtoissueaqueryto
severalfirewalls.
Currently,youcanonlyusetype=opquerieswhenredirectingqueriesthroughPanorama.

QueryaFirewallfromPanorama
Step1

Getalistofconnectedfirewalls.

GetalistofconnectedfirewallsthatPanoramamanages:

https://panorama/api/?type=op&cmd=<show><devices
><
https://panorama/api/?type=op&cmd=<show><devices
><connected></connected></devices></show>
Theresponseincludestheserialnumber(serial)ofeachfirewall.
<response status="success">
<result>
<devices>
name="007200002517">
<serial>007200002342</serial>
<connected>yes</connected>
<unsupported-version>no</unsupported-version>
<deactivated>no</deactivated>
<hostname>PM-6-1-VM</hostname>
<ip-address>10.3.4.137</ip-address>
<mac-addr />
<uptime>81 days, 20:39:41</uptime>
<family>vm</family>
<model>PA-VM</model>
<sw-version>6.1.3</sw-version>
<app-version>555-3129</app-version>
<av-version>2254-2693</av-version>
<wildfire-version>91873-101074</wildfire-version>
<threat-version>555-3129</threat-version>
<url-db>paloaltonetworks</url-db>
<url-filtering-version>2016.02.02.416</url-filtering-version>
<logdb-version>6.1.3</logdb-version>
<vpnclient-package-version />
<global-protect-client-package-version>0.0.0</global-protect-c
lient-package-version>
<vpn-disable-mode>no</vpn-disable-mode>
<operational-mode>normal</operational-mode>
<multi-vsys>no</multi-vsys>
<vsys>
name="vsys1">
<display-name>vsys1</display-name>
<shared-policy-status />
<shared-policy-md5sum>4a0913667df83ff1098492e2e2ec1756</shared
-policy-md5sum>
</entry>
</vsys>
</entry>
<!--truncated -->
</devices>
</result>
</response>

Theresponsecontainsa<serial>XMLelementforeachfirewall.
Step2

Collectfirewallserialnumbers.

PaloAltoNetworks,Inc.

Inyourscriptorcode,storethefirewallserialnumbersreturnedin
theresponsetothepreviousrequest.

PANOSandPanorama7.1XMLAPIUsageGuide 27

QueryaFirewallfromPanorama(API)

PANOSXMLAPIUseCases

QueryaFirewallfromPanorama(Continued)
Step3

QueryafirewallfromPanorama.

Anormalrequesttoshowsysteminformationonafirewalllooks
likethis:

https://firewall/api/?type=op&cmd=<show><system>
<info></info></system></show>
TodirectlytargetafirewallthroughPanorama,appendthefirewall
serialnumbertotherequest:

https://panorama/api/?type=op&cmd=<show><system>
<info></info></system></show>&target=d
evice-serial-number
Asuccessfulresponseshouldlooklikethis:
<response status="success">
<result>
<system>
<hostname>firewall</hostname>
<ip-address>10.41.0.8</ip-address>
<netmask>255.255.224.0</netmask>
<default-gateway>10.41.0.1</default-gateway>
<is-dhcp>no</is-dhcp>
<ipv6-address>unknown</ipv6-address>
<ipv6-link-local-address>fe80::21c:17cf:feff:c04a/64</ipv6-lin
k-local-address>
<ipv6-default-gateway></ipv6-default-gateway>
<mac-address>00:1b:17:fc:c0:4a</mac-address>
<time>Tue Oct 27 13:39:09 2015</time>
<uptime>12 days, 0:05:26</uptime>
<devicename>pm-firewall</devicename>
<family>3000</family>
<model>PA-3020</model>
<serial>001802000104</serial>
<sw-version>7.1.0-c54</sw-version>
<global-protect-client-package-version>2.0.0</global-protect-c
lient-package-version>
<app-version>537-2965</app-version>
<app-release-date>2015/10/26 18:10:48</app-release-date>
<av-version>2149-2586</av-version>
<av-release-date>2015/10/26 15:31:55</av-release-date>
<threat-version>537-2965</threat-version>
<threat-release-date>2015/10/26 18:10:48</threat-release-date>
<wf-private-version>0</wf-private-version>
<wf-private-release-date>unknown</wf-private-release-date>
<url-db>paloaltonetworks</url-db>
<wildfire-version>80683-89773</wildfire-version>
<wildfire-release-date>unknown</wildfire-release-date>
<url-filtering-version>2015.10.27.226</url-filtering-version>
<global-protect-datafile-version>1445974904</global-protect-da
tafile-version>
<global-protect-datafile-release-date>2015/10/27
19:41:44</global-protect-datafile-release-date>
<logdb-version>7.0.9</logdb-version>
<platform-family>3000</platform-family>
<vpn-disable-mode>off</vpn-disable-mode>
<multi-vsys>on</multi-vsys>
<operational-mode>normal</operational-mode>
</system>
</result>
</response>

Repeatthisrequestforeachconnectedfirewall.

28 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

UpgradePANOSonMultipleHAFirewallsthrough
Panorama(API)
ThisusecasehighlightstheabilityofthePANOSXMLAPItoautomateamorecomplexprocedure,namely
upgradingfirewallssetupasactivepassivehighavailability(HA)pair.Normally,thisprocedureinvolves
multiple,manualstepsonindividualfirewalls.
Thisisahighleveloverviewofthestepsyoumusttakeinthisprocedure.Youscriptorapplication
mustincorporateerrorcheckingandlogictoimplementthissequenceofsteps.

UpgradePANOSonMultipleFirewallsthroughPanorama
Step1

CheckforthelatestPANOSsoftware
updatethroughPanorama

CheckforthelatestavailablePANOSsoftwareupdates.Include
thefirewallserialnumberinyourrequest:

https://panorama/api/?type=op&cmd=<request><syst
em><software><check></check></software></system>
</request>&target=007200002517&key=apikey
Theresponsecontainsanarrayofresultssortedtoshowthe
latestversionfirst:
<response status="success">
<result>
<sw-updates last-updated-at="2016/02/03 08:29:09">
<msg />
<versions>
>
<version>7.1</version>
<filename>PanOS_vm-7.1</filename>
<size>540</size>
<size-kb>553964</size-kb>
<released-on>2016/02/02 10:57:20</released-on>
<release-notes><![CDATA[https://10.44.2.19/updates/ReleaseNote
s.aspx?type=sw&versionNumber=7.1.0-c158&product=panos&platform
=vm]]></release-notes>
<downloaded>no</downloaded>
<current>no</current>
<latest>yes</latest>
</entry>
<!-- truncated -->
</versions>
</sw-updates>
</result>
</response>

Step2

DownloadthelatestPANOSsoftware
update.

1.

Inthiscase,thelatestversionis7.1.0c65,sodownloadthat
version:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><sys
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.

Usethejobidintheresponsetoensurethatthesystem
updatedownloadcompletessuccessfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=318&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 29

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

PANOSXMLAPIUseCases

UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step3

InstallthelatestPANOSsoftware
update.

Toinstallthelatestsystemupdate,includetheversionina
softwareinstallrequest:

curl -X GET
'https://firewall/api/?type=op&cmd=<request><sys
tem><software><install><version>7.1.0-c65</versi
on></install></software></system></request>&key=
apikey'
Step4

Checkonthesoftwareinstallation
status.

Usethejobidintheresponsetoensurethatthesystemupdate
installssuccessfully:

curl -X GET
'https://firewall/api/?type=op&action=get&job-id
=jobid&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step5

Getalistofconnectedfirewalls.

GetalistofconnectedfirewallsthatPanoramamanages:

https://panorama/api/?type=op&cmd=<show><devices
><https://panorama/api/?type=op&cmd=<show><devic
es><connected></connected></devices></show>
Theresponseincludestheserialnumber(serial)ofeachfirewall.
<response status="success">
<result>
<devices>
name="007200002517">
<serial>007200002342</serial>
<connected>yes</connected>
<unsupported-version>no</unsupported-version>
<deactivated>no</deactivated>
<hostname>PM-6-1-VM</hostname>
<ip-address>10.3.4.137</ip-address>
<mac-addr />
<uptime>81 days, 20:39:41</uptime>
<family>vm</family>
<model>PA-VM</model>
<sw-version>6.1.3</sw-version>
<app-version>555-3129</app-version>
<av-version>2254-2693</av-version>
<wildfire-version>91873-101074</wildfire-version>
<threat-version>555-3129</threat-version>
<url-db>paloaltonetworks</url-db>
<url-filtering-version>2016.02.02.416</url-filtering-version>
<logdb-version>6.1.3</logdb-version>
<vpnclient-package-version />
<global-protect-client-package-version>0.0.0</global-protect-c
lient-package-version>
<vpn-disable-mode>no</vpn-disable-mode>
<operational-mode>normal</operational-mode>
<multi-vsys>no</multi-vsys>
<vsys>
name="vsys1">
<display-name>vsys1</display-name>
<shared-policy-status />
<shared-policy-md5sum>4a0913667df83ff1098492e2e2ec1756</shared
-policy-md5sum>
</entry>
</vsys>
</entry>
<!--truncated -->
</devices>
</result>
</response>

Theresponsecontainsa<serial>XMLelementthatcontains
eachfirewallserialnumber.

30 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step6

CheckforthelatestPANOSsoftware
update.

ChecktoseeifnewsoftwareisavailableonyourHApair:

https://panorama/api/?type=op&cmd=<request><syst
em><software><check></check></software></system>
</request>&target=serialnumber&key=apikey
Theresponsecontainsanarrayofresultssortedtoshowthelatest
versionfirst:

<response status="success">
<result>
<sw-updates last-updated-at="2016/02/03
08:29:09">
<msg />
<versions>
<version>7.1</version>
<filename>PanOS_vm-7.1</filename>
<size>540</size>
<size-kb>553964</size-kb>
<released-on>2016/02/02 10:57:20</released-on>
<release-notes><![CDATA[https://10.44.2.19/updat
es/ReleaseNotes.aspx?type=sw&versionNumber=7.1.0
-c158&product=p
anos&platform=vm]]></release-notes>
<downloaded>no</downloaded>
<current>no</current>
<latest>yes</latest>
</entry>
<!-- truncated -->
</versions>
</sw-updates>
</result>
</response>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 31

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

PANOSXMLAPIUseCases

UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step7

DownloadthelatestPANOSsoftware
update.

Afterdeterminingthelatestsystemupdate,downloadittoboth
firewallsintheHApair:

https://panorama/api/?type=op&cmd=<request><syst
em><software><download><version>7.1</version></d
ownload></software></system></request>&target=se
rialnumber&key=apikey
TheresponsecontainsajobID:
<response status="success" code="19">
<result>
<msg>
<line>Download job enqueued with jobid
3448</line>
</msg>
<job>3448</job>
</result>
</response>
UsethejobIDtocheckonthedownloadstatus:

https://panorama/api/?type=op&cmd=<show><jobs><i
d>3448</id></jobs></show>&target=serialnumber&ke
y=apikey
TheresponsecontainsajobstatusofFINwhenthedownloadis
complete:
<response status="success">
<result>
<job>
<tenq>2016/02/03 08:32:00</tenq>
<id>3448</id>
<user />
<type>Downld</type>
<status>FIN</status>
<stoppable>no</stoppable>
<result>OK</result>
<tfin>08:32:10</tfin>
<progress>08:32:10</progress>
<details>
<line>Successfully downloaded</line>
<line>Preloading into software manager</line>
<line>Successfully loaded into software
manager</line>
</details>
<warnings />
</job>
</result>
</response>
Step8

SuspendtheactiveHAfirewall.

Suspendtheactivefirewallinyourhighavailabilityfirewallpair:

https://panorama/api/?type=op&cmd=<request><high
-availability><state><suspend></suspen
d></state></high-availability></request>&target=
serialnumber&key=apikey
Theresponseconfirmstheactivefirewallhasbeensuspended:

<response status="success">
<result>Successfully changed HA state to
suspended</result>
</response>

32 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step9

Installthelatestsoftwareupdateonthe AftersuspendingtheactiveHAfirewall,installthesystemupdate
suspendedHApair.
onit:

https://panorama/api/?type=op&cmd=<request><syst
em><software><install><version>version</version>
</install></software></system></request>&target=
serialnumber&key=apikey
Theresponseshowsthesystemupdateisqueued:

<response status="success" code="19">

<result>
<msg>
<line>Software install job enqueued with
jobid 3453. Run 'show jobs id 3453' to monitor
its status. Please reboot the device after the
installation is done.</line>
</msg>
<job>3453</job>
</result>
</response>
Step10 Checkonthesoftwareinstallation
status.

Usethejobidintheresponsetoensurethatthesystemupdate
installssuccessfully:

curl -X GET
'https://panorama/api/?type=op&action=get&job-id
=jobid&target=serialnumber&key=apikey
Theresponseshouldincludethefollowing:

<response status="success">
Step11 RebootthesuspendedHApeer.

Afterinstallingthelatestsystemupdate,rebootthesuspendedHA
peer:

https://panorama/api/?type=op&cmd=<request><rest
art><system></system></restart></request>&target
=serialnumber&key=apikey
Step12 Verifythattheupgradeissuccessful.

ShowsysteminformationonyourupgradedHApeertoensureit
hasthelatestsystemupdateandisoperational:

https://panorama/api/?type=op&cmd=<show><system>
<info></info></system></show>&target=serialnumbe
r&key=apikey
Step13 MakesthesuspendedHApeeractive.

AfteryouverifythatthesystemupdateonthesuspendedHApeer
issuccessful,makeitactiveagain:

https://panorama/api/?type=op&cmd=<request><high
-availability><state><functional></functional></
state></high-availability></request>&target=seri
alnumber&key=apikey
Theresponseconfirmstheactivefirewallisnowactive:

<response status="success">
<result>Successfully changed HA state to
functional</result>
</response>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 33

UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)

PANOSXMLAPIUseCases

UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step14 Installthesystemupdateonthepassive OncethesuspendedHAfirewallisactive,youcanthenrepeat
HApeer.
steps58onthenowpassiveHApeer.

34 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes
ThisfollowingtopicsprovidecommonrequestexamplesthatyoucanusetobetterunderstandthePANOS
XMLAPI.

PANOSXMLAPIRequestTypesandActions

AsynchronousandSynchronousRequeststothePANOSXMLAPI

Configuration(API)

CommitConfiguration(API)

RunOperationalModeCommands(API)

GetReports(API)

ExportFiles(API)

ImportFiles(API)

RetrieveLogs(API)

ApplyUserIDMappingandPopulateDynamicAddressGroups(API)

GetVersionInfo(API)

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 35

PANOSXMLAPIRequestTypesandActions

PANOSXMLAPIRequestTypes

PANOSXMLAPIRequestTypesandActions
ThePANOSXMLAPIallowsyoutorunvariousrequestsdependingontherequesttypethatyouspecify:

RequestTypes

ConfigurationActions

RequestTypes
Youcancurrentlyusethefollowingrequesttypes:
Syntax

Description

type=keygen

GenerateAPIkeysforauthentication.

type=config

Modifytheconfiguration.

type=commit

Commitfirewallconfiguration,includingpartialcommits.

type=op

Performoperationalmodecommands,includingcheckingsystemstatusandvalidating
configurations.

type=report

Getreports,includingpredefined,dynamic,andcustomreports.

type=log

Getlogs,includingtraffic,threat,andeventlogs.

type=import

Importfilesincludingconfigurationsandcertificates.

type=export

Exportfilesincludingpacketcaptures,certificates,andkeys.

type=user-id UpdateUserIDmappings.
type=version ShowthePANOSversion,serialnumber,andmodelnumber.

ConfigurationActions
Inadditiontotherequesttypethatyouspecify,thesearetheavailableactionswhenmodifyingorreading
configurationsusingtype=config:

ActionsforModifyingaConfiguration

ActionsforReadingaConfiguration

36 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

PANOSXMLAPIRequestTypesandActions

ActionsforModifyingaConfiguration
ConfigurationActionType

Syntax

Setcandidateconfiguration

action=set

Editcandidateconfiguration

action=edit

Deletecandidateobject

action=delete

Renameaconfigurationobject

action=rename

Cloneaconfigurationobject

action=clone

Moveaconfigurationobject

action=move

Overrideatemplatesetting

action=override

Movemultipleobjectsinadevicegrouporvirtualsystem

action=multi-move

Clonemultipleobjectsinadevicegrouporvirtualsystem

action=multi-clone

ShowavailablesubnodevaluesandXPathsforagivenXPath.

action=complete

Setandeditactionsdifferintwoimportantways:

Setactionsadd,update,ormergeconfigurationnodes,whileeditactionsreplaceconfigurationnodes.

Setactionsarenondestructiveandareonlyadditive,whileeditactionscanbedestructive.

ActionsforReadingaConfiguration
ConfigurationActionType

Syntax

Getactiveconfiguration

action=show

Getcandidateconfiguration

action=get

Showandgetactionsdifferinthreeimportantways:

Showactionsretrievetheactiveconfiguration,whilegetactionsretrievethecandidate,uncommitted
configuration.
ShowactionsonlyworkwhentheprovidedXPathspecifiesasinglenode.Getactionsworkwithsingle
andmultiplenodes.
ShowactionscanuserelativeXPath,whilegetactionsrequireabsoluteXPath.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 37

AsynchronousandSynchronousRequeststothePANOSXMLAPI

PANOSXMLAPIRequestTypes

AsynchronousandSynchronousRequeststothePANOS
XMLAPI
MostPANOSXMLAPIrequestsaresynchronous,meaningtheresponseimmediatelyprovidesthe
requesteddata.Forexample,whenyouMakeYourFirstAPICallandrequestsysteminformation,theAPI
responseisimmediateandcontainsinformationsuchastheIPaddress,hostname,andmodelofyour
firewall.
However,therearesomeRequestTypesthatrequiremoretimetoprocessandareasynchronous,meaning
theyrequiremorethanonerequesttogetfinalresults.TheseAPIrequestsincludethefollowing:

GetReports(API)

RetrieveLogs(API)

ExportTechnicalSupportData

SomerequeststoRunOperationalModeCommands(API),includingdownload,upgrade,andinstallation
requests

Withasynchronousrequests,youfirstinitiatearequest.TheAPIrespondswithajobIDwhileitprocesses
yourrequest.Inyoursubsequentrequests,youusethisjobIDtocheckontheresultsofyouroriginal
request.

38 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

Configuration(API)

Configuration(API)
TherequestsexamplesinthesetopicsillustratehowyoucanusethePANOSXMLAPItoconfigureyour
firewall.

GetActiveConfiguration

GetCandidateConfiguration

SetConfiguration

EditConfiguration

DeleteConfiguration

RenameConfiguration

CloneConfiguration

MoveConfiguration

OverrideConfiguration

MultiMoveorMultiCloneConfiguration

ViewConfigurationNodeValuesforXPath

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 39

Configuration(API)

PANOSXMLAPIRequestTypes

GetActiveConfiguration
Usingaction=showwithnoadditionalparametersreturnstheentireactiveconfiguration.
GetActiveConfiguration
Step1

Usethexpathparametertotargetaspecificportionoftheconfiguration.Forexample,toretrievejustthe
securityrulebase:xpath=/config/devices/entry/vsys/entry/rulebase/security:

https://firewall/api/?type=config&action=show&key=apikey&xpath=/config/devices/entry/
vsys/entry/rulebase/security
ThereisnotrailingbackslashcharacterattheendoftheXPath.
Step2

ConfirmthattheXMLresponseforthequerylookssimilartothefollowing(truncated):

<response status="success">
<result>
<security>
<rules>
<entry name="IT DNS Services">
<profile-setting>
<group>
<member>best-practice</member>
</group>
</profile-setting>
<to>
<member>untrust</member>
</to>
<from>
<member>trust</member>
</from>
<source>
<member>any</member>
</source>
<destination>
<member>Data Center</member>
</destination>
<source-user>
<member>any</member>
</source-user>
<category>
<member>any</member>
</category>
<application>
<member>dns</member>
</application>
<service>
<member>application-default</member>
</service>
<hip-profiles>
<member>any</member>
</hip-profiles>
<action>allow</action>
<tag>
<member>Best Practice</member>
</tag>
<log-start>no</log-start>
<log-setting>default</log-setting>
</entry>
...
</rules>
</security>
</result>
</response>

GetARPInformation
Step1

UsethefollowingrequesttoretrieveARPinformation:

https://firewall//api/?type=op&command=<show><arp><entry name='all'/></arp></show>

40 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

Configuration(API)

GetARPInformation
Step2

ConfirmthattheXMLresponseforthequerylookslikethefollowing(truncated):

<response status="success">
<result>
<max>3000</max>
<total>16</total>
<timeout>1800</timeout>
<dp>dp0</dp>
<entries>
<entry>
<status>c</status>
<ip>10.47.0.1</ip>
<mac>00:1b:17:00:2f:13</mac>
<ttl>1743</ttl>
<interface>ethernet1/1</interface>
<port>ethernet1/1</port>
</entry>
<entry>
<status>c</status>
<ip>10.47.0.10</ip>
<mac>00:50:56:93:68:6f</mac>
<ttl>386</ttl>
<interface>ethernet1/1</interface>
<port>ethernet1/1</port>
</entry>
<!-- truncated -->
</result>
</response>

GetCandidateConfiguration
Getthecandidateconfigurationfromafirewallbyspecifyingtheportionoftheconfigurationtoget.Usethe
followingrequest,includingthexpathparametertospecifytheportionoftheconfigurationtoget.
https://firewall/api/?type=config&action=get&xpath=path-to-config-node

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 41

Configuration(API)

PANOSXMLAPIRequestTypes

ConfigurationNode

APIRequest

AddressobjectsinaVSYS.

https://firewall//api/?type=config&action=get&xpath=/confi
g/devices/entry/vsys/entry[@name='vsys1']/address
Theresponselookssimilartothefollowing:

<response status="success" code="19">

<result total-count="1" count="1">
<address admin="name" dirtyId="8" time="2015/10/20
15:32:36">
<entry name="testobject">
<ip-netmask>2.2.2.2</ip-netmask>
</entry>
<entry name="test1">
<ip-netmask>1.1.1.1</ip-netmask>
</entry>
...
</address>
</result>
</response>
PrerulespushedfromPanorama.

https://firewall//api/?type=config&action=get&xpath=/confi
g/panorama/vsys/entry[@name='vsys']/pre-rulebase/security

Detailedinformationon
https://firewall/api/?type=config&action=get&xpath=/config
ApplicationsandThreatsfromthe /predefined/threats/vulnerability/entry[@name='30003']
firewall.
Fulllistofallapplications.

https://firewall/api/?type=config&action=get&xpath=/config
/predefined/application

Detailsonthespecificapplication.

https://firewall/api/?type=config&action=get&xpath=/config
/predefined/application/entry[@name='hotmail']

SetConfiguration
Usingaction=set,youcanaddorcreateanewobjectataspecifiedlocationintheconfigurationhierarchy.
Usethexpathparametertospecifythelocationoftheobjectintheconfiguration.
Forexample,ifyouareaddinganewruletothesecurityrulebase,thexpathvaluewouldbe:
/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/rulebas
e/security
UsetheelementparametertospecifyavaluefortheobjectyouareaddingorcreatingusingitsXML
representation(asseenintheoutputofaction=show).

42 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

Configuration(API)

SetConfiguration
Step1

Createanewrulecalledrule1inthesecuritypolicy:

https://firewall/api/?type=config&action=set&key=keyvalue&xpath=xpath-value&element=e
lement-value
wherethexpathvalueis:
/config/devices/entry/vsys/entry/rulebase/security/rules/entry[@name='rule1']

andtheelementvalueis:
<source><member>src</member></source><destination><member>dst</member></destination><ser
vice><member>service</member></service><application><member>application</member></applic
ation><action>action</action><source-user><member>src-user</member></source-user><option
><disable-server-response-inspection>yes-or-no</disable-server-response-inspection></opt
ion><negate-source>yes-or-no</negate-source><negate-destination>yes-or-no</negate-destin
ation><disabled>yes-or-no</disabled><log-start>yes-or-no</log-start><log-end>yes-or-no</
log-end><description>description</description><from><member>src-zone</member></from><to>
<member>dst-zone</member></to>

Step2

UsetheresponsefromtheconfigshowAPIrequesttocreatetheXMLbodyfortheelement.

https://firewall/api/?type=config&action=show
Step3

Toaddanadditionalmembertoagroup/list,includethe'list'nodeinthexpathusingthe
member[text()='name'] syntaxandincludethemembersintheelementparameter.Forexample,toaddan
additionalstaticaddressobjectnamedabctoanaddressgroupnamedtest,use:

https://firewall/api/?type=config&action=set&xpath=/config/devices/entry/vsys/entry[@
name='vsys1']/address-group/entry[@name='test']&element=<static><member>abc</member><
/static>

EditConfiguration
Usingaction=edit,youcanreplaceanexistingobjecthierarchyataspecifiedlocationintheconfiguration
withanewvalue.Usethexpathparametertospecifythelocationoftheobject,includingthenodetobe
replaced.UsetheelementparametertospecifyanewvaluefortheobjectusingitsXMLobjecthierarchy(as
seenintheoutputofaction=show).
EditConfiguration
Step1

Replacetheapplication(s)currentlyusedinarulerule1withanewapplication:

https://firewall/api/?type=config&action=edit&key=apikey&xpath=xpath-value&element=el
ement-value
where
xpath=/config/devices/entry/vsys/entry/rulebase/security/rules/entry[@name='rule1']/appl
ication&element=<application><member>app-name</member></application>

Step2

UsetheresponsefromtheconfigshowAPIrequesttocreatetheXMLbodyfortheelement.

https://firewall/api/?type=config&action=show
Step3

Optionallyreplaceallmembersinanodewithanewsetofmembersusingtheentrytaginboththexpathand
elementparameters.Forexample,toreplacealltheaddressobjectsintheaddressgroupnamedtestwithtwo
newstaticmembersnamedabcandxyz,use:

https://firewall/api/?type=config&action=edit&xpath=/config/devices/entry/vsys/entry[
@name='vsys1']/address-group/entry[@name='test']&element=<static><entry
name='test'><member>abc</member><member>xyz</member></entry></static>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 43

Configuration(API)

PANOSXMLAPIRequestTypes

DeleteConfiguration
Usingaction=delete,youcandeleteanobjectataspecifiedlocationintheconfiguration.Usethexpath
parametertospecifythelocationoftheobjecttobedeleted.
DeleteConfiguration
Deletearulenamedrule1inthesecuritypolicy:

https://firewall/api/?type=config&action=delete&xpath=/config/devices/entry/vsys/entry
/rulebase/security/rules/entry[@name='rule1']
Deleteasinglememberobjectinagroup,usetheobjectnameinthexpathasmember[text()='name'].Forexample,
todeleteastaticaddressobjectnamedabcinanaddressgroupnamedtest,usethefollowingxpath:

https://firewall/api/?type=config&action=delete&xpath=/config/devices/entry/vsys/entry
[@name='vsys1']/address-group/entry[@name='test']/static/member[text()='abc']

RenameConfiguration
Usingaction=rename,youcanrenameanobjectataspecifiedlocationintheconfiguration.Usethexpath
parametertospecifythelocationoftheobjecttoberenamed.Usethenewnameparametertoprovideanew
namefortheobject.
RenameConfiguration
Step1

Renameanaddressobjectcalledold_addresstonew_addressusingthefollowingAPIquery:

https://firewall/api/?type=config&action=rename&xpath=/config/devices/entry/vsys/entr
y[@name='vsys1']/address/entry[@name='old_address']&newname=new_address
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:

<response status="success" code="20"><msg>command succeeded</msg></response>

CloneConfiguration
Usingaction=clone,youcancloneanexistingconfigurationobject.Usethexpathparametertospecifythe
locationoftheobjecttobecloned.Usethefromparametertospecifythesourceobject,andthenewname
parametertoprovideanamefortheclonedobject.
CloneConfiguration
Step1

Cloneasecuritypolicycalledrule1intorule2usingthefollowingAPIquery:

https://firewall/api/?type=config&action=clone&xpath=/config/devices/entry/vsys/entry
[@name='vsys1']/rulebase/security/rules&from=/config/devices/entry/vsys/entry[@name='
vsys1']/rulebase/security/rules/entry[@name='rule1']&newname=rule2

44 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

Configuration(API)

CloneConfiguration
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:
<response status="success" name="rule2"/>

AcorrespondingsuccesslogisrecordedintheConfigurationlog:
1,2014/03/19 19:07:45,0009C100708,CONFIG,0,0,2014/03/19
19:07:45,10.66.18.1,,clone,admin,Web,Succeeded, config devices entry vsys
vsys1 rulebase security rules,384,0x8000000000000000

MoveConfiguration
Usingaction=move,youcanmovethelocationofanexistingconfigurationobject.Usethexpathparameter
tospecifythelocationoftheobjecttobemoved,thewhereparametertospecifytypeofmove,anddst
parametertospecifythedestinationpath.

where=after&dst=xpath

where=before&dst=xpath

where=top

where=bottom

MoveConfiguration
Step1

Moveasecuritypolicycalledrule1afterrule2,usethefollowingAPIquery:

https://firewall/api/?type=config&action=move&xpath=/config/devices/entry/vsys/entry[
@name='vsys1']/rulebase/security/rules/entry[@name='rule1']&where=after&dst=rule2
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:

<response status="success" code="20"><msg>command succeeded</msg></response>

OverrideConfiguration
Usingaction=override,youcanoverrideasettingthatwaspushedtoafirewallfromatemplate.Usethe
xpathparametertospecifythelocationoftheobjecttooverride.
OverrideConfiguration
Step1

OverridetheSNMPTrapprofileconfigurationsettingsthatwerepushedtothefirewallusingatemplate:

https://firewall/api/?type=config&action=override&xpath=/config/shared/log-settings/s
nmptrap&element=<entry name="snmp" src="tpl"><version src="tpl"><v2c src="tpl"><server
src="tpl"><entry name="test" src="tpl"><manager src="tpl">2.2.2.2</manager><community
src="tpl">test</community></entry></server></v2c></version></entry>
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:

<response status="success" code="20"><msg>command succeeded</msg></response>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 45

Configuration(API)

PANOSXMLAPIRequestTypes

MultiMoveorMultiCloneConfiguration
Theaction=multi-moveandaction=multi-cloneactionsallowyoutomoveandcloneaddressesacross
devicegroupsandvirtualsystems.Templatesdonotsupportthemultimoveandmulticlonecapability.
Thesyntaxformultimoveandmulticlonespecifiesthexpathforthedestinationwheretheaddresseswill
bemovedto,thexpathforthesourceandthelistofobjectswithinthespecifiedsource.Italsoincludesa
flagfordisplayingtheerrorswhenthefirewallperformsareferentialintegritycheckonthemultimoveor
multicloneaction.
MultiMoveorMultiCloneConfiguration
Moveaddressesaddr1,addr2,todevicegroupnorcalfromdevicegroupsocal:

https://firewall/api/?type=config&action=multimove&xpath=/config/devices/entry[@name='
localhost.localdomain']/devicegroup/entry[@name='norcal']/address&element=<selected-li
st><source
xpath="/config/devices/entry[@name='localhost.localdomain']/devicegroup/entry[@name='s
ocal']/address"><member>addr1</member><member>addr2</member></source></selected-list><
all-errors>no</all-errors>
Cloneaddressesaddr1,addr2,todevicegroupnorcalfromdevicegroupsocal:

https://firewall/api/?type=config&action=multiclone&xpath=/config/devices/entry[@name=
'localhost.localdomain']/devicegroup/entry[@name='norcal']/address&element=<selected-l
ist><source
xpath="/config/devices/entry[@name='localhost.localdomain']/devicegroup/entry[@name='s
ocal']/address"><member>addr1</member><member>addr2</member></source></selected-list><
all-errors>no</all-errors>

ViewConfigurationNodeValuesforXPath
Theaction=completeactionallowsyoutoprovideanXPathandseethepossiblevaluesthatareavailable
undertheXPathnode.
ViewConfigurationNodeValuesforXPath
Step1

Viewthepossiblevalues,suchasnetworkinterfaces,formultivsysfirewalls,usethefollowingcommand:

https://firewall/api/?type=config&action=complete&xpath=/api/?type=config&action=get&
xpath=/config/devices/entry[@name='localhost.localdomain']/vsys&key=apikey
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:
<response status="success" code="19">
<completions>
<completion value="vsys1"
vxpath="/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']"
current="yes" help-string="vsys1"/>
</completions>
</response>

46 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

CommitConfiguration(API)

CommitConfiguration(API)
YoucancommitcandidateconfigurationtoafirewallusingthecommitAPIrequest.
YoucanvalidateacandidateconfigurationbeforecommittingitusingRunOperationalMode
Commands(API).

Commit

Commitall

Commit
UsetheAPIBrowsertofinddifferentoptionsavailableforusewithforceandpartialcommits.Replacethe
bodyelementinthecmdparameterwiththeXMLelementforthecorrespondingcommitoperation.
Commit
Step1

Useoneofthefollowingrequeststocommitaconfiguration:
Commit

https://firewall/api/?type=commit&cmd=<commit></commit>
ForceCommit

https://firewall/api/?type=commit&cmd=<commit><force></force></commit>
Partialcommit

https://firewall/api/?type=commit&cmd=<commit></commit>
Step2

ConfirmthattheXMLresponsefortherequestlookslikeoneofthefollowing:
Nopendingchangestocommit
<response status="success" code="19">
<msg>There are no changes to commit.</msg>
</response>

Pendingchanges
<response status="success" code="19">
<result>
<msg>
<line>Commit job enqueued with jobid 4</line>
</msg>
<job>4</job>
</result>
</response>

Step3

QuerythestatusofthejobusingthejobID:

https://firewall/api/?type=op&cmd=<show><jobs><id>4</id></jobs></show>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 47

CommitConfiguration(API)

PANOSXMLAPIRequestTypes

Commit
Step4

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:
<response status="success">
<result>
<job>
<tenq>2011/10/20 20:41:44</tenq>
<id>4</id>
<type>Commit</type>
<status>FIN</status>
<stoppable>no</stoppable>
<result>OK</result>
<tfin>20:42:22</tfin>
<progress>20:42:22</progress>
<details>
<line>Configuration committed successfully</line>
</details>
<warnings />
</job>
</result>
</response>

Commitall
TocentrallymanagefirewallsfromPanorama,youcanusethecommitallAPIrequesttypetopushand
validatesharedpolicytothefirewallsusingdevicegroupsandconfigurationtothefirewallsusingtemplates
ortemplatestacks.
CommitType

APIRequest

Precommitpolicyvalidation.

https://panorama/api/?type=commit&action=all&cmd=
<commit-all><shared-policy><validate-only></validate-only>
</shared-policy></commit-all>

Devicegroupcommit.

https://panorama/api/?type=commit&action=all&cmd=<commit-a
ll><shared-policy><device-group><entry%20name="device-grou
p-name"/></device-group></shared-policy></commit-all>

VSYScommit.

https://panorama/api/?type=commit&action=all&cmd=<commit-a
ll><shared-policy><device-group><entry%20name="device-grou
p-name"/><devices><entry%20name="serial_number"><vsys><mem
ber>vsys-name</member></vsys></entry></devices></device-gr
oup></shared-policy></commit-all>

Specificfirewallcommit.

https://panorama/api/?type=commit&action=all&cmd=<commit-a
ll><shared-policy><device-group><entry%20name="device-grou
p-name"><devices><entry%20name="serial_number"></devices><
entry/></device-group></shared-policy></commit-all>

UsetheAPIBrowsertofindotheroptionsavailableforgranularcommitoperationsonPanorama.Inthecmd
parameter,youmustreplacetheXMLelementforthecorrespondingcommit-alloperation.

48 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

RunOperationalModeCommands(API)

RunOperationalModeCommands(API)
UseanyoftheoperationalmodecommandsavailableonthecommandlineinterfaceusingthefollowingAPI
request:
https://firewall/api/?type=op&cmd=xml-body
UsetheAPIBrowsertoexploreoperationalmodecommandsandacompletelistingofalltheoptions
availableforthexml-bodyandtheircorrespondingoperation.
OperationalCommand

APIRequest

Systemrestart.

https://firewall/api/?type=op&cmd=<request><restart><syste
m></system></restart></request>

Systemsoftwareversion
installation.

https://firewall/api/?type=op&cmd=<request><system><softwa
re><install><version>version_number</version></install></s
oftware></system></request>

Multivsysmode.

https://firewall/api/?type=op&cmd=<set><system><setting><m
ulti-vsys></multi-vsys></setting></system></set>

UserActivityReportscheduling.

https://firewall/api/?type=op&cmd=<schedule><uar-report><u
ser>username</user><title>titlename</title></uar-report></
schedule>

Fullconfigurationvalidation.

https://firewall/api/?type=op&cmd=<validate><full></full><
/validate>

Partialconfigurationvalidation.

https://firewall/api/?type=op&cmd=<validate><partial><devi
ce-and-network>excluded</device-and-network></partial></va
lidate>

Configurationsaving.

https://firewall/api/?type=op&cmd=<save><config><to>filena
me</to></config></save>

Configurationloading.

https://firewall/api/?type=op&cmd=<load><config><from>file
name</from></config></load>

Somerequestsoperationalmodecommands,includingdownload,upgrade,andinstallation
requests,areasynchronous,meaningtheyrequiremorethanonerequesttogetfinalresults.
LearnmoreaboutAsynchronousandSynchronousRequeststothePANOSXMLAPI.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 49

GetReports(API)

PANOSXMLAPIRequestTypes

GetReports(API)
TheXMLAPIprovidesawaytoquicklypulltheresultsofanyreportdefinedinthesystemusingthe
ype=reportparameter.
Youcanaccessthreekindsofreports:

DynamicReports(ACCreports)reporttype=dynamic

PredefinedReportsreporttype=predefined

CustomReportsreporttype=custom

Toretrieveaspecificreportbyname,usethereportnameparameter:
https://firewall/api/?type=report&reporttype=dynamic|predefined|custom&reportname=name
Whenyourequestareport,theAPIrespondsasynchronouslywithajobID,whichyoucanuseto
retrievethereports.LearnmoreaboutAsynchronousandSynchronousRequeststothePANOS
XMLAPI.

DynamicReports

PredefinedReports

CustomReports

DynamicReports
YoucanviewanumberofdynamicreportsusingtheAPIsuchastop-applications-summary,
top-blocked-url-summary,andtop-spyware-threats-summary.Fordynamicreports,youcanprovidethe
eitheraspecificperiodusingtheperiodoratimeframeusingstarttimeandendtimeoptions(usea+instead
ofaspacebetweenthedateandtimestamp).Usetopntodeterminethenumberofrows.
DynamicReportType

APIRequest

Fulldynamicreportlist.

https://firewall/api/?type=report&reporttype=dynamic

Last60seconds.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-60-seconds&topn=5

Last15minutes.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-15-minutes&topn=5

Lasthour.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-hour&topn=5

Last12hours.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-12-hrs&topn=5

Lastcalendarday.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-calendar-day&topn=5

Last7days

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-7-days&topn=5

50 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

GetReports(API)

DynamicReportType

APIRequest

Last7calendardays

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-hour&topn=5

Lastcalendarweek.

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-calendar-week&topn=5

Last30days

https://firewall/api/?type=report&reporttype=dynamic&repor
tname=top-app-summary&period=last-30-days&topn=5

PredefinedReports
Predefinedreportsalwaysreturndataforthelast24hourperiod.Youcanalsogetthislistbyfollowingthe
linkforpredefinedreports,suchastop-applications,top-attackers,andbandwidth-trendontheAPI
browser.
DynamicReportType

APIRequest

Fullpredefinedreportlist.

https://firewall/api/?type=report&reporttype=predefined

Topapplications.

https://firewall/api/?type=report&async=yes&reporttype=pre
defined&reportname=top-application-categories

Topattackers.

https://firewall/api/?type=report&async=yes&reporttype=pre
defined&reportname=top-attackers

Topvictims.

https://firewall/api/?type=report&async=yes&reporttype=pre
defined&reportname=top-victims

CustomReports
Forcustomreports,theselectioncriteria,suchastimeframe,groupby,andsortbyarepartofthereport
definition.TheAPIreturnsanysharedcustomreports.Notethatquotesarenotrequiredaroundthereport
nameandanyspacesinthereportnamemustbeURLencodedto%20.
ForcustomreportscreatedinaspecificVSYS,youcanretrievethemdirectlybyspecifyingthevsys
parameters.
GetaCustomDynamicReport
Step1

Retrievethereportdefinitionfromtheconfiguration:

https://firewall/api/?type=config&action=get&xpath=/config/devices/entry/vsys/entry[@
name='vsys1']/reports/entry[@name='report-abc']

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 51

GetReports(API)

PANOSXMLAPIRequestTypes

GetaCustomDynamicReport
Step2

Createajobtoretrieveadynamicreportusingreporttype=dynamic,
reportname=custom-dynamic-report,andcmd=report-definitionwherereport-definitionisthe
XMLdefinitionretrievedinthepreviousquery:

https://firewall/api/?type=report&reporttype=dynamic&reportname=custom-dynamic-report
&cmd=<type><appstat><aggregate-by><member>category-of-name</member><member>technology
-of-name</member></aggregate-by></appstat></type><period>last-24-hrs</period><topn>10
</topn><topm>10</topm><query>(name neq '') AND (vsys eq 'vsys1')</query>
TheresponseincludesthejobIDyoucanusetoviewtheresults:

<response status="success">
<result>
<msg>
<line>Report job enqueued with jobid 6</line>
</msg>
<job>6</job>
</result>
</response>
Step3

Viewthedynamicreport:

https://firewall/api/?type=report&action=get&job-id=jobid

52 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ExportFiles(API)

ExportFiles(API)
Youcanexportcertaintypesoffilesfromthefirewallusingthetype=exportparameterintheAPIrequest.
Usethecategoryparametertospecifythetypeoffilethatyouwanttoexport.

Configurationcategory=configuration

Certificates/Keyscategory=certificate | high-availability-key | key-pair

Responsepagescategory= application-block-page | captive-portal-text |

file-block-continue-page | file-block-page | global-protect-portal-custom-help-page |
global-protect-portal-custom-login-page | global-protect-portal-custom-welcome-page |
ssl-cert-status-page | ssl-optout-text | url-block-page | url-coach-text | virus-block-page>

Technicalsupportdatacategory=tech-support

DeviceStatecategory=device-state

UsecURLtoolstoexportthefilefromthefirewallandsavelocallywithalocalfilename:
curl -o filename "https://firewall/api/?query-parameters"
WhenusingtheAPIqueryfromawebbrowser,youcanspecifyto=filenameasanoptionalparameterifyou
wouldliketoprovideadifferentnamewhensavingthefilelocally.

ExportPacketCaptures

ExportCertificatesandKeys

ExportTechnicalSupportData

ExportPacketCaptures
YoucanexportpacketcapturesfromthefirewallbyspecifyingthePCAPtypeusingthecategoryparameter:

ExportApplicationPCAPS

ExportThreat,Filter,andDataFilteringPCAPs

ExportCertificatesandKeys

ExportApplicationPCAPS
ApplicationPCAPsareorganizedbyadirectory/filenamestructurewherethedirectoryisadatein
yyyymmddformat.Filenamesforapplicationpcapsusea
SourceIP-SourcePort-DestinationIP-DestinationPort-SessionID.pcapformat.
ApplicationPCAPType

APIRequest

ApplicationPCAPdirectorylist.

https://firewall/api/?type=export&category=application-pca
p

Listoffilesunderadirectoryusing https://firewall/api/?type=export&category=application-pca
thefromparametertoindicate
p&from=yyyymmdd
date.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 53

ExportFiles(API)

PANOSXMLAPIRequestTypes

ApplicationPCAPType

APIRequest

ApplicationPCAPfilebyname
usingthefromparameter.

https://firewall/api/?type=export&category=application-pca
p&from=yyyymmdd/filename
Thefilewillberetrievedandsavedlocallyusingthenameyyyymmddfilename.

ApplicationPCAPfilesavedlocally https://firewall/api/?type=export&category=application-pca
withacustomnameusingtheto p&from=yyyymmdd/filename&to=localfile
parameter.

ExportThreat,Filter,andDataFilteringPCAPs
ToexportthreatPCAPs,youneedtoprovidethePCAPIDfromthethreatlogandthesearchtime,whichis
thetimethatthePCAPwasreceivedonthefirewall.ThreatPCAPfilenamesuseapcapID.pcapformat.
PCAPType

APIRequest

ThreatPCAPusingPCAPIDand
search

https://firewall/api/?type=export&category=threat-pcap&pca
p-id=id&search-time=yyyy/mm/dd hr:min:sec

ListoffilteredPCAPs

https://firewall/api/?type=export&category=filters-pcap

SpecificfilteredPCAPfile

https://firewall/api/?type=export&category=filters-pcap&fr
om=filename

ListofdatafilteringPCAPfile
names

https://firewall/api/?type=export&category=dlp-pcap&dlp-pa
ssword=password

SpecificdatafilteringPCAPfile

https://firewall/api/?type=export&category=dlp-pcap&dlp-pa
ssword=password&from=filename&to=localfile

ExportCertificatesandKeys
ExportCertificatesandKeys
Step1

Toexportcertificatesandkeys,specifyqueryparameterscertificate-name,format,andpassphrase:

https://firewall/api/?type=export&category=certificate&certificate-name=certificate_n
ame&format=pkcs12 | pem&include-key=yes | no&vsys=vsys | omit this parameter to import
it into a shared location

certificate-namenameofthecertificateobjectonthefirewall
formatcerficateformat,pkcs12orpem
include-keyyesornoparametertoincludeorexcludethekey
passphraserequiredwhenincludingthecertificatekey
vsysvirtualsystemwherethecertificateobjectisused.Ignorethisparameterifthecertificateisasharedobject.

54 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ExportFiles(API)

ExportCertificatesandKeys
Step2

ConfirmthattheXMLresponseincludesthecertificate:

-----BEGIN CERTIFICATE----MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3Df
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVx
aWRnaXRzIFB0eSBMdGQwHhcNMTExMjMxMDg1OTQ0WhcNMT
<!-- TRUNCATED -->
-----END CERTIFICATE-----

ExportTechnicalSupportData
Debuglogdatasizesarelarge,sotheAPIusesanasynchronousjobschedulingapproachtoretrievetechnical
supportdata.LearnmoreaboutAsynchronousandSynchronousRequeststothePANOSXMLAPI.The
valuesfortheactionparameterare:

action=<null>When

an action parameter is not specified, the system creates a new job to retrieve tech
support data. The initial query creates a job ID that you can then use to check on the status of the job,
retrieve results, or delete the job.

action=statusCheckthestatusofthejob.ThisreturnsanXMLresponsewithastatuselement;when
thestatustextdataisFINthejobiscompletedandthetechsupportfilecanberetrieved.Example:
https://firewall/api/?type=export&category=tech-support&action=status&job-id=299
action=getRetrievethetechsupportfileasanattachment.Theresponsecontainsa
application/octet-streamcontenttypeandacontentdispositionheaderwithasuggestedfilename;for
example:
Content-Type: application/octet-stream
Content-Length: 19658186
Content-Description: File Transfer
Content-Transfer-Encoding: binary
Content-Disposition: attachment; filename=techsupport-8469.tgz

action=finishStopanactivejob.

ExportTechnicalSupportData
Step1

Createajobtoretrievetechnicalsupportdata.
Usethefollowingrequest:

https://firewall/api/?type=export&category=tech-support
TheresponseincludesajobID:
<response status="success" code="19">
<result>
<msg>
<line>Exec job enqueued with jobid 2</line>
</msg>
<job>2</job>
</result>
</response>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 55

ExportFiles(API)

PANOSXMLAPIRequestTypes

ExportTechnicalSupportData(Continued)
Step2

Checkonthestatusofthejob.
UsethejobIDreturnedinthepreviousresponseasthejobidparameter:

https://firewall/api/?type=export&category=tech-support&action=get&job-id=id
AstatusvalueofFINindicatesthedataisreadytoberetrieved.
<response status="success">
<result>
<job>
<tenq>2012/06/14 10:11:09</tenq>
<id>2</id>
<user />
<type>Exec</type>
<status>FIN</status>
<stoppable>no</stoppable>
<result>0K</result>
<tfin>10:12:39</tfin>
<progress>10:12:39</progress>
<details />
<warnings />
<resultfile>//tmp/techsupport.tgz</resultfile>
</job>
</result>
</response>

Step3

Retrievethetechsupportdata.

https://firewall/api/?type=export&category=tech-support&action=get&job-id=id
WhenusingcURL,youcanspecifytheoutputfilenameasanoptiontocURL(-o).Afterasuccessfulretrieval
ofthejobdata,thejobisautomaticallydeletedbythesystem.
Step4

(Optional)Stoptheactivejobincaseoferror.
Ifthereisanerrororissuewiththeexportjob,itmaynotcomplete.Incaseslikethis,stoptheactivejob:

https://firewall/api/?type=export&category=tech-support&action=finish&job-id=id
Theresponseincludesasuccessmessage:

<response status"success">
<msg>Job 2 removed.</msg>
</response>

56 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ImportFiles(API)

ImportFiles(API)
Youcanimportcertaintypesoffiles,includingassoftware,content,licenses,andconfigurationsintothe
firewallusingthetype=importparameterintheAPIrequest.
Usetype=importandspecifythecategorytoimportthesetypesoffiles:

Softwarecategory=software

Contentcategory=<anti-virus | content | url-database | signed-url-database>

Licensescategory=license

Configurationcategory=configuration

Certificates/keycategory=<certificate | high-availability-key | key-pair>

Responsepagescategory=< application-block-page | captive-portal-text |

file-block-continue-page | file-block-page | global-protect-portal-custom-help-page |
global-protect-portal-custom-login-page | global-protect-portal-custom-welcome-page |
ssl-cert-status-page | ssl-optout-text | url-block-page | url-coach-text | virus-block-page>

Clientscategory=global-protect-client

Customlogocategory=custom-logo

ImportingBasics

ImportFiles

ImportingBasics
UsecURLtoimportfilestothefirewall.
ImportFilestoaFirewallorPanorama
Importfilestoafirewall:

curl --form file=@filename https://firewall/api/?query-parameters

ImportfilestoafirewallviaPanorama.FirstimportthefiletoPanorama,thenrunarequestbatchuploadinstallop
command:

http://panorama/api/?type=op&cmd=<request><batch><anti-virus><upload-install><uploaded
-file>your-file-name-here</uploaded-file><devices>serialnumber</devices></upload-insta
ll></anti-virus></batch></request>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 57

ImportFiles(API)

PANOSXMLAPIRequestTypes

ImportFiles
UsetheAPIBrowsertoseeafulllistofimportcategories.
ImportCertificates,Keys,ResponsePages,orCustomLogos
importacertificateorkeybyspecifyingthetypeofthecertificateorkeyfileusingthecategoryparameter
category=certificate
category=keypair
category=high-availability-key
Thecertificatefileimport(category=certificate)andkeypairimport(category=keypair)taketheseadditional
parameters.
certificate-namenameofthecertificateobjectonthefirewall
formatcertificateformat,pkcs12orpem
passphraserequiredwhenincludingthecertificatekey
vsysvirtualsystemwherethecertificateobjectisused.Ignorethisparameterifthecertificateisashared
object.

https://firewall/api/?type=import&category=certificate&certificate-name=certificate_na
me&format=pkcs12 | pem&passphrase=text&vsys=vsys
ImportaGlobalProtectresponsepagesusinganadditionalparameterforthesecurityprofileinwhichthe

pageshouldbeimported:
profile=profilename

Importcustomlogostodifferentlocationsbasedonthewhereparameter:

where=<login-screen | main-ui | pdf-report-footer | pdf-report-header>

58 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

RetrieveLogs(API)

RetrieveLogs(API)
RetrievelogsfromthefirewallusingtheAPIwiththetype=logparameter.Thetypeoflogstoretrievemust
bespecifiedusingthelogtypeparameter:

log-type=traffictrafficlogs

log-type=threatthreatlogs

log-type=configconfiglogs

log-type=systemsystemlogs

log-type=hipmatchHIPlogs

log-type=wildfireWildFirelogs

log-type=urlURLfilteringlogs

log-type=datadatafilteringlogs

log-type=corrcorrelatedeventlogsasseenintheuserinterfacewithinMonitor>Automated Correlated

Engine>Correlated Events.

log-type=corr-detailcorrelatedeventdetailsasseenintheuserinterfacewhenyouselectanevent
withinMonitor>Automated Correlated Engine>Correlated Events.
log-type=corr-categcorrelatedeventsbycategory,currentlycompromisedhostsseenwithinACC>

Threat Activity>Compromised Hosts.

Theotheroptionalparameterstothisrequestare:

queryparameterSpecifymatchcriteriaforthelogs.ThisissimilartothequeryprovidedintheWebUI
undertheMonitortabwhenviewingthelogs.ThequerymustbeURLencoded.
nlogsparameterSpecifythenumberoflogstoretrieve.Thedefaultis20whentheparameterisnot
specified.Themaximumis5000.
skipparameterspecifythenumberoflogstoskipwhendoingalogretrieval.Thedefaultis0.Thisis
usefulwhenretrievinglogsinbatcheswhereyoucanskipthepreviouslyretrievedlogs.
dirparameterspecifywhetherlogsareshowninoldestfirst(forward)ornewestfirst(backward)order.

Thedefaultdirectionisbackward.
Sincelogdatasizescanbelarge,theAPIusesanasynchronousjobschedulingapproachtoretrievelogdata.
TheinitialqueryreturnsaJobIDthatyoucanuseforfuturequerieswiththeactionparameter.Learnmore
aboutAsynchronousandSynchronousRequeststothePANOSXMLAPI.Thevaluesfortheaction
parameterare:

Unspecifiedwhentheactionparameterisnotspecified,thesystemcreatesanewjobtoretrievelog
data.
action=gettocheckstatusandretrievethelogdatawhenthestatusisFIN.(Thisisaslightdifference
fromtheasynchronousapproachtoretrievetechsupportdatawhereaseparationstatusactionwas
available)
action=finishtostopandactivejob.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 59

RetrieveLogs(API)

PANOSXMLAPIRequestTypes

RetrieveTrafficLogs
Step1

Createajobtoretrievealltrafficlogsthatoccurredafteracertaintime:

https://firewall/api/?type=log&log-type=traffic&query=(receive_time geq '2012/06/22

08:00:00')
AwebbrowserwillautomaticallyURLencodetheparameters,butwhenusingcURL,thequery
parametermustbeURLencoded.
Response:
<response status="success" code="19">
<result>
<msg>
<line>query job enqueued with jobid 18</line>
</msg>
<job>18</job>
</result>
</response>

Step2

RetrievetrafficlogdatausingthefollowingrequestusingthejobIDasthevaluereturnedintheprevious
response:

https://firewall/api/?type=log&action=get&job-id=id
Step3

ConfirmthattheXMLresponselookssimilartothefollowing:
<response status="success"">
<result>
<job>...</job>
<log>
<logs count="20" progress="100n>
<entry logid="5753304543500710425"> <domain>1</domain> <receive_time>2012/06/13
15:43:17</receive_time> <serial>001606000117</serial> <segno>6784588</segno>
<actionflags>0x0</actionflags> <type>TRAFFIC</type> <subtype>start</subtype>
<config_ver>1</config_ver> <time_generated>2012/06/13 15:43:17</time_generated>
<src>172.16.1.2</src> <dst>10.0.0.246</dst> <natsrc>10.16.0.96</natsrc>
<natdst>10.0.0.246</natdst> <rule>default allow</rule>

WhenthejobstatusisFIN(finished),theresponseautomaticallyincludesallthelogsintheXMLdata
response.The<log>nodeinXMLisnotpresentwhenthejobstatusisstillpending.Aftersuccessfullogdata
retrieval,thesystemautomaticallydeletesthejob.
Step4

(Optional)Deleteandactivelogretrievaljob.Todeleteanactivelogretrievaljob,runthefollowingquery:

https://firewall/api/?type=log&action=finish&job-id=id
AsuccessfulcompletionreturnsajobID.

60 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ApplyUserIDMappingandPopulateDynamicAddressGroups(API)

ApplyUserIDMappingandPopulateDynamicAddress
Groups(API)
Usethetype=user-idparametertoapplyUserIDmappinginformationdirectlytothefirewall.Ifyouare
usingathirdpartyVPNsolutionorhaveuserswhoareconnectingtoa802.1xenabledwirelessnetwork,
theUserIDAPIenablesyoutomapuserstogroupssothatyoucancapturelogineventsandsendthemto
theUserIDagentordirectlytothefirewall.Incaseslikethis,youcanusetheAPItocaptureloginevents
andsendthemtotheUserIDagentordirectlytothefirewall.Additionally,youcanusetheAPItoregister
theIPtousermappinginformation,fromtheinputfile,topopulatethemembersofaDynamicAddress
Grouponthefirewall.
curl -F key=apikey --form file=@filename "https://firewall/api/?type=user-id"
or
curl --data-urlencode key=apikey -d type=user-id --data-urlencode "cmd=xml-document"
https://firewall/api/
WithyourUserIDAPIrequests,youcanusethefollowingoptionalparameters:

vsys=vsys_idSpecifythevsyswhereyouwanttoapplyUserIDmapping.

target=serialnumberSpecifythefirewallbyserialnumberwhenredirectingthroughPanorama.

MappingorRegistrationAction

APIRequest

UserIDmappingforalogin,
logout,orgroups.

UsethisinputfileformatwhenprovidingaUserIDmappingforaloginevent,
logoutevent,orforgroups:
<uid-message>
<version>1.0</version>
<type>update</type>
<payload>
<login>
<entry name="domain\uid1" ip="10.1.1.1" timeout="20">
</entry>
</login>
<groups>
<entry name="group1">
<members>
<entry name="user1"/>
<entry name="user2"/>
</members>
</entry>
<entry name="group2">
<members>
<entry name="user3"/>
</members>
</entry>
</groups>
</payload>
</uid-message></uid-message>
YoucanincludeaHIPreportbyincludinga<hip-report></hip-report>XML
containerwithinan<entry>parentelement.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 61

ApplyUserIDMappingandPopulateDynamicAddressGroups(API)

PANOSXMLAPIRequestTypes

MappingorRegistrationAction

APIRequest

MultiUserSystemEntry

Usethefollowinginputfileformattosetupaterminalserverentryonthefirewall
andtospecifytheportrangeandblocksizeofportsthatwillbeassignedperuser.
Ifyouareusingthedefaultportrange(1025to65534)andblocksize(200)you
donotneedtosendamultiusersystemsetupmessage;thefirewallwill
automaticallycreatetheterminalserverobjectwhenitreceivesthefirstlogin
message.
<uid-message>
<payload>
<multiusersystem>
<entry ip="10.1.1.2" startport="xxxxx"
endport="xxxxx" blocksize="xxx">
</multiusersystem>
</payload>
<type>update</type>
<version>1.0</version>
</uid-message>

UserIDXMLmultiusersystem
loginevent

Whentheterminalserverssendsalogineventpayloadtothefirewall,itcan
containmultipleloginevents.Thefirewallusestheinformationintheinformation
intheloginmessagetopopulateitsusermappingtable.Forexample,ifthefirewall
receivedapacketwithasourceaddressandportof10.1.1.23:20101,itwould
maptherequesttouserjparkerforpolicyenforcement.
<uid-message>
<payload>
<login>
<entry name="acme\jparker" ip="10.1.1.23"
blockstart="20100">
</login>
</payload>
<type>update</type>
<version>1.0</version>
</uid-message>

UserIDXMLmultiusersystem Uponreceiptofalogouteventmessagewithablockstartparameter,thefirewall
logout
removesthecorrespondingIPaddressportusermapping.Ifthelogoutmessage
containsausernameandIPaddress,butnoblockstartparameter,thefirewall
removesallmappingsfortheuser.IfthelogoutmessagecontainsanIPaddress
only,thefirewallremovesthemultiusersystemandallassociatedmappings.
<uid-message>
<payload>
<logout>
<entry user="domain\uid2" ip="10.1.1.2"
blockstart="xxxxx">
</logout>
</payload>
<type>update</type>
<version>1.0</version>
</uid-message>

62 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

MappingorRegistrationAction

ApplyUserIDMappingandPopulateDynamicAddressGroups(API)

APIRequest

DynamicAddressGroupIPaddress <uid-message>
<version>1.0</version>
registration
<type>update</type>
<payload>
<register>
<entry ip="10.1.1.1">
<tag>
<member>CBB09C3D-3416-4734-BE90-0395B7598DE3</member>
</tag>
</entry>
</register>
<unregister>
<entry ip="10.1.1.3"/>
<tag>
<member>CBB09C3D-3416-4734-BE90-0395B7598DE5</member>
</tag>
</entry>
</unregister>
</payload>
</uid-message>

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 63

GetVersionInfo(API)

PANOSXMLAPIRequestTypes

GetVersionInfo(API)
Usethetype=versionrequesttypeshowthePANOSversionforafirewallorPanorama.Inadditiontothe
PANOSversion,thisrequestprovidesadirectwaytoobtaintheserialnumberandmodelnumber.
GetVersionInfo(API)
Step1

MakearequesttothePANOSXMLAPIandwithtype=versionalongwithyourAPIkey:

https://firewall/api/?type=version&key=apikey
Step2

TheXMLresponsecontainsthesoftwareversion,model,serialnumber,andwhethermultivsysmodeison:
<response status="success">
<result>
<sw-version>7.1.0</sw-version>
<multi-vsys>off</multi-vsys>
<model>pa-vm</model>
<serial>007000001222</serial>
</result>
</response>

64 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIErrorCodes
TheAPIresponseXMLcontainsastatusfieldandanerrorfield.ThesearetheavailableAPIerrorcodesand
names:
Error
Code

Name

Description

400

Badrequest

Arequiredparameterismissing,anillegalparametervalueisused.

403

Forbidden

Authenticationorauthorizationerrorsincludinginvalidkeyor
insufficientadminaccessrights.LearnhowtoGetYourAPIKey.

Unknowncommand

Thespecificconfigoroperationalcommandisnotrecognized.

25

Internalerrors

Checkwithtechnicalsupportwhenseeingtheseerrors.

BadXpath

Thexpathspecifiedinoneormoreattributesofthecommandisinvalid.
ChecktheAPIbrowserforproperxpathvalues.

Objectnotpresent

Objectspecifiedbythexpathisnotpresent.Forexample,
entry[@name='value']wherenoobjectwithname'value'ispresent.

Objectnotunique

Forcommandsthatoperateonasingleobject,thespecifiedobjectisnot
unique.

10

Referencecountnotzero

Objectcannotbedeletedasthereareotherobjectsthatrefertoit.For
example,addressobjectstillinuseinpolicy.

11

Internalerror

Checkwithtechnicalsupportwhenseeingtheseerrors.

12

Invalidobject

Xpathorelementvaluesprovidedarenotcomplete.

14

Operationnotpossible

Operationisallowedbutnotpossibleinthiscase.Forexample,moving
aruleuponepositionwhenitisalreadyatthetop.

15

Operationdenied

Operationisallowed.Forexample,Adminnotallowedtodeleteown
account,Runningacommandthatisnotallowedonapassivedevice.

16

Unauthorized

TheAPIroledoesnothaveaccessrightstorunthisquery.

17

Invalidcommand

Invalidcommandorparameters.

18

Malformedcommand

TheXMLismalformed.

1920

Success

Commandcompletedsuccessfully.

21

Internalerror

Checkwithtechnicalsupportwhenseeingtheseerrors.

22

Sessiontimedout

Thesessionforthisquerytimedout.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 65

PANOSXMLAPIErrorCodes

66 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.