AXP 1.6 Developer Guide
Cisco AXP Features
Downloads: This chapterpdf (PDF - 441.0KB) The complete bookPDF (PDF - 9.62MB) | Feedback

Cisco AXP Features

Table Of Contents

Cisco AXP Features

Hosting Infrastructure

Virtualization

Virtual Instances

Dedicated Application Resources

CPU and Memory Resources

Displaying CPU Information for Multi-core Systems

Application Packaging

Core System Package

Cisco AXP Add-on Packages

Third Party Application Packages

Cisco AXP Certificates

Guest Operating System

Application Startup

Preparing for Automatic Startup

Referencing Environment Variables (Optional)

Setting Up the init Process

Automatic Startup

Manual Startup

Accessing the Guest Operating System

Application Development Package

Postinstall Script

Cisco AXP Virtual Instance Operating System

Application Status Reporting

Application Status Monitoring using Watchdog Scripts

Status Monitor

Logging Support

IOS Events

Cisco AXP Optional Features

Optional Features Table

NFS Client

Using the NFS Client in an Application

Setting up Access to the NFS Server from the Guest OS

Displaying the Mount Points for an NFS Server

Determining the Status of the NFS Server

Application Monitoring of the NFS Server

Remote Serial Device

Developing an Application Using a Serial Device

Time Zone

Development System Requirements

Running Cisco AXP on the Application Service Module

Swap Space and Memory Allocation

Swap Space Off

Swap Space On


Cisco AXP Features


Cisco AXP's Linux-based hosting infrastructure allows open source software to be used for application development. The hosting infrastructure installs and runs applications in separate security contexts using the Cisco AXP Virtual Instance Manager. These security contexts use a common Linux kernel and 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 service modules.

This chapter consist of the following sections:

Hosting Infrastructure

Virtualization

Dedicated Application Resources

Application Packaging

Guest Operating System

Cisco AXP Optional Features

Development System Requirements

Swap Space and Memory Allocation

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 shows the relationship between Cisco AXP service module and Cisco ISR. For a list of different service modules, see Table 1.


Note The NME-APPRE-522-K9 service module is not supported on Cisco ISR G2 router 2911 and 2921. It is supported on Cisco ISR G2 router 2951 and higher.


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 uses partitioning of resources to support concurrent execution of applications in virtual machines/virtual instances.

The advantages of virtualization in Cisco AXP are:

Enhanced security due to isolation of processes.

Library Independence—Software ported to run on Cisco AXP might have a dependency on Linux libraries that are incompatible with a library provided by Cisco AXP. To allow the software to access Linux libraries, the application loads its own guest operating system (OS) environment, which separates the application from the Cisco AXP host OS. Components of various Linux distributions can be installed on the same physical server, running in separate virtual instances. Each application runs on its own Linux OS and has administrator privileges within its own virtual instance. The application can access utilities, and libraries.

Resource Isolation—Each application has its own set of CPU, memory, and disk resource limits. An application running in one virtual instance cannot use more resources than the resources allocated to the virtual instance. This results in the improved stability of all applications. Virtual instances share disk space with the Cisco AXP host OS, so disk space does not have to be preallocated.

Low Memory Overhead—gives higher performance.


Note Applications use Cisco AXP APIs to access the Cisco AXP host OS.


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 "Dedicated Application Resources" 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 shows virtualization in the host OS, and virtual instances.

Figure 3 Cisco AXP Virtualization

Virtualization is achieved by kernel-level isolation, allowing multiple virtual instances to run simultaneously, and use common resources.


Note Installed kernel modules affect the entire platform, not just the virtual instance.


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 Cisco AXP User Guide.

CPU and Memory Resources

In Table 1 the CPU (Index) column shows the CPU resources available for different service modules. The CPU (Index) value is relative to a base value. (This base value is provided by the CPU index for the NME_APPRE_302-K9 service module with a 1.0 GHz Celeron M CPU.)

The Available CPU (Index) is the total available CPU Resources for a module. An application package uses approximately the same amount of CPU resources on any service module.

The last column of the table shows the Available RAM (MB)—the available memory resources for each service module.

This available RAM is further reduced depending on the optional features in the software running on the service module. The reduction in available RAM by optional features, is shown in Table 2.

Table 1 CPU and Memory Resources

Service Module
CPU (Index)
CPU for host OS (Index)
Available CPU
(Index)
Physical
Memory (MB)
RAM for host OS (MB)
Available RAM (MB)

AIM2-APPRE-104-K9

5700

300

5400

512

112

400

NME-APPRE-302-K9

10000

300

9700

512

112

400

NME-APPRE-502-K9

10000

300

9700

1024

112

912

NME-APPRE-522-K9

14000

300

13700

2048

112

1936

ISM-SRE-300-K9

9400

300

9100

512

112

400

SM-SRE-700-K9

22000

300

21700

4096

112

3984

SM-SRE-710-K9

22000

300

21700

4096

112

3984

SM-SRE-900-K9

55000

300

54700

4096

112

3984

SM-SRE-910-K9

55000

300

54700

4096

112

3984


Table 2 Memory and CPU used by Optional Features

Optional Feature
Reduction in CPU Index (MB)
Reduction in Available Memory (MB)

CLI plugin

10

5

Remote Serial Device

10

5

IOS CLI API

10

8

Event API

10

27


If an application running on the service module is packaged with swap = ON, the available RAM is the physical RAM plus the swap space. An application packaged with memory-wildcard changes the memory-limit from the maximum limit allowed to the minimum required limit.

The memory limit specifies the maximum memory allowed for the application if the memory wildcard is not used. If the total memory being used by applications running in the virtual instance is greater than the memory limit, then application processes running in the virtual instance are killed.

Displaying CPU Information for Multi-core Systems

The show tech-support command includes the following commands giving information about the CPUs for multi-core service modules.

cat /proc/cpuinfo —gives information about each CPU detected by the kernel.

cat /proc/stat —gives raw information about the CPUs.

