Creating a log

Configuring a log file entry

When creating a logging rule, you need to configure an event within this rule that builds the log file entries.

A log file entry provides information about an activity that is performed on Web Gateway. For example, receiving and filtering a request.

Properties are used to store this information. For example, the Authentication.Username property is used to store the name of a user who sent a request.

To configure an event that builds log file entries, you need to specify all the properties you want to use for storing information. The event combines the values of these properties to the value of a single property, which is named User-Defined.logLine.

The value of the User-Defined-logLine property is then written by a write event into a log file.

When specifying the properties for the event that builds the log file entries, you need to consider some requirements.

Create a log rule set with a logging rule

To create a logging rule that lets entries be written into log files and stored in a log, create a log rule set for it and configure rule criteria and events.

The purpose of the sample rule described here is to log all requests that are received from a client with a particular ID if the following also applies:

• A request is not valid under the HTTP protocol (response 403) or
• A request is blocked by the web security rules on Web Gateway (block ID is not 0).

1. Select Policy | Rule Sets.
2. Select Log Handler and on the log handler tree, expand the Default log handler rule set.
3. Create a rule set for the logging rule.
   This rule set will be nested in the Default rule set.
   1. Click Add, then Rule Set.
   2. In the Name field, type a suitable name for the new log rule set. For example, Troubleshooting Log.
   3. Click OK.
      The window closes and the new log rule set appears on the log handler tree.
4. Add a logging rule and name it.
   1. On the settings pane, click Add Rule.
   2. In the Name field, type a suitable name for the logging rule. For example, Log requests that caused issues.

5. Configure the rule criteria.
   1. Select Rule Criteria. then click Add and select Advanced Criteria.
   2. Select Client.IP as the property, equals as the operator, and in the field below Compare with, type an IP address as the operand. For example, 10.149.33.8.
   3. Click OK.
      The Add Criteria window closes and the configured rule criteria appears in the Add Rule window.
   4. Click Add again for the second part of the criteria.
   5. In the same way as for the first part, configure Response.StatusCode, equals, and 403, then click OK.
   6. In the same way configure Block.ID, does not equal, and 0, then click OK.
6. Configure the event that builds the log file entry.
   • Select Events and click Add, then select Set Property Value.
   • From the properties list, select User-Defined.logLine and below To concatenation of these strings click Add.
   • Click Parameter property and from the properties list, select DateTime.ToWebReporterString, as the first element of the log file entry. Then click OK.
     The Enter a String window closes and the configured element appears in the Add Set Property window.
   • Click Add, make sure Parameter value is selected, and type a blank followed by a double quote. Then click OK.
     The Enter a String window closes and the configured delimiters appear in the Add Set Property window.
   • Add the next element of the log file entry.
     • Click Add, then Parameter property.
     • Select String.ReplaceIfEquals and click Parameters next to the property name.
       The Parameters For Property window opens.
     • For the first parameter, click Parameter property, and select Authentication.Username.
     • Select the second parameter and do not enter anything in the input field on the right.
       This creates a blank as the parameter value.
     • Select the third parameter and type a dash in the input field.
     • Click OK in the Parameters For Property, then in the Enter a String window.
       The element appears in the Add Set Property window.
   6. Click Add and type a double quote, a blank, and a double quote. Then click OK.
      The Enter a String window closes and the configured delimiters appear in the Add Set Property window.
   7. Add the remaining elements by selecting the properties listed in the following. Insert delimiters between the elements, as shown in substep f.
      • Client.IP. For this element, configure the IP.ToString property with the Client.IP property as its parameter. Add the parameter as shown in substep e.
      • Request.Header.First.Line.
      • Header.Request.Get. Configure a parameter for this element by typing user-agent as the parameter value.
      • Rules.CurrentRuleSet.Name.
      • Rules.CurrentRule.Name.
      • Block.ID. For this element, configure the Number.ToString property with the Block.ID property as its parameter.
      • Block.Reason. After this last element, only use one double quote as the delimiter.
   8. Click OK to close the Add Set Property window.
      The event that creates the log file entry appears in the Add Rule window. It should look like this:

Set User-Defined.logLine =
DateTime.ToWebReporterString
+ " ""
+ String.ReplaceIfEquals
(Authentication.UserName, "", "-")
+ "" ""
+ IP.ToString(Client.IP)
+ "" ""
+ Request.Header.First.Line
+ "" ""
+ Header.Request.Get("user-agent")
+ "" ""
+ Rules.CurrentRuleSet.Name
+ "" ""
+ Rules.CurrentRule.Name
+ "" ""
+ Number.ToString(Block.ID)
+ "" ""
+ Block.Reason
+ """

If you need to make changes, select the event, click Edit, and work with the Edit Set Property window.

7. Configure the event that writes the log file entries into a log file.

   1. Under Events in the Add Rule window (or Edit Rule window if you made changes), click Add and select Event.

   2. From the events list, select FileSystemLogging.WriteLogEntry and click Parameters.

   3. Click Parameter property and from the list below, select User-Defined.logLine, then click OK.
      The Parameters for Execute Action window closes.

   4. In the Add Event window, click Add below the Settings field.

   5. Create new settings.
      These settings will be used by the File System Logging module (or engine) to handle the new log you are creating.

      • In the Name field, type a suitable name for the new settings, for example, Troubleshooting Log Settings.

      • Under Name of the log, type troubleshooting.log.

      • Select Enable header writing and in the Log header field, type the elements of the log header.
        The log header will appear at the beginning of every log file in the new log. It should represent the elements of the log file entry that you configured in step 6. So the log header might look like this:

time_stamp "auth_user" "src_ip" "req_line" "user_agent" "rule_set" "rule"
"block_page_res"
"block_res"

• Under Settings for Rotation, Pushing, and Deletion, configure the following.

  • Select Enable specific settings for user-defined log.

  • Under Auto-Rotation, select GZIP log files after rotation to save memory space.

  • Configure the remaining settings under Auto-Rotation and those under Auto-Deletion as needed.

6. ​Click OK in the Add Settings window, then in the Add Event window.
   The windows close and the event that writes the log file entries appears in the Add Rule (or Edit Rule) window.

7. Click Finish.
   The window closes and the new logging rule appears as a rule of the Troubleshooting Log rule set on the Rule Sets tab.

You have now created a logging rule for recording a particular kind of requests.

The log files can be viewed in the log with the configured name. The log is accessible from the Troubleshooting top-level menu on the appliance you have configured the rule on.

The path to the log is Log files | user-defined logs.