Running the offline database cleanup utility

To perform offline database cleanup, you can choose between running the Offline Cleanup utility through the GUI or through a command line interface (CLI).

Important

After running the offline cleanup utility, do not directly access the Health Dashboard. First, run the online database cleanup utility and access the dashboard. For more information, see Using-the-Health-and-Value-dashboards.

Before you begin

For a list of preparatory tasks that you might need to perform before performing offline database cleanup, see Preparing-for-offline-database-cleanup. Most importantly, back up your database before you begin the cleanup.

Important

Do not execute any offline database cleanup-related CLI command when a GUI-based offline database cleanup is already running. You can run offline database cleanup either through GUI or CLI at one time.

To run offline cleanup through the GUI

Log on to the Application Server that you plan to run the offline database cleanup utility (ensure that you have the required permissions to access the Database Maintenance Wizard).
To start the Database Maintenance Wizard navigate to the location where the executable file is located. The path and file name for Microsoft Windows and Linux are listed in the table below:
Platform
Path
Executable File
Microsoft Windows
C:\Program Files\BMC Software\BladeLogic\NSH\br\dbm-rcp
dbm.exe
Linux and UNIX
/opt/bmc/bladelogic/NSH/br/dbm-rcp
dbm
Note
If the wizard is launched through a third-party utility, such as Exceed, the screen resolution should be set to 1024*768.
Before you proceed to the Settings pane, ensure that all Application Servers connected to the database are shut down and no ETL processes are running.
On the Settings pane, perform the following configuration steps:
Note
A link above the list of retention periods ("Click here to get the approximate cleanup percentages") enables you to evaluate the impact of the database cleanup process (that is, how much data would be deleted from the database) for different retention periods when applied to the various modules. This option opens a secondary dialog box that is similar to the report returned by the dbm_cli.nsh script when run with the -eval option. The displayed data can help you decide on appropriate retention periods for the various modules. Audit Trail and Job Run Event modules are not evaluated for cleanup percentages.
1. Select the modules for which you want to run the cleanup utility. If the modules selected have a dependency on Job Run Event, Job Run Event is selected by default.
  Tip
  To speed up this step, use the Select All and Clear All buttons.
  The Last Run Date and Last Run Status columns contain information about the most recent time when each of the modules was cleaned up. This information can help you decide on the modules that you want to include in the cleanup.
  The BL Value module is applicable for Oracle databases, and it is available only when you run the offline cleanup utility through the GUI.
2. Select the retention period for your data (in days). Data older than the specified retention period will be purged. The retention period can be set to a maximum of 9999 days and a minimum of 3 days. Default retention period for Job Run Event and Audit Trail is 14 days and for all other modules it is 90 days. The retention period is applied to all Job Result data irrespective of the existing retention policy set at the individual job level.
  Tip
  To set retention periods for all modules to default values, click the Reset Default Retention Period button.
  Important
  To maximize the effectiveness of the offline database cleanup, BMC recommends you to select all modules while running the clean up.
  In some case running an offline clean up on the Snapshot and Audit modules can prevent BLFILE related errors during the clean up.
3. If you want to set a maximum length of time for the cleanup process to run, select the Configure Database Maintenance Execution Duration check box, and then set a duration in minutes.
  The range is 60 minutes to 1440 minutes (1 hour to 24 hours). If this duration is not defined, the process will continue until completion or until it is stopped.
  Note
  After completion of the specified duration, the maintenance process will end only after it has reached an appropriate stage in its execution. This is done to prevent data inconsistency and it might take a while for the process to stop.
After the Database Maintenance process has started, you can see the progress of each module and its status on the Database Maintenance pane.
Note
The Database Maintenance process is not run for the modules that were already cleaned up during the last 180 days.
You can pause the offline database cleanup process by clicking the Stop button. However, the system only halts the process at a stage from where it can recover without any loss or corruption of data.
Note
After pausing the cleanup process on an Oracle database, ensure that database statistics are updated before resuming the process at any later time.
When the Database Maintenance Wizard is in the Halted state, you can do either of the following:
- Click Restart to continue the clean up process from where it was halted.
  Note
  The wizard will perform the following actions if the process is restarted:
  - It will rerun the Database Maintenance process for modules that were completed before a period of 180 days.
  - It will rerun the Database Maintenance process for modules that were run unsuccessfully.
- Click Finish to end the clean up process and exit the wizard. You can restart the wizard to continue the clean up activities at a later time.
On the Summary pane of the wizard, review the list of modules and their statuses.
To exit the wizard, click Finish.
Note
You can find a detailed log report of the Database Maintenance process in the run_log.csv file, which is stored in the following location:
<Path to BladeLogic>/NSH/br/dbm-rcp/run_log.log

Platform	Path	Executable File
Microsoft Windows	C:\Program Files\BMC Software\BladeLogic\NSH\br\dbm-rcp	dbm.exe
Linux and UNIX	/opt/bmc/bladelogic/NSH/br/dbm-rcp	dbm