ps obtains the "lastcpu" —the CPU id upon which the task was last scheduled for the Cisco AXP host OS. The ps command is summarized as follows:

ps -eo pid,ppid,user,priority,nice,vsz,rss,state,pcpu,pmem,time,lastcpu,cmd


Note A Cisco AXP application can retrieve the same information (about its process), from the /proc file system.


Application Packaging

Cisco AXP supports a range of applications and programming languages, including applications written in Java, C, Python 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 "Packaging Tool" section on page 132.

To use the packaging tool you need to obtain a developer's certificate from Cisco—sign the application package using your third party private key.

System and application packages are summarized in the following sections:

Core System Package

Cisco AXP Add-on Packages

Third Party Application Packages

Core System Package

The core system package is preinstalled on all Cisco AXP service modules, and supports applications and virtualization. The package contains a host OS and a guest OS.

The host 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 OS consists of a kernel that is shared by all virtual instances running on the service module.

The guest OS is an embedded Linux OS that shares the kernel of the host OS. The default Linux OS used in the guest OS is based on a Cent OS 5.2 Linux distribution and is known as the AXP Reference OS . The AXP Reference OS is also known as the AXPOS. The guest OS has utilities to set up and manage the virtual environment. It contains software needed to install applications.

For a list of commands available in the AXP Reference OS, refer to
"Appendix B: Commands in AXP Reference OS" section on page 258.

Cisco AXP Add-on Packages

Cisco AXP add-on packages extend the capabilities of the guest OS. Most add-ons are now "built-in" to Cisco AXP 1.5 or higher. One remaining add-on is the Application Development Package. This is used for debugging and is a package that must be downloaded separately from Cisco AXP. To use these add-on packages with your application, package the application with the add-on package as a dependency. Obtain the UUID to use during packaging by referring to
"Cisco AXP Optional Features" section.

A Cisco add-on is created and signed by Cisco and cannot be modified by third party developers.

Files in Cisco add-on packages are shared on a read-only basis between multiple virtual instances. A single Cisco add-on package is stored in a file system created and signed by us. Copies of the add-on package are instantiated in multiple virtual instances.

Third Party Application Packages

Third party application packages contain binaries, supporting libraries, and any required data files to support the third party vendor's application.

Features of a Third Party Application Package:

Signed using the private key of a third-party developer. The key is verified using the third party developer's certificate.

Loaded and run in a Cisco AXP virtual instance. One third party application is loaded into one virtual instance.

Consists of several application packages bundled together. For more information on bundling applications, refer to "Bundling Tool" section on page 151.

Figure 4 shows a virtual instance and add-on package.

1

Virtual Instance 1: contains an application and add-on packages. For example, Application Development Package—an add-on package created and signed by Cisco.

2

Kernel: The kernel is shared with the virtual instance and Cisco OS.

3

Cisco add-on: The add-on is held in the Cisco OS file system and can be packaged with the third-party application and run in the virtual instance.


Figure 4 Cisco AXP Virtual Instance and 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 the third party with a software development authorization certificate. The certificate is a checksum of the third party X.509 certificate. Figure 6 and Table 3 refer to the steps required to obtain permission. (In Figure 6, the third party developer is referred to as the application vendor.)

Figure 6 Cisco AXP Certificates

Table 3 Steps in the Development Authorization Process

Step

Description (Refer to the figure above)

1

Third party generates a certificate request (private/public keys).

2

Third party requests a signed certificate from the certificate authority.

3

Certificate authority responds to the third party request, by providing a signed X.509 certificate1 .

4

Third party requests software development authorization from Cisco (includes signed certificate from certificate authority).

5

Cisco authorizes the signed certificate.

6

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 3.).


Package the application to include all of the following components:

Cisco authorization certificate

Third party certificate

Third party private key

Third party application

The checksum of the authorization certificate (see step 6 above) 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 Cisco AXP 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 tools for packaging and signing application files, and for attaching a certificate to the application bundle.

Guest Operating System

The Linux guest operating system (OS) consists of a set of binaries and libraries embedded in the virtual instance on the service module.

For AXP 1.5 or higher, the guest OS is one of the following two types:

AXP Reference OS (AXPOS)

or

AXP User Defined Linux Environment (AXPUDL)—a linux distribution provided by yourself

AXP Reference OS

The default AXP Reference OS (AXPOS) is based on components of the Cent OS 5.2 Linux distribution. For the reasons why Cent OS was chosen, refer to the "Appendix D: Comparison of Linux Distributions for AXPOS" section on page 297.

AXP User Defined Linux Environment

The AXP User Defined Linux Environment (AXPUDL) has a skeleton virtual instance. This virtual instance is not bootable but creates certain important directories such as: /dev and /proc .

For a list of files in the skeleton virtual instance, refer to the "Appendix F: Skeleton Virtual Instance Files" section on page 301.

For libraries and files needed for the init system, refer to the "Files and Libraries for the init System" section.

For the virtual instance to stay up, at least one process needs to be running. To troubleshoot startup related issues, /sbin/init make use of /dev/console to output errors. To log these start up errors into a log file create a soft link /dev/console to /var/log/init.log.

Guest OS libraries are listed in the "Appendix C: Libraries in AXP Reference OS" section on page 274. 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 can add or modify its own components.

In the following sections, starting an application is explained in the "Application Startup" section, and monitoring the status of an application is described in the "Application Status Monitoring using Watchdog Scripts" section.

The guest OS is further explained in the following sections:

Application Startup

Accessing the Guest Operating System

Cisco AXP Virtual Instance Operating System

Application Status Reporting

Application Status Monitoring using Watchdog Scripts

Logging Support

IOS Events

Remote Serial Device

Time Zone

For information on libraries and commands available in the guest OS, see the "Appendix C: Libraries in AXP Reference OS" section on page 274 and "Appendix B: Commands in AXP Reference OS" section on page 258.

Application Startup

Run an application using either an automatic or manual startup. The following sections explain these processes and other preparation and setting up details:

Preparing for Automatic Startup

Referencing Environment Variables (Optional)

