3 Using Existing Scripts

This chapter explains how to manage existing driver scripts from within the Oracle Communications IP Service Activator user interface (client). It includes the following:

For details of requirements for running specific pre-defined scripts, see "Pre-defined Scripts".

Importing Scripts

Any pre-defined scripts included with the system are installed in the Service Activator\DriverScripts directory. Before applying them you need to import the scripts you intend to use.

To import a script:

From the Custom tab, click the Driver Scripts folder.

The Custom tab is available within the Global Setup window or any domain management window.

A context menu appears.
Right-click and choose Add Driver Script. The Driver Script dialog box appears, as in Figure 3-1.

Figure 3-1 The Driver Script Dialog Box

Description of "Figure 3-1 The Driver Script Dialog Box"
Click Import. A file selection dialog box appears, listing all available scripts in the DriverScripts directory (.py files). Any Oracle-supplied scripts will appear in this list.
Choose the appropriate script, then click Open. The script is loaded.

The name of the imported script is set to the value of the script_name variable in the Behavior section, if present. Other variables in the Behavior section set details of device and interface roles (on the Role properties page) and scheduling requirements (on the Schedule properties page).

Scripts are not domain-specific. Once imported or created within a domain, a script is available within all domains.

Note:

The order in which scripts are applied to a policy object is dependent on the order in which they are imported into IP Service Activator. Changing the list order of scripts in the client does not have any effect on their order of application. If script application order is critical, you can specify it using the shared data area. For more information, see "Sharing Data Between Scripts".

Viewing and Organizing Scripts

Driver scripts are accessed from the Custom tab, which is available from both the Global Setup window and all domain management windows.

All scripts that have been imported or created within the client appear in the Driver Scripts folder. They can be organized into a structure of folders for administrative purposed.

Creating Driver Script Folders

Within the Driver Scripts folder, you can create a folder hierarchy to organize the driver scripts. You can create multiple levels of folders, and you can drag scripts between folders. You can also set permissions on folders in order to control which users are able to access them.

Figure 3-2 shows an example hierarchy for the Driver Scripts folder.

Figure 3-2 Driver Scripts Folder Hierarchy

Description of "Figure 3-2 Driver Scripts Folder Hierarchy"

To create a driver script folder:

On the Custom tab, right-click on the Driver Scripts folder.

A context menu appears.
Select Add Folder.

The Driver Script dialog box appears.
Provide a name for the folder, and add remarks if necessary. Select the Ownership property page to set permissions on this folder.

Note:

Folders are not ”groups” of driver scripts: it is not possible to apply a folder of scripts to a target

Viewing a Summary of Scripts

To view a summary of the existing scripts:

Click on the Driver Scripts folder.

The existing scripts will be listed in the Details pane, as in Figure 3-3.

Figure 3-3 List of Existing Scripts in the Details Pane

The Details pane provides the following information about each script:

Name: name of the script
State: indicates the current status of the script; values are:
- Inactive: the script has been created, but not yet propagated to the devices
- Active: the script has been propagated to proxy agents, but is not yet configured on a device. A once-only script returns to Active status once it has been run; you can run it again by reapplying it to the device
- Installed: the script has been propagated to proxy agents and has been successfully installed on the designated device
- Failed: the proxy agent experienced a failure trying to install the rule and it has therefore been discarded
- Rejected: the script has been rejected by the device driver (for example, because of a syntax error)
Level: indicates the level within the object hierarchy at which the script is applied (not relevant on this screen)
Driver Type: the driver that will run the script
Applies To: the target that the script applies to; values are Device, Interface, Sub-interface, ATM PVC or Frame Relay PVC.
Device Role: the device role(s) that this script will be applied to.
Interface Role: for Interface, sub-interface, ATM PVC and FR PVC scripts, the interface role(s) that this script will be applied to.
Installed: indicates when this script will be applied relative to other configuration changes; value is either Before config. changes or Following successful config. changes.
Frequency: indicates how often the configuration will be applied. Value is either Once only (that is, on the next commit) or Repeat (on each commit until the script is removed).
Install on restart: indicates if the script is to be run when a device restart is detected; value is either True or False.
Owner: if ownership of the script has been specified, value is the owner's username.
Owner Group: the group to which the owner belongs

