AXP 1.6 Developer Guide
Application Development
Downloads: This chapterpdf (PDF - 210.0KB) The complete bookPDF (PDF - 9.62MB) | Feedback

Application Development

Table Of Contents

Application Development

Writing the Application

Hello World Application: Example

Application Development Overview

Loopback Interfaces

Creating Scripts for Startup and Softlinking

Cisco AXP on VMware

Cisco AXP Emulation using VMware

VMware System Requirements

Configuring VMware

Network Connectivity

Licensing and Support of VMware

Cisco AXP API Support on VMware

Packet Analysis

RITE Traffic Filtering and Sampling

Packet Monitoring and Analysis

Raw Socket Monitoring

GetRouterIP API: Example

Running the RPM File Extractor Tool

RPM File Extractor Tool Arguments

RPM Troubleshooting


Application Development


This section describes the following processes used in developing applications:

Writing the Application

Application Development Overview

Loopback Interfaces

Creating Scripts for Startup and Softlinking

Cisco AXP on VMware

Packet Analysis

GetRouterIP API: Example

Running the RPM File Extractor Tool

Writing the Application

Writing, Testing, and Packaging an Application

The overall development process:

Write your application along with startup and shutdown scripts in your Linux development environment. After testing your application, copy the application and the relevant scripts, extracted RPM files and any other required files to your build directory. Create a package directory and run the Cisco AXP packaging tool to package your application in the package directory. Install the application package on Cisco AXP.

Certificates

During packaging, there are several steps to be followed. One step is to create a signed certificate for your application. Any application to be installed on Cisco AXP must have a signed certificate, a private key, and a development authorization certificate—which is provided by Cisco. For more information see the "Creating Certificates" section on page 209. Also, consider allowing access to the OS shell of your application and protecting files.

Shell Access and Security

