XMPP Client Configuration

Feature Information for XMPP

Table 1 Feature Information for XMPP
Feature Releases Feature Information
SPOM 7.2(0)D1(1) Included as a part of the chapter XMPP Client Configuration.

Single point of management support.

Overview of XMPP Client

Extensible Messaging and Presence Protocol (XMPP) is a communication protocol. XMPP clients set up TCP based XMPP connection to XMPP server. XMPP server forwards the messages from one client to another client or a group of clients based on the configuration and request.

This XMPP protocol is adopted by DFA, so the administrator can manage (by issuing CLI commands) a device or group of devices in the network from the administrator’s XMPP connection with a single point of management with no separate login required for each device. Each device is a XMPP client that can be configured to connect to XMPP server. The administrator issues the CLI command and the device receives the CLI commands. Device processes the CLI commands and sends CLI output back to the administrator XMPP client.

XMPP client support is added to the Cisco NX-OS operating system with DFA since 7.0(0)N1(1) for Cisco Nexus 5000/6000 Series Switches and from 7.2(0)D1(1) for Cisco Nexus 7000 Series Switches. The XMPP client library can be shared by different features which require XMPP client functionality. This chapter explains the usage of XMPP for managing Cisco NX-OS supported devices with the XMPP bus. The XMPP client on the switch provides a single point of access from any switch to the rest of the switches in the network. You can also use other XMPP clients like Pidgin.

Cisco Nexus Series switch command line shell (VSH) includes an integrated XMPP client. You can utilize this feature to send CLI commands to a single device or a group of devices through the XMPP bus.

The figure below illustrates switches in a network being managed by a user using the XMPP protocol. The user can either telnet or SSH to a Cisco NX-OS switch or run a third-party instant messenger such as Pidgin to manage other switches.

Figure 1. XMPP Client

XMPP Server

An XMPP server is required to establish the XMPP communication with the clients. DFA only supports the XMPP server bundled with the Cisco Prime Data Center Network Manager (DCNM) Open Virtual Appliance (OVA). For more information on XMPP server configuration, see Cisco DCNM OVA Installation Guide, release 7.x.

The XMPP server bundled with Cisco Prime DCNM OVA is XCP (Cisco internally developed product) with Version 2012.2.0.38425. Standalone XMPP server uses PostGreSQL database that is packaged in the same OVA. In a XMPP HA setup, an external Oracle database is required to be installed by user for both XMPP active and standby servers to share. Oracle 11g XE version 11.2.0 (oracle-xe-11.2.0-1.0.x86_64.rpm) is verified to work with XCP Version 2012.2.0.38425.

XMPP server is bundled with DCNM OVA. Log into Cisco Prime DCNM server via SSH and use the appmgr command to verify the XMPP status:

appmgr [start|stop|status|restart] xmpp 
appmgr start xmpp

For XMPP user and group management use the following appmgr command to add, delete, and list the users and groups:

appmgr [add_user|delete_user|list_users|add_group|delete_group|list_groups] xmpp 
 
appmgr add_user xmpp -u <user> -p <secret>
appmgr delete_user xmpp -u <user>
appmgr list_users xmpp
appmgr add_group xmpp –u <user> -p <secret> -g <groupname>
appmgr delete_group xmpp -u <user> -p <secret> -g <groupname>
appmgr list_groups xmpp

XMPP Client Configuration

The basic configurations required on an Cisco NX-OS switch to establish an XMPP session are the following:

  • Enabling the XMPP Client (fabric access) feature

  • Network path to the XMPP server

  • XMPP server configuration to establish client-server connection

  • XMPP group subscription

Enabling the XMPP Client Feature

The XMPP client feature on an Cisco NX-OS switch is a conditional service which is referred as fabric access. This feature can be enabled/disabled using the following configuration command: 

[no] feature fabric access

Network Path to the XMPP server

The address information for an XMPP server is a Fully Qualified Name (FQN). Therefore, the switch requires either the static local IP-to-Name mapping or the capabilities to resolve the FQN via DNS to establish a client-server connection.

The following is an example for configuration of a locally configured DNS resolution for server host-65-mgmt.cisco.com with IP address 10.0.0.1. 
switch(config)# ip host-65-mgmt.cisco.com 10.0.0.1

Note

This name must match with the name of the XMPP server. In case of Cisco Prime DCNM XMPP server, the name must match with the printout of the appmgr list_users xmpp command.

XMPP Server Connection Configuration

XMPP client connects to a specific XMPP server with configured VRF route and JID information.

