CLI Callback APIs and Macros



 

Overview

 

CLI Callback APIs are provided as hooks to the user / customer where they can have their own code instrumentation and change the value of certain parameters. Some of such Callback API's provided in CLI Agent are listed below

 

Callback for Received CLI Message

 

RcvdCLIMsgInfo() function defined in submain.c file present under "<project-name>/agent/stubs/" directory can be used by the developer to take any action on the CLI message that was received in the CLI Agent

 

void RcvdCLIMsgInfo(void *incmd,INT32 sesID)

 

Here,

 

incmd is the reference to input message

sesID is the reference to the Session ID

 

This function is called by default from CLIEngineForString() function in cliengine.c file, once the command is dequeued from the Receive Queue and after parsing the CLI command but before calling the corresponding action function so that the users can take / perform any modification if required.

 

Callback for Response CLI Message  

 

Similar to callback for receive CLI message, the ResponseCLIMsgInfo() function defined in the submain.c file present under "<project-name>/agent/stubs/" directory can be used to modify the response output formed by the CLI Agent and send it to the client.

 

void ResponseCLIMsgInfo(CLIMessage *resMessPtr)

 

Here,

 

resMessPtr is the reference to the response message formed by the CLI Agent to send back to the client

 

User can instrument in this function such a way that the output response content can be changed according from its original content. This function is called after dequeuing the response message to the TxQ and before sending the message to the appropriate channel interface

 

 

Connection Close

 

If the user wants to perform any tasks / operations while closing the session with the CLI agent, then ConnectionClose() function defined in submain.c file present under "<project-name>/agent/stubs/" directory can be used.

 

 

CHAR ConnectionClose(void *clientSock, INT32 sockType, INT32 sessionID, CHAR *tpName)

 

Here,

clientSock is the reference to the client sock pointer.

sockType refers the socket Type

sessionID has the client session identifier

tpName has the transport interface name (like TCP or Telnet)

 

This function is called by default from CloseTelnetConnection() function in telnettp.c file, from CloseTcpConnection() function in tcptp.c file, from  CloseCraftInterface() function in craftifc.c file and also from CloseSerialInterface() in serial.c file.
All these files are present under "<project-name>/agent/source/system/src" directory and will be available based on the transport interface option enabled in Agent Compiler Project Settings before the stub code generation.  

 

 

Callback for creating CLI Security Log Records

 

By default, the CLI agent will read the security log information from a flat text file. This is done only when the "Text File Stroage for API" feature has been enabled in Agent Compiler tool -> Project Settings UI and the macro "AGENT_FILE_TO_VECTOR" has been defined in the config.h file present under "<project-name>/agent/stubs/" directory.

Suppose, if the target operating system doesn't have the support for the creating / reading text files, then using the CreateCLISecurityLogRecords() available in submain.c file, the user can read the data from his / her external storage device.

 

 

void CreateCLISecurityLogRecords(void)

 

User can instrument his code to read the security log records stored either in his database or from some other storage device and populate it in the CreateAndAddCLISecurityRecord() function available in cliseculog.c present under "<project-name>/agent/source/protocols/cli/src/security" directory. 

 

 

Callback for Updating CLI Security Log Records

 

By default, the CLI agent will write the security log information into a flat text file. This is done only when the "Text File Stroage for API" feature has been enabled in Agent Compiler tool -> Project Settings UI and the macro "AGENT_FILE_TO_VECTOR" has been defined in the config.h file present under "<project-name>/agent/stubs/" directory.

Suppose, if the target operating system doesn't have the support for the creating / reading text files, then using the UpdateCLISecurityLogRecords() available in submain.c file, the user can store the data in his / her external storage device.

 

 

void UpdateCLISecurityLogRecords(void)

 

User can instrument his code to write the security log records stored either in his database or from some other storage device with the data obtained from CLI Security log record.

 

Configuring screen scroll size

 

CLI_SCROLL_SIZE macro can be used for configuring the number of lines of output message needs to be displayed in the client screen. While displaying the output of a message once the number of lines has been reached, automatically the display will go to paging mode where you can use Page-Up / Page-Down key's, Up / Down arrow key's can be used for traversing through the command output.

This macro will be defined by default in the config.h file present under the "<project-name>/agent/source/system/include/" directory

 

 

#define CLI_SCROLL_SIZE 25

 

 

Configuring Maximum Scroll size for MAN command

 

When viewing the manual page of the CLI commands, for some of the commands the manual page will be more than one screen / has several page information. This makes difficult for the user to read the manual of a command. To avoid this WebNMS CLI Agent provides a macro for configuring the number of lines / rows to be shown per screen.

The macro named "CLI_HELP_SCROLL_SIZE" has to be defined in the config.h file present under the "<project-name>/agent/source/system/include/" directory along with the number of lines per screen

 

 

#define CLI_HELP_SCROLL_SIZE 25

 

This will set the screen size to 25 lines per page and to access a next page, the user can press SPACE BAR key.

To quit from the manual page. press the letter "q" .  

 

Configuring Help scroll prompt

 

CLI_HELP_PROMPT macro in config.h file present under the "<project-name>/agent/source/system/include/" directory can be used for configuring the help prompt appears when the manual pages of a command goes more than one screen or the size specified in the CLI_HELP_SCROLL_SIZE macro. By default, it will be displayed as colon ":" .

 

 

#define CLI_HELP_PROMPT :

 

 

Configuring Maximum invalid login attempts

 

For restricting the number of invalid login attempts, CLI_MAX_INVAL_LOGIN macro can be used. This helps This feature will be available by default and has been defined in the config.h macro file present under the "<project-name>/agent/source/system/include/" directory. Number of maximum invalid attempts can be specified in the macro CLI_MAX_INVAL_LOGIN_LIMIT in the config.h file. Using this feature, the user can restrict the number of invalid login attempts (such as illegal user id or password) and the agent will close the corresponding session automatically thus avoiding the intrusion attempts made continuously to the agent.

 

/* To support the maximum invalid login attempts */
#define CLI_MAX_INVAL_LOGIN

 

/* The macro to specify the maximum number of invalid login attempts */

#define CLI_MAX_INVAL_LOGIN_LIMIT 3

 

 

By default, the value of this macro will be 3. Once a user tries to connect to the agent with invalid user name / password for 3 times continuously, after which the CLI agent will close the session. 

 

Maximum Vector size for Receive Queue

 

User can configure the size or number of entries for the receive queue by using the specifying a value to the macro CLI_MAX_VECTOR_SIZE.

 

This macro has to be defined in the config.h file present under the "<project-name>/agent/source/system/include/" directory and size check has been done in CheckCLIMaxVectorySize() function of cliengine.c file present under the "<project-name>/agent/source/protocols/cli/src/" directory

 

CHAR CheckCLIMaxVectorSize(Vector *vectName, INT32 sessionID)

 

Once this macro has been defined in the config.h file, for each input message the CLI agent will check the size of the receive queue (RxQ) and whether the input message can be queued. If  its not possible to queue, then the agent will send failure.

 

 



Copyright © 2012, ZOHO Corp. All Rights Reserved.