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:

  1. Each XML element is separated by a slash / as we drill down the XML structure.
  2. 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.

_images/xpath-example.png

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:

_images/debug-cli.png

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.

  1. Start by pointing your browser to https://<ip-of-firewall>/debug
  2. Check Debug and Minimize Javascript
  3. In a separate browser tab, navigate in the firewall GUI to where you want to make a change and capture the API call
  4. In the debug tab, click Clear debug
  5. In the GUI tab, take the action you want to capture
  6. 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:

_images/debug-gui.png

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.