Setting Up the init Process

Automatic Startup

Manual Startup

Preparing for Automatic Startup

When the virtual instance starts, a default Cisco AXP environment determines the available libraries. This environment is set to enable the successful startup of a virtual instance to run an application.

When your application's startup script starts, if the default environment is causing problems—if required libraries are not accessible—set PATH and LD_LIBRARY_PATH environment variables to point to the required libraries. For more information about the LD_LIBRARY_PATH variable, see the "Appendix B: Commands in AXP Reference OS" section on page 258.

Referencing Environment Variables (Optional)

To create or modify environment variables:


Choose one of the following two options:

Reference the environment variables using an /etc/profile file.

Add the following two lines of code to the /etc/profile file:

export LD_LIBRARY_PATH=/lib:/usr/lib:/opt/IBM-ME-2.2.2/jre/bin
export PATH=/sbin:/usr/sbin:/bin:/usr/bin:/opt/IBM-ME-2.2.2/jre/bin

Execute the /etc/profile file from your application startup script by having the following line in your startup script:

. /etc/profile

OR

Reference the environment variables directly from your application startup script. Put the following two lines of code in your startup script (for example, startHelloworld.sh):

export LD_LIBRARY_PATH=/lib:/usr/lib
export PATH=/sbin:/usr/sbin:/bin:/usr/bin


Setting Up the init Process

For a Cisco AXP (version 1.5 or higher) application the /sbin/init program (or init system) is required. The default guest OS linux environment is the AXP (1.5) Reference OS that has a standard sysv init system. If required, your application can overwrite this init system as part of its own distribution.

Cisco AXP only supports a non-interactive startup script. Write the application's startup script so that it runs without prompting for user inputs (such as single user mode passwords).

The init system coordinates part of the boot process and configures the user environment. The application requires an /etc/inittab script, which specifies the init system configuration.

The configuration must specify the location of the sysinit script and rc scripts. Also include code to detect the Ctrl+Alt+Delete shutdown signal when the application shuts down.

Troubleshoot by viewing errors that are output to /dev/console and are automatically collected in /var/log/init.log (application init output), and /var/log/rc.log (application startup script output). Troubleshoot any issues at startup by viewing these logs. You can also redirect the output of your startup scripts to other log files for debugging purposes.

To respawn an application after it dies, add an entry to the /etc/inittab file. For example, if "my_monitored_app" is the application, then the entry in the /etc/inittab file is:


1:2345:respawn:/bin/my_monitored_app

Files and Libraries for the init System

The application needs to start the init system, which requires the following files:

/sbin/init

/etc/inittab

The init system also requires access to the following libraries:

/lib/libm.so.6

/lib/libc.so.6

/lib/libpthread.so.0

/lib/ld-linux.so.2

Automatic Startup

To prepare an automatic startup script:


Step 1 Create a startup script, with executable permissions, in your build source directory.

The default start run level is 3 (specified in /etc/inittab) for the AXP OS. This start run level can be modified. For example, create a script startHelloWorld.sh in build source directory /etc/rc.d/init.d

Step 2 Reference the startup script using a startup softlink in directory /etc/rc.d/rc3.d

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.sh

Step 3 Reference the startup script from a kill softlink in directory /etc/rc.d/rc0.d:

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/rc0.d

K98helloworld

Manual Startup

For manual startup, perform the following steps.


Step 1 Obtain access to the guest OS shell for your application by first performing the steps in Postinstall Script.

Step 2 app-service <name>

<name> is the application's name.

Step 3 Access the guest OS shell using the connect console command.

Step 4 Start the application.


Accessing the Guest Operating System

Access the guest OS by obtaining console access for the application using the Application Development package or a postinstall script:

Application Development Package

Postinstall Script

Application Development Package

The Application Development Package is an add-on package for use in debugging an application running in a non-production environment and gives console access in the virtual instance. To use this feature, package your application to include the Universal Unique Identifier (UUID) of the application development package as a dependency.

The summary steps for downloading and using the package are as follows:


Step 1 Download the application development package (part of the installation package) from the "Download Software" link in the Support area at: http://www.cisco.com/en/US/products/ps9701/index.html

Step 2 Package your application with application development package axp-app-dev.<platform>.<version>.pkg, as a dependency. For more information, refer to the "Packaging Tool" section on page 132.

Step 3 (Optional) Bundle your application package with the add-on package using the bundling tool. Refer to the "Bundling Tool" section on page 151.

Step 4 Install your application package or bundle into Cisco AXP. See the "Installing and Upgrading Software" section on page 237.

Step 5 In the guest OS shell, log in to your application using the linux shell command.


Postinstall Script

To obtain console access using a postinstall script, perform the following steps.


Step 1 Create a login script.

For example, create a bash file /source/bin/login.sh, where /source is the build directory.

login script: Example

#! /bin/sh
/bin/bash --login


Step 2 Create a postinstall script.

For example, create script /source/bin/postinstall.sh, where /source is the build directory.

postinstall script: Example

#! /bin/sh
ln -s /bin/login.sh /bin/console

Step 3 Change the permissions of the postinstall script for non-owner users to read-execute as follows:

chmod 755 /opt/tcptrace/postscripts/postinstall.sh

Step 4 Package and install your application, referring to the postinstall script.

Step 5 app-service application-name

Enters application service mode.

Step 6 connect console

Accesses the guest OS shell.

Allows a third party to integrate their own application commands in the guest OS shell.

On initiating the command, /bin/console executes. The application must provide its own binary console file or a script to telnet or connect to their CLI shell.

If the application does not provide a console file, the following message appears:

Unable to start console


Cisco AXP Virtual Instance Operating System

The OS running in the virtual instance is known as the AXPOS. An alternative is the AXPUDL. For more information on the AXPOS and AXPUDL, see the "Cisco AXP Reference Operating System" section on page 123.

You can view the status of the virtual instance with commands such as show app-service state, which shows a virtual instance as being online or offline.

Application Status Reporting

