Perl Scripts

This section describes the details of using Perl scripts within Adaptive CLI. See Using Perl in Adaptive CLI for more about why to use Perl.

The Perl output goes to the selected target device. Typically, this means creating lines like the following:

println(“show $param”);

or

print(“show $param\n”);

You must specify parameters within the script (like $param) in the screen described in Attributes. Unlike its internal scripts, Adaptive CLI does not automatically create attributes. You must also manually configure created attributes to be Mandatory, or Optional in that screen.

A few things to remember when using Perl:

• The normal output of your Perl scripts (to stdout) are the commands sent to a device by this application.

• If your script produces an error message (to stderr), the job fails with that message and all script outputs are ignored. You can validate a script before sending any command to the device by using die(...) and warn(...) functions in Perl to produce error messages to stderr. Such messages trigger the script’s failure.

• For such scripts to operate correctly, you must have Perl installed on the directory path for all Open Manage Network Manager servers.

• Perl does not come with Open Manage Network Manager and must be installed on the server system independently for it to work with Adaptive CLI.

• You can install your version of Perl and set the PATH environment variable accordingly so that one can run perl -v from the command line (where the Open Manage Network Manager server is to be started). Adaptive CLI invokes that same perl command.

If for some reason Adaptive CLI, fails to invoke the default perl command, it reads the setting of activeconfig.perl.exe=... inside owareapps/activeconfig/lib/ac.properties, and uses that alternative command.

Note that the default activeconfig.perl.prefix= setting in ac.properties is prepended to every Perl script. It basically forces the script to use strict mode and provides a convenient println method for the user. Knowledgeable Perl users can change this default behavior setting but should be careful about it. Remember, best practice is to override properties as described in Overriding Properties.

• The standard output (using println) of the Adaptive CLI Perl script represents the command set that is to be sent to the device. For convenience, a println subroutine is embedded with the script.

• Adaptive CLI with Perl scripts must contain valid Perl under the “strict” pragma (use strict;). If you import or migrate from a previous version a Perl script that does not pass this “strict” criterion, you must rewrite it for “strict” compliance before it can be successfully edited or copied.

When you import a Perl Adaptive CLI that doesn't pass strict, you can execute it without problems. However, you cannot edit it at all, unless you first edit it to pass strict (or it won't even let you save the changes).

Create Adaptive CLI Examples

The following describes the basics of creating and using Adaptive CLIs.

Example 1 - Existing Show Run uses an existing, seeded Adaptive CLI to show protocols.

Example 2 - New Adaptive CLI describes making and using a new Adaptive CLI.

Example 3 - Adaptive CLI with Reboot shows you how to make an Adaptive CLI that requires rebooting the target device(s).

Example 4 - Adaptive CLI To Extract Upload / Download Speeds demonstrates Adaptive CLI that extracts information from the target device, then displays the results on a dashboard.

Example 5: Monitor Text Values demonstrates using and Adaptive CLI configured to monitor attributes with strings that indicate their status.

Some devices do not respond to commands unless they are in the correct state. For example, some Dell devices must not be in “Simple” mode to respond to Adaptive CLIs. Take account of this as you create Adaptive CLIs.

Example 1 - Existing Show Run

1. Adaptive CLI Manager has pre-seeded tasks and diagnostic commands based upon the drivers you have installed. For example: the Cisco 'show protocols' command. Right-click and Select Edit to view and / or alter this Adaptive CLI.

2. Click the Edit icon next to the Cisco script. The Scripts tab in this editor appears above, displaying the show protocols command to be sent target devices. Notice (in the upper right corner) that this Adaptive CLI filters so it applies to all Cisco devices excluding PIX.

3. Close the editor(s), and select this Adaptive CLI.

4. Right click to Execute, and select the target equipment for this run in the next screen. The screen that appears is a standard Open Manage Network Manager equipment selector. The Adaptive CLI is valid only on devices that pass the Target Filter mentioned in step 2, but the selection here narrows the target devices for the Adaptive CLI.

5. An Audit trail screen tracks the execution progress

6. Select the Adaptive CLI you ran in the Expanded Portal, and right-click the execution run that appears in the Execution History snap panel at the bottom of the screen.

7. Right-click and select Execution Details.

View latest results classified by the device you select on the left. View latest results by right-clicking in the Execution History snap-in of the expanded Action portlet. You can use the Find search box to find matches to strings within the results.Click Go to see the next match.

8. You can also look in the Sent Commands tab to see what actually went to the device.

Example 2 - New Adaptive CLI

1. Create a new Adaptive CLI. Right-click and select New.

2. Name this (for example “Test ACLI”)

3. In the Attributes panel, create string attributes named required and optional after creating a new Parameter Schema (for example “test123”).

4. In the Script panel define the Attribute Delimiter (< >) and Optional Attributes Delimiter ([ ]) and enter the following three scripts:

show run

show <required>

show [optional]

Notice that the created attributes appear in the panel on the right of this screen.

5. Select the attribute “required,” then click the Required icon (the green circle) in the lower right corner to of this screen to associate this icon with the Required attribute. Similarly, associate the Optional icon with the attribute “optional.”

Notice that you can double-click the attributes listed in the panel on the right, and they appear in the script editor at the cursor.

6. Save this Adaptive CLI

7. Execute it with action > Execute.

