About the IAG rule-creating utility

  • Article

Applies To: Intelligent Application Gateway (IAG)

The Whale Communications Intelligent Application Gateway (IAG) 2007 rule creation utility automates the process of generating positive-logic rule sets; it records HTTP or HTTPS requests, converts them into rules, and processes the list of rules into an optimized rule set. The rule set can then be imported into other trunks.

You create rule sets using the utility as follows:

  • Use the online recorder utility to record the requests you wish to enable in the trunk. Note that you can create rule sets by defining requests that will be accepted (thus rejecting any other request), but you cannot create rule sets that specify which requests should be rejected.

  • Use the optimizer utility to optimize the recorded requests by eliminating duplications and combining requests that hold similar parameters. The optimized rule set is then ready to be imported into the trunk.

  • Repeat the record and optimize steps for all the trunks through which you wish to record rule sets.

Recording HTTP and HTTPS requests

The online recorder utility enables recording of both HTTP and HTTPS requests. The requests can be recorded while IAG is in production.

By default, each instance of the recorder records all the requests that arrive at the trunk; optionally, you can configure it so that it only records requests that arrive at a specific application. You can also activate a number of online recorders in order to record a number of trunks. Configure the recorder as follows.

Configuring the online recorder

To configure the online Recorder for a trunk

  1. Copy this file:

    …\Whale-Com\e-Gap\Von\Conf\WhlFiltRecorder.ini

    into one of the following folders:

    • If you are using the default Recorder settings, copy the file into this folder:

      …\Whale-Com\e-Gap\Von\Conf\Websites\Trunk_Name\Conf

      Proceed to the section "Recording the rule set".

    • If you wish to make changes to the default settings, copy the file into the CustomUpdate folder under the trunk’s Conf folder; if the

      CustomUpdate folder does not exist, create it:

      …\Whale-Com\e-Gap\Von\Conf\Websites\Trunk_Name

      \Conf\CustomUpdate

      Proceed to step 2.

      Note

      If the CustomUpdate folder already exists and contains the WhlFiltRecorder.ini file, this file may include previously defined custom changes. In this case, make your changes in the existing file and do not overwrite it.

  2. Use the following parameters and examples described in "Custom update file values" to configure the file.

Custom update file values

Parameter Description Values and Notes

Type

Functionality of the output file.

Must be 1.

OutputFilesPath

Path where the output files are created.

Must be the same folder where the optimizer utility files are located. Folder must be created before you run the recorder application.

HttpOutputFileName

Name of the output file for HTTP rules.

Ensure that you use different names for the HTTP and HTTPS output files.

HttpsOutputFileName

Name of the output file for HTTPS rules.

 

ApplicationID

Optional. When this option is applied, the Recorder records only requests that arrive at the application specified here.

You can view and copy the application ID in the Application Properties dialog box, in the General tab.

AppendToOutput

In cases where a rule list already exists, select whether to append the output to the existing file or whether to create a new file.

Set to 0 to specify that the output should not be appended. Set to any value except 0 to specify that output should be appended.

A sample WhlFiltRecorder.ini file:

[GENERAL]

# 1 - rules file

Type = 1

OutputFilesPath = C:\temp\

HttpOutputFileName = OutHttpRecord.ini

HttpsOutputFileName = OutHttpsRecord.ini

# 0 - new file other - append

AppendToOutput = 0

Recording the rule set

To record the rule set

  1. Use a Web browser to generate requests to the application server that you wish to enable in the rule set. The requests are recorded by the Recorder utility, and a rule list is created in the output file defined in WhlFiltRecorder.ini.

  2. To deactivate the recorder and stop recording, rename the WhlFiltRecorder.ini file in one of the following locations:

    • If you are using the default online recorder settings, use the following location:
      \Whale-Com\e-Gap\Von\Conf\Websites\<Trunk_Name>\Conf

    • If you have modified the default online recorder settings, use the following location:
      \Whale-Com\e-Gap\Von\Conf\Websites\<Trunk_Name>\Conf\CustomUpdate

  3. After you finish recording all the requests you want to enable in the rule set, at the browser, stop generating requests to the application server.

  4. In the IAG Configuration console, activate the configuration.

Optimizing the recorded rule sets

After you record the rules, using the online recorder utility, you can take the following steps to optimize the rule set:

  1. If required, configure the file that holds the optimization settings, Optimizer.ini. If you customize the Optimizer.ini file, it is recommended that the Optimizer.ini and userRules.ini files are both located in the CustomUpdate folder. If the userRules.ini file is located in a different folder than the Optimizer.ini file, you must enter the absolute path for the userRules.ini file in the user_rules_file_name parameter of the Optimizer.ini file.

  2. If required, configure the file that holds the settings of the additional, user-defined optimizing rules, userRules.ini. If you customize the userRules.ini file, it is recommended that the Optimizer.ini and userRules.ini files are both located in the CustomUpdate folder. If the userRules.ini file is located in a different folder than the Optimizer.ini file, you must enter the absolute path for the userRules.ini file in the user_rules_file_name parameter of the Optimizer.ini file.

  3. Run the optimizer utility. In the following stages, the application optimizes the rule set that was generated by the recorder utility:

    • Merges all identical requests.

    • Combines all the requests with the same URL into one rule and sets the statistics for all the URL parameters. Each combined rule will contain all the parameters that appeared in any request for the URL of the rule.

    • Reads the user-defined optimizing rules, and, according to this input, further combines matching rules.

  4. As required, import the rule set into the trunk.

Customizing the optimizer file (optional)

