Testing and Troubleshooting Tools : Component statistics and diagnostics

Component statistics and diagnostics

Topic 50101 / Updated: 24-Jun-2010

Applies To:

Websense Web Filter 7.5 Websense Web Security 7.5

A command-line utility called ConsoleClient is included as part of your Websense software installation. This utility can be used to retrieve statistics and diagnostic information from Websense Web Security / Websense Web Filter components.

Use ConsoleClient to:

Review user name to IP address resolution maps to troubleshoot user identification issues.

Review requests sent to Filtering Service to make sure that requests are being passed properly by Network Agent, Content Gateway, or a third-party integration product.

Collect Network Agent diagnostic data.

Information about other uses of ConsoleClient can be found in troubleshooting materials for specific components.

Run ConsoleClient

Windows:

1.	Open a command prompt on the Filtering Service machine (go to Start > Run and enter cmd).

2.	Navigate to the Websense bin directory (by default, C:\Program Files\Websense\bin).

3.	Enter the ConsoleClient command with one or more additional parameters. For example:

websenseping <IPaddress> <port>

This command returns a menu showing options for the component running at the specified IP address and listening on the specified port.

Linux:

1.	Open a command shell on the Filtering Service machine.

2.	Navigate to the Websense installation directory (by default, /opt/Websense).

3.	Enter the WebsenseTools -d command with one or more additional parameters. For example:

./WebsenseTools -d <IPaddress> <port>

This command returns a menu showing options for the component running at the specified IP address and listening on the specified port.

The initial menu that displays looks like this:

DIAGNOSTICS>
****** Facilities ******
1) Tracing
2) PrintSelf
Q) Quit

> _

Use option 1 (Tracing) to log current activity for the selected component. Submenus show what information can be recorded and allow you to enable and disable the tracing process.

Depending on the component, you may be able to trace communication on a specified channel, communication between specific components, filtering activity by the selected component, and so on.

Use option 2 (PrintSelf) to output current status details or data maps for the selected component. Submenus shows what output formats (onscreen and file) and types of information are available.

Depending on the component, you may be able to view user maps, current configuration details, summary information about requests processed, service resource allocation information, and so on.

The sections that follow provide instructions for gathering specific types of tracing and status information.

Review user name to IP address resolution maps

If user-based policies are not being applied correctly in your environment, or if user information is missing from reports, use the following steps to make sure that Filtering Service and any transparent identification agents deployed in your network have correct user name to IP address mappings.

1.	Navigate to the appropriate directory (by default, C:\Program Files\Websense\bin or /opt/Websense/) and enter the relevant command:

consoleclient <IP address> <port>

./WebsenseTools -d <IP address> <port>

Provide the IP address and diagnostic port of the component for which you want to gather data.

Filtering Service	15869	DC Agent	30601
Logon Agent	30603	eDirectory Agent	30701
RADIUS Agent	30801

2.	Enter the following:

a.	2 (PrintSelf )

b.	1 (Dump to Local File)

c.	3 (This specifies a higher level of detail.)

d.	usermap.txt (You can use any descriptive file name. By default, the file is created in the Websense bin directory.)

e.	5 (XID User Map)

f.	Q (Exit the utility.)

3.	Open the output file in a text editor and examine the entries to ensure the user map contains correct user name, host name, and IP address information.

Generate a list of manually authenticated users

You can use ConsoleClient to generate a list of users prompted for manual authentication. To do this, follow the steps in the previous section, Review user name to IP address resolution maps, with the following variations:

1.	Provide the Filtering Service IP address and port (15869).

2.	After entering a name for the output file, enter 1 (User Map) instead of 5 (XID User Map).

The resulting output file shows only users who were prompted for their logon information. Users who fail manual authentication are denied Internet access. Denied users do not generate Internet traffic, so no data is logged to the Websense reporting database. Although no reporting data is saved, since Filtering Service received the Internet request, one seat is added to the current subscription count.

Review requests sent to Filtering Service

Use ConsoleClient to verify that Network Agent, Content Gateway, or a third-party integration product is successfully passing Internet requests to Filtering Service. This process also shows how much latency is involved in processing a lookup request.

To create a log file showing Filtering Service responses to status and lookup requests:

1.	Navigate to the appropriate directory (by default, C:\Program Files\Websense\bin or /opt/Websense/) and enter the relevant command:

ConsoleClient <IP address> 15869

./WebsenseTools -d <IP address> 15869

