Cisco IOS XR Virtual Firewall Configuration Guide, Release 3.7 - Configuring an XML Interface on the Virtual Firewall [Cisco IOS XR Software]

Table Of Contents

Configuring an XML Interface on the Virtual Firewall

Contents

Information About Configuring an XML Interface

XML Usage with the VFW

HTTP and HTTPS Support with the VFW

HTTP Return Codes

Document Type Definition

How to Configure an XML Interface

Configuring HTTP and HTTPS Management Traffic Services

Prerequisites

Accessing the VFW DTD File

Enabling the Display of Raw XML Request show Command Output in XML Format

Configuration Examples for XML

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Configuring an XML Interface on the Virtual Firewall

Extensible Markup Language (XML) is a powerful and flexible tool that you can use to remotely configure the Virtual Firewall (VFW) application from a network management station (NMS). Any command that you can configure from the VFW application CLI can be configured remotely from an NMS by exchanging XML documents over HTTP or secure HTTP (HTTPS). You can transmit, exchange, and interpret data among the applications. In addition, you can configure the VFW application to transfer show command output to an NMS in XML format for result monitoring and analysis.

Feature History for Configuring XML Interfaces on the VFW Application

Release

Modification

Release 3.5.0

This feature was introduced on the multiservice blade (MSB) for the Cisco XR 12000 Series Router.

Release 3.6.0

No modification.

Release 3.7.0

No modification.

Contents

•Information About Configuring an XML Interface

•How to Configure an XML Interface

•Configuration Examples for XML

•Additional References

Information About Configuring an XML Interface

To configure the XML interface, you should understand the following concepts:

•XML Usage with the VFW

•HTTP and HTTPS Support with the VFW

•HTTP Return Codes

•Document Type Definition

XML Usage with the VFW

Today's e-business applications increasingly rely upon service-oriented architectures such as those provided by Web services. Web services allow companies to easily integrate their strategic applications with those of their partners, both internally and over the Internet. To conduct e-business transactions, organizations need a common language through which to exchange structured information between their computer systems. Web services provide network-based software applications that use XML to transmit, exchange, and interpret data among applications that would otherwise have difficulty interoperating together.

XML provides an application-independent way of sharing data between computer systems. Similar to HTML, XML consists of text delimited by tags, so it is easily conveyed over the Internet. In XML, the tags define the meaning and structure of the information, enabling computer applications to use the information directly. Unlike HTML, XML tags identify the data, rather than specifying how to display it. An XML tag acts like a field name in your program; it puts a label on a piece of data that identifies it (for example: <message>...</message>).

An XML document containing configuration commands and output results is easily transferred between the devices by using standard Internet protocols such as HTTP or secure HTTP (HTTPS) as the transfer protocol.

The XML application programming interface (API) enables you to automate the programmatic configuration of the VFW application by using a Document Type Definition (DTD). The XML format is a translation of the CLI commands into an equivalent XML syntax. Each VFW application CLI command has an equivalent XML tag and all the parameters of the CLI command are attributes of that element. The VFW application uses an Apache HTTP server to provide the XML management interface and to provide HTTP services between the VFW application and the management client.

XML can be used to:

•Provide a mechanism using XML to transfer, configure, and monitor objects in the VFW application. This XML capability allows you to easily shape or extend the CLI query and reply data in XML format to meet different specific business needs.

•Transfer show command output from the VFW application CLI interface in XML format for statistics and status monitoring. This show command output transfer capability allows you to query and extract data from the VFW application.

•Use the VFW application XML DTD schema for formatting CLI queries or parsing the XML results from the VFW application to enable third-party software development through XML communications.

•Provide remote user authentication through AAA.

•Provide session and context management by the administrator and other privileged users.

A network management station (NMS), such as the CiscoWorks Hosting Solution Engine (HSE), can connect to the VFW application and push new configurations to it over HTTP or HTTPS.

HTTP and HTTPS Support with the VFW

An XML document containing configuration commands or output results can easily be sent and received between the VFW application and an NMS by using standard Internet protocols such as HTTP or secure HTTP (HTTPS) as the transfer protocol. HTTPS uses Secure Sockets Layer (SSL) to provide encrypted communication between the management client and the VFW application.