You can optionally modify settings for the optimizer utility, as follows. 

To customize the Optimizer.ini file

  1. Copy the file Optimizer.ini from this folder:

    …\Whale-Com\e-Gap\Utils\HttpRecorder

  2. Access the following CustomUpdate folder:

    …\Whale-Com\e-Gap\Utils\HttpRecorder\CustomUpdate

    If this folder does not exist, create it.

  3. Place the file Optimizer.ini in the CustomUpdate folder.

    Note

    If the CustomUpdate folder already contains the Optimizer.ini file, this file may include previously defined custom changes. In this case, make your changes in the existing file and do not overwrite it.

  4. Set the parameters in the Optimizer.ini file, according to the descriptions and notes in the following table and according to the sample file provided thereafter.

Key Description Parameters and Notes

recorder_

file_name

Name of the file generated by the Recorder utility.

The file name is defined in the Recorder configuration file, WhlFiltRecorder.ini, in one of the following parameters:

HttpOutputFileName

Or,

HttpsOutputFileName

user_rules_

file_name

Name of the file that holds the additional, user-defined optimizing parameters.

By default:

userRules.ini

Please see note below.

optimized_rules_

file_name

Name of the output file, that is, the optimized ruleset that will be imported into the trunk.

In order to import the file into

the trunk, the file name must be the following:

HTTP_RuleSet.ini.

log_level

Select whether to create a log

file, and, if a log is created,

the level of severity of the

events recorded in the file.

0=no log is created.

1=record high severity events.

2=record high and medium

severity events.

3=record all events.

create_first_

level_rules_file

Select whether to create the

first-level rule file, that is, the

rule list that the Optimizer

utility generates before it runs

the additional, user-defined

optimizing parameters.

0=no.

1=yes.

Note

If the Optimizer.ini and userRules.ini files are not located in the same folder, that is, if the userRules.ini file is not located in the CustomUpdate folder, you must enter the absolute path for the userRules.ini file.

A sample Optimizer.ini file:

[GENERAL]

# The recorded HTTP requests file

#-------------------------------

recorder_file_name = outRecord.ini

# The user rules file

#---------------------

user_rules_file_name = userRules.ini

# The output file name

#---------------------

optimized_rules_file_name = HTTP_RuleSet.ini

# log_level can take the values:

#

# 0 - Log file is not active at all.

# 1 - Only high severity events will be written to the log.

# 2 - High & medium severity events will be written to the log.

# 3 - All events will be written to the log.

#-----------------------------------------------------------

log_level = 0

# Indicate whether to create the first level rule file

# Can take the values: 1 = true or 0 = false

#---------------------------------------------

create_first_level_rules_file = 0

Customizing additional user-define optimizing rules (optional)

Configure additional user-defined optimization options as follows:

To customize the userRules.ini file

  1. Access the CustomUpdate folder at the following location:

    Whale-Com\e-Gap\Utils\HttpRecorder\CustomUpdate

    If the folder does not exist, create it.

  2. Copy the file userRules.ini from the folder following folder, and then place it into the CustomUpdate folder:

    \Whale-Com\e-Gap\Utils\HttpRecorder

    Note

    If the CustomUpdate folder already contains the userRules.ini file, the file may include previously defined custom changes. In this case, make the changes in the existing file and do not overwrite it.

  3. The userRules.ini file is divided into two parts. At the top, the “General user parameters” rule holds parameters that apply to all the consecutive rules, as described in the following table.

Key Description Parameters and Notes

is_url_ casesensitive

Defines whether URLs are case sensitive.

0=not case sensitive

1=case sensitive

is_param_name _casesensitive

Defines whether parameter names are case sensitive.

0=not case sensitive

1=case sensitive

is_param_val_ casesensitive

Defines whether parameter values are case sensitive.

0=not case sensitive

1=case sensitive

The “User defined rules” area is divided into sections, each section holding one rule. The following table describes the parameters of one rule; a sample file is provided thereafter. Create as many rules as you wish. Note that section and rule names must be unique.

Key Description Parameters and Notes

match_name

A regular expression to be matched.

For example: .*\.asp

Method

Method or methods allowed in the rule.

Only the GET and POST methods are applicable. Note that if both methods are allowed, separate them with a comma and no space: GET,POST

The rules are handled in a lexicographic order, as in a dictionary, and not according to the order by which they appear in the file. We recommend that you name the user-defined rules by using a numeric method. For example:

Rule_1

Rule_2

Rule_n

A sample userRules.ini file:

# General user parameters

#------------------------

[RULE_0]

is_url_casesensitive = 1

is_param_name_casesensitive = 0

is_param_val_casesensitive = 1

# User defined rules

#-------------------

[RULE_1]

method = GET,POST

match_name = .*\.asp

[RULE_2]

method = GET

match_name = .*\.gif

Running the optimizer utility

You run the optimizer utility to optimize rule sets generated using the recorder utility. Running the optimizer requires the same actions whether you are using the default optimizer options or customized options. The optimizer utility checks requests against the rule parameters in the following order:

  • Match_name, including case-sensitive parameters

  • Method

To run the Optimizer utility

  • Open a command prompt, and then run the following file:

    …\Whale-Com\e-Gap\utils\HttpRecorder\rulesoptimizer.exe

    The application runs on the input ruleset and optimizes it. Once the optimization is finished, a message is displayed in the command prompt.

    The optimizer utility generates the output ruleset in the file HTTP_RuleSet.ini, which it creates under the same folder where it had run. You can import the file into any HTTP trunk. For information about importing and exporting rule sets, see Configuring IAG URL rules.