Guest

Cisco Application Extension Platform

Cisco Application Extension Platform 1.5 Advanced Features Guide

  • Viewing Options

  • PDF (291.4 KB)
  • Feedback
Cisco Application Extension Platform 1.5 Advanced Features Guide

Table Of Contents

Cisco Application Extension Platform 1.5 Advanced Features Guide

Contents

Unrestricted Shell Access

Obtaining the Unrestricted Shell Add-on Package

Obtaining Unrestricted Shell Access

Capabilities

Packaging Tool (Non-interactive): Example

Specifying a Capabilities Category in the Development Authorization File

Capabilities Configuration File

@CCAPABILITIES: Context Capabilities

@FLAGS: Context Flags

@BCAPABILITIES: System Capabilities

@DEVFS: devfs

@PROCFS: procfs

@MODULES: Loadable Kernel Modules

Viewing Kernel Capabilities

Additional References

Loadable Kernel Module Support

LKM Types

Cisco Loadable Kernel Modules

Third Party Loadable Kernel Modules

LKM Verification and Troubleshooting

Safe Mode

Enabling Safe Mode

How to Build a Third Party LKM

Building a Third Party LKM

Troubleshooting the Build of a Third Party LKM

Viewing LKM Support

Building Additional Kernel Modules

Cisco AXP Commands for Advanced Features

debug shell

References

Notices


Cisco Application Extension Platform 1.5 Advanced Features Guide


This guide explains the advanced features of Cisco AXP for developers.

Use this document with other Cisco AXP documentation found in the "Support" section at: http://www.cisco.com/en/US/products/ps9701/index.html

Revised: 10/12/10, OL-21478-01

Contents

Unrestricted Shell Access

Capabilities

Loadable Kernel Module Support

Cisco AXP Commands for Advanced Features

References

Notices

Unrestricted Shell Access

The unrestricted shell, available using Cisco AXP 1.1 and higher versions, allows root access for debugging, monitoring CPU usage, or obtaining virtual memory statistics.

To obtain unrestricted shell access for your application:

1. Obtain the required software package from Cisco Developer Support, and perform the steps in the "Obtaining the Unrestricted Shell Add-on Package" section.

2. Install the add-on package by performing the steps in the "Obtaining Unrestricted Shell Access" section.

3. Install your application on the application service module.

To remove the debug shell add-on package, one option is to use the command software install clean to reinstall the Cisco AXP host OS package, and then reinstall all other required packages. For further details on these commands, see the Cisco AXP (1.1) Command Reference and the Release Notes for Cisco AXP.

Obtaining the Unrestricted Shell Add-on Package

To obtain unrestricted shell access, the debug shell add-on package obtained from Cisco Developer Support must be installed on top of AXP.

To obtain the debug shell package:


Step 1 Contact your Cisco AXP representative to apply for unrestricted shell access for a number of hardware application service modules or VMware system.

Step 2 If Cisco AXP marketing sends their approval for unrestricted shell access, you must sign a contract stating that you will not deploy or sell any hardware that includes the add-on package.

Step 3 Retrieve UDIs using the show license udi command (in Cisco AXP EXEC mode).

show license udi: Example

In this example, the command is run on VMware.

show license udi
PID            SN              UDI 
---------------------------------------------------
VME_APPRE-K9 	-- 			00:11:22:33:44:55

Step 4 Contact Cisco Developer Support and send a file that lists the UDIs of the hardware requiring access.

Step 5 Cisco Developer Support checks the list of UDIs you provide and sends you the debug shell add-on package contained in two files: axp-dbgshell.<vendorcompany>.<version>.prt1 (payload) and axp-dbgshell.<vendorcompany>.<version>.pkg.


Note You cannot modify the debug shell add-on package provided by Cisco Developer Support.



Obtaining Unrestricted Shell Access

To obtain unrestricted shell access:


Step 1 Install the debug shell add-on package onto the application service module using the software install package command.

Step 2 After installing the debug shell add-on package, use the show software versions detail or the
show tech-support command in Cisco AXP EXEC mode to verify that the debug shell package has successfully installed.

Verifying Debug Package Installation: Example

In this example the following output is displayed after you enter show software versions detail:

Name: Debug Shell built for  <Customer Name> (1.5)
 Desc: Debug shell - not for use  on production systems
   id:  8c7ea828-82ad-455f-b8a8-9dd965ce4d1b
 Type:  (plug-in)

Step 3 To verify root access, enter the debug shell command (in Cisco AXP EXEC mode):

If the command is successful, you see a bash shell allowing root access and a message containing the following phrase is logged to messages.log:

INFO AXP_debug_shell shll exec  Debug shell access has been  granted

If the command is unsuccessful, a message containing the following phrase is logged to messages.log:

ERROR AXP_debug_shell shll exec  Debug shell access has been  denied


