3.6.5 Definition file manipulation function

(a) Host to retrieve

A single host can retrieve a list of definition files that can be retrieved in a single run. If you want to get a list of definition files from more than one host, you must run it multiple times.

(b) List of definition files to be acquired

Retrieves a list of user-created definition files that are defined in a definition file that can be updated by JP1/IM - Manager or JP1/IM - Agent, or user-created definition file list definition file (imdd_user_deffile_list) or user-created definition file list definition file (jpc_user_deffile_list.json).

For details on the definition files that can be updated by JP1/IM - Manager or JP1/IM - Agent, and the files that can be defined by user-created definition file list definition file, see the note of List of definition files in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

For details on user-created definition file list definition file, see the appropriate file in Chapter 2. Definition Files refer to the appropriate file in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

The following table shows the items for each file that are retained as internal information in the list.

For files with incorrect user-created definition file list definition file definitions, add them to the list as files with invalid definitions.

(a) Host to retrieve

You can retrieve definition files from a single host for a host that you can retrieve in a single run. If you want to retrieve the definition file from more than one host, you must run it multiple times.

(b) Definition file that received the acquisition request

Returns the definition file requested for retrieval in a single zip file. Returns a zip file-whether the destination is a Windows, Linux. The name of zip file is "hostname from which the definition file is retrieved_current time of the Integration Manager host (YYYYMMDDhhmmssSSS).zip"(YYYYMMDDhhmmssSSS is the local time of the Integration Manager host). If a file name is duplicated when a file is created, the current time is acquired again. When retrieving from integrated operation viewer window, the upper limit of the file size is 10 files for 1MB, retrieval. In addition to the definition file, the contents of zip file are included in definition file properties file.

The extension fields that are set in zip file created by the definition file manipulation function use the "Extended Timestamp Extra Field" supported by Go. The update date and time of the definition file created when zip file is extracted is expressed in the time zone of JP1/IM - Manager host.

Important

When extracting zip files, use a tool that supports Extended Timestamp Extra Field. If you use an unsupported zip decompression tool, the update date and time of the definition file created when you extract zip file is not represented by JP1/IM - Manager time zone when JP1/IM - Agent time zone differs. Also, Windows Server standard zip does not support "Extended Timestamp Extra Field".

(c) Definition file properties file

For details about definition file properties file that summarizes the information in the definition file, see Definition file properties file (imdd_file_properties.json) in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference. Place this file in zip when the definition file is retrieved. When you use the definition file update facility or the definition file deletion facility, you can use information about the location of the definition file or the post-placement import operation.

(a) Files that can be deleted

The files that can be deleted are those that are defined in user-created definition file list definition file and that actually contain the files.

If you want to use the definition file manipulation function for a file that can be created in any folder of the definition files of the Integration Manager, you must place it in Manager path \conf\imdd\user. For a logical system, replace "Manager-path" with "shared-folder\JP1IMM".

For details about the files that can be defined in user-created definition file list definition file, see the note in List of definition files in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

(b) Backing Up Files to Delete

Leave only one generation of backups before deleting files. After the deletion is complete, the backup file is deleted.

(c) Importing definitions after file deletion

After the file is deleted, the content described in updateaction of user-created definition file list definition file is executed, and the definition information is updated.

(d) Recovery when an operation for definition import fails

If the operation for definition import fails, the deleted file is restored from the file that was being backed up. After that, the system executes the information described in user-created-definition file list definition file's updateaction again for definition import and recovers the definition information to the state that existed prior to the deletion of the file.

(e) Deleting backup files

After deleting a file or executing an operation for importing a file, the file that was being backed up is deleted regardless of whether the operation succeeded or failed. When executing the process of deleting a file, if a file with an update date of at least one day before the time of deletion exists in the destination of the backup file, the file is also deleted. Even if the deletion of the backup file fails, the deletion function of the definition file continues.

(f) Printing Integrated Trace Logs and issuing JP1 events

Outputs success and failure information about the delete operation of the definition file to the consolidation tray log. If the deletion is successful, it issues a JP1 event for the event ID:00007640. If the deletion fails, it issues a JP1 event for the event ID:00007641.

If the status is 200 in the definition file deletion API, the displayed message is KAJY68115-I. It is KAJY68116-E when the status is other than 200.

For output of the integrated trace log, deletion of the definition file of integrated agent is also output by the deletion function of the definition file of the integration manager.

Important

• If you delete a user-created definition file, edit user-created-definition file list definition file to delete the deleted file. If you do not delete the file information, KAJY68102-W message is displayed when the definition file list is retrieved.