An application can invoke the notification command /bin/app_status_notifier, passing the application name and health status code as parameters. For example:

#/bin/app_status_notifier myapp ALIVE 

The health status code is detected by watchdog scripts.

For example, an application sends a status code indicating that it is up and running. Configuration CLI commands recognize that the application is available. Commands can then be sent to the application.

Example health status codes: INITIALIZING, ALIVE, and DOWN. For further information on status codes, refer to "Viewing the Application State" in Cisco AXP User Guide.

To enable application to be monitored, an application includes one or more watchdog scripts or executable files bundled with the application package.

For further details, refer to the "Application Status Monitoring using Watchdog Scripts" section.

If an application fails, one option is to use the respawn feature of inittab. For further information on the init process, refer to the "Setting Up the init Process" section.

Application Status Monitoring using Watchdog Scripts

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

You must provide one or more watchdog scripts (also known as health check scripts or health check executables) for the application. Shell scripts and C executables are supported. The number of scripts is dependent upon the application.

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".

Place watchdog scripts in the predefined directory /opt/app_status_monitor/watchdogs/

The watchdog scripts directory is in the application's vserver directory, and must have executable permissions. All watchdog scripts inside the directory are invoked. To ensure the correct ordering for script invocation, use 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, refer to the "Status Monitor" section. Also, see
Cisco AXP User Guide. Each script or executable needs to return a status code.

Status code = zero (0): application is healthy and alive.

Status code = non-zero value: application is not functional. For example, the application has crashed.

Watchdog Script: Example:

#!/bin/bash 
APP=test.sh 
APPNAME_NO_EXT=test 
PID_FILE=/var/run/${APPNAME_NO_EXT}.pid 
if [ ! -e $PID_FILE ]; then 
exit 1; 
fi 
PID_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 
fi 
done

In 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:

Allowing only one instance of the application to run

Removing the /var/run/<app name>.pid file on shutdown

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:

Application status monitor ran three times and received non-zero status code

Watchdog ran over 3 monitor intervals and did not return a non-zero status code

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 "Application Status Monitor" section in the Cisco AXP User Guide.

Show status monitor

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

Change the monitor interval and recovery threshold

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 for the application status monitor. Use a config file packaged with your application. For example, the following is an example of a config file name.

/opt/app_status_monitor/config/config

The records in the config file have 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 Both monitor_interval and recovery_threshold must be present in the config file.


config file: Example

monitor_interval 50
recovery_threshold 10

Configuration values (such as the values of 24 and 10 set in the example above titled "Change the monitor interval and recovery threshold") take precedence over the config file values. The config file only serves as a source of default values when the application is installed.


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 on page 245.

IOS Events

The Cisco AXP application on the service module uses the IOS Event API to be notified of Cisco IOS events on the Cisco IOS router.

The IOS Event API supports two main types of event:

CLI config-change event

These CLI configuration change events are notified via Netconf.

EEM event

EEM (Embedded Event Manager) events are managed by the Cisco IOS EEM system.

The IOS Event API is supported on the following Cisco IOS images: IP-Voice, Adv-Security, and Adv-Enterprise. For more information on using the IOS Event API, refer to the "IOS Event API" section on page 59.


Note A maximum rate of one IOS event per second is supported by Cisco AXP.


IOS Events are described in the following sections:

Displaying Events

Event Status

Registering an Event

Displaying Event Counters

Clearing Events

Event Notification

Displaying Events

To display registered EEM events, use the following command:

show event manager policy [ registered ]

show event manager policy: Example:

In this example, the events listed as Client Policies match with events on the Cisco AXP side with TYPE=EEM. The first client policy below has a registered name of "STRESS_1_COUNTDOWN_1", which matches with the first event in the "show event status: Example" section.

javalin#show event manager policy reg
No. Class Type Event Type Trap Time Registered Secu Name
1 applet user none Off Wed Nov 11 18:31:29 2009 none TRIGGER_APPL_ED
policyname {TRIGGER_APPL_ED} sync {yes}
maxrun 20.000
action 1.0 publish-event sub-system 798 type 1 arg1 "Hello" arg2 "World"

2 applet user none Off Wed Nov 11 18:31:29 2009 none INCREMENT_COUNTER
policyname {INCREMENT_COUNTER} sync {yes}
maxrun 20.000
action 1.0 counter name counter1 value 1 op inc

3 applet user none Off Wed Nov 11 18:31:29 2009 none action
policyname {action} sync {yes}
maxrun 20.000

Client Policies
No. Class Type Event Type Trap Time Registered Name
1 axp user timer countdown Off Thu Nov 5 15:54:47 STRESS_1_COUNTDOWN_1
name {count1} time 10.000
queue-priority normal maxrun 600.000

2 axp user timer countdown Off Thu Nov 5 15:54:47 STRESS_1_COUNTDOWN_2
name {count2} time 30.000
queue-priority normal maxrun 600.000

3 axp user timer watchdog Off Thu Nov 5 15:54:47 STRESS_1_TIMER_WD_1
name {wdtimer1} time 5.000
queue-priority normal maxrun 600.000

4 axp user interface Off Thu Nov 5 15:54:47 STRESS_1_INTERFACE_1
name {GigabitEthernet0/0} parameter {receive_broadcasts} entry_op gt entry_val 1 
entry_type value
queue-priority normal maxrun 600.000

5 axp user interface Off Thu Nov 5 15:54:47 STRESS_1_INTERFACE_2
name {GigabitEthernet0/1} parameter {receive_broadcasts} entry_op gt entry_val 1 
entry_type value
queue-priority normal maxrun 600.000

6 axp user syslog Off Thu Nov 5 15:54:47 STRESS_1_SYSLOG_5
pattern {up}
queue-priority normal maxrun 600.000

7 axp user syslog Off Thu Nov 5 15:54:47 STRESS_1_SYSLOG_6
pattern {down}
queue-priority normal maxrun 600.000
javalin#

Event Status

Displaying event status for each third party application, shows the following information for each event: Number, ID, Name, Type, Status, and Time.

