Cisco Application Extension Platform 1.5 Developer Guide
Packaging the Application
Downloads: This chapterpdf (PDF - 254.0KB) The complete bookPDF (PDF - 9.6MB) | Feedback

Packaging the Application

Table Of Contents

Packaging the Application

Flexible Resource Allocation

Displaying Current Resource Limits

Applying Resource Limits

Additional References

Creating a Common Root Directory

Copying Files

Creating a File of Protected Files

Creating Certificates

Creating a Certificate for AIM2, NME, and VmWare Platforms

Creating a Certificate for ISM Platforms

Creating a Package Directory for Project

Running the Packaging Tool

Bundling the Application

Packaging the Hello World Application: Example

Library Dependency Checker

Library Dependency Checker: Example

Library Dependency Checker Arguments

Library Dependencies Checker: Limitations

Packaging and Installing RPMs

Packaging and Installing RPMs using a Predefined Directory Path

RPM Installation Sequence

Using a Predefined Directory Path for Packaging

Using a Predefined Directory Path for Packaging: Example

Packaging and Installing RPMs using a Post Install Script

RPM Installation Error Scenarios

Corrupted RPMDB

Corrupted RPM package

Incompatible RPM package

Failed RPM scripts

Miscellaneous RPM Errors

Disclosure Statement for External RPMs

Installing SDK RPM Packages

Development System Requirements

Cisco AXP Base RPM Packages

Installing RPM Packages

Trimming RPM Packages

RPM Conflicts and Dependencies

File Level Conflicts

RPM Level Conflicts

Additional References


Packaging the Application


Common packages and bundles used in Cisco AXP are:

Cisco AXP 1.5 host OS package

Third party application package

Cisco AXP 1.5 host OS package + third party application package (bundle)

This bundle can be used as a single package to install and upgrade the Cisco AXP host OS and the application.

Third party application package + third party application add-on package (bundle)

This bundle can be used as a single package to install an application and the application's add-on.

The following sections describe packaging and bundling:

Flexible Resource Allocation

Creating a Common Root Directory

Copying Files

Creating a File of Protected Files

Creating Certificates

Creating a Package Directory for Project

Running the Packaging Tool

Bundling the Application

Packaging the Hello World Application: Example

Library Dependency Checker

Packaging and Installing RPMs

Flexible Resource Allocation

During packaging, flexible resource allocation can be turned on for an application. Some of the advantages of flexible resource allocation are as follows:

makes it easier to control the hardware's capability to support the application

grants extra memory, CPU, and disk resources to an application if those resources are available, as part of a resource management system

shares unallocated resources between virtual instances (provided the applications in those virtual instances have flexible resource allocation turned on)


Note If you override the resource limits of an application using the Cisco AXP CLI on the application service module, then flexible resource allocation no longer allocates additional available resources for this application.


The following packaging tool parameters control the main memory, CPU, and disk resources:

--memory-wildcard

--cpu-wildcard

--disk-wildcard

If you configure the resource limit using the Cisco IOS CLI and use the write memory command and reload or reload apps command, resources are reallocated or rebalanced.

Resource allocation occurs after installing an add-on package, upgrading or uninstalling a package, or configuring resource limits with the Cisco AXP CLI on the application service module.


Note If --memory-wildcard is set—the --memory-limit specifies the minimum required memory resources. If --cpu-wildcard is set—the --cpu-limit specifies the minimum required cpu resources.
If --disk-wildcard is set—the --disk-limit specifies the minimum required disk resources.


Resource Limits Exceeded after Downgrade

The following scenario may occur after downgrading an application on Cisco AXP. When using an application version 2 with Cisco AXP host OS 1.5.1, then downgrading to a lower version of Cisco AXP host OS (for example, 1.0.6) using version 1 of the same application, the files for version 2 of the application may still be present on the application service module. The presence of two versions of the application may cause resource limits may be exceeded. For example, the following error messages may be displayed when trying to run version 1 of application APP1 on Cisco AXP host OS (1.0.6):

localhost err_handler: invalid parameters: 'space_used' is larger than 'space_total'. 
localhost err_handler: Failed to start vserver 'APP1'.