Step 4 (Optional) To verify any attempted access or use of the unrestricted shell by a user, search the messages.log file for entries containing "debug shell" using the show log name command. For example:

show log name messages.log  |  include debug_shell

Capabilities

Capabilities allow the following additional functions to be enabled for an application.

Accessing the /dev and /proc file systems

Installing an LKM

Functions to access the host OS with root-level privileges: POSIX capabilities

If an application has permission to a category it can access and configure all capabilities belonging to category.

To obtain permissions to a capabilities category, contact Cisco Developer Services. See the "Specifying a Capabilities Category in the Development Authorization File" section for further details. The development authorization file/bundle controls capabilities permissions.

You can use capabilities defined in the capabilities configuration file to relax certain restrictions in a virtual instance. Use a single host-level capability or kernel-level capability with one application in the system.


Note If more than one application is installed and they modify the same shared resources, we do not provide any arbitration to resolve the conflict. There is no guarantee of the order of processing, or error reporting.


There are three categories of capabilities:

Guest-level capabilities—only affect the virtual instance.

Host-level capabilities—affect the whole system.

Kernel-level capabilities—used for installing third-party LKMs, see the "Third Party Loadable Kernel Modules" section.


Note Capabilities that are included with an add-on application are ignored.


If you have permissions for a capability category, you can turn on any of the capabilities within that category. If you add a new capability to a category, the capability can be accessed by any existing applications that already have access to that category. This saves you from having to repackage a new development authorization file with your application.

During packaging of your application, specify the capabilities configuration file using parameter "cap-config".


Note Network context flags (nflags) are not supported by Cisco AXP.


The following sections describe the capabilities configuration file, and the development authorization file as it relates to capabilities.

Packaging Tool (Non-interactive): Example

Specifying a Capabilities Category in the Development Authorization File

Capabilities Configuration File

Packaging Tool (Non-interactive): Example

The following example shows how to specify the capabilities configuration file during packaging. To do this, the packaging tool pkg_build.sh is called in non-interactive mode.

The last argument in the call of pkg_build.sh is cap-config, which references the capabilities configuration file /capabilities.cfg. The capabilities configuration file is at the same level as the project source directory or file post-install.sh.


./pkg_build.sh --project-dir '/wsa/proj-cap' --dev-cert 
'/wsa/auth/cert/dev_certificate.sig' --dev-auth '/wsa/auth/cert/dev_authorization.sig' 
--private-key '/wsa/auth/cert/private.key' --name 'capdev' --version '1' --source-dir 
'/wsa/captest/bin/' --disk-limit '100M' --memory-limit '50M' --cpu-limit '1000' 
--postinstall '/post-install.sh' --cap-config '/capabilities.cfg'

Specifying a Capabilities Category in the Development Authorization File

The development authorization file contains attributes to control the capabilities categories that are turned on/off. If a capability category is turned on, you can access the capabilities in the category. The attributes are: guest_admin, host_admin, and kernel_admin.

To obtain permission to a capabilities category for an application package, perform the following steps.


Step 1 Contact Cisco Developer Support and obtain a development authorization file that grants permission to use a capabilities category.

Step 2 Create a configuration file that specifies the capabilities to be turned on. See the "Capabilities Configuration File" section.

Step 3 Package the configuration file along with the development authorization file using the packaging tool pkg_build.sh. For example, include the parameter --cap-config '/capabilities_file'

Step 4 Install the application package. The application access now has access to capabilities specified in the capabilities configuration file.


If your application is being repackaged as part of an upgrade and previously contained an older configuration file, permission to access old (previously granted) capabilities are removed and permission to access new capabilities are added. Therefore, before running the application, make sure that application commands using old capabilities are removed or blocked.

Capabilities Configuration File

Different capabilities are listed in sections of the capabilities configuration file. Each section begins with the "@" symbol.

Capabilities Configuration File: Example

The CCAPABILITIES section is the first section in this example configuration file, shown using the command cat. CCAPABILITIES are context capabilities. The module ip_tables.ko is a Cisco LKM, and module /mypath/to/module/my.ko is the name of the third-party LKM.

$ cat capabilities_file

@CCAPABILITIES=
UTSNAME
RLIMIT
RAW_ICMP 
SYSLOG
SECURE_MOUNT 

@FLAGS=
FAKEINIT
VIRT_MEM
VIRT_UPTIME
VIRT_CPU

@BCAPABILITIES=
SYS_NICE
NET_ADMIN
SYS_TIME
MKNOD
SYS_MODULE
SYS_ADMIN
SYS_CHROOT

@DEVFS=
/dev/loop0 b 7 0
/dev/loop1 b 7 1
/dev/loop2 b 7 2
/dev/null c 1 3
/dev/myown b 2 2

@PROCFS=
/proc/bus/
/proc/sys/vm/overcommit_memory 0
/proc/sys/net/ipv4/ip_forward 0