JID is a Jabber Identifier (JID), which uniquely identify individual entities in the XMPP (Jabber) network. For example, consider if the Fully Qualified Domain name of server is xmpp-server.cisco.com and the username is 'admin' (username can be obtained by issue 'where' cli on the device), JID for this user is admin@xmpp-server.cisco.com. For a device, by default device hostname is used as the ID to construct device JID. If device host name is leaf, JID for this device is leaf@xmpp-server.cisco.com.

Use the following command: 

[no]fabric access server <fqn-name> [vrf <vrf-known-name>] password <password>
switch(config)# fabric access server  host-65-mgmt.cisco.com vrf management password 
		  pwd

For more information on XMPP commands, see XMPP Client Commands.

XMPP Group Subscription

XMPP client can join multiple group chats. The user has to create a group by using the fabric access create group group-name command. Before running the command to create a group, the user has to log into the XMPP server and get an authentication.


Note

If a group does not exist yet, the group subscription command will not be in effect, and the switch has to retry the group subscription periodically till it is successful.

The XMPP client can join a group using the [no] fabric access group <group-name> command. 

switch(config)# fabric access group leaves

XMPP Client Configuration for Third-Party Instant Messenger

The basic configurations (high level) required on a third-party instant messenger to establish an XMPP session are the following:


Note

The detailed procedure depends on the type of instant messenger application used, for example Pidgin. For more information, see https:/​/​www.pidgin.im/​support/​.

  • An account with the XMPP server (if open registration is allowed; else the system administrator can set up an account on the XMPP server.)

  • Establish connection with the XMPP server

  • Establish connection with the Cisco NX-OS switches

  • XMPP group subscription

Logging into an Account with the XMPP Server

The user has to log in to the XMPP server and get an authentication first to access the XMPP client on the Cisco NX-OS switch. The XMPP login username is inherited from the current login/telnet session username on the switch.


Note

Whenever a user role or privilege of a user account is changed, the changed role shall come into effect for subsequent logins only. 

Switch# fabric access login <user-password>

Note

After successful authentication from the server, the user can use the XMPP client on the switch to perform XMPP client functionalities similar to those on the instant messenger.

Verifying the Network Path to the XMPP Server

The network path (through VRF) can be validated with a ping to ensure that the XMPP client on the Cisco NX-OS switch communicates with the XMPP server. 

ping host-65-mgmt.cisco.com vrf management

Verifying the XMPP Server Connection

The following show command can be used to check if the XMPP client on the switch has been successfully authenticated to the server: 
Switch# show fabric access connection

XMPP Ping:
  Status = Enabled
  Interval = 120 second(s)
  Response = 60 second(s)
  Retry = 3 time(s)
  Next Ping will be sent : in 24 second(s)
XMPP Payload CDATA-Encapsulated : Enabled
Device Connection :
  JID      = switch@host-65-mgmt.cisco.com/(fmgr-device)(FOX01010101)
  State    = AUTHENTICATED

Examples for XMPP Client Configuration

This is an example for basic configuration required on a Cisco NX-OS switch to enable the XMPP client and to establish the XMPP connection with the server. 

feature fabric access
!Enables the XMPP Client feature

ip host host-2-mgmt.cisco.com 10.1.1.2
!DNS for XMPP server

fabric access server host-2-mgmt.cisco.com vrf management password pwd
!Establishes XMPP connection between the switch and the XMPP-server,
configures XMPP-server DNS name, and switch password.

This is an example for basic configuration required for an XMPP client to join multiple groups. 

fabric access group global
!XMPP client joins group chat “global”

fabric access group leaves
!XMPP client joins group chat “leaves”

The following is a simple example of getting into XMPP client mode from Cisco NX-OS VSH CLI exec mode. Some prerequisite steps are needed to reach this stage, for example, setting up the XMPP server, have the Cisco Nexus Switch establish XMPP connection to the server. This specific example starts with attaching to the group "leaves" and at the same time entering the XMPP Client mode. Any commands entered in the client mode will be applied to all members of the "leaves" group. The exit command leaves the XMPP client mode and gets back to Cisco NX-OS VSH CLI. 

Switch#
Switch# fabric access attach group leaves  
Switch>leaves# copy running-config startup-config //will be applied to all members//
Switch>leaves# exit
Switch#

NETCONF contents in XMPP bus

Since 7.0 release, XMPP Client can process NETCONF XML. There is no specific "tag" introduced for NETCONF XML processing in the XMPP Client. XMPP Client has the capability to distinguish the incoming XMPP payload as XML/Netconf or raw CLI without a specific tag.

XMPP Client will use the following information to distinguish the XML/Netconf commands or raw CLI commands.

