The File Watch module monitors a list of files for additions, deletions, and modifications.
This chapter discusses the following topics:
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.
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
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. |
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. |
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:
|
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. |
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.
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
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.
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 data types for record_format:
datatype = {STRING, INT, IPADDRESS, ZERO_STRING, RANGE_INT, CHOICE_INT, CHOICE_STRING CONST}
where
The string cannot be empty
The string can be empty or not empty
The integer must match one of the strings specified
The integer must match one of the integers specified
The string must match one of the strings specified
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)
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 data type. 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:
[] , | , *
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 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:
Success
Cannot open file
record_format is not correct
file format is not correct
program error, such as not enough memory
argument error
This section describes how to access and use the File Watch module.
Load the File Watch module.
For instructions on how to load a module, refer to the Sun Management Center 3.6 User’s Guide.
In the Navigator window, double-click Local Applications.
The category expands.
Double-click File Watch.
The Viewer displays the File Watch icon in the Viewer window.
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.
If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.
Press mouse button 3 on the header or any selected row in the Watched File table.
A pop-up menu is displayed.
Choose New Row.
This command adds a file.
Provide the following attribute values to describe the format of the file to be monitored.
If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.
Press mouse button 3 on the row displaying the file name.
A pop-up menu is displayed.
Choose Edit Row from the pop-up menu.
Modify the path name and the definition of the record format of the file.
Click OK.
If you do not want to monitor a file, you must remove the file from the list of files to be monitored.
If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.
Press mouse button 3 on the row displaying the file name.
A pop-up menu is displayed.
Choose Delete Row from the pop-up menu.
This option removes the file from the list of files to be monitored.
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.
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.6 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.
If the Watched File Table is not already displayed, display it as described in To Access the File Watch Module.
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.
Select on to enable event monitoring or off to disable it.
An Alert dialog box appears asking you to confirm the change.
Click OK to confirm.
The state of event monitoring for the file is changed.
The File Change Table is cleared when events are dumped to a log file.
If the File Change Table is not already displayed, display it as described in To Access the File Watch Module.
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.
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.