24.0 TL1 Agent Tutorial

 

1.0 Introduction

2.0 Objective of the Tutorial

3.0 Application Notes

4.0 Defining the TCS File

4.1 Creating New TCS File

4.2 Creating Input Message "GET-SYSTEM"

4.3 Creating Input Message "GET-SYSTEN-JAVAINFO"

4.4 Creating Input Message "GET-SYSTEM-MEM"

4.5 Creating Autonomous Message "ALM-FREEMEM"

5.0 Generating Code for the TCS

6.0 Compiling the Generated Code

7.0 Starting the Agent

8.0 Testing the Agent

9.0 Instrumenting the Agent

10.0 Testing the Instrumented Agent

 

1.0 Introduction

 

Transactional Language 1 (TL1), is the dominant network management protocol used for managing Telecommunication Networks. Using the tools packaged with WebNMS Agent Toolkit, it is possible to develop 'Standalone TL1 Agents' and 'Multi-Protocol agents with support to TL1 adaptors'. Multi-Protocol agents developed provide common instrumentation for all protocol adaptors.

 

2.0 Objective of the Tutorial

 

This tutorial concentrates on the development of a Standalone TL1 Agent. It explains the steps involved in developing the TL1 Agent. After going through the steps given in the sections followed you will be able to,

3.0 Application Notes

 

Transaction Language 1 (TL1) is defined for OS/NE (machine-to-machine) interfaces. TL1 corresponds to the User System Language (USL), which is the language for human-to-machine interactions. Operations functions such as surveillance, memory administration, need to be performed between an OS and a NE. TL1 Agents are widely used to manage NE's (Network Elements) residing in a device.

 

Let us take the following scenario for our tutorial.

 

Say, you want to get some details from a system.  You may need to get the memory related information and java related information like "Java_Home" etc., from the system. These details will be queried from the OS (Manager) to the NE. (system) The agent, upon receiving the request, will get the appropriate details from the system and send those details to the OS, as a response. The Manager can also query for all the equipments for which the agent has to send the details of all the equipments in a single response.

 

Basically, you have to do a "GET" on the system. As you must be aware, going through the basics of TL1, "GET"  is a verb defined in the Command Code of the Input message in the TCS file.

 

In addition to getting the  system details, you may also want to send an alarm to the OS, when the free memory is being viewed. Autonomous messages (similar to trap in SNMP) can be sent from the agent to the manager when any change occurs in the NE or when anything has to be reported to the OS.

 

Let us see how the response and autonomous messages are sent and the target of developing a tl1 agent is achieved in the following sections.

 

4.0 Defining the TCS File

 

TL1 Command Set file contains input message ,output message, and autonomous message definitions, which are to be implemented in the agent for managing an NE. The input message and the autonomous message definitions  are  strored in XML format in TCS file.

 

Defining a TL1 Command Set (TCS) file is the first step toward building a TL1 Agent. The TCS is the source for TL1Compiler for generating code for the TL1 Agent for instrumentation, and also the TCS file  will be used in TL1Browser to query  the agent. TCS file can be created using the TL1 MessageBuilder provided with the toolkit. TL1 Message builder helps to define input message, output message,  and autonomous message as per GR831 specification.

 

In this section, you will learn how to create a TCS file. The TCS file contains the following Commands

  1. GET-SYSTEM

  2. GET-SYSTEM-JAVAINFO

  3. GET-SYSTEM-MEM

  4. ALM-FREEMEM

The first three commands are Input Message type commands and the fourth command is an Autonomous Message  type command.

 

4.1 Creating a New TCS File in TL1 Message Builder

 

Follow the steps given below to create a new file in the TL1 MessageBuilder.

Now, you will see the Parent Node (systeminfo) added under the TL1 Tree in the left frame.

 

Now, you can start adding the commands for the TCS file as explained in the following sections.

 

4.2 Creating Input Message "GET-SYSTEM"

 

The syntax of the command is as follows:

 

Syntax: GET-SYSTEM:<TID>:<AID>:<CTag>:<General Block>:<MPB>;

 

Refer to TL1 basics for details about the  input message syntax.

 