Displaying Current Resource Limits

To display the current resource limits, use the show resource limits command.

Display only the selected output, by adding one of: cpu, memory, or disk to the show resource limits command. These selected output commands are as follows:

show resource limits cpu—Displays only CPU resources

show resource limits memory—Displays only memory resources

show resource limits disk—Displays only disk resources

For further details on the show resource limits command, see Cisco AXP Command Reference.

Pending resource limits, changed through the CLI, are not applied immediately (Cisco AXP 1.1 and higher versions). After changing the resource limits (for example, using the limit disk utilization nn command) the output displayed by the show resource limits command might include limit values with an asterisk "*" after the limit value. The asterisk indicates that the limit value is in a pending state—the limit value is currently not in effect. After write memory and (reload/reload apps) commands are used, the resource limits are applied. For more information on changing resource limits, refer to the "Applying Resource Limits" section.


Note Pending resource limits are not applied until you use write memory command and the application service module reboots.


Applying Resource Limits

To apply disk resource limits:


Step 1 limit disk utilization nn

Configures the resource limit to nn megabytes.


Note If you use reset to restart each virtual instance, the new resource limit is not yet applied.


Step 2 write memory

Updates the resource limits in the startup-config.

Step 3 Enter one of the following two commands to rebalance resources:

a. reload

Reboots the application service module.

or

b. reload apps

Reboots the virtual instances. Does not reboot the application service module.


To allocate non-disk resource limits, replace the command limit disk utilization nn in step 1 with one of the following commands:

limit memory utilization nn : sets the memory usage to nn megabytes.

limit cpu utilization nnnn : sets the CPU utilization to index value nnnn.

Additional References

For further information on configuring resource limits, see the "Configuring Resource Utilization Limits" section in Cisco AXP User Guide.

Creating a Common Root Directory

Create a common root directory such as /source/helloworldapp/build.

This directory is the common root directory containing the software for packages that are created and installed on Cisco AXP.

Copying Files

Copy your start up and kill softlinks located in /etc/rc.d/rc3.d and /etc/rc.d/rc6.d with their directory structure intact, into the common root directory.

Copy your referenced script /etc/rc.d/init.d into the common root directory.

Copy all other files and links required for your application into the common root directory.

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

Creating Certificates

Certificates and a private key file are required during packaging. The 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.

In the first of the following two procedures, the key length is 1024 bits, and in the second procedure, the key length is 2048 bits.

Perform one of the following two procedures based on the hardware platform:

Creating a Certificate for AIM2, NME, and VmWare Platforms

Creating a Certificate for ISM Platforms

Creating a Certificate for AIM2, NME, and VmWare Platforms

To create a self-signed certificate perform the following steps:


Step 1 Generate a self-signed X.509 certificate with the OpenSSL tool

Create an RSA key pair with the OpenSSL tool. The resulting private key file contains a private key

openssl genrsa -out private.key 1024

Create a self-signed X.509 certificate valid for one year

openssl req -new -x509 -days 365 -key private.key -out dev_certificate.sig


Note The developer certificate must be named dev_certificate.sig.


Step 2 Request approval of the developer certificate by submitting an Evaluation Request.

Step 3 If the developer certificate is approved, we will return the authorization certificate: dev_authorization.sig

Step 4 If the directory does not exist, create directory /source/certs

Step 5 Move the authorization certificate (including the private key file) to directory /source/certs


Creating a Certificate for ISM Platforms

To create a self-signed certificate perform the following steps:


Step 1 Generate a self-signed X.509 certificate with the OpenSSL tool

Create an RSA key pair with the OpenSSL tool. The resulting private key file contains a private key

openssl genrsa -out private.key 2048

Create a self-signed X.509 certificate valid for one year

openssl req -new -x509 -days 365 -key private.key -out dev_certificate.sig


Note The developer certificate must be named dev_certificate.sig.


Step 2 Request approval of the developer certificate by submitting an Evaluation Request.

Step 3 If the developer certificate is approved, we will return the authorization certificate:
dev_authorization.sig

Step 4 If the directory does not exist, create directory /source/certs

