Table Of Contents

IOS CLI API

Overview

Java

Java Signatures

Class and Methods

IosServiceAPI

Java Example

C/C++

C/C++ Signatures

Class and Methods

IosServiceAPI_t

IosapiMessage_t

C/C++ Example

Python

Python Signatures

Iosapi

Python Example

Perl

Perl Signatures

Iosapi

Perl Example

Bash

Bash Signatures

Bash Examples

CLI Commands for Viewing and Clearing IOS CLI API Records

IOS CLI API

---

This chapter contains the following sections:

•Overview

•Java

•C/C++

•Python

•Perl

•Bash

•CLI Commands for Viewing and Clearing IOS CLI API Records

Overview

Use the IOS CLI API to issue the following selected commands on the Cisco IOS router:

•Copy commands—for example, copy running-config startup-config

•Show commands—for example, show running-config

•Configuration commands—for example, int fa9/0

Package your application with the IOS CLI API package as a dependency. Refer to the optional features Table 4 on page 26.

Multiple configuration commands can be passed at one time by using a semi-colon delimiter. However, multiple exec commands are not allowed.

For example, multiple configuration commands can be invoked as follows:

iosapi --mode config "int fa9/0; ip address 172.31.100.195; no shutdown"

To run an application that uses the IOS CLI API, you must configure the router and service module using NETCONF. Refer to the "Netconf" section on page 314.

---

Note For Cisco AXP 1.5.2 and below, issuing the do command through the IOS CLI API always returns "OK". —if the do command runs successfully.
For example, the do show run command returns "OK" instead of returning the show run command output. If the do command fails, the return value is "ERROR: operation failed."
However, issuing the do command through a Cisco IOS CLI console session returns the correct error messages when the do command fails.

---

Java

•Java Signatures

•Java Example

Java Signatures

•Class and Methods

•IosServiceAPI

Class and Methods

Table 10 Java IOS CLI API Class and Methods

Class/Method
public class IosapiMessage { public void setRequest(String request); public void setResponse(String response); public String getRequest(); public String getResponse(); }

IosServiceAPI

Table 11 Java IosServiceAPI Methods

Method	Description
int exec(IosapiMessage ( ))	Method for invoking exec CLI command.
int config(IosapiMessage msg)	Method for invoking config CLI command.

Table 12 shows returned integer values; for example from calls to the exec( ) method.

Table 12 Java IOS CLI API Return Status Codes