The administrator of the system designates a website as the entry point to the API, and all requests and queries are made through those URLs. This website also provides the DTDs that define the XML for requests, queries, and responses.

The XML input is submitted through the data portion of an HTTP POST request. A field named "xml" contains the XML string that defines the request or query. The response to this HTTP POST represents a pure XML response with either a success or failure indicator for a request or the response to a query.

When you use XML to transfer configuration data and results, the NMS connects to the VFW application and sends a new configuration in an XML document to the VFW application over HTTP or HTTPS. The VFW application then applies the new configuration.

HTTP Return Codes

HTTP return codes indicate the status of the request and report errors between the server and the client. The Apache HTTP server return status codes follow the standards outlined in RFC 2616. Table 15 lists the supported HTTP return codes.

Table 15 Supported HTTP Return Codes for XML

Return Code

Description

200

OK

201

Created

202

Accepted

203

Non-Authoritative Information

206

Partial Content

301

Moved Permanently

302

Found

400

Bad Request

401

Unauthorized (credentials required, but not provided)

403

Forbidden (illegal credentials submitted; syslog also generated)

404

Not Found ("/xml-config" not specified)

405

Method Not Allowed

406

Not Acceptable

408

Request Time-out (more than 30 seconds has passed waiting on receive)

411

Missing Content-Length (missing or zero Content-Length field)

500

Internal Server Error

501

Not Implemented ("POST" not specified)

505

HTTP Version Not Supported ("1.0" or "1.1" not specified)

The following HTTP headers are supported:

•Content-Length (nonzero value required for all POST requests)

•Connection (close value indicates that a request should not be persistent)

•WWW-Authenticate (sent to client when credentials are required and missing)

•Authorization (sent from client to specify basic credentials in base 64 encoding)

For example, when an XML error occurs, the HTTP response contains a 200 return code. The portion of the original XML document with the error is returned with an error element that contains the error type and description.

