Important

   

Starting version 8.9.03, BMC Server Automation is renamed to TrueSight Server Automation. This space contains information about BMC Server Automation 8.9.02 and previous versions. For TrueSight Server Automation 8.9.03 and later releases, see TrueSight Server Automation 8.9.

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:

ColumnAction
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 nameFlagDescription
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 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.
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 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.
DurationDistribution

-p

Distributes the run-time (as set by the MaxDuration parameter) across the delete commands in below shares (percent).

  • JobRunEvent = 8% (60 minutes)
  • AuditTrail = 8% (60 minutes)
  • cleanupDatabase = 50% (360 minutes)
  • hardDeleteAllSharedObjects = 17% (120 minutes)
  • cleanupFileServer = 17% (120 minutes)

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:
"JobRunEvent=8 AuditTrail=8 cleanupDatabase=50 hardDeleteAllSharedObjects=17 cleanupFileServer=17"

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:

TYPICAL

HISTORY_RDR

HISTORY_ORDR


CLEAN_AGENT

CLEAN_ALL_AS

CLEAN_AS

CLEAN_REPEATER

It is used by the following BLCLI commands:

Delete cleanupHistoricalData — for historical data from the audit trail, job run events, job schedules, and shared generic assets. (For historical job results, a job property named RESULTS_RETENTION_TIME is used instead.)

Delete cleanupAgent

Delete cleanupAllAppServerCaches

Delete cleanupAppServerCache

Delete cleanupRepeater


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:


AuditResult

AuditTrail

ComplianceResult


Deploy


JobRunEvent

JobSchedule

PatchResult


SharedData (for generic assets and configuration objects created during execution of Snapshot Jobs and Audit Jobs, such as configuration files, hardware information, processes, and daemons)


SnapshotResult

NEW IN 8.9.02 OldVersionComponent

NEW IN 8.9.02OldVersionJob

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 valueCommand executedWhat it does
HISTORY


Delete cleanupHistoricalData



Cleans up BMC Server Automation historical data based on retention time.

  • A default retention time of 14 days is used for the following types of historical data: job run events, job schedules, audit trail, and shared data (generic asset data from Audit Jobs and Snapshot Jobs).
  • For job results (of Compliance Jobs, Audit Jobs, Snapshot Jobs, Patching Jobs, Deploy Jobs, NEW IN 8.9.02Old Version Component, and NEW IN 8.9.02Old Version Job), retention is set by a job property named RESULTS_RETENTION_TIME, for which the default is 0 (no deletion of job data).
HISTORY_O


Delete cleanupHistoricalData

Cleans up BMC Server Automation historical data for the specified OBJECT_TYPE (a required argument) based on retention time.

  • A default retention time of 14 days is used for the following types of historical data: job run events, job schedules, audit trail, and shared data (generic asset data from Audit Jobs and Snapshot Jobs).
  • For job results (of Compliance Jobs, Audit Jobs, Snapshot Jobs, Patching Jobs, Deploy Jobs, NEW IN 8.9.02Old Version Component, and NEW IN 8.9.02Old Version Job), retention is set by a job property named RESULTS_RETENTION_TIME, for which the default is 0 (no deletion of job data).
HISTORY_RDR


Delete cleanupHistoricalData

Cleans up BMC Server Automation objects for RoleName based on retention time. The RoleName parameter can be literally null to cleanup data from all roles.

  • Retention time is set by the RetentionTime parameter for the following types of historical data: job run events, job schedules, audit trail, and shared data (generic asset data from Audit Jobs and Snapshot Jobs). The default retention time is 14 days and the minimum value allowed is 3 days.
  • For job results (of Compliance Jobs, Audit Jobs, Snapshot Jobs, Patching Jobs, and Deploy Jobs), retention is set by a job property named RESULTS_RETENTION_TIME, for which the default is 0 (no deletion of job data).


HISTORY_ORDR


Delete cleanupHistoricalData


Cleans up BMC Server Automation historical data for objects of the specified ObjectType and RoleName, based on retention time.

  • Retention time is set by the RetentionTime parameter for the following types of historical data: job run events, job schedules, audit trail, and shared data (generic asset data from Audit Jobs and Snapshot Jobs). The default retention time is 14 days and the minimum value allowed is 3 days.
  • For job results (of Compliance Jobs, Audit Jobs, Snapshot Jobs, Patching Jobs, and Deploy Jobs), retention is set by a job property named RESULTS_RETENTION_TIME, for which the default is 0 (no deletion of job data).
RETENTION


Delete executeRetentionPolicy 
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.
CLEAN_DB


Delete cleanupDatabase 

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


Delete cleanupDatabase 
Performs a BMC Server Automation Database cleanup with the duration limitation specified in the MaxDuration parameter.
CLEAN_SHARED_OBJECTS


Delete hardDeleteAllSharedObjects 
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 BMC Server Automation.
CLEAN_FS


Delete cleanupFileServer

Cleans all the unused files from the file server and from temporary file storage on the Application 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


Delete cleanupFileServer
Performs a FileServer cleanup with the duration limitation specified in the MaxDuration parameter.
CHECK_FS


Delete checkFileServerIntegrity 

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.




CLEAN_AGENT


Delete cleanupAgent

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.

 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).

CLEAN_ALL_AS


Delete cleanupAllAppServerCaches

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


Delete cleanupAppServerCache

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


 Delete cleanupRepeater

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.
Was this page helpful? Yes No Submitting... Thank you

Comments