3 File Watcher

This chapter covers the following topics:

The File Watcher module monitors a list of files for additions, deletions, and modifications. If changes are detected, it builds events and displays them in a table. It provides default capabilities for some of the popular files, such as passwd, vfstab, and so on.

You can add, remove, or edit entries in this default list. To add a new file, you must define the record format of the file being monitored. In the case of a record addition event, a record deletion event, or a record modification event, you have to also specify the file-specific severities of the alarms to be generated.

Note - The purpose of the File Watcher module is to monitor files that are not modified frequently, and therefore, it is useful to get notified when a change occurs. Therefore, module should only be used to monitor system files that are not expected to change frequently, for example, the passwd file.

The File Watcher Module

To Access the File Watcher or the File Watch Module

Load the File Watch module.

For instructions on how to load a module, refer to the Sun Management Center 3.0 User's Guide.

Double-click Local Applications in the Navigator window.

Double-click on File Watch in the Navigator window.

Double-click on the File Watcher option.

The Viewer displays the File Watch icon in the Viewer window.

Double click on the File Watch icon in the Viewer window.

Sun Management Center displays the following File Watch tables:

On the right side of each table title, File Watch lists the associated alarm counts.

The Watched File Table is used to monitor the existence of files. The Change Table is used to monitor the changes in existing files.

File changes can only be noticed once the file has been detected as existing. This means that if a file does not exist or is non-existing, the module detects that it is existing with a size bigger than 0. For example, when a file has two records already, the module will not be able to notice those two records. However, the module will notice all future modifications.

FIGURE 3-1 displays the File Watcher tables.

FIGURE 3-1 File Watch Module

This table is initialized with seven system files through filewch.dat:

/etc/hosts
/etc/aliases
/etc/nsswitch.conf
/etc/inittab
/etc/vfstab
/etc/passwd
/etc/printers
/etc/mnttab
/etc/rmtab

Watched File Table

The Watched File Table lists all the files being monitored by the module. It displays some of the more commonly used attributes at the top level and other hidden attributes in a lower level. For more information on hidden attributes, refer to To Access Hidden Attributes.

Displayed Attributes

The Watched File Table displays information about each file and provides the data on the following.

TABLE 3-1 Watched File Table
Field
Description

Name

Name of the file

Full Path

Path to file and the real name

File Size

Size of the file in bytes.

File Owner

The owner of the file

File Group

The group the file belongs to

File Permissions

Permissions on the file

Timestamp

Time when the file was last updated

Validation Script

It is the path to the validation script to be used to validate the file (for a row) when its timestamp changes. Save the script in
/var/opt/SUNWsymon/SysMgmtPack/filewch/scripts and enter the path as one that is relative to this directory. The value for script may or may not be provided.

Exit Code

Displays the exit code of the last execution of the validation script.

**TABLE 3-1** Watched File Table
Field	Description
Name	Name of the file
Full Path	Path to file and the real name
File Size	Size of the file in bytes.
File Owner	The owner of the file
File Group	The group the file belongs to
File Permissions	Permissions on the file
Timestamp	Time when the file was last updated
Validation Script	It is the path to the validation script to be used to validate the file (for a row) when its timestamp changes. Save the script in `/var/opt/SUNWsymon/SysMgmtPack/filewch/scripts` and enter the path as one that is relative to this directory. The value for script may or may not be provided.
Exit Code	Displays the exit code of the last execution of the validation script.

To Access Hidden Attributes

Select a row.

Right-click and select Edit Row.

Sun Management Center displays the Row Editor with all the attributes displayed in the Watched File Table, and those that are hidden.

Hidden Attributes

The following attributes are hidden and can be accessed by right clicking on any row and selecting Edit Row. You will see the Row Editor.

TABLE 3-2 Row Editor
Field
Description

Delimiter

Delimiter between columns.

Comment char

Type of the char that delimits a comment line.

Number of fields

Number of fields in each file entry.

Num key field

Number of fields composing the key. The key is assumed to be at the beginning of the record. A key is an identifier for the record. For example, in the passwd file, the key for each record is the first field: user name. It is unique for each record.

Field names

Names of the different columns in the file entries.

Hide values flag

One of the following values:
FALSE = Display the value that changed
TRUE = Do not display

Addition Severity

Possible values: Info, Warning, Error, None.

Deletion Severity

Possible values: Info, Warning, Error, None.

Change Severity

Possible values: Info, Warning, Error, None.

Record Format

Format of the record. Refer to Validation Script for more information.