• If you delete information about a file that you plan to delete from user-created-definition file list definition file prior to deleting a user-created definition file, the file cannot be deleted, leaving unnecessary definition files. If this happens, add the information of the file to be deleted to user-created-definition file list definition file. After adding the file, delete the file using the definition file deletion facility, or delete the file by logging in directly to the host where the definition file is located.

(a) Updatable file

The files that can be updated are files that actually exist and can be updated from the list of definition files.

If you want to use the definition file manipulation function for a file that can be created in any folder of the definition files of the Integration Manager, you must place it in Manager path\conf\imdd\user. For a logical system, replace "Manager-path" with "shared-folder\JP1IMM".

For details about the files that can be acquired in the definition file list, see 3.6.5(1)(b) List of definition files to be acquired.

(b) Backing up files to update

Leave only one generation of backups before updating the file.

(c) Importing definitions after file update

After updating the file, execute the information described in updateaction of user-created-definition file list definition file and update the definition information.

If updateaction contains the following command string, and JP1/IM - Agent is running on a logical host, the command is executed with -h logical-host-name assigned.

• addon_jpc_service_reload

• addon_jpc_service_get_status

• jco_spmd_reload

• jddupdateaction

• jddupdatessomap

In addition, among the definition files of JP1/IM - Manager, the definition files that reflect the definition contents by executing the following commands are imported as soon as the definition files are updated.

• jco_spmd_reload

• jddupdateaction

• jddupdatessomap

For a definition file that uses a command other than the above to import definition information, execute the command with response action (manual) to import the definition information.

(d) Recovery when an operation for definition import fails

If the operation for definition import fails, the updated file is restored from the file that was being backed up. Executes the information described in user-created definition file list definition file's updateaction for redefinition import, and then recovers the definition information to the status prior to the file update.

(e) Deleting Backup Files

After the operation execution processing for updating the file or for importing the file is completed, the file that was being backed up is deleted regardless of whether the operation succeeded or failed. When executing the process of deleting a file, if a file whose update date is at least one day earlier than the time of deletion exists in the backup file storage location, the file is also deleted. Even if the deletion of the backup file fails, the deletion function of the definition file continues.

(f) Printing Integrated Trace Logs and issuing JP1 events

Outputs success and failure information for update processing of the definition file to the integrated trace log. If the update is successful, it issues a JP1 event for the event ID:00007642. If the update fails, issue JP1 event of the event ID:00007643.

If the status is 200 in the definition file update API, the message that is output is KAJY68119-I. If the status is anything other than 200, the message is KAJY68120-E.

For the log output of the integrated trace log, the update function of the definition file of the integration manager also outputs the update of the definition file of integrated agent.

(g) Definition files that reflect definition information using jco_spmd_reload

If the definition file is updated with an error in the definition information for a definition file that reflects definition information using jco_spmd_reload, the following behavior occurs.

• The integrated operation viewer or the result of running of REST API does not result in an error.

• The definition file recovery process is not performed, and the definition file with incorrect definition information is placed on the manager host.

• An error message stating that the definition information is incorrect is output in the integrated trace log.

If the definition cannot be reflected correctly after the definition information is reflected, modify the definition information according to the response to the message output in the integration trace log, and update the definition information again.

The definition files that use the jco_spmd_reload to reflect definition information are as follows:

• File that defines the event source host mapping (user_hostmap.conf)

• Health check definition file (jcohc.conf)

• Event guide information file (jco_guide.txt)

• Correlation event generation system profile (egs_system.conf)

• Severity changing definition file (jcochsev.conf)

• Definition file for extended event attributes

• Definition file for extended event attributes (extended file)

• File that defines which items are displayed for common exclusionconditions (common_exclude_filter_attr_list.conf)

• File that defines automatic input of common exclusionconditions (common_exclude_filter_auto_list.conf)

• File that defines which items are displayed for repeated event conditions (event_storm_attr_list.conf)

• File that defines automatic input of repeated event conditions (event_storm_auto_list.conf)

• File that defines which items are displayed for severity changing definitions (chsev_attr_list.conf)

• File that defines automatic input of severity changing definitions (chsev_auto_list.conf)

• Definition file for opening monitor windows

• Definition file for changed display messages (jcochmsg.conf)

• File that defines automatic input of display message change definitions (chmsg_auto_list.conf)

• File that defines which items are displayed for display message change definitions (chmsg_attr_list.conf)

(h) Notes

