cOS Stream 4.00.00 Data Collection Guide

The Scope of this Guide

This guide outlines the data collection procedures to be used with the cOS Stream product when entering a Support Ticket into the Clavister support system. The procedures it describes should be applied for each ticket submitted.

Following the recommendations in this document ensures that appropriate and sufficient information is provided to support personnel in order to achieve timely issue resolution.

Support Tickets

A Support Ticket is the basis for all issue reporting to Clavister support personnel. It is created online after logging in to the MyClavister section of the Clavister website and then selecting the Help Desk feature. After creation, each ticket goes through a defined process towards a satisfactory resolution. Creating tickets and the resolution process are described in Chapter 2, Creating Tickets.

A ticket single relates to a single issue for which resolution is sought. Once entered, both the customer and support personnel can provide and exchange information via the ticket system with email notifications going to the customer when the ticket's status changes.

Providing the Required Information is Important

If a ticket is incorrectly entered or the necessary information and/or attachments are missing, processing can be delayed or may even require resubmission. It is therefore vital to provide all the mandatory information and any relevant optional information.

The information that is required and the information which is optional is described in Chapter 2, Creating Tickets as well as in Chapter 3, Attachments.

This chapter looks in detail at how a Support Ticket is created when reporting an issue to Clavister support personnel.

Using the Support Ticket System

To create a new ticket in the Clavister support ticket system, use the following steps:

Support Ticket Components

The following submitted components make up a support ticket:

A. The Issue Description

B. Attachments

These two components will now be described further.

A. The Issue Description

This part allows the entry of free text to describe the issue. The text description is in two parts:

The longer text description should cover the following:

B. Attachments

A support ticket usually also includes attachments which consist of files containing system output that help support personnel to understand the issue. These files should be compressed together into a single ZIP file. The ZIP file is then added after ticket creation by opening the ticket and then dragging and dropping the ZIP file into the attachment box on the webpage.

The attachment should be a single compressed ZIP file. Do not use tar + gzip.

Where the ZIP file exceeds 25 MBytes, it should not be attached to a ticket in the MyClavister system. Instead, support personnel should be contacted to get instructions for uploading to Clavister support's FTP server. A request for FTP upload of attachments could be made in the description text that is entered when the ticket is created.

Attachments are described in more detail in Chapter 3, Attachments.

Available Customer Options After Ticket Creation

Once a ticket is created, there are three ticket options available to the administrator:

The Ticket Life Cycle and Ticket States

A support ticket has a large number of possible states which indicate its progress in the ticket system. However, only a small number of states will be encountered by a typical ticket and those are the ones that will be discussed here.

The typical ticket life cycle and the associated states are as follows:

Email Notifications

Any change of support ticket state is reported to the customer automatically via an email. The email will not state what has changed in the ticket, only that there has been a change.

The addition of comments by support personnel will also cause a notification email to be sent even though there may be no state change.

Multiple Organization Users Can Track a Single Ticket

Multiple login accounts can be associated with a single organisation in the support system and it is possible for any of these to see a ticket and also get email notifications of status changes.

An Explanation of the MyClavister User Account Hierarchy

Each customer organization should have at least one initial top-level administrator MyClavister account. Each administrator account will have product licenses associated with it and also has a complete overview of tickets associated with those licenses. For smaller organizations this can be sufficient.

However, for larger organizations with many product installations, multiple new user accounts could be created later, with different login credentials and email addresses, and these can then be linked with the organization. Linking is done by an administrator account inviting in a new user so they become associated with the same organization as the administrator. The administrator can then assign access rights to the newly included user. A new user could be given administrator privileges too or, more typically, they might be given only restricted access to support tickets and/or licenses.

It is often beneficial for a larger organization to have one or a small number of administrator user accounts and then different user groups could create accounts which are invited in by an administrator to be part of an organization. This will mean that accounts can have a separate email address so that email traffic related to their support tickets will go only to the user who created the ticket. However, an administrator or any user with support ticket access privileges will still have the ability to see the ticket details for all the accounts associated with an organization.

This chapter reviews the attachments that could be included with a support ticket and describes how they are created and the file format in which they should be sent. Before beginning the process, a number of points should be noted:

Mandatory and Optional Attachments

Attachments can be considered to be either mandatory or optional. When submitting a new ticket, it is advisable to provide all mandatory attachments (where relevant) since they are considered to make up the minimum amount of information for issue resolution.

The optional attachments should be provided where the ticket creator judges they are relevant to the reported issue. Both types of attachments are listed below:

A. Mandatory Attachments

B. Optional Attachments

Directory Structure for Submitted Data

All attachments for a given support ticket should be submitted in a single compressed file, preferably using the ZIP file format.

