Use the Unit Limits Agent to Track Capacity

The Unit Limits agent carefully monitors the number of classes, matching rules, partitions, and dynamic partitions on your PacketShaper and alerts you when the unit is approaching its limits. Note that the agent does not report specific values for each of these objects — it tracks a composite score.

The standard alert is a red indicator on the info tab (PacketWise) or configuration tab (PolicyCenter). In addition, you can have an email, SNMP trap, or syslog message sent when the unit is close to system capacity (such as 99 percent); this method requires that you create an action file — a text file of PacketWise commands. The action file can take other actions, as well, such as disabling traffic discovery or deleting unnecessary classes (for example, port numbered classes). The file can include any CLI command that can run without additional user input. See Action File Overviews for more information.

In order to use this feature, adaptive response must be enabled and you must create an agent based on the Unit Limits template.

Create a Unit Limits Agent

By default, the Unit Limits agent checks the current number of classes, matching rules, partitions, and dynamic partitions every 15 minutes. It compiles this information into a composite score, represented as a percentage of system capacities. With the default settings, a score greater than 99 percent would trigger a red alert.

To create a Unit Limits agent:

1. On the setup tab, click the Adaptive Response Settings link.
   
   
2. Click add. The Add Agent Entry window will open.
   
   
3. In the create a new agent from this agent template drop-down list, choose Unit Limits.
   
   
4. Enter a unique identifying name for the new agent in the Name field.
   
   
5. If desired, change the evaluation interval, in minutes (how often the agent should measure its target).
   
   
6. Click OK and Edit Parms. This will open the Edit Agent Entry window where you can define the parameter values for your new agent.
   
   
7. If desired, modify the threshold values:
   
   RedThreshold — The value at which the status of the agent turns red, and a red action file is triggered, if present. For the Unit Limits agent, this number represents the percentage at which the unit is getting close to maximum system capacities. For instance, if the RedThreshold is set to 95, the agent's status will change to red when the composite score is greater than 95 percent of system capacity.
   
   GreenThreshold — The value at which the status of the agent turns green, and a green action file is triggered, if present. For instance, if the GreenThreshold is set to 90, the agent's status will be green when the unit's composite score is less than 90 percent of system capacity.
   
   
8. Click OK to save your changes.

Check the Agent Status

Note: Before you can check the status of the Unit Limits agent, you will need to wait until the first evaluation interval has passed (15 minutes, by default).

To check the status of the Unit Limits agent:

1. Click the info tab. The PacketShaper’s info tab shows an icon for each agent category, and a colored status indicator for each. The Unit Limits agent is in the Unit Health category.
   
   
2. To see the status of the Unit Limits agent, hover your mouse over the Unit Health colored status indicator, as shown below.
   
   
   
   
3. In the pop-up window, locate the Unit Limits agent. The value (6 in the figure above) indicates the unit's composite score represented as a percentage of system capacities. For example, a score of 63 indicates the unit was at 63 percent of capacity in the last evaluation interval.
   
   What color is its status indicator?
   
   Green — During the last evaluation interval, the Packeteer unit was not close to reaching maximum capacity.
   Yellow — During the last evaluation interval, the composite score was getting close to the red threshold. (Yellow is the range between the red and green thresholds.)
   Red — During the last evaluation interval, the Packeteer unit was approaching maximum capacity. If the status indicator is red, you should look at the incident report for details.
   
   If the agent has ever changed status (from green/yellow to red or from red/yellow to green, a report icon with a link to a detailed incident report will be available for that agent.
   
   
4. If there is a report for the Unit Limits agent, click the report icon. The incident report lists the maximum number of objects allowed, currently used, and remaining. You can use this report to see which objects are approaching their limits. For example, if the number of classes is approaching capacity, you might want to delete unnecessary classes from the traffic tree.
   
   
   
   

Create an Action File

If you would like to be notified by email when the PacketShaper is approaching maximum capacity, you can create a command file that contains a single line: the send email command. By designating this command file as the red action file, an email will be sent when the red threshold is crossed.

Note: In order to send email notification, you must configure an SMTP server in PacketWise.

To create an action file:

1. If the info tab is currently displayed, click the Settings link; otherwise, go to the setup tab and click the Adaptive Response Settings link.

2. Click the edit button next to the Unit Limits agent.

3. Click the browse files button. The File Browser window opens and shows the contents of the 9.258/agent/cmd directory (where action files need to be stored).

4. Click the new cmd file button. A command file window opens.

5. In the File Name field, enter a unique name for your action file up to eight characters long, including 0-9, a-z, AZ, -,_. Spaces are not allowed. The file will automatically be assigned the extension .cmd. Example: red-lmt

6. In the Contents area, enter the following commands:

#Title: red action file for Unit Limits agent
send email <address> "<subject>" ["<body>"]

where <address> is the email address of the recipient. For example:

send email raltman@test.com "Unit Limits" "The Packeteer unit is currently close to maximum capacity. Go to the info tab to view the incident report for the Unit Limits agent."

Note: If you want to send an email notification to more than one recipient, repeat the send email command for each email address.

Alternatively, you can include the variables for the agent name ($agentname) and the composite score ($scorevalue) in the <subject> or <body>, as the following example shows:

send email raltman@test.com "$agentname agent" "The PacketShaper is at $scorevalue of its capacity. Go to the info tab to view the incident report for the $agentname agent."

When the message is sent, the body of the email message would look something like this:

The PacketShaper is at 96 percent of its capacity. Go to the info tab to view the incident report for the Unit Limits agent.

7. Click save.

8. Enter the name of your action file in the Red Action File field (for example, red-lmt.cmd).

9. Click OK.

After the next evaluation interval, an email will be sent if and when the agent's red threshold is crossed. After reviewing the incident report, you can decide on the appropriate course of action, such as deleting unnecessary classes, turning off auto-discovery, expanding the capacity of your unit by purchasing a software key, or upgrading to a higher-capacity unit. If you are running out of matching rules, it's possible that the rules have not been defined as efficiently as they could be. For instance, instead of creating separate matching rules for each host, you can create a single matching rule with a host list.

If you like, you can create a green action file to notify you when the Unit Limits agent returns to a green status.