Table Of Contents
Cisco Application eXtension Platform 1.1 Developer Guide
Cisco Application eXtension Platform Overview
Dedicated Application Resources
Application Packaging Overview
Running Applications on the Guest Operating System
Obtaining Console Access for the Application
Infrastructure Add-on Packages
Development System Requirements
Application Development Overview
CLI Plug-in Utility Tools and APIs
Automatic or Manual Application Startup
Creating a Common Root Directory
Creating a File of Protected Files
Creating a Package Directory for Project
Packaging the Hello World Application: Example
Verifying Your Application is Installed and Running
CLI Plug-in Distribution Service
CLI Plug-in Application Components
Packaging a CLI Plug-in Application
Installing a CLI Plug-in Application
Activating a CLI Plug-in Application
CLI Plug-in Distribution Listener APIs
Interrupting Action Invocation
Simultaneous CLI plug-in Invocation
CLI Plug-in Application: Example
Show Time Application: Example
Troubleshooting Your Application
Bundles Including the Cisco AXP Host OS
Cisco AXP Emulation using VMware
Debugging and Troubleshooting Enhancements
Integrating Log Files into the Host OS
System Performance Status Monitoring
RITE Traffic Filtering and Sampling
Creating an RITE Capture Profile
Configuring the RITE Capture Profile Parameters
Applying the RITE Capture Profile to an Interface
Swap Space and Memory Allocation
Displaying Current Resource Limits
Running the RPM File Extractor Tool
RPM File Extractor Tool Arguments
Appendix A: Porting an Application from Fedora Core 6: Examples
Example 1: Simple C++ Application
Example 2: Porting an Existing Application
Identifying Cisco AXP Package Contents
Bundling Libraries in Your Application
Identifying Libraries to Bundle
Library location and LD_LIBRARY_PATH
Appendix B: Commands in Guest OS
Appendix C: Libraries in Guest OS
Cisco Application eXtension Platform 1.1 Developer Guide
Revised: May 18, 2009, OL-14813-01
The Cisco Application eXtension Platform Developer Guide provides information on how to create, package and install applications on the Cisco Application eXtension Platform (Cisco AXP).
Contents
This guide contains the following sections:
•
Cisco Application eXtension Platform Overview
•
•
•
•
•
•
•
•
For more information on the following topics, see the Cisco AXP User Guide.
•
•
•
•
•
To obtain the names of recently introduced Cisco AXP features, and the version of Cisco AXP in which they are available, see the Cisco Application eXtension Platform (AXP) Feature History.
Cisco Application eXtension Platform Overview
The Cisco Integrated Services Router (Cisco ISR) is an integrated system within a single chassis. The Cisco ISR ties together and runs multiple value-added services such as voice, layer 2 switching, security, and application acceleration. In addition, integrated services can be hosted within the router's Cisco IOS software or the services can be decoupled and hosted on modular application service modules.
The Cisco ISR allows for blade hardware plug-in modules. These application service modules enhance the functionality, intelligence and flexibility of the router. The Cisco Application eXtension Platform (Cisco AXP) represents the next generation for this set of features.
Cisco AXP allows third parties such as system integrators, managed service providers, and large enterprise customers to extend the functionality of Cisco ISRs by providing their own value-added integrated services. On the service module, Cisco AXP hosts applications in a separate runtime environment with dedicated resources. In addition, Cisco AXP provides Application Programming Interfaces (APIs) that enable functions such as packet analysis, event notification, and network management to be utilized by hosted applications.
Cisco AXP has facilities and frameworks to host applications, and service APIs for integrating applications into the network.
Cisco AXP provides the following features:
•
These resources (including CPU, memory, disk and network IO) are segmented, which ensures that the application and router features work independently, and without interference.
•
If an application crashes, other applications are not affected and the router continues running normally. This is achieved by having each installed application in its own virtual instance.
•
Native and interpreted applications written in other programming languages can be integrated by the third party application if the third party application uses additional support libraries and interpreters.
•
Only third parties certified by us can install software onto Cisco AXP.
•
•
•
An application can receive the status of a Cisco ISR and take the appropriate action.
•
The Cisco IOS auxiliary serial port can be virtualized and appear in Cisco AXP OS as a local device. The application controls external peripherals attached to the router auxiliary serial port without special knowledge of the where the device is located.
•
The Cisco AXP network interfaces are protected by a firewall for security. Ports can be opened using the "CLI Service API" section.
Figure 1 shows the relationship between applications running on the Cisco AXP host OS of the Application Service Module and Cisco IOS software of the Cisco ISR.
Figure 1 Cisco ISR and Cisco AXP Service Module Interface
Cisco AXP Features
Cisco AXP provides a Linux-based hosting infrastructure. Having a Linux base allows the use of open source software for development. The hosting infrastructure installs and runs applications in separate security contexts using Cisco AXP Virtual Instance Manager. These security contexts all use a common Linux kernel but have separate dedicated resources. Libraries can be independent in each context. The network infrastructure is made more secure by only allowing software that has been developed by Cisco-approved partners to be installed and run on the service module.
The key features of Cisco AXP are:
•
•
•
•
Note
Hosting Infrastructure
Cisco AXP's Linux-based features allow applications to interact with Cisco IOS software. Program interfaces in Cisco AXP enable applications to modify Cisco IOS software configurations, receive notification of events from Cisco IOS software, and access peripherals attached to Cisco ISRs.
Applications can be tightly integrated with Cisco ISRs: this is a key advantage of using Cisco AXP for hosting, compared to using other server-based solutions. Cisco AXP hosts and executes an operating system in a virtualized environment.
The execution environment separates the application space from the router space, providing an extensible and flexible platform for hosting applications.
Figure 2 Cisco Application eXtension Platform on the Cisco ISR
Cisco AXP supports basic watchdog functionality to start, stop and monitor applications written in Java, C/C++, Perl, Python, and Bash. Cisco AXP supports tools for compiling applications in an x86-based Linux environment.
Virtualization
Cisco AXP uses virtualization at the operating system level to create an environment for multiple applications to run as stand-alone components. Virtualization partitions resources to support concurrent execution of applications in multiple virtual machines/virtual instances.
The advantages of virtualization in Cisco AXP are:
•
•
•
•
Note
Virtual Instances
In Cisco AXP, a virtual instance is a container within a virtual server. Process isolation gives security, and results from processes running in one virtual instance not being able to see processes running in another instance. This technology applies a change root barrier. If the application software is installed under /home/app1 and then application processes start, the directory /home/app1 becomes the root directory for the application processes. Processes can only access directories below this root directory and do not have permission to escape from /home/app1.
User-level processes are virtualized: one Linux kernel is used throughout the system, which uses a low amount of memory and has a low scheduling overhead with high speed IO access. The system provides near native OS performance.
Your application software (which can contain multiple processes) is packaged into a Super Lightweight Installer Mechanism (SLIM) format, using the Cisco AXP packaging tool. You can then install the application package into the root directory of a virtual instance. Within the virtual instance, the application has its own guest OS. The host OS manages all the guest OSs.
Files delivered by a third party cannot be shared between virtual instances. Cisco AXP does not support applications in different virtual instances having read or write access to a file in a shared area.
To further improve security, the shell environment of the host OS is not available by default. Only the CLI within the guest OS is available for managing the operating environment. You, the developer, control shell access to the guest OS.
Devices are not virtualized and are shared across all virtual instances. Therefore, IO operations do not incur additional overhead.
Network interfaces cannot be virtualized. However, you can use a "virtualized loopback interface" mechanism. See the "Loopback Interfaces" section.
Interface hiding occurs in a virtual instance. Network routing tables are not virtualized; however, multiple routing tables can be configured in Cisco AXP.
Figure 3 Cisco AXP Virtualization
Virtualization is achieved by kernel-level isolation, allowing multiple virtual instances to run simultaneously, and use common resources.
Note
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 to Cisco AXP, its /etc/host file should look like this:
127.0.0.x localhost.localdomain localhost127.0.0.1 apprehostIf 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 ranging in value from 2 upwards, 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
Dedicated Application Resources
Cisco AXP provides a predictable and constant set of resources such as CPU, memory, and disk space. For configuring resource limits, see the "Setting Resource Utilization Limits" section in the Cisco AXP User Guide.
CPU Resources
An indication of the CPU resources that are available for different service modules is specified as a CPU index. The CPU index is a value that is relative to a base value. The base value of 10000 is assigned to the following configuration:
1.0 GHz Celeron M CPU and a NME_APPRE_302-K9 service module.
For example, the CPU index for the service module AIM_APPRE 102 is 3000.
An application package uses approximately the same amount of CPU resources on any service module. The total available CPU (Index) or CPU RAM varies depending on the service module as shown in the Available CPU (Index) and Available RAM (MB) columns of Table 1.
Memory Resources
Cisco AXP does not use disk swapping for virtual memory. Therefore, the amount of memory available to an application is limited by the physical memory of the system.
In the context of virtual instances, the memory limit specifies the maximum memory available for each virtual instance. When memory overcommit is enabled, if the total memory usage within the virtual instance exceeds the memory limit (specified in MB), then processes within the virtual instance are killed.
Application Packaging Overview
Cisco AXP supports a range of applications and programming languages, including applications written in Java, C, and Bash scripts. To install your application in a virtual instance, you must first package your application. For information on how to package the application and sign the package, see the "Packaging Tool" section. To use the packaging tool you need to obtain a developer's certificate from Cisco. You sign the application package using your third party private key.
System and application packages are summarized in the following sections:
•
Core System Package
The core system package is preinstalled on all Cisco AXP service modules, and is necessary to support applications and virtualization. A Cisco Linux distribution OS is used in the Cisco AXP virtual instance.
The Cisco AXP OS gives support for virtualization, and includes kernel and system utilities such as Linux commands, Router Blade Communication Protocol (RBCP), and a CLI server.
The host Operating System (host OS) consists of a kernel of the core system package that is shared by all virtual instances running on the service module.
The guest Operating System (guest OS), is an embedded Linux OS that shares the kernel of the host OS. The guest OS includes virtual environment setup and management utilities, and software required for installing the application. The guest OS shares the Linux kernel of the core system package in the host OS.
For a list of commands available in a guest OS, see the "Appendix B: Commands in Guest OS" section.
Packages can be divided into the following two types:
•
Cisco AXP Infrastructure Add-on Packages
Cisco AXP infrastructure add-on packages extend the capabilities of the guest OS. In this guide these packages are also referred to as either Cisco add-on packages, or value-added service APIs.
Your application package can be packaged with a Cisco add-on package as a dependency. These add-on packages are created and signed by us and cannot be modified by third party developers.
Cisco add-on packages each have a separate intended function to depending on the purpose of the application in the hosting environment.
Files in Cisco add-on packages are shared on a read-only basis between multiple virtual instances. The Cisco AXP host OS that supports multiple virtual instances. One copy of a Cisco add-on package is stored in a file system created and signed by us. Copies of a Cisco add-on package are instantiated in multiple virtual instances.
Examples of Cisco add-on packages include: Cisco IOS Service API, and Perl. See the "Infrastructure Add-on Packages" section.
Hosted Application Packages
Hosted application packages are created by third party developers. In this guide these packages are also referred to as third party application packages. These application packages contain the binaries, supporting libraries, and any required data files to support the application. Each third party application package is signed using a developer's private key and verified using the developer's certificate. Third party application packages are hosted only in Cisco AXP virtual instances.
Each third party application is loaded into one virtual instance. (There is one virtual instance for each application.) Several application packages can be bundled together. For more information on bundling, see the "Bundling" section.
Figure 4 Cisco AXP Add-on Packages
Cisco AXP Certificates
Cisco AXP uses cryptographic signatures to verify packages that are signed by us to prevent unauthorized software to be loaded onto the operating system.
Signatures are also used to verify application packages developed by third parties. Third parties do not have access to our private keys for package signing and must manage their own public or private key pairs. The process for signing application packages is summarized in Figure 5.
Figure 5 Cisco AXP Application Packaging
Permission to install third party software on Cisco AXP is managed by us and is granted by providing you (the third party) with a software development authorization certificate. The certificate is a checksum of the third party X.509 certificate. See Figure 6 and Table 2 to see the process steps for obtaining permission.
Figure 6 Cisco AXP Certificates
Table 2 Steps in the Development Authorization Process
Step
Description
Third party generates a certificate request (private/public keys).
Third party requests a signed certificate from the certificate authority.
Certificate authority responds to the third party request, by providing a signed X.509 certificate1 .
Third party requests software development authorization from Cisco (includes signed certificate from certificate authority).
Cisco authorizes the signed certificate.
Cisco replies with a software development authorization certificate2 .
1 The third party is responsible for providing the signed X.509 certificate to Cisco. (Step 3)
2 The software development authorization certificate is a file that contains an encrypted checksum authorizing the third party to install software in Cisco AXP. The authorization certificate only applies to an X.509 certificate signed by the certificate authority (Step 3 in Table 2.).
Notes on Steps in the Authorization Process
During application packaging, the third party includes the following items in the package:
Cisco authorization certificate, third party certificate, third party private key, and third party application.The checksum of the authorization certificate is checked before the authorization certificate's public key is used to verify the application. The certificate can be used to verify that the application files are installed with the application package. The authorization certificate is held in the application's manifest file and stored outside the virtual environment of the host OS.
If the target hardware contains a device to securely store cryptographic keys or certificates, then
Cisco AXP does not use the third party's key to verify software integrity. The installed software is re-signed using a private key tied to the hardware and is verified using the corresponding public key.The Cisco AXP software development kit (SDK) provides third parties with the tools for packaging and signing their application files, and for attaching their certificate to the application bundle.
Running Applications on the Guest Operating System
An embedded Linux guest OS is automatically included in the application software dependency list. The guest OS contains a set of basic Linux binaries and libraries. The libraries are listed in "Appendix C: Libraries in Guest OS". The guest OS shares its kernel with the host OS. After being installed on the service module, every application instance has access to its own guest OS and may add or modify its own components.
In the following sections, starting an application is explained in "Application Startup", and monitoring the status of an application is described in "Application Status Monitoring".
The Guest OS is further explained in the following sections:
•
•
•
For information on libraries and commands available in the guest OS, see the "Appendix C: Libraries in Guest OS" section and "Appendix B: Commands in Guest OS".
Note
Application Startup
You can run your application using one of the following two startup processes:
Automatic Startup
Information about the Automatic Startup Process
Before starting your application using a startup script as explained in the "Preparing to Run an Automatic Startup Script" section, we advise you to specify the library path in the LD_LIBRARY_PATH variable.
When the virtual instance starts, a default Cisco AXP environment is used, which determines the available libraries—this environment is set to enable successful startup of the virtual instance.
When your application startup script starts, it uses this default environment which may cause problems for your application.
To avoid the problem of accessing libraries that are not available, enable reference the PATH and LD_LIBRARY_PATH environment variables.
(The LD_LIBRARY_PATH variable is also explained in the "Library location and LD_LIBRARY_PATH" section.)
How to Prepare the Startup Script
This section contains the following tasks. You may not need to perform all of these procedures.
•
•
Referencing the Environment Variables
To create or modify environment variables:
Choose one of the following two options:
•
–
export LD_LIBRARY_PATH=/lib:/usr/lib:/opt/IBM-ME-2.2.2/jre/binexport PATH=/sbin:/usr/sbin:/bin:/usr/bin:/opt/IBM-ME-2.2.2/jre/bin–
. /etc/profileOR
•
export LD_LIBRARY_PATH=/lib:/usr/lib:/opt/IBM-ME-2.2.2/jre/binexport PATH=/sbin:/usr/sbin:/bin:/usr/bin:/opt/IBM-ME-2.2.2/jre/binPreparing to Run an Automatic Startup Script
To prepare your automatic startup script:
Step 1
For example, create a script startHelloWorld.sh in build source directory /etc/rc.d/init.d
Step 2
S priority softlinkname
Startup Softlink: Example
In this example the softlink to startup script startHelloWorld.sh has a priority of 98 (range is 00-99). The startup script is in directory /etc/rc.d/init.d
S98helloworld
If you use the ls -l command in directory rc3.d, the following output shows how the softlink S98helloworld links to startHelloWorld.sh:
lrwxrwxrwx 1 uname uname 26 Aug 11 13:40 S98helloworld -> ../init.d/startHelloWorld.shStep 3
K priority softlinkname
Kill Softlink: Example
In this example the softlink to kill script endHelloWorld.sh has a priority of 98 (range is 00-99). The kill script is in directory /etc/rc.d/rc6.d
K98helloworld
Manual Startup
For manual startup, perform the following steps.
Step 1
–
–
Step 2
<name> is the application's name.
Step 3
–
–
Step 4
Obtaining Console Access for the Application
To obtain console access for the application choose one of the following procedures:
•
•
Console Access using Application Development Package
To obtain console access using a debug package as a dependency, perform the following steps.
Step 1
Step 2
Step 3
Step 4
Your application has console access to the guest OS shell using the command linux shell.
Console Access using Postinstall Script
To obtain console access using a postinstall script, perform the following steps.
Step 1
For example, create a bash file /source/bin/login.sh, where /source is the build directory.
login script: Example
#! /bin/sh/bin/bash --loginStep 2
For example, create script /source/bin/postinstall.sh, where /source is the build directory.
postinstall script: Example
#! /bin/shln -s /bin/login.sh /bin/consoleStep 3
chmod 755 /opt/tcptrace/postscripts/postinstall.shStep 4
Your application now has access to the guest OS shell by using the command connect console.
Application Status
An application must invoke the notification command to signal its status. See the "Notification" section. For example, this is necessary in order for configuration CLI commands to detect when the application is available.
An application that sends a status code indicating that it is up and running, expects configuration commands to arrive at any time. The possible status codes are shown in Table 3.
Table 3 Status Codes
INITIALIZING
Application is starting up.
ALIVE
Application is running.
DOWN
Application is down.
Notification
Notification command location: /bin/app_status_notifier.
Application name and status code are passed as parameters or arguments to the notification command.
Notification: Example:
#/bin/app_status_notifier myapp ALIVEViewing an Application's Health
To view the health of an application perform the following steps.
Step 1
<name> is the application name.
Step 2
For further information, see "Viewing the Application State" in the Cisco AXP User Guide.
Application Status Monitoring
An application must include one or more watchdog scripts or executable files bundled in the application package so that application status monitoring can be used.
Two methods of monitoring the application are described in the following sections.
Watchdog Scripts
If the application state is "online" and application health is not "DOWN", the application is monitored by the application status monitor.
The application must provide one or more watchdog scripts (also known as health check scripts or health check executables). Shell scripts and C executables are supported. The number of scripts is application dependent.
Bundle the watchdog scripts in the application package.
An application has its own way of determining if another application is running. For example, an application may check the Process Identifier (PID), or check the response to a "ping".
Watchdog scripts must be placed in the predefined directory /opt/app_status_monitor/watchdogs/
The watchdog scripts directory is in the application's vserver directory, and needs to have executable permissions. All watchdog scripts inside that directory will be invoked, and if you want to ensure the correct ordering for script invocation, you can follow the following template for naming a watchdog script:
W**<name>.sh, where ** is a two digit number. For example, one watchdog script is called W01myapp.sh.
The application status monitor has a heartbeat of 5 seconds, where 5 seconds = 1 interval. Five seconds is the minimum interval that the application status monitor requires for monitoring.
When any one watchdog script returns a non-zero status code, information for this failed watchdog will be logged, including: watchdog name, return status, and time of failure. A recovery counter counts how many times that failure occurs, and works as a delay in taking any action. A recovery counter of 3 means that the application monitor has run the monitoring for 3 iterations and is either getting non zero return status, or the watchdog has been running for over 3 monitor intervals and is not returning. The configurable recovery threshold determines the number to which the recovery counter increments to before taking the next action. When the recovery threshold is reached the virtual instance is restarted. After the virtual instance is restarted, application status monitoring continues, and the monitoring steps above continue. There is no limit on how many times the virtual instance restarts.
To configure the monitor interval, see the "Status Monitor" section. Also see the Cisco AXP User Guide. Each script or executable needs to return a status code.
•
•
Watchdog Script: Example:
#!/bin/bashAPP=test.sh APPNAME_NO_EXT=test PID_FILE=/var/run/${APPNAME_NO_EXT}.pidif [ ! -e $PID_FILE ]; then exit 1; fiPID_FROM_FILE=`cat ${PID_FILE}` for x in `ps -ef|grep $APP |awk '{print $2}'` do if [ $x == "${PID_FROM_FILE}" ]; then exit 0 else exit 1 fidoneIn this example watchdog script, the startup script must have populated the /var/run/<app>.pid file with the pid of the currently running application. The startup script should also account for various scenarios such as:
•
•
When any watchdog script returns a nonzero status code, information is logged such as name of watchdog, return status, and the time of failure. A recovery counter counts how many times failures happen. A recovery counter value of 3 indicates one of the following two conditions:
•
•
There is a configurable recovery threshold that decides the value that the recovery counter reaches before taking the next action. When the recovery threshold is reached, the virtual instance is restarted.
After the virtual instance restarts, the application status monitor continues to run, and the above two conditions are tested again. There is no limit on how many times the virtual instance restarts.
Status Monitor
The following example commands include show status-monitor, and commands to configure the monitor interval and recovery threshold. For more information, see The Status Monitor in the
Cisco AXP User Guide.•
blade# app-service myapp(myapp)# show status-monitorApplication: myapp1Monitor status: PASSEDMonitor in progress: NoLast executed watchdog: W01myapp1_test.shLast executed date: Tue Jul 10 10:22:06 PDT 2007Last failed watchdog: W01myapp1_test.shLast failed return code: 4Last failed date: Mon Jul 9 12:34:18 PDT 2007Last restarted date: Mon Jul 9 12:33:32 PDT 2007Recovery threshold: 6Monitor interval: 2•
blade# config terminal(config)# app-service myapp(config-myapp)# status-monitor monitor_interval 24 recovery_threshold 10(config-myapp)# end
Configuration File
In addition, you can provide a default configuration by using a configuration (config) file that is packaged together with your application.
The config file name and path:
/opt/app_status_monitor/config/configEach record in the config file is in the following format:
[monitor_interval | recovery_threshold] [1-99]The default value monitor_interval is 12. The application is monitored every 12 heartbeats. If the monitor interval is 12, then the monitor is active on each virtual instance every minute.
The default value for recovery_threshold is 5.
Note
config file: Example
monitor_interval 50recovery_threshold 10Configuration values, (such as the values of 24 and 10 set in the Change the monitor interval and recovery threshold example above), take precedence over the config file values. The config file only serves as a source of default values when the application is installed.
CLI Service API
The CLI service API allows your application in the guest OS to interact with the CLI server in the host OS.
For example, Java application code can issue EXEC mode commands or configuration mode CLI commands.
Care must be taken to issue commands suitable for a particular mode. For example, show run should be run in EXEC mode—if it is not run in EXEC mode, an error occurs. The supported languages for programming/scripting languages are supported: C, C++, Java, Python, and Perl. CLI service APIs for these languages are shown in the following sections.
CLI commands can be submitted in batches by the application within a single instance. This is useful in automating repetitive tasks such as reconfiguration after an image refresh.
The Cisco AXP SDK contains the libraries and modules required for writing CLI service EXEC mode or configuration mode commands. The languages supported by the Cisco AXP SDK and the associated libraries/modules are listed in Table 4.
Table 4 Files for CLI Service API
C/C++
/include/appreapi.h
/lib/libappreapi.soJava
/jar/appreapi.jar
Python
/python2.3/AppreAPI.py
Perl
/perl/AppreAPI.pm
CLI Service APIs
Java API
public int exec (AppreMessage msg);public int config (AppreMessage msg);The Java bean object AppreMessage contains both the request and response string.
After the code has run, the returned status code indicates completion/failure. For status code values, see Table 5.
public class AppreMessage{private String _response;private String _request;public void AppreMessage(){this._response = "";this._request = "";}public String getRequest(){return this._request;}public void setRequest(String request){this._request = request;}public String getResponse(){return this._response;}public void setResponse(String response){this._response = response;}}C/C++ API
Note
int appreapi_exec(AppreMessage_t* msg);int appreapi_conf(AppreMessage_t* msg);free (msg.response);AppreMessage_t is a struct containing the request and response string.
After the code has run, the returned status code indicates completion/failure. For status code values, see Table 5.
typedef struct AppreMessage_t{char* request;char* response;int size;} AppreMessage_t;Perl API
sub exec (request)sub config (request)The request string is input and the status code value is output. For status code values, see Table 5.
Python API
sub exec (request)sub config (request)The request string is input and the status code value is output. For status code values, see Table 5.
Bash API
appreapi [--mode name] [[--file filename] | [cmdlist]]The request string is input and the status code value is output. For status code values, see Table 5.
CLI Service API Examples
In the following examples, commands are issued by passing a string to a function/method such as request (for C) or setRequest (for Java). More than one command may be passed at one time, by separating each command with a comma. For example, to use setRequest( ) to call two or more system commands:
msg.setRequest(cmd)where cmd is a string containing a sequence of commands separated by commas.
For example,
String cmd = "show run,show trace"The following sections show code fragments that implement AppreMessage in the main programming/scripting languages of C/C++, Java, Perl, and Python.
C/C++: Example
#include "appreapi.h"int main(int argc, char** argv){char buf[] = "show run";AppreMessage_t msg;msg.size = 0;msg.response = NULL;msg.request = buf;int status = APPRE_FAIL;status = appreapi_conf(&msg);status = appreapi_exec(&msg);return status;}Java: Example
import com.cisco.aesop.apphosting.appreapi.*;public static void main (String[] args){int status = 0;CommonServiceImpl apiCall = new CommonServiceImpl();AppreMessage msg = new AppreMessage();msg.setRequest("show run");status = apiCall.exec(msg);status = apiCall.config(msg);}In the above example the Java class CommonServiceImpl implements the API access service.
The class has two methods for exec and config mode:
public int exec (AppreMessage msg)public int config (AppreMessage msg)Perl: Example
use AppreAPI;$api = new AppreAPI::AppreAPI();$req = "show run";($val, $res) = $api->exec($req);($val, $res) = $api->config($req);Python: Example
from AppreAPI import *api=AppreAPI()status, response = api.exec(request)status, response = api.config(request)Logging Support
Cisco AXP provides logging support for applications that include a syslog or log4j logging facility, and file rotation of logging files. Different logging levels can be set. If an error occurs with a level below the logging level, the error is not reported in a log file. For more information on logging errors, see the "Logging" section.
SNMP
Your application can use SNMP. net-snmp code is located in the following two places:
•
•
The net-snmp library uses a socket for internet access.
Further details:
•
•
•
Infrastructure Add-on Packages
Cisco infrastructure add-on packages are packages provided by us, with additional functionality for applications.
Package names have the format: <package>.<platform>.<version>.pkg
A package name of "axp-tomcat5.nme.1.1.1.pkg" shows the package is a tomcat application, the platform is NME , and the version is 1.1.1.
The associated payload file for each add-on package has the suffix ".prt1"; for example "axp-tomcat5.nme.1.1.1.prt1" (the version number in this example, is the same as the version number in the Cisco AXP host OS package: axp-k9.<platform>.<version>.pkg).
Add-on packages:
Installing Add-on Packages
Step 1
Step 2
Step 3
–
–
Step 4
Cisco AXP User Guide.
Cisco AXP Add-on Packages
Cisco AXP provides the following add-on packages.
•
•
•
Tomcat
Package name: axp-tomcat5.<platform>.<version>.pkg
An example package name is axp-tomcat5.nme.1.1.1.pkg
Use the tomcat package to embed the Tomcat 5.5 servlet container in a virtual instance.
Application SSH
Package name: axp-ssh-4.6p1-k9.<platform>.<version>.pkg
An example package name is axp-ssh-4.6p1-k9.nme.1.1.1.pkg
For further information, see the "Application SSH package used in production for SSH Tunneling" section "SSH Tunneling" section.
Application Development Package
Package name: axp-app-dev.<platform>.<version>.pkg
An example package name is axp-app-dev.aim.1.1.1.pkg
Access the Linux shell to issue CLI commands, see "Obtaining Console Access for the Application" section.
Add either package axp-ssh-4.6p1-k9.<platform>.<version>.pkg or axp-app-dev.<platform>.<version>.pkg as a dependency when you package your application.
The application development package provides an SSH server that runs in a virtual instance.
SSH Tunneling, rsync utility, and GDB debug are described in Debugging Tools.
CLI Plug-in Distribution Service
Package name: axp-cli-plugin.<platform>.<version>.pkg
An example package name is axp-cli-plugin.nme.1.1.1.pkg
The Cisco AXP CLI Plug-in distribution service is an add-on package that provides the necessary libraries that allows you to use your CLI within the Cisco AXP system. The service distributes CLI plug-ins from the Cisco AXP CLI server to the application.
For CLI plug-ins, there are three components you need to define: CLI plug-in definitions, CLI plug-in distribution listener and CLI plug-in actions. See the "CLI Plug-in Applications" section.
Cisco IOS Service API
Package Name: axp-iosapi.<platform><version>.pkg
An example package name is axp-iosapi.nme.1.1.1.pkg
The Cisco IOS Service API allows you to write applications that access router information and change system configurations using commands equivalent to Cisco IOS configuration and EXEC mode commands.
The Cisco AXP SDK contains the libraries and modules you require for writing applications that use Cisco IOS configuration mode commands. The languages supported by the SDK and the associated libraries/modules are listed in Table 6.
Table 6 Files for Cisco IOS Service API
C/C++
iosapi.h
libiosapi.soJava
iosapi.jar
Python
iosapiPython.so
IosapiFactory.py
Iosapi.pyPerl
iosapi.pm
Bash
iosapi
APIs are listed in the following section, Cisco IOS APIs. Each API includes a call to a method to set the timeout period. You can use the timeout to prevent the calling program from hanging or halting while waiting for a return message. The calling program can set the timeout period for a particular batch session (for example, see "set_timeout" in the C/C++ example in "Cisco IOS APIs" section). The timeout applies to all subsequent Cisco IOS software commands in the session.
Cisco IOS APIs
APIs for accessing Cisco IOS commands are listed below.
C/C++ API
typedef struct IosServiceAPI_t {apiMethod exec;apiMethod config;} IosServiceAPI_t;extern int getIosApi(const char *serviceName, IosServiceAPI_t* iosapi);void set_timeout (int sec)Java API
public int exec(IosapiMessage msg);public int Config(IosapiMessage msg);public void set_timeout (int sec);Python API
class Iosapidef Config(self, request)def Exec(self, request)def Set_timeout(self, sec)Perl API
package Iosapi::Iosapi;sub exec(self, request);sub config(self, request);sub set_timeout (timeout)Bash API
appreapi [--mode name] [[--file filename] | [cmdlist]] [--timeout sec]Cisco IOS API Response and Status
In the case of C/C++/Java, the API returns a response string, which is stored in the message struct.
In the case of Perl and Python, the API returns a response string and a status code (multiple return values).
The possible return status codes are explained in the table below.
Cisco IOS API Examples
In the following Cisco IOS API examples, commands are issued by passing a string to a function/method such as request (for C) or setRequest (for Java). More than one command may be passed at one time, by separating each command with a semi-colon. For example, to use setRequest to call two or more system commands:
msg.setRequest(cmd)where cmd is a string containing a sequence of commands separated by semi-colons.
For example,
String cmd = "int fa0/0; ip address 172.31.100.195; no shutdown"C/C++: IosapiMessage_t
For C/C++, use the structure type variable IosapiMessage_t.
typedef struct IosapiMessage_t {char *request;char *response;int size;} IosapiMessage_t;response: set to zero, for the API to allocate memory for the response, or set to non-zero to allocate memory for the response yourself.
size: set to zero: if the API allocates memory, or set to non-zero: if caller allocates memory.
In both cases you need to free the allocated space after the code has run.
Note
C/C++: Example
#include "iosapi.h"int main(int argc, char** argv){char buf[] = "show run";IosServiceAPI_t iosapi;IosapiMessage_t msg;msg.size = 0;msg.response = NULL;msg.request = buf;getIosApi("CommonService", &iosapi);retcode = iosapi.exec(&msg);retcode = iosapi.config(&msg);return retcode;}Java: IosapiMessage
For Java, a bean object IosapiMessage is used.
public class IosapiMessage {public void setRequest(String request);public void setResponse(String response);public String getRequest();public String getResponse();}Java: Example
import com.cisco.aesop.apphosting.iosapi.*;public static void main (String[] args){int status = 0;IosServiceAPI iosapi = IosapiFactory.getIosApi("commonservice");IosapiMessage msg = new IosapiMessage();msg.setRequest("show run");status = iosapi.exec(msg);status = iosapi.config(msg);}Perl: Exampleuse Iosapi::Iosapi;my $request = "show run";my $type = "CommonService";my $val;my $response;$iosapi = Iosapi::Iosapi->new($type);($val, $response) = $iosapi->exec($request);($val, $response) = $iosapi->config($request);Python: Example
import Iosapiimport IosapiFactorytype = "CommonService"request = "show run"val, iosapi = IosapiFactory.getIosApi(type)val, response = iosapi.Exec(request)val, response = iosapi.Config(request)Configuration
NETCONF over BEEP feature must be configured on the router and the Cisco AXP service module. NETCONF over BEEP in Cisco IOS software does not support any authentication; it supports only an SASL/Anonymous profile.
For security, an ACL list can be added to the netconf configuration to allow or deny access to the netconf/BEEP connection. See "Configuration within Cisco IOS Software: Example" section.
Configuration within Cisco IOS Software: Example
>config t>sasl profile JAVALIN_ANONYMOUS_SASL>mechanism anonymous>exit>ip access-list standard 1>permit host 10.1.10.2 >exit>netconf beep listener 12345 acl 1 sasl JAVALIN_ANONYMOUS_SASL>netconf max-sessions 16Configuration within Cisco AXP Service Module: Example
>config t>netconf beep initiator 1.100.50.1 12345>netconf max-sessions 16Where 1.100.50.1 is the IP address of the Cisco IOS router.
Port 12345 is the port that matches both Cisco IOS software and Cisco AXP. The number of 12345 is only an example.
Embedded Event Manager API
Package Name: axp-eemapi.<platform>.<version>.pkg
An example package name is axp-eemapi.nme.1.1.1.pkg
The Embedded Event Manager (EEM) supports Cisco IOS event notification and enables a wide range of events to be reported from Cisco IOS software to your Cisco AXP application.
The Cisco AXP Embedded Event Manager API supports the following Cisco IOS images:
•
•
•
To register events for your Cisco AXP application, use one of the following two methods:
1.
2.
Configuration for Cisco IOS EEM is automatically performed during boot up. Configuration includes generating an EEM policy file for each event, transferring the file over Cisco IOS and configuring the EEM.
When the requested event occurs, the EEM triggers an EEM policy, which is usually a Tcl script. Execution of the event policy causes event information to be delivered to the EEM event dispatcher on the Cisco AXP Host. The dispatcher dispatches the event to the application that registered the event.
To notify an event using an API call, see the "EEM APIs" section.
Registering using an Event Configuration File
Specify events in an event configuration file eem_config.xml. Package event configuration files with the application and install the application on the blade. When the EEM-specific startup routine is executed during reboot, the corresponding event policy files are set and the Cisco IOS EEM is configured. The events become active.
For an example of an event configuration file and its corresponding DTD, see Event Configuration File: Example and Event Configuration File DTD: Example. Note that the name attribute of the event element must be unique within the file.
When entering a parameter string, use double quotes for the whole string and use single quotes for substrings. For example,
<event name = "myeventname" type = "syslog" parameter = "pattern 'ethernet' " />
Note
Event Configuration File: Example
<Events ><event name="myCLIEvent" type="timer" parameter = "cron name ... " /><event name="myIntEvent" type="interface" parameter= "name Ethernet0/0 ......." /><event name="myiosevent" type="ios_config" / ><\Events>Event Configuration File DTD: Example
<!ELEMENT events (event+) ><!ELEMENT event EMPTY><!ATTLIST event name CDATA #required><!ATTLIST event parameter CDATA ><!ATTLIST event type ( appl | cli | counter | interface | ioswdsysmon |none | oir | snmp | syslog | timer | timer_subscriber |ios_config) #required>The event type attribute values consist of a list of types that map to event register keywords in EEM. In addition, there are other Cisco IOS events that are not provided from EEM, such as the event ios_config.
Event Types and Command Extensions
The event types and corresponding command extensions are shown in Table 8.
Note
Note
EEM APIs
Event Notification
To notify an event using an API call from your application, use a function of the event handler to receive notification of an event. Your application must also have dependency set up upon the eemapi package (for example, package axp-eemapi.nme.1.1.1.pkg). Setup this dependency during packaging of your application. For further information on packaging, see the "Packaging the Application" section.
The following sections show the EEM APIs for Java, C, and Python.
Table 9 Files for EEM APIs
Java
eemapi.jar
C/C++
eemapi.h
libeemapi.soPython
eemapi.py
The Java API for EEM is bundled in file eemapi.jar, which contains all the interface APIs to support the receipt of EEM events.
The C APIs for EEM are bundled in lib eemapi.so under directory /lib in the guest OS. You must include the header file eemapi.h in your application.
The Python API for EEM is bundled in eemapi.py under directory /lib/python2.3/eemapi in the Cisco AXP guest OS.
Event Registration
Use an event registering function or method to handle events in your application.
Event handling functions and methods are described below for C, Java, and Python. Their arguments are described in Table 10.For C, an event handler is a callback function defined in your application.
Void AppEventHandler (char *eventName, char *eventType, char *eventInfo)
For Java, an event handler is a class defined in your application, subclassed from the EventHandler class. The event handler class must overwrite the EventHandler class's callback function to receive events.
public class EventHandler {public void callback (String eventName, String eventType, String eventInfo);}For Python, an event handler is a class defined in your application, subclassed from the EventHandler class. The event handler class must override the ReceiveEvent function to receive events.
class EventHandler :def ReceiveEvent (self, eventName, eventType, eventInfo);
Table 10 Application Event Handler Arguments
eventName
"name" attribute of the event element in the event configuration file or the event-name specified through the CLI.
eventType
Event Type as shown in Table 8.
eventInfo
Result string event_reqinfo from Cisco IOS EEM. The string is formatted and specific to an event.
Remote Serial Device
Package Name: axp-vserial.<platform>.<version>.pkg
The virtual serial driver package enables an application running on the application service module to access external Cisco IOS serial devices connected to the serial port of a Cisco IOS router. For example, this allows an application to support a peripheral that is connected to a serial port such as a GPS locator.
The package supports a maximum of 16 serial devices.
The auxiliary serial ports of the Cisco IOS router are virtualized and appear in the Cisco AXP OS as local devices. External devices connected to the Cisco IOS router appear as standard local devices such as "/dev/tty1" or "/dev/tty2" to Linux applications hosted on application service modules. Third party applications can therefore control external peripherals attached to the router's auxiliary serial port without special knowledge of the location of the devices. Applications can open/close/read/write to the peripherals using standard Linux System calls such as: open("/dev/vtty1"), and read( ).
A reverse telnet session is established for either a line interface or a serial interface (provided that the serial interface is configured in async mode). This telnet session enables serial data transfer.
Developing an Application Using a Serial Device
The following steps summarize the development, packaging, installation, and configuration of an application for accessing a serial device.
Develop
Develop your application to access a serial device using standard Linux System calls such as
open ( ), and read( ).If a device name is hard coded in the application (for example, "modem" or "gps") make a note of the device name. Configuring on the router using the bind serial vtty000 modem command creates an entry "/dev/modem" in the application's virtual instance. After binding the device, your application accesses an external device on the host router as if it was a local serial port.
int main(int argc, char *argv[]) {char *dev;int fd;if (argc > 1)dev = strdup(argv[1]);elsedev = strdup("/dev/modem");fd = open (dev, O_RDWR | O_NONBLOCK | O_NOCTTY | O_NDELAY);Package
Package and install the application by using one of the following two methods.
(The first method installs the application as part of a bundle, the second method installs the application separately from other packages.)
1.
a.
b.
c.
2.
a.
b.
c.
Configure
Connect the serial device to the router's serial port and configure the device on the router.
After binding the device, your application accesses an external device on the host router as if it is a local serial port. For an example showing an application that accesses a serial device, see the "Remote Serial Device: Example" section.
Perl
Package Name: axp-perl-5.8.8.<platform>.<version>.pkg; for example, axp-perl-5.8.8.nme.1.1.1.pkg
Perl version 5.8.8 is supported by the add-on package axp-perl-5.8.8.nme.1.1.1.pkg.
The add-on package has multiple threading support and uses ithreads (one Perl Interpreter per thread).The Perl add-on package, for Cisco AXP version 1.1.1 and higher, contains path file names that include "i586" instead of "i686".
Example (Cisco AXP 1.1.1)
In this example, the perl files for Cisco AXP 1.1.1 have path names that include "i586". The files in the @INC directory are:
@INC:/usr/local/lib/perl5/5.8.8/i586-linux-thread-multi/usr/local/lib/perl5/5.8.8/usr/local/lib/perl5/site_perl/5.8.8/i586-linux-thread-multi//usr/local/lib/perl5/site_perl/5.8.8/usr/local/lib/perl5/site_perlAdditional References
•
•
•
•
•
•
•
•
•
•
Development System Requirements
Applications must be developed in a Linux OS environment. The minimum system requirements are:
•
•
•
Prerequisites
See the Cisco AXP User Guide for information on the following tasks before you install the Cisco AXP SDK.
Step 1
Step 2
Step 3
Application Development Overview
The main phases of application development are shown in Figure 7.
Figure 7 Application Development
The steps below explain the stages in the application development flow.
Step 1
a.
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 with the same version number as the version of Cisco AXP running on the service module.
c.
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.
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
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.
b.
Accessing the Linux shell helps you to debug the application software after the software is loaded onto the Cisco AXP service module. See the "Console Access using Postinstall Script" section.
c.
Step 3
a.
For further information on rsync, see the "Rsync" section.
b.
c.
d.
Step 4
a.
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.
c.
(For further information on debugging tools, see the "Troubleshooting Your Application" section, and the "Application Development Package" section.)
d.
Step 5
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
a.
b.
c.
d.
e.
f.
g.
h.
Cisco AXP SDK
Cisco AXP provides a software development kit (SDK) for developers to use in a Linux development environment.
SDK tools/utilities are explained in the following sections:
•
Note
Installing the SDK
To install the Cisco AXP SDK, perform the following steps.
Note
Step 1
Step 2
mkdir -p /source/sdkStep 3
tar xvzf axp-sdk.<package>.tar.gz -C /source/sdk
Note
The Cisco SDK is now installed. If the <package> in the file axp-sdk.<package>.tar.gz is "1.1.1", the SDK directory name includes "1.1.1".
The Cisco AXP SDK includes the directories and files shown in Table 11.
Packaging and Bundling Tools
Tools related to bundling and packaging are explained in the following sections:
Packaging
Use the packaging tool pkg_build.sh to create and sign an application package, see the "Packaging Tool" section.
Bundling
You can use the bundling tool (pkg_bundle.sh) to combine packages. For example, after packaging an application with the required dependencies, you can bundle the application with add-on packages before installing the bundle. See the "Bundling Tool" section.
Library Dependency Checker
The Library Dependency Checker tool (pkg_check.sh) allows you to check software dependencies before installing your application on the Cisco AXP service module.
The Library Dependency Checker tool looks for dependencies of packaged binary files in the default /lib directory. (The root directory is not checked.) The checker tool lists any binaries with unsatisfied dependencies and any corresponding missing libraries. A library in a directory such as "/opt/lib" is ignored unless it is added using the --lib-path argument.
Library Dependency Checker: Example
pkg_check.sh --project-dir '/xyz-src' --check-pkg AppXYZ-1.0.pkg --lib-path '/usr/local/lib:/opt/app/lib' DependencyPkg1.pkg DependencyPkg2.pkgLibrary Dependency Checker Arguments
Library Dependencies Checker: Limitations
The Library Dependency Checker tool cannot detect the following:
•
•
Package Information
The Package Information tool (pkg_info.sh) displays information about a package. The tool is located in the tools directory of the SDK.
An example of useful information that can be obtained is the SSID of a package, which can then be used to add a dependency to your application during packaging.
The SSID is specified in the deps parameter of the Packaging Tool.
Output from pkg_info.sh is placed in file: <your project directory>/tmp/core.log.
Example
pkg_info.sh sanity_test.pkgSubsystem ID: d984142e-4dfb-4a28-bf42-60d278b7e798Name: sanity_testVersion: 1.0Type: plug-inDescription: SanityContent:/hello.txt (file, not-link, data)/xterm (file, not-link, executable)/sbin/.app_sig (file, not-link, data)
Note
Note
RPM File Extraction
While your application is running you may discover that it stops running on the service module. To investigate this you can manually start up your application. See the "Manual Startup" section.
Start your program by entering <script name> start (a command, for example, in the startup script in /etc/rc.d/init.d).
If an error message appears that says files are missing, and a message also says that certain RPM files are required, you need to identify the RPM files to be installed so that your application can run successfully.
After you identify missing files, you can add each missing RPM file with the help of these utilities:
Standard RPM Utilities
To add additional software after the third party's application is installed, use standard RPM utilities such as rpm and rpm2cpio. You will need access to the guest OS shell of the application on the service module.
To extract the RPM files, perform the following steps.
1. Run the rpm2cpio utility on the development machine.
2. Upload files from the development machine to an FTP server.
3. Download from the FTP server to the client (service module) using curl utility (see http://curl.haxx.se/docs/manpage.html). The curl utility downloads files from HTTP/FTP servers.
To install an RPM file as part of your application, perform the following steps. For more information, the "RPM File Extractor Tool" section.
Step 1
To extract an RPM file to the current directory:
rpm2cpio /tmp/myapp.rpm | cpio -ivdStep 2
To examine any pre or postinstall/uninstall scripts that the RPM file contains, use the RPM file extractor tool as follows:
rpm -qp --scripts /tmp/myapp.rpmTo examine any dependencies (libraries, or other RPM files) that the RPM requires, use the RPM file extractor tool as follows:
rpm -qp -R /tmp/myapp.rpmSee the "RPM File Extractor Tool" section.
Step 3
RPM File Extractor Tool
The RPM File Extractor Tool (tools/rpm_extractor.sh) is part of the Cisco AXP SDK. The tool quickly extracts all the RPM files into the project source root directory. From the root directory, you can examine any dependencies the RPM files require, and view any preinstall, postinstall, or uninstall scripts that the RPMs contain.
For more information, see the "RPM File Extractor Tool" section.
CLI Plug-in Utility Tools and APIs
Cisco AXP provides a mechanism for CLI applications to be integrated into the Cisco AXP CLI environment.
A set of tools are available for you to use during development to validate, process and package the CLI plug-in along with your application.
Value-added Service APIs
Value-added service APIs allow application programs to access, manage, and augment the existing features of Cisco IOS software. Value-added service APIs are provided by Cisco add-on packages. See "Infrastructure Add-on Packages" section.
The Cisco AXP SDK includes libraries, APIs, and associated header files. The Cisco AXP SDK allows you to compile applications and link applications in a development environment.
Developing an Application
Developing an application is explained in the following sections.
For developing CLI plug-in applications, see the "CLI Plug-in Applications" section.
•
Writing, Testing, and Packaging an Application
In general, the first step in the development process is to 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. You then create a package directory, run the Cisco AXP packaging tool to package your application ready to be installed onto the Cisco AXP.
Certificates
There are several steps to be followed when packaging your application before installing the application on Cisco AXP. One required 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. Additionally, 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"). Inside the virtual instance the application has its own shell. Access the guest OS shell for debugging, modifying/viewing specific files for your program, and importing other applications and tools. However, allowing the user to access the shell increases the security risk in your application. Access to the guest OS shell access is described in the "Packaging the Application" section.
If you decide to allow someone to have shell access to your application environment, there may be certain files that you want to protect from modification and/or deletion. To protect files, see the "Creating a File of Protected Files" section. If any of these listed files are modified and/or deleted, then when the virtual instance for your application next tries to restart, the modifications/deletions will be reported and the virtual instance will not start. This prevents your application from running. A message is written to the system log listing the name of the modified/deleted file.
Writing the Application
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.
We recommend that "health status" is coded in the application so that the show state cli command can show the application's health status.
Note
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 "Obtaining Console Access for the Application" section.C Applications
When developing native C/C++ software targeted to run on Cisco AXP, we recommend that you use the following components:
•
•
•
Fedora 6 C/C++ applications must be linked with one of the two following linker options:
•
•
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.
Step 1
mkdir /source/helloworldappStep 2
#!/bin/bash#provide health status/bin/app_status_notifier helloworld INITIALIZING# remove old log filerm -rf fancy_output#provide health status/bin/app_status_notifier helloworld ALIVEwhile [ 1 ]; doecho "Hello world!" >> fancy_outputsleep 5doneStep 3
Step 4
–
echo "Hello world!" >> /var/log/fancy_output–
touch /var/log/fancy_outputln -s /var/log/fancy_output /helloworld/fancy_outputFile 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
show log name <your file name>
Automatic or Manual Application Startup
The application starts up in one of the following two ways:
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 "Obtaining Console Access for the Application" section.
Packaging the Application
This section consists of the following sections:
•
•
•
•
Note
Creating a Common Root Directory
Create a common root directory such as /source/helloworldapp/build.
This directory is the common root directory from which the packages are created and installed on Cisco AXP.
Copying Files
•
•
•
Hello World Build Directory: Example
In this example, the common root directory is /source/helloworldapp/build.
The subdirectories beneath the common root directory are:
./bin:post-install.sh./etc/rc.d/init.d:helloworld./etc/rc.d/rc3.d:S99helloworld -> ../init.d/helloworld./etc/rc.d/rc6.d:K99helloworld -> ../init.d/helloworld./helloworldapp:hello_world.sh./sbin:Creating a File of Protected Files
If you decide to allow a user to access the guest OS Shell, you can optionally protect files from being changed. This may include the startup script, kill script, helloworld, and process script helloworld.sh. This is done by creating a file that contains a list of protected files.
Create file called protect.txt that holds a list of protected files. Include any necessary file path before each file name. Note: There should be only one file in each line of the protect.txt file.
During packaging, a checksum is run on each of the files in protect.txt, and the results are stored along with the package. When the virtual instance starts, protected files are verified against the checksums to ensure the integrity of the files.
Protected File List: Example
/etc/rc.d/init.d/helloworld/helloworldapp/helloworld.shCreating Certificates
Certificates and a private key file are required during packaging. This developer certificate is an X.509 certificate, signed by a trusted certificate authority, for example VeriSign. Please refer to your certificate authority for instructions on how to generate a certificate request and obtain a signed certificate. We recommend that you use a key length of 1024 bits or greater for certificate keys, using RSA public-key encryption.
Step 1
•
•
Perform the following steps.
–
openssl genrsa -out private.key 1024
–
openssl req -new -x509 -days 365 -key private.key -out dev_certificate.sig
Note
Step 2
Step 3
Step 4
Step 5
Creating a Package Directory for Project
Create a package directory for your project. This directory includes packaged files to be installed on Cisco AXP. For example: mkdir /source/helloworldapp/package.
Running the Packaging Tool
To package your application, perform the following steps.
Note
Step 1
Specify parameters to the packaging tool interactively or in batch mode (in a file).
•
•
You can build a package from any location in the file system.
Step 2
Execute the postinstall script after installation and before the application first starts.
Specify the location of the script using a relative path with respect to the common root directory. For example, if script postinstall.sh is in directory /source/build/bin, and the common root directory is /source/build, specify the location of the script as /bin/postinstall.sh
Packaging the Hello World Application: Example
This example shows the packaging tool pkg_build.sh, in interactive mode, packaging the "Hello World" application.
For further information on the packaging tool, see the "Packaging Tool" section.
After packaging, to install the application, see the "Installing an Application" section.
The packaging tool is started by entering the command pkg_build.sh.
[user@linuxdir ~]$ /xyz-src/tools/axp-sdk.1.1.1/tools/pkg_build.shSLIM Packaging Utility. (C) 2007 Cisco Systems, IncChecking dependencies...In interactive mode, the tool prompts you for each input parameter, starting with parameter ** project-dir.
Note
** project-dirUsed to store output packages as well as any intermediary files, for example manifest files. Project directory must be readable and writable.Project Directory: /xyz-src/apps/helloworld_app/package** auth-bundleAuthorization bundle provided by Cisco Systems. This bundle is required to allow your application to install and run on the target bladeAuthorization Bundle: /xyz-src/certs/1.1/basic/nme/auth_bundle.sig** private-keyPrivate key stored in this file will be used to sign application package files. Public key corresponding to this private key must be stored in development certificatePrivate Key for Signing Operations: /xyz-src/certs/1.1/basic/nme/private.key** nameName of application to be packaged. This name will be used to identify application through command line interface as well as or naming package filesApplication Name: helloworld** versionApplication version is used when displaying application information through command line interface. It is also used for upgrade/downgrade sequencingVersion: 1.1** description (optional)Application description is used when displaying application information through command line interface. For example it may contain a statement about application's capabilitiesDescription: helloworld application** uuid (optional)Unique identifier to be used with this application. The identifier can be generated using Linux 'uuidgen' utility. It will be automatically generated if left blankUnique Identifier:** source-dirSource directory contains the files to be packaged. Files must be laid out in the same manner as they will appear on the root file system when installed in the application hosting environmentSource Directory: /xyz-src/apps/helloworld_app/build** protect (optional)File that contains a list of application files to be protected. All files listed in this file will be verified during system startup. No application files will be protected if this parameter is left blankProtect List File:** deps (optional)Application may depend on one or more components outside of its own package. Dependencies are specified based on application's unique identifiers. This tool can lookup application unique identifiers for packages in '${PROJECT_DIR}/pkg' and '${SDK_DIR}/pkg' directories. If this option is not specified the application will have no dependenciesLoading existing SLIM Packages in directories:/xyz-src/tools/axp-sdk.1.1.1/pkg/xyz-src/apps/helloworld_app/package/pkghelloworld.1.1.pkg:1c741d0d-9eac-42b9-9b0f-caa3fd41dede - helloworldDependency Subsystem Identifier:** disk-limitdisk limit option specifies the minimum disk space allocated for the application. When disk resource falls below this limit, the application will not be allowed to install. Minimum disk limit must be specified in megabytes, for example 1500MDisk Limit: 100M** memory-limitMemory limit option allocates RAM space for the application. Memory limit must be specified in megabytes, for example 256MMemory Limit: 100M** cpu-limitCPU limit option specifies the minimum amount of cpu resource allocated for the application. When the cpu resource falls below this limit, the application will not be allowed to install. This option is uniform across supported platforms so the same package can be installed on any of the supported platforms of the same CPU architecture. Please refer to developer's guide for the information on how to calculate CPU limitCpu Limit: 200** swap (optional)swap option specifies whether swap needs to be turned on or off on theNetwork Module. The application can specify ON or OFF; the system willenable/disable swap after reboot based on Application's requirementSwap Space: ON** postinstall (optional)Postinstall script is executed after installation is complete but beforethe application has been started for the first time. Postinstall scriptmust be packaged with the application. When entering postinstall scriptlocation, use relative path with respect to source tree directory.Post-install script path: bin/post-install.sh** cap-config (optional)Capabilities configuration file can be used to relax certain restrictionsin the virtual container. Only the capabilities granted by the developmentauthorization file can be configuredCapabilities Configuration File:** disk-wildcard (optional)Enable disk wildcard support? (y/n): y** memory-wildcard (optional)Enable memory wildcard support? (y/n): y** cpu-wildcard (optional)Enable cpu wildcard support? (y/n): yInteractive mode complete. Resulting CLI command:-------------------/xyz-src/tools/axp-sdk.1.1.1/tools/pkg_build.sh --project-dir '/xyz-src/apps/helloworld_app/package' --auth-bundle '/xyz-src/certs/1.1/basic/nme/auth_bundle.sig' --private-key '/xyz-src/certs/1.1/basic/nme/private.key' --name 'helloworld' --version '1.0' --description 'this is a helloworld' --source-dir '/xyz-src/apps/helloworld_app/build/' --disk-limit '100M' --memory-limit '100M' --cpu-limit '200' --swap 'ON' --postinstall 'bin/post-install.sh' --disk-wildcard --memory-wildcard --cpu-wildcard-------------------Press enter to continue...
Tip
Installing an Application
For information on installing, uninstalling and upgrading software, see the "Installing and Upgrading Software" section in the Cisco AXP User Guide.
Bundling allows you to install one package containing many others. For example, you can install the application package and the required Cisco add-on packages in one bundle. For information on packaging and bundling, see the "Packaging Tool" section and "Bundling Tool" section.
If you are not using bundling and choose to install the packages separately, make sure that you install the packages in the following order:
1.
2.
Verifying Your Application is Installed and Running
To verify your helloworld application is installed, enter the following command.
Step 1
If your application is installed, the application appears in a list of other processes.
Step 2
If your application is running, you enter the CLI of the guest OS shell.
Step 3
Your application appears in a list. For example, "helloworld".
Step 4
Your application appears in a list that shows the state of the application. For example a state of "online". The STATE display depends on having the health status returned by your application.
Example:
APPLICATION STATE HEALTHhelloworld online ALIVE
CLI Plug-in Applications
Cisco AXP CLI plug-ins allow you to create application-specific commands to be used in addition to commands that are already available via the Cisco AXP CLI.
CLI plug-in application development:
•
•
CLI plug-in application tasks:
•
•
•
CLI plug-in reference information:
•
•
•
Examples of simple CLI plug-in applications:
•
Note
CLI Plug-in Distribution Service
The Cisco AXP CLI plug-in distribution service (axp-cli-plugin.<platform>.<version>.pkg) is a Cisco add-on package that provides the necessary libraries to distribute CLI plug-ins from the Cisco AXP CLI server to your application. For further details, see the "Infrastructure Add-on Packages" section.
CLI Plug-in Application Components
The required components for integrating a CLI plug-in command into Cisco AXP are described in Table 13.
Table 13 CLI Plug-in Application Components
XML definition file
Defines the syntax of the command entered by the user. The XML for the command must adhere to the Data Type Definition (DTD) shown in the "Elements and Attributes" section.
Action class
A Java class, C class, or Bash script that runs when the user enters a CLI command that is defined in the XML definition file.
Note
Java: When writing an action script (class) using Java, compile the class into <action name>.class.
C: When writing an action script (class) using C, compile the class into a shared library called <action name>.so.
Bash: When writing an action script using a Bash Shell script, <action name>.sh, note that only an integer value may be returned indicating the exit status. There is no support for returning messages for display by the CLI console.
Application
Starts a CLI VM thread startCLIDistributionVMThread that listens to user commands. Only if the application is running will the thread be able to listen and respond to CLI commands entered by the user.
When the user enters a CLI command defined in the XML definition file, startCLIDistributionVMThread invokes the corresponding action class.
Figure 8 shows these three CLI plug-in components, which are set up to process the show time command.
Figure 8 Cisco AXP CLI Plug-in Service
Prepackaging the CLI Plug-in
The CLI plug-in application must be prepackaged before running the packaging tool. For more information on packaging the plug-in, see the "Packaging a CLI Plug-in Application" section.
Prepackaging, using the CLI Plug-in SDK Packaging Tool, is dependent on setting up the data correctly in the directory sdk/tools/custom_cli/.
Each of the required directory components is listed below and then described in Table 14.
sdk/tools/custom_cli/actions/definitions/internal/cli_plugin.configcli_plugin.pycli_grammar.dtd
Note
To prepackage the CLI plug-in application perform the following steps.
Step 1
Step 2
Note
Step 3
Table 15 Configuration File Components
file
CLI plug-in definitions file, located in the directory definitions/
javapath
Path to the directory Java SDK bin/
vm
Name of the application. This name must match the name provided later in the application packaging tool. See the "Package Name" section.
proj_src
Root directory from which this product will be prepackaged.
•
•
tar xvf showtime.tar -C /source/showtimeapp/buildNote
Step 4
To run the executable packaging tool, (cli-plugin.py), enter:
python cli-plugin.pyIf the tool runs successfully, a tar file of the application is created in the output/ directory.
Step 5
Moving the tar File: Example
This example extracts the contents of the CLI plug-in tar file to the source directory where the packaging tool runs, and then deletes the tar file.
#cp output/showtime.tar /tmp/proj_dir/src#cd /tmp/proj_dir/src#tar xf showtime.tar#rm showtime.tarPrepackaging of the CLI plug-in is now complete.
The next stage is packaging. See the "Packaging a CLI Plug-in Application" section.
Packaging a CLI Plug-in Application
Check that the CLI plug-in prepackaged files have been copied into the /source/showtime/build directory. (See the "Prepackaging the CLI Plug-in: Example" section.) If the CLI plug-in's prepackaged files are in a tar file, extract them to the package directory. For example, use the following command to untar the showtime.tar file:
tar xvf showtime.tar -C /source/showtimeapp/build
Note
To package the application, see the "Packaging the Application" section and the "Packaging Tool" section.
The CLI plug-in can be installed on Cisco AXP with or without the application:
Package the CLI Plug-in Separately from the Application
•
•
•
or
Bundle the CLI Plug-in with the Application
•
•
•
Installing a CLI Plug-in Application
To install the CLI plug-in application, see the "Installing and Upgrading Software" section in the Cisco AXP User Guide.
Activating a CLI Plug-in Application
To invoke a CLI plug-in application on the service module, in application service EXEC mode:
app-service <application name>To invoke a CLI plug-in command, see the "CLI Plug-in Invocation" section in
the Cisco AXP User Guide.Activating a CLI Plug-in Application: Example
In the "Show Time Application: Example" section a plug-in for the command show time is created. To invoke this CLI plug-in:
app-service showtimeTo display current time on the Cisco AXP service module:
show timeXML DTD File
A CLI command for a CLI plug-in written by a third-party is defined using XML. The XML must conform with an XML Document Type Definition (DTD) file. The DTD file allows you to plug a CLI plug-in application into the Cisco AXP CLI server.
For an explanation of how to define a CLI command using an XML DTD file, and the individual action classes invoked for the CLI command, see the "CLI Plug-in Applications" section.
To find out more about DTD files the following website provides some general information: http://www.w3schools.com/dtd/default.asp.
DTD Introduction
In a DTD, the declarations for elements, attributes, and entities are prefaced in the same way, with an opening angle bracket followed by an exclamation mark: <!. After the exclamation mark comes one of three keywords written in all capitals—ELEMENT, ATTLIST, or ENTITY—that specify the type of declaration.
The syntax of the ELEMENT is:
<!ELEMENT element-name (child1,child2,...)>, where child1, child2 are child elements of element-name.
The syntax of ATTLIST is:
<!ATTLIST element-name attribute-name attribute-type default-value>The ATTLIST keyword is followed by the name of the element element-name for which the attributes are being defined and the list of attributes.
Occurrence Operators
The child elements of ELEMENT are shown above as: "(child1,child2,...".
The element child1 indicates there is exactly one occurrence of the child1 element. Use the following operators to control if an element is optional and how many elements occur together.
•
•
•
Element Choice
You may nest a choice of elements by placing them in parentheses and separating them by a vertical bar. For example, (e1|e2) indicates an occurrence of either element e1 or element e2.
CLI DTD
The CLI DTD file is used to define the format of the XML that specifies a CLI command. This DTD file is tools/custom_cli/cli_grammar.dtd , within the Cisco AXP SDK.
<?xml version="1.1" encoding="UTF-8" ?><!ELEMENT cli_grammar (mode)+><!ELEMENT mode (pattern, (cmd)*)+><!ELEMENT pattern (#PCDATA)><!ATTLIST pattern type (id|regex|help) "id"><!ELEMENT cmd ((pattern,(help)?), ((param)*),action)><!ELEMENT help (#PCDATA)><!ELEMENT param (pattern,(help)?)+><!ELEMENT action ((class)?, (interrupt-timeout)?)><!ATTLIST actiontype (default) "default"paginate (yes|no) "no"pipehelp (yes|no) "no"><!ELEMENT class (#PCDATA)><!ELEMENT interrupt-timeout (#PCDATA)>Elements and Attributes
The elements and attributes of the CLI DTD are explained as follows:
•
•
•
•
•
cli_grammar
The cli_grammar element defines the top level document type for CLI XML files. All CLI XML files must start by declaring this element and specifying the "cli_grammar.dtd" definitions file.
<!ELEMENT cli_grammar (mode)+>Each cli_grammar element consists of one or more mode elements.
<!DOCTYPE cli_grammar SYSTEM "cli_grammar.dtd"><cli_grammar><!-- The contents of the CLI XML file are place here --></cli_grammar>mode
<!ELEMENT mode (pattern, (cmd)*)+>There are one or more mode elements. Applications must define at least one mode element within the XML file. The mode element defines the CLI mode to which the subsequent XML elements will apply.
Each mode element contains one pattern element and zero or more cmd elements.
The pattern element has two type attribute values: exec and config, which represent the two common CLI modes.
mode: Example
<cli_grammar><!-- Place valid mode elements here --><mode><pattern type="id">exec</pattern>...</mode>...<mode><pattern type="id">config</pattern>...</mode></cli_grammar>pattern
<!ELEMENT pattern (#PCDATA)>There is one pattern element, containing parsed character data (#PCDATA).
The parsed character data in the pattern element defines a name string used by the CLI for token matching. The pattern element is used within two different elements in the CLI XML:
1.
2.
CLI mode
In the case of a pattern element defined within the mode element, the name specified in the pattern element defines the name of the CLI mode to which the subsequent XML elements apply. The following example uses the pattern element to declare the CLI "exec" mode.
CLI mode: Example
<cli_grammar><mode><pattern>exec</pattern><!-- Place additional mode elements here --></mode></cli_grammar>CLI Token String
The pattern element can also be declared within the cmd element. The pattern declares the token string to be matched by the CLI parser.
The following example shows the pattern element is used to declare the CLI token string "show". The "show" command is used in "exec" mode. The CLI server looks for an exact match of the token string defined in the pattern element.
CLI Token String: Example
<cli_grammar><mode><pattern>exec</pattern><cmd><pattern>show</pattern></cmd><!-- Place additional mode elements here --></mode></cli_grammar>type
type is an attribute of the pattern element.
<!ATTLIST pattern type (id|regex|help) "id">type has three possible values which describe the pattern:
1.
As "id" is the default attribute value, the following two DTD pattern element definitions are identical:
<pattern type="id">trace</pattern>
<pattern>trace</pattern>
2.
pattern type="regex">[abc]</pattern>
3.
type attribute: Example:
<cli_grammar><mode><pattern>exec</pattern><cmd><pattern type="id">show</pattern><pattern type="regex">[abc]</pattern><!—Specifies the help WORD for display in place of the regex --><pattern type="help">A-B-C</pattern><help>Select A or B or C</help></cmd></mode><!-- Place additional mode elements here --></cli_grammar>Enter show? to display:
A-B-C Select A or B or C
help
<!ELEMENT help (#PCDATA)>There is one occurrence of the help element, containing parsed character data (#PCDATA).
The element help defines the position sensitive help text that will appear on the console in response the `?' entered at the command line. The help element is associated with the previous pattern element in the CLI XML. We recommend that every pattern element have an associated help pattern specified to provide meaningful online help information.
The following lines show the help that appears for the exec mode command "show user".
hostname> ?show Show running system informationhostname> show?
user Display user informationhostname>The XML supporting the above help output is:
<cli_grammar><mode><pattern type="id">exec</pattern><prompt></prompt> <!--no prompt for exec mode--><cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">user</pattern><help>Display user information</help></param></cmd></mode><!-- Place additional mode elements here --></cli_grammar>param
<!ELEMENT param (pattern,(help)?)+>There are one or more param elements, with one child pattern element and
zero or one child help elements.The param element defines keywords/tokens on the CLI command line in addition to the primary keyword. Each cmd element defines a complete CLI command line which will consist of the primary keyword pattern element optionally followed by zero or more param elements each specifying their own keyword pattern elements.
The following example has the minimum number of definitions required to construct the EXEC mode command line "turn on the lights".(To make the example easier to understand, help elements, as well as optional elements and attlists have been removed.) Note that the primary keyword is defined by:
<pattern type="id">turn</pattern>prior to the param elements which define the remaining keywords on the command line.
<cli_grammar><mode><pattern type="id">exec</pattern><prompt></prompt> <!--no prompt for exec mode--><cmd><pattern type="id">turn</pattern><param><pattern type="id">on</pattern></param><param><pattern type="id">the</pattern></param><param><pattern type="id">lights</pattern></param><action><class>com.home.lights.exec_lights_on</class></action></cmd></mode><!-- Place additional mode elements here --></cli_grammar>cmd
<!ELEMENT cmd ((pattern,(help)?), ((param)*,action)>The cmd element contains an optional child help element, zero or many param elements, and one action element.
The cmd element is the core building block for the CLI command definition. The cmd element is used to construct CLI parser nodes within the CLI server. The type of CLI parser node and the node's behavior is derived from the child elements of the cmd element.
cmd: Example 1
Defines the CLI command "show user database" and a CLI eval( ) handler to the com.cisco.aesop.cli.commands.exec_show_user_database.class class.
The CLI server is instructed to enable pagination during the formatting of the output of the command and the CLI server is instructed to enable the use of the pipe "|" text search mechanism. Refer to the paginate attribute within the action element.
<cli_grammar><mode><pattern type="id">exec</pattern><prompt></prompt> <!--no prompt for exec mode--><cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">user</pattern><help>Display user information</help></param><param><pattern type="id">database</pattern><help>Display all the CLI commands</help></param><action paginate="yes" pipehelp="yes"><class>com.cisco.aesop.cli.commands.exec_show_user_database.class</class></action></cmd></mode><!-- Place additional mode elements here --></cli_grammar>cmd: Example 2
This example defines a CLI configuration command "hostname <name>". It defines the CLI eval( ) handler for this CLI command to be class com.cisco.aesop.platform.conf_hostname.class.
The hostname entered at the command line is accepted as a regular expression meeting the rule defined below, and a "?" help response is provided for each keyword on the command line including the regular expression.
<cli_grammar><mode><pattern type="id">config</pattern><prompt>(config)</prompt><cmd><pattern >hostname</pattern><help>set the system name</help><param><pattern type="regex">[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]/pattern><pattern type="help">name</pattern><help>hostname not including the domain</help></param><action><class>com.cisco.aesop.platform.conf_hostname.class</class></action></cmd></mode><!-- Place additional mode elements here --></cli_grammar>action
<!ELEMENT action ((class)?, (interrupt-timeout)?)>One action element contains an optional class and optional interrupt-timeout element.
The element action defines the action the CLI server will take when a CLI command match is declared by CLI parser.
type
type is an attribute within the action element.
<!ATTLIST action type (default) "default" paginate (yes|no) "no" pipehelp (yes|no) "no">The type attribute currently only supports the default attribute-type.
The type attribute may be expanded in the future to support additional action element types. At present, you can leave the type attribute out of the CLI XML action element definitions.
paginate
paginate is an attribute within the type element.
<!ATTLIST action type (default) "default" paginate (yes|no) "no" pipehelp (yes|no) "no">The paginate attribute instructs the CLI server to format the text output from the action class eval( ) handler method. The CLI server breaks the output text stream every 24 lines and displays the "-- More --" message to the user. The user can then press any key to display the next page of output.
paginate: Example
The following example shows how to create a command ("show parser commands") which specifies pagination of the output. The command invokes the eval( ) method in the handler class com.cisco.aesop.cli.commands.show_commands.class.
<cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">parser</pattern><help>Display parser information</help></param><param><pattern type="id">commands</pattern><help>Display all the CLI commands</help></param><action paginate="yes"><class>com.cisco.aesop.cli.commands.show_commands.class</class></action></cmd>pipehelp
pipehelp is an attribute in the type element.
<!ATTLIST action type (default) "default" paginate (yes|no) "no" pipehelp (yes|no) "no">The action element supports the pipehelp attribute. The pipehelp attribute instructs the CLI server to add the pipe `|' token to the end of the command line. The pipe filters the text that is output from the eval( ) method in the handler class. (The handler class in the example below is com.cisco.aesop.cli.commands.show_commands.class.)
Pipe filters:
•
•
•
•
pipehelp: Example
This example shows how to create a command which will implement the pipe feature.
The following example command is "show parser commands".
<cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">parser</pattern><help>Display parser information</help></param><param><pattern type="id">commands</pattern><help>Display all the CLI commands</help></param><action pipehelp="yes"><class>com.cisco.aesop.cli.commands.show_commands.class</class></action></cmd>Example:
hostname> show parser commands | ?begin Begin with the line that matchesexclude Exclude lines that matchinclude Include lines that matchpage Paginate output (--More--)The output from "show parser commands" is piped through one of the filter types: begin, exclude, include, or page.
Example:
hostname> show parser commands | begin "d""show parser commands" invokes the eval( ) method in the handler class com.cisco.aesop.cli.commands.show_commands.class.
Each line of the output from the command is piped through "begin" filter type—in this example, only allowing commands starting with the letter "d".
class
<!ELEMENT class (#PCDATA)>The class element, which is a child of the action element, specifies the handler class containing the eval( ) function/method invoked when the corresponding CLI command is recognized by the CLI parser. The name of the handler class contains the fully specified domain and class name (for example, com.cisco.aesop.service.handler.class). As a naming convention, we recommend that the mode of the CLI command is included in the class name. This prevents name-space collisions. For example, the "exec" mode is part of the name of the following class: com.cisco.aesop.service.exec_handler.class
class: Example
This example shows the class element used within the action element to define the eval( ) handler for the CLI command. The CLI command is "show users", and the class element is com.cisco.aesop.exec_show_users.class.
<cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">users</pattern><help>Display user information</help></param><action><class>com.cisco.aesop.exec_show_users.class</class></action></cmd>interrupt-timeout
<!ELEMENT interrupt-timeout (#PCDATA)>The interrupt-timeout element overrides the interrupt-timeout for this action. The parsed character data evaluates to an integer specifying the duration (in minutes) of the interrupt-timeout.
The following example is very similar to the class: Example, except for the interrupt-timeout element that sets interrupt-timeout to 10 minutes.
<cmd><pattern type="id">show</pattern><help>Show running system information</help><param><pattern type="id">users</pattern><help>Display user information</help></param><action><class>com.cisco.aesop.exec_show_users.class</class><interrupt-timeout>10</interrupt-timeout>d></action></cmd>
Type Regex
In the pattern tag, type= `regex' defines the contents as being a regular expression conforming to the
Perl 5 regex standard. See http://perldoc.perl.org/perlre.html for Perl 5 regex documentation.Regex definition examples:
Example 1: A 1 or 2 digit number from 0 to 99.
<pattern type='regex'>[0-9][0-9]?</pattern>Example 2: An alphanumeric string.
<pattern type='regex'>[a-zA-Z0-9]*</pattern>Example 3: An HTTP URL.
<pattern type='regex'>http://[-*.+:@?=a-zA-Z0-9/_]*</pattern>CLI Plug-in Action APIs
CLI plug-in action scripts or classes, supported by the distribution service, are written as C classes, Java classes, and Bash shell scripts. The API of the scripts/classes is provided by the eval( ) method (for Java), or the eval( ) function (for C).
After the user enters a CLI command, a CLI plug-in action corresponding to that particular command is invoked. The CLI plug-in action interacts with the application. For further details of the necessary CLI plug-in actions, application, and DTD, see the "CLI Plug-in Applications" section.
The CLI plug-in action API is implemented by using the eval( ) method or function. Compile the API calls into the appropriate C libraries or Java classes.
The required APIs for the action class, in Java, C, or Shell script, are described below:
Java
The action class must implement the eval( ) method.
Compile Java action classes into files with a name format of <action_name>.class. The class can be in a namespace hierarchy; for example, com.xyz.myclass.class. The hierarchical class name must be defined in the XML definition for the CLI plug-in: see the class element of the "Elements and Attributes" section.
C
The action class must implement the eval( ) function.
Compile C action classes into a shared library with the name <action_name>.so.
Shell script
Shell scripts are directly executed using a C system call.
Since a shell script can only return an integer value indicating its exit status, there is no support for a shell script to pass back messages displayed on the CLI console.
The APIs use the following terms:
•
•
•
•
The eval and evalError action APIs are shown below for Java, C, and Bash.
•
Note
eval: CLI plug-in Action API
Invokes a CLI command.
The example Java code MyTime.java, includes a call to the eval( ) method. It is similar to the Java code shown in the CLI plug-in of Figure 8.
Parameters:
tokens[] - the space delimited string of tokens entered by the CLI user, split into an array, e.g. "sho tim" is {"sho", "tim"}grammar[] - the space delimited string of grammar matching the tokens, split into an array. This grammar list is defined in the custom CLI definition, e.g. "show time" is {"show", "time"}Returns:
String[] - a String array containing 2 Strings. The first String is the return status: "0" - succeed, non-zero - failed. For config CLIs, the failed return status is not saved. The second String is the return display. The rest of the list is ignored. For example, {"0", "Tue, 07 Aug 2007 16:20:36"}Example:
eval({"sho", "tim"}, {"show", "time"});returns the following:{"0", "Tue, 07 Aug 2007 16:20:36"}
evalError: CLI plug-in Action API
Supporting the no Prefix
Consider the following syntax:
>set timeout [0-9][0-9]?The command may be prefixed with no, for example:
>no set timeout 10The no prefix is automatically supported for all configuration CLIs and is appended in front of the CLI tokens in the tokens array.
In the following example, the CLI plug-in action receives the items shown in these Grammar and Tokens arrays:
Grammar:
set timeout [0-9][0-9]?Tokens:
no set timeout 10CLI Plug-in Distribution Listener APIs
An application starts the CLI plug-in distribution service by calling the CLI plug-in distribution listener to start within the application's main program.
Starting the distribution listener allows the CLI actions to be invoked within the same program space as the main program.
The CLI plug-in distribution listener can be started in a Java, C or shell script. Depending on the language being used, the code invokes one of the following APIs in its main program.
The following Java code snippet shows the call to the startCLIDistributionVMThread( ) method.
The following C code snippet shows the call to the start_cli_distribution_vm_thread( ) function.
The following shell script snippet shows the call to cli_distribution_vm.
CLI Plug-in Errors
Action classes communicate the return status of a command to the Cisco AXP server. The return status informs the server if the command succeeded or failed at execution. Action classes use a return string to communicate messages that must be displayed by the console to the user.
The return string is only supported in C and Java action classes.
The return status is supported by C action classes, Java action classes, and shell scripts.
Error messages are displayed on the CLI console when any of the following conditions are true:
•
•
•
A header in the error message indicates that the message is displayed by the CLI plug-in service.
Interrupting Action Invocation
The user of a CLI plug-in can interrupt action invocation by pressing Ctrl-C.
You have the option to implement an interrupt handler to handle the Ctrl-C interrupt for action classes. The interrupt handler is only available for C, and Java. See the "evalError: CLI plug-in Action API" section. The interrupt handler is action-specific—the handler only applies to a particular action class.
•
•
An action without an interrupt handler is dealt with by the CLI Distribution Listener. The listener uses a system call to stop the thread that is executing the eval( ) function.
The interrupt handler may become stuck. A rescue timer monitors the invocation of the interrupt handling, with a default value of 5 minutes. To change the timer value, change the interrupt-timeout in the XML definition file. The definition file is explained in the "Elements and Attributes" section. If the rescue timer detects a timeout, interrupt handling is regarded as having failed. If interrupt handling fails, the CLI Distribution Listener handles the interrupt.
Table 16 describes the different scenarios for interrupt handling.
Simultaneous CLI plug-in Invocation
Multiple CLI sessions can be opened by a user. However, simultaneous CLI plug-in invocation to the same CLI Distribution Listener is not supported. When the CLI Distribution Listener is processing one CLI plug-in (that is, a CLI plug-in action is being invoked and has not yet returned), the listener blocks any new CLI plug-in request. Users see a message displayed on the CLI console saying that the CLI plug-in request is blocked, try again later.
CLI Plug-in Application: Example
The development of simple CLI plug-in applications is shown in the following sections.
•
Health Status
We recommend that the health status is coded in an application in order for the show state cli command to show your application's health status.
If health status is not coded in an application, when the show state command is issued, the reported health status of an application is shown as dashes "---".
show state command (where the Application Health Status is not Coded): Example
my-javalin> app-service helloworldmy-javalin(exec-appservice)> show stateAPPLICATION STATE HEALTH
helloworld online ---
Package Name
You must determine the package name for your application. The same package name must be used in the following three places:
1.
2.
3.
Show Time Application: Example
A custom command is defined by an XML definition file and an action script. You can create code for the custom command, package it with your application, and then import it into Cisco AXP.
As an example, consider an application which has to respond to a user request to display the time using the command show time. (The user request is shown as step 3 in Figure 9.)
To develop the "show time" example, perform the following steps.
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Figure 9 describes the sequence of events when the showtime CLI plug-in application runs on the Cisco AXP CLI server.
Figure 9 CLI Plug-in Application: Example
XML Script: Example
Use the XML DTD to write an XML definition file. For further information on XML DTD definitions, see the "XML DTD File" section.
The following code script, MyTime.xml show time.
<?xml version='1.1' encoding='UTF-8' ?><!DOCTYPE cli_grammar SYSTEM "cli_grammar.dtd" ><cli_grammar><mode><pattern type="id">exec</pattern><cmd><pattern type="id">show</pattern><help>show time</help><param><pattern type="id">time</pattern><help>show current time</help></param><action><class>MyTime.class</class></action></cmd></mode></cli_grammar>When the user enters command show time, Java action class MyTime.class is called.
Action Class: Example
MyTime.java returns the date and time. The eval() method is the API that accepts the user's CLI command and returns the current date and time. For a further explanation of the eval( ) method, see the "CLI Plug-in Action APIs" section.
/*MyTime.java is a simple CLI Action class that returns the application return code and*the current date/time. If it fails an application return code of 1 is returned along*with the exception message. The static main program can be invoked to easily test the*program independently*/import java.util.Date;import java.text.SimpleDateFormat;/*** Returns the current time of the day*/public class MyTime{public static String[] eval(String[] tokens, String[] grammar){String[] retArray = new String[2];try{if(tokens.length == 2 && grammar[0].tolower().equals("show") &&grammar[1].tolower().equals("time")){Date curTime = new Date();SimpleDateFormat sdf = new SimpleDateFormat("EEE, d MMM yyyy HH:mm:ss");retArray[0]="0";retArray[1]=sdf.format(curTime);}else{retArray[0]="1";retArray[1]="Unknown command";}}catch(Exception e){retArray[0]="1";retArray[1]=e.getMessage();}return retArray;}public static void main(String[] args){String[] tokens = {"show","time"};String[] grammer = {"show","time"};String[] message = eval(tokens,grammer);System.out.println("Exit code: " + message[0] + " Result:" + message[1]);}}The XML script MyTime.xml defines the show time command. See the "XML Script: Example" section.
After compiling and testing the above action class (MyTime.class), store it in file showtime.jar so that it can be easily accessed later. Place the jar file in the /source/showtimeapp directory:
jar -cvf showtime.jar MyTime.classWhen the user enters command show time, this action class MyTime.class processes the command. See the "Action Class: Example" section.
For the class MyTime.class to be called, a listener must be started in your application. See the "Starting a Listener from the Application: Example" section.
Starting a Listener from the Application: Example
Start an application listener using the thread startCLIDistributionVMThread. For example, the following command is used within the application MyAppMgr.
CLIDistributionVM.startCLIDistributionVMThread("showtime");
MyAppMgr gives the health status of the application, and activates a VM thread which listens for the defined show time command. When the user enters the show time command, the application calls the MyTime class.
/** Third party application that reports its health status, starts up the CLI distribution* thread, and then waits.*/import com.cisco.aesop.apphosting.cli_distribution.CLIDistributionVM;import java.io.*;import java.lang.*;public class MyAppMgr{/***Displays and writes passed in message*@param msg: message to be displayed and logged.*@param pw: PrintWriter object*@return nothing**/public void printMessage(String msg, PrintWriter pw){System.out.println(msg);if(pw != null){pw.println(msg);pw.flush();}}/***Sends the health status. Logs exception.*@param name: application package name*@param status: health status*@param pw: PrintWriter object*@return nothing**/public void sendStatus(String name, String status, PrintWriter pw){try{Runtime rt = Runtime.getRuntime();rt.exec("/bin/app_status_notifier " + name + " " + status);}catch(Exception e){printMessage("Send of status failed. Exception " + e.getMessage(),pw);}}//code for testing applicationpublic static void main(String[] args){MyAppMgr mgr = new MyAppMgr();PrintWriter pw = null;try{pw = new PrintWriter(new FileOutputStream(new File("/var/log/showtime.log")));mgr.sendStatus("showtime","INITIALIZING",pw);mgr.printMessage("Starting VM Thread",pw);// The following line starts the listenerCLIDistributionVM.startCLIDistributionVMThread("showtime");Object obj = new Object();synchronized(obj){mgr.sendStatus("showtime","ALIVE",pw);mgr.printMessage("Going into wait mode",pw);pw.flush();obj.wait();}}catch(Exception e){mgr.printMessage("Exception " + e.getMessage(),pw);}finally{mgr.printMessage("Exiting MyAppMgr program",pw);mgr.sendStatus("showtime","DOWN",pw);if(pw != null){pw.close();}}} //end main} //end classBuilding and Testing: Example
Build
[bash]# javac -classpath cli_distribution_vm.jar MyAppMgr.javaAdd this class to file showtime.jar, which allows for easy access later.
jar -uvf showtime.jar MyAppMgr.classTest
For testing, you need access to the following Linux library: liblocal_socket.so.
Copy showtime.jar to directory /source/showtimeapp.
The java command below tests application MyAppMgr. File liblocal_socket.so and jar files are in directory "lib" —one level below the current directory.
Note
Note
[bash]# java -Djava.library.path=lib/ -cp lib/cli_distribution_vm.jar:lib/localsocket.jar:lib/showtime.jar MyAppMgrOutput:
Starting VM ThreadGoing into wait modeCLI_PLUGIN:CLIDistributionVM.receiveIPCMessages: server socket opened successfullyCreate a build directory
Create a directory to hold prepackaged files to be packaged and installed onto Cisco AXP:
mkdir /source/showtimeapp/buildPrepackaging the CLI Plug-in: Example
The following example of prepackaging a CLI plug-in application follows the steps in the "Prepackaging the CLI Plug-in" section.
Step 1
Step 2
Step 3
file=MyTime.xml
javapath=/usr/bin/java/bin
vm=showtime
proj_src=/source/showtimeapp/build
You have the option of whether to change the proj_src argument or not. See proj_src in Table 15.
Step 4
python cli-plugin.py
For further information, see step 4 of the "Prepackaging the CLI Plug-in" section.
Next, move the tar file to the source directory, see the "Moving the tar File: Example" section.
Prepackaging is complete.
Troubleshooting and Logging
This section explains some troubleshooting tips and the main types of logging in the following sub-sections:
•
Note
Troubleshooting Your Application
Debugging Steps
The following debugging steps go through a range of options for debugging your application.
Step 1
app-service <app name>
where <app name> is the name of your application
show process
Shows all processes sorted by process ID in ascending order. See "Viewing Processes" in the
Cisco AXP User Guide. If your application is part of a CLI plug-in application, the application must always be running.Step 2
show state
Step 3
If application health = "ALIVE", then your application is running, go to the end of the steps.
If application state is "---" and your application is coded to provide its health status, go to step 5.
If application health NOT = "ALIVE", then go to step 5.
Step 4
a.
b.
–
–
, where <application name> is the name of your application. The log files contain error messages created by the system.
Look at the log files displayed by one of these two commands. There should be evidence of why the virtual instance did not start. Log files are displayed one page at a time.
Step 5
•
•
, where <application name> is the name of your application. Look at the log files displayed by one of these two commands. There should be evidence of why your application did not start. The log files contain error messages created by your application.
Note
Step 6
trace all
After your process has run, enter:
show trace buffer
Step 7
show interfaces <interface>
vi Editor Troubleshooting
The vi editor does not behave as expected with some terminals. To fix this, run vi with parameter:
-T ansi
Logging
For logging inside a virtual instance, the syslog daemon syslog-ng, adds tracing or logging information to file /var/log/messages.log.
Logging is described in the following sections:
Note
For information about the following topics, see the Cisco AXP User Guide.
•
•
•
•
•
•
Log File Rotation
The Cisco AXP syslog supports log file rotation of two files:
•
•
When the messages.log reaches a limit specified by the limit log-file size command, the file's contents are moved to backup file messages.log.prev and a new messages.log file is started. The default log file size is 20 MB.
You can use the command show logs to display the contents of all log files, and the command show log name to display the contents of a log file in the /var/log directory.
Logging Levels
Cisco AXP supports the following log levels:
•
•
•
•
•
•
•
•
Out of all the log levels that are available to the application, the CLI reduces these to a more manageable number of four log levels.
You can set your log threshold to one of the following values:
•
•
•
•
Logging Usage
Logging on the virtual instance is explained below for either C or Java code:
Log messages go to file /var/log/messages.log in the virtual instance. After the log file reaches its specified limit (set by command limit log-file size), the contents of the log file are moved to a backup log file messages.log.prev. A new messages.log file starts to collect log messages. The default log file size for the log file and the backup log file is 5MB.
C: Syslog
For more information and examples on syslog APIs for C, see the GNU website.
C Syslog: Example
int main(int argc, char* argv[]){setlogmask (LOG_UPTO (LOG_DEBUG));openlog("myapp", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);syslog(LOG_DEBUG, "myapp_user_management.eval() processing a CLI message\n ");}Java: Log4j
For more information on the Log4j package regarding syslog, refer to syslog appender in the log4j documentation at: http://logging.apache.org/log4j/docs/documentation.html.
In Cisco AXP APIs and libraries, logs are redirected to stdout (via System.out.println).
To redirect logs to syslog, pipe the application's output to /bin/logger, as shown in the following example.
Redirect logs to syslog: Example
This example starts application MyAppMain, and uses a CLI plug-in. The stdout of the CLI plug-in and the output from System.out.println calls made by the application are redirected to syslog with a log level of LOG_INFO.
# java -cp ./app_bin/myApp.jar:/cli_comm/:/usr/lib/java/localsocket.jar:/usr/lib/java/cli_distributio n_vm.jar com.myApp.MyAppMain | /bin/logger -p infoTurn on logging: Example
Logger myLogger = Logger.getInstance("myapp");myLogger.debug("myapp_user_management.eval() processing CLI message");Enable syslog appender: Example
# To enable the syslog appender, set the root logger level to DEBUG and an appender to mySyslog.log4j.rootLogger=DEBUG, mySyslog, myFile, myConsole# appender definitionslog4j.appender.myConsole=org.apache.log4j.ConsoleAppenderlog4j.appender.mySyslog=org.apache.log4j.net.SyslogAppenderlog4j.appender.myFile = org.apache.log4j.RollingFileAppender# myConsole configlog4j.appender.myConsole.layout=org.apache.log4j.PatternLayoutlog4j.appender.myConsole.layout.ConversionPattern=%p %t %c - %m%n# mySyslog configlog4j.appender.mySyslog.layout=org.apache.log4j.PatternLayoutlog4j.appender.mySyslog.layout.ConversionPattern=%p %t %c - %m%nlog4j.appender.mySyslog.SyslogHost=localhostlog4j.appender.mySyslog.Facility=USERlog4j.appender.mySyslog.threshold=INFO# myFile configlog4j.appender.myFile.File = example.loglog4j.appender.myFile.MaxFileSize = 100KBlog4j.appender.myFile.MaxBackupIndex=1log4j.appender.myFile.layout=org.apache.log4j.PatternLayoutlog4j.appender.myFile.layout.ConversionPattern=%p %t %c - %m%Syslog Server Logging
To log messages to the host syslog server, use the syslog server feature. For example, messages can be logged from a workstation to the host syslog server.
Logging messages to the host syslog server for either C or Java code, is explained in the following sections.
C: Syslog Server
In C programs, to direct log messages to the host syslog server, configure the syslog server config file, located at either /etc/syslog.conf, or /etc/syslog-ng.conf. These location names apply if the virtual instance's syslog server is syslog-ng. See the "Logging" section.
Redirect: Example
To redirect all log messages with facility= "local1", and priority value of "info" or higher, append the following line to the syslog server config file:
local1.info @mybladeJava: Syslog Server
In Java programs, to direct log messages to the host syslog server, edit the log4j.properties file in the log4j package (see the "Java: Log4j" section). For example,
log4j.rootLogger=DEBUG, mySyslog# mySyslog configlog4j.appender.mySyslog.layout=org.apache.log4j.PatternLayoutlog4j.appender.mySyslog.layout.ConversionPattern=%p %t %c - %m%nlog4j.appender.mySyslog.SyslogHost=myblade/* Note the SyslogHost is "myblade" compared to "localhost" used by logging in the virtual instance */log4j.appender.mySyslog.Facility=USERlog4j.appender.mySyslog.threshold=INFOIn addition to changing your application code, commands must be issued on the Cisco AXP service module to run the host syslog server:
blade# config terminal(config)# syslog-serverTo show the remote syslog server status:
blade# show syslog-serverSyslog ServerStatus: RUNNINGTo configure the number of files for rotation and the file size:
blade# config terminal(config)# syslog-server limit file-rotation 2 file-size 500file-rotation has a value from 1 to 40, with a default of 10.
file-size has a value from 1 to 1000 MB, with a default of 20 MB.
Packaging Tool
This section explains how to use the packaging tool to package your applications before installing the packages on the application service module.
This tool requires that the third party application has development authorization from Cisco and can access private keys for signing the application. Specify parameters to the packaging tool in single command line mode (batch file) or in interactive mode.
Note
>echo $PATH
For example, a path similar to the following path value is displayed:
>/bin:/sbin:/usr/bin:/usr/local/sbin:/usr/sbinCall the packaging tool command (pkg_build.sh) using one of the following two modes:
1.
2.
Note
The values supplied to the packaging tool determine the resources allocated to the packaged application when the package is installed. The only way to change the resource allocation is by re-packaging.
Upgrading
When you are upgrading an application, there are three arguments/parameters of the packaging tool to consider:
1.
2.
3.
Other arguments include: deps, disk-limit, and cpu-limit. Details of these arguments are found in the following sections.
Note
Note
Packaging Tool Arguments
The arguments to the packaging tool are described in Table 17.
Note
Table 17 Packaging Tool Arguments
project-dir
Project directory
Contains package files, templates, and temporary files created during packaging.
/xyz_src/empty_app/package
auth-bundle
Authorization bundle
File containing authorization details that allow your application to run on the target application service module. (Replaces dev-cert and dev-auth parameters from AXP 1.1 or higher.)
/xyz_src/auth_bundle.sig
private-key
Location of private key file
File containing the RSA key that is used to sign the application third party software.
/xyz_src/privkey.txt
name
Name of application
Name of the packaged application.
myapp
version
Version of application
Version of the packaged application.
1.1
description
(Optional) Description of application
Description of the application's function.
myapp utility
uuid
(Optional) Unique identifier of the application
1. You can enter a uuid value; for example a uuid generated using the Linux "uuidgen" tool. This is what we recommend. or
2. You can leave the uuid as blank: an ID is automatically generated.
25773fde-b599-459c-b0fa-5be90cc73a2f
source-dir
Location of application files
Directory that contains application files to be packaged. The directory structure must mirror the desired directory structure on the target file system.
/xyz_src/empty_app/build
protect
(Optional)
List of files to be protectedPlain text file containing a list of files (one file per line) that are checked for signs of alteration before application initialization.
deps
(Optional) Package Dependencies
ssid for each of the packages that the application is dependent upon. For example, tomcat add-on package. See Dependencies.
f463dc25-4749-48bd-b08c-25d8939c068b,all
disk-limit
Disk Limit
Minimum disk space required by the application.
10M
memory-limit
Memory Limit
RAM usage limit. Consider the target hardware resources when selecting a memory-limit. The application might fail to install or run if the requested amount of resources are not available on the target hardware (1M = 1048576 bytes.)
10M
cpu-limit
CPU Limit
CPU resources utilized by the application. Based on CPU index, not percentage utilization. Must be greater than 100.
200
swap
(Optional)
Swap SpaceON: Enable swap after reboot
OFF: Disable swap after reboot.
ON
postinstall
(Optional) Postinstall script
Script to run after installation. For example, it is useful to have a postinstall script to gain console access and then modify the package. The script must be packaged with the application.
Specify the location of the script using a relative path with respect to the common root directory. For example, if script postinstall.sh is in directory /xyz-source/build/bin, and the common root directory is /xyz-source/build, specify the location of the script as /bin/postinstall.sh
/bin/postinstall.sh
cap-config
(Optional)
Capabilities Configuration FileThe capabilities configuration file can relax certain restrictions in the virtual instance by configuring capabilities that have been granted by the development authorization file.
disk-wildcard
(Optional)
Disk wildcard.Grants extra disk resources to an application if those resources are available.
y
memory-wildcard
(Optional)
Memory wildcard.Grants extra memory resources to an application if those resources are available.
y
cpu-wildcard
(Optional)
CPU wildcard.Grants extra CPU resources to an application if those resources are available.
y
Packaging Tool: Example
echo $PATH//the next line shows example output/bin:/sbin:/usr/bin:/usr/local/sbin:/usr/sbinpkg_build.sh --project-dir '/xyz-src/package' --auth-bundle '/xyz_src/auth_bundle.sig' --private-key '/xyz_src/private.key' --name 'showtime' --version '1.4' --description 'showtime test' --uuid 'd1b4aef6-eb03-47a6-a537-324b76794a00' --deps 'b4b0ee92-cf8e-472b-8434-e8e7412ec71a,all' --source-dir '/xyz-src/build/' --disk-limit `100M' --memory-limit `128M' --cpu-limit `200' --swap 'ON'--postinstall 'bin/post-install.sh' --memory-wildcard --cpu-wildcard --disk-wildcardDependencies
The parameter for a list of dependencies (deps) consists of a selection of available packages from the Cisco AXP SDK and project directories. When you list a package that already exists on the development workstation, you can specify the UUID and filename of the package. After each dependency, the user must specify one of the following dependency types:
•
•
•
•
•
•
Version
Each application package has a version number, which is used by the installer when resolving dependencies between subsystems.
For dependency checking only the first two digits of the version number are checked.
The first digit is treated as the Major version number. The second digit is treated as the Minor version number.
For example, version 1.2.3.4 has a major number of 1 and a minor number of 2, and is treated the same as version 1.2, or version 1.2.3 in dependency checking.
List of Dependencies: Syntax
[Dependency List] => (One or more colons (":") separated [Dependency String] [Dependency String] => [Dependency UUID],(One or more comma (",") separated [Dependency Type] [Dependency Type] => [to/from/exclude/only/none/all](=[version])
List of Dependencies: Example
--deps 'cc1b5b06-6b17-42c9-b9dd-88c29674b390,from=1.0,to=2.0: b569b32d-1b5b-4306-8eb6-c7d6808aa7b6,only=3.0'Disk Limit
When calculating disk-limit, consider the disk space required by the following components: application package (not including the disk space used by packages from Cisco), log files, and core dumps.
The disk limit is the minimum disk space required for the application. When disk resources falls below this limit, you will not be able to install the application. The disk limit must be specified in megabytes, for example 1M.
CPU Limit
The cpu-limit argument for the packaging tool sets the CPU utilization of the application package measured in CPU index points.
The cpu-limit is the minimum CPU limit for the application. The minimum CPU limit specifies the minimum amount of CPU resources allocated for the application. When the available CPU resources on the target service module fall below the CPU limit, you will not be able to install the application.
The CPU index for the service module is a known value, calculated using a benchmark. A more powerful service module will have a higher CPU index and will be able to accommodate a higher number of concurrent applications. For further information, see the "Dedicated Application Resources" section.
A CPU index is assigned to each service module based on the power of the CPU. The application's CPU index is then calculated, based on the following formula:
Application CPU index = CPU Index(of service module) * CPU usage%
For example, the NME APPRE 302 service module has a CPU index of 10000. Each service module has a CPU index relative to a value of 10000. If an application requires 60% CPU utilization, the applications's CPU index is 10000 * 60% = 6000. Supply this value as the cpu-limit argument.
The advantage of knowing the application CPU index is that the application package can be installed on other service modules, and you know it will run successfully if the module has enough CPU resources.
Bundling Tool
Bundling is a method of compiling packages into a single package. This package is called a bundle. For bundling, use the bundling tool pkg_bundle.sh with the arguments described in Table 18.
Note
This section contains the following sub-sections:
•
Note
Bundling Tool Arguments
Note
Use the bundling tool by entering a single command line with a list of arguments. See Table 18.
Table 18 Bundling Tool Arguments
help
Version and usage
project-dir
Project directory
Stores generated package files, templates, and temporary files created during packaging in a sub-directory given by adding the project-dir parameter and "/pkg". See the "Bundling Tool: Example" section.
private-key
Location of private key file
File containing the RSA key used for security headers and package specification.
output
Output package
List of packages. The first name contains the name of the combined package "bundle". If the path name is not included or is invalid, the package is written to directory: project-dir/pkg. Second and subsequent names in the list of parameter values following "output" are the names of other packages forming the bundle. Payload files such as prt1, prt2 should be located in the same directory as their corresponding package files.
Bundling Tool: Example
In the following example, the two packages iosapi_test.1.1.pkg and axp-iosapi.nme.1.0.4.pkg are bundled together into package iosapi_test_bundle.1.0.4.pkg. The bundle is placed in project directory /iosapi_app/package/pkg if you specify the directory /iosapi_app/package (note no "/pkg" at the end) in the --project-dir parameter.
/axp-sdk.1.0.4/tools/pkg_bundle.sh --project-dir '/iosapi_app/package' --private-key '/certs/private.key' --output 'iosapi_test_bundle.1.0.4.pkg' '/iosapi_app/package/pkg/iosapi_test.1.1.pkg' '/bryce/axp-iosapi.nme.1.0.4.pkg'Bundles Including the Cisco AXP Host OS
Note
To install bundles including the third party signed add-on applications onto the service module, including the Cisco AXP host OS, use the commands software install clean, or software install upgrade.
To install a bundle onto the application service module where the bundle does not contain the Cisco AXP host OS, and contains a third party signed add-on package, use the command: software install add.
The following sections explain some dependencies and also show bundles with or without the Cisco AXP Host OS:
•
•
Dependencies
The following dependency is permitted:
A third party signed add-on package depending upon both a Cisco signed add-on package and a third party application package.
The following dependencies are not permitted:
•
•
•
•
Bundles Including the Cisco AXP Host OS
The following is a list of possible bundles including Cisco AXP host OS:
•
•
•
•
Note
Note
Bundles not Including the Cisco AXP Host OS
Examples of bundles not including the Cisco AXP host OS:
•
•
–
–
–
•
For dependency limitations of third party add-on packages, see the "Dependencies" section.
Additional References
"Installing and Upgrading Software" section in the Cisco AXP User Guide.
Cisco AXP Emulation using VMware
The Cisco AXP platform can run as a virtual appliance under VMware. You can use the VMware Player, which runs under multiple x86 operating systems, to run your application and Cisco AXP infrastructure add-on packages. 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
Note
Virtualization with VMware is explained in the following sections.
Note
VMware System Requirements
The system requirements for using Cisco AXP emulation on VMware are:
•
•
•
•
Configuring VMware
Prerequisites
•
•
The Cisco AXP VMware environment package axp-k9.vmw.1.1.1.tar.gz contains the VMware configuration and virtual appliance package.
To configure Cisco AXP to use VMware:
Step 1
Note
Step 2
Step 3
Step 4
Step 5
Step 6
The VMware session panel opens.
Step 7
localhost>
Step 8
a.
b.
c.
d.
Example: In this example, the hostname is JOV.
localhost> config tlocalhost(config)> hostname JOVJOV(config)> interface eth0JOV(config-interface)> ip address 128.104.28.7 255.255.255.0JOV(config-interface)> exitJOV(config)> ip route 0.0.0.0 0.0.0.0 128.104.28.1JOV(config)> router ip address 172.168.24.102JOV(config)> exitJOV> wr memJOV>At this point the session for Cisco AXP Emulation using VMware is configured and you are able to install add-on packages on the virtual system.
In addition to VGA console access, Cisco AXP server CLI access is also possible using SSH.
See the section Secure Shell Access to the Service Module 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 acquire 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
To obtain a license for Cisco AXP Emulation using VMware, contact your Cisco marketing representative to obtain an authorization file. Cisco AXP Emulation using VMware is available for evaluation purposes only and is not supported by Cisco Technical Support
Cisco AXP API Support
All Cisco AXP APIs are supported on VMware with the exception of the Promiscuous Packet API (for packet monitoring)—see Note below.
The add-on package APIs for AIM and NME modules are listed in the Cisco AXP Release Notes.
Note
Debugging and Troubleshooting Enhancements
The following enhancements to debugging and troubleshooting are available:
•
•
Note
Integrating Log Files into the Host OS
Files in /var/log directory of the guest OS are bundled using copy log bundle command and the files are copied to an external server.
Guest