@MODULES=
ip_tables.ko
iptable_filter.ko
/mypath/to/module/my.ko

The capabilities in the configuration file are explained in the following sections:

@CCAPABILITIES: Context Capabilities

@FLAGS: Context Flags

@BCAPABILITIES: System Capabilities

@DEVFS: devfs

@PROCFS: procfs

@MODULES: Loadable Kernel Modules


Note Network context flags (nflags) are not supported.


@CCAPABILITIES: Context Capabilities

Context capabilities (ccaps) are guest-level capabilities, which apply to all processes within a virtual instance. One capability is defined per entry in the capabilities configuration file.

Example:

@CCAPABILITIES=
UTSNAME

For a list of supported context capabilities, see Table 1.

Note: The following ccaps are not supported by Cisco AXP:

ADMIN_MAPPER

ADMIN_CLOOP

Table 1 @CCAPABILITIES: Context Capabilities

Bit
Mask
Name
Description

0

0x00000001

UTSNAME

Allow setdomainname(2) and sethostname(2)

1

0x00000002

RLIMIT

Allow setrlimit(2)

8

0x00000100

RAW_ICMP

Allow usage of raw ICMP sockets

12

0x00001000

SYSLOG

Allow syslog(2)

16

0x00010000

SECURE_MOUNT

Allow secure mount(2)

17

0x00020000

SECURE_REMOUNT

Allow secure remount

18

0x00040000

BINARY_MOUNT

Allow binary/network mounts

20

0x00100000

QUOTA_CTL

Allow quota ioctls


@FLAGS: Context Flags

Context flags (cflags) apply to all processes within a virtual instance.

Example:

@FLAGS=
FAKEINIT
VIRT_MEM

For a list of supported context flags, see Table 2.

Note: The following cflags are not supported in Cisco AXP:

INFO_SCHED

VIRT_TIME

HIDE_VINFO

STATE_ADMIN

SC_HELPER

REBOOT_KILL

PERSISTENT

SCHED_HARD

SCHED_PRIOR

SCHED_PAUSE

Table 2 @FLAGS: Context Flags

Bit
Mask
Name
Tag
Description

0

0x00000001

LOCK

L

Prohibit further context migration

2

0x00000004

INFO_NPROC

L

Apply process limits to context

3

0x00000008

INFO_PRIVATE

L

Context cannot be entered

4

0x00000010

FAKEINIT

X

Show a fake init process

5

0x00000020

HIDEINFO

X

Hide context information in task status

6

0x00000040

ULIMIT

L

Apply ulimits to context

7

0x00000080

NAMESPACE

L

Use private namespace

20

0x00010000

VIRT_MEM

 

Virtualize memory information

21

0x00020000

VIRT_UPTIME

 

Virtualize uptime information

22

0x00040000

VIRT_CPU

 

Virtualize cpu usage information

23

0x00080000

VIRT_LOAD

 

Virtualize load average information

28

0x01000000

HIDE_MOUNT

 

Hide entries in /proc/$pid/mounts

29

0x02000000

HIDE_NETIF

 

Hide foreign network interfaces

32

0x0001<<32

STATE_SETUP

IO

Enable setup state

33

0x0002<<32

STATE_INIT

IO

Enable init state

48

0x0001<<48

FORK_RSS

 

Block fork when RSS limit is exceeded

49

0x0002<<48

PROLIFIC

 

Allow context to create new contexts

52

0x0010<<48

IGNEG_NICE

 

Ignore priority raise


@BCAPABILITIES: System Capabilities

System capabilities (bcaps) apply to all virtual instances in Cisco AXP.

Example:

@BCAPABILITIES=
SYS_NICE
NET_ADMIN

For a list of system capabilities supported in Cisco AXP, see Table 3.


Note The following system capabilities are not supported by Cisco AXP: SYS_MODULE, SYS_CHROOT, SYS_ADMIN, and MKNOD.


Table 3 @BCAPABILITIES: System Capabilities

Bit
Mask
Name
Description

0

0x00000001

CHOWN

In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, this overrides the restriction of changing file ownership and group ownership.

1

0x00000002

DAC_OVERRIDE

Override all DAC access, including ACL execute access if [_POSIX_ACL] is defined. Excludes DAC access covered by CAP_LINUX_IMMUTABLE.

2

0x00000004

DAC_READ_SEARCH

Overrides all DAC restrictions regarding read and search on files and directories, including ACL restrictions if [_POSIX_ACL] is defined. Excludes DAC access covered by CAP_LINUX_IMMUTABLE.

3

0x00000008

FOWNER

Overrides all restrictions about allowed operations on files, where file owner ID must be equal to the user ID, except where CAP_FSETID is applicable. It does not override MAC and DAC restrictions.

4

0x00000010

FSETID