To display the event status for each application in Cisco AXP, and to (register or deregister) event(s), use the following command:

show event status

Displays the following event status information: Number, ID, Name, Type, Status, Time

Name—the name of the event is created by the application via the event creation API. The event name display is limited to 20 characters, so that only the beginnings of longer names are displayed.

Type—the type of the event is created by the application via the event creation API.

Status—registered, or deregistered.

Time—the timestamp of the action's API.

show event status: Example

se-1-100-80-172# show event status
Application: mytest2
NO.  ID         NAME                   TYPE       STATUS        TIME
1    134929920  STRESS_1_COUNTDOWN_1   EEM        Registered    Thu Nov  5 15:54:47 2009
2    134909672  STRESS_1_COUNTDOWN_2   EEM        Registered    Thu Nov  5 15:54:47 2009
3    134934344  STRESS_1_TIMER_WD_1    EEM        Registered    Thu Nov  5 15:54:47 2009
4    134935632  STRESS_1_CONFIG_1      config-change Registered    Thu Nov  5 15:54:47 
2009
5    134936920  STRESS_1_INTERFACE_1   EEM        Registered    Thu Nov  5 15:54:47 2009
6    134938208  STRESS_1_INTERFACE_2   EEM        Registered    Thu Nov  5 15:54:47 2009
7    134940376  STRESS_1_SYSLOG_5      EEM        Registered    Thu Nov  5 15:54:47 2009
8    134941664  STRESS_1_SYSLOG_6      EEM        Registered    Thu Nov  5 15:54:47 2009
se-1-100-80-172# 

Registering an Event

The application registers event using the Event API. An admin can then deregister or register an event, without using the application, using the following command:

event [register | deregister] [ all | event-id ]

Displaying Event Counters

The following command displays events for each application. Perform the command in Cisco AXP application sub-mode or at system level.

show event counter

Counter—number of events received after registration of the event.

Time—timestamp of the last event notification.

Example

# show event count
Application: mytest2
NO.  ID         NAME                   COUNTER    TIME
1    134929920  STRESS_1_COUNTDOWN_1   1          Thu Nov  5 15:54:57 2009
2    134909672  STRESS_1_COUNTDOWN_2   1          Thu Nov  5 15:55:17 2009
3    134934344  STRESS_1_TIMER_WD_1    11903      Fri Nov  6 08:27:19 2009
4    134935632  STRESS_1_CONFIG_1      16969      Fri Nov  6 08:27:19 2009
5    134936920  STRESS_1_INTERFACE_1   59447      Fri Nov  6 08:27:19 2009
6    134938208  STRESS_1_INTERFACE_2   0
7    134940376  STRESS_1_SYSLOG_5      7164       Fri Nov  6 08:27:06 2009
8    134941664  STRESS_1_SYSLOG_6      7607       Fri Nov  6 08:27:14 2009
# 

Clearing Events

To clear the counter of all received events, use the following command:

clear event counter [ all | event-id ]

Event Notification

To receive notifications of events, you need to write and install an application using the IOS Event API. Refer to the "IOS Event API" section on page 59.


Note For CLI config-change events, you must configure netconf. Refer to the "Netconf" section on page 314.


Using CLI to Trigger a CLI config-change Event

To manually trigger a CLI config-change event, perform the following steps on the router:

1. configure terminal

Enters configuration mode.

2. Enter any configuration command that configures the hostname and IP address. For example,
ip host ...

Using CLI to Trigger a Syslog Event

To manually trigger a syslog event by logging onto an interface, perform the following steps on the router:

1. configure terminal

Enters configuration mode.

2. logging buffered buffer-size

3. interface interface-name

Selects the type of interface to be recorded in the syslog. This is dependent upon having first set up an event-type of "syslog" with a pattern to be matched. For example, attribute pattern = "eth0/1".

4. shutdown

Shuts down the interface. Sends event information to syslog.

5. no shutdown

Starts the interface. Sends event information to syslog.

Troubleshooting a Cisco Event API config-change Event

To track config-change events on the router, use one of the following commands:

(for Netconf layer):
debug netconf all

(for SSH transport):
debug ip ssh

To trace config-change or EEM events on the Cisco AXP service module, use the following command.

trace AXP_eventapi all

EEM events have three different layers: eem, snap, and ipc. These layers need to be monitored.

For config-change events, turn on netconf using one of the following commands:

(for Netconf layer):
trace netconf client

(for SSH transport):
trace netconf ssh

Cisco AXP Optional Features

Cisco AXP optional features are listed in Table 4. For some features, a UUID must be specified during packaging of the application—these features are marked in the table by having a package UUID.

The following features do not need to be specified during packaging: AXP CLI API, AXP SysInfo API, and AXP SysOp API.

For more information on APIsAPIs, refer to the API sections starting with the "AXP API Files" section on page 37.

Optional features are described in the following sections:

Optional Features Table

NFS Client

Remote Serial Device

Time Zone

Optional Features Table

Table 4 Optional AXP Features 

Feature
Package UUID
Note

IOS CLI API, page 43

8cec8ee5-54c3-4667-b62e-d4a31805d44a

-

AXP CLI API, page 53

-

Basic service—You can use this API without having to package your application with a dependency.

NFS Client

35391828-9ecc-4b05-a3de-7c260a92429a

Basic service—You can use the NFS1 client feature without having to package your application with a dependency.

CLI Plugin

b4b0ee92-cf8e-472b-8434-e8e7412ec71a

If you are using a CLI plug-in developed at a lower version than Cisco AXP 1.5, you must re-compile and re-link the CLI plug-in. Refer to the "CLI Plug-in Distribution Service" section on page 173.

IOS Event API, page 59

545c3671-c4bc-43b8-bce4-690123ab9d4d

The package UUID differs from the UUID of the EEM package in Cisco AXP 1.1

Remote Serial Device

7a013f0e-07cb-4c25-8122-4a0af7704c3b

Application Development

5d9267f0-f9c2-11db-8f0d-001635a94464