Each application installed onto Cisco AXP has its own virtual instance (also, see the "Cisco Application Extension Platform Overview" section on page 1. Inside the virtual instance, the application has its own shell. Access the guest OS shell to debug, change or view files for your application, or to import other applications and tools. If you allow the user to access the shell, this increases the security risk for your application. Access to the guest OS shell access is described in the "Packaging the Application" section on page 205.

If you decide to allow someone to have shell access to your application environment and if you want to protect some files see the "Creating a File of Protected Files" section on page 208.

If any of these listed files are modified and/or deleted, when the virtual instance for your application next tries to restart, the modifications/deletions are reported and the virtual instance does not start. This prevents your application from running. A message is written to the system log with the name of the modified/deleted file.

Your application should be written and tested in the Linux development environment before attempting to install the application on Cisco AXP.

Cisco AXP is based on Cisco Linux. Libraries are listed in the appendix. You must import all additional code features for your application into Cisco AXP. This code may include: start up and kill scripts, softlinks to these scripts, and any additionally required RPMs.

Code the "health status" within the application so that the show state cli command shows the application's health status.


Note The size of the /tmp directory in the virtual instance is limited to 16MB.


For your application to have console access, you need to either have a post-install script or your application must depend upon debug package axp-app-dev.<platform>.<version>.pkg.
For more details of the post-install script and the debug package, see the "Accessing the Guest Operating System" section on page 17.

Random Number Generation

If an application requires random number generation—use the /dev/urandom device, where urandom stands for an "unlocked" or non-blocking random source. Do not use the /dev/random device. Refer to linux man pages for information on /dev/urandom and /dev/random.

The reason why using a /dev/random device is unsuitable, is explained below:

/dev/random relies on an entropy pool being filled to use as a resource for generating random numbers. The entropy pool is filled by the system grabbing random noise from devices such as video, keyboards, and file I/O. Cisco AXP uses file I/O to fill the entropy pool. There are no video or keyboard hardware connections, so the pool fills slowly.

C Applications

When developing native C/C++ software targeted to run on Cisco AXP, we recommend that you use the following components:

Compiler GCC/G++ 3.4.3

Library glibc: 2.3.5

Library libstdc++: 6.0.3

Fedora 6 C/C++ applications must be linked with one of the two following linker options:

-Xlinker -hash-style=sysv

-Xlinker -hash-style=both

Hello World Application: Example

The following example is a simple "Hello World" application. It consists of a Bash script that reports on its health status every five seconds by writing to a file called fancy_output. This "Hello World" application also exists in the SDK as a walk-through. It is located in the directory:
<axp-sdk>/examples/HelloWorld. A README file explains how to package, install, and run your HelloWorld application.


Step 1 Create a directory in which to save a bash script using the following command:
mkdir /source/helloworldapp

Step 2 Create a script called helloworld.sh containing the following lines of code:

#!/bin/bash
#provide health status
/bin/app_status_notifier helloworld INITIALIZING
# remove old log file 
rm -rf fancy_output
#provide health status
/bin/app_status_notifier helloworld ALIVE
while [ 1 ]; do
	echo "Hello world!" >> fancy_output
	sleep 5
done

Step 3 Save helloworld.sh into directory /source/helloworldapp.

Step 4 (Optional) View the file fancy_output without accessing the guest OS shell. Select one of the following two steps:

Write to the fancy_output file in directory /var/log/. For example:

echo "Hello world!" >> /var/log/fancy_output

Create a softlink from file fancy_output's directory to a file that you will create in directory /var/log/. For example, add the following lines to your postinstall script:

touch /var/log/fancy_output
ln -s /var/log/fancy_output /helloworld/fancy_output

File fancy_output is written to directory /helloworld. Cisco AXP does not allow you to create a softlink from the /var/log directory to your file because this could potentially lead to a security breach.

Step 5 (Optional) View your file from the CLI of the guest OS:

show log name <your file name>


Application Development Overview

The main phases of application development are shown in Figure 14.

Figure 14 Application Development

The steps below explain the stages in the application development flow.


Step 1 Prepare Application Software.

a. Set up the workstation.

Use a PC with a Linux operating system, including software components that closely match the software in the final runtime environment on the application service module. See the "Writing the Application" section.

b. Download the Cisco AXP SDK tar file axp-sdk.<package>.tar.gz from the "Download Software" link in the Support area at: http://www.cisco.com/en/US/products/ps9701/index.html.

Use the same version number for the SDK as the version of Cisco AXP running on the service module.

c. Install the Cisco AXP SDK and prepare the workspace.

Prepare the application software to run in a Linux environment, and keep the directories containing the application software separate from the workstation Linux environment. Isolate the application software in a simulated root directory; for example, /opt/. The software beneath this root directory has the same structure as the application software when it is loaded into the virtual environment on the application service module. The simulated root directory contains all application software and any required libraries. You do not have to include the libraries and system add-on packages in the simulated root directory that are already included in the embedded guest OS.


Note The Linux kernel is upgraded in Cisco AXP 1.5. If your application uses Linux kernel modules developed using an earlier version of Cisco AXP than Cisco AXP 1.5, you must recompile the earlier Linux kernel modules.


Convert an absolute path in each symbolic link to a relative path. The symbolic links should refer exclusively to files underneath the simulated root directory.

Isolate any endpoint specific code such as license installation, site/networking configuration into a postinstall shell script. We recommend that core software is self-contained and does not have any external dependencies.

Step 2 Create the Initial Software Package.

Creating an initial package can be used as the starting point in your development process and the package need not be fully functional at this stage. Creating the initial package helps you to find any missing dependencies and to customize your software before loading the software onto the Cisco AXP service module.

a. Add or change required software in the workstation's sync repository, such as executable files and scripts. The sync repository contains binary files, not source files.

b. Enable access to the Linux shell.

Accessing the Linux shell helps you to debug the application software after the software is loaded onto the Cisco AXP service module. See the "Postinstall Script" section on page 18.

c. Define the dependencies of the application software on any required Cisco add-on packages. See the "Cisco AXP Optional Features" section on page 25.

Step 3 Load Software onto the Service Module.

a. Load the application software onto the Cisco AXP service module. For example, by using the rsync utility, which synchronizes files between two environments.

For further information on rsync, refer to the "Rsync" section on page 249.

b. Confirm that you have access to the Linux shell.

c. Confirm that the virtual environment contains files linked from Cisco add-on packages that are required by the application; for example, CLI plug-ins.

d. Extract any required additional files/scripts for your application using the "RPM File Extraction" section.

Step 4 Application Testing and Development.

a. Upload any missing application components and/or libraries to the service module, using SFTP or rsync.

You can use iterative development on the service module if required. However, you must remember to synchronize the changed software back to the workstation environment during step 5.

b. Integrate the application into the embedded virtual environment. Consider end user interface issues, including application configuration and diagnostics. If you want to extend the CLI on the development service module, use the "CLI Plug-in Distribution Service" section on page 173.

c. Test your application's functionality and stability.

For further information refer to the"Application Development Package" section on page 17.

d. Update and test the application startup script(s) and postinstall script.

Step 5 Update Application Software on the Development Workstation.

Copy back any application software that you have changed on the service module to the development workstation. For example, use the rsync CLI command.

During this copying, try and avoid copying Cisco add-on packages and embedded guest OS components into the application software repository—they already exist on the development workstation. Having duplicated files unnecessarily increases the storage space taken up by the application, which has a negative effect when the application is later deployed on the Cisco application service module.

Step 6 Create Application Software Production Package.

a. On the workstation, create a new package for the application software.

b. Disable access to the Linux shell if it is not required by the user.

c. Identify required dependencies upon Cisco add-on packages and the postinstall script.

d. Delete any unwanted temporary files in preparation for the packaging stage.

e. Run the library dependency checker tool to verify all libraries required by the application are in the package. See the "Library Dependency Checker" section on page 214.

f. Package the application using the packaging tool with a dependency on any required Cisco add-on packages, and (optional) specify the postinstall script.

g. (Optional) Bundle the application package with add-on package(s).

h. Install and test the application package or bundle.

Loopback Interfaces

Network interfaces cannot be virtualized. An application can use a loopback to communicate internally without worrying that an interface is being used by other virtual instances or the host.

Cisco AXP provides a way to virtualize loopback interfaces for each instance.

For example, a virtual interface of the loopback (lo:2, lo:3) and its corresponding address (127.0.0.2, 127.0.0.3) is provided to a virtual instance.

The default loopback (127.0.0.1 and lo) is reserved for the Cisco AXP host loopback interface, and is also accessible in each virtual instance.

The /etc/host file of each virtual instance is populated with the virtualized loopback interface and the Cisco AXP host loopback interface.

For example, if an application is installed on Cisco AXP, the /etc/host file should be similar to the following:

127.0.0.x         localhost.localdomain localhost
127.0.0.1         apprehost

If you issue the command netstat in the virtual instance, this shows that "lo" is associated with "127.0.0.1", and "lo:x" is associated with "127.0.0.x".

x is a number >= 2, depending on the number of virtual instances. This number is dynamically allocated, so applications must not assume that x stays the same.

For example, when a new application is installed, the new application can be assigned x while the original application can be assigned x+1. Applications should instead rely on "localhost" being their own virtualized loopback interface.

127.0.0.1 is assigned to "apprehost" and 127.0.0.x is dynamically assigned to "localhost".


Note The following potential security issue exists: A virtualized loopback interface for one virtual instance can also be accessed by other virtual instances.


Creating Scripts for Startup and Softlinking

The application starts up in one of the following two ways:

Automatic Startup

Manual Startup

Automatic Startup

For automatic startup on bootup of Cisco AXP, create a startup script, normally created in /etc/rc.d/init.d and reference it with a softlink placed in your /etc/rc.d/rc3.d directory. Remember that your startup softlink should be formatted as S<priority><app-name> where S means startup, priority is 0-99, and app-name is the name you want to call your startup script.

Create a kill softlink that references your startup script, and put the script in your /etc/rc.d/rc6.d directory. Recall that your kill softlink should be in the format:

K <priority> <app-name>

where, K means kill, priority is 0-99, and app-name is the name of your startup script.

Package your application with these softlinks and references to the startup script and import them into Cisco AXP.

Manual Startup

For manual startup, first configure your system for shell access. For more information, see the "Accessing the Guest Operating System" section on page 17.

Cisco AXP on VMware

The Cisco AXP platform can run as a virtual appliance under VMware. Running Cisco AXP under VMware is described in the following sections:

Cisco AXP Emulation using VMware

VMware System Requirements

Configuring VMware

Network Connectivity

Licensing and Support of VMware

Cisco AXP API Support on VMware

Cisco AXP Emulation using VMware

To run your application and Cisco AXP infrastructure add-on packages, you can use VMware Player, which runs under multiple x86 operating systems. The virtual appliance package emulates the Cisco AXP application service module NME-APPRE-302-K9 by default, providing two Ethernet ports attached to the same L2 (virtual) network.


Note Emulation of the NME-APPRE-302-K9 service module uses up to a maximum of 10 GB disk space. (The real NME-APPRE-302-K9 service module has up to 80 GB disk space available.)



Note Applications that are packaged to run on a Cisco Application Service Module cannot also be run under VMware. Obtain a separate authorization bundle from Cisco to enable the application package to run on VMware.


Cisco AXP emulation using VMware is explained in the following sections:

VMware System Requirements

Configuring VMware

Network Connectivity

Licensing and Support of VMware

Cisco AXP API Support on VMware


Note To return to the Table of Contents, click here.


VMware System Requirements

To use Cisco AXP with VMware software requires the following hardware:

PC with a CPU of Intel Pentium 4 or above

1 GB memory space

5-10 GB free disk space, depending on the size of the application

Configuring VMware

Prerequisites

Installed VMware player (version 2.0 or higher)

PC with an Intel x86 CPU

One additional IP address—to be assigned to the VMware session

The Cisco AXP VMware environment package axp-k9.vmw.1.5.1.tar.gz contains the VMware configuration and virtual appliance package.

To configure Cisco AXP using VMware, perform the following steps:


Step 1 Download VMware Player or VMware Server software from http://www.vmware.com/.

Step 2 Install VMware Player software.

Step 3 Download and unzip the Cisco AXP VMware environment package into a working directory. Obtain the package axp-k9.vmw.<version>.tar.gz from the "Download Software" link in the Support area at: http://www.cisco.com/en/US/products/ps9701/index.html.

Step 4 Copy the Cisco AXP VMware image files axp-vm.vmx and axp-k9.vmw.<version>.vmdk into the same directory as in step 3.

Step 5 Start VMware software.

Step 6 Open the virtual appliance by using one of the following two methods:

Select File > Open in the same directory as the VMware image files

OR

Run the "vmplayer axp-vm.vmx &" command

Step 7 Select axp-vm.vmx.

The VMware session panel opens.

Step 8 Start the Cisco AXP VMware session by selecting "power on". After the usual power on sequence, a CLI prompt appears, verifying successful log-in. For example:

localhost>

Step 9 Configure a VMware session:

a. Configure the hostname.

b. Configure eth0 interface with a static IP address.

c. Configure the default gateway.

d. Configure the remote router IP address.

Example: In this example, the hostname is JOV.

localhost> config t
localhost(config)> hostname JOV
JOV(config)> interface eth0 
JOV(config-interface)> ip address 128.104.28.7 255.255.255.0
JOV(config-interface)> exit 
JOV(config)> ip route 0.0.0.0 0.0.0.0 128.104.28.1
JOV(config)> router ip address 172.168.24.102
JOV(config)> exit 
JOV> wr mem 
JOV> 

The session for Cisco AXP Emulation using VMware is now complete and you can install add-on packages on the virtual system.

In addition to VGA console access, Cisco AXP server CLI access is possible using SSH.
See the "Secure Shell Access to the Service Module" section in the Cisco AXP User Guide for details.

The virtual appliance package emulates Cisco AXP application service module NME-APPRE-302-K9 by default. The virtual appliance package provides two ethernet ports attached to the same L2 (virtual) network, which is similar to the Cisco AXP application service module (NME) hardware.


Network Connectivity

The virtual appliance is configured to use bridge mode by default. You must obtain an additional
IP address from the network administrator for the host PC, to use the virtual appliance on interface Eth0. You will need an additional IP address if you want to use interface Eth1. DHCP client functionality is not supported, so you must manually configure the IP address of the virtual appliance.

Licensing and Support of VMware

To obtain a license for Cisco AXP Emulation using VMware, contact your Cisco marketing representative to obtain an authorization bundle. Cisco AXP Emulation using VMware is available for evaluation purposes only and is not supported by Cisco Technical Support

Cisco AXP API Support on VMware

To use Cisco AXP APIs on VMware, you must access a Cisco IOS router. The configuration on the Cisco AXP service module must include the IP address of the remote Cisco IOS router.

Use the router ip address ip address command to configure a generic router IP address.

The following Cisco AXP APIs and packages are supported on VMware:

IOS CLI API, page 43

AXP CLI API, page 53

Remote Serial Device, page 31

IOS Event API, page 59

The Promiscuous Packet API is not supported in VMware because there is no direct connection to the Cisco ISR (router). However, operations using packet monitoring and packet capture with pcaplib are available if the packet source is not the Cisco ISR.

Packet Analysis

Traffic Filtering and Packet Analysis for Cisco AXP are explained in the following sections:

RITE Traffic Filtering and Sampling

Packet Monitoring and Analysis

Raw Socket Monitoring

RITE Traffic Filtering and Sampling

Router IP Traffic Export (RITE) is a Cisco IOS software export tool that supports traffic filtering and sampling. For further information on RITE, see the "Configuring Router IP Traffic Export" section on page 328.

Using RITE, the analysis module does not need to be attached to the Cisco router. (This is in contrast to using Raw Socket Monitoring, which requires the analysis module to be attached to the Cisco router.)

There is however a limitation when using RITE: router generated traffic will not be captured by RITE. Router generated packets are process switched and not cef switched.

Packet Monitoring and Analysis

Packet monitoring on a Cisco AXP service module interface is similar to packet monitoring in a Cisco IOS environment.

To enable packet monitoring on a Cisco AXP service module interface, see the "Packet Analysis" section on page 327. (Packet analysis uses the analysis-module monitoring command in interface configuration mode.)

The raw socket can be monitored to measure the inbound and outbound traffic on the configured interface and to export local router-generated packets. Refer to the "Raw Socket Monitoring" section.


Note If there are multiple application service modules installed in the router, packet monitoring takes place on the service module that is first to register.


Raw Socket Monitoring

The kernel is configured with the following directly accessible features:

Raw socket interface (CONFIG_RAW).

Raw socket memory mapped mode (CONFIG_RAW_MMAP).

Socket filtering (CONFIG_FILTER).

The raw socket interface is compatible with the higher level abstraction of libpcap and
MMAP packet access. For more information on libpcap/tcpdump, refer to:

libpcap/tcpdump: http://www.tcpdump.org

manual pages; for example, man 3 pcap

tutorial:

http://yuba.stanford.edu/~casado/pcap/section1.html


Note An application running inside a virtual instance can use a raw socket to monitor all the available network interfaces on the Cisco AXP service module.


Raw Socket: Example

#include <stdio.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <linux/if_ether.h>
#include <linux/if_arp.h>
#include <errno.h>
 
int main (int argc, char* argv[]){ 
  int result = 0; 
  int s = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_ALL));
  if(s != -1){
      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)); 
      char* buffer= (char*)malloc(ETH_FRAME_LEN+1);
      int length=recvfrom(s, buffer, ETH_FRAME_LEN,0,NULL,NULL);
   }
   else{
     printf("Socket creation error %d\n",errno);
     result = s;
   } 
 return result;
}

