PANOS and

Panorama
XMLAPIUsage
Guide
Version7.1

ContactInformation
CorporateHeadquarters:

PaloAltoNetworks
4401GreatAmericaParkway
SantaClara,CA95054
[Link]

AboutthisGuide
[Link],refer
tothefollowingresources:

ForinformationonhowtoconfigureothercomponentsinthePaloAltoNetworksNextGenerationSecurity
Platform,gototheTechnicalDocumentationportal:[Link]
searchthedocumentation.

Foraccesstotheknowledgebase,discussionforums,andvideos,referto[Link]

Forcontactingsupport,forinformationonsupportprograms,tomanageyouraccountordevices,ortoopena
supportcase,referto[Link]

ForthemostcurrentPANOSandPanorama7.1releasenotes,goto
[Link]

Toprovidefeedbackonthedocumentation,pleasewritetousat:documentation@[Link].

PaloAltoNetworks,Inc.
[Link]
2016PaloAltoNetworks,[Link]
at[Link]
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
[Link],application,
orscript.
[Link]
request,youmustspecifytheXPath(XMLPathLanguage)totheXMLnodethatcorrespondstoaspecific
[Link]
Panorama.
UsethePANOSXMLAPItoautomatetaskssuchas:

create,update,andmodifyfirewallandPanoramaconfigurations

executeoperationalmodecommands,suchasrestartthesystemorvalidateconfigurations

retrievereports

manageusersthroughUserID

updatedynamicobjectswithouthavingtomodifyorcommitnewconfigurations

BecausePANOSXMLAPIfunctionalitymirrorsthatofthewebinterfaceandCLI,familiarizeyourselfwith
[Link]
[Link]
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 [Link]
functionalityincludingreports,logs,andoperationalmodecommands.
adminroles
OptionstoviewXML
syntaxthroughAPI
browser,CLIandweb
interfacedebugmode

ToexploreallvariousfunctionsoftheAPI,youcanusetheAPIbrowserthroughthe
[Link]
APIequivalentofCLIcommands.

6 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

AboutthePANOSXMLAPI

StructureofaPANOSXMLAPIRequest

StructureofaPANOSXMLAPIRequest
AnAPIrequesttypicallycomprisesofanumberofparameters,asshownintheexamplebelow:
[Link]

APIkey(key=):[Link]
aboutAPIAuthenticationandSecurityandhowtoGetYourAPIKey.
Requesttype(type=):BecausetheXMLAPIallowsyoutoperformwidearrayofrequests,youmustfirst
specifythetypeofrequestyouwant,rangingfromconfigurationtooperation,importingtoexporting,
[Link].
Action(action=):Whentherequesttypeisconfig(configuration)orop(operationalmodecommand),you
mustalsospecifyanassociatedaction,suchasedit,delete,[Link]
Actions.

XMLandXPathelements(xpath=orcmd=):Whenusingconfigurationoroperationalmodecommandsonthe
firewall,[Link]
andXPathandXPathNodeSelection.
[Link]
youaresendinglargeamountsofformdata,[Link]
requests,suchasimportingfiles,[Link].
WhenusingtheGETmethod,appendthequerystringtotherequestURLasaURLencodedparameter
string:
GET /api/?type=keygen&user=username&password=password
WhenusingthePOSTmethod,[Link],therequestbody
includesthelogincredentials:
POST /api/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
password=password&user=username&type=keygen

APIAuthenticationandSecurity
Bydefault,[Link],youmustGetYourAPIKeyandinclude
[Link],youcanuseBasicAuthenticationwithyour
admincredentialsbypassingtheBase64encodedusername:passwordinaAuthorizationheaderfield:
Authorization: Basic amJPbLxpbw9UaTpXb3JrKjIwMDA=
YoucannotusebasicauthenticationwhenyouGetYourAPIKey.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 7

StructureofaPANOSXMLAPIRequest

AboutthePANOSXMLAPI

XMLandXPath
[Link],constructan
[Link]
exampleAPIrequest:
[Link]
/vsys/entry/rulebase/security
EnsureyoureplacevariablessuchashostnameandAPIkeywiththeIPaddressorhostnameofyourfirewall
orPanoramaandAPIkey,respectively.
Whenmakingconfigurationrequests(type=config),youcanuseXPath,asyntaxforselectingnodesfrom
[Link]
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>

[Link].
[Link]
[Link]:<permissions></permissions>

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

Textnodescontainplaintextsuchas:<superuser>yes</superuser>

