Main

Admin - Networking 5.2

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:29:47 GMT

Admin - Networking

Creating Virtual and VLAN Interfaces 4.8

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:29:02 GMT

Creating Virtual ethernet and Vlan interfaces

- Virtual and Vlan interfaces can only be created on a configured and non-virtual interface.

- The syntax for virtual interface is eth<#>:<#> e.g. eth0:200 where 200 is a locally significant number to distinguish within the blade.

- The syntax for vlan interface is eth<#>.<#> e.g. eth1.100 where 100 is the VLAN ID tag used to send traffic.

Creating Virtual Ethernet Interface

se-1-100-50-127> configure t
Enter configuration commands, one per line. End with CNTL/Z.
se-1-100-50-127(config)> interface eth0:200
se-1-100-50-127(config-interface)> ip address 12.12.13.10 255.255.255.0
se-1-100-50-127(config-interface)> end
se-1-100-50-127>

- Make sure on the IOS side a appropriate route is setup to direct traffic to this new network

Creating VLAN interface

se-1-100-50-127> configure t
Enter configuration commands, one per line. End with CNTL/Z.
se-1-100-50-127(config)> interface eth0.10
se-1-100-50-127(config-interface)> ip address 10.7.8.9 255.255.255.0
se-1-100-50-127(config-interface)> end
se-1-100-50-127>

- On top of making sure that the IOS side has the appropriate route to setup traffic to the VLAN interface. Need to configure the IOS interface to the DOT1Q mode (causes the interface to inject 802.1q VLAN tag)

- Note the DOT1Q mode only affects the traffic flowing to and from this interface and not injecting the VLAN tag for end to end traffic.

interface Integrated-Service-Engine1/0.1
encapsulation dot1Q 10

CLI Service API 4.3

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:27:52 GMT

What is the CLI Service API?

The CLI service API allows your application to interact with the underlying CLI server on the host. Your application code can issue EXEC mode commands or configuration mode CLI commands to dynamically query and modify the AXP module configuration. Multiple CLI commands of the same type, exec or configuration, can be submitted as long as they are separated by the comma delimiter.

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

No package dependency is needed. This functionality is built into the AXP Guest OS.

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

No additional configuration is required.

Please provide a source code example of this API.

CliServiceTest.java

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

