XML Api

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:documentation@paloaltonetworks.com.
PaloAltoNetworks,Inc.
www.paloaltonetworks.com
2016PaloAltoNetworks,Inc.PaloAltoNetworksisaregisteredtrademarkofPaloAltoNetworks.Alistofourtrademarkscanbefound
athttps://www.paloaltonetworks.com/company/trademarks.html.Allothermarksmentionedhereinmaybetrademarksoftheir
respectivecompanies.
RevisionDate:September21,2016
2 PANOSandPanorama7.1XMLAPIUsageGuide
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
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
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
AboutthePANOSXMLAPI
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.
AboutthePANOSXMLAPI
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.
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
AboutthePANOSXMLAPI
ThispathselectsthefollowingXMLnodethatincludesalistofusers:
<users>
<entry name="admin">
<permissions>
<role-based>
</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:
AboutthePANOSXMLAPI
GetStartedwiththePANOSXMLAPI
TousethePANOSXMLAPI,firstuseyouradmincredentialstogetanAPIkeythroughthekeygencommand
type.YoucanthenusetheAPIkeytotestasimplecall.
ThisguidetestsAPIrequestsusingcURLcommands.However,youcanuseotherAPItesting
toolssuchasPostmanandRESTClienttotestAPIrequests.
EnableAPIAccess
GetYourAPIKey
MakeYourFirstAPICall
ExploretheAPI
EnableAPIAccess
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.
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.
GetYourAPIKeytomakeyourfirstcalltothePANOSXMLAPI.
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:
<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>
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
ExploretheAPI
UsetheAPIBrowsertoExploretheAPI(Continued)
Step3
Drilldowntoarequest.
WhenyoufirstopentheAPIbrowser,theavailableRequestTypes
display.
1.
Selectoneoftherequesttypestodrilldowntothenextlevel
oftheXPath.LetsstartwithConfigurationCommands,which
equatestotype=report:
2.
Drilldownfurtheruntilyouselectarequestthatyouwantto
test.
ExploretheAPI
Step4
Testarequest.
3.
SelecttheURLtothentestthatrequestinthebrowser.
ThebrowsershowstheresultingXMLresponseinthebrowser:
ExploretheAPI
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>
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
ExploretheAPI
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:
<info></info></system></show>&key=apikey
PANOSXMLAPIUseCases
ThefollowingusecaseshighlighttheuseofthePANOSXMLAPI,eithertoreducerepetitivestepsorto
automatetasksnormallyyouperformthroughthewebinterfaceorCLI.
UpgradeaFirewalltotheLatestPANOSVersion(API)
ShowandManageGlobalProtectUsers(API)
QueryaFirewallfromPanorama(API)
UpgradePANOSonMultipleHAFirewallsthroughPanorama(API)
PANOSXMLAPIUseCases
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:
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.
<result>
<msg>
<line>Content install job enqueued with jobid
3</line>
</msg>
<job>3</job>
</result>
</response>
PANOSXMLAPIUseCases
UpgradeaFirewalltotheLatestPANOSVersion(Continued)
Step4
Checkonthecontentinstallationstatus. Usethejobidtoensurethatthecontentinstallationcompletes
successfully:
curl -X GET
=3&key=apikey'
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:
<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
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.
Usethejobid intheresponsetoensurethatthe
systemupdatedownloadcompletessuccessfully:
curl -X GET
=318&key=apikey'
Step7
InstallthelatestPANOSsoftware
update.
Toinstallthelatestsystemupdate,includetheversionina
softwareinstallrequest:
curl -X GET
tem><software><install><version>7.1.0-c65</versi
on></install></software></system></request>&key=
apikey'
PANOSXMLAPIUseCases
UpgradeaFirewalltotheLatestPANOSVersion(Continued)
Step8
Checkonthesoftwareinstallation
status.
Usethejobidintheresponsetoensurethatthesystemupdate
installssuccessfully:
curl -X GET
=320&key=apikey'
Step9
Rebootthefirewall.
Afterthesystemupdateinstallssuccessfully,trigger:
curl -X GET
'https://firewall/api/?type=op&cmd=<request><res
tart><system></system></restart>
</request>&key=apikey'
PANOSXMLAPIUseCases
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:
<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).
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:
<result>
<gateway>Home-N</gateway>
<domain>(null)</domain>
<user>dward</user>
<computer>Dans iPhone</computer>
</response>
</result>
</response>
PANOSXMLAPIUseCases
ThetargetparameteronPanoramaallowsyoutoredirectqueriestoamanagedfirewall.Redirectingqueries
tofirewallshelpstoreducetimeandthenumberofstepsrequiredtoissuerepetitivecommands.Usingthe
scriptinglanguageoryourchoice,youcanstorefirewallserialnumbersandusethemtoissueaqueryto
severalfirewalls.
Currently,youcanonlyusetype=opquerieswhenredirectingqueriesthroughPanorama.
QueryaFirewallfromPanorama
Step1
Getalistofconnectedfirewalls.
GetalistofconnectedfirewallsthatPanoramamanages:
https://panorama/api/?type=op&cmd=<show><devices
><
><connected></connected></devices></show>
Theresponseincludestheserialnumber(serial)ofeachfirewall.
<result>
<devices>
name="007200002517">
<connected>yes</connected>
<unsupported-version>no</unsupported-version>
<deactivated>no</deactivated>
<hostname>PM-6-1-VM</hostname>
<mac-addr />
<family>vm</family>
<model>PA-VM</model>
<sw-version>6.1.3</sw-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>
<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>