Overrides the following restrictions that the effective user ID must match the file owner ID when setting the S_ISUID and S_ISGID bits on that file; that the effective group ID (or one of the supplementary group IDs) must match the file owner ID when setting the S_ISGID bit on that file; that the S_ISUID and S_ISGID bits are cleared on successful return from chown(2) (not implemented).

5

0x00000020

KILL

Overrides the restriction that the real or effective user ID of a process sending a signal must match the real or effective user ID of the process receiving the signal.

6

0x00000040

SETGID

Allows setgid(2) manipulation.

Allows setgroups(2).

Allows forged gids on socket credentials passing.

7

0x00000080

SETUID

Allows set*uid(2) manipulation (including fsuid).

Allows forged pids on socket credentials passing.

8

0x00000100

SETPCAP

Transfer any capability in your permitted set to any pid, remove any capability in your permitted set from any pid.

9

0x00000200

LINUX_IMMUTABLE

Allow modification of S_IMMUTABLE and S_APPEND file attributes.

10

0x00000400

NET_BIND_SERVICE

Allows binding to TCP/UDP sockets below 1024.

Allows binding to ATM VCIs below 32.

11

0x00000800

NET_BROADCAST

Allow broadcasting, listen to multicast.

12

0x00001000

NET_ADMIN

Note: For further information on this capability, refert to the "NET_ADMIN Capability" section.

Allow interface configuration.

Allow administration of IP firewall, masquerading and accounting.

Allow setting debug option on sockets.

Allow modification of routing tables.

Allow setting arbitrary process / process group ownership on sockets.

Allow binding to any address for transparent proxying.

Allow setting TOS (type of service).

Allow setting promiscuous mode.

Allow clearing driver statistics.

Allow multicasting.

Allow read/write of device-specific registers.

Allow activation of ATM control sockets.

13

0x00002000

NET_RAW

Allow use of RAW sockets.

Allow use of PACKET sockets.

14

0x00004000

IPC_LOCK

Allow locking of shared memory segments.