Step 5 Move the authorization certificate (including the private key file) to directory /source/certs


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, run the SDK packaging tool pkg_build.sh, located in directory axp-sdk.<version>/tools. To run your application on Cisco AXP 1.5, you must package your application using the Cisco AXP 1.5 SDK. For further information on packaging, refer to the "Packaging Tool" section on page 132.

Bundling the Application

You can use the bundling tool, pkg_bundle.sh—see the "Bundling Tool" section on page 149—to combine application packages. For example, after packaging an application with the required dependencies, you can bundle the third party application with third party application add-on packages before installing the bundle on the service module.

Packaging the Hello World Application: Example

This example shows the packaging tool pkg_build.sh being used in interactive mode, to package the application "Hello World".

For further information on the packaging tool, see the "Packaging Tool" section on page 132.

After packaging, to install the application, see the "Packaging Tool: Example" section on page 145.

Start the packaging tool by entering pkg_build.sh.

> ./axp-sdk.1.5.0/tools/pkg_build.sh
SLIM Packaging Utility. (C) 2007-2009 Cisco Systems, Inc
Checking dependencies...

WARNING: If an application from AXP 1.0/1.1 is repackaged to be installed
on AXP 1.5, please make sure to increment the application version

No command parameters specified - entering interactive mode.

** project-dir
Project directory will be used 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-bundle
Authorization bundle provided by Cisco Systems. This bundle is
required to allow your application to install and run on
the target blade

Authorization Bundle: Authorization Bundle: /xyz-src/certs/1.5/basic/nme/auth_bundle.sig

** private-key
Private 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 certificate

Private Key for Signing Operations: /xyz-src/certs/1.5/basic/nme/private.key

** name
Name of application to be packaged. This name will be used to identify
application through command line interface as well as for naming
package files

Application Name: helloworld

** version
Application version is used when displaying application information
through command line interface. It is also used for upgrade/downgrade
sequencing

Version: 1.5

** description (optional)
Application description is used when displaying application information
through command line interface. For example it may contain a statement
about application's capabilities

Description: This is a 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 blank

Unique Identifier:

** source-dir
Source 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 environment

Source 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 blank

Protect 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 '/pkg' and '/pkg' directories.
If this option is not specified the application will have no
dependencies

Loading existing SLIM Packages in directories:
/xyz-src/package

sanity_ism_iosapi.1.pkg:
UUID                                  NAME             VERSION DESCRIPTION
1ff24c0f-e4ed-43ce-91c2-e381f2aa823a sanity_ism_iosapi 1

AXP add-ons
UUID                                   NAME    Disk CPU Memory Description 
b4b0ee92-cf8e-472b-8434-e8e7412ec71a cli_plugin 0 10 5         CLI Plugin
8cec8ee5-54c3-4667-b62e-d4a31805d44a iosapi     0 10 5         IOS CLI API
7a013f0e-07cb-4c25-8122-4a0af7704c3b vserialapi 0 10 5         Remote Serial Device 
support
5d9267f0-f9c2-11db-8f0d-001635a94464 app_dev    0 10 5 Application Debugging Add-on 
Package
545c3671-c4bc-43b8-bce4-690123ab9d4d eventapi   0 10 5         IOS Event API

Dependency Subsystem Identifier:

** disk-limit
disk 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 1500M.

Disk Limit: 100M

** memory-limit
Memory limit option allocates RAM space for the application.
Memory limit must be specified in megabytes, for example 256M

Memory Limit: 100M

** cpu-limit
CPU 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 limit

Cpu Limit: 200

** swap (optional)
swap option specifies whether swap needs to be turned on or off on the
Network Module. The application can specify ON or OFF; the system will
enable/disable swap after reboot based on Application's requirement

Swap Space: ON

** postinstall (optional)
Postinstall script is executed after installation is complete but before
the application has been started for the first time. Postinstall script
must be packaged with the application. When entering postinstall script
location, use relative path with respect to source tree directory

Post-install script path: bin/post-install.sh

** preupgrade (optional)
Preupgrade script is executed before the upgrade takes place.
Preupgrade script is first extracted from the incoming package
it is then executed in vserver. When entering preupgrade script
location, use relative path with respect to source tree directory