Info

TrueSight Server Automation

supports only English messages on the Database Maintenance Wizard.

To run offline cleanup through a command line

Through the command line, run the dbm_cli.nsh script file with the following command options:

Warning

Due to a known issue (QM002216872), customers running a version of BMC Server Automation prior to 8.9.01, should not run the offline DB cleanup (DBM) using the dbm_cli.nsh command line tool. Doing so can result in unexpected purging of data. Customers running a version of BMC Server Automation prior to 8.9.01, should instead use the GUI version of the offline DB Cleanup (DBM) tool (dbm.exe or dbm.nsh), which is not affected by this issue.

Customers running BMC Server Automation 8.9.01 or later, can use either the command line or GUI version of the DBM tool.

Option	Description
-run <module>=<retention>	Run the offline cleanup process on the specified modules and remove all data older than the specified retention period (in days). To specify multiple modules, separate module=retention definitions with colons. The following modules are available. Most of these modules are based on types of TrueSight Server Automation jobs: All (that is, all other modules) JRE Audit_Trail Snapshot (Snapshot cleanup requires some additional considerations. For details, see Cleanup-considerations-for-snapshot.) Compliance NSH Patching Deploy Audit Important The BLValue module is only accessible through the GUI. The JRE module must accompany most of the other modules. Only the Audit_Trail module does not require specification of the JRE module. In addition, the All module already includes the JRE module and does not require its explicit specification. The retention period can be set to a maximum of 9999 days and a minimum of 3 days. This retention period is applied to all Job Result data for the specific job type, and it overrides any existing retention policies defined at the individual job level. Example:./dbm_cli.nsh -run Snapshot=45:Audit=30:JRE=20 -dur 120 Note: Retention periods specified for the JRE and Audit Trail modules take precedence over retention periods specified for other modules. As a result, the cleanup process deletes JRE and Audit Trail details for jobs even if the retention period for the specific job type is longer than the retention period defined for the JRE and Audit Trail modules. Important: To maximize the effectiveness of the offline database cleanup, BMC recommends you to select all modules to run the offline clean up. In some case running an offline clean up on the Snapshot and Audit modules can prevent BLFILE related errors during the clean up.
-dur <minutes>	Specify the duration (in minutes) for which the database cleanup process will run. Value range: 60 – 1440 minutes. This option is used in combination with the -run option.
-force (only for BSA 8.9.01 and later)	Forces database cleanup even if deletable data is under 30% of the total data for a specific module. This option is used in combination with the -run option. Warning: Do not use this option if you are on BSA 8.9.00 or any other earlier version. Using this option in BSA 8.9.00 or any other earlier version will cause unexpected purging of data.
-stop	Stops the current run of the database cleanup process. Example:./dbm_cli.nsh -stop
-state	Provides the current state of the database cleanup process along with useful information about the cleanup and the state of the database. Example:./dbm_cli.nsh -state
-eval	Provides an evaluation of the impact of the database cleanup process (that is, how much data would be deleted from the database) for different retention periods when applied to the various modules. For more information about this option, see its description in Preparing for offline database cleanup. Example:./dbm_cli.nsh -eval Note: Before using the -eval option on an Oracle database, gather stats from the Oracle database: Connect as DBAdmin to the TrueSight Server Automation database. Execute the following command in SQL Plus:exec dbms_stats.gather_schema_stats(ownname=>'db_user_name');
-impact <module>=<retention>	Lists the impacted Jobs of the specified module whose runs will be deleted based on the specified retention period. You can use this option with the following modules: Snapshot, Compliance, NSH, Deploy, Patching, and Audit. For more information about this option, see its description in Preparing for offline database cleanup. Example:./dbm_cli.nsh -impact Snapshot=45
-logs	Exports the logs generated during the database cleanup process. Example:./dbm_cli.nsh -logs

Note

After you enter a -run command, you receive a message that database cleanup has started, but no further progress messages are issued afterwards during cleanup.

While the database cleanup operation is running (that is, after entering the -run command), it is recommended that you do not run any parallel operations (that is, any additional -run command or any -eval, -impact, or -logs operation). If you specified a maximum duration for the cleanup operation using the -dur option, simply wait until the end of that time period; otherwise, check whether the cleanup operation has completed before running any further operation through the command line.

The retention scenarios calculated by the -eval option are based on statistics from job run data. To save time when you run an evaluation, statistics are refreshed only if the most recent calculation was performed more than 15 days ago. Therefore, if you run an evaluation within 15 days after a previous evaluation, during a period of normal (or heavy) usage of TrueSight Server Automation, evaluation results might not be fully accurate. For more accurate estimates, ensure that you run your evaluation more than 15 days since the last evaluation was run.

Where to go from here

For tasks that you need to perform after completing the offline database cleanup process, see Post-cleanup-activities.