Allow mlock and mlockall (which doesn't really have anything to do with IPC).

15

0x00008000

IPC_OWNER

Override IPC ownership checks.

17

0x00020000

SYS_RAWIO

Allow ioperm/iopl access.

Allow sending USB messages to any device via /proc/bus/usb.

19

0x00080000

SYS_PTRACE

Allow ptrace() of any process.

20

0x00100000

SYS_PACCT

Allow configuration of process accounting.

22

0x00400000

SYS_BOOT

Allow use of reboot().

23

0x00800000

SYS_NICE

Allow raising priority and setting priority on other (different UID) processes.

Allow use of FIFO and round-robin (realtime) scheduling on own processes and setting the scheduling algorithm used by another process.

Allow setting cpu affinity on other processes.

24

0x01000000

SYS_RESOURCE

Override resource limits. Set resource limits.

Override quota limits.

Override reserved space on ext2 file system.

Modify data journaling mode on ext3 file system (uses journaling resources).

Note ext2 honors fsuid when checking for resource overrides, so you can override using fsuid too.

Override size restrictions on IPC message queues.

Allow more than 64hz interrupts from the real-time clock.

Override max number of consoles on console allocation.

Override max number of keymaps.

25

0x02000000

SYS_TIME

Allow manipulation of system clock.

Allow irix_stime on mips.

Allow setting the real-time clock.

26

0x04000000

SYS_TTY_CONFIG

Allow configuration of tty devices.

Allow vhangup() of tty.

28

0x10000000

LEASE

Allow taking of leases on files.


NET_ADMIN Capability

The NET_ADMIN capability allows:

the removal of restrictions on network administration from the guest OS application, such as creating interfaces

the management of networking operations as if on the host OS

Refer to the "NET_ADMIN Capabilities List" section. This shows a BCAPABILITY of NET_ADMIN, and flag CISCO_ADVANCED_NET_ADMIN.


Note If CISCO_ADVANCED_NET_ADMIN is enabled, then managing networking operations is only done using the application (through the console/linux shell). Entering AXP commands (such as "bind interface") via the CLI is not supported.



Note When running an application in a virtual instance, do not change the IP address of interface eth0.
Interface eth0 must be configured from the Cisco IOS router, not from the application.


NET_ADMIN Capabilities List

@CISCO_FLAGS=
CISCO_ADVANCED_NET_ADMIN

@BCAPABILITIES=
NET_ADMIN

@MODULES=
tun.ko

@DEVFS: devfs

The @DEVFS section of the capabilities configuration file contains entries for each device node in the /dev file system. Data in each device node is written at packaging time.

Each devfs entry consists of the following four attributes, separated by a single space character:

<device name> <device type> <major number> <minor number>

Each attribute is described in Table 4.

Table 4 devfs attributes

/dev file system attribute
Example
Description

<device name>

/dev/loop0

Identifies the device driver.

<device type>

b

b (block): system moves data in blocks.

c (character): system moves data in characters.

<major number>

7

Determines handling of subdevices by the device driver.

<minor number>

0

Determines handling of subdevices by the device driver.


Example:

In the following example, /dev/loop0 is a loopback disk device.

@DEVFS=
/dev/loop0 b 7 0
/dev/loop1 b 7 1
...

The /dev file must exist at the specified location at installation time. Errors are logged to /var/log/messages.log.

@PROCFS: procfs

The @PROCFS section of the capabilities configuration file contains /proc file system entries. Each entry represents a directory that can be unhidden at runtime and viewed by an application in a virtual instance. Applications can make changes to writable entries in the /proc file system, typically in the /proc/sys directory.

This host-level capability is exposed to the guest OS, and visible in all virtual instances. For detailed information of the available /proc file system entries, contact Cisco Developer Support.

Each entry in @PROCFS section of the capabilities configuration file may use * (the wildcard character) for pattern matching.

Each entry in the configuration file starts with "/proc/".

If an entry contains a pathname ending in "/", files underneath are unhidden recursively. For example, the "/proc/bus/" entry in the @PROCFS example below means that files in sub-directories such as /proc/bus/a /proc/bus/b are unhidden.

Example

@PROCFS=
/proc/vmstat
/proc/bus/
/proc/sys/overcommit_memory  2
...

If an entry ends in *, this indicates that all directories on the same level are unhidden. For example, /proc/bus* indicates with names such as /proc/busa or /proc/busb.

Each valid /proc entry is added to the virtual instance.

Upgrading an application to expose the /proc file system follows the rules outlined in the "Unrestricted Shell Access" section of the Cisco Application eXtension Platform Developer Guide.

Contact Cisco Developer Services to ask if a particular /proc file system entry is supported.

Modifying a /proc Entry

Each writable /proc entry may have an optional second parameter that specifies a value. The value is separated from the rest of the entry by a single space character. There is no arbitration of conflicts arising from different virtual instances writing to the same /proc entry.

Example

In the following example the value of 2 modifies the /proc entry, and any errors are logged to /var/log/messages.log. The existence of /proc/sys/overcommit_memory is not checked, and the value of "2"is not checked.

/proc/sys/overcommit_memory 2


Note If an application exposes a /proc file system, the file system is visible to any application in all virtual instances.


@MODULES: Loadable Kernel Modules

The @MODULES section of the capabilities configuration file lists the loadable kernel modules (full pathname), to be installed, in order. If just the value of ".ko" is supplied (without no pathname), then the module is treated as a Cisco-provided kernel module.

Example

@MODULES=
/mypath/to/module/my.ko 	? third-party module
/mypath/to/module2/my2.ko	? third-party module
ip_tables.ko							? Cisco provided ko
/mypath/to/module3/my3.ko		 ? third-party module

A third-party kernel module entry includes the full path name of the module. (Symbolic links or soft links to module names are not supported.)

For non-Cisco provided modules, the full pathname must indicate the location of the module. The path must be absolute (non-relative).

During installation, no checks are performed. However, on system boot up, all the modules are added, and any errors are logged to /var/log/messages.log.

Viewing Kernel Capabilities

Use the show tech-support command in Cisco AXP application service EXEC mode to view kernel capabilities that were set up on the service module.

show tech-support: Example

se-10-0-0-0(exec-guest-application)> show tech-support | begin Capabilities
------------------ Application Capabilities------------------
System Capabilities:
                DAC_OVERRIDE
                DAC_READ_SEARCH
                FOWNER
                FSETID
                KILL
                SETGID
                SETUID
                SETPCAP
                NET_ADMIN
Context Capabilities:
                UTSNAME
                RLIMIT
                RAW_ICMP
                SYSLOG
                SECURE_MOUNT
                SECURE_REMOUNT
                BINARY_MOUNT
                QUOTA_CTL
Dev FS:
                /dev/null c 1 4
                /dev/mytest b 20 8
                /dev/loop0 b 7 0
                /dev/loop1 b 7 1
Net Flags:
Proc FS:
                /proc/test blah
                /proc/sys/net/ipv4/ip_forward 0
Kernel Modules:
                cisco_module.ko
                /mymod/capture.ko

The following capabilities have errors when applied:
Proc FS:  /proc/test blah
Kernel Modules:  cisco_module.ko
 
The following capabilities have errors during installation:
System Capabilities: SYS_ADMIN

Additional References

For further information on capabilities, see http://linux-vserver.org/Capabilities_and_Flags.

Loadable Kernel Module Support

Loadable kernel module (LKM) support on Cisco AXP is provided by Cisco, or a third-party.

. The following sections describe both Cisco and third-party LKMs

LKM Types

LKM Verification and Troubleshooting

Safe Mode

How to Build a Third Party LKM

Viewing LKM Support

Building Additional Kernel Modules

LKM Types

LKMs for Cisco AXP consist of the following types:

Cisco Loadable Kernel Modules

Third Party Loadable Kernel Modules

Cisco Loadable Kernel Modules

Cisco AXP supports Cisco-provided loadable kernel modules (Cisco LKMs). Cisco LKMs are in the Cisco AXP base image. To use the LKMs, you must first package the LKMs with your application. Your application needs to have host-level capability. Refer to the "Capabilities" section.

Specify the list of Cisco LKMs at packaging time in the @MODULES section of the capabilities configuration file.

Example

In this example, third-party LKMs mymodule.ko and mymodule2.ko are specified in the capabilities configuration file.

@MODULES=

ip_tables.ko

iptable_filter.ko

List of Cisco LKMs

ip_tables.ko

iptable_filter.ko

iptable_mangle.ko

ip_queue.ko

tun.ko

Third Party Loadable Kernel Modules

Loadable Kernel Modules (LKMs), which are not provided by Cisco, are known as third-party LKMs. You can package third-party LKMs with your application if the application has a kernel-level capability. Refer to the "Capabilities" section.

During packaging, specify kernel modules in the "@MODULES" section of the capabilities configuration file.


Note For third-party LKMs, the full path name to the module is required, using full pathnames relative to the root folder of the virtual instance.


Example

In this example, third-party LKMs mymodule.ko and mymodule2.ko are specified in the capabilities configuration file.

@MODULES=

/my/path/to/module/mymodule.ko

/my/path/to/module/mymodule2.ko

The modules are copied to the application service module during installation. They are installed during startup after the application service module reloads. (Currently the application service module always reloads after an application is installed.)

When the system boots up, each kernel module is installed into the kernel, before the virtual instance starts. If a virtual instance is started and stopped, this does not affect any installed kernel modules.

If an application with kernel modules is uninstalled, the kernel modules are removed along with the contents of the virtual instance.

Upgrading Cisco AXPOS

If you are considering upgrading Cisco AXPOS to a higher version, determine if your kernel modules will continue to work after the new version of Cisco AXP is installed.

Installing the LKMs might fail if you have an old version of your kernel module that does not match the new version of the OS. Failures that occur during installation, are logged to the file /var/log/messages.log. If a failure occurs because of a kernel module: rebuild the kernel module using a newer version of the LKM SDK, repackage and upgrade the application.

Controlling LKMs at Runtime

If your application is packaged with a dependency on the application development package axp-app-dev.<product>.<version>.pkg and you have kernel-level capability, you can install or uninstall kernel modules with your application at runtime. In the test environment the LKMs are added or removed depending on the contents of the capabilities configuration file. This avoids having to repackage your application each time that you want to test a kernel module.


Note In the production environment, do not run applications that were packaged with the application development package. This ensures the user cannot change the capabilities that you previously setup for the application during packaging.


To add or modify an LKM at runtime, perform the following steps:


Step 1 Install your application with a dependency upon the application development package axp-app-dev.<platform>.<version>.pkg.

Step 2 Ensure the LKM filename to be added or modified is included as one of the @MODULE files listed in the capabilities configuration file. (For example, /my/path/to/module/mymodule.ko)

Step 3 app-service <application-name>

Enters application service mode.

Step 4 reset

The virtual instance resets and the new LKMs are loaded.


LKM Verification and Troubleshooting

Use the following command to verify configurations or to troubleshoot:

show tech-support | begin Capabilities

Displays logs to help determine which modules are causing errors.

Another command that may be used to verify or troubleshoot, is lsmod. To use this command, first install the RPM file for lsmod, which is modutils. The lsmod command displays the loaded kernel modules of /proc/modules.


Note The show tech-support command may show errors for modules crc32.ko or bitrev.ko if the application was previously packaged with these two modules. These errors can be ignored. The modules crc32.ko and bitrev.ko are no longer required in the capabilities configuration file because they are part of the kernel in AXP 1.5.2 or higher.


To see if third-party LKMs are affecting an error, enable safe mode. Refer to the "Safe Mode" section.

Safe Mode

Enabling safe mode on Cisco AXP prevents the system from installing third-party kernel modules at startup.

A kernel oops, introduced by a developer-provided kernel module, may send the system into a continuous crash loop. This makes the system inaccessible when the system installs all modules at bootup.

Enabling Safe Mode

To enable safe mode, perform the following step.


Step 1 When the system boots up, enter the following keystroke sequence after you see the prompt:

###

The message "Entering Safe Mode" appears.

The following Safe Mode Menu appears:

1) Erase startup configuration