Add-on package. For example, axp-app-dev.nme.1.5.0.pkg. Refer to the "Application Development Package" section.

Perl

-

For Cisco AXP 1.5 or higher versions, add Perl as an RPM package. In Cisco AXP versions lower than1.5, Perl was an add-on package.

Java

-

Add Java as an RPM package. Download the JRE 6 .rpm.bin from the software download website at oracle.com.

Tomcat server

-

For Cisco AXP 1.5 or higher versions,, add Tomcat as an RPM package. In lower versions of Cisco AXP than 1.5, Tomcat was an add-on package.

SSH

-

SSH server that runs in a virtual instance. For Cisco AXP 1.5 or higher, add ssh as an RPM package. In lower versions of Cisco AXP than 1.5, ssh was an add-on package.

AXP SysInfo API, page 91

-

Basic service—You can use this API without having to package your application with a dependency on the package.

AXP SysOp API, page 111

-

Basic service—You can use this API without having to package your application with a dependency.

Time Zone

-

Basic service—Timezone sharing is enabled by default. You can disable timezone sharing by specifying --share-timezones=OFF when you package the application.

1 Network File System = NFS


NFS Client

By packaging your application with a dependency on the NFS client, the application can be mounted to a Cisco Integrated Storage System (ISS) Network Module. This gives access to additional storage on an NFS server. The NFS client and configuration commands are explained in the following sections:

Using the NFS Client in an Application

Setting up Access to the NFS Server from the Guest OS

Displaying the Mount Points for an NFS Server

Determining the Status of the NFS Server

Application Monitoring of the NFS Server

Using the NFS Client in an Application

To use the NFS Client in your application, your application must be packaged with a dependency on the NFS client application. Use the following UUID as a dependency: 35391828-9ecc-4b05-a3de-7c260a92429a. For further details on packaging, refer to the "Cisco AXP Optional Features" section and the "Application Packaging" section.

You can bind the file system used by the application to the NFS server using the bind filesystem command (in application service configuration mode). For further information on this command, read the remainder of this "NFS Client" section and also refer to the bind filesystem command in the
Release Notes for Cisco AXP 1.5.3 at: http://www.cisco.com/en/US/products/ps9701/prod_release_notes_list.html.


Note NFS version 3 is supported by Cisco AXP.


Several applications can be dependent on the NFS client add-on. If these applications are installed, each application can have its own bind points. For NFS mounts, User Datagram Protocol (UDP), the default protocol, is the only protocol supported by ISS.

An alternative to using the Cisco AXP CLI command in application service configuration mode is to call the command from an application using the AXP CLI API.

If an application requires the use of an NFS mount, the application can run the command automatically using the existing AXP CLI API and C/C++, Java, Perl, Python, or Bash.

Bash Example

bash-3.2# appreapi --mode config "app-service App,bind filesystem 192.168.24.4 /local/nfs"

For further information on the AXP CLI API, refer to the AXP CLI API, page 53.

The NFS client can be used to access an ISS service module. The ISS service module can be configured to only allow access by the Cisco AXP service module.

The configuration of an ISS service module is only based on the IP address—so other applications installed on the AXP service module can also mount to the ISS service module.

The ISS service module can be configured to only allow access from the Cisco AXP service module using the following configuration mode CLI command on the ISS blade:

export mount-point media0 IP address

where IP address is the address of the of the AXP service module.

Example

In this example, the Cisco AXP service module has an IP address of 192.1.1.100

To give the Cisco AXP service module access to /media0 on the ISS service module, run the following command on the ISS service module:

config t
export mount-point media0 192.1.1.100

For further information on the bind filesystem command, refer to the
Release Notes for Cisco AXP 1.5.3
http://www.cisco.com/en/US/products/ps9701/prod_release_notes_list.html.

If you are developing a system using AXPUDL (AXP User Defined Linux) as the guest OS, to unmount a file system, you must include your own umount utility in the application package, including any dependent libraries.

When an application shuts down, an unmount of the file system occurs on both the host OS and the guest OS.

An application is not blocked from mounting to another application's space on an NFS server, assuming both applications reside on the same AXP module. Note that this may cause an application to function incorrectly.

Applications need to be aware of each other so that they do not write to the same location on an NFS server.

The NFS Client has been tested using the following Linux distributions:

Fedora Core 4

Fedora Core 10

Debian Etch

Setting up Access to the NFS Server from the Guest OS

From the guest OS, a Cisco AXP application can access the NFS server by specifying a mount point at a subdirectory of /mnt/filesystem.

Examples of an application binding to subdirectories are shown below.

In example A, the application binds to one subdirectory. In example B, the application binds to two subdirectories. In example C, the application attempts to bind to a subdirectory that does not exist and therefore fails with an error message.

Example A

In this example, the application binds to a single subdirectory. The mkdir command creates one subdirectory (my_mount) underneath directory /mnt/filesystem. This subdirectory is bound to the server at 192.168.24.4 and path /media0. Files on the NFS server in /media0 are shown by listing the /mnt/filesystem/my_mount subdirectory using the ls command.

> mkdir -p /mnt/filesystem/my_mount

> ls /mnt/filesystem/my_mount/

> bind filesystem 192.168.24.4 /media0 

> ls /mnt/filesystem/my_mount/
my.file  info 

Example B

In this example the application binds to two subdirectories. The mkdir command creates two subdirectories underneath directory /mnt/filesystem.

The first bind filesystem command binds directory dir1 to the server at 192.168.24.11 and path /media0

The second bind filesystem command binds directory dir2 to the server at 192.168.24.4 and path /local/nfs

> mkdir -p /mnt/filesystem/dir1 /mnt/filesystem/dir2

> bind filesystem 192.168.24.11 /media0 dir1

> bind filesystem 192.168.24.4 /local/nfs dir2

Example C

In this example, the ls command shows that the /mnt/filesystem directory has no subdirectories. The application issues the bind filesystem command for subdirectory mount1, which does not exist. An error is displayed to the console and messages.log.