Here GET-SYSTEM is the command code. GET is the Verb and SYSTEM is the Modifier1 in the command code. The following sections will teach you to add the above command and its parameters in the  TCS  file using the TL1 MessageBuilder.

 

Adding the Verb "GET"

 

Verb identifies the action to be taken at the NE on receiving a TL-1 message from an OS. To add the Verb "GET" for the input message, follow the steps given below.

    1. Select the Parent Node (systeminfo) under the TL1 Tree in the left frame of the tool.

    2. Right-click and choose the Add Verb Option.

    3. The wizard interface for verb will be opened on the right frame. Enter the following details:

    4. Message Type : Input Message

    5. Verb : In this example, the action to be taken by the input command is getting the details from the specified system. Hence we can give the verb name as "GET".

    6. Command Code : Select NO in the Command Code option. In this command, GET-SYSTEM is the command code; hence, Command Code for the verb GET alone is selected as NO.

After entering the above details, click the OK button. Now the Verb will be added successfully to the TCS file tree.

      Note: For this Command,  we shall define AID, MPB, Response Block, and Description in Modifier1. They need to be defined only when Command Code option is selected as Yes.

Adding Modifier1 "SYSTEM"

 

The first Modifier identifies where the action is to be applied in the NE. To add the Modifier1 "SYSTEM" for the input message, follow the steps given below. SYSTEM is the device from which the system details are to be obtained and sent to the TL1 Manager.

Adding AID, MPB, and Response Block for the input message are dealt with in the next three sections.

 

Adding Staging Parameter Block

 

Access Identifier Block(AID): AID is used  to  uniquely identify  the entity, within the target NE, to be acted upon by the input message to the NE.

 

Follow the steps given below to add the parameter "System1" in the AID Block.

    1. Click the "...." button next to the AID Block.

    2. Enter the first parameter Name of the Response Block as "system1".

    3. Choose parameter Type as "String".

    4. Choose Separator as "  ".

    5. After entering the above details, click the "Add" button. You will find the new parameter added to the AID Block.

    6. Click the OK button to finish adding the AID block.

Adding Response Block

 

When GET-SYSTEM command is sent to the TL1 Agent, the Agent must respond with the system details for the device given in the AID block. Hence, the response block has to be defined. The response block has the following information.

USER NAME Following are the steps involved in adding the Response Block

    1. Click the "..." button next to the Response block.

    2. Choose response type as Quote and click on Add Block.

    3. Enter the first name parameter Name of the Response Block as "OS NAME".

    4. Choose paramter Type as "String".

    5. Select EQ VAL as "True". If true is selected, the response will be displayed in Name=Value format.

    6. Choose Delimiter as "," . This will enable more parameters to be added to the Response Block.

    7. Click the "Add" button.

    8. Enter the next parameter of the Response Block as "OS_VERSION" as follow the steps 4 to 7.

You will find the new parameters with response type as quote added to the Response Block.

 

The other parameters with different response types can also be added easily to the Response Block in a similar manner.

 

After entering all the above explained details for Verb and Modifier1,  the OK button. The new command code will be created successfully in the TCS file.

 

4.3 Creating Input Message "GET-SYSTEM-JAVAINFO"

 

The syntax of the command is as follows:

 

Syntax: GET-SYSTEM-JAVAINFO:<TID>:<AID>:<CTag>:<GB>:<MPB>;

 

Refer to TL1 basics for details about the  input message syntax.

 

Here GET-SYSTEM-JAVAINFO is the command code. GET is the Verb, SYSTEM is the Modifier1, and JAVAINFO is the Modifier2 in the command code. The following sections will teach you to add the above command and its parameters in the  TCS  file using the TL1 MessageBuilder.

 

Adding the Verb "GET"

 

The verb GET and its details are already added in the previous section (section 4.2.1). 

 

Adding Modifier1 "SYSTEM"

 

The Modifier "SYSTEM" and its details are already added in the previous section (section 4.2.2). 

 

Adding Modifier2 "JAVAINFO"

 

