Integrating Zabbix with Palo Alto Networks Subinterfaces

with the PAN-OS XML API

Tech Note
PAN-OS 5.0

Revision A ©2013, Palo Alto Networks, Inc. www.paloaltonetworks.com

Contents
Overview ................................................................................................................................................................................ 3  
Summary ............................................................................................................................................................................ 3  
Network Architecture ......................................................................................................................................................... 4  
Hardware and Software Versions Used ............................................................................................................................... 5  
Working with PAN-OS API ..................................................................................................................................................... 5  
Generating the API key ....................................................................................................................................................... 5  
API Call to Retrieve Subinterface Information .................................................................................................................... 5  
Building the Shell Scripts ...................................................................................................................................................... 8  
Zabbix configuration .............................................................................................................................................................. 9  
Creating the Host Items ...................................................................................................................................................... 9  
Adding the Graph ............................................................................................................................................................. 13  
Verifying the Configuration .................................................................................................................................................. 15  
Conclusions ......................................................................................................................................................................... 16  
Revision History ................................................................................................................................................................... 16  

 
©2013, Palo Alto Networks, Inc. [2]
Overview
In addition to the PAN-OS web interface and the Command Line Interface (CLI), PAN-OS provides a RESTful XML API to
manage both firewall and Panorama devices. The API allows access to several types of data on the device, so they can be
easily integrated with and used in other systems. The main purpose of this document is to show security and network
administrators how to use Zabbix to monitor the bandwidth activity of Palo Alto Networks subinterfaces, through the
utilization of the PAN-OS RESTful XML API.

The content of the document is mostly technical and therefore the intended audience is system engineers. The reader should
already have basic knowledge on how to configure a Palo Alto Networks next-generation firewall; therefore all the steps
required to set up a basic configuration are not covered here. Similarly, we will not describe the steps required to install or
set up Zabbix. More specifically, we will cover the following areas:

• Working with PAN-OS API

• Building the shell scripts that will interact with the API
• Configuring Zabbix to get subinterface bandwidth information via scripting
• Verifying the configurations

The content included in this document is not intended to substitute any official documentation from Palo Alto Networks.
The official documentation can be found in the public website and also in the corporate Intranet for employees.

Summary
As of PAN-OS 5.0.x, retrieving subinterface bandwidth information via SNMP is not supported. Nevertheless, PAN-OS
offers a powerful XML API that allows the retrieval of this information via operational commands (PAN-OS 4.1 and later).
In this tech note, we will only cover the required steps to access the API and get the bandwidth information.
For those readers interested in gaining deeper knowledge on the API and all of its capabilities, refer to
https://live.paloaltonetworks.com/docs/DOC-3576

Zabbix is a popular open source network monitoring tool that supports polling information from the monitored devices via
different methods, including scripting, which makes it perfect for integrating it with PAN-OS XML API. More precisely, and
according to the definition provided in their website: “Zabbix is the ultimate open source availability and performance
monitoring solution. Zabbix offers advanced monitoring, alerting, and visualization features today which are missing in
other monitoring systems, even some of the best commercial ones.” Again, in this document we will cover only some of the
basic steps required for making this integration work. If you are interested into getting more information about Zabbix,
refer to www.zabbix.com

 
©2013, Palo Alto Networks, Inc. [3]
Network Architecture
Screenshot 1 that follows shows the logical network diagram that we will use in our lab:

Screenshot 1.- Lab logical diagram

Explanation of each element:

ü The firewall has 3 different segments configured (LAN, DMZ, and Internet)
ü LAN (ethernet 1/3) and Internet (ethernet 1/1) segments are not tagged
ü The DMZ (ethernet 1/2) has a tagged subinterface (ethernet 1/2.2), configured with vlan tag 2

The following screenshot shows this network configuration as displayed in the firewall’s Network tab:

Screenshot 2.- Firewall’s network configuration

 
©2013, Palo Alto Networks, Inc. [4]
Hardware and Software Versions Used
ü Zabbix: Zabbix 2.0.6 VMware appliance over OpenSuSE, that can be downloaded from:
http://sourceforge.net/projects/zabbix/files/ZABBIX%20Latest%20Stable/2.0.6/Zabbix_2.0_x86.i686-
2.0.6.vmx.tar.gz/download
ü Iperf: Iperf version 2.0.5 for making some basic bandwidth tests
ü Palo Alto Networks: PA-200 firewall running PAN-OS version 5.0.6

Working with PAN-OS API

Generating the API key
In order to externally access the API we need to generate a key using admin credentials, which will grant access for all the
API calls that the script will require. For this example, we need to execute the following call in a web browser:
https://192.168.1.10/api/?type=keygen&user=<admin-user>&password=<admin-password>

After running this, the system will return an XML file containing the key that we need to copy for the scripts. Please note
that in PAN-OS 4.1, the key generated was always the same. In PAN-OS 5.0 and later, the key generated is different each
time you peform the previous XML request, but all the keys obtained are valid forever. The following screenshot shows an
example output for this API call (the key is not showed in its complete length):

Screenshot 3.- Returned XML file with the key

API Call to Retrieve Subinterface Information

After we have the key, we need to determine what API call we need to make in order to get the ethernet1/2.2 subinterface
bandwidth statistics. Although there are several possibilities, using the built-in API browser in the PAN-OS web interface is
the simplest and most powerful way to do it. In order to access the API, use your browser to navigate to: https://<firewall-
management-ip>/api. The following screenshot shows the initial page retrieved when navigating the API with a web browser:

 
©2013, Palo Alto Networks, Inc. [5]
 Screenshot 4.- Root tree of the API from the GUI browser

Starting with PAN-OS 4.1 and later the XML API supports operational commands, so we need to execute the CLI command
show interface ethernet1/2.2 that returns, among other data, the in and out bytes that the interface handles as an
increasing counter in bytes. Let’s look first at the output of this command using the CLI:

admin@PA-200> show interface ethernet1/2.2

--------------------------------------------------------------------------------
Name: ethernet1/2.2, ID: 257, 802.1q tag: 2
Operation mode: layer3
Virtual router GW-LAB
Interface MTU 1500
Interface IP address: 192.168.2.200/24
Interface management profile: Portal-Cautivo_y_SSL-VPN
ping: yes telnet: no ssh: yes http: no https: yes
snmp: no response-pages: yes userid-service: no
Service configured:
Zone: DMZ, virtual system: vsys1
Adjust TCP MSS: no
--------------------------------------------------------------------------------

Logical interface counters read from CPU:

--------------------------------------------------------------------------------
bytes received 171982525
bytes transmitted 1436512515
packets received 225551
packets transmitted 968156
receive errors 0
packets dropped 0
packets dropped by flow state check 0
forwarding errors 0

 
©2013, Palo Alto Networks, Inc. [6]
no route 2
arp not found 29
neighbor not found 0
neighbor info pending 0
mac not found 0
packets routed to different zone 466
land attacks 0
ping-of-death attacks 0
teardrop attacks 0
ip spoof attacks 0
mac spoof attacks 0
ICMP fragment 0
layer2 encapsulated packets 0
layer2 decapsulated packets 0
--------------------------------------------------------------------------------

Let’s see now how it works via the API browser and the response that we get after we press the Submit button in the
following form:

Screenshot 5.- API call via the GUI API browser

 
©2013, Palo Alto Networks, Inc. [7]
 Screenshot 6.- Response to the previous API call

The important fields from this response, which store the required information about inbound and outbound bytes for the
interface, are ibytes and obytes:

Inbound bytes: ibytes

Outbound bytes: obytes

Building the Shell Scripts