8. Notice that the attributes entered now are visible as inputs.

When you enter values for these, they accompany the show run sent to the target devices. Notice that you must enter the required variable, or execution fails.

9. Select a target.

10. Click Execute. The show run, and any other required / optional run commands’ results appear. These are searchable with the results screen.

Example 3 - Adaptive CLI with Reboot

The following describes how to set up multi-line ACLI with error / success tracking for a command sequence that requires reboot.

1. Create an example configure Adaptive CLI command (here quickThenReboot).

2. Separate commands into parts. First issue the command (here show run), then issue the reboot command with a parameter that allows a prompt return before actual reboot (a delay, for instance). If the first command fails the ACLI doesn't continue, so that makes using the reboot command second the solution.

In our example:

show run

reboot 1 minute

3. Open Manage Network Manager assumes commands are successful if a prompt appears without an error return. Default error tracking for most drivers provides all the error pattern matching you might need (testing the Adaptive CLI lets you know whether the device is addressed by a driver in “most”).

Use specific error pattern matching for cases where the driver does not detect the typical errors by default. , erroneous output appears if the error occurs on the reboot command.

4. When reboot is successful with a proper command sequence, the job screen displays the successful execution.

5. Continue Patterns -- The following Continue Patterns section is an addition to the above example. It looks for the Proceed prompt so the Adaptive CLI can issue a new line to force the reboot. But the shutdown command follows the next prompt, so the shutdown command must be in another continue pattern to force the last line before a pause in output to be the router's prompt. The patterns are .*Proceed.* and .*SHUTDOWN in.* allowing any characters before and after the keywords to match.

Alternatively, this example could have a third command after reboot to force a new router prompt, but managing this problem with the continuation set seemed more straightforward.

Example 4 - Adaptive CLI To Extract Upload / Download Speeds

The following describes an example Adaptive CLI configured to extract upload and download ADSL speeds from a Cisco Router. To create this example, follow these steps:

1. Right-click to create a new Adaptive CLI in the Actions portlet.

2. Name it and configure the Adaptive CLI in the General screen. Since these are generic settings described elsewhere, the details do not appear here.

Create attributes to extract. In this case, we configure Upload Speed, and Download Speed as integer attributes, with a name, description, and nothing else.Notice, however, that you could configure validation for extracted attributes if you liked in this screen.

3. Create a new schema for these attributes. Schemas are helpful if you are creating several Adaptive CLIs (create, destroy, update, and so on) with the same set of attributes. With schemas, you are sure the attributes are configured exactly the same.

4. Save the configured attributes, click the Script panel

5. Enter the script. This extracts upload and download speeds from a Cisco device based on the output from this command (the script’s contents):

show dsl int atm0 | inc Speed

This command shows dsl, grepping (inc) for the unique line beginning with Speed. The line for which this script searches looks like this:

Speed (kbps): 544 0 256 0

The attributes configured previously appear beside the script panel, but are not part of the script, even though that possibility might be useful for another Adaptive CLI. The current attributes are for extraction from the script results. The filter at the top of this panel can limit the devices scanned by the Adaptive CLI to extract data. If you have a specific device or group of devices against which you plan to test this script, it would be a time saver to create the filter first.

6. Click the Value Extractions panel within the Scripts screen, and configure an extraction regular expression for each of the two values.

Click the green plus to add the second attribute.

With the pick lists, select an attribute, and that you want to extract (that is, within which you plan to store a value), then enter the regular expression to match its target value. Here are those attribute / regular expression pairs:

• Download Speed (the first integer in the output)

[Speed (kbps):\s+]([0-9]+).

• Upload Speed (the third integer in the output)

[Speed (kbps):\s+][0-9]+\s+[0-9]+\s+([0-9]+).

You can use free regular expression testers to debug these expressions. See Regular Expression Testing.

7. Apply the edits you have made to script and extractive regular expressions, then Save the Adaptive CLI.

8. Right-click the Adaptive CLI and Execute it.

9. Select the target device(s).

10. Confirm the execution. The screen that appears before you click Execute again would have fields if you had a script with input parameters.

11. The Results panel appears to advise whether the script ran successfully, displaying its output.

12. Click Job Viewer, and arrange that panel so it displays informational messages by clicking the icon next to the date / time display. Check the checkbox next to the blue informational circle, and click the Refresh icon to the far left.

13. Click the last informational message (Set attribute extraction results...) and the extracted attribute values appear in the data panel at the bottom of the screen.

Example 5: Monitor Text Values

Create an Adaptive CLI with the following to monitor layer 1 and layer 2 status:

• integer attributes: layer1status, layer2status

• Script to produce the output: show isdn status

Here is the output to match:

Layer 1 Status:

ACTIVE

Layer 2 Status:

TEI = 0, Ces = 1, SAPI = 0, State = MULTIPLE_FRAME_ESTABLISHED

• Attribute Extraction Pattern:

layer1status / Match / (Layer 1 Status:\n\s+ACTIVE)

• For layer2status, the regular expression is like

(Layer 2 Status:\n\s+TEI = \d, Ces = \d, SAPI = \d, State = MULTIPLE_FRAME_ESTABLISHED)

Create a monitor to display the result of regularly running this Adaptive CLI on selected targets, and display its result in a dashboard.

Don’t forget to enable the attributes in the monitor!