This chapter describes steps you need to perform to package collection plug-ins.
This chapter contains these topics:
The previous chapters have taken you to the point where you can package the collection plug-in.
Chapter 2 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.
Chapter 3 described the mapper file.
Now you are in a position to create a plugin-manifest.xml file that describes where everything resides, what AVDF should do with it, and then package everything into a .zip file to ship to the AVDF Administrator.
When the collection plug-in program is ready to be packaged, create a directory structure as illustrated in the "Audit Collection Plug-in Directory Structure".
Create a plugin-manifest.xml file. Refer to the "Description of Plug-in Manifest File", if needed. 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. See "Example Code" for example plugin-manifest.xml files specific to your type of collection plug-in.
Package the collection plug-in files, the plugin-manifest.xml file, and any additional jars that collection plug-in depends on at run-time.
Run the avpack tool. The avpack tool validates and generates a .zip package that represents an collection plug-in package. See "avpack Tool".
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.
External dependencies, in this packaging process, are files that will be needed during runtime, but may not be available when you package the collection plug-in. For example, if your collection plug-in depends on a third-party component that the end-user licenses, or a component with an issue related to licensing or copyright, you may not able to package this component, and will expect the end-user to provide it 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 Audit Vault Server. If the file is missing, avpack will fail to deploy the collection plug-in 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. Then, avpack can deploy the collection plug-in successfully.
If you create new versions of the collection plug-ins, you can easily plug them in to replace existing versions without difficulty.
Using the avcli command-line tool, you can use the DEPLOY PLUGIN command, described in Oracle Audit Vault and Database Firewall Administrator's Guide, to update an existing collection plug-in to a newer version. collection plug-ins are cumulative in nature. All necessary files are created and updated.
Collection plug-ins can be removed or undeployed, using the avcli tool and the UNDEPLOY PLUGIN command, described in Oracle Audit Vault and Database Firewall Administrator's Guide. This command is atomic, that is, it is an all or nothing transaction, which helps maintain a high degree of system stability.
The plugin-manifest.xml file is a core XML file that describes the collection plug-in and defines the following elements and attributes:
The plugin element represents the plug-in object with these attributes:
Name: A descriptive name for the collection plug-in.
version: The version should be updated along with each update to the collection plug-in, and should monotonically increase based on some ordering scheme. For instance, AVDF uses a versioning scheme comprising of five digits, separated by periods: majr.minr.minr.patch.hotfix.
provider: The name of the provider, typically, the company or organization.
copyright: Any copyright notices for the collection plug-in.
TargetVersion: Oracle Audit Vault and Database Firewall Version that the collection plug-in is compatible with. The min attribute represents the minimum version of the target.
extensionSet: A set of extensionPoints.
ExtensionPoint: Each extensionPoint uniquely identifies the area of AVDF that is being extended by the collection plug-in. Currently, AVDF supports one Extension Point, securedTargetType, as indicated by the type attribute.
fileList: A list of all the files that ship with the collection plug-in.
jars: A directory that contains Java files ending with the extension .jar, in the element file.
templates: A directory that contains the mapper files for a collection plug-in, in the element file.
bin: A directory that contains executable files, typically those that end with .exe, in the element file.
config: A directory that contains plug-in specific configuration files, in the element file.
shell: A directory that contains shell or batch command files, in the element file.
patch: A directory that contains event patches for the collection plug-in, in the element file.
unresolved-external: A directory that contains files that cannot be packaged with the collection plug-in for some reason, but are needed at run-time. Packaging succeeds but the plug-in deployment will fail until these files are made available in the $OH/av/dropins folder of Oracle Audit Vault Server. These files are in the element file. See "External Dependencies" for further information.
securedTargetTypeInfo: This is a mandatory field that indicates the source type that this collection plug-in supports. Specify the source type by filling in the name attribute of this element.
trailInfo: A mandatory field that indicates the type of audit trails, on this source type, that the collection plug-in supports.
trailType: A mandatory field that indicates the type of trail described by this entry. Oracle Audit Vault and Database Firewall 12.1.1 supports these trail types: TABLE, DIRECTORY, TRANSACTIONLOG, SYSLOG, and EVENTLOG.
trailType can also be any arbitrary string, in which case, it is treated as a custom trail type.
trailLocation: Specifies the location of the trail; this is applicable only for TABLE and CUSTOM type trails only. This field must not be set for other trail types and will be ignored if set.
className: Specifies the Java class that handles the task of retrieving the audit data from this trail. Use the following:
-oracle.av.platform.agent.collfwk.ezcollector.table.DatabaseTableCollector for database table collection plug-ins.
-oracle.av.platform.agent.collfwk.ezcollector.xml.XMLFileCollector for XML file collection plug-ins.
To handle audit trails of different source versions of the same source type, you can optionally set the srcVersion attribute.
eventPatch: This is an optional field containing any event patches that must be applied as part of the collection plug-in deployment. These patches are in the eventPatch element with the name attribute as the file name and an order attribute that indicates the order to apply the patches.
Events attributes to be added are extended through patches generated by Oracle Audit Vault and Database Firewall Development. Partner developers can request specific events and attributes or both, to be added to the Oracle Audit Vault Event dictionary. If the core development team determines that a request is justified, it may issue a patch. You can bundle these patches with the collection plug-in for application during plug-in deployment.
See Also:
For sample manifest plug-in files for specific collection plug-ins:
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.
You must lay out the collection plug-in artifacts following the directory structure recommended in "Audit Collection Plug-in Directory Structure". Then, you can use avpack to generate a collection plug-in package.
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. It also performs some basic sanity checks such as verifying that all the files specified in the plugin-manifest.xml are staged in their corresponding directories, and so on.
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.
Once validation is complete, the tool packages the files into a .zip plug-in package suitable for deployment with Oracle Audit Vault and Database Firewall.
Usage:
avpack -stagedir <directory name> -o <archive filename> [-l <loglevel> ]
Where:
directory: The directory under which the collection plug-in artifacts are staged. Contents of this directory will be archived in the generated plug-in archive.
archive filename: The name for the generated plug-in archive file. It should end with a .zip extension. (for example, myplugin.zip).
log level: Optional: Sets the log level to the level specified. Supported log levels: INFO, WARNING, ERROR, and DEBUG. Default log level is INFO.
For further help, see avpack -h output.