**TABLE 3-2** Row Editor
Field	Description
Delimiter	Delimiter between columns.
Comment char	Type of the char that delimits a comment line.
Number of fields	Number of fields in each file entry.
Num key field	Number of fields composing the key. The key is assumed to be at the beginning of the record. A key is an identifier for the record. For example, in the `passwd` file, the key for each record is the first field: `user name`. It is unique for each record.
Field names	Names of the different columns in the file entries.
Hide values flag	One of the following values: FALSE = Display the value that changed TRUE = Do not display
Addition Severity	Possible values: Info, Warning, Error, None.
Deletion Severity	Possible values: Info, Warning, Error, None.
Change Severity	Possible values: Info, Warning, Error, None.
Record Format	Format of the record. Refer to Validation Script for more information.

Validation Script

During a refresh, if the module detects that the timestamp of a file has changed, the validation script associated with the file, if provided, will be executed. The exit code of the last execution will be displayed in Exit Code. When a new value is given to the script field, the module checks if the path given is a valid file. If it is not, the Exit Code field will display NO_SUCH_SCRIPT. (The field could also display "killed" in the event that the validation script running was killed. In this case, specify regular expressions on which to generate alarms for Exit Code.)

You can place your own scripts in /var/opt/SUNWsymon/SysMgmtPack/filewch/scripts or use the fileparse binary installed with the module.

If fileparse is specified, the module will ignore the parameters provided and will build the arguments from the delimiter, comment, and record format values known for the file.
If you specify a value such as
"fileparse -c 55 -d 556 -f "STRING*" -n /tmp/banana"
for example, all the parameters will be replaced by the ones built into the module, to make sure no unsupported comment or delimiter gets specified.
If you specify "mytest.sh -a myarg", the script executed will be the mytest.sh script, with -a myarg as argument.

Fileparse

The default list of files has a value set for Validation Script and Record Format. For example, for /etc/hosts:

Validation Script is set to fileparse
Record Format is set to IPADDRESS STRING STRING

fileparse is a C binary located in:
/var/opt/SUNWsymon/SysMgmtPack/filewch/scripts/
It accepts four arguments: delimiter, comment, record format, filename. Its usage is:
./fileparse -d index -c index -f record_format -n input_filename
The binary parses an input file against the file format specified as parameters, and reports an error if the file contents do not conform to the input file format. Blank lines and comment lines are skipped. The default comment is "NULL", which means there is no comment. The binary returns the following values:
0: Success;
1: cannot open file.
2: record_format is not correct. 
3: input_file's format is not correct.
-1: program error, such as not enough memory.
-2: argument error.

`/var/opt/SUNWsymon/SysMgmtPack/filewch/scripts/`

./fileparse -d index -c index -f record_format -n input_filename

0: Success; 1: cannot open file. 2: record_format is not correct. 3: input_file's format is not correct. -1: program error, such as not enough memory. -2: argument error.

Fileparse Arguments

fileparse accepts four parameters. The module will provide the correct values as arguments when fileparse is invoked.
%fileparse -d index -c index -f record_format -n input_filename
where

-d index Specifies the delimiter index;

-c index Specifies the comment index;

-f record_format Specifies grammar expression, where grammar expression support 4 kinds of operation on datatypes.
The datatypes supported are:
datatype = {STRING, INT, IPADDRESS, ZERO_STRING, CONST} 
where

STRING The string can not be empty.

ZERO_STRING The string can be empty or not empty.

CONST The field value must match.
A constant string can be declared by enclosing it in double quotes. For example:
"+" | "-" | STRING STRING 
Syntax of record format:
The operators available are:
operator = | , [], *
where

| Means "or". For example: - line-format = "+" | "-" | STRING STRING

[] Means optional. For example: - line-format = STRING [STRING|IPADDRESS]

* Means zero or multiple repetition of one datatype. For example: - line-format= IPADDRESS STRING STRING*
For example, the record format to validate /etc/passwd is:
STRING STRING INT INT ZERO_STRING STRING ZERO_STRING | "+" | "-"
The precedence of the operators is:
[] , | , * 

%fileparse -d index -c index -f record_format -n input_filename

-d index	Specifies the delimiter index;
-c index	Specifies the comment index;
-f record_format	Specifies grammar expression, where grammar expression support 4 kinds of operation on datatypes.

datatype = {STRING, INT, IPADDRESS, ZERO_STRING, CONST}

STRING	The string can not be empty.
ZERO_STRING	The string can be empty or not empty.
CONST	The field value must match.

"+" \| "-" \| STRING STRING

operator = \| , [], *

\|	Means "or". For example: - line-format = "+" \| "-" \| STRING STRING
[]	Means optional. For example: - line-format = STRING [STRING\|IPADDRESS]
*	Means zero or multiple repetition of one datatype. For example: - line-format= IPADDRESS STRING STRING*

STRING STRING INT INT ZERO_STRING STRING ZERO_STRING \| "+" \| "-"

[] , \| , *

Watched File Table Alarms