Pre-upgrade script path:

** preupgrade-oldver (optional)
Preupgrade_oldver script is executed before the upgrade takes place.
Preupgrade_oldver script is found and executed from the currently installed
version of the application. When entering preupgrade-oldver script
location, use relative path with respect to source tree directory

Pre-upgrade-oldver script path:

** cap-config (optional)
Capabilities configuration file can be used to relax certain restrictions
in the virtual container. Only the capabilities granted by the development
authorization file can be configured

Capabilities Configuration File:

** share-timezones (optional)
Specify whether this application will share the system's timezone
information. If enabled, the application will be given timezone
information from the system at the time the application starts.
If disabled, the application will use it's own timezone information.
This can be ON(default) or OFF.

Share Timezone Option:

** shutdown-timeout (optional)
Specify the shutdown timeout value for the application. This is specified
in seconds and can vary from 0-300. The default value is 30.

Shutdown Timeout Option:

** disk-wildcard (optional)
Specify if the disk-wildcard feature is enabled or disabled(default.)
If enabled, the application is permitted to exceed its disk limit.
When a new package is installed, the remaining free disk space is
divided evenly amongst applications with the disk-wilcard feature
enabled.
Enable disk wildcard support? (y/n): n

** memory-wildcard (optional)

Specify if the memory-wildcard feature is enabled or disabled(default.)
If enabled, the application is permitted to exceed its memory limit.
When a new package is installed, the available memory is divided evenly
amongst applications with the memory-wildcard feature enabled.
Enable memory wildcard support? (y/n): n

** cpu-wildcard (optional)

Specify if the cpu-wildcard feature is enabled or disabled(default.)
If enabled, the application is permitted to exceed its cpu limit.
When a new package is installed, the available CPU is divided evenly
amongst applications with the cpu-wildcard feature enabled.

Enable cpu wildcard support? (y/n): n

** user-defined-linux (optional)
Select yes to use the User Defined Linux Environment.
Select no (default) to use the AXP Reference OS Environment.

Use User Defined Linux Environment? (y/n): n

Interactive mode complete. Resulting CLI command:

-------------------
pkg_build.sh --project-dir '/xyz-src/apps/helloworld_app/package' --auth-bundle 
'/xyz-src/certs/1.5/basic/nme/auth_bundle.sig' --private-key 
'/xyz-src/certs/1.5/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' 
-------------------
Press enter to continue...


You can save the above "Resulting CLI command" to use as the basis of a script file for future packaging

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

Library Dependency Checker Arguments

Table 108 Library Dependency Checker Arguments 

Argument
Name Associated with Argument
Description

--help

(No argument)

Version and usage information

--project-dir

Project directory

Project directory used as a temporary storage location for extracted package files.

--check-pkg

Package to check (optional) or Software root directory (optional)

Package to check (for dependencies). Must have a corresponding .prt1 payload file stored in the same directory. Package name has .pkg suffix.

or

Software root directory: contains application files.

Note Either the package or the software root directory must be supplied for the --check-pkg argument.

--lib-path

Extra path locations

The --lib-path argument allows library search path locations to be specified in addition to the default library path "/lib". The library path locations must be separated by a colon symbol. For example, "/usr/lib:/usr/local/lib".

Note You also need to add any required library locations to LD_LIBRARY_PATH
before running your application.

--core-sys

Core System Package

Cisco AXP core system package (full path). Application dependencies are checked against the core system package. For example, "axp-k9.nme.1.5.1.pkg"

<list of package names>

Dependency packages

Each dependency package in the list contains files used to satisfy binary dependencies. Please note that subsystems must be specified in this list.


Library Dependencies Checker: Limitations

The Library Dependency Checker tool cannot detect the following:

Missing dynamically loaded plugin libraries: because binaries will not contain linkage information for such libraries.

Binaries that do not have exec permissions.

Packaging and Installing RPMs

Packaging and installing RPM's is described in the following sections:

Packaging and Installing RPMs using a Predefined Directory Path

Packaging and Installing RPMs using a Post Install Script