Status Code	Value	Description
IosServiceAPI.OK	0	Request processed and successfully executed.
IosServiceAPI.FAIL	1	Request aborted because of an error. If a response string is returned (it contains the error message.
IosServiceAPI.FILE	2	Request processed successfully. If a response string is returned, it contains the file name and path, and is written to a file.

Java Example

In the following example, the show run command is passed in an IosapiMessage object via methods exec( ) and config( ). Note that in this example, config() fails because show run is not a valid configuration command.

import com.cisco.aesop.apphosting.iosapi.*;

public static void main (String[] args){

	int status = 0;

	IosServiceAPI iosapi = IosapiFactory.getIosApi("commonservice");

	IosapiMessage msg = new IosapiMessage();

	msg.setRequest("show run");

	status = iosapi.exec(msg);

	status = iosapi.config(msg);

}

C/C++

•C/C++ Signatures

•C/C++ Example

C/C++ Signatures

•Class and Methods

•IosServiceAPI_t

Class and Methods

typedef struct IosapiMessage_t {

	char   *request; 

	char   *response;

	int     size;

} IosapiMessage_t;

---

Note It is the calling program's responsibility to allocate or free up the memory required to accommodate the response from Cisco IOS software for C programs.

---

IosServiceAPI_t

typedef struct IosServiceAPI_t {

	apiMethod    exec;

	apiMethod    config;

} IosServiceAPI_t;

Table 13 C/C++ IosServiceAPI _t Methods

Method
extern int getIosApi(const char *serviceName, IosServiceAPI_t* iosapi).
int config(IosapiMessage msg).
int exec (IosapiMessage msg).

Table 14 shows returned integer values; for example, from calls to the exec( ).

Table 14 C/C++ IOS CLI API Return Status Codes

Status Code (C/C++)	Value	Description
IOSAPI_OK	0	Request processed and successfully executed.
IOSAPI_FAIL	1	Request aborted because of an error. If a response string is returned (Java/C), it contains the error message.
IOSAPI_FILE	2	Request processed successfully. If a response string is returned (Java/C), it contains the file name and path, and is written to a file.

IosapiMessage_t

Table 15 C/C++ IosapiMessage_t Methods 

Method	Description
request	CLI request; for example, "show run".
response	Memory allocated for the response. The C/C++ code must free the allocated space after the code has run.
size	Set to zero if the IOS CLI API allocates memory, or set to non-zero if C/C++ code allocates memory.

C/C++ Example

#include "iosapi.h"

int main(int argc, char** argv){

	char buf[] = "show run";

	IosServiceAPI_t iosapi;

	IosapiMessage_t msg;

	msg.size = 0;

	msg.response = NULL; 

	msg.request = buf; 

	getIosApi("CommonService", &iosapi);

	retcode  = iosapi.exec(&msg);

	retcode  = iosapi.config(&msg);

	return retcode;

}

Python

•Python Signatures

•Python Example

Python Signatures

•Iosapi

Iosapi

Table 16 Python Iosapi Methods

Method
def Config(self, request).
def Exec(self, request).

Table 17 shows returned integer values; for example, from calls to Exec( ).

Table 17 Python IOS CLI API Return Status Codes

Value	Description
0	Request processed and successfully executed.
1	Request aborted because of an error.
2	Request processed successfully. If a response string is returned, it contains the file name and path, written to a file.

Python Example

import Iosapi

import IosapiFactory

type = "CommonService"

request = "show run"

val, iosapi = IosapiFactory.getIosApi(type)

val, response = iosapi.Exec(request)

val, response = iosapi.Config(request)

Perl

•Perl Signatures

•Perl Example

Perl Signatures

•Iosapi

Iosapi

Table 18 Perl Iosapi Methods

Method
sub exec(request).
sub config(request).

Table 19 shows returned integer values; for example, from calls to Exec( ).

Table 19 Perl IOS CLI API Return Status Codes

Value	Description
0	Request processed and successfully executed.
1	Request aborted because of an error.
2	Request processed successfully. If a response string is returned, the response consists of the file name and path, which is written to a file.

The default size of the response is 2048 bytes.

Perl Example

use Iosapi::Iosapi;

my $request = "show run";

my $type = "CommonService";

my $val;

my $response;

$iosapi = Iosapi::Iosapi->new($type);

($val, $response) = $iosapi->exec($request);

($val, $response) = $iosapi->config($request);

Bash

•Bash Signatures

•Bash Examples

Bash Signatures

For Bash, commands can be passed as a command list or in a file.

iosapi --mode [config|exec] cmdlist

iosapi --mode [config|exec] --file filename

mode: specifies whether command is an exec or config mode command

cmdlist:

•config mode: string containing one command

•exec mode: string containing multiple commands separated by semi-colons

filename: full path of the file containing list of commands

Bash Examples

exec command

bash-3.2# iosapi --mode exec "show clock"

*03:01:26.256 UTC Thu Oct 29 2009bash-3.2#

exec command (unsuccessful as it is not a "show" or "copy" command)

bash-3.2# iosapi --mode exec "invalid command"

ERROR: Unsupported operationbash-3.2#

exec command (unsuccessful as the command is not a valid show command)

bash-3.2# iosapi --mode exec "show abc"

ERROR: invalid valuebash-3.2#

config command

bash-3.2# iosapi --mode config "username myuser password 0 abc"

OKbash-3.2# 

config command using cmdlist

bash-3.2# iosapi --mode config "username abc password abc; no username abc"

OKbash-3.2#

config command using filename

bash-3.2# iosapi --mode config --file /tmp/cmd

OKbash-3.2# 

config command (unsuccessful as the config command has invalid syntax)

bash-3.2# iosapi --mode config "usr myuser pword 0 abc"

ERROR: operation failedbash-3.2#

CLI Commands for Viewing and Clearing IOS CLI API Records

The following three commands can be used to view or clear the records of past IOS CLI API commands.

•show history iosapi—(config or exec mode) views up to 100 of the latest records of issued iosapi commands for a single virtual instance (up to 70 config mode commands and 30 exec mode commands)

•clear history iosapi —clear a specific number of records

•show log name messages.log—(EXEC mode) view the audit history

The following procedure shows commands for viewing or clearing records of past IOS CLI API commands.

SUMMARY STEPS

1. app-service application-name

2. show history iosapi [num ]

3. show history iosapi [exec | config ] [num ]

4. clear history iosapi [num ]

5. clear history iosapi [exec | config ] [num]

6. exit

7. show log name messages.log | include "iosapi audit"

DETAILED STEPS

	Command or Action	Purpose
Step 1	app-service application-name	Enters application service EXEC mode.
Step 2	show history iosapi [num]	Displays up to one hundred records for configuration and EXEC modes. num—Number of records to be displayed.
Step 3	show history iosapi [exec|config ][num ]	Displays up to one hundred of the latest records for either of the following two specified modes: exec—EXEC mode config—Configuration mode num—Number of records to be displayed.
Step 4	clear history iosapi [num]	Clears records for configuration and EXEC modes. Up to 100 records are cleared if num is not specified. num—Number of records to be cleared. Default 100.
Step 5	clear history iosapi [exec|config][num]	Clears the number of specified records for the specific mode. exec—EXEC mode config—Configuration mode num—Number of records to be cleared.
Step 6	exit	Exits application service EXEC mode.
Step 7	show log name messages.log | include "iosapi audit" SE-Module> show log name messages.log|incude "iosapi audit"	Displays audit history in Cisco AXP EXEC mode.