XML Transport and Event Notifications

This chapter contains these sections:

•TTY-Based Transports

•Dedicated Connection Based Transports

•SSL Dedicated Connection based Transports

TTY-Based Transports

These sections describe how to use the TTY-based transports:

•Enabling the TTY XML Agent

•Enabling a Session from a Client

•Sending XML Requests and Receiving Responses

•Configuring Idle Session Timeout

•Ending a Session

•Errors That Result in No XML Response Being Produced

Enabling the TTY XML Agent

To enable the TTY agent on the router, which is ready to handle incoming XML sessions over Telnet and Secured Shell (SSH), enter the xml agent tty command, as shown in this example: 

RP/0/RP0/CPU0:router# configure

RP/0/RP0/CPU0:router(config)# xml agent tty

RP/0/RP0/CPU0:router(config)# commit

RP/0/RP0/CPU0:router(config)# exit

For more information about the xml agent tty command, see Cisco IOS XR System Management Configuration Guide.

TTY (SSH) agent is telnet based, so IPv6 addressing is supported.

Enabling a Session from a Client

To enable a session from a remote client, invoke SSH or Telnet to establish a connection with the management port on the router. When prompted by the transport protocol, enter a valid username and password. After you have successfully logged on, enter xml at the router prompt to be in XML mode.

A maximum of 50 XML sessions total can be started over a dedicated port, TTY, SSH, and Secure Sockets Layer (SSL) dedicated port.

Note You should use, if configured, either the management port or any of the external interfaces rather than a connection to the console or auxiliary port. The management port can have a significantly higher bandwidth and offer better performance.

Sending XML Requests and Receiving Responses

To send an XML request, write the request to the Telnet/SSH session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window.

Note The XML request must be followed by a new-line character; for example, press Return, before the request is processed.

Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with </Response> and asynchronous responses (for example), notifications, end with </Notification>.

The client application is single threaded in the context of one session and sends requests synchronously; for example, requests must not be sent until the response to the previous request is received.

Configuring Idle Session Timeout

When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout.

To configure the idle session timeout in minutes for the XML agents, use this command:

xml agent [tty | ssl] session timeout <1-1440>

Ending a Session

If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt:

1. Enter the exit command to end XML mode.

2. Enter the exit command to end the Telnet/SSH session.

Errors That Result in No XML Response Being Produced

If the XML infrastructure is unable to return an XML response, the TTY agent returns an error code and message in the this format: 

ERROR: 0x%x %s\n

Dedicated Connection Based Transports

These sections describe how to use the dedicated connection-based transports:

•Enabling the Dedicated XML Agent

•Enabling a Session from a Client

•Sending XML Requests and Receiving Responses

•Configuring Idle Session Timeout

•Ending a Session

•Errors That Result in No XML Response Being Produced

Enabling the Dedicated XML Agent

To enable the dedicated agent on the router, which is ready to handle incoming XML sessions over a dedicated TCP port (38751), enter the xml agent command, as shown in the following example: 

RP/0/RP0/CPU0:router# configure

RP/0/RP0/CPU0:router(config)# xml agent

RP/0/RP0/CPU0:router(config)# aaa authorization exec default local

RP/0/RP0/CPU0:router(config)# commit

RP/0/RP0/CPU0:router(config)# exit

For more information about the xml agent command, see Cisco IOS XR System Management Configuration Guide.

The default addressing protocol for the XML dedicated agent is

•IPv4 enabled

•IPv6 disabled

To configure a dedicated agent to receive and send messages through IPv6 protocol:

xml agent ipv6 enable

To configure dedicated agent to disable IPv4 protocol

xml agent ipv4 disable

To receive and send messages only through IPv6 protocol:

xml agent ipv4 disable

xml agent ipv6 enable

Enabling a Session from a Client

To enable a session from a remote client, establish a TCP connection with the dedicated port (38751) on the router. When prompted, enter a valid username and password. After you have successfully logged on, the session is in XML mode and is ready to receive XML requests.

A maximum of 50 XML sessions total can be started over dedicated port, TTY, SSH, and SSL dedicated port.

Sending XML Requests and Receiving Responses

To send an XML request, write the request to the established session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window.

Note The XML request must be followed by a new-line character; for example, press Return, before the request is processed.

Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with </Response> and asynchronous responses (for example), notifications, end with </Notification>.

The client application is single threaded in the context of one session and sends requests synchronously; for example, requests must not be sent until the response to the previous request is received.

Configuring Idle Session Timeout

When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout.

To configure the idle session timeout in minutes for the XML agents, use this command:

xml agent [tty | ssl] session timeout <1-1440>

Ending a Session

If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt:

1. Enter the exit command to end XML mode.

2. Enter the exit command to end the Telnet/SSH session.

Errors That Result in No XML Response Being Produced

If the XML infrastructure is unable to return an XML response, the TTY agent returns an error code and message in this format: 

ERROR: 0x%x %s\n

SSL Dedicated Connection based Transports

These sections describe how to use the dedicated connection based transports:

•Enabling the SSL Dedicated XML Agent

•Enabling a Session from a Client

•Sending XML Requests and Receiving Responses

•Configuring Idle Session Timeout

•Ending a Session

•Errors That Result in No XML Response Being Produced

Enabling the SSL Dedicated XML Agent

To enable the SSL dedicated agent on the router, which is ready to handle incoming XML sessions over dedicated TCP port (38752), enter the xml agent command, as shown in this example: 

RP/0/RP0/CPU0:router# configure 

RP/0/RP0/CPU0:router(config)# xml agent ssl

RP/0/RP0/CPU0:router(config)# aaa authorization exec default local 

RP/0/RP0/CPU0:router(config)# commit 

RP/0/RP0/CPU0:router(config)# exit

Note The k9sec package is required to use the SSL agent. The configuration is rejected during a commit when the k9sec package is not active on the system. When the k9sec package is deactivated after configuring the SSL agent, the agent is not available.

The SSL dedicated agent uses IPSec, so IPv6 addressing is supported.

Enabling a Session from a Client

To enable a session from a remote client, establish a TCP connection with the dedicated port (38752) on the router. When prompted, enter a valid username and password. After you have successfully logged on, the session is in XML mode and is ready to receive XML requests.

A maximum of 50 XML sessions can be started over a dedicated port, TTY, SSH, and a SSL dedicated port.

Sending XML Requests and Receiving Responses

To send an XML request, write the request to the established session. The session can be used interactively; for example, typing or pasting the XML at the XML> prompt from a window.

The XML request must be followed by a new-line character. For example, press Return before the request is processed.

Any responses, either synchronous or asynchronous, are also displayed in the session window. The end of a synchronous response is always represented with </Response>. Asynchronous responses end with </Notification>.

The client application is single threaded in the context of one session and sends requests synchronously. Requests must not be sent until the response to the previous request is received.

Configuring Idle Session Timeout

When a session times out, the resource from that session is reclaimed. By default, XML agents do not have an idle session timeout.

To configure the idle session timeout in minutes for the XML agents, use this command:

xml agent [tty | ssl] session timeout <1-1440>

Ending a Session

If you are using a session interactively from a terminal window, you can close the window. To manually exit the session, at the prompt:

1. Enter the exit command to end XML mode.

2. Enter the exit command to end the Telnet/SSH session.

Errors That Result in No XML Response Being Produced

If the XML infrastructure is unable to return an XML response, the SSL dedicated agent returns an error code and message in this format:

ERROR: 0x%x %s\n