Configuration API Introduction¶

Actions¶

The introduction described the different API Command Types. Within the config API type there are several actions.

Actions¶
Retrieve configuration
get	Retrieve candidate configuration
show	Retrieve running configuration
Modify 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:

get
show
set
edit
delete

Every action takes an xpath parameter which specifies where in the configuration that action should be taken. Actions like set and edit that modify configuration also require and element parameter that contains the XML configuration to apply at the xpath.

Parameters:

xpath: The location in the configuration to apply the ‘action’. Always required.
element: The XML configuration to apply at the specified xpath.

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:

/config/shared/address/entry[@name="my-server"]

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 name can be specified with square brackets [] and an @ symbol.

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.

Answer: /config/devices/entry[@name="localhost.localdomain"]/deviceconfig/system/hostname

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 action, xpath, and element necessary for you to use that command via the API.

Example:

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
Check Debug and Minimize Javascript
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 action, xpath, and 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.

Example:

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.