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:
Column | Action |
|---|---|
Flag runtime usage | Choose whether each of the defined parameter flags should be used or ignored. |
Value | 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.
Parameter name | Flag | Description |
|---|---|---|
ExecutionMode | -m | 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 indicated: | ||
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. | ||
ContinueOnError | -c | Specifies if the script is to keep processing if it runs into errors. By default, the NSH Script uses Continue on error = true. If set to true, upon encountering an error the script will log the error and then continue with the cleanup run. |
MaxDuration | -d | 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 completed. 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 Duration. |
DurationDistribution | -p | Distributes the run-time (as set by the MaxDuration parameter) across the delete commands in below shares (percent).
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: |
{{id name=".Configuringparametersinthescript-basedcleanupjobv23.4-retention"/}} RetentionTime | -r | 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. |
ObjectType | -o | Deletes a specific type of object. To use this parameter, you must be using an execution mode of HISTORY_O or HISTORY_ORDR. Use one of the following values:
|
RoleName | -R | Deletes objects from the database that were created by a specific role. |
TargetDevices | -t | Lists the device names which have an Application Server cache or a repeater. The execution modes CLEAN_AS and CLEAN_REPEATER use this parameter. |
TargetSize | -s | 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 |
|---|---|---|
HISTORY | Cleans up TrueSight Server Automation historical data based on retention time.
| |
HISTORY_O | Cleans up TrueSight Server Automation historical data for the specified OBJECT_TYPE (a required argument) based on retention time.
| |
HISTORY_RDR | Cleans up TrueSight Server Automation objects for RoleName based on retention time. The RoleName parameter can be literally null to cleanup data from all roles.
| |
HISTORY_ORDR | Cleans up TrueSight Server Automation historical data for objects of the specified ObjectType and RoleName, based on retention time.
| |
RETENTION | Marks entries for deletion based on retention time in the TrueSight Server Automation database. It marks old job runs and automatically created jobs and depot objects. | |
CLEAN_DB | 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. | |
CLEAN_DB_TL | Performs a TrueSight Server Automation Database cleanup with the duration limitation specified in the MaxDuration parameter. | |
CLEAN_SHARED_OBJECTS | Deletes database rows for shared data objects with the duration limitation specified in MaxDuration parameter. It includes data for shared files, checksum files, ACL entries, and internal values generated by TrueSight Server Automation. | |
CLEAN_FS | Cleans all the unused files from the temporary file storage on the Application Server and from the following directories in the file server:
Note: 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. | |
CLEAN_FS_TL | Performs a File Server cleanup with the duration limitation specified in the MaxDuration parameter. | |
CHECK_FS | Performs a File Server 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. | |
CLEAN_AGENT | Cleans up old temporary files on a target server (agent) that are older than the RetentionTime parameter value. This includes old files that were created by Deploy Jobs in the Transactions directory (especially rollback files) and in the Staging directory. 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). | |
CLEAN_ALL_AS | Deletes old temporary files on all the Application Servers that are currently up and running (and accessible). It removes files older than the RetentionTime parameter value. 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. | |
CLEAN_AS | Deletes old temporary files on a specific Application Server (any files older than the RetentionTime parameter value). 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. | |
CLEAN_REPEATER | Cleans up files from the staging directory of a repeater server. This cleanup removes files that have not been accessed for the RetentionTime parameter value until a specified maximum cache size (the TargetSize parameter) is reached on the target repeater server. 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 Cleanup module, 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 MaxObjectsPurgedPerTransaction setting. 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 MaxObjectsPurgedPerTransaction setting), 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.