The second modifier may be used to further define the identity of the object upon which the action is to be taken. Modifier JAVAINFO is the actual information that is to be retrieved from the system. To add the Modifier2 "JAVAINFO" for the input message, follow the steps given below.

    1. Right-click on the Modifier1 "SYSTEM" in the TCS file tree for which Modifier2 has to be added.

    2. Choose "Add Modifier2" from the pop-up menu. The wizard interface for Modifier1 opens in the right frame.

    3. Enter the following details:

    4. Modifier : Because we will be retrieving the Java related information from the system specified, let us name the Modifier2 as "JAVAINFO".

    5. Command Code : Select YES in the Command Code option.

    6. Inherit Option : Select NO as the Inherit option, because there are no details from the Modifier1 that is needed to be inherited by the Modifier2.

    7. Description : Add the required description in this block. For example, add the below text in the block "This command returns information about JAVA and JVM:.

Adding AID, MPB, and  Response Block for the input message are dealt with in the next three sections.

 

Adding Staging Parameter Block

 

Access Identifier Block(AID): AID is used  to  uniquely identify the entity, within the target NE, to be acted upon by the input message to the NE.

 

Follow the steps given below to add the parameter "System1" in the AID Block.

Adding Response Block

 

When GET-SYSTEM-JAVAINFO command is sent to the TL1 Agent, the Agent must respond with the system details for the device given in the AID block. Hence, the response block has to be defined. The response block has the following information.

Following are the steps involved in adding the Response Block

    1. Click the "..." button next to the Response block.

    2. Choose response type as UNQUOTE and click on Add Block.

    3. Enter the first parameter Name of the Response Block as "JAVA_HOME".

    4. Choose parameter Type as "String".

    5. Select EQ_VAL as "True". If true is selected, the response will be displayed in Name=Value format.

    6. Choose Delimiter as ",". This will enable more parameters to be added to the Response Block.

    7. Click the "Add" button.

    8. Enter the next parameter of the Response Block as "JVM_NAME" and follow the steps 4 to 7.

You will find the new parameters with response type as unquote added to the Response Block. The other parameters can also be added to the Response Block in a similar manner.

 

After entering all the above explained details for the Verb, Modifier1, and Modifier2, click the OK button. The new command code will be created successfully in the TCS file.

 

4.4 Creating Input Message "GET-SYSTEM-MEM"

 

The syntax of the command is as follows:

 

Syntax: GET-SYSTEM-MEM:<TID>:<MEMORY>:<CTag>:<GB>:<MPB>;

 

Refer to TL1 basics for details about the  input message syntax.

 

Here GET-SYSTEM-MEM is the command code. GET is the Verb, SYSTEM is the Modifier1, and MEM is the Modifier2 in the command code. The following sections will teach you to add the above command and its parameters in the  TCS  file using the TL1 MessageBuilder.

 

Adding the Verb "GET"

 

The verb GET and its details are already added in the previous section (section 4.2.1).

 

Adding Modifier1 "SYSTEM"

 

The Modifier "SYSTEM" and its details are already added in the previous section (section 4.2.2).

 

Adding Modifier2 "MEM"

 

The second modifier may be used to further define the identity of the object upon which the action is to be taken. Modifier MEM is the actual memory detail that is to be retrieved from the system. To add the Modifier2 quot;JAVAINFO" for the input message, follow the steps given below.

Adding AID, MPB, and  Response Block   for the input message are dealt with in the next three sections.

 

Adding Staging Parameter Block

 

Access Identifier Block(AID): AID is used  to  uniquely identify  the entity, within the target NE, to be acted upon by the input message to the NE. In this tutorial the memory to be retrieved can be Free Memory or Total Memory. Hence the AID values can be Free and Total

 

Follow the steps given below to add the parameter "MEMORY " in the AID Block.

Adding Response Block

 

When GET-SYSTEM-MEMORY command is sent to the TL1 Agent, the Agent must respond with the memory in bytes for the memory device given in the AID block. Hence, the response block has to be defined. The response block has the following information.

Following are the steps involved in adding the Response Block.

You will find the new parameters with response type as unquote added to the Response Block.

 

After entering all the above explained details for the Verb, Modifier1, and Modifier2, click the OK button. The new command code will be created successfully in the TCS file.

 

4.5 Creating the Autonomous Message "ALM-FREEMEM"

 