• It takes time to check whether the operation for importing the definition has been reflected correctly. The confirmation time of the reflection process is set in item "service_startup_wait_time" of the imagent configuration file (jpc_imagent.json).

  In addition, update processing of the definition file is performed for each file to be updated. When updating multiple files, it takes time to complete depending on the number of files.

  Note that if you update more than one file, the timeout for file manipulation specified in imbase configuration file (jpc_imbase.json) "file_operation_timeout" field may be exceeded. If the timeout period is exceeded, update will fail. Adjust the setting so that the following conditions are met:

  Confirmation time of reflection process (service_startup_wait_time) × number of concurrent update files < timeout period for file operation processing (file_operation_timeout)

  Because the timeout period for file operation processing is the timeout period for the entire file operation processing, set a value with plenty of time.

  For details about the above definition files, see imagent configuration file (jpc_imagent.json) and imbase configuration file (jpc_imbase.json) in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

• If you have updated the definition file of add-on program (OSS) that corresponds to add-on administration function, and you have updated the definition file of OSS that corresponds to add-on administration function and you have enabled automatic periodic restart of OSS wrapper (JP1/IM - Agent wrapper specifies the value of the environment variable IMA_OSSWRAPPER_RESTART_INTERVAL in service definition file or unit definition file of the applicable OSS, and you have JP1/IM - Agent wrapper automatically restarts the process of the service periodically), if you do not restart OSS after updating the definition file of add-on program, the update content of the definition file is not reflected in the process of add-on administration function, but if you continue to operate in this condition, the settings are reflected in the timing when OSS wrapper automatically restarts the process of the service.

  In some OSS, restarting the system may affect operation. For notes on restarting OSS, see 10.3.1 Notes on Stopping and Restarting in the JP1/Integrated Management 3 - Manager Administration Guide.

(a) Updatable file

Alert configuration file (jp1_alerting_rule.yml) is the only file that can be updated by function to bulk distribution of definition file. In the Distribute alert configuration file dialog box of the integrated operation viewer, specify the filename (jpc_alerting_rules.yml) of alert configuration file to be distributed in bulk. If the specified filename differs, a KAJY68127-E message is issued and the process is aborted.

When a file is specified in the Distribute alert configuration file dialog box, the content of the file is not checked. When you use the update function of definition file to distribute or apply files to individual hosts, Prometheus service checks the definition contents. If an invalid definition is found, the definition contents are restored.

(b) About File Update

The function to bulk distribution of definition file uses the update function of definition file to update the definition file. After updating, displays the update success or failure on each host and an error message (message returned from each REST API) if it fails.

When the distribution process for all distribution hosts is completed, the distribution is issued in JP1 event (event ID:3F84). For details, see 3.6.5(5)(g) Checking whether updating is successful.

(c) Parallel execution of the distribution process

The multiple host distribution process REST API the definition file updates in parallel from integrated operation viewer. This ensures that definition file updates are performed in parallel on each host. The degree of multiplicity of parallel is 10 (fixed).

(d) Number of hosts that can be distributed at one time

The function to bulk distribution of definition file allows you to distribute up to 200 hosts at a time. If you need to distribute to more than 200 hosts, distribute them more than once.

(e) Interrupting the distribution process

If the distribution process takes a long time, you can stop the bulk distribution process by closing the List of distribution results dialog box or integrated operation viewer window. However, when you close the window, JP1/IM - Manager continues the ongoing operation without interrupting it, and the next operation to be executed is interrupted.

Also, any actions that were executed or terminated before the screen was closed remain and do not revert to the definition before distribution.

When the bulk distribution process is stopped by closing the List of distribution results dialog box, a JP1 event (ID:3F85) indicating that the process has stopped is issued. For details, see 3.6.5(5)(g) Checking whether updating is successful. Also, if the bulk distribution process is stopped by closing integrated operation viewer, no JP1 events are issued.

(f) Retry distribution process

If there is a host that needs to be retried for the distribution process, perform the bulk distribution again to the corresponding host.

(g) Checking whether updating is successful

The success or failure of the update of the distributed definition file on each host can be confirmed in the List of distribution results dialog box of integrated operation viewer and JP1 event.

The bulk distribution of definition files uses the events listed in the following tables to issue JP1 events. The results of the entire bulk distribution process (successful or unsuccessful updates for each host) can be viewed in the event details window for JP1 event in items 3 and 4. The success or failure of the update of the definition file on each host can be confirmed by the messages in item 1 and 2.

The user checks the host where the distribution failed and the host where the distribution was interrupted, selects the applicable host from the List of Integrated Agents window, and performs the bulk distribution again.

For details about item 1 and item 2 in the above tables, see 3.6.5(4)(f) Printing Integrated Trace Logs and issuing JP1 events.

JP1 events in No.3 and No.4 in the above tables output the following to the extended properties: For details, see 3.2.2(121) Details of Event ID:00003F84 and 3.2.2(122) Details of Event ID:00003F85 in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference. In addition, messages for JP1 events in No.3 and No.4 are always output in English.