Chapter 3 File Watch

The File Watch module monitors a list of files for additions, deletions, and modifications.

This chapter discusses the following topics:

• File Watch Module Overview

• Accessing and Using the File Watch Module

File Watch Module Overview

The File Watch module can only monitor files that have a one record per line format. If changes to monitored files are detected, the module builds events and displays them in a table. The module 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. You must specify the file-specific severities of the alarms to be generated in the following cases:

• A record addition event

• A record deletion event

• A record modification event

Use the File Watch module to monitor only system files that are not expected to change frequently, for example, the passwd file. This approach ensures that the change notifications are as useful as possible.

The following File Watch tables are displayed in the module:

• Watched File Table

• File Change Table

If the file to be monitored, such as a directory, exists but cannot be opened, the file is added to the Watched File Table. No other information about this file is displayed. An information alarm is generated.

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.

The module uses a validation script to validate the file when its timestamp changes. You can use the fileparse binary included with the module or create your own validation script.

This module provides a way to enable or disable the event monitoring mode for a particular file. This concept is similar to the idea of enabling or disabling a pattern matching search in the file scan module. For example, if you disable the /etc/passwd file and an entry is added to this file, no corresponding event detection appears in the bottom table. The entry will not appear until the /etc/passwd monitoring state is enabled again.

Watched File Table

The Watched File Table lists all the files being monitored by the module. This table 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 Hidden File Attributes.

File changes can only be noticed once the file has been detected as existing. If a file does not exist or is nonexistent, the module detects that the file does exist with a size bigger than 0. For example, if a file has two records, the module is not able to notice those two records. However, the module notices all future modifications.

This table is initialized with the following seven system files:

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

Displayed File Attributes

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

Table 3–1 Watched File Table

Field	Description
File	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	The path to the validation script used to validate the file when its timestamp changes. Save the script in /var/opt/SUNWsymon/ SysMgmtPack/filewch/scripts and provide a relative path. The value for script is optional. For more information, see Validation Script.
Exit Code	Displays the exit code of the last execution of the validation script.
Event Monitoring	Displays the state of the file watch mode for each file. For more information, see To Disable Event Monitoring.

Hidden File Attributes

The following is a list of attributes that are hidden, and that are accessible from the Row Editor window. To open this window, press mouse button 3 on any row and choose Edit Row from the pop-up menu.

Table 3–2 Hidden File Attributes

Field	Description
Delimiter	Delimiter between columns.
Comment char	Type of the character 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. The key 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 changed values
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 Record Format for more information.

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 Watch generates an information alarm. However, the module 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, the file is added to the Watched File Table. No other information about this file is displayed.

File Change Table

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

The File Change Table provides the data on the attributes listed in the following table.

Table 3–3 File Change Table

Field	Description
File	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	Indicates whether one of the following actions occurred: addition, deletion, or change.
Field Changed	One of the following values are possible:  For an addition or a deletion, the cell displays All. For a change, the cell displays the column name, as specified when the Watched File entry was created.
Old Value	One of the following values are possible:  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 are possible:  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 Watch detects a new event, the event is displayed and the corresponding alarm is generated. The color of the File Name cell changes to the event-value appropriate color you specified when the file was added to the Watch File Table. The event options are info, warning, error, or none.

Record Format

When you add a new file to the list of files to be monitored by the module, you must provide a value for the record format attribute. This attribute defines the format of the file being monitored. This value is needed if the fileparse binary is specified as the only required validation script. The fileparse binary checks the record format as part of the validation performed on the file. The record format is a hidden attribute of the file entry in the Watched File table. You will not see this attribute displayed once it is defined, unless you choose to edit the file's entry. For more information, see Validation Script.

The following list describes supported datatypes for record_format:

datatype = {STRING, INT, IPADDRESS, ZERO_STRING, RANGE_INT, 
CHOICE_INT, CHOICE_STRING CONST}

where

STRING

The string cannot be empty

ZERO_STRING

The string can be empty or not empty

RANGE_INT

The integer must match one of the strings specified

CHOICE_INT

The integer must match one of the integers specified

CHOICE_STRING

The string must match one of the strings specified

CONST

The field value must match

The grammar also supports the following values:

• Ranges for numbers, such as RANGE_INT (1...9)

• A list of possible values for numbers and strings, such as:

  • CHOICE_INT (0|1)

  • CHOICE_STRING (true|false)

---

Note –

The character “|” is not allowed in the choice list of strings. These strings can only be embedded in double quotes if they appear within double quotes in the monitored file. INT values can only be positive values. Negative values for INT are not supported.

---

A constant string can be declared by enclosing it in double quotes, as shown in the following example:

 "+" | "-" | STRING STRING 

The available operators are as follows:

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*

The following example shows the record format to validate /etc/passwd:

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

The precedence of the operators is as follows:

[] , | , * 