This section explains how to add an Autonomous Message to the TCS file. Here an alarm message will be sent by the NE/NS to the Agent, when GET-SYSTEM-MEM command is executed with "Free" as the AID. That is the Agent will send a Autonomous Message when free memory in the system is viewed.

 

Here, ALM-FREEMEM is the command code. ALM is the Verb indicating that an Alarm is being sent, and FREEMEM is the Modifier2 in the command code that stands for free memory. The following sections will teach you to add the above command and its parameters in the TCS  file using the TL1 MessageBuilder.

 

Adding the Verb "ALM"

 

To add the Verb "ALM" for the Autonomous Message, follow the steps given below.

After entering the above details, click the OK button. Now, the Verb will be added successfully to the TCS file tree.

After entering all the above explained details for Verb and Modifier1click the OK button. The new command code will be created successfully in the TCS file.

 

Saving and Viewing the Created TCS File

 

After adding the commands: Input messages and one Autonomous message, save the file using the File>>Save option in the Menu Bar or press CNTRL+S. The TCS file systeminfo.tcs is now created and can be used in the TL1 Compiler for code generation and compilation as explained in the following topics.

 

5.0 Generating Code for the TCS File

 

After creating the TCS file, which is the input for building the TL1 Agent, the next step is generating the code for the TCS file created.

 

Creating a New Project and Loading the TCS.

 

Follow the steps given below to create a new project for a standalone TL1 Agent.

    1. Launch the TL1 Compiler by executing the TL1Compiler.sh/bat file under the <Agent Toolkit Home>/bin directory.

    2. File>>New Project option from the File Menu or using the shortcut key CTRL+SHIFT+N 

    3. Enter the details of the Workspace, Project Name, and the directory of the project in the Project Settings Dialog Box.

    4. Click OK after entering the details.

A new project is now created.

 

Follow the steps given below to load a TCS for the project created above.

The TCS file will be loaded to the TL1 Compiler. You can view the TCS file tree in the TCS View of the Workspace panel.

 

Generating Code 

 

Please follow the steps given below to generate the code for any  loaded TCS. Before following the steps given below, load the systeminfo.tcs  with the default project settings. 

6.0 Compiling the Generated Code

 

After generating the code for the TCS file(s), the next stage in agent development is compiling the source code.  This section shows how to compile the source code without any instrumentation. You can compile your project either from the UI or from the Command prompt as explained in the following sections.

 

Compiling the Code from the TL1 Compiler UI

 

Follow the steps given below to compile the generated code using the TL1 Compiler UI.

Compiling the Code from the Command Line.

 

You can also compile the source from the command prompt. Please follow the steps given below to compile the source files from the command prompt.

    1. Open a command prompt/ terminal.

    2. Go to the <Agent Toolkit Home>/tl1projects/projectname directory.

    3. Execute the following  command
      javac -d agent\bin agent\src\*.java

      The above command will compile all the files under agent/src directory and if the compilation is successful, the compiled class files can be found under <Agent Toolkit Home>/tl1projects/projectname/agent/bin directory. 

      Now all the files have been compiled and the Agent can be started.

7.0 Starting the Agent

 

After successfully compiling the Agent, you can start the Agent either from the TL1 Compiler UI or from the Command prompt as explained in the following sections.

 

Starting from the TL1 Compiler UI

 

You can start and stop the Agent from the TL1 Compiler UI by clicking the Build >> Start Agent andBuild>> Stop Agent option in the menu bar.

 

Starting from the Command Line

 

Follow the steps given below to start and stop the Agent from the command prompt.

    1. Open a command prompt/ terminal.

    2. Go to the <Agent Toolkit Home>/tl1projects/projectname/agent/bin directory where the compiled files are available.

    3. Execute the Run.bat/Run.sh command

      You will find the following details at the end of the execution of the above command
      TL1 Server started on 9099
      Registering Commands...
      Registration Done.

This means that the Agent has been successfully started on port 9099.

 

8.0 Testing the Agent

 