GetRouterIP API: Example

Use the function GetRouterIP( ) to obtain the IP address of the Cisco IOS router. GetRouterIP( ) is located in library /lib/libipcserviceapi.so.

The following example specifies the include file of ipcServiceAPI.h in the following include statement:

#include <ipcServiceAPI.h>

C
unsigned int GetRouterIP( void);

Obtain the Cisco IOS router's IP address.

Parameters:

None

Returns:

4-byte value for IP address

Example:

#include <stdio.h>
#include <string.h>
#include <ipcServiceAPI.h>

#define maskA 0x000f
#define maskB 0x00f0
#define maskC 0x0f00
#define maskD 0xf000
main () {

	unsigned int ip = GetRouterIP();

	printf("Router ip address=%d.%d.%d.%d\n", 
	(maskA & ip) , ((maskB & ip) >> 8), ((maskC & ip) >> 16),  ((maskD & 
	ip) >> 24 ));
}


Running the RPM File Extractor Tool

The RPM File Extractor Tool extracts all the RPM files into the project source root directory.

From the project source root directory, you can examine any dependencies the RPM files require, and view any preinstall, postinstall, preuninstall, or postuninstall scripts that the RPM files contain.

To use the RPM File Extractor Tool (rpm_extractor), perform the following steps.


Step 1 Create a project directory if you have not done so already. This directory can be the same directory as the directory in which the packaging tool runs.

