Configuration API Introduction¶
The introduction described the different API Command Types.
config API type there are several actions.
|get||Retrieve candidate configuration|
|show||Retrieve running configuration|
|set||Merge existing config with this config|
|edit||Replace existing config with this config|
|delete||Delete existing config|
|rename||Rename entry in existing config|
|clone||Clone existing config|
|move||Change configuration entry order|
|override||Override existing config from Panorama|
In this lab you will learn the following actions, but the concepts for these actions transfer to the others:
Every action takes an
xpath parameter which specifies where in
the configuration that action should be taken. Actions like
edit that modify configuration also require and
parameter that contains the XML configuration to apply at the
- xpath: The location in the configuration to apply the ‘action’. Always required.
- element: The XML configuration to apply at the specified xpath.
An XPath is a representation of a specific place in an XML document. The Firewall and Panorama store their configuration internally as XML documents, so to interact with pieces of the XML document (the configuration) you must specify what part of the XML you’re interested in. You do this with an XPath.
Example XPath 1: Let’s say you have an XML document with this structure:
<config> <shared> <address> <entry name="my-server" /> </address> </shared> </config>
If you want to modify the “my-server” address object, you would use this XPath:
There are two things to take from this example about XPath:
- Each XML element is separated by a slash
/as we drill down the XML structure.
- XML Attributes like
namecan be specified with square brackets
Example XPath 2: Here is a real Firewall configuration. If you wanted to get or change the hostname of this firewall, what XPath would you use? Consider your answer before checking the answer below.
Find the right XPath¶
There are a 3 techniques you can use to find the XPath you need for a part of the configuration.
Technique 1: API Browser¶
You can use the API Browser to figure out the XPath. As you
drill down in the browser, it will build the XPath for you.
The API Browser does not build an
element for you, but
you can submit the API call in the browser to see existing
XML in the configuration and derive the element from that.
Access the API Browser at https://<ip-of-firewall>/api
Technique 2: Debug CLI¶
For those who are familiar with the Firewall and Panorama Command Line, you can get the XPath and Element for any CLI command to reproduce that CLI command on the API. The CLI uses the API internally, so this technique simply prints the internal API calls that are made when you run a command.
Start by typing
debug cli on on the command line.
Now any command you type will display the
element necessary for you to use that command via the API.
Technique 3: Debug GUI¶
For those who are familiar with the Firewall and Panorama GUI, you can get the XPath and Element for any action taken in the GUI to reproduce that action on the API. The GUI uses the API internally, so this technique simply prints the internal API calls that are made when you take action in the GUI.
- Start by pointing your browser to https://<ip-of-firewall>/debug
- In a separate browser tab, navigate in the firewall GUI to where you want to make a change and capture the API call
- In the debug tab, click Clear debug
- In the GUI tab, take the action you want to capture
- In the debug tab, click Refresh
In the debug window you will see the
element necessary for you to reproduce that action on the API.
There is a lot of output and the fields you need are not labeled,
so look for things that appear familiar. You known the actions that
are possible and what an xpath looks like. The element is usually
a block of XML.
Use these 3 techniques as you work on the lab modules. Which technique you use depends on the situation and your own familiarity with the firewall. If you are more familiar with the CLI, you probably know the command for which you want to make an API call, and you can use debug cli on (Technique #2). If you’re more familiar with the firewall’s GUI, then you’ll use Technique #3. If you only need to determine a simple XPath, or want to see a range of available options, then the API Browser (Technique #1) might be appropriate. Try each one during the lab to understand when and how to use each.
Continue to Retrieve Configuration - show and get.