Validation Script

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

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

• If fileparse is specified, the module ignores the parameters provided. The arguments are built from the delimiter, comment, and record format values that are known for the file. If you specify a value, all the parameters are replaced by the ones built into the module. This behavior ensures that no unsupported comment or unsupported delimiter is specified.

• If, for example, you specify mytest.sh -a myarg, the mytest.sh script will be executed, with -a myarg as argument.

fileparse Binary

fileparse is a C binary located in /var/opt/SUNWsymon/SysMgmtPack/filewch/scripts/.

The default list of script files has a value set for Validation Script and Record Format. For example, for /etc/hosts, the values are set as follows:

• Validation Script is set to fileparse

• Record Format is set to IPADDRESS STRING STRING

The binary parses filename against the record_format specified in the file definition contained in the Watched File table. Errors are reported if the file contents do not conform to the input file record_format. Blank lines and comment lines are skipped. The binary returns the following values:

0

Success

1

Cannot open file

2

record_format is not correct

3

file format is not correct

–1

program error, such as not enough memory

–2

argument error

Accessing and Using the File Watch Module

This section describes how to access and use the File Watch module.

To Access the File Watch Module

1. Load the File Watch module.

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

2. In the Navigator window, double-click Local Applications.

   The category expands.

3. Double-click File Watch.

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

4. Access the File Watch tables using one of the following methods:

   • Double-click the File Watch option.

   • In the Viewer window, double-click the File Watch icon.

   The Watched File Table and the File Change Table are displayed in the right pane.

   

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

1. If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.

2. Press mouse button 3 on the header or any selected row in the Watched File table.

   A pop-up menu is displayed.

3. Choose New Row.

   This command adds a file.

4. Provide the following attribute values to describe the format of the file to be monitored.

   Table 3–4 Watched File Table Attributes

   Field	Description
   Name	Name of the file.
   File Name	Complete path to the file.
   Delimiter	Type of the delimiter.
   File Comment Char	Type of the character that delimits the comment line. The only possible values are tab, colon, semicolon, comma, hash, and pipe.
   Number of Fields	The number of fields in each file entry.
   Num Key Field	The number of fields composing the key. The key is assumed to be at the beginning of the record.
   Field Names	Meaningful names for the different columns in the file.
   Hide values flag	The following values are possible:  FALSE = Display the value. TRUE = Do not display the value. This setting is used to prevent users with insufficient privileges from viewing information.
   Addition Severity	Info, Warning, Error, None
   Deletion Severity	Info Warning, Error, None
   Change Severity	Info, Warning, Error, None
   Validation Script	The path to the validation script to be used to validate the file.
   Record Format	Format of the record, if fileparse is specified as the only required validation script.
   Exit Code	The number returned by a script when the script finishes.
   Event Monitoring	The state of the file watch mode for the file. The following values are possible: On = event monitoring is enabled. Off = event monitoring is disabled.

To Modify or Edit File Information

1. If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.

2. Press mouse button 3 on the row displaying the file name.

   A pop-up menu is displayed.

3. Choose Edit Row from the pop-up menu.

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

5. Click OK.

To Remove a File From Being Monitored

If you do not want to monitor a file, you must remove the file from the list of files to be monitored.

1. If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.

2. Press mouse button 3 on the row displaying the file name.

   A pop-up menu is displayed.

3. Choose Delete Row from the pop-up menu.

   This option removes the file from the list of files to be monitored.

   ---

   Note –

   When a file is removed from the list of watched files, the events previously detected for that file are not automatically removed from the events log. These events continue to be displayed in the File Changes Table. To find out how to clear the File Change Table, see To Dump Events to a Log.

   ---

To Disable Event Monitoring

The state of event monitoring is shown in the final column of the Watched File Table. The on value indicates that event monitoring is enabled. The off value indicates that event monitoring is disabled. You can also use the Manage Jobs feature of Sun Management Center 3.5 to create a data property task to set the Event Monitoring node to on or off. Trying to set the node to a value other than on or off results in the task failing.

1. If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.

2. From the table column titled Event Monitoring, click the corresponding table cell.

   Use the scroll bar located at the bottom of the window to view the Event Monitoring column, if needed.

   The table cell becomes a drop-down menu displaying the options on and off.

3. Select on to enable event monitoring or off to disable it.

   An Alert dialog box appears asking you to confirm the change.

4. Click OK to confirm.

   The state of event monitoring for the file is changed.

To Dump Events to a Log

The File Change Table is cleared when events are dumped to a log file.

1. If the File Change Table is not already displayed, display it as described in To Access the File Watch Module.

2. Press mouse button 3 anywhere in the row that displays the file name whose events you want to clear.

   A pop-up menu is displayed.

3. Choose Dump events to log.

   The events are saved to the events_timestamp.log file in the log directory. The Probe Viewer then provides the location of the log file.