RPM Installation Error Scenarios

Disclosure Statement for External RPMs

Installing SDK RPM Packages

RPM Conflicts and Dependencies

Packaging and Installing RPMs using a Predefined Directory Path

To use a predefined directory path for packaging and installing RPMs, follow the installation sequence described in RPM Installation Sequence.

RPM Installation Sequence

The Cisco AXP 1.5 SDK supports installing RPM packages sequentially using a priority file. This enables basic RPM packages (such as bash, coreutils) to be installed before other RPMs that are dependent upon the basic RPM packages.

To install RPMs sequentially using a priority file, perform the following steps:


Step 1 Create a priority file with the name rpm_priority.dat

The syntax of the priority file is:

:<rpm filename>:<priority>:

Example

:httpd.rpm:2: 
:mysql.rpm:1: 

Step 2 Add rpm_priority.dat to the predefined directory that stores the RPM packages to be installed. For automatic installation of RPMs this directory must be called third_party_rpms_repository. For more information on the directory, refer to the "Using a Predefined Directory Path for Packaging" section.


Using a Predefined Directory Path for Packaging

To package and install RPMs using a predefined directory path perform the following steps:


Step 1 From the project source directory, make sure a predefined directory is set up with a pathname relative to the project source directory. The directory name must be third_party_rpms_repository. An example of the path to this directory is: path /source/myapp/project/src/third_party_rpms_repository. In this case the project source directory is shown in the first part of the directory path: /source/myapp/project/src/.

Step 2 Put RPM packages that need to be installed, into the predefined directory: third_party_rpms_repository.

During packaging, the packaging tool checks for RPM packages in the predefined directory and creates manifest entries, marking the RPM files to be installed.

For further information, refer to the "Installing RPM Packages" section.


Using a Predefined Directory Path for Packaging: Example

Consider the following directory, specified to be the project source directory in the packaging tool: /source/myapp/project/src


/source/myapp/project/src/
                          third_party_rpms_repository/
                                                      httpd.rpm 
                                                      mysql.rpm 
                                                      php.rpm 
bin/
..
lib/

The packages httpd.rpm, mysql.rpm, and php.rpm are installed as RPMs.

Any other packages that exist in that predefined directory follow the regular file installation process in Cisco AXP.

Packaging and Installing RPMs using a Post Install Script

You can use a post install script to package RPMs, instead of using the method shown in the "Using a Predefined Directory Path for Packaging" section. RPM commands are available in CentOS.


Note If you choose to package RPMs using a post install script, you will have to handle upgrading the script. Cisco's upgrade commands are not aware of new files added during post install of RPMs.


To use a post install script for packaging and installing RPMs:


Step 1 Add RPM commands to directories of your choice.

Step 2 Implement a post install script to install the RPM packages.


Installing RPMs using a post install script may be better than using a pre-defined path in the following scenarios:

RPM packages must be installed conditionally

RPM packages must be installed with different option flags

RPM Installation Error Scenarios

An RPM package is a common Linux installation mechanism with its own error scenarios and these problems can occur in the AXPOS just as in other linux environments. This section explains common RPM error scenarios and how Cisco AXP passes the error results to developers, and what recovery steps developers can take.

Common RPM error scenarios are:

Corrupted RPMDB

Corrupted RPM package

Incompatible RPM package

Failed RPM scripts

Miscellaneous RPM Errors

Corrupted RPMDB

This is a common problem with the following example error messages:

rpmdb: Lock table is out of available locker entries

rpmdb: Unknown locker ID: d45

error: db4 error(22) from db->close: Invalid argument

error: cannot open Packages index using db3 - Cannot allocate memory (12)

error: cannot open Packages database in /var/lib/rpm

The error is due to users prematurely stopping RPM operations in the middle, breaking the cleanup of RPMDB lock files.

AXP installation attempts to recover from this issue, and a recovery is usually complete.

AXP cleans out the RPMDB stale lock files and rebuilds the RPMDB.

Shown below is an online source that has more details on this issue:

http://rackerhacker.com/2007/05/27/rpmdb-lock-table-is-out-of-available-locker-entries/

