fix_hist utility
Problems with the history database sometimes develop through undesirable incidents such as an abrupt shut down of the PATROL Agent. In these cases, one or more pointers in the .dir file could lead to erroneous data in the other two files. Corrupted history can cause the agent to consume excessive amounts of CPU and memory.
The PATROL Agent provides two ways for you to correct problems with the history database:
- Run the
fix_histcommand-line utility Set the /AgentSetup/fixHistFlag configuration variable to automatically run commands when the agent restarts
For more information, see the following topics:
Overview of the fix_hist utility
The fix_hist command tries to solve these problems by removing the errant pointers and packing the related files: dir, annotate.dat, and param.hist. Often you will find out that your history database has these problems when you see an error message similar to the following: Found inconsistency in hist param database.
Note
On Microsoft Windows operating systems, the history index file has a file size limit of 2 GB.
Once such a problem is discovered, you might want to perform one of the following actions:
- Shut down the PATROL Agent and run the fix_hist utility, and remove any history you no longer need by selecting Options > Clear History from the parameter list screen.
- Shut down the PATROL Agent and move the annotate.dat, dir, and param.hist files.
Be sure to move or delete all three files. When the agent is restarted, it creates new versions of these files.
The -force_history_cleanup<days> option is available in versions 3.5.30 and later of fix_hist (available for PATROL for UNIX 9.0.00 and later and PATROL for Microsoft Windows Servers 3.0.01 and later). The -force_history_cleanup option deletes anything older than the number of days specified. This option is used to trim the history files.
The syntax for the option is as follows:
$ fix_hist -force_history_cleanup = <last number of days of parameter history to keep>Warning
BMC recommends archiving history files before you use this feature. The number of days that the parameter history is retained is relative to the time at which the fix_hist -force_history_cleanup command is issued. You cannot delete selective parts of the history file or manually add data to the history files.
Output
While reading the annotation database, the fix_hist utility creates a file. When the utility encounters an error that it cannot repair, it saves the data that it has already read and discards the data that is unreachable due to a corrupted pointer or other error.
The fix history utility backs up the history database files that it attempts to repair by appending "~#~" to each file, for example param.hist.~3~. The utility then writes the recovered information to the history database files, for example param.hist.
Overview of the fixHistFlag configuration variable
The /AgentSetup/fixHistFlag variable automatically runs commands when the agent restarts to back up and repair history files.
Format and type of data | text string (comma-separated list) always — attempts repair, packing or both |
Default value | None |
Minimum and maximum | Not applicable |
Dependencies | None |
Recommendation | None |
For more information about changing configuration variables, see Using wpconfig (Windows) to configure the BMC PATROL Agent and Overview of the xpconfig configuration utility.
With PATROL Agent version 3.5.30 or later, the /AgentSetup/fixHistFlag Agent configuration variable is used to fix the history files when the agent starts up.
The /AgentSetup/fixHistFlag variable can have one of the following values:
Values for the /AgentSetup/fixHistFlag variable
Option | Description |
|---|---|
always | Attempts to repair, pack, or both; always run fix_hist |
dirtybit | Attempts to repair, pack, or both when the history database indicates that the database may have been left in an unknown or incomplete state; run fix_hist only when the history was not closed properly during the previous agent was shut down |
no_repair_hist | Do not repair history |
no_pack_hist_index | Do not pack history index files |
nopackann | Do not pack annotation file |
nobackup | Do not back up history file |
repair_cycle=<number> | Specifies the maximum number of repair cycles |
force_history_cleanup=<days> | Specifies the number of days you want to retain the parameter history |
Note
If the /AgentSetup/fixHistFlag variable is not defined, the default of never is used.
File and directory structure used by fix_hist
PATROL creates and maintains a standard file and directory structure in which it stores the history database. The fix_hist utility will not run if the proper file and directory structure do not exist.
Directory structure used by the fix history utility
The following table lists the directories for fix_hist:
Directories for fix_hist
| UNIX directory | Definition |
|---|---|
| Windows directory | |
| PATROL_HOME | Directory specified when the PATROL Agent is started |
| PATROL_HOME | |
| PATROL_HOME\log | Log directory for the PATROL Agent |
| PATROL_HOME\log | |
| PATROL_HOME/log/history | Top directory of the parameter history databases contains top directories of each PATROL Agent |
| PATROL_HOME\log\history | |
| PATROL_HOME/log/history/<hostName> | A PATROL Agent's top directory of the parameter history database. Created by the PATROL Agent using the official host name on which it is running |
| PATROL_HOME\log\history\<hostName> | |
| PATROL_HOME/log/history/<hostName>/<port_num> | The directory where a single PATROL Agent stores files when multiple PATROL Agents are running on the same host created by the PATROL Agent using its port number |
| PATROL_HOME\log\history\<hostName>\<port_num> |
Files read by the fix history utility
The following table shows which files are read by the fix_hist utility:
Files read by fix_hist
| File description | File name and path for UNIX |
|---|---|
| File name and path for Windows | |
| Index file | PATROL_HOME/log/history/<hostName>/<port_num>/dir |
| PATROL_HOME\log\history\<hostName>\<port_num>\dir | |
| History text file | PATROL_HOME/log/history/<hostName>/<port_num>/param.hist |
| PATROL_HOME\log\history\<hostName>\<port_num>\param.hist | |
| History data file | PATROL_HOME/log/history/<hostName>/<port_num>/annotate.dat |
| PATROL_HOME\log\history\<hostName>\<port_num>\annotate.dat |
Relocating files
Moving these files will not prevent you from viewing them. The dump_hist utility can be used to view the old history data.
To reuse the old history data, perform the following steps:
- Create the directory PATROL_HOME/log/history/<hostName>/<new_port> on UNIX or PATROL_HOME\log\history\<hostName>\<new_port> on Windows.
- Move the files in the dir, annotate.dat, and param.hist files to the new directory. (The files must be named dir, annotate.dat, and param.hist.)
- To view the data, type the following command and press Enter:
dump_hist -pnew_port
Before running the fix_hist utility
The PATROL environment must be set up prior to running fix_hist. You must set the PATROL_HOME environment variable. Before running the dump_hist utility describes how to define this variable for UNIX and Windows.
Running the fix_hist utility
Running the fix_hist command could require shutting down the agent for a considerable amount of time. The length of the down time is directly related to the size of dir, annotate.dat, and param.hist. If these files are very large or any down time for the agent is undesirable, consider clearing unneeded history or moving the files instead of running the fix_hist utility. Some options for the fix_hist command may reduce its run time. See Options for fix_hist utility.
Warning
The fix_hist utility requires disk space while it is running. If you have limited disk space on your computer, it is possible to run out of space. Running out of disk space can cause all PATROL files to be inaccessible or it can cause other applications to crash.
To run fix_hist
- Stop the PATROL Agent.
- For Windows, set the variable called
%PATROL_HOME%. For UNIX, run one of the following scripts from the PATROL installation directory:. ./patrolrc.sh(for Korn and Bourne shell)source.patrolrc(for C shell)
- At the command line, run fix_hist and monitor the output.
- Issue the following command to get the return code of the process:
$ echo $?
See Return values for fix_hist utility for more information about return values. - Repeat step 3 and step 4 until no more errors are reported or until you determine that the history files cannot be fixed.
Return values for fix_hist utility
The fix_hist utility exits with one of the following values:
- 0 — fix_hist completed successfully
- 1 — fix_hist was aborted because of an error
Syntax for fix_hist utility
The fix_hist utility has the following format:
|
|
Options for fix_hist utility
The following table lists and defines the options recognized by the fix_hist utility:
Options recognized by the fix_hist utility
Option | Definition |
|---|---|
-force | This option tells fix_hist or the PATROL Agent process to ignore an invalid lock and start anyway. An invalid lock occurs when fix_hist or PATROL Agent incorrectly detects a conflicting process is running for the same host and port. |
-force_history_cleanup <days> | This option specifies the last number of days for which you want to keep the parameter history. |
-host | This option specifies which PATROL Agent's history database is used. By default, the name of the host on which fix_hist is started is used. |
-no_repair_hist | This option stops this command from repairing the history. This option is useful if you only want to pack the data and index files. |
-no_pack_hist_index | This option specifies that the history index file is to be left unpacked. |
-no_pack_ann | This option specifies that the annotation file is to be left unpacked. |
-no_backup | This option prevents the history files from being backed up before the command starts. |
-p | This option specifies which PATROL Agent's history database is used. Combined with the -host option, -p specifies a unique PATROL Agent. The value of this option must be the port number to which the specified PATROL Agent is listening. The default value is 3181. |
-repair_cycle | This option specifies the maximum number of times to scan the history data while repairing it. |
-v | This option displays version information. |
Examples of the fix_hist utility
The following examples illustrate how to use the fix history utility.
To repair history for an agent on a specific port
The following command fixes history and packs the data and index files at port 5000:
fix_hist -p 5000To scan the history database a maximum of two times
The following command fixes history and packs the data and index files for host host1 at port 3181. It will scan the history file a maximum of two times.
fix_hist -host host1 -p 3181 -repair_cycle 2To repair history database without packing index files
The following command fixes history for host host1 at port 3181. The history index file is not packed.
fix_hist -host host1 -p 3181 -no_pack_hist_indexTo pack index files without repairing history database
The following command packs the files for host host1 at port 3181. The history files are not scanned and fixed.
fix_hist -host host1 -p 3181 -no_repair_hist
Comments
Log in or register to comment.