</devices>
</result>
</response>
Theresponsecontainsa<serial>XMLelementforeachfirewall.
Step2
Collectfirewallserialnumbers.
Inyourscriptorcode,storethefirewallserialnumbersreturnedin
theresponsetothepreviousrequest.
PANOSXMLAPIUseCases
QueryaFirewallfromPanorama(Continued)
Step3
QueryafirewallfromPanorama.
Anormalrequesttoshowsysteminformationonafirewalllooks
likethis:
<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:
<result>
<system>
<hostname>firewall</hostname>
<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>
<devicename>pm-firewall</devicename>
<family>3000</family>
<model>PA-3020</model>
<sw-version>7.1.0-c54</sw-version>
<app-release-date>2015/10/26 18:10:48</app-release-date>
<av-release-date>2015/10/26 15:31:55</av-release-date>
<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>
<wildfire-release-date>unknown</wildfire-release-date>
<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>
<platform-family>3000</platform-family>
<vpn-disable-mode>off</vpn-disable-mode>
<multi-vsys>on</multi-vsys>
</system>
</result>
</response>
Repeatthisrequestforeachconnectedfirewall.
PANOSXMLAPIUseCases
UpgradePANOSonMultipleHAFirewallsthrough
Panorama(API)
ThisusecasehighlightstheabilityofthePANOSXMLAPItoautomateamorecomplexprocedure,namely
upgradingfirewallssetupasactivepassivehighavailability(HA)pair.Normally,thisprocedureinvolves
multiple,manualstepsonindividualfirewalls.
Thisisahighleveloverviewofthestepsyoumusttakeinthisprocedure.Youscriptorapplication
mustincorporateerrorcheckingandlogictoimplementthissequenceofsteps.
UpgradePANOSonMultipleFirewallsthroughPanorama
Step1
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:
<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>
<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>

</versions>
</sw-updates>
</result>
</response>
Step2
update.
1.
Inthiscase,thelatestversionis7.1.0c65,sodownloadthat
version:
curl -X GET
tem><software><download><version>7.1.0
-c65</version></download></software></system></r
equest>&key=apikey'
2.
Usethejobidintheresponsetoensurethatthesystem
updatedownloadcompletessuccessfully:
curl -X GET
=318&key=apikey'
PANOSXMLAPIUseCases
UpgradePANOSonMultipleFirewallsthroughPanorama(Continued)
Step3
InstallthelatestPANOSsoftware
update.
Toinstallthelatestsystemupdate,includetheversionina
softwareinstallrequest:
curl -X GET
tem><software><install><version>7.1.0-c65</versi
on></install></software></system></request>&key=
apikey'
Step4
Checkonthesoftwareinstallation
status.
curl -X GET
=jobid&key=apikey'
Step5
Getalistofconnectedfirewalls.
GetalistofconnectedfirewallsthatPanoramamanages:
><https://panorama/api/?type=op&cmd=<show><devic
es><connected></connected></devices></show>
Theresponseincludestheserialnumber(serial)ofeachfirewall.
<result>
<devices>
name="007200002517">
<connected>yes</connected>
<unsupported-version>no</unsupported-version>
<deactivated>no</deactivated>
<hostname>PM-6-1-VM</hostname>
<mac-addr />
<family>vm</family>
<model>PA-VM</model>
<vpnclient-package-version />
<vpn-disable-mode>no</vpn-disable-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>

</devices>
</result>
</response>
Theresponsecontainsa<serial>XMLelementthatcontains
eachfirewallserialnumber.
PANOSXMLAPIUseCases
Step6
update.
ChecktoseeifnewsoftwareisavailableonyourHApair:
em><software><check></check></software></system>
</request>&target=serialnumber&key=apikey
Theresponsecontainsanarrayofresultssortedtoshowthelatest
versionfirst:
<result>
<sw-updates last-updated-at="2016/02/03
08:29:09">
<msg />
<versions>
<filename>PanOS_vm-7.1</filename>
<size>540</size>
<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>