> ls /mnt/filesystem/

> bind filesystem 192.168.24.11 /mount1

ERROR: There must be at least one subdirectory listed in 
/mnt/filesystem/ to mount to

Displaying the Mount Points for an NFS Server

To display the mount points for an NFS server, use the show mounts command.

The show mounts command displays the following values to the screen:

APP NAME—displays the name of the application running in this virtual instance of the guest OS

LOCAL MOUNT POINT—displays the local mount point of the mount from within the guest OS; for example,/mnt/filesystem/my_mount2

SERVER—displays the location (IP address and path) of the NFS server; for example, 192.168.24.11:/media0

BOUND IN APPLICATION—displays True if the application has not unmounted the bind point, False if the application has unmounted the bind point.

PINGABLE?—displays True if the server is pingable using the ping command

NFS ACCESSIBLE?—displays True if the server is "NFS accessible"—the server is determined as being accessible if an ls command can be successfully performed on the bind point

For more information on the show mounts command, refer to the Release Notes for Cisco AXP 1.5.3 at: http://www.cisco.com/en/US/products/ps9701/prod_release_notes_list.html..

For troubleshooting errors for the NFS client, refer to the "Displaying Mount Points for an NFS Server" section in Cisco AXP User Guide.

Determining the Status of the NFS Server

If the NFS Server goes down, an input/output error occurs when an application tries to read or write to a directory that is mounted to the same NFS server. Methods for determining if the NFS server is available are shown below:

Attempted Read of the Mounted Directory

Attempted Write of the Mounted Directory

Using the show mounts Command

Attempted Read of the Mounted Directory

Example

In this example, the NFS Server has gone down and an ls command is attempted on the mount point.

The ls command fails because the command was executed after the NFS server became unavailable.

>ls /mnt/filesystem/mount
ls: /mnt/filesystem/mount: Input/output error

Note After the NFS server goes down, the ls command may continue to succeed for a period of 30 seconds or more. After this period, the ls command will fail properly.


Attempted Write of the Mounted Directory

Example

In this example, an error is reported when attempting to write to the directory /mnt/filesystem/mount