Follow the steps given below to test the Agent created in the previous chapter. It is assumed that a Standalone TL1 Agent created using systeminfo.tcs file is running on port 9099.

  1. Start the TL1 Browser Application using the TL1Browser.bat or TL1Browser.sh file from the <Agent Toolkit Home>/tl1projects/projectname/bin directory. It can also be started from the launcher.

  2. Load the systeminfo.tcs and tl1security.tcs files using the File>>Load option in the menu bar.

  3. Choose Operations>>Connect option in the MenuBar. 

  4. Enter the Host Name and Port Number where the agent is running in the dialog box that appears.

  5. Click OK. Now you will be connected to the Agent.

  6. Authenticate into the TL1 Agent by sending the Input command "ACT-USER::root:1::public;" by choosing Operations>>Send in the menu bar or using the shortcut key CTRL+N.

    The Agent will respond by sending the following Autonomous Message. This means that you have successfully authenticated into the TL1 Agent.

    Autonomous Message Received From :localhost
    <CR>
    <LF><LF>   system 2002-04-11 12:22:25<CR>
    <LF> ** 1 REPT EVT SESSION<CR>
    <LF>   "system:NO"<CR>
    <LF>   /*NOTICE:This is a private computer system. <LF>  Unauthorised access or use may lead to prosecution*/<CR>
    <LF>;

  7. Now expand the TCS tree of systeminfo.tcs file.

  8. Choose the command code GET-SYSTEM-JAVAINFO

  9. Send the message by choosing Operations>>Send in the menu bar or using the shortcut key CTRL+N.

    The Agent will respond with some default dummy values as shown in the response message below. 

    Response Message Received From :localhost
    <CR>
    <LF><LF> rajeshm 2002-06-07 22:13:29<CR>
    <LF>M 3 COMPLD<CR>
    <LF> not_initialized,not_initialized,not_initialized<CR>
    <LF>;

    This means that your Agent works!

9.0 Instrumenting the Agent

 

Instrumentation involves the modification of source codes generated or adding of user codes to the generated code to make the Agent respond with the desired values.

 

Following files are instrumented to make the TL1 Agent respond desirably. Please note that no instrumentation is required in the WebNMSTL1Agent.java file in this example.

  1. GET_SYSTEM.java is instrumented to send the system information like the OS Name, OS version, System Info, and User Name to the manager.

Following code snippet shows the user code required for instrumenting the file.

 

/* Implementation for QUOTED type */

defaultRespValues = new Object[2];

defaultRespValues[0] = System.getProperty("os.name");

>defaultRespValues[1] = System.getProperty("os.version");

 

>/* Implementation for UNQUOTED type */

defaultRespValues = new Object[1];

defaultRespValues[0] = System.getProperty("user.name");

 

/* Implementation for COMMENT */

defaultRespValues = new Object[1];

defaultRespValues[0] = "These information are taken from the machine where agent runs ";

 

The above code snippet shows the instrumentation required in the GET_SYSTEM.java file, for all the response blocks namely, quoted type, unquoted type, and comment  in the response message.

  1. GET_SYSTEM_JAVAINFO.java is instrumented to send the Java related Information like Java Home, JVM Name, User Name, and JVM Info to the manager.

Following code snippet shows the user code required for instrumenting the file.

 

/* Instrumentation */

 

defaultRespValues = new Object[3];

defaultRespValues[0] = System.getProperty("java.home");

defaultRespValues[1] = System.getProperty("java.vm.name");

defaultRespValues[2] = System.getProperty("java.vm.info");

  1. GET_SYSTEM_MEM.java is instrumented to send the amount of free or total memory available, depending on the AID, to the manager.

Following code snippets shows the user code required for instrumenting the file.

 

/** Instrumentation */

 

else{

throw new TL1AgentException("Access id missing ",TL1Errors.IIAC);

}

String memoryToBeViewed = aid.get(0).toString();

if(!(memoryToBeViewed.equalsIgnoreCase("Free")) && !(memoryToBeViewed.equalsIgnoreCase("Total"))){

throw new TL1AgentException("No such object ",TL1Errors.ANSO);

}

 

 

The above instrumentation is done to check for AID that can be passed in the command. The code checks if the AID is Free or Total. If the AIDis not any of the two, it will throw an error "Invalid Access Identifier"

 