/**
*Sample CliServiceTest class to query and configure the service module with *netconf over beep protocol. In a production level program,the *System.out.println commands should be replaced by logging.
*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.
*/
public class CliServiceTest{

/**
*Constructor
*/
public CliServiceTest(){}

/**
* 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();

  System.out.println("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{
    throw new Exception("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();

  System.out.println("Entering saveConfigurationOnSM");
  msg.setRequest(cmd);
  if(apiCall.exec(msg) != AppreAPI.FAIL){
    result = true;
  }
  else{
    throw new Exception("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();

  System.out.println("Entering configureSM");
  msg.setRequest(cmd);
  if(apiCall.config(msg) != AppreAPI.FAIL){
    result = true;
  }
  else{
    throw new Exception("Command failed " + cmd);
  }
  return result;
}


public static void main(String[] args){
  try{
    System.out.println("Starting application.");
    CliServiceTest IOS = new CliServiceTest();
    if(!IOS.isNetconfConfiguredOnSM()){
      if(IOS.configureSM()){
        IOS.saveConfigurationOnSM();
        System.out.println("Configured service module.");
      }
    }
    else{
      System.out.println("Service module has already been configured.");
    }
  }
  catch(Exception e){
    System.out.println(e.getMessage());
  }
  finally{
    System.out.println("Application done.");
  }
}

How do I compile the source code example?

To compile this java source code you'll need the jar file appreapi.jar. This jar file is provided in the AXP sdk. So to compile this code you command line would like something like:

javac -classpath appreapi.jar CliServiceTest.java

Do I need to include the appreapi.jar file in my package?

No. The jar file is included in the AXP Guest OS of your application and resides 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.

AXP Triggering API 3.9

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:26:45 GMT

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.

adventerpris
advsecurity
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.

snippet.txt

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.

MyEventHandler.java

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?

How to Install AXP via the Helper File 4.7

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:24:23 GMT

This installation requires that you set up both tftp and ftp servers. In the tftp public directory place the helper file into it. And on the same box place together into a different directory the installation files. The helper file has the named format axp-helper. while the installation files have the named format of axp-k9...pkg, axp-k9...prt1 and axp-installer-k9...prt1. Be sure that your blade can ping this server, and assure your tftp and ftp servers are running. Here are the steps to follow should you decide to do this process. This is a clean installation, so your previously existing software and packages on the blade will be removed. 1. At the AXP prompt type 'reload' {{{ 2. When the boot loader prompt comes up saying 'type *** to change boot configuration', type ***. }}} 3. Type config. 4. Enter the following information for each prompt: IP Address : [Your AXP blade IP] Subnet mask : 255.255.255.0 TFTP server : [IP of your tftp server]. Must be pingable from blade. Gateway : [Your router-side IP]. Default Helper-file : [helper file name] Ethernet interface : internal External interface media : copper Default Boot : disk Default bootloader : secondary 5. Type 'show config' and verify your settings. Re-edit if necessary. Then type 'ping ' to confirm network communication. 6. Type 'boot helper'. 7. Boot helper will load. Note that if your boot helper does not load, then check these common issues: your tftp server is not running, you haven't placed the helper file into your tftp server's public directory, you misnamed the helper file in your configuration. 8. Select from the menu, 'install software'. 9. At the package name prompt enter the axp installation package name. This file was describe above and has the suffix .pkg. 10. At the url prompt enter the url ftp:/// 11. When prompted, enter the username and at the password prompt enter the password. 12. System may ask you if you want to retain old settings, do not retain them. 13. AXP platform will be installed.

How AXP Upgrades Your Package Files 3.2

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:23:57 GMT

During an upgrade the AXP system compares the manifest file included in the upgrade package to the manifest file of the already installed package. Each manifest file contains a list of the file names, along with the directory location and checksum of each file. Regarding the manifest file of the already installed package, there are two important items to take note of: First, the manifest contains details of only files that were installed onto the system, so files created by the application are not tracked. Second, the manifest does not track file changes so even if these installed files are then modified or deleted on the system by the application, their initial md5sum taken during the installation is still what is used for comparison. In the discussion below I'll call the manifest file of the already installed package ManA and the manifest file of the upgrade package ManU. As the reader will see, there are several possibilities that could occur based upon the comparison of the manifest files.

The originally installed file will be removed if ManU does not contain the matching file location and name listed in ManA.
The originally installed file will be overwritten if ManU contains the same file location and name listed in ManA but with a different checksum.
The originally installed file will be left alone if ManU contains the same file location, name and checksum of the file in ManA.
A new file will be added if ManU contains a file location, name that does not exist in ManA.

After being installed onto AXP files that are dynamically created by the application are not added to the installation manifest and, therefore, are essentially ignored during the upgrade. In addition, the installation manifest file does not pay attention to file changes such as deletion or modifications that occur after the application is installed. As a result there are a few upgrade scenarios to consider.

Installed file A has a checksum value of Y and is changed by the application to have a checksum value of Z, during the upgrade process only the checksum value of Y will be considered.
Installed file A is deleted by the application; however the upgrade process will only consider the installed manifest file which will show that file A still exists.
File A is dynamically created by the application. The upgrade process will not remove this file because it does not exist in the installed manifest file. However, file A would be overwritten if the upgrade manifest contains a file with the same location and name.

Finally, before the upgrade process begins the system shuts down the virtual instance of the installation to be upgraded effectively stopping the running applications so that timing issues do not occur.

Configuring eth1 8.7

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:23:35 GMT

Configuration of the Network-Modules' External Interface

On most network-module, there is an additional External Interface. This External Interface is located on the faceplate of the Network-Module and provides a RJ-45 connector.

This interface can only be used (and therefore configured) by the Network-Module; the ISR does not see this interface. This external interface can be use to connect the Network-Module to a different network.

The configuration of the interface (eth1) is done similarly to any other IOS Modern Ethernet Interface.

First, get to the Network-Module's console in configuration mode and enter the eth1 interface submode.

Router#service-module integrated-Service-Engine 1/0
session network-module> configure terminal
Enter configuration commands, one per line. End with CNTL/Z.
network-module(config)> interface eth1
network-module(config-interface)> ip address 10.10.0.24 255.255.255.0
network-module(config-interface)> no shutdown

After the configuration of the external interface, make sure that the network is connected and that you configure additional ip route if required.

Application Install, Upgrade and Uninstall 4.5

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:22:21 GMT

Installing an Application

In the packaging section of our SFS various bundling scenarios are explained. The following are the CLIs used to install a third party signed add-on on a blade.

1. use "software install clean" for the following bunling scenarios.

AXP host OS
AXP host OS + 3rd party signed add-ons
AXP host OS + cisco signed infrastructure add-ons + 3rd party signed add-ons
2. use "software install add" for the following bundling scenarios.
3rd party signed add-ons
cisco signed infrastructure add-ons + 3rd party signed add-ons

AXP also supports single install mode that enables the user to bundle a AXP host OS with 3rd party add-ons and install them together. The user can either use "software install clean" CLI or helper image to install this bundle on the blade.

Upgrading /Downgrading an application

AXP Installer supports upgrade/downgrade of infrastructure and add-on (both Cisco signed and 3rd party signed) packages. The upgrade mechanism supported by the AXP installer is any-to-any upgrade, so the user can upgrade from any version of the application to any other version. The user must provide a full payload of the newer version of the application. Since AXP supports upgrades based on Application UUID, downgrade is provided using reverse upgrade.

Foundation code base will be responsible for upgrading packages created internally by Cisco. But AXP installer should check if any 3rd party add-on subsystems are dependent on these packages and update their unified link dependencies.

The following CLI is used to upgrade/downgrade an application installed on the blade

1. "software install upgrade" for the following bundles

AXP host OS
3rd party signed add-ons
AXP host OS + 3rd party signed add-ons
AXP host OS + 3rd party signed add-ons + cisco signed infrastructure add-ons

Uninstalling an application

AXP supports uninstallation of an application. If the user uninstalls the application all the resources allocated to the application are released and claimed by AXP host OS.

The following CLI is used to uninstall an application from the blade.

1. "software uninstall" and select the subsystem to be removed from the menu displayed.

Adding authentication to service module sessioning 3.3

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:21:43 GMT

There are two methods to add authentication and both are done on the ISR (router) and are very simple.

1. Create a username and password on the router.

Example:

config t

username brett password 0 pass123

end

copy run start

2. Follow step A or B.

A. config t

aaa new-model

end

copy run start

B*. config t

line 66

end

copy run start

3. Now session into the service module and you will see a request for the username and password.

* Step B relies on knowing ISR and Service module communication line. You can get this information via the following steps.

1. Session into the service module.

2. Exit back to the router by typing Ctl + Shift + 6, then type x

3. Type 'show users'. The data showing Line: tty, Host: incoming is the communication line.

4. You can return to the service module by pressing the <Enter> key.

Admin - Basics 3.3

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:21:03 GMT

Admin - Add-On Packages and Features 2.2

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:20:40 GMT

1. AXP Value-add components

1. AXP Value-add components

a. Netflow collector

No explicit support here, 3rd party can add their own collector

APPLICATIONEXTENSIONPLATFORM:Return To Top

b. Exposing the syslog server to clients on the LAN

Set up Syslog Server (phase II)

AXP runs a syslog server that can receive log messages from remote hosts. To use this functionality, the following needs to be done:

1. Write code that uses syslog to log messages, or able to direct logs to syslog when running the program
2. Direct log messages to remote syslog
3. Setup AXP to run remote syslog server

Write code that uses syslog

C programs

See this online resource for using the syslog API:
http://www.gnu.org/software/libc/manual/html_node/Submitting-Syslog-Messages.html#Submitting-Syslog-Messages

Example of using syslog API:

syslog.c

#include 

int main(int argc, char* argv[]){
   setlogmask (LOG_UPTO (LOG_DEBUG));
   openlog("myapp", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
   syslog(LOG_DEBUG, "This is a debug message\n");
   syslog(LOG_INFO, "This is an info message\n");
}

Java programs

For java programs, developers can use the log4j module, see the following online resource:

Example of using Java log4j API:

Logging.java

import org.apache.log4j.*;

class Logging {
   public static void main(String args[]){
      Logger x = Logger.getLogger("foo");
      x.debug("This is debug message");
      x.info("This is info message");
   }
}

Direct log messages to remote syslog server

C programs

By default, C programs using the syslog API should be directed to the local syslog server. In order to direct log messages from local syslog server to remote syslog server, users need to configure the syslog server config file, usually at /etc/syslog.conf, or /etc/syslog-ng.conf if local syslog server is syslog-ng.

For example, append the following line to the config file to redirect all log messages of facility "local1" and priority "info" and higher to "myblade"

local1.info @myblade

Java programs

Using the log4j, user can configure the syslog behavior by editing the log4j.properties file.

log4j.rootLogger=DEBUG, mySyslog

mySyslog config
log4j.appender.mySyslog.layout=org.apache.log4j.PatternLayout
log4j.appender.mySyslog.layout.ConversionPattern=%p %t %c - %m%n
log4j.appender.mySyslog.SyslogHost=myblade
log4j.appender.mySyslog.Facility=USER
log4j.appender.mySyslog.threshold=INFO

Set up AXP to run the remote syslog server

Use the CLI to enable the remote syslog server

blade# config terminal
(config)# syslog-server

There are CLI to show remote syslog server status

Syslog Server
Status: RUNNING

Also, there are CLIs to configure the number of files for rotation and the file size

blade# config terminal
(config)# syslog-server limit file-rotation 2 file-size 500

The range for file-rotation is from 1 to 40. The range for file-size is from 1 to 1000 (in MB). By default, file-rotation is 10 and file-size is 20.

APPLICATIONEXTENSIONPLATFORM:Return To Top

c. ProSyst OSGI

Overview

The OSGi specification defines how Java applications or components (bundles in OSGi term) can be remotely installed, started, stopped, updated and uninstalled without requiring a reboot and post no impact to the operation of the device.

AXP has chosen and partnered with ProSyst, the leading commercial OSGi software provider, to provide the OSGI framework to the customers.

OSGi support by Cisco is provided via the optional infrastructure add-on package, prosyst_mbs6.pkg, without any license key embedded.

The current supported osgi package is ProSyst Embedded Server mBS6.0 Framework package 6.0.02

If customers choose not to use Cisco provided prosyst_osgi.pkg (i.e. version is not compatible with their product etc.). Customers will purchase the Cisco signed OSGI bundle directly from Prosyst and packaged in their application packages for installation and used as per their requirements.

OSGI add-on package

1. In general, customers who require OSGI support and would like to leverage Cisco prosyst_osgi.pkg, need to purchase the license from ProSyst directly.
2. Application developer needs to place the license key file (domain.crp) in the AXP designated path, /opt (i.e. /opt/domain.crp ), in their project tree. The key file will then be packaged inside the Application add-on package.
3. The startup script for prosys_osgi.pkg will first copy the license key file before it starts up the mBeddedServer.

Access OSGI

AXP provides add-on CLI, connect osgi, to manage the OSGI framework.
o > connect osgi
This command will cross connect to the text console of the Prosyst OSGI framework and allows administration to manage the OSGI framework by means of Prosyst text commands (CLI) from there.
This command is only available when prosys_mbs6.pkg infrastructure add_on package is installed.

Application eXtension Platform Wiki 4.7

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:19:27 GMT

This is the home page for the Application Extension Platform space.

Blade IP Address Configuration 1.5

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:19:09 GMT

Hardware Overview

The network-module circuit board has 2 Network Interfaces.

Internal Interface (eth0)

The first Network Interface is internal between the ISR and the network-module. This connection is used to exchange traffic between the network interface and the ISR. For example, the console connection to the network-module is connected through this interface.

Designation

1. On the ISR side (Cisco IOS), this interface is described as: Service Interface Engine x/0 (where x is the network-module slot the blade was inserted in).
2. On the network-module side (Linux), the same interface is designated as eth0.

External Interface (eth1)

The other one, which is available on most of the network-module is external. It varies between a Fast Ethernet (100Mb/s) or Gigabit (1000Mb/s) and is available through an RJ-45 connector.

Designation

1. On the network-module side (Linux), this interface is designated as eth1.Note: This interface is not visible from the ISR and can only be configured and use on/by the network-module.

Configuring Network-Module internal interface

The first step in configuring the network-module interface is to enter the configuration on the ISR side. The complete configuration consist of:1. Configure the Integrated-Service-Engine interface
2. Configure the route proper route so that packets are relayed from the router to the network-module.

Integrated Service Engine Interface Configuration

To configure the internal interface on the ISR, you first need to get enable access to it.

1. Enter the configuration mode:

Router# config terminal

Router(config)#

2. Enter the interface mode

Router(config)#interface integrated-Service-Engine 1/0

Router(config-if)#

3. Now it is time to enter the IP configuration parameters for the network-module internal interface. Since the primary interface of the network-module does not have a physical connector, it is accessed through an ISR physical interface. One way to configure this is to set the internal interface as an unnumbered interface.

Here is a simple of such a configuration:

interface Integrated-Service-Engine1/0

ip unnumbered FastEthernet0/0

service-module ip address 192.168.1.3 255.255.255.0

service-module ip default-gateway 192.168.1.2

In the previosus configuration example, the ip unnumbered FastEthernet0/0 is used so that we can avoid using an additional IP Address for the Integrated-Service-Engine1/0 interface on the IOS side.

Network-Module Routing Configuration (IOS)

Once the Network-Module interface on the IOS side is configured, the configuration of a route is necessary. A specific route to redirect traffic from the router to the Network-Module internal interface is required.This is achieved by creating a route to a single host (or ip address) specifying the ip address previously assigned through configuration of the Network-Module and using the 255.255.255.255 network mask to redirect to the Network-Module's interface.

First get to the IOS configuration mode:

Router# configure terminal

Router(config)# ip route 192.168.1.3 255.255.255.255 Integrated-Service-Engine1/0

SSH Access to Blade 4.9

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:18:53 GMT

Overview

AXP provides secure shell (SSH) access to the AXP CLI through a default user, sysadmin, that acts like a system administrator. The password for the default system administrator must be configured by the user through the CLI, before SSH access to the AXP CLI. This initial configuration gives users direct SSH access to the AXP CLI and also allows them to perform remote configuration without having to constantly access Cisco IOS and telnet into the service module.

How To

Configure password protection
o For direct SSH access to the AXP CLI, a user must first telnet into the service module and configure the password.
o If "service password-encryption" is enabled, system will encrypt the clear text password entered and saved it in the encrypted format in the configuration file.
o If user prefers to keep clear text password, then "service password-encryption" shall be disabled with no....
o no service password-encryption
o no username sysadmin password [ 0 | APPLICATIONEXTENSIONPLATFORM:7] clear-password-string

Configure SSH server
o SSH access to CLI server opens up the SSH channel to allow remote access to AXP blade. This potentially raises security concern. The following configuration allows user to have more control over SSH service.
o no ip ssh server
+ This command will enable the SSH service (i.e. starts the SSHD daemon). Default SSH service is enabled. When "no ip ssh server" is configured and sshd was running, SSHD is instructed to stop. This will cause AXP to no longer accept new SSH session but will keep existing SSH session alive.
o no ip ssh interface interface
+ This command will explicitly specify which interface SSHD should listen on for incoming connection. If no such statement specified (default), SSHD will listen on all interfaces.
+ In the case that SSHD is configured to listen to specific network interfaces (explicit configuration), an ip address change of one of those interface will not be detected by SSHD causing the inability of SSHD to accept connection on the modified interface. The workaround for this is to restart SSHD or the blade.
Diagnose SSH server
o show processes
+ Use this command to view the state of the SSHD process
o show processes memory
+ Use this command to display the information of the sshd process when running.

SSH Access to Router 3.9

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:10:47 GMT

Your IOS image on your router must be a k9 image that supports encryption.

ConfigurationRouter> config terminal
Router (config)# hostname <the name of the router>
Router (config)# ip domain-name domainname <a domain that the router services>

At this point, you're ready to enable the SSH server on the router. To enable the SSH server, you must first generate an RSA key pair using the following command:

Router (config)# crypto key generate rsa

Generating an RSA key pair for the router automatically enables SSH. If you delete the RSA key pair, this automatically disables the SSH server.

The last step to implementing SSH is to enable Authentication, Authorization, and Accounting (AAA). When you configure AAA, specify usernames and passwords, the session timeout, and the number of retries allowed during a connection attempt. Use the global commands, as shown below:

Router (config)# aaa new-model
Router (config)# username <username> password <password>
Router (config)# ip ssh time-out <second>
Router (config)# ip ssh authentication-retries <value>

To verify that you've configured SSH and it's running on the router, execute the following command:

Router# show ip ssh

After verifying the configuration, you're ready to force the users that you added during the AAA configuration to use SSH instead of Telnet. You can do so by requiring SSH for virtual terminal (vty) connections.
Here's an example:

Router (config)# line vty 0 4
Router (config-line)# transport input SSH

Routing packets to Blade 5.1

Marjie Ennis Floyd — Tue, 25 Sep 2012 09:10:29 GMT

Network-Module Routing Configuration (IOS)

This is achieved by creating a route to a single host (or ip address) specifying the ip address previously assigned through configuration of the Network-Module and using the 255.255.255.255 network mask to redirect to the Network-Module's interface.

First get to the IOS configuration mode:

Router# configure terminal Router(config)# ip route 10.10.3.188 255.255.255.255 Integrated-Service-Engine1/0

Router# end

Access to the Network-Module's console

After the configuration of the Network-Module's interface and route is completed, we should be able to connect to the console of the Network-Module by typing

Router# service-module integrated-Service-Engine 1/0 session

se-192-168-1-3>

Blade Installation 1.9

Marjie Ennis Floyd — Tue, 25 Sep 2012 03:58:05 GMT

Hardware description

The network-module is placed in a compatible Cisco ISR chassis. The Cisco ISR provides power, network connectivity and software interfaces to it. The network-module is a self-contained computer which can host 3rd party application.

Different type of network-module are available for different performance need.

Cisco ISR compatibility

The network-modules are compatible with certain Cisco ISRs. Cisco ISR also require to be loaded with the right Cisco IOS to recognize and enable the network-module.

Network-Module vs Cisco ISR
Network-Module Hardware Description Cisco ISR Cisco IOS Version External Interface
AIM-APPRE-102-K9 CPU: 300Mhz, Mem: 256MB, Flash: 1GB Cisco 1841 only 12.4(15)T No
NME-APPRE-302-K9 CPU: 1.0Ghz, Mem: 512MB, HDD: 80GB All Cisco ISRs 12.4(15)T Yes
NME-APPRE-522-K9 CPU: 1.4Ghz, Mem: 2048GB, HDD: 160GB Cisco 3800 12.4(15)T Yes

Physical Installation of Network-Module

Note to writer: This section assumes that the ISR is already installed, is console available, has power and network connectivity

The network module need to first be installed in the ISR. The network-module is not a hot-swappable card; the ISR first needs to be powered off prior to insert the blade.

Follow the following steps to physically install the network-module inside the Cisco ISR.

1. Power off the Cisco ISR
2. Remove the a network-module face plate by unscrewing the 2 Phillips head bolts
3. Grab the netork-module by its handle, slide in the module in the ISR
4. Secure the network-module by tightening the 2 screws from the Network-Module face-plate to the ISR
5. Power the Cisco ISR back

After the Cisco ISR power is restored, monitor its boot process through the console. After the ISR boot sequence completes, verify that the "EN" led on the Network-Module is lit up.

Wiki Home 1.1

David Nguyen — Thu, 16 Sep 2010 22:08:08 GMT

This is the home page for the Application Extension Platform space. Use links on the left to display content

Development - Overview 1.0

Matthew J Denapoli — Fri, 06 Aug 2010 18:32:41 GMT

1. Initial development setup

InitialDevelopmentSetup?

2. Developer Linux box requirements

DeveloperLinuxBoxHWRequirement?

3. Developer overview

a. High level overview of architecture. How applications are built and installed.

AXP operating system hosting environment consists of a Linux-Vserver built on top of Cisco's Linux operating system. It is a container based environment in which each application will receive a separate Vserver container called Virtual Instance (VI). The execution of an application is limited within its container. This method prevents 3rd-party software from interfering with the host operating system or other application running on the system. The vserver architecture utilizes a single kernel to be shared by all the VI, developers should make sure that its application is compatible with the linux kernel provided by AXP.

Here are some basic features of AXP:

Prevents 3rd-party software from interfering with the host operating system.
Creates virtual instances for application separation.
Managed through the host operating system instead of the CLI.
Reduced troubleshooting times
Container based virtualization
Broad based CPU support, good resource usage, single Linux kernel support (x86 support for AXP future releases to support additional platforms).
3rd-Party software cannot install kernel modules or device drivers.
Efficient use of resources (kernel level isolation).
Process level security.
Processes utilize shared resources (no hard partitioning).
Multiple 3rd-Party applications running simultaneously on a single AXP blade.
Supports start, stop, and control for individual applications.
Complete isolation ensures discrete health state.
Each application runs a separate Vserver container called a Virtual Instance (VI) or Application Instance.

How to install a third party application - Overview

Third party developers will develop their application on their own linux environment. When the application is ready to be installed onto the blade, 3rd Party developers will need to obtain a development authorization from Cisco in order for their application to be installable onto AXP. The development authorization will only need to be requested once, and can be used on other applications that the 3rd party wishes to install. Cisco will provide a packaging tool that will do all the necessary work to package a 3rd party application (i.e. bundling, adding authorization ..etc) into a AXP acceptable format. The developers can then execute a command on the blade to ftp the package onto the blade and have it installed.

After an application is installed, its status and health can be monitored using AXP commands. Each application will be running in its own vserver container, and each vserver will have its own shell. Developers can use this shell to manually start their application, or they can use a start up script to start the application automatically after installation completes. AXP also provides commands to stop and/or remove the installed packages when needed.

APPLICATIONEXTENSIONPLATFORM:Return To Top

b. VServer overview

What is AXP virtualization used for?

1. Security Isolation between applications and between application and host: Application software will not be able to cause a crash on the host or other application. Also if one vserver is compromised by hacker, the host will be less affected.
2. Linux library independence: When porting software to run on AXP, applcation may have dependency on certain linux libraries that are not compatible with the library provided by AXP. In these circumstances, application can load up it's own guestOS environment. Decoupling the 3rd party application from the AXP guestOS environment.
3. Resource isolation: Each application is given it's own set of CPU, Memory and Disk resource limits. application running in a Virtual environment cannot use more resource than that allocated to it. This improves application stability when running in a multiple 3rd party application environment.

Description of Vserver technology

Container based technology, making use of change root barrier and attaching security context to processes.
Virtualization of user level processes. One signle linux kernel is used throughout the system. Which has low virtualization memory and scheduling overhead. This provides near native OS performance.
When application software is installed under a certain directory, e.g. /home/app1. Application processes started under the context of this directory, /home/app1 becomes the root directory of for these processes. The processes can only access directories below this root; they do not have permission to escape out of /home/app1.
Processes running in a context cannot see processes running in another Vserver context hence provide security isolation.
Devices are not virtualized rather shared amoung vservers. Hence no addition overhead incurred for IO operation.
Networks is not virtualized, only interface hiding is done for vserver context. Network routing tables are not vitualized, however multiple routing tables can be configured under AXP.
The unit of vserver context is described in AXP as a Virtual Instance. This is the unit that can be installed and run under the AXP context. Application software (which can contain multiple processes and functionalities) are packaged into the slim format using the AXP packaging tool. The package is installed into the VI's root directory and run within a VI's context. (Hence a 3rd party slim package cannot run in multiple VIs).
An application running inside a VI is provided a operating environment which is termed guestOS as opposed to the hostOS which manages all the VI in the system.
Application can run as root within the VI context.
To further improve security, the HostOS?'s shell environment is not available only the CLI will be provided to manage the operating environment.
In the VI, the application developer has the choice to enable shell access to within the guestOS.

APPLICATIONEXTENSIONPLATFORM:Return To Top

c. Resource handling overview (disk, CPU applications, etc)

Resource Handling

Provided to segment system resource for a Virtual Instance (VI)
Reduce resource contention within the system, make system behave more predictably and reduce side effects (e.g. one application hogs memory causing another application to fail)
The resources that are managed by AXP are
o CPU
o Memory
o Disk

CPU

CPU resource limit is specified based on a CPU index. This CPU index is an arbitrary number of 10000 assigned to the 1.0 GHz Celeron M CPU used on NME_APPRE_302-K9 application runtime engine.
Other AXP blades CPU performance will be scaled with respect to this CPU.
The CPU index for AIM_APPRE is 3000
A percentage CPU application usage figure can be calculated by application CPU index/platform CPU index.
Certain CPU resource is allocated for the host operating system
o AIM APPRE module approx 8% CPU
o NME APPRE 320 module approx 5% CPU is allocated.

Memory

APPRE as a platform does not make use of disk swapping, the amount of memory available to application is limited by the physical memory found in the system.
The RSS parameter (Resident size) in the kernel is the parameter that gets limited per VI
The default memory allocation behavior for linux is to allow for memory overcommit. Memory overcommit is feature of linux memory management to allow applications that are memory hungry in terms of allocation but relatively lean actual usage to run. The down side of this approach is that application that successfully allocated memory can still fail in run time. This memory overcommit mode however is necessary for application with heavy memory foot print to run.
The "test memory" CLI allows this memory overcommit behavior to be changed or turned off. (This CLI is supposed to be hidden so it is best not to document it)
Here is that actual description of the overcommit modes. The Linux kernel supports the following overcommit handling modes:
o 0 - Heuristic overcommit handling. Obvious overcommits of address space are refused. Used for a typical system. It ensures a seriously wild allocation fails while allowing overcommit to reduce swap usage. root is allowed to allocate slighly more memory in this mode. This is the default.
o 1 - Always overcommit. Appropriate for some scientific applications.
o 2 - Don't overcommit. The total address space commit for the system is not permitted to exceed swap + a configurable percentage (default is 50) of physical RAM. Depending on the percentage you use, in most situations this means a process will not be killed while accessing pages but will receive errors on memory allocation as appropriate.

The overcommit policy is set via the sysctl `vm.overcommit_memory'.

The overcommit percentage is set via `vm.overcommit_ratio'.

The current overcommit limit and amount committed are viewable in /proc/meminfo as CommitLimit and Committed_AS respectively.

Gotchas -------

The C language stack growth does an implicit mremap. If you want absolute guarantees and run close to the edge you MUST mmap your stack for the largest size you think you will need. For typical stack usage this does not matter much but it's a corner case if you really really care

In mode 2 the MAP_NORESERVE flag is ignored.

How It Works ------------

The overcommit is based on the following rules

For a file backed map
SHARED or READ-only - 0 cost (the file is the map not swap)
PRIVATE WRITABLE - size of mapping per instance

For an anonymous or /dev/zero map
SHARED - size of mapping
PRIVATE READ-only - 0 cost (but of little use)
PRIVATE WRITABLE - size of mapping per instance

Additional accounting
Pages made writable copies by mmap
shmfs memory drawn from the same pool

Status ------
o We account mmap memory mappings
o We account mprotect changes in commit
o We account mremap changes in size
o We account brk
o We account munmap
o We report the commit status in /proc
o Account and check on fork o Review stack handling/building on exec
o SHMfs accounting
o Implement actual limit enforcement

To Do -----
o Account ptrace pages (this is hard)

When out of memory occurs, the linux kernel employs the oom_kill (out of memory kill) function to figure out a process to kill to maintain system's operation.

In the Vsever context, specify memory limit specifies the maximum memory available for each VI conext. When memory overcomit is enabled, when total memory usage within the VI exceeds that specified by the limit, processes within the VI will get killed.

When specifying memory limit the granularity is in MB.

Disk

Disk space limit, limits the maximum disk space that can be used by the VI.
Specified in MB

Packaging Time Resource Specifications

Since the application developer is the best judge of maximum resource usage by an application. The control is given to the application developer to specify application resource usage during packaging time.
see packaging tool syntax for resource limit specification.

Install Time Resource Management

The APPRE system keep track of resource usage by the HostOS?, and all installed VI's
During installation time when requested resource specified by the package cannot be met, the software will not be allowed to install.

Run time Resource Limit Enforcement

APPRE make use of linux-vserver's resource limit capability to enforce runtime resource limits for CPU, memory and disk.
For CPU limit enforcement the linux-vserver has a token bucket based scheme to schedule CPU time for the entire Virtual Instance (VI).
When a VI has run out of CPU time, based on the token bucket algorithm, the process priority of the VI are set to a lower priority.
The priority scheduler allows CPU usage to be regulated amount the host and VI's. It also elimiate wastage of CPU time when the hostOS or a VI does not make use of it's allocated amount.
For Phase II deliverable, the CPU and disk paremater can be altered through CLI after installation. This provides flexibility to adjust these parameters in the field. However, due to the sensitivity of the out of memory issue, there is no CLI to modify the memory limit.

4. SDK overview

AXP provides Software Development kit (SDK) to the 3rd party Developers for Linux environment. The SDK provides the following types of tools:

Packaging utility tools (Phase 1)
o A packaging tool, pkg_build.sh, is provided to the 3rd party developer to bundle and sign the application package. This tool will require that application vendor has development authorization from Cisco and access to private keys that will be used in signing application.
o A bundling tool, pkg_bundle.sh, is used to compile multiple packages into a single bundle
o Two interfaces will be supported for these tools: command arguments and interactive command line interface
o Refer to SFS section 3.4.8, Packaging Tools, for details and examples (Merwan/John)
Utility tools (phase 2)
o Library Dependency Checker tool, pkg_check.sh, is used checks and verifies the library dependency on a specified package (*.pkg)
+ Note See SFS 3.4.12 to provide more detail and example (Merwan/John)
o Package Info Tool, pkg_info.sh, is used to display package information
o RPM extractor too, rpm_extractor.sh, is used to extract content from a RPM package.
CLI plugin tility tools and APIs
o AXP provides a mechanism for third party applications CLIs to be integrated into the AXP CLI environment.
o A set of tools are provided to third party developers during their development time to validate, process and package the CLI plugin along with their main application
o See SFS section 3.4.2 for more detail and sample (Merwan/John)

Value-added service APIs
o AXP provides various service APIs to allow 3rd parties to programmatically access, manage and augment existing features available within IOS. The SDK includes the necessary libraries, APIs and/or their associated header files for each supported languages. This allows developer be able to compile and/or link their applications in their desktop.
o The implementation of these value-added services are provided via AXP infrastructure add-on packages. During application packaging, the dependency on the associated infrastructure add-on package needs to be specified if that application depends upon that service.
o Both infrastructure add-on package and application package need to be installed for that service to be enabled for the application.
o The following are the list of value-added services provided: (Mostly in phase 2)
+ IOS Service APIs
+ Event Notification APIs
+ Serial device APIs
+ AXP Service APIs
+ SNMP APIs (phase 1)
+ packet service - (phase 1) This one uses standard library (see its section in SFS)
+ refer to SFS for more detail description for reference (Merwan/John)

APPLICATIONEXTENSIONPLATFORM:Return To Top

a. Installing the SDK

AXP SDK, appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version].tar.gz, is provided with compressed tarball in gzip format.

1. Place the tarball in a direcoty.

cp appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:versin].tar.gz /source/workspace/sdk
2. Unzip and untar the package into desired directory
bash> tar xvfz appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version].tar.gz OR
bash> gunzip appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version].tar.gz
bash> tar xvf appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version].tar
3. This will populate appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version] directory
4. cd /source/workspace/sdk/appre-sdk.nme.[APPLICATIONEXTENSIONPLATFORM:version]

APPLICATIONEXTENSIONPLATFORM:Return To Top

b. Directories of the SDK and source tree

AXP SDK provides packaging tools, Service API's include header files as well as libraries/modules, which can be used to build, compile, and link AXP service enabled third party applications. The SDK has the following hierarchical structure:
include Contains header files to C/C++ API
jar Contains JAVA jar files
lib Contains library files used for linkage
perl Contains Perl modules files
python2.3 Contains Python module files
tools Contains packaging and CLI plugin tools

APPLICATIONEXTENSIONPLATFORM:Return To Top

c. Which scripts are provided.

Helper scripts are provided as part of the Software Development Kit and can be found in tools directory.
gen_auth.sh Certification Authorization Tool
This tools will generate Javelin Authorization files (.jvln) and Certification files (.key)
Note::Do NOT show in devloper's Guide. It is internal usage and only available in engineer build.
See SFS 3.4.16 to provide more detail and example (Merwan/John)
pkg_build.sh SLIM Packaging Utility
This tool will generate a installation package for a specific application

Note See SFS 3.4.8 to provide more detail and example (Merwan/John)
pkg_bundle.sh SLIM Bundle Utility
This tool will bundle multiple packages together into one single install package

Note See SFS 3.4.8 to provide more detail and example (Merwan/John)
pkg_check.sh Library Dependency Checker Utility
This tools checks and verifies the library dependency on a specified package (*.pkg)

Note See SFS 3.4.12 to provide more detail and example (Merwan/John)
pkg_info.sh Package Info Utility
Displays package information
rpm_extractor.sh RPM Extractor
This tool extracts content from a RPM package. User can specify directories for storing scripts, dependencies and other files

Note See SFS 3.4.13 to provide more detail and example (Merwan/John)

APPLICATIONEXTENSIONPLATFORM:Return To Top

d. Multiple package support

1. Dependency management
2. Host vs. Guest OS packages

Artem PackageSupport?

APPLICATIONEXTENSIONPLATFORM:Return To Top

e. Development Flow

Overview

There are different ways the developer can approach the application development. There is a variety of criteria that can affect the method the developer will adopt as development flow. Some of those criteria are:

complexity of the application
whether the developer starts the application from scratch or from existing code
software dependencies this application might have (RPMs)

Whether the application is developed from scratch or the developer is required to port an existing application to the network-module, the basic recommended work flow should be similar. Since the workstation is a similar runtime environment to the network-module, the developer can do some minor testing on the workstation if wanted.

Here is a recommended work-flow to build an application:

1. First Time Setup:

Workstation setup:
o SDK installation, workspace preparation, sync repository
o Create an empty application, package it and install on network-module, this is needed to get access to the linux shell in the vserver
Network-module installation and configuration
Export Directory structure from network-module to the workstation using rsync CLI
2. Main development iteration loop:
Add/modify software such as executable and scripts as required to the workstation sync repository
o Only the binary are needed to be placed in the sync directory (not the source code)
o Use the RPM Extraction Tool to extract any RPM your application may require
Import back the changes to the network-module
Test changes
Developer can modify files on the network-module as well, if this is the case, make sure to sync from the network-module to the workstation so that those changes are not lost.
3. Package And Test
Package Application - Make sure to remove unwanted files that might have been exported to the workstation such as temp files.
Run the LDD Checker tool - this will help verify that all libraries required by the application were bundled in the package.
Install packaged Application for testing
Test Application

In the previous development flow, there are some reference to tools. Those tools are either part of the SDK or available at runtime on the network-module (such as rsync CLI).

RPM Extraction Tool

One shortcoming of the Application Runtime Environment is that it does not support the installation of RPMs. The developer might face this issue if its application depends on RPM(s). If this is the case, the developer must bundle the RPM content and its script setup as part of its application.

To help the developer extracting the RPM, the SDK provides a tool to ease this extraction process.

- Note to Writer: There should be a reference here to the section where RPM Extraction Tool is covered in detail.

RSYNC

Another tool provided is the rsync cli (available from the application debug package). This CLI allows the synchronization of the VServer/Application content between the network-module and the workstation workspace repository. This tool was made available to ease the development cycle. This is achieved by bypassing the packaging and installation steps of the application. This way, modification can easily be done on the workstation and be updated to the network-module.

LDD Checker

LDD Checker is an executable that validates if all the libraries have been packages in your application. This is used to validate that the application will have the full set of libraries once installed.

Development - Details 1.0

Matthew J Denapoli — Fri, 06 Aug 2010 17:44:20 GMT

1. Creating a simple application (basic)

In the following sections, we'll go through steps to build a simple package and deploy it to the blade.

Build your application

As mentioned in the requirement section, the 3rd party development should be done on a linux machine and should be compatible with the kernel that AXP provides. Third party development can be done in Java, C/C++, shell scripts, Python, and Perl. Building your application should not be any different than building any other linux application. Just make sure you include all the libraries required when packaging your application.

For this tutorial, we'll use a simple Hello app, which is a simple bash script. We'll show you how to package this app and get it installed onto the blade.

#!/bin/bash echo "Hello...##########################################"

APPLICATIONEXTENSIONPLATFORM:Return To Top

Package the application

Extract the SDK

You'll first need to get the packaging tool:

Locate the sdk package in your "aesop-root/all-images" directory for the "sdk.tar.gz" file. You will see this directory in your workspace root.
Extract the tarball into any directory on your machine "tar -xzf sdk.tar.gz".

Note: if you do not see the tarball under aesop-root, then either your workspace has not been build, or "make install" has not been done to install the image into this directory. Do a "make" and "make install" in the workspace root.

Create a Root Directory

Create a common root directory. This directory will be the root directory from which the packages will be created and then installed onto the AXP platform. Copy all relevent files and links including their directories into the common root directory. The root directory I have created for my app is in /users/home/jescheng/source.

Everything under this directory will appear in the root directory of my vserver with the directory structure intact.

Note: If you're accessing the blade as the host, you'll see your application's root directory in /home/vserver/[APPLICATIONEXTENSIONPLATFORM:AppName]/

Create a Project Directory

Create a project directory for the packaging tool. You'll find your resulting package in this directory. The project directory I used for my app is /ws2/jescheng/project/

Packaging information

You'll need to prepare some information before packaging your application. Here is a complete list of information and some description of each. Note that not all of them are required, some are labeled with optional. The information here is provided for completeness (straight from developer guide), you can skip over to the next section if you just want to package with basic options.

Project Directory¿Directory that stores generated package files, templates, and temporary files created during packaging.
Development Certificate location ¿X.509 certificate authorized for software development on the platform. Example: "/xyz_source/x509.cer"
Software Development Authorization file location¿Binary file that grants permission to the certificate holder to develop software for the platform. Example: "/xyz_source/dev_auth"
Private Key location¿File containing the RSA key that is used to sign the application vendor software. Example: "/xyz_source/privkey.txt"
Application Name¿Name of the packaged application. Example: "XYZ"
Application Version¿Version of the packaged application. Example: "1.0"
Application Description¿(optional) Description of application functionality. For example:"XYZ Utility"
Application UUID¿(optional) Application unique identifier. It is automatically generated when not specified.
Application Files Location¿Directory that contains application files to be packaged. The directory structure should mirror the desired directory structure on the target file system. Example: "/xyz_source/root_fs"
List of files to be protected¿(optional) Plain text document that contains a list of files (one file per line) that will be checked for tampering before application initialization.
Platform License¿ Specifies modern POSIX regular expression for target platforms where this software is allowed to run. The application is only installed and allowed to run if the target platform matches the specified regular expression.
Package Dependencies¿Select from a list of packages in the SDK and project directories. The user can also specify UUID and filename for a package that exists on the development workstation file system. After each dependency, the user has to specify a dependency type:
o - From [APPLICATIONEXTENSIONPLATFORM:version]¿Dependency must be of the specified or later version.
o - To [APPLICATIONEXTENSIONPLATFORM:version]¿Dependency must be of the specified or earlier version.
o - Exclude [APPLICATIONEXTENSIONPLATFORM:version]¿ Package cannot be installed with other dependencies for the specified version.
o - Only [APPLICATIONEXTENSIONPLATFORM:version]¿Dependency must be of the specified version.
o - None¿Package cannot be installed with the specified dependency.
o - All¿Dependency of any version must be present for the package installation.
Disk Limit (in megabytes) - Set application disk usage limit. Disk usage includes all application binary and data files as well as any diagnostics data generated by the customer when using the application (such as log and core files). Target platform resources must be taken into consideration when selecting a value for this option. Application may fail to install or run if the requested resource is not available on the target platform. Example: 1500Mb
Memory Limit (in megabytes) - Set application RAM usage limit. Target platform resources must be taken into consideration when selecting a value for this option. Application may fail to install or run if requested resource is not available on target platform. Example: 256Mb
CPU Limit (in CPU index points) - Sets the maximum CPU utilization that an application can access. CPU index will be calculated using a benchmark and published for each supported hardware platform. A more powerful platform will have a higher CPU index and will be able to accommodate a higher number of concurrent applications. Target platform resources must be taken into consideration when selecting a value for this option. Application may fail to install or run if enough CPU resources are not available on the target platform. Example: 50Mb
Application capacity¿ Textual description of application capabilities. Example: This string may indicate the call processing rate for voice routing application.
Post-install script ¿(Optional) Specifies the script to run after installation. Example: /bin/postinstall.sh

Run the packaging tool

Look into the sdk directory you just created, under "tools" there should be a script called pkg_build.sh. You can run this script in interactive or non-interactive mode.

Interactive Mode

Following is a sample output when packaging the Hello app, with the interactive mode (redundant output such as description has been removed from the output to reduce size).

[APPLICATIONEXTENSIONPLATFORM:jescheng@jescheng-lnx /ws2/jescheng/sdk/tools]$ pkg_build.sh SLIM Packaging
Utility. (C) 2007 Cisco Systems, Inc Checking dependencies... No command
parameters specified - entering interactive mode. ** project-dir Project
Directory: /ws2/jescheng/project ** dev-cert Development Certificate
File: /vws/vld/devtest-pkg/devcert/dev_certificate.jvln ** dev-auth
Development Authorization File: /vws/vld/devtest-pkg/devcert
/dev_authorization.jvln ** private-key Private Key for Signing Operations:
/vws/vld/devtest-pkg/devcert/private.key ** name Application Name: Hello

- version Version: 1 ** description (optional) Description: echo hello
- uuid (optional) Unique Identifier: Using Default Value: ** source-dir
  Source Directory: /users/jescheng/source ** protect (optional) Protect List
  File: Using Default Value: ** deps (optional) Dependency Subsystem
  Identifier: Using Default Value: ** disk-limit resource limit parameters are
  'min' and 'opt' Enter resource limit parameter: min Minimum Limit: 50M
  resource limit parameters are 'min' and 'opt' Enter resource limit parameter:
  opt Optimal Limit: 50M query_disk_limits min=50M,opt=50M ** memory-limit
  Memory Limit: 50M ** cpu-limit resource limit parameters are 'min' and 'opt'
  Minimum Limit: 1 resource limit parameters are 'min' and 'opt' Enter resource
  limit parameter: opt Optimal Limit: 1 query_cpu_limits min=1,opt=1
- postinstall (optional) Post-install script path: Using Default Value:
  Interactive mode complete.

Non-Interactive Mode

We can do the same work without the interactive mode. The command below will produce the same package.

./pkg_build.sh --project-dir '/ws2/jescheng/project' --dev-cert
'/vws/vld/devtest-pkg/devcert/dev_certificate.jvln' --dev-auth
'/vws/vld/devtest-pkg/devcert/dev_authorization.jvln' --private-key
'/vws/vld/devtest-pkg/devcert/private.key' -name 'Hello'
--version '1' --description 'echo hello' --source-dir
'/users/jescheng/source' --disk-limit 'min=50M,opt=50M' --memory-limit
'50M'--cpu-limit 'min=1,opt=1'

APPLICATIONEXTENSIONPLATFORM:Return To Top

Retrieve Package

After the packaging tool completes, you should find the package in the project directory you specified under "pkg". There should be a .pkg and a .prt1 file. Copy them to your ftp directory.

[APPLICATIONEXTENSIONPLATFORM:jescheng@jescheng-lnx /ws2/jescheng/project/pkg]$ ls Hello.1.pkg
Hello.1.prt1 [APPLICATIONEXTENSIONPLATFORM:jescheng@jescheng-lnx /ws2/jescheng/project/pkg]$cp
Hello.1.* /var/ftp/

APPLICATIONEXTENSIONPLATFORM:Return To Top

Install an Application Package to the Blade

Install the packages using the software install add url url command where url is the ftp location of the package.

se-1-100-50-222.unspecified> $software install add url
ftp://128.107.146.24/Hello.1.pkg WARNING:: This command will install the
necessary software to WARNING:: complete an add-on install. It is
recommended that a backup be done WARNING:: before installing software.
Would you like to continue? [n] y Downloading ftp Hello.1.pkg Bytes
downloaded : 4745 ....

Note: Both .pkg and pkg.prt1 files must be present in the ftp server.

APPLICATIONEXTENSIONPLATFORM:Return To Top

Verify installation

You can verify the state of your application by executing the command:

se-1-100-50-222.unspecified> sh app-service state APPLICATION
STATE HEALTH Hello online

APPLICATIONEXTENSIONPLATFORM:Return To Top

Start your application

There are two ways to start your application: Manually or Automatically.

Please refer to VSEapp.AXP3rdPartyApplicationsDevelopmentFAQ for more information.

2. Application development

a. Handling RPM files

Extracting RPM files with standard rpm, rpm2cpio commands (phase I)

Since rpm is not supported, developers who want to install RPMs as part of their application needs to extract the RPMs in their development environment and integrate it together with the rest of their application.

To extract an RPM to current directoy as if that is root

rpm2cpio /tmp/myapp.rpm | cpio -ivd

Developers can examine any pre/post install/uninstall scripts that the RPM contains

rpm -qp --scripts /tmp/myapp.rpm

Developers can examine any dependencies (libraries, other RPMs) that the RPM requires

rpm -qp -R /tmp/myapp.rpm

Extracting RPM files with RPM extractor tool (phase II)

Given that their development environments have rpm and rpm2cpio supported, there is a tool provided by the SDK to help developers quickly extract all the RPMs into the project source root directory, examine any dependencies the RPMs required, and view any pre/post install/uninstall scripts that the RPMs contains.

This tool is provided as /tools/rpm_extractor.sh inside the SDK package.

Using the RPM extractor tool

Before using this tool, developers should have a project directory created, this directory could be the same directory where packaging tool is run.

workstation# rpm_extractor.sh --proj <Project Directory> [APPLICATIONEXTENSIONPLATFORM:\-\-output]
[APPLICATIONEXTENSIONPLATFORM:\-\-scripts] [APPLICATIONEXTENSIONPLATFORM:\-\-deps] <RPM files>

Required Arguments

--proj <Project Directory>: Designates where the project directory is located. This tool will create a sub-directory structure as under the project directory as follows:

<Project Directory>/ rpm_extractor/ output/ scripts/ deps/

Extracted RPM files will be placed in the output/ directory as if the directory is root directory. Scripts information will be placed in the scripts/ directory, the name of the file will be the RPM filename suffixed with ".scripts". Dependencies information will be placed in the deps/ directory, the name of the file will be the RPM filename suffixed with ".deps". If none of the optional arguments are specified, all three operations will be performed.

<RPM files>: A list of RPM files. This tool can process multiple RPM files at the same time. RPM files will be extracted to the same output directory as that directory is treated as root .

Optional Arguments

--output: Specify the extract operation to be performed
--scripts: Specify the script extract operation to be performed
--deps: Specify the dependency extract operation to be performed
--help: Print a usage page

After RPM extraction

With the RPM extracted (either by using the standard rpm commands, or the rpm extraction tool), and given the scripts and dependencies information known, developers should port the files following the steps below

1. Look at any library and RPM dependencies, gather any new RPM files needed and perform the extraction
2. Examine the extracted RPM files, move them to the project source directory
3. Examine the pre/post install/uninstall scripts, write the appropiate scripts in the project source directory
4. Package the application and install it on the blade

Troubleshooting an application with extracted RPMs

It might not work the first time an application containing RPMs are installed to the blade. Typical problems include:

1. Missing libraries
If there are further libraries missing, try transfer those libraries using ftp into the blade. Developers usually don't need to repackage to test
2. Missing configurations
Sometimes the configuration scripts extracted from the RPMs might not run successfully in the first trial. Developers can access the linux shell of the application and manually invoke the scripts to see if there are any problems.

APPLICATIONEXTENSIONPLATFORM:Return To Top

b. Accessing the shell of the VServer context

Phase I

To access shell in vserver context, application developers can install their application with dependency on the application debug package. This package provides a CLI to access the linux shell within the vserver context. The steps are:

1. Package the application with dependency on the app_debug.pkg
2. After installation of the application with the app_debug.pkg, use this CLI:

blade# app-service system myapp (myapp)# linux shell bash#

Phase II

In addition to the CLI to access linux shell, application debug package provides an SSH server that runs on the vserver context in phase 2.

Vserver SSH server support is provided at two levels:

1. Production Environment

Provides a "tunnel_user" SSH user that does not have shell access upon SSH login. Third party developers have control what this "tunnel_user" can do by writing a startup script that is called upon successful SSH login
2. Debugging Environment
Provides a "tunnel_user" SSH user, same as Production Environment
Provides a "tunnel_root" SSH user that has shell access of the vserver context upon SSH login

This two levels of support is provided through two separate add-on package. Third party application that wants this support must specify either of these add-on packages as dependency upon packaging time.

1. app_ssh.pkg - addon package for Production Environment SSH support
2. app_debug.pkg - addon package for Debugging Environment SSH support

Setup vserver SSH server

Steps to setup a vserver to run SSH server:

1. Package the application with dependency on the application debugging
2. After installation of the application with the app_debug.pkg, make sure that there is an interface binded to the vserver, so that SSH connection can be made into the vserver. If not, follow these steps:

blade# config terminal (config)# app-service system myapp (config-myapp)#
bind ip eth0 (config-myapp)# end

3. Activate the "tunnel_root" user (same applies to "tunnel_user" user) by setting a password

blade# config terminal (config)# app-service system myapp (config-myapp)#
ip ssh uername tunnel_root password hello (config-myapp)# end

4. Enable the vserver SSH server

blade# config terminal (config)# app-service system myapp (config-myapp)#
ip ssh server (config-myapp)# end

5. Users can check that vserver SSH server is running

blade# app-service system myapp (myapp)# show ssh-server Application SSH
Server Status: RUNNING

6. Users can now connect to the vserver SSH server. By default, vserver SSH server port is 2022 (There is a CLI to change the port). For connection using "tunnel_root" as the SSH user, there will be shell access

workstation-shell# ssh tunnel_root@myblade -p 2022 tunnel_root@myblade's
password: vserver-shell#

7. For using the "tunnel_user" as the SSH user, upon successful connection, it will first be greeted by the AXP login message. Then, the startup script third party application provides will be processed. Third party application should provide the script /usr/ssh/home/tunnel_user_app_startup.sh. For example

#!/bin/bash
echo "Welcome Tunnel User!"
echo "Please enter 1 to do a 'pwd', or 2 to do a 'ls'"
read choice
if [APPLICATIONEXTENSIONPLATFORM: $choice -eq 1 ]; then
pwd
else ls
fi

Upon login, this is what "tunnel_user" will encounter

workstation-shell# ssh tunnel_user@myblade -p 2022
tunnel_user@myblade's password:
==Start of message from the Cisco AppRE Application SSH Support==
Tunnel User (tunnel_user) has logged in successfully
Application specific Tunnel User startup script will be
invoked (if exists)
==End of message from the Cisco AppRE Application SSH Support==
Welcome Tunnel User!
Please enter 1 to do a 'pwd', or 2 to do a 'ls'
2
tunnel_user_app_startup.sh tunnel_user_startup.sh
tunnel_user_app_startup.sh.sample
Connection to myblade closed.
workstation-shell#

APPLICATIONEXTENSIONPLATFORM:Return To Top

c. Developing in the VServer

I. Synchronizing them with the developer tree on the linux blade

Eric RsyncHowToUseIt? II. Identifying and gathering the files that have been changed in the VServer
Eric IdentifyingChangedFiles?

APPLICATIONEXTENSIONPLATFORM:Return To Top

d. Extending the CLI

Implementing Plugin CLI

Third party developers will use the CLI Plugin tool provided in the SDK to implement Plugin CLI. The tool is located at /tools/custom_cli of the SDK directory.

In addition, developers will need to achieve the following:

1. implement plugin CLI definitions
2. implement plugin CLI actions
3. Run the plugin CLI tool with the definitions and actions
4. Make changes in the third party main application to start the plugin CLI listener
5. Package and bundle the third party application with dependency on the plugin CLI add-on package
6. Install the bundled application
7. Run the main application, issue the CLI
8. Config CLIs

Plugin CLI definitions

Developers will need to write the plugin CLI definitions as XML format. An example of plugin CLI definition file (please note that the <xml> and <DOCTYPE> header tags must also present)

-bash-3.00$ ls
actions app cli_plugin.config myapp1_cli.xml proj proj_src sdk
-bash-3.00$ cat myapp1_cli.xml

<?xml version='1.0' encoding='UTF-8' ?>

<!DOCTYPE cli_grammar SYSTEM "cli_grammar.dtd" [
<!ENTITY num '[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?'>
<!ENTITY ipaddr '[APPLICATIONEXTENSIONPLATFORM:1\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?[APPLICATIONEXTENSIONPLATFORM:0\-9]?\.[APPLICATIONEXTENSIONPLATFORM:1\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?[APPLICATIONEXTENSIONPLATFORM:0\-9]?\.
[APPLICATIONEXTENSIONPLATFORM:1\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?[APPLICATIONEXTENSIONPLATFORM:0\-9]?\.
[APPLICATIONEXTENSIONPLATFORM:1\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?[APPLICATIONEXTENSIONPLATFORM:0\-9]?'>
<!ENTITY portNum '[APPLICATIONEXTENSIONPLATFORM:1\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]*'>
<!ENTITY login '[APPLICATIONEXTENSIONPLATFORM:a\-zA\-Z]+'>
<!ENTITY password '[APPLICATIONEXTENSIONPLATFORM:a\-zA\-Z0\-9]+'>
<!ENTITY range '[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?'> ]>

<cli_grammar>
<mode>
<pattern type='id'>exec</pattern>
<cmd>
<pattern type='id'>math</pattern>
<help>Math operations with Java actions</help>
<param>
<pattern type='regex'>[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?</pattern>
<pattern type='help'>NUM</pattern>
<help>0-99</help>
</param>
<param>
<pattern type='id'>add</pattern>
<help>Add operation</help>
</param>
<param>
<pattern type='regex'>[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?</pattern>
<pattern type='help'>NUM</pattern>
<help>0-99</help>
</param>
<action paginate="yes" pipehelp="yes">
<class>exec_math.class</class>
</action>
</cmd>
<cmd>
<pattern type='id'>math</pattern>
<help>Math operations with Java actions</help>
<param>
<pattern type='regex'>[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?</pattern>
<pattern type='help'>NUM</pattern>
<help>0-99</help>
</param>
<param>
<pattern type='id'>sub</pattern>
<help>Subtract operation</help>
</param>
<param>
<pattern type='regex'>[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?</pattern>
<pattern type='help'>NUM</pattern>
<help>0-99</help>
</param>
<action paginate="yes" pipehelp="yes">
<class>exec_math.class</class>
</action>
</cmd>
</mode>
<mode>
<pattern type='id'>config</pattern>
<cmd>
<pattern type='id'>store</pattern>
<help>Store a value</help>
<param>
<pattern type='id'>key_1</pattern>
<help>Key 1</help>
</param>
<param>
<pattern type='regex'>[APPLICATIONEXTENSIONPLATFORM:0\-9][APPLICATIONEXTENSIONPLATFORM:0\-9]?</pattern>
<pattern type='help'>NUM</pattern>
<help>0-99</help>
</param>
<action>
<class>conf_store.class</class>
</action>
</cmd>
</mode>
</cli_grammar>

This will plugin 2 CLIs to the CLI console, one config CLI, another exec CLI:

exec CLI: math <num> [ add | APPLICATIONEXTENSIONPLATFORM:sub ] <num>
config CLI: store key_1 <num>

Plugin CLI actions

Developers should then implement the action classes referenced in the CLI definitions. For example, implementing "exec_math.java":

exec_math.java

import java.lang.Integer;

public class exec_math{
   public static String[] eval(String tokens[], String grammar[]){
      System.out.println("exec_math.eval: called");      
      /*
      math_j  add 
      math_j  sub 
      */
      int num1 = Integer.parseInt(tokens[1]);
      int num2 = Integer.parseInt(tokens[3]);
      String operation = grammar[2];
      int result = 0;
      if (operation.equals("add")){
         result = num1 + num2;
      } else {
         result = num1 - num2;
      }
      