> touch /mnt/filesystem/mount/file.error
touch: cannot touch `/mnt/filesystem/mount/file.error': Input/output error

Using the show mounts Command

The NFS ACCESSIBLE output line from the show mounts command reports if the NFS mount is accessible.

Example

se-192-168-24-7# show mounts
APP NAME:  friendly_app_PROD
    LOCAL MOUNT POINT:  /mnt/filesystem/mount
    SERVER:  192.168.24.4:/local/nfs/discus
    BOUND IN APPLICATION?:  True
    PINGABLE?:  True
    NFS ACCESSIBLE?:  False

Application Monitoring of the NFS Server

If the NFS server goes down, the application can take steps such as storing files locally until the server becomes available. When the NFS server becomes available, the application can copy cached local files to the NFS directory and continue running normally.

To monitor the status of the NFS server, the application can periodically attempt to read or write to the NFS drive.

After a read/write, if the server is down an I/0 error will result, and files can be stored locally until the server becomes available.

After a read/write, if no I/O error results, consider the state of the NFS drive to be up.

You can use a Cisco AXP watchdog script to monitor the NFS server, as shown in the following example.

Example

#!/bin/bash
# File name: W99nfsWatchdog.sh

touch /mnt/filesystem/my_mount/temp.file
if [ $? -ne 0 ]; then
    # Cannot write to the NFS mount. An error has occurred. Exit the script.
    exit 1
fi

rm -f /mnt/filesystem/my_mount/temp.file

Remote Serial Device

The Remote Serial Device package provides a virtual serial driver. The driver allows an application running on the application service module to access external Cisco IOS serial devices connected to the auxiliary serial port of a router.

To use the remote serial device package, package your application with the remote serial device package. When packaging, specify the UUID shown in Table 4.

One example usage is to allow an application to support a peripheral such as a Global Positioning System (GPS) locator, connected using a serial port. Up to 16 serial devices are supported.

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.


Step 1 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]);
	else
		dev = strdup("/dev/modem");
	fd = open (dev, O_RDWR | O_NONBLOCK | O_NOCTTY | O_NDELAY);
}

Step 2 Package and install the application.

Package the application with a dependency on the Remote Serial Device add-on package, see the "Cisco AXP Optional Features" section.

Install the application package on the application service module.

Step 3 Connect the remote 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. An example showing an application that accesses a serial device is in the "Remote Serial Device" section.

Time Zone

In a linux environment such as the AXP Reference OS, the time zone definition is located in /usr/share/zoneinfo with a reference held in /etc/localtime.

If you are developing a Java application, consider how the application determines the time zone. Your application may use the time zone definition in the JVM/JRE or use the time zone name from C runtime to determine the time zone, or use the time zone definition used by C directly.

Standard Linux commands and C runtime (glibc) time conversions also use the time zone definition in /usr/share/zoneinfo.

To share the time zone definition of the Cisco AXP host OS, package your application using the packaging tool with --share-timezones = ON. See the "Share Timezones" section on page 150. After this, every time the application is started the time zone definition is copied from the definition held in the Cisco AXP host OS to /usr/share/zoneinfo. If the host OS time zone definition is changed or redefined, the change is only seen in the guest OS after restarting the application.

Initially there is no information in /usr/share/zoneinfo and /etc/localtime if the linux environment in the guest OS is the default AXP Reference OS. Consider using an application to set the time zone definition in /usr/share/zoneinfo and /etc/localtime. Alternatively, consider using a different linux environment in the guest OS (not CentOS-based), in which an application in the guest OS obtains the time zone definition directly from the linux operating system. The host OS could also use the same time zone definition.


Note If you bundle your application with the timezone package, the timezone defined in the package supersedes any timezone definitions that are in Cisco AXP where your application is installed.


Development System Requirements

Applications must be developed using a Linux operating system. The minimum hardware and operation system requirements for developing Cisco AXP software applications are:

Intel Pentium 4 CPU 1.8 GHz, 40 GB Hard Disk, and 512 MB Memory

C Compiler: GNU C Compiler (gcc) Version 3.4.3

Linux distribution such as the CentOS 5.2 Linux distribution

Running Cisco AXP on the Application Service Module

Before running an application on the application service module, install the router and application service module. For more information, refer to the hardware documentation for your product in Cisco Network Modules Hardware Installation Guide and Application eXtension Platform Enhanced Network Modules.

For information on downloading the Cisco IOS software image, and configuring the router, refer to the System Requirements section in the Release Notes for Cisco Application eXtension Platform.

After booting up the router, configure the service module interface. See the "Configuring the Cisco AXP Service Module Interface" section in the Cisco AXP User Guide. Cisco AXP is preloaded on the service module.

Swap Space and Memory Allocation

Swap space allows processes or parts of processes to move between physical memory and disk. This frees up space in physical memory and allows more processes to run simultaneously.

Swap space is available on the following Cisco AXP service modules:

NME-APPRE-302-K9

NME-APPRE-502-K9

NME-APPRE-522-K9

SM-SRE-700-K9

SM-SRE-710-K9

SM-SRE-900-K9

SM-SRE-910-K9

Swap space can be turned on or off during packaging.

4 GB of swap space can be made available to the application. If you upgrade from Cisco AXP 1.1 to 1.5—the 4 GB of swap space consists of a 2 GB swap partition and a 2 GB swap file. If Cisco AXP 1.1 or 1.5 is preloaded on the service module or is installed using a helper image then the 4 GB swap space consists of a 4 GB swap partition.

Memory allocation for Cisco AXP applications is dependent upon Linux overcommit_memory and the physical memory limit for the virtual instance. Linux overcommit_memory mode has a default value
of 0. In this mode, the Linux memory manager heuristically determines how memory is allocated. Overcommit handling enables a greater amount of memory to be allocated by a process than would normally be allowed using the available memory.

However, when a process accesses a page with allocated memory that does not have physical RAM, an out of memory (OOM) condition exists. The Linux kernel then attempts to kill the process to preserve the integrity of the system.

A physical memory limit can be setup for the Cisco AXP Virtual Instance using the "memory-limit" argument of the packaging tool.

When swap space is off, the memory limit restricts the amount of physical memory being used. If the memory limit is exceeded, overcommit_memory is still in effect, and an OOM condition is the result.

When swap is off and your application is running, you can estimate the memory usage by using the Linux top or ps command—add up the RSS column of the processes to give a total memory usage (MB).
Add some more space to this total to determine a memory limit.

When swap is on, the memory limit for an application within a virtual instance is not applied. Therefore, the application can allocate as much memory as it wants. This could impact the AXP host OS. The AXP EXEC mode show swap usage command can be used to monitor swap usage—to ensure that the third party application is not exhausting system memory. Additionally, if the Cisco AXP system detects that there are less than 80 MB of available memory, it logs a message similar to the following in messages.log:

AXP_sysmon: SystemMemoryLow: System  Memory: Mem Total: 2073100 Mem Free: 54448 Cache 
Used: 2010220 Cache  Free: 62880 Swap Total: 3911816 Swap Free:  4136

This message is followed by another set of messages listing the processes that are using the most memory in the host and applications.

After the free memory rises above 100 MB, the following message is written to messages.log:

AXP_sysmon: SystemMemoryOK: System  Memory: Mem Total: 2073100 Mem Free: 103388 Cache 
Used: 1959156  Cache Free: 113944 Swap Total: 3911816 Swap Free: 5820  

To show the swap space usage of each application, use the show swap usage command. Also, refer to the "Displaying Current Resource Limits" section on page 206.

Turning swap space support on or off is explained in the following sections:

Swap Space Off

Swap Space On

Swap Space Off

By default, swap space support is turned off.

During packaging, specify the virtual memory limit for each application using the "memory-limit" argument of the packaging tool. When swap is off, this memory limit is the physical memory limit. When the application is running in a virtual instance, the application process is killed if the physical memory limit is exceeded.

When the system reboots, the startup script enables/disables swap space support based on the requirements of the installed applications.

Swap Space Off: Example

The following example shows the packaging tool being run to turn off swap space support ("--swap `off'") and specify a 128 MB virtual memory limit
("--memory-limit '128M'").


Note If swap space is OFF, use the "--memory-limit" option to specify the physical memory limit.


pkg_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 Discus Beta' --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 "2000" --memory-wildcard --cpu-wildcard 
--disk-wildcard --postinstall 'bin/post-install.sh' --swap 'OFF'  --protect 
`/protect-list.txt' --preupgrade `/bin/preupgrade.sh' --preupgrade-oldver 
`/bin/preupgrade-oldver.sh' --cap-config `/bin/cap-config.txt' --share-timezones `ON' 
--shutdown-timeout `10' --user-defined-linux

Swap Space On

During packaging, you can turn on swap space support using the "swap `on'" argument—see the "Swap Space On: Example" section.

Swap space support cannot be turned on or off dynamically. All applications running using Cisco AXP 1.1 or higher must use the same swap space option—either on or off.

If you bundle together several applications with the bundling tool, where some of the applications have swap space on and others have swap space off, and try to install the bundle, then the installation fails.

You must specify the virtual memory limit for each application using the "memory-limit" argument.

Having swap space on guarantees the available virtual memory for each virtual instance but does not guarantee the physical memory available for each virtual instance.

Swap Space On: Example

The following example shows the packaging tool being run to turn on swap space ("--swap `ON'").

pkg_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 Discus Beta' --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 "2000" --memory-wildcard --cpu-wildcard 
--disk-wildcard --postinstall 'bin/post-install.sh' --swap 'ON' --protect 
`/protect-list.txt' --preupgrade `/bin/preupgrade.sh' --preupgrade-oldver 
`/bin/preupgrade-oldver.sh' --cap-config `/bin/cap-config.txt' --share-timezones `ON' 
--shutdown-timeout `10' --user-defined-linux