What is the AXP Triggering API?

The AXP Triggering API allows your application to listen and respond to real time events which occur on the system. The API leverages the Embedded Event Manager - EEM for event detection and tracking.

Are there any special IOS images that my router must use to support this API?

Yes. You can use any of these these IOS image types. Please also assure that the router and IOS version are supported by AXP.

1. adventerpris
2. advsecurity
3. ipvoice

What package must my application depend upon to use this api?

Your application must depend upon the package axp-eemapi.<platform><version>.pkg

How would I package my application with this dependency?

When you are creating your command line arguments to run the packaging script pkg_build.sh, you must include the parameter --deps '<dependency package ssid>,<dependency version>'. An example is given below. Be sure to get your dependency package ssid by using the script pkg_info.sh.

--deps '6aee7d85-980a-4e20-b15a-c8ac882a968d,all'

Do I have to install this dependency package separately onto the AXP module?

No, you can bundle it with your packaged application using the bundling script pkg_bundle.sh

Do I need to configure the ISR or AXP Module for this API to work?

Yes, on the AXP Module you must configure the IOS user. The IOS user must have the same username/password that you assigned to your ISR for tty log in.. An example is below. The assumption below is that the ISR has for tty login the username cisco and password cisco123 assigned to it.

config t
username ios cisco password cisco123
end
copy run start

In addition, to track ios_config event types, you must set up netconf over beep on the both the ISR and the AXP module. On the ISR you'll type the commands below. Be sure to replace <port number> with your actual port number. You can also use ACLs to limit communication, but they're not shown here.

config t
sasl profile SASL_PROFILE
mechanism anonymous
netconf beep listener <port number> sasl SASL_PROFILE
netconf max-sessions 16
end
copy run start

On the AXP service module, you can either manually add the netconf over beep protocol or include it in your source code for you application. The manual steps are shown below. The 'ISR IP address' must match the ip of your ISR, and the 'port number' must also match the chosen port number specified in the net conf beep commands on your ISR.

config t
netconf beep initiator <ISR IP address> <port number>
netconf max-sessions 16
end
copy run start

To track syslog events you must turn on the logging buffer on the router

config t
logging buffered <size>
end
copy run start

APPLICATIONEXTENSIONPLATFORM:Return to top

How do I register events to be tracked?

Event registration and tracking is a two step process. The first step is to define the events by either creating and packaging them in an XML file or by entering the events via the CLI. The two methods to define the events is shown below.

Step 1: Method 1 - Create an xml file called eem_config.xml and place it into your build source directory usr/eemapi. For example if you wanted to track ios_config, syslog and timer event types, your eem_config.xml might look like the example shown below.
<Events>
<event name="myiosevent" type="ios_config" />
<event name="mysyslogevent" type="syslog" parameters="pattern Ethernet" />
<event name="mytimerevent" type="timer" parameters="watchdog name dog time 10" />
</Events>

Step 1: Method 2 - Define your events via the CLI. This definition must be configured within the guest environment of your packaged application. Note that you could do this same process programmatically using the CLI Service API - not shown below. After defining a new event you must reset your virtual instance so that the new event will be received.

config t
app-service eemapi_app
event myiosevent register ios_config
event mysyslogevent register syslog "pattern Ethernet"
event mytimerevent register timer "watchdog name dog time 10"
end

copy run start
app-service eemapi_app
reset
end

Step 2:
In the second step, your application must register these events with the EventManager. Assuming you have a class called MyEventHandler that is a child of class EventHandler, here is a snippet below.

MyEventHandler eh = new MyEventHandler();
EventManager em = EventManager.getInstance();
em.Register(eh,"ios_config syslog timer");

APPLICATIONEXTENSIONPLATFORM:Return to top

Please provide a source code example of this API.

import com.cisco.aesop.apphosting.eemapi.*;
import com.cisco.aesop.apphosting.appreapi.*;
import java.io.*;

/**
*Sample MyEventHandler class to configure the service module and modify the router
*interface. Uses the IOS Service API for router modification and the CLI Service API to *configure the Service Module.
*Be sure to replace the [router-ip] [port] strings in the configureSM method
*with your router IP and the matching port number you set up on the router for
*netconf communication.
*/
class MyEventHandler extends EventHandler{
  private static final String appName = "[eemapi_test] ";

  MyEventHandler(){
    super(null);
  }

  /**
   * callback method where detected event is reported to the application.  Use this
   * for start of business logic.
   * @param eventName  the name of the event
   * @param eventType  the type of the event
   * @param eventInfo  the event detail
   */
  public void callback(String eventName, String eventType, String eventInfo){
     log("callback got event " + eventName + "type " + eventType + " info " + eventInfo);
  }