      String retStrArray[] = new String[2];
      retStrArray[0] = "0";
      retStrArray[1] = "exec_math.eval: answer is " + result + ".";
      return retStrArray;
   }
}

An example Makefile to compile these action classes:

JAVAC = javac
default: bundle
bundle: compile
mv *.class actions/
compile: action_dir
$(JAVAC) exec_math.java conf_store.java
action_dir:
mkdir actions
clean:
@rm -rf *~ actions

The following is an example how developers compile the actions

-bash-3.00$ ls
actions app cli_plugin.config myapp1_cli.xml proj proj_src sdk
-bash-3.00$ cd actions/
-bash-3.00$ ls
conf_store.java exec_math.java Makefile
-bash-3.00$ make
mkdir actions
javac exec_math.java conf_store.java
mv *.class actions/
-bash-3.00$ cd actions/
-bash-3.00$ ls
conf_store.class exec_math.class

Running the CLI Plugin tool

After defining the CLI definitions and implementing the CLI actions, developers should now use the CLI Plugin tool to package the CLIs into the project source directory. They need to copy the CLI definitions and CLI actions into the appropiate directories, as well as edit the cli_plugin.config file with the correct values

bash-3.00$ cd ../../sdk/tools/custom_cli/
bash-3.00$ ls
actions cli_plugin.config definitions
cli_grammar.dtd cli_plugin.py internal
bash-3.00$ cp ../../../actions/actions/* actions/
bash-3.00$ cp ../../../myapp1_cli.xml definitions/
bash-3.00$ cat cli_plugin.config
file=myapp1_cli.xml
javapath=/usr/java/java/bin
vm=myapp1
proj_src=/tmp/proj_src
bash-3.00$ python cli_plugin.py
cli_plugin.py ran successfully, please check the packages at output/
package has been bundled into the project source directory at
/tmp/proj_src

Developers may verify that certain directories (e.g. cli_comm) are created in the project source directory

-bash-3.00$ cd /tmp/proj_src/
-bash-3.00$ ls
cli_comm etc usr

Start the plugin CLI listener in the main application

Developers should make changes in their main application to start the CLI listener. This CLI listener will listen for CLIs from the host CLI server, and dispatch them to the appropiate CLI actions. The following example illustrate how to start the CLI listener in the main application

MyApp1Main.java

package com.myApp1;

import com.cisco.aesop.apphosting.cli_distribution.CLIDistributionVM;

public class MyApp1Main {

   public static void main(String[] args) {
      System.out.println("MyApp1Main.main: called");
      CLIDistributionVM.startCLIDistributionVMThread("myapp1");
      
      int num = 0;
      System.out.println("MyApp1Main.main: entering loop");
      while(true){
         System.out.println("MyApp1Main.main: " + num++);
         try {
            Thread.sleep(10 * 1000);
         } catch (InterruptedException e) {
            System.out.println("MyApp1Main.main: done");
            System.exit(1);
         }
      }   
   }
}

A example Makefile to compile the main application. Notice that the main application now needs "cli_distribution_vm.jar" to compile. This jar file is found in the SDK, under sdk/jar/cli_distribution_vm.jar

JAVAC = javac

default: build_app

build_app:
mkdir classes/
$(JAVAC) -classpath cli_distribution_vm.jar com/myApp1/MyApp1Main.java
-d classes
mkdir jar/
jar cf jar/myApp1.jar -C classes/ com/

clean:
@rm -rf classes/ jar/ *~

Make sure that the third party application is included in the project source directory

-bash-3.00$ cd /tmp/proj_src/
-bash-3.00$ ls
app_bin cli_comm etc usr
-bash-3.00$ ls app_bin/
myApp1.jar

Packaging and bundling application with dependency on plugin CLI add-on

Finally, developers should use the packaging and bundling tool to package and bundle the application with dependency on the plugin CLI add-on package. For more information, please refer to the SDK packaging and bundling section.

Developers first make sure that under the project directory, a pkg/ directory is created, and it contains the plugin CLI add-on package

bash-3.00$ cd /tmp/proj/pkg/
bash-3.00$ ls
cli_plugin.0.0.2.45.prt1 cli_plugin.pkg

Then, developers can run the packaging tool. Notice it contains a dependency on the plugin CLI SSID

/tmp/sdk/tools/pkg_build.sh --project-dir '/tmp/proj' --dev-cert
'/tmp/devcert/dev_certificate.jvln'
--dev-auth '/tmp/devcert/dev_authorization.jvln' --private-key
'/tmp/devcert/private.key'
--name 'myapp1' --version '45.5' --source-dir '/tmp/proj_src' --deps
'b4b0ee92-cf8e-472b-8434-e8e7412ec71a,all'
--disk-limit 'min=5000M,opt=6000M' --memory-limit '128M' --cpu-limit
'min=4000,opt=5000'

Then, developers can run the bundling tool to bundle the third party application and the plugin CLI add-on together

/tmp/sdk/tools/pkg_bundle.sh --project-dir '/tmp/proj'
--private-key '/tmp/devcert/private.key'
--output 'myapp1_cli.pkg' '/tmp/proj/pkg/cli_plugin.pkg'
'/tmp/proj/pkg/myapp1.45.5.pkg'

The project pkg directory now contains the bundled application

-bash-3.00$ cd ../proj/pkg/
-bash-3.00$ ls
cli_plugin.0.0.2.45.prt1 myapp1.45.5.pkg myapp1_cli.pkg
cli_plugin.pkg myapp1.45.5.prt1 myapp1_cli.prt1

Install the bundled application

Developers can try install this package via the CLI:

se-1-100-50-147.unspecified> software install add url ftp://myworstation
/pub/apps/myapp1_cli.pkg ...

Run the main application, issue the CLIs

During installation, the blade should reboot. After rebooted, make sure that the third party main application, which runs the CLI listener, is started. The following startup command (run in the third party application vserver context) in Java serves as example of what library files and path are needed with starting the CLI listener in the main application

-bash-2.05b# cd app/
-bash-2.05b# ls
myApp1.jar
-bash-2.05b# java -cp ./myApp1.jar:/usr/lib/java/localsocket.jar:/usr/lib
/java/cli_distribution_vm.jar:/cli_comm com.myApp1.MyApp1Main

On the CLI console, the new CLIs should be available

se-1-100-50-147.unspecified> app-service custom myapp1
se-1-100-50-147.unspecified(exec-appservice-myapp1)> ?

end Leave app-service exec mode
math Math operations with Java actions
no Negate the command
se-1-100-50-147.unspecified(exec-appservice-myapp1)>
se-1-100-50-147.unspecified(exec-appservice-myapp1)> end
se-1-100-50-147.unspecified> config terminal
Enter configuration commands, one per line. End with CNTL/Z.
se-1-100-50-147.unspecified(config)> app-service custom myapp1
se-1-100-50-147.unspecified(config-appservice-myapp1)> ?

end Leave app-service config mode
no Negate the command
store Store a value
se-1-100-50-147.unspecified(config-appservice-myapp1)>

When user invoke the CLI, they should see the response from the CLI action:

se-1-100-50-147.unspecified> app-service custom myapp1
se-1-100-50-147.unspecified(exec-appservice-myapp1)> math 12 add 34
exec_math.eval: answer is 46.
se-1-100-50-147.unspecified(exec-appservice-myapp1)>

Config CLIs

Configuration CLIs are CLIs that can be persistently stored in the blade's flash memory. In the above example, "store key_1 <num>" is a config CLI. Executing config CLIs is similar to that of exec CLIs

se-1-100-50-147.unspecified> config terminal
Enter configuration commands, one per line. End with CNTL/Z.
se-1-100-50-147.unspecified(config)> app-service custom myapp1
se-1-100-50-147.unspecified(config-appservice-myapp1)> store key_1 34
se-1-100-50-147.unspecified(config-appservice-myapp1)>

Issuing a config CLI will not display the response, but it nevertheless will invoke the CLI action. Also, this CLI can be seen by doing "show run" in the app-service. User can do "write memory" to write this CLI to flash.

se-1-100-50-147.unspecified> app-service system myapp1
se-1-100-50-147.unspecified(exec-appservice)> show run
Generating running configuration:

app-service system myapp1
hostname se-1-100-50-147.unspecified
shutdown
status-monitor interval_threshold 12 recovery_threshold 5
exit
app-service custom myapp1
store key_1 34
end
se-1-100-50-147.unspecified(exec-appservice)>

The way to retrieve the config CLI the next time the blade is rebooted, or the application is resetted, is by using the application status notifier. Application status notifier is a command to signal the application health state (more info can be found in the "Health Monitor" section). Anytime the application status monitor is invoked to set the application to "ALIVE" state will triggered all the plugin config CLIs to be sent over to the CLI actions.

-bash-2.05b# /bin/app_status_notifier myapp1 ALIVE

APPLICATIONEXTENSIONPLATFORM:Return To Top

e. Health monitor

Checking and Changing Application Health

There is a CLI to display the health of application:

blade# appservice system
(myapp)# show state
APPLICATION STATE HEALTH
myapp online —

The column marks "HEALTH" indicates the current application health state.

There are 4 HEALTH states:

1. "---" default health state when application is reset or shutdown
2. "INITIALIZING" indicates application is starting up
3. "ALIVE" indicates application is up and running
4. "DOWN" indicates application is down

This application health state should be changed by application itself. For example, application can change it from "INITIALIZING" to "ALIVE" when it knows that all the initializing is done.

Application can use the command /bin/app_status_notifier to change the health state:

vserver-shell# /bin/app_status_notifier myapp ALIVE

Application Status Monitoring

Watchdog scripts

If the application state is "online" and application health is not "DOWN", the application will be monitored by the application status monitor.

Application needs to provide one or more health check script(s)/executable(s) and bundled in their package, if it wants to leverage this application status monitor functionality. The number of scripts/executables is application dependent. Shell scripts and c executables are supported.
Each application has its own way to determine whether the application is running or not. The logic of health check scripts/executables is application dependent. For example, it can be based on Process Identifier (PID), or some response to an application "ping".
The watchdog script(s) need to be placed in the predefined directory, /opt/app_status_monitor/watchdogs/ in the application vserver directory, and needs to be executable. All watchdog scripts inside that directory will be invoked, and if application developer wants to ensure correct ordering for script invocation, they can follow the template watchdog script format, which is W**.sh, where ** is a two digit number. The template script is named W00template.sh and is provided for every vserver.
Application status monitor has a heartbeat of 5 seconds, this is the minimum interval application status monitor performs any monitoring. Given a monitor interval of 12, the monitor will perform monitoring on each vserver every 12 heartbeat intervals (i.e. 1 minute). There is a CLI to configure this monitor interval. For example, specifying a value of "3" for this vserver means that application status monitor will wait for every 3 heartbeat to monitoring this vserver.
The script(s) or executable(s) need to return the status code. A zero (0) status code indicates the application is healthy and alive. A non-zero status code indicates to the monitoring system, the application is not functional (i.e. crashed etc.). Example of a watchdog script:

#!/bin/bash
if [APPLICATIONEXTENSIONPLATFORM: -e /var/run/myapp.pid ]; then
exit 0
else
exit 1
fi

When any one watchdog returns a non-zero status code, information of this failed watchdog will be logged, such as name of watchdog, return status, and the time of failure. There is a recovery counter that counts how many times failure occurs, and it works like a delay in taking any actions. A recovery counter of 3 means that the application monitor has run the monitoring for 3 iterations and was either getting non zero return status, or the watchdog has been running for over 3 monitor interval and is not returning. There is a configurable recovery threshold that decides how many recovery counter before taking the next action. When the recovery threshold is reached vserver will be restarted.
After vserver restarted, application status monitor shall continue to run, and the steps described above will be repeated. There is no limit on how many times the vserver restarts.

CLIs and configurations

There are CLIs to show the status monitor, as well as configure the monitor interval and recovery threshold.

1. Show status monitor

blade# appservice system myapp
(myapp)# show status
Application: myapp1
Monitor status: PASSED
Monitor in progress: No
Last executed watchdog: W01myapp1_test.sh
Last executed date: Tue Jul 10 10:22:06 PDT 2007
Last failed watchdog: W01myapp1_test.sh
Last failed return code: 4
Last failed date: Mon Jul 9 12:34:18 PDT 2007
Last restarted date: Mon Jul 9 12:33:32 PDT 2007
Recovery threshold: 6
Monitor interval: 2

2. Change the monitor interval and recovery threshold

blade# config terminal
(config)# appservice system myapp
(config-myapp)# status-monitor monitor_interval 24
recovery_threshold 10
(config-myapp)# end

In addition, third party developers can provide a default configurations via a config file packaged together with the third party application. This file name and path is /opt/app_status_monitor/config/config, and it should look like this:

monitor_interval 50
recovery_threshold 10

The two configuration values "monitor_interval" and "recovery_threshold", followed by a space, and then a number ranges from 1 to 99. Both must be present.

The CLI configuration values takes precedence over the config file values, since the config file only serves as a default at application is installed.

APPLICATIONEXTENSIONPLATFORM:Return To Top

f. SSH tunneling

Given that AXP supports vserver SSH connection, AXP also supports third party developers to utilize SSH tunnelling to enhance their applications. Third party developers can run applications such as X services that are tunnelled through SSH. In addition, developers and application administrators can use the SSH tunnelling to debug their own applications and vserver environment. Given that user can login to the vserver SSH server, we support two SSH tunnelling options

1. "ssh -L" - Port Forwarding
2. "ssh -X" - X11 Forwarding

Detail explanation on these two options are best found on the manual pages for SSH. The link below provides one example of online resources:

http://www.die.net/doc/linux/man/man1/ssh.1.html

Port Forwarding

One example to connect with "-L" port forwarding option:

workstation-shell# ssh -L :: @ -p
workstation-shell# ssh -L 7777:localhost:8888 tunnel_root@myblade -p 2022

X11 Forwarding

One example to connect with "-X" X11 forwarding option:

workstation-shell# ssh -X @ -p
workstation-shell# ssh -X tunnel_root@myblade -p 2022
vserver-shell# xterm &

APPLICATIONEXTENSIONPLATFORM:Return To Top

g. Utilizing the Promiscuous packet API

NAM - Network Analysis Module

Overview

Currently Cisco IOS enables a configuration to duplicate packets for network analysis when it detects the presence of the network analysis module (NAM) or intrusion detection module (IDS). Cisco IOS is notified through a card type cookie which consists of the product ID and a controller ID. The Cisco ISR service module cookie is similarly programmed to contain the same controller ID as a NAM to enable the Cisco IOS packet analysis CLI to be turned on for the service module.

How to configure NAM

Under the interface you would like to monitor traffic, configure analysis-module monitoring. Both incoming and outgoing traffic are monitored.

For example:

interface GigabitEthernet0/0
description $ETH-LAN$$ETH-SW-LAUNCH$$INTF-INFO-GE 0/0$
ip address 1.100.50.221 255.255.255.0
duplex auto
speed auto
analysis-module monitoring
no keepalive
end

Advantages of NAM

Easy to configure
Lightweight Export.
Exports BOTH inbound/outbound traffic on the configured interface
Exports locally generated packets (router generated) (i.e. ping reply from the ISR)

Limitations of NAM

No ACL support
No Sampling rate support
Can only export to an attached NAM or IDS module. (sufficient for AXP).

RITE - Router IP Traffic Export

Overview

RITE is a lightweight mechanism for duplicating and exporting monitored traffic on an interface to an analysis module. The analysis module need not be attached to the ISR (unlike NAM), they can be connected over a physical interface with different encapsulations such as Ethernet, PPP, and many more. The Integrated-Service-Engine interface used by the AXP service module behaves like an Ethernet interface and is therefore a supported export interface for RITE.

RITE provides a more granular traffic capture over NAM. One can specify ACL, sampling rate, and also the direction of the capture to export more specific traffic on an interface. There is however one limitation on RITE; router generated traffic will not be captured by RITE. Router generated packets are process switched and not cef switched, and is not along the capture path of RITE.

How to configure RITE

The high level steps to configure RITE are:

1. Create a RITE capture profile
2. Configure the parameters of the profile
3. Apply the profile on the interface one wishes to monitor

Create a RITE capture profile

Create a profile with ip traffic-export profile [APPLICATIONEXTENSIONPLATFORM:any name]

Configure the interface you wish to export to. This should be interface Integrated-Service-Engine 1/0.

Configure the mac-address of the Integrated-Service-Engine1/0 interface with the mac-address [APPLICATIONEXTENSIONPLATFORM:address] command.

One can optionally configure bidirectional if one wishes to capture both inbound and outbound traffic. Inbound only capture is default.

A Note on the mac-address: Conceptually, the mac-address should be the valid mac-address of the service module. However, since the service-module is configured with promiscuous mode, invalid mac-address will also work. There is however still a problem since the service module is set to route packets by default, configuring a valid mac-address will actually cause the routing stack of the service-module to route the traffic which is not a desired behavior (this will cause duplicated packets to be routed). So to eliminate this problem, it is recommended that you configure an invalid mac-address (something other than the mac-address of the service-module - such as a.a.a), this way your traffic will reach the service module but will not be routed.

Example:

jc1(config)#ip traffic-export profile rite-bi
jc1(conf-rite)#?
IP traffic export profile configuration commands
bidirectional Enable bidirectional traffic export
exit Exit from ip traffic export profile sub mode
incoming Configure incoming IP traffic export
interface Specify outgoing interface for exporting traffic
mac-address Specify ethernet address of destination host
no Negate or set default values of a command
outgoing Configure outgoing IP traffic export

ip traffic-export profile rite-bi
interface Integrated-Service-Engine1/0
bidirectional
mac-address a.a.a
!

Configure RITE export parameters

One can configure incoming or outgoing parameters by entering each menu. You can apply a regular access-list, or configure the sample rate of the export traffic.

Example:

jc1(config)#ip traffic-export profile rite-bi
jc1(conf-rite)#incoming ?
access-list Apply standard or extended access lists to exported traffic
sample Enable sampling of exported traffic

ip traffic-export profile rite-bi
interface Integrated-Service-Engine1/0
bidirectional
incoming access-list 4
outgoing access-list 4
mac-address a.a.a
incoming sample one-in-every 2
outgoing sample one-in-every 2
!

Apply the profile to an interface

Configure ip traffic-export apply [APPLICATIONEXTENSIONPLATFORM:profile name] on the interface you wish to monitor.

Example:

interface GigabitEthernet0/0
description $ETH-LAN$$ETH-SW-LAUNCH$$INTF-INFO-GE 0/0$
ip address 1.100.50.221 255.255.255.0
ip traffic-export apply rite-bi
duplex auto
speed auto
no keepalive
end

Advantages of RITE

Lightweight export
Can capture incoming or bidirectional traffic
Allow user to configure ACL
Allow user to configure sampling rate
Can export to interfaces with different encapsulation types (though for AXP, we're only interested in the Integrated-Service-Engine type).

Limitations of RITE

¿ Due to design of RITE, router generated packets cannot be exported since it does not go through the CEF switching path. (i.e. If someone pings the ISR, the ping reply that the ISR generates will not be exported even if you have bidirectional configured). If capturing this traffic is important for your application, consider using NAM.

How to decide whether to use NAM or RITE for your application

Both packet monitoring features have its pros and cons. The advantages and limitations for each is listed in their respective sections. Here is an attempt to provide some suggestions on which to use for your application:

If your application requires monitoring router-generated packets then use NAM as RITE cannot support this.
If you just want to quickly configure something and get it to work, use NAM.
If you want more granular control on your exported traffic, then RITE would be the choice for you. Keep in mind the above limitation. In general, if you don't care about router-generated packets I would recommend RITE as it provides more feature set.

Note: Both features are allowed to be configured at the same time, however, it is not recommended to do so. Each feature does its own duplication, you will receive two duplicated packets if you configured both of them at the same time.

Packet Capture API support:

Refer to section on NAM and RITE for configuration of packet diversion technology that will capture and divert replicated packets to the AXP blade.

In terms of API support, AXP enables application to capture packet through the use of promiscuous mode thorough the use of raw socket the following kernel configuration have been enabled for packet capturing:
o raw socket interface (CONFIG_RAW) - http://en.wikipedia.org/wiki/Raw_socket
o raw socket memory mapped mode (CONFIG_RAW_MMAP) -
o socket filtering (CONFIG_FILTER).

These features can be accessible directly by 3rd party developer.

AXP also provides the libpcap library as higher level abstraction for packet capture.

libpcap references:
o Libpcap library(http://www.tcpdump.org)
o "man 3 pcap" for further details.
o http://www.cet.nau.edu/~mc8/Socket/Tutorials/section1.html

A cavaet to this is that the linux-vserver technology does not fully virtualize networking interfaces as a result, with raw socket being used, all available network interface created under AXP can be monitored by the an application running inside a vsever container.

Example of using Raw Socket

s = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
struct sockaddr_ll socket_address;
socket_address.sll_family = AF_PACKET;
socket_address.sll_protocol = htons(ETH_P_ALL);
bind(s, (struct sockaddr *) & socket_address, sizeof(socket_address));
recvfrom(s, buffer, ETH_FRAME_LEN, 0, NULL, NULL);

APPLICATIONEXTENSIONPLATFORM:Return To Top

h. Logging support and recommendations

Virtual Instance Logging Support

Syslog is used as the tracing/logging facility for the applications inside the virtual instance (VI).

1. Configure Application Logging Facility

syslog-ng, an improved syslogd daemon, is used for VI logging service.

The syslog file, /var/log/messages.log, is pre-configured by the system.

AXP syslog supports file rotation - rotation of two files is supported.
o messages.log (primary log file)
o messages.log.prev (backup log flie)
o User is able to configure the log file size limit. Once /var/log/messages.log reaches the configured limit, its contents is moved to a backup log file, messages.log.prev. A new /var/log/messages.log file is started.
+ conf t
+ app-service [APPLICATIONEXTENSIONPLATFORM:appname]
+ limit log-file size [APPLICATIONEXTENSIONPLATFORM:MegaBytes] ( default 5MB)

AXP syslog supports syslog levels
o Even though all log levels are support, but CLI reduces configuration to 4 log levels.
+ conf t
+ app-service [APPLICATIONEXTENSIONPLATFORM:appname]
+ log level [error ] (default warning)
+ error - Events with LOG_ERR, LOG_EMERG, LOG_ALERT, and LOG_CRIT are logged.
+ warning - Events with LOG_WARNING, LOG_ERR, LOG_EMERG, LOG_ALERT, LOG_CRIT are logged.
+ notice - Events with LOG_NOTICE, LOG_WARNING, LOG_ERR, LOG_EMERG, LOG_ALERT, LOG_CRIT are logged.
+ info - Events with LOG_INFO, LOG_NOTICE, LOG_WARNING, LOG_ERR, LOG_EMERG, LOG_ALERT, LOG_CRIT are logged

AXP syslog supports remote logging
o Logging support is default to log locally to /var/log/messages.log file.
o User is able to configure the logging to remote syslog server.
+ conf t
+ app-service [APPLICATIONEXTENSIONPLATFORM:appname]
+ log server address [APPLICATIONEXTENSIONPLATFORM:a.b.c.d] (default disabled)

2. Application Logging Usage

Third party applications can use either the C syslog API or Java log4j Syslog Appender for logging. As mentioned, log messages goes to /var/log/messages.log

Syslog for C
o See syslog API

*
o Examples:
+ setlogmask (LOG_UPTO (LOG_DEBUG));
+ openlog("myapp", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
+ syslog(LOG_DEBUG, "myapp_user_management.eval() processing CLI message\n");

Log4j for Java
o See Syslog Appender in the Log4J document
o If an application uses log4j, it might use multiple appenders for the logging. To leverage AXP logging facility (syslog), application need to specify the Syslog Appender to log to syslog.
o SyslogAppender can specify its own log level in the log4j.properties file. The log will first be filtered by the SyslogAppender level configuration. Then, the log will be send to the syslog on the vserver, which will then be filtered by the syslog level configuration (i.e. log level [APPLICATIONEXTENSIONPLATFORM:level] CLI as above). Hence, both level configuration is in effect, and the logs are filtered first by the log4j then by the syslog.
o Currently, if an application chooses to use the AXP syslog mechanism, they can set the log level in its log4j SyslogAppender to be of lowest priority (e.g. DEBUG), then control the filtering through the syslog CLI on AXP.
o In the future release, AXP will provide plugin for application to dynamic change Log4J syslog appender to the log level configured via CLI.
o Examples: log4j.properties to enable Syslog Appender:
+ # Set root logger level to DEBUG and its only appender to A1.
+ log4j.rootLogger=DEBUG, mySyslog
+ # mySyslog config
+ log4j.appender.mySyslog.layout=org.apache.log4j.PatternLayout
+ log4j.appender.mySyslog.layout.ConversionPattern=%p %t %c - %m%n
+ log4j.appender.mySyslog.SyslogHost=localhost
+ log4j.appender.mySyslog.Facility=USER
+ log4j.appender.mySyslog.threshold=INFO
o (new) For any APIs and libraries provided by AXP, logs are redirected to stdout (via System.out.println). If an application that uses these APIs and libraries and wants to redirect such logs to syslog, the application can be executed with its output piped to /bin/logger. Given the example of starting an application that uses CLI Plugin

java -cp ./app_bin/myApp.jar:/cli_comm/:/usr/lib/java
/localsocket.jar:/usr/lib/java/cli_distribution_vm.jar
com.myApp.MyAppMain | /bin/logger -p info

This will redirect stdout of the CLI Plugin (as well as any System.out.println called by the application itself) to the syslog as priority INFO

3. Application Logging Viewing

CLIs are provided to display the contents of all log files under /var/log directory in the Vserver context.
o >app-service [APPLICATIONEXTENSIONPLATFORM:appname]
o exec-appname> show logs
+ Show all the files under /var/log directory
o exec-appname> show log name [APPLICATIONEXTENSIONPLATFORM:log name]
+ show the content of the spcified log file
+ wild card is supported for the file name (i.e. *.log)
+ output modifiers (i.e. paged, containing, tail, |, and less) are supported for easier viewing

APPLICATIONEXTENSIONPLATFORM:Return To Top

i. Creating a application console within the CLI

Overview

A CLI command, connect console , is provided to allow application to create console access in its own vserver instance (Merwan: please use consistent term to name a Vserver through out the document. Whatever term is decided). Application can leverage this capability to

Access the shell inside its own vserver context, or
Launch their own CLI console access, or
Run an application program inside vserver

Usage

1. To leverage this capability, application needs to provide a "console" file which can be a executable or a script. Please see the sample files below.
2. The file needs to be placed under /bin directory in the source files to be packaged. (i.e. /bin/console)
3. After application is installed, execute the connect console command under the application context. This will trigger the execution of /bin/console file.

>app-service sampleApp
exec-sampleApp>connect console

Sample

The following provides some sample /bin/console files for references:

Used to access the shell
o One way is to link the bash program to this file using post-install script or application startup script
+ ln -s /bin/bash /bin/console
o The other way is to have one line in the /bin/console file as follows:
+ #!/bin/bash
+ bash
Used to cross connect to application CLI console
o #!/bin/bash
o telnet 127.0.0.1 34567
Used to run a application program
o build application program as executable and named as console, or
o launch the application program in the console file
o #!/bin/bash
o start_myapp.sh

Linux Shell access via CLI

Another optional packaged CLI command, linux shell , is also provided to allow application to access the guest os shell.

This CLI is bundled in infrastructure add-on package, app_debug.pkg.
After intalling the package, user can go into linux shell by doing the following:
o >app-servcie [APPLICATIONEXTENSIONPLATFORM:appname]
+ linux shell

3. Application debugging

a. Vserver commands

Not Sure what is required here we do not expose Vserver command in GuestOS?. We have provided wrappers in CLI

APPLICATIONEXTENSIONPLATFORM:Return To Top

b. GDB Debugging

Set up GDB Debugging Session

GDB debugging capability is provided through the "gdbserver" and "gdb" commands. The GDB connection is done through the vserver SSH connection. The steps are:

1. Setup a debugging session on the application running in the vserver, using "gdbserver"
2. Make a SSH tunnel connection ("-L" option for port forwarding)
3. Run "gdb" on the workstation and connect to the SSH tunnel

Set up debugging session

There are two ways to setup gdb debugging session

1. Login to vserver SSH server as "tunnel_root" and run "gdbserver" manually. Given that the application name is /my_app/debug

workstation-shell# ssh tunnel_root@myblade -p 2022
tunnel_root@myblade's password:
vserver-shell# gdbserver localhost:2222 /my_app/debug
Process /my_app/debug created; pid = 29165
Listening on port 2222

2. Setup the "tunnel_user" startup script to do runtime "gdbserver" binding, using the application process ID

This requires changing the "tunnel_user" startup script, as example like this (given my application process name is "debug"):

#!/bin/bash
pid=`ps -ef | grep debug | awk '{print $2}'`
echo "gdbserver will be running on process ${pid}, binded to port 2222"
gdbserver localhost:2222 --attach $

Unknown macro: {pid}

Making SSH tunnel connection

Given that port 2222 is binded to the gdbserver on the vserver side, the following command will establish SSH tunnel from the workstation's port 4567 to blade's 2222

workstation-shell# ssh -L 4567:localhost:2222 tunnel_root@myblade -p 2022

Run "gdb" on the workstation and connect to SSH tunnel

Given that port 4567 is binded to the SSH tunnel on the workstation

workstation-shell-2# gdb
(gdb) file debug
(gdb) target remote localhost:4567
(gdb)

After that you can use gdb commands like "break", "continue", "step". Below list one online resource regarding GDB usage: http://www.cucy.net/lacp/archives/000024.html