The recovery rarely fails. In this case, installation aborts and the user has to uninstall and reinstall the application. Log messages always record if RPMDB is corrupted, whether or not it is recoverable.

Corrupted RPM package

An RPM file can be corrupted or invalid. This may happen as a result of:

Naming a .txt file to an .rpm file

Corrupting the contents in the .rpm file

During the preinstall stage of AXP, all RPM packages to be installed are checked to be valid RPM files. If they are not, then installation aborts and log messages show this issue. The developer should examine the contents of the RPM packages, correct the problem, and rebuild a new RPM package.

Incompatible RPM package

Different versions of RPMs exist for different architectures and Linux distros, and are not always compatible with Cisco AXP. RPM packaging does not allow an incompatible RPM package to be installed. For example, an RPM for a 64 bit system cannot be installed on a 32 bit system—the AXP preinstall stage aborts the installation.

RPM packages having different Linux distros, such as Fedora Core or CentOS, might be able to be installed onto the system. However, you must make sure you are installing the right RPM for the Linux distribution you are using. The installed RPMs must be compatible with the Cisco AXPOS.

Failed RPM scripts

RPM packages contains pre/post install scripts, and are run during installation steps. Cases that cause these scripts to fail are:

A poorly written script—for example, syntax error in the script (using "cp" with one argument)
# cp a.txt

A well written script that fails—for example, dependency on another RPM not installed (dependency on the "sed" command)
# sed -e `ld' /etc/services

In both cases, the RPM installation results in a failure because of scripts errors. The AXP installation will log such errors, and continue with the remainder of the installation. You should check the log to see that the application is installed successfully. If there are installation errors in the log, you are recommended to uninstall the application, resolve the RPM scripts error and reinstall a correct application.

Miscellaneous RPM Errors

This category of errors includes remaining RPM errors that could happen during RPM installation.

An AXP installation always logs the RPM installation messages to the log, so you should check to make sure that all the RPMs are installed successfully. If there are any installation issues, you can try to resolve them by doing the following steps:


Step 1 Look at the console output and check for installation errors.

Step 2 Look at the log file and check for installation errors.

Step 3 If you can run the application, go to the application console and check the application environment (RPM command is available inside the application environment).

Step 4 If you cannot run the application, uninstall the application.

Step 5 Resolve the installation issues.

Step 6 Reinstall the corrected application.


Disclosure Statement for External RPMs


Warning Use of external RPMs for an application may result in the exposure of the Cisco AXPOS functionality. This exposure must be documented by third party developers in their product documentation.


For example, an application that uses the OpenSSH RPM to connect via SSH to an application may expose Cisco AXP features such as AXP APIs, IPC communication ports, and namespace to an outside connection.

Installing SDK RPM Packages

This section explains how to install RPMs from the Cisco AXP SDK to setup the linux environment on your development machine. The section is consists of the following subsections:

Development System Requirements

Cisco AXP Base RPM Packages

Installing RPM Packages

Trimming RPM Packages

Development System Requirements

For the development machine to be able to use RPM packages, the development machine's linux distribution must be similar to the CentOS 5.2 linux distribution that supports RPMs. The linux distribution must also support the installation of RPM packages to a chrooted environment and the chroot command.

Cisco AXP Base RPM Packages

The Cisco AXP SDK contains RPM packages in the following directory of the Cisco AXP SDK:

<sdk root>/centos-5.2/ 
                      coreutils.rpm 
                      basesystem.rpm 
                      bash.rpm 
                      grep.rpm 
                      ... 
                      ... 

Refer to the "Installing RPM Packages" section and the "Trimming RPM Packages" section on how to use RPM packages.

Installing RPM Packages

To install RPM packages in a chrooted environment, perform the following steps:


Note In a script to install RPM files, ensure that the proper installation sequence is maintained. This allows the pre-installation and post installation scripts in the RPM packages to work properly.



Step 1 Put the RPM packages (for example, Cisco AXP Base RPM Packages) in a location ready to be picked up by an installation script. In the example below, the location used by the installation script is: /src/axpos_rpms.

Step 2 Create an installation script for the RPM packages. An example is shown in the "Installation Script: Example" section.

