Adaptive Response Action Files Overview

Adaptive response action files are command files that are associated with a specific agent. Action files can be configured to take corrective action, notify network administrators of changes in their network, or to capture relevant history when an agent crosses a threshold to get worse or better. An action file can contain any CLI command that can run without additional user input. For example, the CLI command setup discover on is a useful command in an action file for a Default Traffic agent. When too high a percentage of traffic falls into the target /default class, the Default Traffic agent triggers its red action file. The action file issues the setup discover on command which turns on traffic discovery, improving the classification of traffic that was otherwise falling into the /default class. Action files can also include commands for sending notification that an agent has crossed a threshold and variables, which can be user-defined or automatically defined by the agent itself.

Each agent can have two assigned action files, one for the red threshold, and one for its green threshold. These files are triggered when any of the following thresholds are crossed:

• Red to Green—triggers green action file
• Yellow to Green—triggers green action file
• Green to Red—triggers red action file
• Yellow to Red—triggers red action file
• Blue (error state) to Red—triggers red action file

A red action file will also trigger if the first value returned by a new agent is past the red threshold. (This avoids the problem of the red action file never triggering if the agent always stays within the red threshold.) An action file gets triggered only when an agent changes status (from green/yellow to red, from red/yellow to green). For example, suppose an agent goes from green to red in a particular evaluation interval. The red action file will get executed. If the agent is still red in the next evaluation interval, the red action file will NOT get triggered. It's not until the agent goes to green or yellow and then back to red that the red action file gets triggered again.

Here is an example of a red action file for the High Bandwidth Host agent. This action file gets triggered when a single host has exceeded a certain percentage of the link size (the red threshold).

class new $direction $host-ip outside host:$host-ip
class rule add $direction/$host-ip inside host:$host-ip
send email raltman@test.com "High Bandwidth Host found" "Host $host-ip recently used $avg-bps bps, which is more than the Red Threshold ($RedThreshold percent). Class $direction/$host-ip was created."

This action file has three actions: creates a class based on the IP address of the bandwidth abuser, adds a matching rule to this class, and sends an email message that notifies the administrator of this situation. Note that this command file makes use of several action file variables ($host-ip, $direction, $avg-bps, and $RedThreshold). See Action File Variables below for more information.

Including Automatic Notification in an Action File

If you want to be notified automatically when an agent has crossed a red or green threshold, you can add one of the send CLI commands to the red or green action file. The notification can take one of the following forms: syslog entries, SNMP traps, or email messages. For additional information on setting up and using these commands, click any of the links below.

• send email
• send syslog
• send trap

Creating an Action File

Action files must be stored in your PacketShaper's 9.258/agent/cmd directory. Although you can use any text editor (such as Notepad) to create the action file, you may find it more convenient to use PacketWise's File Browser utility which has a facility for creating command files and storing them directly on the unit. To access the File Browser utility, use one of the following ways:

• The file browser button on the info tab
• The browse files button on the Edit Agent page

The second method offers two advantages. First, it automatically stores the action file in the proper place. (You don't have to navigate to the 9.258/agent/cmd directory). Second, after creating the action file, you are on the right screen for supplying the red or green action filename.

For step-by-step instructions on creating an action file, see Add or Edit Adaptive Response Action Files.

Action File Variables

By including variables in an action file, you can create action files that work in a variety of situations, that are applicable to multiple agents. Three types of variables can be included in action files:

• Variables available to all agents
• Agent-specific variables
• User-defined variables

Variables Available to All Agents

When the following action file variable names are included in an action file, the agent automatically enters the values for the variables as the file is run. You cannot change the values of these variables; their values come from the agent only.

These variables can be included in an action file as part of an email message to provide descriptive information about the threshold crossing.

Examples

Suppose you are creating an action file for a Partition Utilization agent that monitors all partitions in the traffic tree and you want to be notified via email when the utilization of one or more partitions exceeds the defined utilization threshold. The action file would contain the following command:

send email bob@test.com "$agentname agent turned red" "$scorevalue classes crossed the Utilization threshold."

When the agent turns red and the action file gets executed, an email will be sent to bob@test.com. The subject of the email will be Partition Utilization agent turned red and the body of the message will have something like 2 classes crossed the Utilization threshold.

Agent-Specific Variables

Any parameter for an agent can be a variable for an action file. For example, the Failed Flow Ratio agent has parameters named RedThreshold, GreenThreshold, RatioThreshold, ViolatingHosts, and ExceptionHosts. To use these as variables for action files, add a dollar sign in front of the parameter name ($RedThreshold, $GreenThreshold, $RatioThreshold, $ViolatingHosts, $ExceptionHosts). In addition to these parameter-based variables, some agent types offer additional variables that can be included in action files.

Examples

An action file for the High Bandwidth Host agent could contain the following command, which makes use of two of its agent-specific variables ($direction and $host-ip):

class new $direction $host-ip outside host:$host-ip


This action file creates a class for the top host in the interval.

As another example, suppose you have created a Partition Utilization agent to monitor the /Inbound/FTP partition, and you entered the traffic class /Inbound/FTP as the agent's ClassName parameter when you defined the agent. The action file for this agent could include the following CLI command:

partition apply $className 30% 40%

When the action file runs, the name of the class specified in the agent's ClassName parameter will automatically be inserted into the action file. Thus, the action file would then execute the CLI command:

partition apply /inbound/FTP 30% 40%

If you ever change the ClassName parameter on the agent to measure a different partition, for example on the /Inbound/Citrix traffic class, the action file would automatically reflect the change, and when triggered, would execute the command:

partition apply /inbound/Citrix 30% 40%

User-Defined Variables

The adaptive response feature also allows you to specify your own unique action file variables. When you define your own variables in an action file, these variables will appear in the Edit Agent Entry window  show screen along with the standard parameters (RedThreshold, GreenThreshold, and so forth). The advantage to using user-defined variables in an action file is that if information changes, you don't need to modify the action file — you can just directly enter the changed values in the fields in the Edit Agent Entry window.

A user-defined variable:

• Must begin with a dollar sign ($)
• Can be up to 32 characters long (not including the $ sign)
• Can have alphanumeric characters
• Can contain the following special characters: underscore (_), hyphen (-), percent (%)
• Cannot contain spaces

Examples of valid variable names: $email_address, $email2, $partition-maximum%.

Example

A red action file could include the following CLI command:

send email $emailaddress $subject_heading $message_to_admin

As a result, these user-defined action file variables will appear on the Edit Agent Entry window with a corresponding entry blank that lets you enter a value.  show screen

Note: Before the user-defined variables appear on the Edit Agent Entry screen, you must reset the parameters.

See also:

Adding and Editing Action Files

Edit an Adaptive Response Agent

Adaptive Response Overview

Adaptive Response Agent Examples