The following is a typical example of an XML error response:
<response_xml>
<config_command>
<command>
interface interface_name
no shut
description xyz
exit
</command>
<status code = `200' text='XML_CMD_FAILURE'>
<error_command> description xyz </error_command>
<error_message> unrecognized element - description </error_message>
</status>
</config_command>
</response_xml>
The returned error codes correspond to the attributes of the configuration element. The possible returned XML error can include:
XML_ERR_WELLFORMEDNESS /* not a well formed xml document */
XML_ERR_ATTR_INVALID /* found invalid value attribute */
XML_ERR_ELEM_INVALID /* found invalid value unrecognized */
XML_ERR_CDL_NOT_FOUN /* parser cdl file not found */
XML_ERR_INTERNAL /* internal memory or coding error */
XML_ERR_COMM_FAILURE /* communication failure */
XML_ERR_VSH_PARSER /* vsh parse error on the given command */
XML_ERR_VSH_CONF_APPLY /* vsh unable to apply the configuration
Document Type Definition

A document type definition (DTD) is the basis for XML configuration documents that you create using the VFW application. The purpose of a DTD is to define the legal building blocks of an XML document by defining the document structure with a list of legal elements.

DTD designates an XML list that specifies precisely which elements can appear in a request, query, or response document. It also specifies the contents and attributes of the elements. A DTD can be declared inline in your XML document, or as an external reference.

The VFW application DTD file, xblade.dtd, is included as part of the software image and is accessible from a Web browser using either HTTP or HTTPS. See the "Accessing the VFW DTD File" section for details.

How to Configure an XML Interface

•Configuring HTTP and HTTPS Management Traffic Services

•Accessing the VFW DTD File

•Enabling the Display of Raw XML Request show Command Output in XML Format

Caution The VFW application creates two default user accounts at startup: admin and www. The admin user is the global administrator and cannot be deleted. The VFW application uses the www user account for the XML interface. Do not delete the www user account. If you do, the XML interface becomes inoperative. If you accidentally delete the www account, you can reconfigure the account to restore XML operation by entering username www password 5 password domain default-domain role Admin in configuration mode. For information about configuring users, refer to the "Configuring Virtualization on the Virtual Firewall" module.

Configuring HTTP and HTTPS Management Traffic Services

The VFW application provides support for remote management using XML over either HTTP or HTTPS to configure, monitor, and manage software objects. You configure HTTP and HTTPS remote management traffic to the VFW application through class maps, policy maps, and service policies.

The following items summarize the role of each function in configuring HTTP or HTTPS network management access to the VFW application:

•Class map—Provides the remote network traffic match criteria to permit HTTP and HTTPS management traffic based on:

–HTTP or HTTPS network management protocols

–Host source IP addresses

•Policy map—Enables remote network management access for a traffic classification that matches the criteria listed the class map.

•Service policy—Activates the policy map and attaches the traffic policy to an interface or globally on all interfaces.

HTTP or HTTPS sessions are established to the VFW application on a per-context basis. For details on creating contexts and users, refer to the "Configuring Virtualization on the Virtual Firewall" module.

This task illustrates the steps required to configure HTTP or HTTPS traffic management services to support XML usage with the VFW application.

Prerequisites

You must attach from the route processor to the VFW application before you can perform this task. See the "Attaching to the VFW Application" section on page VFC-14.

SUMMARY STEPS

1. configure

2. class-map type management [match-all | match-any] map_name

3. [line_number] match protocol {http | https} {any | source-address ip_address mask}

4. exit

5. policy-map type management first-match map_name

6. class map_name

7. permit

8. exit

9. interface management interface_name

10. ip address ip_address mask

11. service-policy input policy_name

12. exit

13. xml-show on

14. copy running-config startup-config

DETAILED STEPS
Command or Action

Purpose

Step 1

configure
Example:

firewall/Admin# configure
Enter configuration commands, one per line. End with CNTL/Z.
firewall/Admin(config)#

Enters global configuration mode. You are now within configuration mode of the VFW application.
Step 2
class-map type management [match-all | match-any] map_name
Example:
firewall/Admin(config)# class-map type 
management match-all HTTPS-ALLOW_CLASS
Creates a Layer 3 and Layer 4 class map to classify the HTTP or HTTPS management traffic that can be received by the VFW application.
Step 3
[line_number] match protocol {http | https} {any | source-address ip_address mask}
Example:
firewall/Admin(config-cmap-mgmt)# match 
protocol https source-address 192.168.1.1 
255.255.255.255
Identifies HTTP or HTTPS as the network management protocols that are matched by the class map.
Step 4

exit
Example:

firewall/Admin(config-if-mgmt)# exit
firewall/Admin#

Exits class map configuration mode.
Step 5
policy-map type management first-match map_name
Example:
firewall/Admin(config)# policy-map type 
management first-match MGMT_HTTPS_POLICY
Creates a Layer 3 or Layer 4 HTTP or HTTPS policy map and enters policy map configuration mode. The VFW application executes the action for the first matching classification.
Step 6
class map_name
Example:
firewall/Admin(config-pmap-mgmt)# class 
HTTPS-ALLOW_CLASS
Associates a class map defined in Step 2 with the Layer 3 and Layer 4 remote access policy map, and enters policy map class configuration mode.
Step 7
permit
Example:
firewall/Admin(config-pmap-mgmt-c)# permit
Specifies to permit the traffic defined by the class.
Step 8

exit
Example:

firewall/Admin(config-pmap-mgmt-c)# exit
firewall/Admin#

Exits policy map class configuration mode.
Step 9
interface management interface_name
Example:
firewall/Admin(config)# interface management 
m1
Enters interface configuration mode for a management interface.
Step 10
ip address ip_address mask
Example:
firewall/Admin(config-if-mgmt)# ip address 
172.16.1.100 255.255.0.0
Specifies the IP address of the firewall interface.
Step 11
service-policy input policy_name
Example:
firewall/Admin(config-if-mgmt)# service-policy 
input MGMT_HTTPS_POLICY
Attaches the traffic policy to the firewall interface.
Step 12

end
Example:

firewall/Admin(config-if-mgmt)# end
firewall/Admin#

Exits configuration mode.

Step 13

xml-show on
Example:

firewall/Admin# xml-show on

(Optional) Enables the XML conversion of show command output from the VFW application for result monitoring by an NMS.

Step 14

copy running-config startup-config
Example:

firewall/Admin# copy running-config startup-config

(Optional) Saves your configuration changes to flash memory.
Accessing the VFW DTD File

The VFW application DTD file, xblade.dtd, is included as part of the software image and is accessible from a Web browser using either HTTP or HTTPS.

To access and view the Cisco VFW application DTD file, perform the following procedure:

Step 1 If you have not done so, create a Layer 3 and Layer 4 class map and policy map to classify the HTTP or HTTPS management traffic that can be received by the VFW application. See the "Configuring HTTP and HTTPS Management Traffic Services" section.

Step 2 Open your preferred Internet web browser application, such as Microsoft Internet Explorer or Netscape Navigator.

Step 3 To directly access the xblade.dtd file, specify the HTTP or secure HTTP (HTTPS) address of your VFW application in the address field, followed by xblade.dtd. For example:
https:// vfw_ip_address/xblade.dtd
http:// vfw_ip_address/xblade.dtd
You can choose to either open the xblade.dtd file or save it to your computer.

Enabling the Display of Raw XML Request show Command Output in XML Format

By default, XML responses automatically appear in XML format if the corresponding CLI show command output supports the XML format. However, if you are running commands on the CLI console or you are running raw XML responses from NMS, the XML responses appear in regular CLI display format.

You can enable the display of raw XML request show command output in XML format by performing one of the following actions:

•Specify the xml-show on command in EXEC mode from the CLI, or

•Include the xml-show on command in the raw XML request itself (CLI commands included in an XML wrapper).

Specifying the xml-show on command is not required if you are running true XML.

For details on the show command output supported in XML format, consult the VFW application DTD file, xblade.dtd, that is included as part of the software image (see the "Accessing the VFW DTD File" section). The VFW application DTD file contains the information on the XML attributes for those show commands whose output supports XML format.

Configuration Examples for XML

The following example illustrates a typical VShell (VSH) CLI command configuration and its equivalent XML configuration commands:
##############################
## TO/FROM CP CONFIGURATION ##
##############################
conf t
access-list acl1 extended permit ip any any
int interface_name
access-group input acl1
ip address 60.0.0.145 255.255.255.0
no shut
exit
ip route 0.0.0.0 0.0.0.0 60.0.0.1
end
<access-list id="acl1" config-type="extended" perm-value="permit"
protocol-name="ip" src- type="any" dest-type="any"/>
<interface type="xxx">
<access-group type="input" name="acl1"/>
<ip_address address="60.0.0.145" netmask="255.255.255.0"/>
<shutdown sense="no"/>
</interface>
<ip_route dest-address="0.0.0.0" dest-mask="0.0.0.0"
gateway="60.0.0.1"/>
############################
## BRIDGING CONFIGURATION ##
############################
conf t
access-list acl1 extended permit ip any any
int interface_name
access-group input acl1
bridge-group 1
no shut
exit
int interface_name
access-group input acl1
bridge-group 1
no shut
exit
end
<access-list id="acl1" config-type="extended" perm-value="permit"
protocol-name="ip" src-type="any" dest-type="any"/>
<interface type="xxx">
<access-group type="input" name="acl1"/>
<bridge-group value="1"/>
<shutdown sense="no"/>
</interface>
<interface type="xxx">
<access-group type="input" name="acl1"/>
<bridge-group value="1"/>
<shutdown sense="no"/>
</interface>
Additional References

The following sections provide references related to XML interfaces.

Related Documents

Related Topic

Document Title

Virtual firewall interface command syntax

"Interface Commands on the Virtual Firewall" module in Cisco IOS XR Virtual Firewall Command Reference

Virtual firewall class map command syntax

"Class Map Commands on the Virtual Firewall" module in Cisco IOS XR Virtual Firewall Command Reference

Virtual firewall policy map command syntax

"Policy Map Commands on the Virtual Firewall" module in Cisco IOS XR Virtual Firewall Command Reference

Standards

Standards

Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.

—

MIBs

MIBs

MIBs Link

—

To locate and download MIBs using Cisco IOS XR software, use the Cisco MIB Locator found at the following URL and choose a platform under the Cisco Access Products menu: http://cisco.com/public/sw-center/netmgmt/cmtk/mibs.shtml

RFCs

RFCs

Title

No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.

—

Technical Assistance

Description

Link

The Cisco Technical Support website contains thousands of pages of searchable technical content, including links to products, technologies, solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content.

http://www.cisco.com/techsupport