Step 3 Run the installation script. In the example, the RPM packages are placed in the directory given by "root" /src/app_root

Step 4 Use the chroot command on the directory of RPM packages. In the example below, this directory is given by "root" /src/app_root.

chroot rpms-directory


Installation Script: Example


#!/bin/bash

root=/src/app_root
from=/src/axpos_rpms

function rpm_install {
    rpm=$1
    rpm -Uvh --nodeps --force --root ${root} ${rpm}
}

cd ${from}

rpm_install basesystem-8.0-5.1.1.noarch.rpm
rpm_install filesystem-2.4.0-1.i386.rpm
rpm_install glibc-2.5-24.i386.rpm
rpm_install libgcc-4.1.2-42.i386.rpm
rpm_install mktemp-1.5-23.2.2.i386.rpm
rpm_install ncurses-5.5-24.20060715.i386.rpm
rpm_install setup-2.5.58-1.noarch.rpm
rpm_install libtermcap-2.0.8-46.1.i386.rpm
rpm_install bash-3.2-21.i386.rpm
rpm_install audit-libs-1.6.5-9.i386.rpm
rpm_install libselinux-1.33.4-5.i386.rpm
rpm_install libsepol-1.15.2-1.i386.rpm
rpm_install shadow-utils-4.0.17-13.i386.rpm
rpm_install zlib-1.2.3-3.i386.rpm
rpm_install info-4.8-14.i386.rpm
rpm_install findutils-4.2.27-4.1.i386.rpm
rpm_install pcre-6.6-2.7.i386.rpm
rpm_install grep-2.5.1-54.2.i386.rpm
rpm_install libacl-2.2.39-3.i386.rpm
rpm_install libattr-2.4.32-1.1.i386.rpm
rpm_install coreutils-5.97-14.i386.rpm
rpm_install chkconfig-1.3.30.1-2.i386.rpm
rpm_install initscripts-8.45.19.EL-1.1.i386.rpm
rpm_install util-linux-2.13-0.47.i386.rpm
rpm_install beecrypt-4.1.2-10.1.1.i386.rpm
rpm_install bind-libs-9.3.4-6.P1.i386.rpm
rpm_install bind-utils-9.3.4-6.P1.i386.rpm
rpm_install bzip2-libs-1.0.3-3.i386.rpm
rpm_install curl-7.15.5-2.i386.rpm
rpm_install device-mapper-1.02.24-1.i386.rpm
rpm_install e2fsprogs-libs-1.39-15.i386.rpm
rpm_install elfutils-libelf-0.125-3.i386.rpm
rpm_install gawk-3.1.5-14.i386.rpm
rpm_install gzip-1.3.5-10.i386.rpm
rpm_install iputils-20020927-43.i386.rpm
rpm_install keyutils-libs-1.2-1.i386.rpm
rpm_install krb5-libs-1.6.1-25.i386.rpm
rpm_install less-394-5.i386.rpm
rpm_install libidn-0.6.5-1.1.i386.rpm
rpm_install libstdc++-4.1.2-42.i386.rpm
rpm_install net-tools-1.60-78.i386.rpm
rpm_install openssl-0.9.8b-10.i386.rpm
rpm_install popt-1.10.2-48.i386.rpm
rpm_install procps-3.2.7-9.i386.rpm
rpm_install readline-5.1-1.1.i386.rpm
rpm_install sed-4.1.5-5.i386.rpm
rpm_install sqlite-3.3.6-2.i386.rpm
rpm_install strace-4.5.16-1.1.i386.rpm
rpm_install sysklogd-1.4.1-44.i386.rpm
rpm_install SysVinit-2.86-14.i386.rpm
rpm_install tar-1.15.1-23.0.1.i386.rpm
rpm_install vim-minimal-7.0.109-3.3.i386.rpm
rpm_install which-2.16-7.i386.rpm
rpm_install rpm-libs-4.4.2-48.i386.rpm
rpm_install rpm-4.4.2-48.i386.rpm
rpm_install cracklib-2.8.9-3.3.i386.rpm
rpm_install cracklib-dicts-2.8.9-3.3.i386.rpm
rpm_install pam-0.99.6.2-3.27.i386.rpm
rpm_install sudo-1.6.8p12-12.i386.rpm
rpm_install glib2-2.12.3-2.i386.rpm
rpm_install libcap-1.10-26.i386.rpm
rpm_install libuser-0.54.7-2.el5.5.i386.rpm
rpm_install passwd-0.73-1.i386.rpm