We have created two shell scripts that will read the ibytes and obytes fields shown previously. The scripts are very simple;
they receive as a parameter the interface name and will then make the API call via curl. The output is stored in a temporary
file at which time we will read the ibytes and obytes content using the xpath library from Perl.

Curl is installed by default in the Zabbix 2.0.6 VM appliance, but xpath is not. Nevertheless, you can easily install it by
executing the following command in the OpenSuSE shell:
 
zypper  install  perl-­‐XML-­‐XPath  

 
©2013, Palo Alto Networks, Inc. [8]
Following you will find the code for both scripts:

shell script for retrieving ibytes:

#!/bin/sh
curl –k "https://192.168.1.10/api/?type=op&cmd=<show><interface>$1</interface></show>&key=<your-
API-key>" -s -o /tmp/curl_in_tmp.xml
xpath /tmp/curl_in_tmp.xml "//ibytes/text()" 2>/dev/null

shell script for retrieving obytes:

#!/bin/sh
curl –k "https://192.168.1.10/api/?type=op&cmd=<show><interface>$1</interface></show>&key=<your-
API-key>" -s -o /tmp/curl_out_tmp.xml
xpath /tmp/curl_out_tmp.xml "//obytes/text()" 2>/dev/null

We need to store both scripts in the Zabbix server in the externalscripts path. This path may differ for each installation,
depending on the compilation options. In our OpenSuSE VM appliance, the path where the scripts will be stored are in the
following location: /usr/share/zabbix/externalscripts. The names that we have given the scripts in our example
are:
bytes-in-sub
bytes-out-sub

The scripts will be run with the zabbix OS user. Therefore, you need to assign execution rights to those scripts (chmod +x)
and optionally make the zabbix OS user the owner. Also ensure that the zabbix OS user has the appropriate rights to write
into the temporary files, if a different user has created them in advance.
Before moving forward, you should test that both scripts can connect to the firewall’s API and successfully retrieve the ibytes
and obytes values. You can do that by simply running the scripts in the CLI of the Zabbix server: ./<script-name>

Zabbix configuration
All the Zabbix configuration will be done using the GUI, usually placed in http://<zabbix-server-IP>/zabbix. We will split
Zabbix’s configuration into two different main steps:
ü Creating the Host Items
ü Adding the Graph

Creating the Host Items

The first step to adding the host items is to add two new items to the host where we want to perform the monitoring, one for
the inbound bytes and the other one for the outbound bytes. In order to do this, you need to navigate to Configuration >
Host > host-name > Items as show the following screenshots:

 
©2013, Palo Alto Networks, Inc. [9]
 Screenshot 7.- Host items configuration screens

Click the Create Item button to create the two new items. In the screen that will appear, provide the following information:
Name: Name of the item. In our example:
Incoming traffic on interface ethernet1/2.2
Outgoing traffic on interface ethernet1/2.2
Type: External check
Key: This is where we call our script; parameters are passed within brackets []. In our example:
bytes_in_sub["ethernet1/2.2"]
bytes_out_sub["ethernet1/2.2"]
Type of information: Numeric (unsigned)
Data type: Decimal
Units: bps (Zabbix will automatically understand this as bits per second)
Use custom multiplier: 8 (this is important to make the conversion from bytes that we are reading into bits that we
want to plot in our graphs)
Update interval (in sec): 30

In this example, the remaining fields will use the default values. Click the Save button to commit the changes.

 
©2013, Palo Alto Networks, Inc. [10]
The following two screenshots show how both items have been configured in our lab:

Screenshot 8.- Host item definition for bytes-in

 
©2013, Palo Alto Networks, Inc. [11]
 Screenshot 9.- Host item definition for bytes-out

 
©2013, Palo Alto Networks, Inc. [12]
Adding the Graph
This section will describe the required steps to add a new graph into our existing Zabbix’ Graph structure. Navigate to
Configuration > Hosts > host-name > Graphs as shown in the following screenshots:

Screenshot 10.- Host graphs configuration screens

