Configuring parameters in the script-based cleanup job
Before you run your script-based cleanup job — the out-of-the-box BSA Recommended Database Cleanup Job or any other cleanup job that you created based on it — you might need to adjust the parameters that are inherited from the out-of-the-box cleanup script (BSA Recommended Database Cleanup Script, stored in the BMC Maintenance folder in the depot).
To configure the parameters, navigate to the cleanup job in the Jobs folder (for example, the out-of-the-box cleanup job is BMC Maintenance > BSA Recommended Database Cleanup Job), and open it. Then, in the job editor of this Network Shell Script Job, select the Parameters tab.
The Parameters panel lets you configure parameters that are replaced with server property values when the job runs. Using this panel, you can perform the following actions:
|Flag runtime usage|
Choose whether each of the defined parameter flags should be used or ignored.
Specify a value for each of the parameters.
|Value runtime usage|
Choose whether the value specified for each optional parameter should be used or ignored (that is, not taken into account).
The following sections further discuss the parameters that are used specifically in cleanup jobs:
Cleanup script parameters
The following figure shows the parameters in cleanup jobs, as inherited from the underlying NSH script. These parameters are not case-sensitive. The following table describes the parameters.
|Sets the Execution mode for the cleanup script. There are two options: Typical mode and individual command mode.|
With the Typical mode, the job executes a series of recommended delete commands. The cleanup script executes the following commands in the order listed below:
|You can also choose to execute an individual delete command. Enter one of the values shown in Supported execution modes to execute an individual delete command. This option is useful if you want to cleanup a specific type of data, such as agent logs.|
|Specifies if the script is to keep processing if it runs into errors. By default, the NSH Script uses |
|Specifies the overall maximum run-time for the script. If this maximum time is reached, the job performs a clean exit, even if cleanup has not completetd. By default, the NSH Script uses an overall maximum run-time of 720 minutes. You can change the overall maximum duration default value. For further points to consider when you set the duration value, see Further discussion of duration.|
Distributes the run-time (as set by the
These are the recommended settings for the script. BMC recommends that you do not change these settings. However, if you are very familiar with the landscape of the objects in the database that you want to delete, then you might want to adjust the settings. To adjust the settings, enter the settings in quotes, as shown below:
Specifies the number of days that must be exceeded for the script to delete the specified data. This parameter is used by the following execution modes:
It is used by the following BLCLI commands:
The default value is 14 days. The minimum allowed value is 3 days.
Deletes a specific type of object. To use this parameter, you must be using an execution mode of
NEW IN 8.9.02
NEW IN 8.9.02
|Deletes objects from the database that were created by a specific role.|
|Lists the device names which have an Application Server cache or a repeater. The execution modes |
|Specifies the maximum size, in MB, for the repeater staging directory.|
Supported execution modes for individual commands
The following table lists all the execution modes (besides TYPICAL) that are supported for use by the cleanup script, as well as the BLCLI commands that each of these modes runs.
|Mode value||Command executed||What it does|
Cleans up BMC Server Automation historical data based on retention time.
Cleans up BMC Server Automation historical data for the specified
Cleans up BMC Server Automation objects for
Cleans up BMC Server Automation historical data for objects of the specified
|Marks entries for deletion based on retention time in the BMC Server Automation database. It marks old job runs and automatically created jobs and depot objects.|
Deletes database rows for objects that have been previously marked for deletion.
Note: Certain objects are not deleted due to potential object dependencies. The cleanup process deletes all top-level model objects of the classes listed in the hk_allowed_classes database table, as well as all their child classes (which are not listed in this table). BMC recommends that you do NOT modify the contents of the hk_allowed_classes table.
|Performs a BMC Server Automation Database cleanup with the duration limitation specified in the |
|Deletes database rows for shared data objects with the duration limitation specified in |
Cleans all the unused files from the file server and from temporary file storage on the Application Server.
You typically use the file server cleanup after running a database cleanup. In this way, you first remove objects from the database, and then you remove the actual underlying file system objects from the file server. Before running the file server cleanup, ensure that the database cleanup has completed.
When a Custom Package Deploy Job runs, it creates a subdirectory under the BLPackage directory for every iteration. Even after the job run history is removed by the retention policy, these directories still exist. These directories are not removed by the cleanup script.
|Performs a FileServer cleanup with the duration limitation specified in the |
Performs a FileServer integrity check.
Note that this mode is NOT included in Typical mode. If you want to check the integrity of the file server, you must run this mode separately.
Deletes all objects marked for deletion and cleans all unused files from the file server and the temporary file storage area on the Application Server.
Note that this mode is NOT included in Typical mode, and is run separately.
Cleans up old temporary files on a target server (agent) that are older than the
Click here for more information about these directories...
The Transactions directory is either rscdInstallDirectory/Transactions or as specified by the server's TRANSACTIONS_DIR property (see Configuring the location of the transactions directory). Within the Transactions directory, the contents of the following directories are not touched during cleanup: mnt, locks, database, events, and logs.
The Staging directory is specified by the server's STAGING_DIR property.
Note that this mode is NOT included in Typical mode. To clean up your agents, you must remember to schedule a separate job with this mode. The standard recommended frequency for this cleanup is once a month. For best results, keep agent cleanup separate from database cleanup (for example, do not include these two types of cleanup jobs in one batch job).
Deletes old temporary files on all the Application Servers that are currently up and running (and accessible). It removes files older than the
Note that this mode is NOT included in Typical mode. To clean up your Application Servers, you must remember to schedule a separate job with this mode. For example, in the example of a standard weekly cleanup plan Application Server cleanup is planned to run on a monthly basis, and in the example cleanup plan for large operational environments Application Server cleanup is planned to run on a daily basis.
Deletes old temporary files on a specific Application Server (any files older than the
Note that this mode is NOT included in Typical mode. If you want to clean up a specific Application Server, you must run this mode separately.
Cleans up files from the staging directory of a repeater server. This cleanup removes files that have not been accessed for the
This command does not delete the lost and found directory.
Note that this mode is NOT included in Typical mode. To clean up the repeater server, you must remember to schedule a separate job with this mode. The standard recommended frequency for this cleanup is once a month. For best results, keep the cleanup of the repeater server separate from database cleanup (for example, do not include these two types of cleanup jobs in one batch job).
Further discussion of duration
When setting the maximum duration value, take the following points into consideration:
- Deletion of objects is done in batches, to allow other transactions to run in the database while cleanups are running. The size of these batches is controlled by a blasadmin setting from the
MaxObjectsPurgedPerTransaction. The default value of this blasadmin setting is 1000. This value refers only to top-level objects, so the actual number of objects that are deleted in each batch (when taking into account all child objects) might be much higher. For example, when deleting job data, a single job (top-level object) could have thousands of job run event entries (child objects). In a large and busy environment, you might want to reduce the value of this setting from the default 1000 to a lower value (even as low as 100 top-level objects).
- Maximum duration is checked between the batches of deletion controlled by the
MaxObjectsPurgedPerTransactionsetting. As a result, in large and busy environments (when, for example, a batch of job runs with millions of database rows is being deleted), the script job might run for a longer time than the maximum duration value that you set (until it completes the deletion of the current batch of objects). By reducing the transaction size (that is, the
MaxObjectsPurgedPerTransactionsetting), you can bring the actual duration closer to the value set by the maximum duration setting.
- Do not use job-level timeout properties to define maximum duration. In other words, ensure that the JOB_PART_TIMEOUT and JOB_TIMEOUT properties of your cleanup job (whether an NSH Script Job or a Batch Job that contains several NSH Script Jobs) are set to 0. Otherwise, when a job-level timeout is reached, the script job stops running, but the underlying BLCLI commands might not all stop properly.
Therefore, to properly set the maximum duration, use the MaxDuration parameter from the NSH Script Job (as described here) or the duration variable in any of the underlying BLCLI commands.