Trimming RPM Packages

To conserve disk space, you can trim documentation files and trim RPM files from a package in the chroot environment.

Trim Documentation Files

When installing RPM packages using the postinstall script, you can trim documentation by using the excludedocs option in the rpm command:

rpm --Uvh --excludedocs <name of RPM>

(Refer to an rpm manual for more details on the excludedocs option.)

Trim RPM files in the chroot Environment


Note If you remove a file using the following procedure, you may exclude files that cause inconsistencies between the RPM database and the actual files on the file system.


In the following procedure, the rpm -e --repackage <RPM name> command creates a trimmed RPM in directory /var/spool/repackage.

To trim files from an RPM package, perform the following steps:


Step 1 Install the RPM package into the chrooted environment.

rpm -Uvh <RPM package name>

Step 2 Remove RPM files that are not required.

Step 3 Repackage the RPM. For example:

rpm -e --repackage <RPM package name>


Example

>rpm -Uvh httpd.rpm 
>rm -rf /usr/share/docs/httpd/* 
>rpm -e --repackage httpd 
>ls /var/spool/repackage 
httpd.rpm 

RPM Conflicts and Dependencies

RPM file conflicts and dependencies may be present at two levels during the installation and upgrade of the AXPOS and application add-on packages:

File Level Conflicts

An RPM installation or upgrade process extracts a file where there is already an existing file.
The existing file may have been generated by another RPM, or is an older version of the same RPM, or is a user-created file.

RPM Level Conflicts

A Cisco AXP installation or upgrade process attempts to install an RPM where there is already an existing RPM, or an upgrade process removes existing RPMs.

For further information on CentOS and RPM's refer to the "Additional References" section.

File Level Conflicts

RPMs differentiate files into configuration and non-configuration types. Conflict resolution is applied only to configuration files.

For more information on the resolution of file level conflicts, refer to the RPM upgrade section in the RPM manual pages published at: www.rpm.org

Configuration file conflicts are resolved by the RPM system when changes are made to the current application during:

A clean application installation or upgrade, or

An upgrade of the AXPOS add-on package.

File Level Conflict: Example

Table 109 summarizes RPM file level conflict resolution (for configuration files only). The MD5 checksums of the files are represented by x, y, and z.

For example, scenario number 4 represents a situation where the original file has a checksum x, and the current file has checksum y. The result is that the file is new (has been modified).

Table 109 RPM File Level Conflict Results

Scenario Number
Original file (MD5 checksum)
Current file (MD5 checksum)
New file
(MD5 checksum)
Result

1

x

x

x

New file

2

x

x

y

New file

3

x

y

x

Current file

4

x

y

y

New file

5

x

y

z

New file. The current file becomes <file>.rpmsave

6

None

y

z

New file. The current file becomes <file>.rpmorig



Note Developers must ensure that their application runs smoothly when a conflicting file is renamed, as shown in Table 109, scenario numbers 5 and 6.


RPM Level Conflicts

RPM packages are upgraded or downgraded irrespective of the RPM version that currently exists on the Cisco AXP.

In Cisco AXP 1.1 and lower versions, development and packaging an application follows a straight forward file-based manifest-style approach. This involves packaging application files from a directory using the packaging tool, and installing the application + add-ons package onto the AXPOS (base Linux Environment).

For Cisco AXP 1.5 and higher versions, RPM packaging is supported in addition to file-based packaging. Installation is more complex: an RPM package is a file archive and cannot be copied straight onto the file system. The RPM package files must be extracted upon installation, extracted and removed upon upgrade, removed upon uninstallation. When different RPM packages contain the same file the behavior varies.

Additional References

CentOS: http://www.centos.org

RPM's: http://www.rpm.org