You can use the Attribute Editor to set a regular expression alarm threshold on Exit Code. There is no default alarm threshold.
If the file to be monitored does not exist, File Watcher generates an info alarm. However, it still adds the file to the Watched File Table but does not display any other information about this file.
If the file to be monitored (such as a directory) exists but cannot be opened, File Watcher adds it to the Watched File Table, however, it displays no other information on this file. It also generates an information (info) alarm in this case.

FIGURE 3-2 Handling of Erroneous File Names

File Change Table

The File Change Table monitors files and displays their record additions, deletions, or modifications.

Displayed Attributes

The File Change Table displays information about each file and provides the data on the following.

TABLE 3-3 File Change Table
Field
Description

File Name

Name of the file.

Line Number

The number of the line.

Index Key

Value found in the key field for the changed record.

Change Type

Whether one of the following occurred: addition, deletion, or change.

Field Changed

One of the following:
In case of an addition or a deletion, the cell displays "All."
In case of a change, the cell displays the column name, as specified when the "Watched File" entry was created.

Old Value

One of the following:
Since this pertains to an old value, in case of a new addition, the cell displays "NA."
If the hidden value flag for this file is set to TRUE, the cell displays "hidden."
The actual old value.

New Value

One of the following:
Since this pertains to a new value, in case of a deletion, the cell displays "NA."
If the hidden value flag for this file is set to TRUE, the cell displays "hidden."
The actual new value.

Time Changed

The time when the changes occurred.

**TABLE 3-3** File Change Table
Field	Description
File Name	Name of the file.
Line Number	The number of the line.
Index Key	Value found in the key field for the changed record.
Change Type	Whether one of the following occurred: addition, deletion, or change.
Field Changed	One of the following: In case of an addition or a deletion, the cell displays "All." In case of a change, the cell displays the column name, as specified when the "Watched File" entry was created.
Old Value	One of the following: Since this pertains to an old value, in case of a new addition, the cell displays "NA." If the hidden value flag for this file is set to TRUE, the cell displays "hidden." The actual old value.
New Value	One of the following: Since this pertains to a new value, in case of a deletion, the cell displays "NA." If the hidden value flag for this file is set to TRUE, the cell displays "hidden." The actual new value.
Time Changed	The time when the changes occurred.

File Change Table Alarms

When File Watcher detects a new event, it displays the event and generates the corresponding alarm that was specified when the file was added to the Watched File Table. File Watcher colors the File Name cell the color appropriate to the event value (info, warning, error, or none) you specified when you added the file to the Watch File Table.
When the probe function, "Dump all events to log," is invoked, the rule leaves the open state.

Available Commands

Commands are available at the following levels:

At the Watched File Table Level

To Add a New File to the List of Files to Be Monitored

Right-click over the header or any selected row in the table to access the pull-down menu commands.

FIGURE 3-3 Watched File Table Commands

Select Add Row.

Add a row to add a file.

Enter the following values to describe the format of the file to be monitored.

**TABLE 3-4** Watched File Table Entries
Field	Value to Enter
Name	Enter a meaningful name.
File Name	Enter the complete path to the file.
Delimiter	Enter the type of the delimiter.
File Comment Char	Enter the type of the character that delimits the comment line. The only possible values are: `tab`, `colon`, `semicolon`, `comma`, `hash`, and `pipe`. You can select the value from the pull-down menu in the Row Add or Row Edit windows.
Number of Fields	Enter the number of fields in each file entry.
Num Key Field	Enter the number of fields composing the key. The key is assumed to be at the beginning of the record.
Field names	Enter the meaningful names of the different columns in the file.
Hide values flag	Possible values are: FALSE = Display the value TRUE = Do not display the value. (This is used to prevent users with insufficient privileges from viewing information they should not have access to.)
Addition Severity	Info, Warning, Error, None.
Deletion Severity	Info, Warning, Error, None.
Change Severity	Info, Warning, Error, None.
Validation Script	It is the path to the validation script to be used to validate the file (for the row) when its timestamp changes.
Record Format	Format of the record (if `fileparse` is specified as the only required validation script).
Exit Code	The code to exit.

To Modify or Edit a Row

Select the row where the file name is present.

Right-click and select Edit Row.

Modify the path name and the definition of the record format of the file.

Click OK.

To Delete a Row

Select the row where the file name is present.

Right-click and select Delete Row.

Remove a file from the list of files to be monitored.

Note - If you remove a file from the list of files to be watched, the events that have already been detected for that file will not be automatically removed from the events log and will continue to be displayed in the File Changes Table. To clear the File Change Table, issue the Dump events to log command.

At the File Change Table Level

To Dump Events to a Log

Right click anywhere in the row.

FIGURE 3-4 File Change Table Properties

Select Dump events to log.

Delete the corresponding events by moving events.log to events_<timestamp>.log in the log directory.

The Probe Viewer then provides the location of the log file to which events.log was moved.

FIGURE 3-5 Output of the Probe Command