Provide the IP address of the Filtering Service instance that you want to query. 15869 is the Filtering Service diagnostic port.

2.	Enter the following:

a.	1 (Tracing)

b.	8 (WISP. This is the communication protocol used to send filtering requests to Filtering Service.)

c.	A (Set Buffer Size), and then enter a buffer size in kilobytes (for example, 10000)

d.	1 (Enable Tracing)

At this point, ConsoleClient starts to log all traffic between Network Agent, Content Gateway, or the integration product and Filtering Service.

3.	Generate HTTP lookup requests by browsing the Internet for at least 1 minute from one or more filtered machines.

Note the specific sites (URLs) that you visit so that you can verify that the associated lookup requests are being passed to Filtering Service correctly.

4.	When you are finished performing the test, return to ConsoleClient and enter the following:

a.	1 (Disable Tracing)

b.	2 (Dump Decoded Buffer )

c.	1 (Dump to Local File)

d.	fstrace.txt (You can use any descriptive file name. By default, the file is created in the Websense bin directory.)

e.	0 (This Format Option selection)

f.	P (Return to Previous Menu)

g.	Q (Exit the utility.)

5.	Open the output file in a text editor and search for the URLs that you visited during the test.

Check the received and response times. Requests taking longer than 200 ms (milliseconds) may be indicative of a problem.

If the sites that you visited are not in the logs, Filtering Service is not receiving the lookup requests.

If no traffic at all appears in the logs, make sure that Network Agent, Content Gateway, or the integration product is configured properly. Also check to see if any network device is intercepting traffic between Filtering Service and Network Agent, Content Gateway, or the integration product.

Note  Not all integration products use the same method to communicate with Filtering Service. Some send lookup requests that do not include full URLs. This can result in tracing output that does not include all of the information described in this paper, even though the integration and Filtering Service are communicating correctly.

Collect Network Agent diagnostic data

You can use ConsoleClient to review the data (packets) being monitored by Network Agent.

1.	Navigate to the appropriate directory (by default, C:\Program Files\Websense\bin or /opt/Websense/) and enter the relevant command:

ConsoleClient <IP address> 55870

./WebsenseTools -d <IP address> 55870

Provide the IP address of the Network Agent instance that you want to query. 15869 is the Network Agent diagnostic port.

2.	Enter the following:

a.	1 (Tracing)

b.	3 (Network Agent Tracing)

c.	A (Set Buffer Size), and then enter a buffer size in kilobytes (for example, 10000)

d.	1 (Enable Tracing)

3.	Reproduce the issue that you are trying to troubleshoot. For example, browse the Internet from a specific machine, or as a specific test user. Typically, perform the test for at least 1 minute.

4.	Return to ConsoleClient and select the following options:

a.	1 (Disable Tracing)

b.	2 (Dump Decoded Buffer)

c.	1 (Dump to Local File)

d.	nadiag.txt (You can use any descriptive file name. By default, the file is created in the Websense bin directory.)

e.	0 (This Format Option selection)

f.	P (Return to Previous Menu)

g.	Q (Exit the utility.)

5.	Open the output file in a text editor and search for the URLs that you visited during the test.

You can also use the PrintSelf option to troubleshoot performance issues. A high number of active connections may indicate problems.

1.	Navigate to the appropriate directory (by default, C:\Program Files\Websense\bin or /opt/Websense/) and enter the relevant command:

ConsoleClient <IP address> 55870

./WebsenseTools -d <IP address> 55870

Provide the IP address of the Network Agent instance that you want to query. 15869 is the Network Agent diagnostic port.

2.	Enter the following:

a.	2 (PrintSelf)

b.	1 (Dump to Local File)

c.	3 (This specifies a higher level of detail.)

d.	nainfo.txt (You can use any descriptive file name. By default, the file is created in the Websense bin directory.)

e.	3 (Network Agent PrintSelf)

f.	Q (Exit the utility.)

3.	Open the output file in a text editor.

A summary near the top of the file shows HTTP and non-HTTP requests processed and blocked, as well as the number of errors encountered in attempting to process requests.

Information near the end of the file shows what configuration settings (from the TRITON - Web Security Settings pages and the Network Agent configuration file) are currently being used by this Network Agent instance.

The file also includes information about the blocking and monitoring NICs, as well as resource use details that can be used to identify potential problem areas.

Testing and Troubleshooting Tools : Component statistics and diagnostics