2) Show startup configuration

3) Show messages.log

4) Do not load third-party LKMs on startup

5) Continue

Enter 1-5>

Step 2 Enter the following option number:

4

The following Safe Mode Menu appears again:

1) Erase startup configuration

2) Show startup configuration

3) Show messages.log

4) Do not load third-party kernel modules on startup

5) Continue

Enter 1-5>

Step 3 Enter the following option number:

5

The third-party LKM is disabled.


Note After entering safe mode, if you do not enter a keystroke sequence the system boots up normally after a delay of a few seconds.



How to Build a Third Party LKM

This section contains the following procedures:

Building a Third Party LKM

Troubleshooting the Build of a Third Party LKM

Building a Third Party LKM

Prerequisites

Check that the shell environment is set to use bash, before executing the make tools command. (If the environment is set to csh, errors might occur.)

Make sure that the linux distribution installed on your development machine has basic development packages installed, such as gcc, and gnu make. For example, in the CentOS 5.2 linux distribution, the following minimum RPMs are required to build the LKM:

gcc-4.1.2-42.el5.i386.rpm

make-3.81-3.el5.i386.rpm

bison-2.3-2.1.i386.rpm

flex-2.5.4a-41.fc6.i386.rpm

texinfo-4.8-14.el5.i386.rpm