The following code snippet shows the instrumentation required for calling the autonomous message ALM-FREEMEM when the free memory is viewed i.e., when Free is passed as the AID in the command GET-SYSTEM-MEM.

 

defaultRespValues = new Object[1];

Runtime rt = Runtime.getRuntime();

if(memoryToBeViewed.equalsIgnoreCase("Total")){

defaultRespValues[0] = new Long(rt.totalMemory());

}

else{

defaultRespValues[0] = new Long(rt.freeMemory());

String alert = "Free memory of the system is beeing viewed";

mainAgent.getALM_FREEMEM().sendAutonomous(alert);

}

  1. ALM_FREEMEM.java is instrumented to send an Autonomous Message to the manager when the Free Memory is viewed. 

Following code snippet shows the instrumentation required in the file

 

The method When public void sendAutonomous(String alert) gets the string autonomous message string from the GET_SYSTEM_MEM.java this string is sent to the manager with the autonomous message.

 

defValues = new Object[1];

defValues[0] = alert;

line = TL1MessageFormatter.createTL1Line

(keys,defValues,delimiters,lineType,nameEqValue);

responseVector.add(line);

 

The instrumented source files are available in the <Agent Toolkit Home>/examples /tl1/ tutorial /agent/src directory. You can either add the above codes in the respective files or overwrite the agent directory under <Your Project> directory with the agent directory under the <Agent Toolkit Home>/examples/tl1/tutorial. 

 

After instrumenting the source files, re-compile the TL1 Agent source and then start the Agent. The Instrumented TL1 Agent will now be started.

 

10.0 Testing the Instrumented Agent

 

After starting the Instrumented Agent, you can test the Agent by following the steps given below.

  1. Start the TL1 Browser Application using the TL1Browser.bat or TL1Browser.sh file from the <Agent Toolkit Home>/bin directory. It can also be started from the launcher.

  2. Load the systeminfo.tcs and tl1security.tcs files using the File>>Load option in the menu bar.

  3. Choose Operations>>Connect option in the MenuBar.

  4. Enter the Host Name (localhost) and Port Number (9099)where the agent is running in the dialog box that appears.

  5. Click OK. Now you will be connected to the Agent.

  6. Authenticate into the TL1 Agent by sending the Input command "ACT-USER::root:1::public;" by choosing Operations>>Send in the menu bar or using the shortcut key CTRL+N.

    The Agent will respond by sending the following Autonomous Message. This means that you have successfully authenticated into the TL1 Agent.

    Autonomous Message Received From :localhost
    <CR>
    <LF><LF>   system 2002-04-11 12:22:25<CR>
    <LF> ** 1 REPT EVT SESSION<CR>
    <LF>   "system:NO"<CR>
    <LF>   /*NOTICE:This is a private computer system. <LF>  Unauthorised access or use may lead to prosecution*/<CR>
    <LF>;

  7. Now expand the TCS tree of systeminfo.tcs file.

  8. Choose the command code GET-SYSTEM-MEM and send the command with free as the AID.

  9. Send the message by choosing Operations>>Send in the menu bar or using the shortcut key CTRL+N.

    The Agent will respond with the response message shown below. 

    Response Message Received From :localhost
    <CR>
    <LF><LF> rajeshm 2002-06-08 14:49:15<CR>
    <LF>M 4 COMPLD<CR>
    <LF> MEMORY_IN_BYTES=1310296<CR>
    <LF>;

    The above response can be seen in the Response Block. 

    Also, since we have instrumented the Agent to send an Autonomous message when free memory is viewed, the Agent will send the following Autonomous Message when the above command is executed.

    Autonomous Message Received From :localhost
    <CR>
    <LF><LF> rajeshm 2002-06-08 14:49:15<CR>
    <LF>*C 2 REPT<CR>
    <LF> /*Free memory of the system is being viewed*/<CR>
    <LF>;

    The above Autonomous Message can be viewed in the Autonomous Message Block.

    The Response Message and the Autonomous Message shown above shows how an Agent can be instrumented to respond with actual values desired by the user.


Copyright © 2009, ZOHO Corp. All Rights Reserved.