</versions>
</sw-updates>
</result>
</response>
PANOSXMLAPIUseCases
Step7
update.
Afterdeterminingthelatestsystemupdate,downloadittoboth
firewallsintheHApair:
em><software><download><version>7.1</version></d
ownload></software></system></request>&target=se
rialnumber&key=apikey
TheresponsecontainsajobID:
<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:
<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:
<result>Successfully changed HA state to
suspended</result>
</response>
PANOSXMLAPIUseCases
Step9
Installthelatestsoftwareupdateonthe AftersuspendingtheactiveHAfirewall,installthesystemupdate
suspendedHApair.
onit:
em><software><install><version>version</version>
</install></software></system></request>&target=
serialnumber&key=apikey
Theresponseshowsthesystemupdateisqueued:

<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.
curl -X GET
'https://panorama/api/?type=op&action=get&job-id
=jobid&target=serialnumber&key=apikey
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:
<result>Successfully changed HA state to
functional</result>
</response>
PANOSXMLAPIUseCases
Step14 Installthesystemupdateonthepassive OncethesuspendedHAfirewallisactive,youcanthenrepeat
HApeer.
steps58onthenowpassiveHApeer.
PANOSXMLAPIRequestTypes
ThisfollowingtopicsprovidecommonrequestexamplesthatyoucanusetobetterunderstandthePANOS
XMLAPI.
PANOSXMLAPIRequestTypesandActions
AsynchronousandSynchronousRequeststothePANOSXMLAPI
Configuration(API)
CommitConfiguration(API)
RunOperationalModeCommands(API)
GetReports(API)
ExportFiles(API)
ImportFiles(API)
RetrieveLogs(API)
ApplyUserIDMappingandPopulateDynamicAddressGroups(API)
GetVersionInfo(API)
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
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.
AsynchronousandSynchronousRequeststothePANOSXMLAPI
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.
Configuration(API)
Configuration(API)
TherequestsexamplesinthesetopicsillustratehowyoucanusethePANOSXMLAPItoconfigureyour
firewall.
GetActiveConfiguration
GetCandidateConfiguration
SetConfiguration
EditConfiguration
DeleteConfiguration
RenameConfiguration
CloneConfiguration
MoveConfiguration
OverrideConfiguration
MultiMoveorMultiCloneConfiguration
ViewConfigurationNodeValuesforXPath
Configuration(API)
Usingaction=showwithnoadditionalparametersreturnstheentireactiveconfiguration.
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):
<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>
</source-user>
<category>
</category>
<application>
<member>dns</member>
</application>
<service>
<member>application-default</member>
</service>
<hip-profiles>
</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>
Configuration(API)
GetARPInformation
Step2
ConfirmthattheXMLresponseforthequerylookslikethefollowing(truncated):
<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>

</result>
</response>
GetCandidateConfiguration
Getthecandidateconfigurationfromafirewallbyspecifyingtheportionoftheconfigurationtoget.Usethe
followingrequest,includingthexpathparametertospecifytheportionoftheconfigurationtoget.
https://firewall/api/?type=config&action=get&xpath=path-to-config-node
Configuration(API)
ConfigurationNode
APIRequest
AddressobjectsinaVSYS.
https://firewall//api/?type=config&action=get&xpath=/confi
g/devices/entry/vsys/entry[@name='vsys1']/address
Theresponselookssimilartothefollowing:

<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.
/predefined/application
Detailsonthespecificapplication.
/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).
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>
Configuration(API)
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
Configuration(API)
CloneConfiguration
Step2
<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
Usingaction=override,youcanoverrideasettingthatwaspushedtoafirewallfromatemplate.Usethe
xpathparametertospecifythelocationoftheobjecttooverride.
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
Configuration(API)
Theaction=multi-moveandaction=multi-cloneactionsallowyoutomoveandcloneaddressesacross
devicegroupsandvirtualsystems.Templatesdonotsupportthemultimoveandmulticlonecapability.
Thesyntaxformultimoveandmulticlonespecifiesthexpathforthedestinationwheretheaddresseswill
bemovedto,thexpathforthesourceandthelistofobjectswithinthespecifiedsource.Italsoincludesa
flagfordisplayingtheerrorswhenthefirewallperformsareferentialintegritycheckonthemultimoveor
multicloneaction.
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>
Theaction=completeactionallowsyoutoprovideanXPathandseethepossiblevaluesthatareavailable
undertheXPathnode.
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
<completions>
<completion value="vsys1"
vxpath="/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']"
current="yes" help-string="vsys1"/>
</completions>
</response>
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
<msg>There are no changes to commit.</msg>
</response>
Pendingchanges
<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>
Commit
Step4
<result>
<job>
<tenq>2011/10/20 20:41:44</tenq>
<id>4</id>
<type>Commit</type>
<result>OK</result>
<tfin>20:42:22</tfin>
<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.
p-name"/><devices><entry%20name="serial_number"><vsys><mem
ber>vsys-name</member></vsys></entry></devices></device-gr
oup></shared-policy></commit-all>
Specificfirewallcommit.
p-name"><devices><entry%20name="serial_number"></devices><
entry/></device-group></shared-policy></commit-all>
UsetheAPIBrowsertofindotheroptionsavailableforgranularcommitoperationsonPanorama.Inthecmd
parameter,youmustreplacetheXMLelementforthecorrespondingcommit-alloperation.
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.
GetReports(API)
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.
tname=top-app-summary&period=last-15-minutes&topn=5
Lasthour.
tname=top-app-summary&period=last-hour&topn=5
Last12hours.
tname=top-app-summary&period=last-12-hrs&topn=5
Lastcalendarday.
tname=top-app-summary&period=last-calendar-day&topn=5
Last7days
tname=top-app-summary&period=last-7-days&topn=5
GetReports(API)
DynamicReportType
APIRequest
Last7calendardays
tname=top-app-summary&period=last-hour&topn=5
Lastcalendarweek.
tname=top-app-summary&period=last-calendar-week&topn=5
Last30days
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.
defined&reportname=top-attackers
Topvictims.
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']
GetReports(API)
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:
<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
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
ExportPacketCaptures
YoucanexportpacketcapturesfromthefirewallbyspecifyingthePCAPtypeusingthecategoryparameter:
ExportApplicationPCAPS
ExportThreat,Filter,andDataFilteringPCAPs
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.
ExportFiles(API)
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
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.
ExportFiles(API)
Step2
ConfirmthattheXMLresponseincludesthecertificate:
-----BEGIN CERTIFICATE----MIIDXTCCAkWgAwIBAgIJAJC1HiIAZAiIMA0GCSqGSIb3Df
BAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEwHwYDVx
aWRnaXRzIFB0eSBMdGQwHhcNMTExMjMxMDg1OTQ0WhcNMT

-----END CERTIFICATE-----
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.
Step1
Createajobtoretrievetechnicalsupportdata.
Usethefollowingrequest:
https://firewall/api/?type=export&category=tech-support
TheresponseincludesajobID:
<result>
<msg>
<line>Exec job enqueued with jobid 2</line>
</msg>
<job>2</job>
</result>
</response>
ExportFiles(API)
ExportTechnicalSupportData(Continued)
Step2
Checkonthestatusofthejob.
UsethejobIDreturnedinthepreviousresponseasthejobidparameter:
https://firewall/api/?type=export&category=tech-support&action=get&job-id=id
AstatusvalueofFINindicatesthedataisreadytoberetrieved.
<result>
<job>
<tenq>2012/06/14 10:11:09</tenq>
<id>2</id>
<user />
<type>Exec</type>
<result>0K</result>
<tfin>10:12:39</tfin>
<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>
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>
ImportFiles(API)
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>
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.
RetrieveLogs(API)
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:
<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.
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>
<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"/>
</members>
</entry>
<entry name="group2">
<members>
</members>
</entry>
</groups>
</payload>
</uid-message></uid-message>
YoucanincludeaHIPreportbyincludinga<hip-report></hip-report>XML
containerwithinan<entry>parentelement.
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>
</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>
</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>
</uid-message>
APIRequest
DynamicAddressGroupIPaddress <uid-message>
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>
GetVersionInfo(API)
GetVersionInfo(API)
Usethetype=versionrequesttypeshowthePANOSversionforafirewallorPanorama.Inadditiontothe
PANOSversion,thisrequestprovidesadirectwaytoobtaintheserialnumberandmodelnumber.
GetVersionInfo(API)
Step1
MakearequesttothePANOSXMLAPIandwithtype=versionalongwithyourAPIkey:
https://firewall/api/?type=version&key=apikey
Step2
TheXMLresponsecontainsthesoftwareversion,model,serialnumber,andwhethermultivsysmodeison:
<result>
<multi-vsys>off</multi-vsys>
<model>pa-vm</model>
</result>
</response>
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
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
22
Sessiontimedout
Thesessionforthisquerytimedout.
PANOSXMLAPIErrorCodes

XML Api

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

XML Api

Enviado por

Direitos autorais:

Formatos disponíveis

PANOS and

SelecttheXML API tab.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Threat Activity>Compromised Hosts.

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

Você também pode gostar