  /**
   * Prints the message to the screen and logs it to the application's
   * /var/log/messages.log file.
   * @param data the message to be printed
   */
  private static void log (String data){
    PrintWriter pw=null;
    try{
       System.out.println(appName + data);
       pw = new PrintWriter(new FileWriter("/var/log/messages.log",true));
       pw.println(appName + data);
    }
    catch(Exception e){
      System.out.println(appName + " Exception " + e.getMessage());
    }
    finally{
      if(pw != null){
        pw.close();
      }
    }
  }

  /**
   * Checks if netconf is already configured on the Service Module
   * @return true if netconf configured, otherwise false.
   * @throws Exception
   */
  public boolean isNetconfConfiguredOnSM() throws Exception{
    final String cmd                = "show run | include netconf";
    boolean result                  = false;
    CommonServiceImpl apiCall       = new CommonServiceImpl();
    AppreMessage msg                = new AppreMessage();

    log("Entering isNetconfConfiguredOnSM");
    msg.setRequest(cmd);
    if(apiCall.exec(msg)!=AppreAPI.FAIL){
      String response = msg.getResponse();
      if(response.length()>0 && response.indexOf("netconf")!=-1){
        result = true;
      }
    }
    else{
      log("Command failed " + cmd);
    }
    return result;
  }


  /**
   * Copies the running configuration to the startup
   * configuration on the Service Module.
   * @throws Exception
   */
  public boolean saveConfigurationOnSM() throws Exception{
    final String cmd                = "copy run start";
    boolean result                  = false;
    CommonServiceImpl apiCall       = new CommonServiceImpl();
    AppreMessage msg                = new AppreMessage();

    log("Entering saveConfigurationOnSM");
    msg.setRequest(cmd);
    if(apiCall.exec(msg)!=AppreAPI.FAIL){
      result = true;
    }
    else{
      log("Command failed " + cmd);
    }
    return result;
  }

  /**
   * Configures netconf over beep on the service module
   * @throws Exception
   */
  public boolean configureSM() throws Exception {
    final String cmd             = "netconf beep initiator [router-ip] [port],netconf max-sessions 16";
    boolean result               = false;
    CommonServiceImpl apiCall    = new CommonServiceImpl();
    AppreMessage msg             = new AppreMessage();

    log("Entering configureSM");
    msg.setRequest(cmd);
    if(apiCall.config(msg)!=AppreAPI.FAIL){
      result = true;
    }
    else{
      log("Command failed " + cmd);
    }
    return result;
  }


  public static void main (String args[]){
    final String EVENTS = "ios_config syslog timer";
    EventManager em = null;

    try{
      boolean isSMConfigured = false;
      log("Starting application.");
      MyEventHandler eh = new MyEventHandler();
      if(!eh.isNetconfConfiguredOnSM()){
        if(eh.configureSM()){
          eh.saveConfigurationOnSM();
          isSMConfigured=true;
        }
      }
      else{
        MyEventHandler.log("Skipping service module configuration");
        isSMConfigured=true;
      }

      em = EventManager.getInstance();
      if(em.Register(eh,EVENTS)==1){
        MyEventHandler.log("Registered events " + EVENTS);
        MyEventHandler.log("Going into wait state");
        Object obj = new Object();
        synchronized (obj){
          obj.wait();
        }
      }
      else{
        MyEventHandler.log("Failed to register events " + EVENTS);
      }
    }
    catch(Exception e){
      MyEventHandler.log("Caught exception " + e.getMessage());
    }
    finally{
      if(em!=null && em.Deregister()==1){
        MyEventHandler.log("Deregistered events " + EVENTS);
      }
      else{
        MyEventHandler.log("Failed to deregister events"+ EVENTS);
      }
    }
  }
}

How do I compile the source code example?

To compile this java source code you'll need the jar files appreapi.jar and eemapi.jar. These jar files are provided in the AXP sdk. So to compile this code your command line would like something like:

javac -classpath appreapi.jar:eemapi.jar MyEventHandler.java

Do I need to include the appreapi.jar and eemapi.jar files in my package?

No. The appreapi.jar file is built into the AXP Guest OS, and the eemapi.jar file is included with your axp-eemapi.<platform><version>.pkg, and gets added to the AXP Guest OS when you install this package. In the AXP Guest OS of your application these files reside in the directory /usr/lib/java.

Are there any additional files required to run this source code example?

Yes. You also need file localsocket.jar. This file is also included with your axp-eemapi.<platform><version>.pkg, and gets added to the AXP Guest OS when you install this package. In the AXP Guest OS of your application these files reside in the directory /usr/lib/java.

Where are the library files located in the sdk and Guest OS for other language support such as C, C++ and Python?

The files for support of these languages in the sdk are located in the directory axp-sdk.<version>. In the AXP module Guest OS, you'll find files supporting these languages in the /lib directory and child directories below it.