The LKM SDK has been successfully tested on Debian, Fedora, and OpenSuse based systems.

To build a third-party LKM, refer to the following two sections:

Building the SDK

Building a Third Party LKM

Building the SDK

To build the SDK, perform the following steps:


Step 1 Untar axp-lkm-sdk.<version>.tar.gz.

Step 2 Enter the following command in the top level directory: make tools (builds the SDK tool chain).

A gcc binary in directory <path to sdk root>/image/gcc can be used to build a third-party LKM against the kernel supplied in the Cisco AXP SDK. The SDK kernel directory is:
<path to sdk root>/image/kernel-2.6.22/linux/include.


Note For ISM and SM service modules, you must include "PLATFORM=sme" in the make tools command. For example, make tools PLATFORM=sme. If this parameter is not specified, a failure will result later when the kernel module is loaded.
For NME or AIM2 service modules PLATFORM does not need to be specified. The default is "PLATFORM=nme". For example, make tools PLATFORM=nme is equivalent to make tools.




Note To clean up the SDK tool chain issue the make cleantools command in the top level directory.



Note For Cisco AXP 1.5.2, the LKM SDK glibc version 2.3.5 is replaced by glibc version 2.7.
glibc (2.7) supports the Native POSIX Thread Library (NPTL) and Thread Local Storage (TLS).


Building a Third Party LKM

To build an LKM against the SDK kernel, perform the following steps:


Step 1 Create a directory containing the third-party LKM source files.

Step 2 Set the environment variable PATH to use the gcc binary in directory <path to sdk root>/image/gcc

Step 3 Create a make file used for building a third-party LKM.

Example

obj-m += hello1_22.o
--include-dir=/<path to sdk root>/image/kernel-2.6.22/linux/include
all:
	make -C /<path to sdk root>/image/kernel-2.6.22/linux M=$(PWD) ARCH=i386 modules

The second line has an --include-dir path that points to the SDK kernel directory:
/<path to sdk root>/image/kernel-2.6.22/linux/include

The fourth line includes the path to the "linux" directory:
/<path to sdk root>/image/kernel-2.6.22/linux

Step 4 Run the make command to build the third-party LKM.


Troubleshooting the Build of a Third Party LKM

If the LKM build fails with the error indicating that "makeinfo" is missing, but "makeinfo" is installed and included in the PATH, check that the "makeinfo" version is between 4.4 and 4.9.
makeinfo versions 4.10 and higher may have issues due to a bug in the configure script logic that incorrectly checks the version of "makeinfo". There are two workarounds for this:

1. Install a version of "makeinfo" from version 4.4 to 4.9

OR

2. Modify the configuration script under tools/gpl/binutils-2.18/configure to allow for versions 4.10 and above. To modify the script, perform the following step:


Step 1 Refer to the line 6131 of file "tools/gpl/binutils-2.18/configure", and change the line containing "egrep" in the following section of code:

    # For an installed makeinfo, we require it to be from texinfo 4.4 or
    # higher, else we use the "missing" dummy.
    if ${MAKEINFO} --version \
       | egrep 'texinfo[^0-9]*([1-3][0-9]|4\.[4-9]|[5-9])' >/dev/null 2>&1; then
      :
    else
      MAKEINFO="$MISSING makeinfo"
    fi


Change the "egrep" line so that the above section of code looks like this:

    # For an installed makeinfo, we require it to be from texinfo 4.4 or
    # higher, else we use the "missing" dummy.
    if ${MAKEINFO} --version \
       | egrep 'texinfo[^0-9]*([1-3][0-9]|4\.[0-9]|[0-9])' >/dev/null 2>&1; then
      :
    else
      MAKEINFO="$MISSING makeinfo"
Fi

Viewing LKM Support

To view LKM support details, use the show tech-support command in application service EXEC mode. show tech-support displays:

