Package import and export best practices
This document serves as a best practices guideline for exporting and importing packages in ESM 4.X. This is not meant to replace or alleviate the need to read the ESM user guide and online Help, which explain the packages feature in great detail.
Packages allow for content (rules, reports, etc.) to be transferred from one ESM instance to another. The feature also provides a GUI utility to manage what gets imported and exported in the packages. The screen shot below shows the package tab in the resource navigator.
Building and exporting a package:
To build a new package
1) Browse to the package tab of the resource navigator, right click on folder in the tree and select new package.
a. Be careful as to where you create the package as this is where it will be imported. Users may not have permission to import the package if you put it in a folder with strict ACL’s. When you are creating resources that you wish to share the same will hold true. The resources will be imported to the same location in the tree where they live in the ESM instance from which they were exported. Keep permissions in mind.
b. If you are building resources specifically to share on the forum you may want to make copies of the ones you use to a public folder. Remember to make copies of dependencies as well.
2) Unlink any rules to be included in the package from the Real-Time rules folder. This will make the install much quicker.
3) Give the package a name, a version and you may want to include the author.
4) Select the resources that are to be included as part of the package. Select the resources tab, and click add. Browse to the appropriate resources and select them. If they are the only resources in the folder, you can select the whole folder. Now click apply.
The above screen shot shows a package that has been created containing rules, a session list, and an active channel. Notice there are fields as part of the active channel. These are fields that have been included because they are dependant variable fields not default system fields.-THE NEXT STEP IS VERY IMPORTANT- Remove Dependencies on System ContentIn this step, you’re going to verify package contents, and remove dependencies on ArcSight system content.
Once the package has been saved, right click on the package in the tree and select show current package contents. Be sure that only custom resources are included. YOU DO NOT WANT TO EXPORT ANY ARCSIGHT DEFAULT SYSTEM or SOLUTION CONTENT. If you have made modifications, they will overwrite changes that others may have made to the same resource. Example: if customer1 changes the ArcSight Events filter and your package includes an unmodified ArcSight Events filter, customers2’s changes will be overwritten when they import the package.
See the package contents in the following screen shot. It may be helpful to sort by URI and look for any URI containing System or Solutions.
In the above example, it is clear that there are system filters and fields included as part of the package. The system fields get pulled in as part of a field set that contains default fields like Name, End Time, and Priority. It’s not a good idea to move these fields around; the only fields that need to be moved are the custom ones that are created by using variables. The dv-fields are created as part of the field set that is using variables so they are custom just stored in a path that contains System. Be aware of this exception to the rule. The ArcSight filters get pulled in because The Non-ArcSight Events filter is referenced by the active channel, that filter in turn reference other filters. See how the dependencies are all pulled in to the package? To solve this we need to exclude the dependencies from the package definition.
To remove dependencies that are default content, use the removed resources option in the lower pane of the resources tab. See the screen shot below.
The example shows the System fields being removed, except for the custom variable fields which we specifically included. So this is an example of how you can exclude a parent group but still include children of a child group. Further any filters that are part of the ArcSight system content have also been specifically removed. Once these changes have been applied, re-examine the current package contents and verify that only resources you plan to share are included. See below.
In the above example, there are only custom resources and no system content. At this point, it is safe to export your package and upload it to the forum for sharing. Be sure to follow the sharing guidelines, available in the sharing section of the user forum.Importing and installing a package:
First, it’s important to understand the difference between importing and installing.
When you import a package, it just uploads the compressed package resource to the database. When a package is imported but not installed, it is only visible from the Packages view, and the package icon is grey.
When you install the package, ESM actually unzips the bundle and installs the resources by importing them into the resource table within ArcSight ESM. The package is visible from the Packages view with a blue package icon, and the resources are distributed among the various resource trees in the Resources view.
* ArcSight recommends installing any shared content to a test system before installing in production as we do not support this content in any way
For best results, import and install in two separate steps: First import and verify what is in the package, then install it.
To import a package, browse to the packages tab in your console.
Click the green import arrow. Browse to the .arb file you would like to import and click open. The importing package screen will appear, and when it completes, you will see a screen asking if you would like to install the package. Uncheck the install package box, as shown in the example below.
Click next and click ok.
Browse to the package in the packages tree – refer to the URI in the above screen shot for the location. The package will be grayed out because it has not been installed. Right-click the package and select Show Package Archive Contents. Verify that there are no resources that are going to overwrite changes that you have made to resources on the ESM instance to which you are importing. A good rule of thumb, as mentioned before, is to make sure there is no ArcSight System or Solution content included in the package.
Once this has been verified, right click on the package and select Install Package
Final Note – Rules will need to be linked to Real-Time Rules in order for them to become active unless they were previously linked to the Real-Time Rules folder, which is not recommended.Good Luck and Happy Sharing!!!-The ArcSight Team