5 Packaging Audit Collection Plug-ins

Learn about the steps you need to perform to package collection plug-ins.

5.1 Flow of Packaging

Review the flow of packaging audit trails with Oracle Audit Vault and Database Firewall. The tools required for packaging the plug-in are available in the SDK.

Setting Up Your Development Environment described the directory structure of the staging area, all the shipping objects such as the JDBC driver (if needed), the mapper file, any executables, and any Oracle-supplied patches.

For Java collectors, it also includes appropriate locations for the compiled code and Java JAR files.

Audit Collection Plug-ins described the mapper file.

Java-Based Audit Trail Collection Plug-ins describes how to create Java-based collection plug-ins.

For Java collectors, it also includes Java code

Now you are in a position to create a plugin-manifest.xml file that describes where everything resides, what Audit Vault and Database Firewall should do with it, and then package everything into a .zip file to ship to the Audit Vault and Database Firewall Administrator.

5.2 Creating a plugin_manifest.xml File for Shipping

After you have created packaging for your audit trails, you are in a position to create a plugin-manifest.xml file for Oracle Audit Vault and Database Firewall.

The plugin-manifest.xml file describes where everything resides, indicates what Oracle Audit Vault and Database Firewall should do with it, and then how to package everything into a .zip file that can be shipped to the Oracle Audit Vault and Database Firewall Administrator.

1. When the collection plug-in program is ready to be packaged, create a directory structure.

   Note that the directory structure is slightly different for Java-based plug-ins than for collection plug-ins.

2. Create a plugin-manifest.xml file. This file describes the collection plug-in and the relevant parameters that provide the Audit Vault Collection Framework necessary information to instantiate and run the collection plug-in.

3. Package the collection plug-in files, the plugin-manifest.xml file, and any additional jars that collection plug-in depends on at run-time.

4. Run the avpack tool. The avpack tool validates and generates a .zip package that represents an collection plug-in package.

   The avpack tool runs a number of validity checks (such as whether the directory structure is correctly populated, the manifest file is well-formed, and is without errors, and so on), then generates the collection plug-in package, in the form of a zip file, for deployment.

See Also:

• Audit Collection Plug-in Directory Structure

• Description of Plug-in Manifest File

• Example Code for example plugin-manifest.xml files specific to your type of collection plug-in.

• avpack Tool

5.3 External Dependencies

In the packaging process, external dependencies are files that are needed during runtime, but that can be unavailable when you package Oracle Audit Vault collection plug-ins.

An example of an external dependey is if your collection plug-in depends on a third-party component that the end-user licenses, or a component that has an issue related to licensing or copyright. In that scenario, it is possible that you are unable to package this component. If you cannot package the required component, then this is an external dependency. To resolve this dependency, you expect that the end-user provides the required compnent during collection plug-in deployment.

For these scenarios, the plugin-manifest.xml exposes the unresolved-external element. avpack does not file-check files under this element, but during deployment time, avpack will fail to deploy the collection plug-in if the $OH/av/dropins folder does not contain these files.

In the following example, foo.jar is an external dependency:

<unresolved-external>
   <file>foo.jar</file>
</unresolved-external>

During deployment, avpack checks to see if the file foo.jar is present in the $OH/av/dropins folder on the Oracle Audit Vault Server. If the file is missing, then avpack fails to deploy the collection plug-in. Instead, it issues a message stating that external dependencies are not being met.

To resolve the issue, the user must acquire the file, and make it available in the $OH/av/dropins folder. After the external dependency is provided, avpack can deploy the collection plug-in successfully.

5.4 Creating New Versions of Your Audit Collection Plug-ins

If you create new versions of the collection plug-ins, then you can easily plug them in to replace existing versions without difficulty in Oracle Audit Vault and Database Firewall.

To update an existing collection plug-in to a newer version, use the avcli command-line tool with the DEPLOY PLUGIN command,

Collection plug-ins are cumulative in nature. All necessary files are created and updated.

To remove or undeploy collection plug-ins, use the avcli tool and the UNDEPLOY PLUGIN commands. These commands are atomic; that is, they are all or nothing transaction, which helps maintain a high degree of system stability.

5.5 avpack Tool

The avpack tool is a command-line based tool written in Java that packages the various collection plug-in objects such as code files, configuration files, and so on.

Prerequisites

You must complete the following prerequsites for using the avtool:

• Install and package (run) the avpack plug-in tool on the same platform on which the agent will run.

  The packaged avpack plug-in for Linux can be used for all platforms, but the packaged avpack plug-in for Windows can only be used for Windows platforms.

• Place collection plug-in artifacts following the recommended directory structure. Then, you can use avpack to generate a collection plug-in package.

File Path

You can stage the collection plug-in files in any directory that is accessible by the avpack tool. The avpack tool validates the directory structure, and then parses and verifies the plugin-manifest.xml file. The tool also performs some basic verifications, such as verifying that all the files specified in the plugin-manifest.xml are staged in their corresponding directories, and so on.

Syntax

avpack -stagedir directory name -o archive filename [-l loglevel ]
[-h]

Options

Each option must be prefixed with a minus sign (-).

Option	Description
-stagedir	The directory under which the collection plug-in artifacts are staged. Contents of this directory will be archived in the generated plug-in archive.
-o	The name for the generated plug-in archive file. It should end with a .zip extension. (for example, myplugin.zip).
-l	(Optional) Sets the log level to the level specified. Supported log levels: INFO, WARNING, ERROR, and DEBUG. Default log level is INFO.
-h	(Optional) Display help for the avpack tool.

Usage Notes

You use the plugin-manifest.xml file to specify the key files that the collection plug-in must have to run. The avpack utility checks for the existence of these files, but zips everything contained in stagedir, so you do not need to list every file unless you want it to be verified by avpack.

After validation is complete, the tool packages the files into a .zip plug-in package suitable for deployment with Oracle Audit Vault and Database Firewall.