Click the Create Graph button as shown in the previous screen and then fill in the following information:
Name: Name that your graph will have. In our example:
Traffic on interface ethernet1/2.2
Items: Here you will add the two items that we created in the previous step. You can also select the function that you
want to display, the drawing style, and the colors. For example:
Name:
1 PA-200-LAB-Madrid: Incoming traffic on interface ethernet1/2.2
2 PA-200-LAB-Madrid: Outgoing traffic on interface ethernet1/2.2
Function: avg (average)
Draw style: Gradient line (to make it look similar to the predefined ones)
Colour: (also to make it look similar to the predefined ones)
3 00C800
4 3333FF

 
©2013, Palo Alto Networks, Inc. [13]
In this example, the remaining fields will use the default values. Click the Save button to commit the changes.
The following screenshot shows how the graph has been configured in our lab:

Screenshot 11.- Graph Management screen

At this point your configuration is complete and you can now add the new graph into your Zabbix’ Dashboard, under
Monitoring > Dashboard as shown in the following screenshot:

Screenshot 12.- Adding the graph into Zabbix’ Dashboard

After everything is configured, wait a few minutes before reviewing the graphs in order to give Zabbix time to create all the
files and take some samples (remember that we poll data every 30 seconds, as defined under the host items).

 
©2013, Palo Alto Networks, Inc. [14]
Verifying the Configuration
There are different methods that can be used to test the configuration to ensure that it works as expected; in this chapter we
will review one method. As Screenshot 1 depicts, in our lab we have purposely configured only one subinterface (with vlan
tag 2), so that the traffic monitored in the physical interface (ethernet1/2) and in the logical one (ethernet1/2.2) should be the
same. We have also set up Zabbix to monitor interface ethernet1/2 via SNMP and ethernet1/2.2 via the scripts and the API,
so that we can check that both methods return similar values.

Furthermore, we have used Iperf on the LAN client and on the DMZ server to generate traffic in both directions. Following
is a short description about this tool from the Iperf website: “Iperf was developed by NLANR/DAST as a modern alternative
for measuring maximum TCP and UDP bandwidth performance. Iperf allows the tuning of various parameters and UDP
characteristics. Iperf reports bandwidth, delay jitter, datagram loss.” For more details on Iperf, refer to
http://iperf.sourceforge.net/ (version 2.x, the one that we used in our lab)
http://code.google.com/p/iperf/ (version 3.x, new development not compatible with version 2.x).

The following screenshots show different examples of bandwidth in both directions for ethernet1/2 and ethernet1/2.2
confirming that the measurements are the same, as expected (ethernet1/2 is monitored via SNMP and ethernet1/2.2 via
scripting and the API):

Screenshot 13.- Monitoring samples for ethernet1/2 (SNMP)

 
©2013, Palo Alto Networks, Inc. [15]
 Screenshot 14.- Same samples for ethernet1/2.2 (API)

Note: The minor differences that appear on some slopes in the previous two screenshots take place because we have used
Iperf over an interface with no traffic and the monitoring period takes place at 30 seconds intervals, but at different
moments on each interface. Therefore when there is a change in Iperf (start/stop) the initial/end measurements will be slightly
different, depending on the moment of the reading.

Conclusions
Palo Alto Networks devices offer a powerful RESTful XML API that extends the configuration and reporting capabilities
well beyond the mechanisms provided within the product itself. In this document, we have shown an example utilization of
this API for those clients that require monitoring network subinterfaces. We have also demonstrated how the API can be
easily integrated with Zabbix’s monitoring solution.

The configuration shown in this document is just a basic example on the utilization of this API. The amount of possibilities
for monitoring and configuring Palo Alto Network devices that the API offers is virtually limitless.

Revision History
Date Revision Comment
2013/08/09 A First version of this document.
2013/09/08 B Orthographical and grammatical revision.

 
©2013, Palo Alto Networks, Inc. [16]