Step 2 Enter the following command and arguments:

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

For details of the arguments see the "Appendix B: Commands in AXP Reference OS" section on page 258.

The RPM File Extractor File tool creates a sub-directory structure under the <project directory> as shown below.


myprojdirectory/
	rpm_extractor/
		output/
		scripts/
		deps/

Step 3 After the RPM scripts have been extracted (either by using "Standard RPM Utilities" or the "RPM File Extractor Tool"), look at a list of the scripts and the RPM dependencies.


Note Cisco AXP only supports postinstall scripts.


Step 4 Move the files you require to the project source directory.

Step 5 Package your application and install it on the service module.


RPM File Extractor Tool Arguments

The arguments of the RPM file extractor tool are shown in Table 104.

Table 104 RPM File Extractor Tool Arguments

Argument
Optional/
Mandatory
Description

--proj <Project Directory>

Mandatory

Location of project directory. Typically this is the same directory name as used in the packaging tool's project-dir parameter.

--output

Optional

Flag specifying if the output/ directory is created. The output/ directory contains extracted RPM files in the directory designated as the root (/) directory. For example, rpmfile1. Also see Note below.

--scripts

Optional

Flag specifying if the scripts/ directory is created. The scripts/ directory contains scripts. Each script name is the RPM filename suffixed with ".scripts". Also see Note below.

--deps

Optional

Flag specifying if the deps/ directory is created. The directory contains a dependency file for each RPM file; for example, rpmfile1.deps. Each dependency file shows any further files required by this RPM file. Also see Note below.

<RPM files>

Mandatory

List of RPM files to be extracted. The RPM files are extracted to the directory designated as the root directory(/). Use either relative or absolute path names.

--help

Optional

Prints help information for the RPM file extractor tool.



Note If none of the three optional arguments to the RPM file extractor tool are specified, all three subdirectories are created: output/ scripts/ deps/. (The optional arguments are: [--output] [--scripts] [--deps].)


RPM Troubleshooting

If your application contains RPM files, the first time that you install your application onto the service module, you may encounter problems such as missing libraries, or missing configurations.

Missing Libraries

If there are libraries missing, locate the missing RPM libraries and transfer them using ftp to the service module, and retest the application. This avoids having to repackage your application before running it on the service module.

Missing Configuration Scripts

Configuration scripts extracted from RPM files may not run successfully. A simple debugging step is to access the Linux shell of the application and manually invoke the scripts. This step is to replicate the error and more easily find out the configuration script causing the problem.