Viewing the Entire Text of Scripts

To view the entire text of a specific script:

On the Hierarchy pane, select the desired script.

The following script text appears in the Details pane:

# Title: Netflow Activation Script
Version = '1.0'

# Copyright (c) 1999, 2008, Oracle. All rights reserved.
# Oracle Corporation and/or its affiliates. Other names may be trademarks of
# their respective owners.

#This script enables the export of flow information from the target device and enables flow-catching on the target interface

#begin preamble section

Oracle recommends that you do not edit the script text directly in the details pane, although it is possible.

Note:

The Behavior section of imported scripts is not visible in the Details pane.

Viewing Script Properties

To view more details about a script:

Right-click on the script object.

A context menu appears.
Select Properties.

The Driver Script dialog box appears, as in Figure 3-1, "The Driver Script Dialog Box".

The Driver Script dialog box displays pages with the following information about the script:

Driver Script: Displays identification information, including the first lines of the script.
Role: Identifies the device role and interface role of the script. This information is defined in the Behavior section of the script; if necessary it can be edited on this page.
Schedule: Identifies the scheduling requirements of the script. This information is defined in the Behavior section of the script; if necessary it can be edited on this page.
Preamble: Displays the Preamble section of the script. Variables defined in this section normally have default values, which can be amended if required. Note that these values can be overridden by the context defined for particular objects.
Common: Displays the Common section of the script. For existing scripts you are advised not to change anything on this page.
Install: Displays the Install section of the script. For existing scripts you are advised not to change anything on this page
Remove: Displays the Remove section of the script. For existing scripts you are advised not to change anything on this page.
Ownership: Displays the permissions granted on the driver script. Only the owner of this object or a Super User can amend this page.

Associating Roles with Scripts

Before implementing a script, you need to apply the appropriate device roles, and, if necessary, interface roles, to define the points in the network to which the script applies.

To apply device or interface roles:

Display the Driver Script dialog box for the desired script. See "Viewing Script Properties".
Select the Role page.

Figure 3-4 shows the Role page.

Figure 3-4 The Role Page

The Script Type drop-down menu indicates the target of the script. This is defined as part of the script and should not be changed.
Select one system-defined device role (Core, Access, Gateway or Shadow) and one user-defined device role.
If the script type is Interface, Sub-interface, ATM PVC or Frame Relay PVC, you select one system-defined interface role (Local, Access, Core or Disabled) and one user-defined interface role.

The system-defined Any Role can be used to apply the script to any device or interface, whatever the role.

For more information about roles and how to assign roles to network elements, see IP Service Activator Concepts and IP Service Activator User's Guide.

Setting Variables

The variables required when scripts are run can be defined in two places:

In the Preamble section of the script, displayed on the Preamble page of the Driver Script dialog box. Variables set here apply to all instances of this script.
In the local context for the object(s), defined on the Script Context property page for the object. Variables set here apply to any script run on that object.

Setting Variables in the Preamble Section

Variables normally have suitable default values supplied, but you can overwrite these if necessary with alternative values.

To set variables for a specific script:

Do one of the following:
- Display the Driver Script dialog box for the selected script and select the Preamble page, as shown in Figure 3-5.
  
  Figure 3-5 The Preamble Page
- Display the script in the Details pane
Edit the variables as required.

Note:

Values set for parameters in the local context for an object override any values set for the same parameters in the Preamble section of a script.

Setting Variables in the Local Context for an Object

You can set variables that are specific to a particular object to which scripts can be applied. For additional guidance on managing script context, refer to "Managing Script Context".

To set variables for a specific object:

Select the object (such as device or interface) and display the Properties dialog box. Choose the Script Context page.
Enter the variables in the Local Context field, as shown in Figure 3-6.

Figure 3-6 Script Context Page of Properties Dialog Box

Note:
A maximum of 512 characters can be included in an object's local context definition.

Associating Scripts with Objects

Before a script is implemented, you must associate it with the appropriate network objects. Inheritance rules apply, so for example you can associate an interface script with a VPN and it will be applied to all relevant interfaces within that VPN.

Linking Scripts to Objects

You link existing scripts to objects by dragging and dropping or by Copy and Paste commands.

To link a script using drag and drop:

With the appropriate destination object (such as a device or interface) displayed in the Details pane, drag the script object and drop it onto the destination object.

To link a script using Copy and Paste Link commands:

Select the script that you want to link, and choose Copy from the Edit menu (or click the Copy toolbar button).
Select the object to which you want to link the script, such as a VPN or a device, and choose Paste Link.

To see which scripts have been applied to an object you need to check the configuration details. See "Checking the Status of Scripts".

The script is not implemented on any network devices until the appropriate transaction is committed.

Re-running a Script

A script set to run once can be run again if required.

To re-run a script on a particular object:

Select the relevant object and right-click on the script.
Select Reapply Driver Script from the context menu.

You must set the display so that both the relevant object and the driver script are visible – for example, by displaying the object in the Hierarchy pane and viewing its configuration in the Details pane.

To re-run all instances of a script:

On the Custom tab, right-click on the script from the Driver Scripts folder.
Select Reapply Driver Script from the context menu.

The script will be re-run on the relevant object(s) when the appropriate transaction is committed.

Removing Scripts

To remove a script from a policy target:

Double-click on the relevant object to view the configuration applied to that object.
On the Configuration pane, select the Driver Scripts tab.
Right-click on the relevant driver script and select Unlink from the script's context menu.

If the script applies to any child objects by a process of inheritance, it will be removed from all objects in the hierarchy. Unlinking a script does not delete the script; it remains visible in the user interface and can be associated with objects later.

To remove all instances of a script from the network:

Right-click on the appropriate driver script and select Properties.
On the Driver Script page, select the Disabled checkbox.
Click OK.

The removal of the script takes place when configuration changes are next propagated to the network.

The actual action that occurs depends on the contents of the Remove section of the script. If no Remove section is defined, the script is run as requested but no action will result, that is, no configuration will be removed.

The Remove section is also run when a device is deleted. When a device is set to Unmanaged, the Remove section will be run if the Unmanaged action (set in the Options dialog box) is set to Remove.

Note:

If a script is set to run once only, and not when a device is restarted, the Remove section can never be run as the device driver does not preserve the script. If a script is set to run once only and run on a restart, then it is possible for the Remove section to be run.

Propagating Configuration

Once a script is linked to an object or unlinked from an object, it is implemented when the appropriate transaction is committed. When the transaction is committed any requested configuration is propagated from the policy server to the proxy agents and from there to the network devices.

Applying Configuration

Where a script has been linked to an object, the commit procedure results in the Install section of the script being run on the specified object and any other object that has inherited the script.

The actual timing of the configuration changes will depend on the scheduling details specified on the Scheduling page of the Driver Scripts Properties dialog box:

If Before standard configuration changes is selected, the script is applied before any other configuration performed at this time. If After standard configuration changes is selected, the script is applied immediately after any other configuration is applied.
If Once is selected, the script is applied on the first configuration only. If Repeatedly is selected, the script is applied on all subsequent configuration changes until it is removed.
If Apply on Restart is selected, the script is always applied when the system detects a device restart (in addition to before configuration is applied).

Removing Configuration

The committed transaction results in the Remove section of the script being run in the following situations:

When a script has been unlinked from an object
When a device has been deleted
When a script has been disabled
When a device has been set to Unmanaged and the Unmanaged Action (set in the Options dialog box) is set to Remove (to specify that configuration is removed when a device is unmanaged).

Note:

Iif a script is set to run once only, and not when a device is restarted, the Remove section can never be run as the device driver does not preserve the script. If a script is set to run once only and run on a restart, then it is possible for the Remove section to be run.

The Remove section of the script is run on the relevant object and any other object that has inherited the script.

The scheduling settings have no effect when the Remove section is run.

Note:

The Remove section is optional. If no Remove section is defined in a script, the script is run as requested but no action will result. Oracle recommends that a Remove section is always included to ensure that configuration can be easily taken off.

Deleting Scripts

You can delete scripts that are not linked to any other object.

If you delete a predefined script that is supplied by Oracle, it is removed from the user interface. If necessary you can import it again later.

If you uninstall IP Service Activator, all pre-defined scripts are deleted from the DriverScripts directory. User-defined scripts are not deleted. If you want to keep a copy of a pre-defined script, you should export it, saving it under a different name (see "Exporting Scripts").