Kernel modules to be installed by the application

Kernel modules that were not installed, but were listed by the application—failure messages for these uninstalled modules are held in /var/log/messages.log.

Building Additional Kernel Modules

This procedure is for building additional kernel modules from kernel module source files in the Cisco AXP SDK.

To build additional LKMs to support your system hardware, perform the following steps:

Prerequisite

Build the LKM SDK—refer to the "Building the SDK" section.


Step 1 cd <path to sdk root>/image/kernel-2.6.22/linux/

Step 2 cp .config .config.bak

Copies the ".config" file to a backup file.

Step 3 Run the make menuconfig command.

Different kernel configuration options are displayed on the screen.

Step 4 From the menu, select the additional module that you want to build.

For example, to enable driver PL2303 use the following instructions in the make menuconfig menu:

Select > Device Drivers > USB support > USB serial converter support > <M> USB serial converter support > <M> USB Prolific 2303 Single Port Serial Driver

Step 5 Select the dependent modules required for the new module.

Step 6 Click Enter to save the configuration, and exit from make menuconfig.

Determine the differences (diffs) between the new, modified ".config" file and the old ".config" file (.config.bak). The diffs may include extra configurations required to build your module. Refer to diff: Example.

Step 7 Modify the .config file to contain both the original configuration from .config.bak and include any desired configurations from the ".config" file modified in step 6. The ".config" file contains both the original configuration and any additional configuration steps that are required to build your module.

Step 8 cd <path to sdk root>/gplCore/kernel-2.6.22

Step 9 Run the make modules command to build the LKM. Refer to the make modules: Example.

The newly built kernel modules are contained in directory  
<path to sdk root>/image/kernel-2.6.22/linux.

These modules can be viewed as follows:

:cd <path to sdk root>/image/kernel-2.6.22/linux
: find -name "*.ko"
./usb/serial/pl2303.ko
./usb/serial/usbserial.ko
:

diff: Example

In the first part of this example, the diffs are checked and the following config parameters are obtained—CONFIG_USB_SERIAL=m and CONFIG_USB_SERIAL_PL2303=m:

:cd <path to sdk root>/gplCore/kernel-2.6.22/app_config/axp
:diff dotconfig-regular-i386-nme.old dotconfig-regular-i386-nme
26a27,31
> CONFIG_USB_SERIAL=m
> CONFIG_USB_SERIAL_PL2303=m
>

If the two parameters (CONFIG_USB_SERIAL=m and CONFIG_USB_SERIAL_PL2303=m:) are required to build your module, keep them in the ".config" file that is used when running the make modules command.

make modules: Example

:cd <path to sdk root>/gplCore/kernel-2.6.22
: make modules
sh <path to sdk root>/makeinc/build_native.sh \
    sh -c 'PATH=/bin:/usr/bin: 
<path to sdk root>//target/i586-os+fndn+app-devtest-nme/tool-chain/usr/bin \
      make ARCH=i386 \
        HOSTCC=gcc \
        
CROSS_COMPILE= 
<path to sdk root> 
//target/i586-os+fndn+app-devtest-nme/tool-chain/cross/bin/i686-pc-linux-gnu- \
        -w -C 
<path to sdk root>//target/i586-os+fndn+app-devtest-nme/gplCore/kernel-2.6.22/linux 
modules'
  CHK     include/linux/version.h
  CHK     include/linux/utsrelease.h
  CALL    scripts/checksyscalls.sh
  Building modules, stage 2.
  MODPOST 15 modules
 
  LD [M]  drivers/usb/serial/pl2303.ko
  LD [M]  drivers/usb/serial/usbserial.ko
:

Cisco AXP Commands for Advanced Features

The following command is used for configuration of Advanced Features:

debug shell

debug shell

To obtain unrestricted shell access, use the debug shell command in Cisco AXP EXEC mode.

debug shell

Syntax Description

This command has no arguments.

Defaults

No default behavior or values.

Command Default

None.

Command Modes

Cisco AXP EXEC.

Command History

Cisco AXP Version
Modification

1.1

This command was introduced.


Usage Guidelines

Use the debug shell command for unrestricted root shell access.

PREREQUISITES

Before invoking the debug shell command in Cisco AXP EXEC mode, install the debug shell add-on package after obtaining authorization from your Cisco representative.

Refer to the "Obtaining Unrestricted Shell Access" section about installing the debug shell package.

Related Commands

Command
Description

show software versions

Displays the software versions.

show tech-support

Displays diagnostic information about the application environment.


References

Reference other Cisco AXP guides under "Support" information at: http://www.cisco.com/en/US/products/ps9701/index.html.

Notices

This product includes software developed by the OpenSSL project for use in the OpenSSL Toolkit.
For further details, see the "Notices" section of the Release Notes for Cisco Application eXtension Platform.