ExploretheAPIwiththeAPIbrowser,CLI,ordebugconsoletolearnhowtoconstructXMLrequests.

XPathNodeSelection
TherearevariouswaystoselecttheXPathforAPIrequests.
[Link],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
[Link].
[Link],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,[Link],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,[Link]
URLencodedwhenusedinHTTPrequests.
GetYourAPIKey
Step1

TogenerateanAPIkey,makeaURLrequesttothefirewallshostnameorIPaddressesusingthe
administrativecredentialsandtype=keygen:

curl -X GET '[Link]

AsuccessfulAPIcallreturnsstatus="success"alongwiththeAPIkeywithinthekeyelement:

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

(Optional)RevokeanAPIkey.
YoucanchoosetorevokeandthenchangeanAPIkeyassociatedwithanadministratoraccountbychanging
[Link]
credentialswouldnolongerbevalid.
GeneratinganAPIkeyusingthesameadministratoraccountcredentialsreturnsuniqueAPIkeyseverytime,
andallofthekeysarevalid.

[Link]
notchangedthefirewallmasterkeyfromthedefault,allfirewallswiththesame
username/passwordwillreturnthesameAPIkey.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 13

MakeYourFirstAPICall

GetStartedwiththePANOSXMLAPI

MakeYourFirstAPICall
GetYourAPIKeytomakeyourfirstcalltothePANOSXMLAPI.
MakeYourFirstAPICall
Step1

MakeacURLcalltogetsysteminformation,whichreturnstheIPaddress,hostname,andmodelofyour
[Link]:

curl
'[Link]
pikey'
Step2

Confirmthattheresponsetotheaboverequestlookssimilartothis:

<response status="success">
<result>
<system>
<hostname>firewall</hostname>
<ip-address>[Link]</ip-address>
<netmask>[Link]</netmask>
<default-gateway>[Link]</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>[Link]</mac-address>
<time>Wed Feb 10 [Link] 2016</time>
<uptime>1 days, [Link]</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 [Link]</app-release-date>
<av-version>2261-2700</av-version>
<av-release-date>2016/02/09 [Link]</av-release-date>
<threat-version>557-3138</threat-version>
<threat-release-date>2016/02/09 [Link]</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 [Link]</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 [Link]</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
[Link]
browserletsyounavigatethroughandviewthecorrespondingXPathandAPIURL.
UsetheAPIBrowsertoExploretheAPI
Step1

Launchthewebinterface.

1.

UseawebbrowsertonavigatetotheactualFQDNorIP
addressofyourfirewall:

[Link]
2.
Step2

LaunchtheAPIBrowser.

Loginwithyouradministratorcredentialswhenpromptedto
logintothewebinterface.

GototheAPIbrowserURLonyourfirewall:

[Link]

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 15

ExploretheAPI

GetStartedwiththePANOSXMLAPI

UsetheAPIBrowsertoExploretheAPI(Continued)
Step3

Drilldowntoarequest.

WhenyoufirstopentheAPIbrowser,theavailableRequestTypes
display.
1.

Selectoneoftherequesttypestodrilldowntothenextlevel
[Link],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
[Link],learnhowtoaccesstheCLIonyour
firewallorPanorama.

Step2

Enabledebugmode.

Enterthefollowingcommand:

debug cli on
Step3

RunaCLIcommand.

[Link]:
test url [Link]
<request cmd="op" cookie="7581536015878829"
uid="1206"><operations><test><url>[Link]
[Link]</url></test></operations></request>

18 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

GetStartedwiththePANOSXMLAPI

ExploretheAPI

UsetheCLItoFindXMLAPISyntaxandXPath(Continued)
Step4

Usetheresultingresponsetocreatean UsethecmdvalueandtheXMLelementswithintheoperations
APIcall.
tagtoformtheAPIcall:

[Link]
p://[Link]</url></test>&key=apikey
DependingontheCLIcommand,theXMLtagvaluesforcmd
[Link],hereisaCLIcommandforshowing
firewallinformation:run show system info
ThecorrespondingAPIcalllookslikethis:

[Link]
<info></info></system></show>&key=apikey

UsetheWebInterfacetoFindXMLAPISyntax
YoucanusethewebinterfacealongwiththeavailabledebugconsoletoexploretheXMLandXPath
necessaryforyourAPIcalls.
Firstlogintothewebinterfaceandthenopenaseparatewindowwhereyoucanviewthecorresponding
XMLandXPath.
UsetheWebInterfaceandDebugConsoletoFindXMLAPISyntaxandXPath
Step1