Opening xml tag "<?xml …?>"

Attribute "urn:ietf:params:xml:ns:netconf:base:1.0"

Closing char string "]]>]]>" 

<?xml version="1.0"?>
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <nc:capabilities>
    <nc:capability>
        urn:ietf:params:xml:ns:netconf:base:1.0
    </nc:capability>
  </nc:capabilities>
</nc:hello>]]>]]>

XMPP Client Commands

Cisco NX-OS commands on XMPP Client

Switch(config)#[no] feature fabric access

  • Enables/disables the fabric access feature. 

Switch(config)#[no] fabric access server <dns-name> [device <name>] [vrf <vrf-name>] password <password>

  • Configures XMPP server (must be DNS name) for the XMPP connections. This is for the switch to establish its own XMPP connection to the server.

  • If no device <name> is configured, the default value will be the hostname of the device. The name can be upper/lower case in configuration, but it will be converted to lower case in the server always based on the standard.

  • Password allows authentication of XMPP device connection. It can be input by clear or encrypted format. And also can be interactive input if no password is specified in the command line. In running-config or startup-config, it will only show encrypted password. 

Switch(config)#[no] fabric access group <group-name>

  • The group-name can be configured in uppercase or lowercase, but it will be always converted to lowercase in the server based on the standard.

  • If the group does not exist in the server, the device will not be able to subscribe to the group and will retry periodically in the background. Device can only join the groups, not create the groups. 

Switch(config)#[no] fabric access prepend-id

  • To have the display of the replied result prepend the source device information for each line. The default is disabled. 

Switch(config)#[no] fabric access ping [ interval <interval> | response <response> | retry <retry>]

  • To have the device send XMPP PING packets periodically to the configured XMPP server. The default is enabled.

  • Proactively validate the liveness of the server.

  • Interval: how frequently send the XMPP PING packet.

  • Response: how long will to wait for the response XMPP PING packet from server.

  • Retry: how many times for retrying.

  • Default values for those parameters and range can be found in the CLI help. 

Switch(config)#[no] fabric access CDATA-encap

  • To have the replied result encapsulated inside <CDATA> tag in the XMPP payload. The default is enabled.

  • CDATA is used about text data that should not be parsed by the XML/XMPP parser. Characters such as "<" and "&" are illegal in XML elements.

  • Different XMPP server may support parsing <CDATA> differently. 

Switch#[no] fabric access create group <group-name>

  • For the login user to create XMPP chat groups in the XMPP fabric access network.

  • Creation will be failed if no successful user connection. 

Switch#[no] fabric access login [<password>]

  • The login user can connect to the configured XMPP server and build up the user connection.

  • The login name can be in upper/lower case, but it will be converted to lower case in the server always based on the standard. Login name is generated automatically for this cli and sent, which is the same as the current user credentials logged into the privileged EXEC mode.

  • Hence, it will be lower case in displaying runtime information.

  • Password allows the authentication of XMPP for the user connection. It can be input by clear or encrypted format. And also can be interactive input if no password specified in the command line.

  • Only when the login user creates the user connection to the XMPP server, the login user can access the fabric access (XMPP) network. 

Switch#[no] fabric access local-help

  • In the attach mode, the help command is executed in local device or remote device. Default is local. 

Switch#[no] fabric access attach { group <group-name> | device}

  • The login user can attach (join) XMPP chat group or device under attaching mode in the XMPP fabric access network.

  • Attaching will be failed if there is no successful user connection.

  • If the group or device do not exist in the XMPP server, the attachment will fail. 

Switch# fabric access send { group <group-name> | device <device-name>+} <cli-command>

  • The login user to send CLIs to group/device(s) in the XMPP fabric access network.

  • Sending will fail if there is no successful user connection.

  • If the group or device(s) does not exist in the XMPP server, the sending will fail. 

Switch# show fabric access connections

  • To show fabric access feature information and all the connections' status. 

Switch# show fabric access group [{members <group-name>} | {device} | {user}]

  • To show fabric access group information.

  • Command will fail if there is no successful user connection.

  • It can show all the created groups in the XMPP fabric access network, groups which the device has joined, groups which the login user has joined, and the group members of the specific group. 

Switch# show fabric access statistics

  • To show fabric access feature statistics information.

  • The statistics information about which device did not reply before. 

Switch# clear fabric access user <username>

  • To clear a user connection in this device.

  • Remove any specified user connection in this device in the XMPP fabric access network. 

Switch# clear fabric access statistics

  • To clear fabric access feature statistics information.

  • The statistics information can be reset by this command.