The structure of the compressed files submitted should follow the hierarchical directory structure shown below, with folders included as needed:

	TIC-nnnn
		Eventn_FWnn_YYYYMMDD_HHMM
			Config
			Techsupport
			CLI
			Crashdump
			Logs
			Pcap
			Statistics
			VM
			

At the very minimum, the Config and Techsupport subdirectories should be included.

The variable names used in this directory structure are:

Multiple Incidents/firewalls Per Ticket

When reporting several issues within the same support ticket, place each issue into its own Eventnnn_FWnn_YYYYMMDD_HHMM folder.

When the issue involves a high availibility cluster of two Clavister Firewalls, there should be one Eventnnn_FWnn_YYYYMMDD_HHMM folder for the master unit and one for the slave.

Each of the lower level directories in the attachments file is designed to hold files related to a specific subject and the different subjects are discussed next.

The Config Directory

The subdirectory contains attachments describing the configuration and network setup.

The Techsupport Directory

This subdirectory holds the file(s) created by running the techsupport command:

System:/> techsupport

This command automatically runs a large series of individual diagnostic commands and stores the collective console output in a text file called techsupport.txt which is placed in the firewall's root directory. SCP can then be used to download this file to a management computer.

Ideally, the techsupport command should be run immediately after a problem occurs so that the state of the firewall after the event can be viewed. However, in some cases, running the command as late as possible prior to the event can provide additional information or may even be necessary if the CLI cannot function after the critical event.

For HA configurations, the techsupport command should be repeated for both the master and slave units.

The CLI Directory

This subdirectory holds any relevant CLI output which is additional to the output of the techsupport command.

The Crashdump Directory

This subdirectory contains any crashdump files downloaded from the system. To list all crashdumps files on the firewall disk, use the CLI command:

System:/> crashdump -list

The filenames of available crashdump files are also listed in the techsupport.txt file generated by the techsupport command.

Crashdump files are always saved on the firewall in a directory called crashdumps. A typical SCP client command on a management computer to download all the available crashdump files might be:

C:\> scp admin@198.10.2.4:crashdumps/* ./

Crashdump filenames have the following format:

			yyyy-mm-dd_hh.mm.ss_binary.dump

For example, 2017-05-30_12.57.12_logd.dump.

After successful download of all the existing crashdump files, it is recommended to clear those files from firewall storage. This is done with the CLI command:

System:/> crashdump -rm=all

The Logs Directory

This subdirectory contains log event and snooping information. Log data should be recovered from a configured Syslog server.

A recommendation is to provide logs that cover at least 30 minutes before the issue occurred and, where possible, 30 minutes after the issue.

For an HA configuration, log files should be provided for both the master and slave unit.

Output from snoop commands could also be included in the Logs directory, if relevant. Examples of these commands include the following:

The Pcap Directory

This subdirectory contains output from packet dumps.

Packet dumps from the unprotected and protected side give a detailed picture of the traffic pattern preceding the incident and may be essential for the root cause analysis.

The amount of data a firewall is exposed to in a production network can be extensive. However, if packet dumps from the time of the incident are available, these should be included with the support ticket.

The recommendation from Clavister is to use a computer running Wireshark/TCPdump with sufficient disk storage for storing large amounts of data in order to capture packets from all relevant interfaces on the unprotected and the protected side at the same time.

The amount of data that needs to be stored depends on how much data each firewall is exposed to and how fast the incident appears.

Include packet dumps within an interval of around 10 minutes before and 5 minutes after the incident, or enough to cover the incident. If possible, keep each submitted file under 1 GB in size.

For an HA configuration, this operation should be done on both nodes, if possible.

The Statistics Directory

This subdirectory contains statistical information which can be helpful in giving a complete picture of the system load and activity at the time of the incident.

The techsupport command already provides a snapshot of all the statistical counters. For retrieving additional statistical data, SNMP or the CLI could be used. However, SNMP is the recommended method because SNMP clients can usually retrieve and store multiple statistical values over a period of time time and then construct graphs or other presentations of the raw data.

It is up to the creator of a ticket to include the relevant statistics. It is recommended, if possible, to provide statistical data covering the 12 hours before and the 2 hours after an incident.

The VM Directory

The subdirectory contains a text file which describes the virtual environment in which the firewall is running.

Details should include the virtual environment name (for example, ESXi), the version number and any other details about the virtual environment that may be relevant.

If an HA configuration is using dissimilar virtual environments, both the master and slave environment should be described.

Downloading All Files Using SCP

As described earlier for backup configuration files, use a suitable SCP client running on a management computer to download files from the firewall. To download all files, a typical SCP client command on the management computer would be:

C:\> scp admin@198.10.2.4:* ./

Here, the firewall's management interface IP is assumed to be 198.10.2.4 and the account name is admin..

A typical SCP command for downloading all files and all folders would be:

C:\> scp -r admin@198.10.2.4:* ./