Launchthewebinterface.

LaunchawebbrowserandenterthefirewallsIPaddressor
[Link].

Step2

Launchthedebugconsole.

Inaseparatewebbrowserwindowortab,launchthedebug
console:

[Link]

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:

[Link]
<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
'[Link]
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
'[Link]
=2&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step3

Installthelatestcontentupdate.

Usethefollowingrequesttoinstallthenewlydownloadedcontent:

curl -X GET
'[Link]
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
'[Link]
=3&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step5

CheckforthelatestPANOSsoftware
update.

AfterinstallingthelatestContentReleaseupdate,checkforthe
latestavailablePANOSsoftwareupdates:

curl -X GET
'[Link]
tem><software><check></check>
</software></system></request>&key=apikey'
Intheresponse,thefirstentryisthelatestversionofPANOS:

<response status="success">
<result>
<sw-updates last-updated-at="2015/10/20
[Link]">
<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 [Link]</released-on>
...
Step6

DownloadthelatestPANOSsoftware
update.

1.

Inthiscase,thelatestversionis7.1.0c65,sodownloadthat
version:

curl -X GET
'[Link]
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.

Usethejobid intheresponsetoensurethatthe
systemupdatedownloadcompletessuccessfully:

curl -X GET
'[Link]
=318&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step7

InstallthelatestPANOSsoftware
update.

Toinstallthelatestsystemupdate,includetheversionina
softwareinstallrequest:

curl -X GET
'[Link]
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
'[Link]
=320&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step9

Rebootthefirewall.

Afterthesystemupdateinstallssuccessfully,trigger:

curl -X GET
'[Link]
tart><system></system></restart>
</request>&key=apikey'

24 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIUseCases

ShowandManageGlobalProtectUsers(API)

ShowandManageGlobalProtectUsers(API)
[Link],you
canviewandthendisconnectaGlobalProtectuserwhohasbeenloggedinfortoolong.
ShowandManageGlobalProtectUsers
Step1

ViewallGlobalProtectusers.

MakearequesttoviewallGlobalProtectusers:

curl -X GET
'[Link]
-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>[Link]</virtual-ip>
<public-ip>[Link]</public-ip>
<tunnel-type>SSL</tunnel-type>
<login-time>Jan.22 [Link]</login-time>
<login-time-utc>1421916636</login-time-utc>
<lifetime>2592000</lifetime>
</entry>
</result>
</response>
The<login-time-utc>fieldisthelogindate/timeinUNIXtime
format(numberofsecondselapsedsin[Link]Jan1970).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
'[Link]
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)
[Link]
[Link]
scriptinglanguageoryourchoice,youcanstorefirewallserialnumbersandusethemtoissueaqueryto
severalfirewalls.
Currently,youcanonlyusetype=opquerieswhenredirectingqueriesthroughPanorama.

QueryaFirewallfromPanorama
Step1

Getalistofconnectedfirewalls.

GetalistofconnectedfirewallsthatPanoramamanages:

[Link]
><
[Link]
><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>[Link]</ip-address>
<mac-addr />
<uptime>81 days, [Link]</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:

[Link]
<info></info></system></show>
TodirectlytargetafirewallthroughPanorama,appendthefirewall
serialnumbertotherequest:

[Link]
<info></info></system></show>&target=d
evice-serial-number
Asuccessfulresponseshouldlooklikethis:
<response status="success">
<result>
<system>
<hostname>firewall</hostname>
<ip-address>[Link]</ip-address>
<netmask>[Link]</netmask>
<default-gateway>[Link]</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>[Link]</mac-address>
<time>Tue Oct 27 [Link] 2015</time>
<uptime>12 days, [Link]</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 [Link]</app-release-date>
<av-version>2149-2586</av-version>
<av-release-date>2015/10/26 [Link]</av-release-date>
<threat-version>537-2965</threat-version>
<threat-release-date>2015/10/26 [Link]</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
[Link]</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)[Link],thisprocedureinvolves
multiple,manualstepsonindividualfirewalls.
[Link]
mustincorporateerrorcheckingandlogictoimplementthissequenceofsteps.

UpgradePANOSonMultipleFirewallsthroughPanorama
Step1

CheckforthelatestPANOSsoftware
updatethroughPanorama

[Link]
thefirewallserialnumberinyourrequest:

[Link]
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 [Link]">
<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 [Link]</released-on>
<release-notes><![CDATA[[Link]
[Link]?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
'[Link]
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.

Usethejobidintheresponsetoensurethatthesystem
updatedownloadcompletessuccessfully:

curl -X GET
'[Link]
=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
'[Link]
tem><software><install><version>7.1.0-c65</versi
on></install></software></system></request>&key=
apikey'
Step4

Checkonthesoftwareinstallation
status.

Usethejobidintheresponsetoensurethatthesystemupdate
installssuccessfully:

curl -X GET
'[Link]
=jobid&key=apikey'
Theresponseshouldincludethefollowing:

<response status="success">
Step5

Getalistofconnectedfirewalls.

GetalistofconnectedfirewallsthatPanoramamanages:

[Link]
><[Link]
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>[Link]</ip-address>
<mac-addr />
<uptime>81 days, [Link]</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:

[Link]
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
[Link]">
<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 [Link]</released-on>
<release-notes><![CDATA[[Link]
es/[Link]?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:

[Link]
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:

[Link]
d>3448</id></jobs></show>&target=serialnumber&ke
y=apikey
TheresponsecontainsajobstatusofFINwhenthedownloadis
complete:
<response status="success">
<result>
<job>
<tenq>2016/02/03 [Link]</tenq>
<id>3448</id>
<user />
<type>Downld</type>
<status>FIN</status>
<stoppable>no</stoppable>
<result>OK</result>
<tfin>[Link]</tfin>
<progress>[Link]</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:

[Link]
-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:

[Link]
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
'[Link]
=jobid&target=serialnumber&key=apikey
Theresponseshouldincludethefollowing:

<response status="success">
Step11 RebootthesuspendedHApeer.

Afterinstallingthelatestsystemupdate,rebootthesuspendedHA
peer:

[Link]
art><system></system></restart></request>&target
=serialnumber&key=apikey
Step12 Verifythattheupgradeissuccessful.

ShowsysteminformationonyourupgradedHApeertoensureit
hasthelatestsystemupdateandisoperational:

[Link]
<info></info></system></show>&target=serialnumbe
r&key=apikey
Step13 MakesthesuspendedHApeeractive.

AfteryouverifythatthesystemupdateonthesuspendedHApeer
issuccessful,makeitactiveagain:

[Link]
-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.
[Link]
andmultiplenodes.
ShowactionscanuserelativeXPath,whilegetactionsrequireabsoluteXPath.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 37

AsynchronousandSynchronousRequeststothePANOSXMLAPI

PANOSXMLAPIRequestTypes

AsynchronousandSynchronousRequeststothePANOS
XMLAPI
MostPANOSXMLAPIrequestsaresynchronous,meaningtheresponseimmediatelyprovidesthe
[Link],whenyouMakeYourFirstAPICallandrequestsysteminformation,theAPI
responseisimmediateandcontainsinformationsuchastheIPaddress,hostname,andmodelofyour
firewall.
However,therearesomeRequestTypesthatrequiremoretimetoprocessandareasynchronous,meaning
[Link]:

GetReports(API)

RetrieveLogs(API)

ExportTechnicalSupportData

SomerequeststoRunOperationalModeCommands(API),includingdownload,upgrade,andinstallation
requests

Withasynchronousrequests,[Link]
[Link],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

[Link],toretrievejustthe
securityrulebase:xpath=/config/devices/entry/vsys/entry/rulebase/security:

[Link]
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:

[Link] 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>[Link]</ip>
<mac>[Link]</mac>
<ttl>1743</ttl>
<interface>ethernet1/1</interface>
<port>ethernet1/1</port>
</entry>
<entry>
<status>c</status>
<ip>[Link]</ip>
<mac>[Link]</mac>
<ttl>386</ttl>
<interface>ethernet1/1</interface>
<port>ethernet1/1</port>
</entry>
<!-- truncated -->
</result>
</response>

GetCandidateConfiguration
[Link]
followingrequest,includingthexpathparametertospecifytheportionoftheconfigurationtoget.
[Link]

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 41

Configuration(API)

PANOSXMLAPIRequestTypes

ConfigurationNode

APIRequest

AddressobjectsinaVSYS.

[Link]
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
[Link]">
<entry name="testobject">
<ip-netmask>[Link]</ip-netmask>
</entry>
<entry name="test1">
<ip-netmask>[Link]</ip-netmask>
</entry>
...
</address>
</result>
</response>
PrerulespushedfromPanorama.

[Link]
g/panorama/vsys/entry[@name='vsys']/pre-rulebase/security

Detailedinformationon
[Link]
ApplicationsandThreatsfromthe /predefined/threats/vulnerability/entry[@name='30003']
firewall.
Fulllistofallapplications.

[Link]
/predefined/application

Detailsonthespecificapplication.

[Link]
/predefined/application/entry[@name='hotmail']

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

42 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

Configuration(API)

SetConfiguration
Step1

Createanewrulecalledrule1inthesecuritypolicy:

[Link]
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.

[Link]
Step3

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

[Link]
name='vsys1']/address-group/entry[@name='test']&element=<static><member>abc</member><
/static>

EditConfiguration
Usingaction=edit,youcanreplaceanexistingobjecthierarchyataspecifiedlocationintheconfiguration
[Link],includingthenodetobe
[Link](as
seenintheoutputofaction=show).
EditConfiguration
Step1

Replacetheapplication(s)currentlyusedinarulerule1withanewapplication:

[Link]
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.

[Link]
Step3

Optionallyreplaceallmembersinanodewithanewsetofmembersusingtheentrytaginboththexpathand
[Link],toreplacealltheaddressobjectsintheaddressgroupnamedtestwithtwo
newstaticmembersnamedabcandxyz,use:

[Link]
@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,[Link]
parametertospecifythelocationoftheobjecttobedeleted.
DeleteConfiguration
Deletearulenamedrule1inthesecuritypolicy:

[Link]
/rulebase/security/rules/entry[@name='rule1']
Deleteasinglememberobjectinagroup,usetheobjectnameinthexpathasmember[text()='name'].Forexample,
todeleteastaticaddressobjectnamedabcinanaddressgroupnamedtest,usethefollowingxpath:

[Link]
[@name='vsys1']/address-group/entry[@name='test']/static/member[text()='abc']

RenameConfiguration
Usingaction=rename,[Link]
[Link]
namefortheobject.
RenameConfiguration
Step1

Renameanaddressobjectcalledold_addresstonew_addressusingthefollowingAPIquery:

[Link]
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,[Link]
[Link],andthenewname
parametertoprovideanamefortheclonedobject.
CloneConfiguration
Step1

Cloneasecuritypolicycalledrule1intorule2usingthefollowingAPIquery:

[Link]
[@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 [Link],0009C100708,CONFIG,0,0,2014/03/19
[Link],[Link],,clone,admin,Web,Succeeded, config devices entry vsys
vsys1 rulebase security rules,384,0x8000000000000000

MoveConfiguration
Usingaction=move,[Link]
tospecifythelocationoftheobjecttobemoved,thewhereparametertospecifytypeofmove,anddst
parametertospecifythedestinationpath.

where=after&dst=xpath

where=before&dst=xpath

where=top

where=bottom

MoveConfiguration
Step1

Moveasecuritypolicycalledrule1afterrule2,usethefollowingAPIquery:

[Link]
@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,[Link]
xpathparametertospecifythelocationoftheobjecttooverride.
OverrideConfiguration
Step1

OverridetheSNMPTrapprofileconfigurationsettingsthatwerepushedtothefirewallusingatemplate:

[Link]
nmptrap&element=<entry name="snmp" src="tpl"><version src="tpl"><v2c src="tpl"><server
src="tpl"><entry name="test" src="tpl"><manager src="tpl">[Link]</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
[Link].
Thesyntaxformultimoveandmulticlonespecifiesthexpathforthedestinationwheretheaddresseswill
bemovedto,[Link]
flagfordisplayingtheerrorswhenthefirewallperformsareferentialintegritycheckonthemultimoveor
multicloneaction.
MultiMoveorMultiCloneConfiguration
Moveaddressesaddr1,addr2,todevicegroupnorcalfromdevicegroupsocal:

[Link]
[Link]']/devicegroup/entry[@name='norcal']/address&element=<selected-li
st><source
xpath="/config/devices/entry[@name='[Link]']/devicegroup/entry[@name='s
ocal']/address"><member>addr1</member><member>addr2</member></source></selected-list><
all-errors>no</all-errors>
Cloneaddressesaddr1,addr2,todevicegroupnorcalfromdevicegroupsocal:

[Link]
'[Link]']/devicegroup/entry[@name='norcal']/address&element=<selected-l
ist><source
xpath="/config/devices/entry[@name='[Link]']/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:

[Link]
xpath=/config/devices/entry[@name='[Link]']/vsys&key=apikey
Step2

ConfirmthattheXMLresponsefortherequestlookslikethefollowing:
<response status="success" code="19">
<completions>
<completion value="vsys1"
vxpath="/config/devices/entry[@name='[Link]']/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
[Link]
bodyelementinthecmdparameterwiththeXMLelementforthecorrespondingcommitoperation.
Commit
Step1

Useoneofthefollowingrequeststocommitaconfiguration:
Commit

[Link]
ForceCommit

[Link]
Partialcommit

[Link]
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:

[Link]

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 47

CommitConfiguration(API)

PANOSXMLAPIRequestTypes

Commit
Step4

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

Commitall
TocentrallymanagefirewallsfromPanorama,youcanusethecommitallAPIrequesttypetopushand
validatesharedpolicytothefirewallsusingdevicegroupsandconfigurationtothefirewallsusingtemplates
ortemplatestacks.
CommitType

APIRequest

Precommitpolicyvalidation.

[Link]
<commit-all><shared-policy><validate-only></validate-only>
</shared-policy></commit-all>

Devicegroupcommit.

[Link]
ll><shared-policy><device-group><entry%20name="device-grou
p-name"/></device-group></shared-policy></commit-all>

VSYScommit.

[Link]
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.

[Link]
ll><shared-policy><device-group><entry%20name="device-grou
p-name"><devices><entry%20name="serial_number"></devices><
entry/></device-group></shared-policy></commit-all>

[Link]
parameter,youmustreplacetheXMLelementforthecorrespondingcommit-alloperation.

48 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

RunOperationalModeCommands(API)

RunOperationalModeCommands(API)
UseanyoftheoperationalmodecommandsavailableonthecommandlineinterfaceusingthefollowingAPI
request:
[Link]
UsetheAPIBrowsertoexploreoperationalmodecommandsandacompletelistingofalltheoptions
availableforthexml-bodyandtheircorrespondingoperation.
OperationalCommand

APIRequest

Systemrestart.

[Link]
m></system></restart></request>

Systemsoftwareversion
installation.

[Link]
re><install><version>version_number</version></install></s
oftware></system></request>

Multivsysmode.

[Link]
ulti-vsys></multi-vsys></setting></system></set>

UserActivityReportscheduling.

[Link]
ser>username</user><title>titlename</title></uar-report></
schedule>

Fullconfigurationvalidation.

[Link]
/validate>

Partialconfigurationvalidation.

[Link]
ce-and-network>excluded</device-and-network></partial></va
lidate>

Configurationsaving.

[Link]
me</to></config></save>

Configurationloading.

[Link]
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:
[Link]
Whenyourequestareport,theAPIrespondsasynchronouslywithajobID,whichyoucanuseto
[Link]
XMLAPI.

DynamicReports

PredefinedReports

CustomReports

DynamicReports
YoucanviewanumberofdynamicreportsusingtheAPIsuchastop-applications-summary,
top-blocked-url-summary,[Link],youcanprovidethe
eitheraspecificperiodusingtheperiodoratimeframeusingstarttimeandendtimeoptions(usea+instead
ofaspacebetweenthedateandtimestamp).Usetopntodeterminethenumberofrows.
DynamicReportType

APIRequest

Fulldynamicreportlist.

[Link]

Last60seconds.

[Link]
tname=top-app-summary&period=last-60-seconds&topn=5

Last15minutes.

[Link]
tname=top-app-summary&period=last-15-minutes&topn=5

Lasthour.

[Link]
tname=top-app-summary&period=last-hour&topn=5

Last12hours.

[Link]
tname=top-app-summary&period=last-12-hrs&topn=5

Lastcalendarday.

[Link]
tname=top-app-summary&period=last-calendar-day&topn=5

Last7days

[Link]
tname=top-app-summary&period=last-7-days&topn=5

50 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

GetReports(API)

DynamicReportType

APIRequest

Last7calendardays

[Link]
tname=top-app-summary&period=last-hour&topn=5

Lastcalendarweek.

[Link]
tname=top-app-summary&period=last-calendar-week&topn=5

Last30days

[Link]
tname=top-app-summary&period=last-30-days&topn=5

PredefinedReports
[Link]
linkforpredefinedreports,suchastop-applications,top-attackers,andbandwidth-trendontheAPI
browser.
DynamicReportType

APIRequest

Fullpredefinedreportlist.

[Link]

Topapplications.

[Link]
defined&reportname=top-application-categories

Topattackers.

[Link]
defined&reportname=top-attackers

Topvictims.

[Link]
defined&reportname=top-victims

CustomReports
Forcustomreports,theselectioncriteria,suchastimeframe,groupby,andsortbyarepartofthereport
[Link]
nameandanyspacesinthereportnamemustbeURLencodedto%20.
ForcustomreportscreatedinaspecificVSYS,youcanretrievethemdirectlybyspecifyingthevsys
parameters.
GetaCustomDynamicReport
Step1

Retrievethereportdefinitionfromtheconfiguration:

[Link]
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:

[Link]
&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:

[Link]

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 "[Link]
WhenusingtheAPIqueryfromawebbrowser,youcanspecifyto=filenameasanoptionalparameterifyou
wouldliketoprovideadifferentnamewhensavingthefilelocally.

ExportPacketCaptures

ExportCertificatesandKeys

ExportTechnicalSupportData

ExportPacketCaptures
YoucanexportpacketcapturesfromthefirewallbyspecifyingthePCAPtypeusingthecategoryparameter:

ExportApplicationPCAPS

ExportThreat,Filter,andDataFilteringPCAPs

ExportCertificatesandKeys

ExportApplicationPCAPS
ApplicationPCAPsareorganizedbyadirectory/filenamestructurewherethedirectoryisadatein
[Link]
[Link].
ApplicationPCAPType

APIRequest

ApplicationPCAPdirectorylist.

[Link]
p

Listoffilesunderadirectoryusing [Link]
thefromparametertoindicate
p&from=yyyymmdd
date.

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 53

ExportFiles(API)

PANOSXMLAPIRequestTypes

ApplicationPCAPType

APIRequest

ApplicationPCAPfilebyname
usingthefromparameter.

[Link]
p&from=yyyymmdd/filename
Thefilewillberetrievedandsavedlocallyusingthenameyyyymmddfilename.

ApplicationPCAPfilesavedlocally [Link]
withacustomnameusingtheto p&from=yyyymmdd/filename&to=localfile
parameter.

ExportThreat,Filter,andDataFilteringPCAPs
ToexportthreatPCAPs,youneedtoprovidethePCAPIDfromthethreatlogandthesearchtime,whichis
[Link].
PCAPType

APIRequest

ThreatPCAPusingPCAPIDand
search

[Link]
p-id=id&search-time=yyyy/mm/dd hr:min:sec

ListoffilteredPCAPs

[Link]

SpecificfilteredPCAPfile

[Link]
om=filename

ListofdatafilteringPCAPfile
names

[Link]
ssword=password

SpecificdatafilteringPCAPfile

[Link]
ssword=password&from=filename&to=localfile

ExportCertificatesandKeys
ExportCertificatesandKeys
Step1

Toexportcertificatesandkeys,specifyqueryparameterscertificate-name,format,andpassphrase:

[Link]
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
[Link].

54 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ExportFiles(API)

ExportCertificatesandKeys
Step2

ConfirmthattheXMLresponseincludesthecertificate:

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

ExportTechnicalSupportData
Debuglogdatasizesarelarge,sotheAPIusesanasynchronousjobschedulingapproachtoretrievetechnical
[Link]
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=[Link];when
[Link]:
[Link]
action=[Link]
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=[Link]

action=finishStopanactivejob.

ExportTechnicalSupportData
Step1

Createajobtoretrievetechnicalsupportdata.
Usethefollowingrequest:

[Link]
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:

[Link]
AstatusvalueofFINindicatesthedataisreadytoberetrieved.
<response status="success">
<result>
<job>
<tenq>2012/06/14 [Link]</tenq>
<id>2</id>
<user />
<type>Exec</type>
<status>FIN</status>
<stoppable>no</stoppable>
<result>0K</result>
<tfin>[Link]</tfin>
<progress>[Link]</progress>
<details />
<warnings />
<resultfile>//tmp/[Link]</resultfile>
</job>
</result>
</response>

Step3

Retrievethetechsupportdata.

[Link]
WhenusingcURL,youcanspecifytheoutputfilenameasanoptiontocURL(-o).Afterasuccessfulretrieval
ofthejobdata,thejobisautomaticallydeletedbythesystem.
Step4

(Optional)Stoptheactivejobincaseoferror.
Ifthereisanerrororissuewiththeexportjob,[Link],stoptheactivejob:

[Link]
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 [Link]

[Link],thenrunarequestbatchuploadinstallop
command:

[Link]
-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
[Link]
object.

[Link]
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=[Link]
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:

[Link]
[Link].
nlogsparameterSpecifythenumberoflogstoretrieve.Thedefaultis20whentheparameterisnot
specified.Themaximumis5000.
[Link]
usefulwhenretrievinglogsinbatcheswhereyoucanskipthepreviouslyretrievedlogs.
dirparameterspecifywhetherlogsareshowninoldestfirst(forward)ornewestfirst(backward)order.

Thedefaultdirectionisbackward.
Sincelogdatasizescanbelarge,theAPIusesanasynchronousjobschedulingapproachtoretrievelogdata.
[Link]
[Link]
parameterare:

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

PaloAltoNetworks,Inc.

PANOSandPanorama7.1XMLAPIUsageGuide 59

RetrieveLogs(API)

PANOSXMLAPIRequestTypes

RetrieveTrafficLogs
Step1

Createajobtoretrievealltrafficlogsthatoccurredafteracertaintime:

[Link] geq '2012/06/22

[Link]')
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:

[Link]
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
[Link]</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 [Link]</time_generated>
<src>[Link]</src> <dst>[Link]</dst> <natsrc>[Link]</natsrc>
<natdst>[Link]</natdst> <rule>default allow</rule>

WhenthejobstatusisFIN(finished),theresponseautomaticallyincludesallthelogsintheXMLdata
[Link]<log>[Link]
retrieval,thesystemautomaticallydeletesthejob.
Step4

(Optional)[Link],runthefollowingquery:

[Link]
AsuccessfulcompletionreturnsajobID.

60 PANOSandPanorama7.1XMLAPIUsageGuide

PaloAltoNetworks,Inc.

PANOSXMLAPIRequestTypes

ApplyUserIDMappingandPopulateDynamicAddressGroups(API)

ApplyUserIDMappingandPopulateDynamicAddress
Groups(API)
Usethetype=[Link]
usingathirdpartyVPNsolutionorhaveuserswhoareconnectingtoa802.1xenabledwirelessnetwork,
theUserIDAPIenablesyoutomapuserstogroupssothatyoucancapturelogineventsandsendthemto
[Link],youcanusetheAPItocaptureloginevents
[Link],youcanusetheAPItoregister
theIPtousermappinginformation,fromtheinputfile,topopulatethemembersofaDynamicAddress
Grouponthefirewall.
curl -F key=apikey --form file=@filename "[Link]
or
curl --data-urlencode key=apikey -d type=user-id --data-urlencode "cmd=xml-document"
[Link]
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="[Link]" 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="[Link]" startport="xxxxx"
endport="xxxxx" blocksize="xxx">
</multiusersystem>
</payload>
<type>update</type>
<version>1.0</version>
</uid-message>

UserIDXMLmultiusersystem
loginevent

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

UserIDXMLmultiusersystem Uponreceiptofalogouteventmessagewithablockstartparameter,thefirewall
logout
[Link]
containsausernameandIPaddress,butnoblockstartparameter,thefirewall
[Link]
only,thefirewallremovesthemultiusersystemandallassociatedmappings.
<uid-message>
<payload>
<logout>
<entry user="domain\uid2" ip="[Link]"
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="[Link]">
<tag>
<member>CBB09C3D-3416-4734-BE90-0395B7598DE3</member>
</tag>
</entry>
</register>
<unregister>
<entry ip="[Link]"/>
<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=[Link]
PANOSversion,thisrequestprovidesadirectwaytoobtaintheserialnumberandmodelnumber.
GetVersionInfo(API)
Step1

MakearequesttothePANOSXMLAPIandwithtype=versionalongwithyourAPIkey:

[Link]
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
[Link]
names:
Error
Code

Name

Description

400

Badrequest

Arequiredparameterismissing,anillegalparametervalueisused.

403

Forbidden

Authenticationorauthorizationerrorsincludinginvalidkeyor
[Link].

Unknowncommand

Thespecificconfigoroperationalcommandisnotrecognized.

25

Internalerrors

Checkwithtechnicalsupportwhenseeingtheseerrors.

BadXpath

Thexpathspecifiedinoneormoreattributesofthecommandisinvalid.
ChecktheAPIbrowserforproperxpathvalues.

Objectnotpresent

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

Objectnotunique

Forcommandsthatoperateonasingleobject,thespecifiedobjectisnot
unique.

10

Referencecountnotzero

[Link]
example,addressobjectstillinuseinpolicy.

11

Internalerror

Checkwithtechnicalsupportwhenseeingtheseerrors.

12

Invalidobject

Xpathorelementvaluesprovidedarenotcomplete.

14

Operationnotpossible

[Link],moving
aruleuponepositionwhenitisalreadyatthetop.

15

Operationdenied

[Link],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.