# User Guide

# About BEA Guardian

This chapter provides an overview of Guardian components, features, and key concepts. Also provided are basic instructions for using and navigating the Guardian User Interface and Online Help System. Topics include the following:

- Introduction
- Guardian User Interface
- Guardian Online Help System
- Guardian Command Line Interface
- Key Concepts
- Security
- Privacy
- Key Tasks
- Example Scenarios
- Supported Configurations
- Supported Targets

## Introduction

#### What is Guardian?

Guardian is a diagnostic tool for identifying potential problems in your environment before they occur, and provides specific instructions for resolving them. Guardian is like having the entire BEA Customer Support Team scrutinize your domain and immediately present their findings and recommendations to you, at your convenience.

#### How do you use it?

First, activate one or more Domain s in Guardian. A domain is a logically related group of WebLogic Server resources that you manage as a unit. You can also organize multiple domains into Domain Groups. Then, select one or more domains, select a Signature Bundle, and launch an Evaluation. Guardian then proceeds to evaluate the Signature Bundle against the specified domain(s), and generates a detailed report of potential issues and their remedies. You can then review the report and decide how to proceed.

#### Where can I run it?

Guardian can run on Windows or Linux systems that have Java Version 5 or higher installed. Guardian can evaluate any platform based on WebLogic Server version 8.1 through 10.3, regardless of the operating system on which it is running.

## Guardian User Interface

This section provides an overview and basic navigation instructions for the Guardian User Interface. For a complete, detailed description of all interface components, see Reference. For detailed instructions for specific Guardian tasks, see Tasks.

In general, you will use the Guardian User Interface to perform the majority of Guardian tasks and activities. For some highly repetitive or complex tasks—for example, activating multiple Guardian domains in multiple Guardian instances—you may want to create a Guardian Command Line Interface (CLI) script to automate a series of tasks. For basic instructions on using the CLI, see Command Line Interface on page 73 on Tasks. For a detailed description of all CLI commands and syntax, see Command Line Interface on page 134 of Reference.

The sections below provide a description and basic navigation instructions for each of the following elements:

- Guardian Main Window

- Main Menu Bar
- Main Toolbar
- Navigation Pane
- Document Pane
- Document View and Editor Titlebars
- Context Menus

- Wizards

- Wizard Titlebar Menus

For a complete detailed description of the Guardian User Interface, see Reference.

### Guardian Main Window

The Guardian Main Window contains the following basic navigation and display components:

- Main Menu Bar
- Main Toolbar
- Navigation Pane

- Explorer Tabs
- Explorer Toolbar Icons
- Explorer Toolbar Menus

- Document Pane

- Document Views and Editors
- Document View and Editor Titlebars

- Context Menus

The following sections provide instructions for using each of these components.

#### Main Menu Bar

The Main Menu Bar is at the top of the BEA Guardian main window just below the BEA Guardian titlebar. The Menu Bar contains the following menus:

- File Menu
- Tools Menu
- Window Menu
- Help Menu

The Menu Bar menus in turn contain a series of options and submenus, some of which also lead to additional menus, dialog boxes, or wizards. The following sections provide an overview of each of these menus, and instructions for invoking them.

##### Keyboard Shortcuts

You can invoke many menus, submenus, and menu options by using a keyboard shortcut. To display Menu Bar menus, press the Alt key and type the menu selection key for the menu you want to display. The menu selection key is the letter underlined in the menu name when you press the Alt key.

Some menu options also have keyboard shortcuts, which consist of a specific sequence of characters pressed simultaneously. If a menu item has a keyboard shortcut, the key sequence is listed next to the item in the menu. To see the complete list of keyboard shortcuts, press Ctrl+Shift+L.

##### File Menu

Table 1-1 describes the File menu options and submenus.

Table 1-1 File Menu
Menu Item | Description
--- | ---
New > | This option opens a submenu with the following options: Domain Group — Open the Add Domain Group dialog box for creating a new Domain Group. Domain — Open the Domain Activation Wizard. Inventory — Open the Inventory Wizard. Evaluation — Open the Evaluation Wizard. Shortcut — Open the Shortcut Wizard.
Close | Close the current display in the Document Pane.
Close All | Close all Document Pane displays.
Save As... | Export the selected Domain Inventory or Evaluation as a file (PDF or HTML).
Print | Print the contents of the Report tab or Source tab currently displayed in the Document Pane.
Import | Open the Import dialog box for importing Guardian Preferences, Workspace, or Report Plug-in.
Export | Open the Export dialog box for exporting Guardian Preferences, Workspace, or Report Plug-in.

##### Tools Menu

Table 1-2 describes the Tools menu options and submenus.

Table 1-2 Tools Menu
Menu Item | Description
--- | ---
Refresh Site List | Update the list of BEA Support site identifiers available for creating support cases.
Purge Inactive Domains | Removes deactivated domains from the Domain Explorer and the Guardian Registry. This also removes the Domain Inventories, Evaluation Summaries, and any Case Creation Archives for those domains from the Guardian Workspace.
View Log > | This opens a submenu with the following options: Signature Log — Display the Guardian Signature log file. Guardian Log — Display the Guardian log file.

##### Window Menu

Table 1-3 describes the Window menu options and submenus.

Table 1-3 Window Menu
Menu Item | Description
--- | ---
Show View | Open a submenu containing options for opening the following Views: Domain Explorer — Opens the Domain Explorer in the Navigation Pane. Bundle Explorer — Opens the Bundle Explorer in the Navigation Pane. Shortcut Explorer — Opens the Shortcut Explorer in the Navigation Pane. Signature Explorer — Opens the Signature Explorer in the Navigation Pane. Active Domains Table — Opens the Active Domains Table in the Document Pane. Shortcuts Table — Opens the Shortcuts Table in the Document Pane. Progress View — Opens the Progress View in the Navigation Pane. Outline View — Opens the Outline View to the right of the Document Pane.
Reset Perspective | Resets the Guardian displays to their default settings.
Preferences... | Open the Preferences configuration page.

##### Help Menu

Table 1-4 describes the Help menu options and submenus.

Table 1-4 Help Menu
Menu Item | Description
--- | ---
Welcome | Display the Guardian Welcome page.
Help Contents | Open the BEA Guardian Online Help System.
Search | Open the Online Help Search utility.
Dynamic Help | Opens the Guardian Dynamic Online Help pane (to the right of the Document Pane).
Cheat Sheet... | Open the Cheat Sheet Selection dialog box for selecting and displaying a Guardian Cheat Sheet. The Cheat Sheet provides step-by-step instructions for certain Guardian tasks. Action buttons are provided for some tasks; click a button to initiate that task.
Manage Guardian > | Open a submenu with the following options: Update Guardian — Open the Update Wizard. Manage Configuration — Open the Product Configuration Manager for performing the following tasks: Scan for Updates View Installation History Show Activities Add an Extension Location
Key Assist... | Display the list of keyboard shortcuts.
Software Updates > | Open a submenu with the following options: Find and Install... — Open the Install/Update dialog box for searching for and installing updates and new features. Manage Configuration — Open the Product Configuration Manager.
About BEA Guardian | Open the About BEA Guardian dialog box. This displays the version of your current Guardian installation, and details about Guardian features, plug-ins, and configuration.

#### Main Toolbar

The Main Toolbar is located below the Main Menu, and contains action buttons for the most common Guardian tasks. To identify a button, move your mouse pointer over the button; this displays the tool tip text for that button.

Table 1-5 describes the Main Toolbar buttons.

Table 1-5 Guardian Main Toolbar Buttons
Button | Description
--- | ---
Open | Display the selected resource in the Document Pane. Open Active Domain Table when Target Domains is selected in the Domain Explorer. Open Domain Inventory when a Domain Inventory is selected in the Domain Explorer. Open Evaluation Summary when an Evaluation Summary is selected in the Domain Explorer. Open Signature Details when a signature is selected in the Signature Explorer or Bundle Explorer. Open Bundle Details when a bundle is selected in the Bundle Explorer. Open Evaluation Wizard when a shortcut is selected in the Shortcut Explorer.
Print | Print the contents of the Report tab or Source tab currently displayed in the Document Pane.
Activate | Open the Domain Activation Wizard.
Inventory | Open the Inventory Wizard.
Evaluate | Open the Evaluation Wizard.
Update | Open the Update Wizard.

#### Navigation Pane

The Navigation Pane resides in the left side of the BEA Guardian main window. The Navigation Pane contains several tabs leading to Explorer Views. You can have multiple Views open at once, but only one can be displayed at a time. Click on a tab to display an Explorer view.

##### Explorer Tabs

Table 1-6 describes the Navigation Pane Explorer View tabs:

Table 1-6 Navigation Pane Explorer Tabs
Explorer Tab | Description
--- | ---
Domain Explorer | Open the Domain Explorer. This View enables you to browse, manage, and administer the domains you have defined in Guardian. Right-click in the Domain Explorer to open a context menu of domain operations. For instructions on Domain Explorer tasks, see Domains on page 47 in Tasks.
Signature Explorer | Open the Signature Explorer. This View enables you to browse the available signatures and view Signature Details for a selected signature. For instructionson Signature Explorer tasks, see Signatures on page 62 in Tasks.
Bundle Explorer | Open the Bundle Explorer. This View enables you to browse the available Signature Bundles and their contents. For instructions on Bundle Explorer tasks, see Bundles on page 69 in Tasks.
Shortcut Exporer | Open the Shortcut Explorer. This View enables you to view and manage your Evaluation Shortcuts. For instructions on Shortcut Explorer tasks, see Shortcuts on page 70 in Tasks.

For a detailed description of each of the Explorer views, see Navigation Pane on page 93 of Reference.

##### Explorer Toolbar Icons

Below each Explorer titlebar is the Explorer toolbar. An Explorer toolbar may contain all or some of the following active icons:

Table 1-7 Explorer Toolbar Icons
Icon | Function
--- | ---
| Close
| Minimize
| Maximize
| Restore
| Expand all items.
| Collapse all items.
| Open Explorer menu.
| Link selected item with Editor.

##### Explorer Toolbar Menus

The Domain Explorer, Signature Explorer, and Bundle Explorer each contain a Menu icon in the right corner of the toolbar. Click the Menu icon to display a menu of operations for that Explorer.

Table 1-8 describes the Explorer menus.

Table 1-8 Explorer Menus
Explorer | Menu Options
--- | ---
Domain Explorer | The Domain Explorer menu contains the following options: Filter Domain Explorer — Open the Filter Domain Explorer dialog box to filter inventories and evaluations by date created. Link with Editor — Link the selected item with an Editor.
Signature Explorer | The Signature Explorer menu contains the following options: Sort Signatures > — This opens a submenu of the following options for sorting signatures: By Name By Severity Filters... — Open the Filters dialog box for filtering signatures in Signature Lists. For instructions, see "Filter Signatures" on page 63 in Tasks. Link with Editor — Link the selected item with an Editor.
Bundle Explorer | Filters... — Open the Filters dialog box for filtering signatures in Signature Lists. For instructions, see "Filter Signatures" on page 63 in Tasks. Sort Signatures > — This opens a submenu of the following options for sorting bundles and signatures in the Bundle Explorer: By Bundle Name, Signature Name By Bundle Name, Severity Link with Editor — Link the selected item with an Editor.

#### Document Pane

The Document Pane is located in the central portion of the BEA Guardian main window. The Document Pane displays the Document Views and Editors.

##### Document Views and Editors

Table 1-9 describes the Guardian Views and editors that can be displayed in the Documentation Pane.

Table 1-9 Document Pane Views and Editors
View/Editor | Description
--- | ---
Active Domain Table | Select Window > Show View > Active Domains Table to display this View. This contains a table of all of the domains currently activated in Guardian, and action buttons for the following tasks: Open Admin Console — Open an instance of the WebLogic Server Administration Console. Modify Domain — Open the Domain Properties configuration page for the selected domain. Deactivate Domain — Open the Domain Deactivation Wizard for the selected domain(s).
Domain Inventory | Double-click on a Domain Inventory entry in the Inventory History folder in the Domain Explorer to display the Inventory Details for that inventory. The inventory includes descriptions of your servers, Java Virtual Machines, operating systems, databases, product versions, and certain configuration settings. The Domain Inventory View contains the following tabs: Overview — Display the Domain Inventory Overview for this Inventory. Source — Display the XML source for the Inventory. Report — Display the Domain Inventory report for this inventory.
Evaluation Summary | Double-click on an Evaluation Summary entry in the Evaluation History folder in the Domain Explorer to display that Evaluation Summary. This contains a table of all detected signatures for the evaluated domain. Select a signature in the list to display the signature details and remedy for that signature.
Shortcut Table | Select Window > Show View > Shortcuts Table to display this View. This contains a table of all of your Shortcuts, and action buttons for the following tasks: Add Shortcut — Open the Shortcut Wizard for creating Shortcuts. Delete Shortcut — Delete the selected Shortcut. A Confirm Delete dialog box prompts you to confirm the delete operation. Click OK to delete the Shortcut.
Signature Details | Double-click on a signature entry in the Signature Explorer or Bundle Explorer. This View contains the following tabs: Overview — Display the Signature Overview for the signature. Source — Display the XML source for the signature. Report — Display the Signature Report for that signature.
Bundle Details | Double-click on a Bundle node in the Bundle Explorer. This View provides a description and some additional details about the selected Bundle. Also included is the Signature Definition for the Bundle.

Note: | You can have multiple Views or Editors open in the Document Pane, but only one can be active at a time.

##### Document View and Editor Titlebars

Each View and Editor has a titlebar that contains the name of the View or Editor, an identity icon, and buttons to close, minimize, maximize, and restore the display.

You can also use View and Editor titlebars to do the following:

- Double-click the titlebar to maximize a View or Editor, and double-click it again to restore it to its original size.
- Right-click on a titlebar to open the System Menu for that View or Editor.
- You can group multiple Views or Editors together on a titlebar as a tab group. Tab groups can be moved together as a unit, using either the System Menu > Move menu option or drop cursors. Only the titlebar of the currently active View or Editor is visible in a tab group.
- If you have more Views or Editors open than can fit on a titlebar, a Show List icon appears to the right of the titlebar tabs. The icon includes a number that indicates how many more of the open Views or Editors can fit on the titlebar. Click the icon to display a list of all the titlebar Views and Editors. Select an item from the list to make it active and bring it to the forefront of the Navigation Pane or Document Pane display. The items listed in bold font are those that cannot fit on the titlebar. The items not listed in bold are those that are already shown on the titlebar.
- You can move Views or Editors by dragging their titlebars to different locations.

- You can move the Views in the Navigation Pane almost anywhere, including outside the BEA Guardian main window. However, you can move Editors only within the Document Pane.
- As you drag a View or Editor titlebar, the mouse pointer changes into a drop cursor that indicates where the View or Editor will appear when you release it.
- The point in the titlebar at which you click determines what will be dragged. Click a View or Editor tab to move that View or Editor, but not the whole tab group. To move the whole tab group, click to the right of the tabs in the title bar, or select Move > Tab Group from the System Menu.

#### Context Menus

Many views and displays contain context menus. Right-click on an item or anywhere in a display to open the associated context menu. For a complete description of context menus, see Reference.

### Wizards

BEA Guardian provides the several wizards for guiding you through some of the more complex or common Guardian tasks.

Table 1-10 describes the Guardian wizards and how to invoke them.

Table 1-10 Guardian Wizards
Menu Item | Description
--- | ---
Domain Activation Wizard | Click Activate to open the Domain Activation Wizard. This contains fields and options for configuring and activating a domain in Guardian. For instructions on using this wizard, see Activate Domain on page 47 in Tasks.
Domain Deactivation Wizard | In Domain Explorer, right-click on a domain entry and select Deactivate Domain from the context menu to open this wizard. This contains a table of all active domains. For instructions on using this wizard, see Deactivate Domain on page 49 in Tasks.
Evaluation Wizard | Click Evaluate to open the Evaluation Wizard for evaluating one or more domains. For instructions on using this wizard, see Evaluate Domain on page 57 in Tasks.
Support Case Wizard | Select a signature in an Evaluation Summary and click Get more help from BEA support. This opens the Support Case Wizard for the selected signature. This enables you to create and submit a support case based on the selected signature. For instructions on using this wizard, see Submit Support Case on page 78 in Tasks.
Inventory Wizard | Click Inventory to open the Inventory Wizard. A Domain Inventory is a snapshot of all of the configuration details for a domain as it exists at that moment. For instructions on using this wizard, see Inventory Domain on page 56 in Tasks.
Shortcut Wizard | Select File > New > Shortcut to open the Shortcut Wizard for creating and modifying Shortcuts. For instructions on using this wizard, see Create Shortcut on page 70 in Tasks.
Shortcut Evaluation Wizard | Click the Shortcut Explorer tab to open the Shortcut Explorer. Then, double-click on a Shortcut name in the Shortcut list to open the Shortcut Evaluation Wizard. For instructions on using this wizard, see Evaluate Shortcut on page 72 in Tasks.
Update Wizard | Click Update to open the Update Wizard. This wizard enables you to automatically download new BEA Guardian software and signatures from the BEA Guardian update site. For instructions on using this wizard, see Automatically Update Guardian on page 81 in Tasks. WARNING: Upgrading from Guardian 1.0.x to Guardian 1.1 must be done manually. For instructions, see Manually Update Guardian on page 83 and Manually Update Guardian Registry on page 86 in Tasks.

For a detailed description of each of the Guardian Wizards, see Wizards on page 116 of Reference.

#### Wizard Titlebar Menus

Right-click a wizard titlebar to open a context menu of options to Move, Size, or Close the wizard. You can also move or resize a Wizard by dragging the titlebar or window borders.

## Guardian Online Help System

The Guardian Online Help system has the following structure:

- About BEA Guardian — This section provides an overview of Guardian components, features, and key concepts. Also provided are basic instructions for using and navigating the Guardian User Interface and Online Help System.
- Tasks — This section provides detailed instructions for Guardian tasks and procedures. Tasks are categorized according to the component or feature to which they apply. The Tasks Help folder contains a number of subfolders, one for each task category. Expand a category folder to see the tasks relating to that topic.
- Reference — This section provides a detailed description of the Guardian User Interface components and features, and a detailed reference guide to the Guardian Command Line Interface.

## Guardian Command Line Interface

The Guardian Command Line Interface is a command interpreter that is an executable `.cmd` batch file for Windows, and a `.sh` shell script for Linux. Both the Windows batch file and the Linux shell script are wrappers that accumulate and organize arguments to the Java command. You can invoke the Command Line Interface from a Windows Command Prompt window or a Linux terminal window.

For basic instructions on using the CLI, see Command Line Interface on page 73 on Tasks. For a detailed description of all CLI commands and syntax, see Command Line Interface on page 134 of Reference.

## Key Concepts

This section provides an overview of Guardian components, features, and key concepts. These include:

- Guardian Agent
- Guardian Workspace
- Guardian Registry
- Domain
- Domain Groups
- Domain Inventory
- Signature
- Signature Bundle
- Signature Annotations
- Evaluation
- Snapshot Evaluation
- Evaluation Summary
- Signature Repository
- Shortcut
- Support Case

### Guardian Agent

The Guardian Agent is a lightweight web application that gathers the data used for evaluations.

The Guardian Agent collects the following data:

- JMX data
- Java system properties
- Database metadata for your JDBC connection pools
- J2EE Deployment Descriptors from WebLogic instances
- JRockit JMAPI data
- JRockit Runtime Analyzer data
- JRockit thread dump data

#### Multiple Guardian Agent Threads

If you have one or more managed servers in a domain, the Guardian Agent spawns the appropriate number of threads for communicating between the Guardian Agent on the WebLogic Administration Server, and the Guardian Agent running on the Managed Server(s).

An excessive number of threads can affect the performance of the Administration Server, so Guardian enables you to specify the maximum number of Agent threads that can be spawned. In addition, in order to manage Agent resources on both the Administration and Managed Servers, you can specify the maximum amount of time (in seconds) that can elapse before a thread is terminated. For instructions, see Configure Maximum Agent Threads on page 39 and Configure Agent Thread Timeout on page 40 in Tasks.

### Guardian Workspace

The Guardian Workspace is the directory in which all of your Guardian data is stored. It includes the following data for each domain you have defined in Guardian:

- Preferences
- Domain Inventories
- Evaluation Summaries

When you invoke Guardian, you are prompted to select a location for your Guardian Workspace. To prevent loss of work when Guardian is updated or uninstalled, select a Workspace location outside of the Guardian installation directory (see Select Workspace on page 41).You can also safely back up your Workspace data by exporting your Workspace to a file also located outside of your Guardian Installation directory. For instructions, see Export Workspace on page 42 of About BEA Guardian.

Although the documents in the Guardian Workspace are persisted as XML files, they are best viewed through the Guardian User Interface. The Guardian User Interface provides a number of tools for viewing, managing, and processing your data, as well as better protection against unintended edits or deletions. For basic instructions on using the interface, see Guardian User Interface on page 2. For a detailed description of Guardian User Interface components and features, see Reference. See Tasks, for detailed instructions for using the interface to perform specific Guardian tasks.

### Guardian Registry

The Guardian Registry is an XML document in which your BEA Guardian configuration specifications are maintained. The Guardian Registry is created during product installation, and updated whenever you modify your configuration or perform certain Guardian operations. The Guardian Registry identifies the domains you have activated, the Signature Bundles available for evaluation, the Shortcuts you have defined, and your Guardian Workspace location(s).

### Domain

A domain is a logically related group of WebLogic Server resources that are managed as a unit. A domain always includes at least one WebLogic Server instance called the Administration Server. The Administration Server acts as a central point of contact for server instances and system administration tools. A domain may also include additional WebLogic Server instances called Managed Servers.

Each BEA Guardian installation maintains a Guardian Registry of active domains. A domain is considered active when it is capable of being evaluated. You can activate and deactivate domains at will, and select which to evaluate at any given time.

### Domain Groups

You can organize the domains in Guardian into Domain Groups for easier management. For instructions on creating and managing Domain Groups, see Domain Groups on page 52 in Tasks.

### Domain Inventory

A Domain Inventory is an XML document that describes the products in a Guardian domain. The inventory includes descriptions of your servers, Java Virtual Machines, operating systems, and databases. The descriptions include product versions as well as some configuration settings.

A Domain Inventory is created when you activate or evaluate a domain. The Inventory History is also refreshed each time a domain is evaluated. You can use the Domain Inventory Wizard in the Guardian User Interface to define and generate a new Domain Inventory.

Domain Inventory files are stored and maintained in your Guardian Workspace. You can use the Domain Explorer in the Guardian User Interface to view and manage Domain Inventories.

### Signature

BEA Support has identified patterns in user domains that can cause problems. These patterns are described in XML documents called signatures.

Signatures describe potential problems based on information about your BEA WebLogic Servers and the environment in which they are deployed, including Java Virtual Machines (JVMs), operating systems, and databases. Signatures contain executable logic that can identify specific versions of these products as well as their configuration settings.

In addition to the potential problem description, signatures also contain a remedy recommendation and a severity level: 1-Critical, 2-Warning, or 3-Info.

To detect which signatures apply to your domain, you conduct an evaluation. When the evaluation is complete, the results are displayed in an Evaluation Summary. The Evaluation Summary lists all of the detected signatures, along with the severity level, description, and recommended remedy for each.

Signatures form a primary component of BEA Guardian, since they contain the distilled knowledge of BEA Support for both detecting potential problems and resolving them.

### Signature Bundle

A Signature Bundle is a group of signatures that are evaluated together against one or more specified domains. You can select which bundle to evaluate against which domain(s). Bundles determine the signatures—and consequently, the potential issues—for which to search. The domain(s) you specify determine where to search.

### Signature Annotations

Signature Annotations enable you to tag a detected signature with one or more persistent annotations about that signature.

An annotation contains the following information:

- Type — This indicates the Annotation Type. There are two types: Ignore and Flag.
- Name — (Optional) This is a text field into which you can enter a short name for this annotation.
- Comment — This is a text field into which you can enter comments or other notes about the signature.
- Timestamp — This records the date and time the annotation was created.
- Domains — This specifies the Annotation Target for this annotation for this signature. This can be All Domains, This Domain, or This Evaluation.
- Evaluations — (Automatic) This specifies the Evaluation(s) to which this annotation applies for this signature.

You can use the Annotations Wizard to create, edit, and delete annotations. For instructions, see Signature Annotations on page 64 in Tasks.

In addition, you can use Signature Filters to specify which annotated signatures are to be displayed in the Signature Explorer, Bundle Explorer, and Evaluation Summaries. For instructions, see "Filter Annotated Signatures" on page 68 in Tasks. For complete instructions on using filters, see Filter Signatures on page 63 in Tasks.

### Evaluation

To detect which signatures apply to your domain, you conduct an evaluation. When the evaluation is complete, the results are displayed in an Evaluation Summary. The Evaluation Summary lists all of the detected signatures, along with the severity level, description, and recommended remedy for each.

### Snapshot Evaluation

A Snapshot Evaluation is a complete assessment of all of the configuration details for a specific domain, at the particular moment the evaluation is executed.

You can compare two Snapshot Evaluations to see very quickly the differences between configurations for two domains, or the same domain at different points in its history. For instructions, see Compare Inventories or Evaluations on page 60 of Tasks.

### Evaluation Summary

The results of an evaluation are displayed in an Evaluation Summary. The Evaluation Summary lists all of the signatures from the specified bundle that were detected for the evaluated domain, along with the severity level, description, and recommended remedy for each signature.

### Signature Repository

The Signature Repository contains the locally persisted store of signatures available for evaluation. When you download signatures from the Guardian update site, they arrive in a Java Archive (JAR) file. The JAR file is stored in the `repository/archives` directory of your Guardian installation directory.

### Shortcut

A Shortcut enables you to streamline the evaluation procedure by predefining and storing the domain, Signature Bundle, and other parameters for evaluations that you perform frequently. You can then evaluate the Shortcut, saving you the effort of re-entering the parameter values each time you want to run the evaluation.

### Support Case

A support case is a record created when you submit technical questions or issues to BEA Support. Customers with a support contract can open a support case on the BEA eSupport website or by calling BEA Customer Support.

Guardian enables you to open a BEA Customer Support case directly from a Guardian evaluation. When you conduct an evaluation that detects a signature, you can create and submit a support case directly from a selected signature in an Evaluation Summary. Guardian automatically creates the case and includes all of the information from the signature and submits it, enabling a BEA support engineer to begin working on your case right away. You can also add any additional attachments and notes before sending the support case to BEA

You also have the option not to submit the case immediately at the time of creation, but rather to save the case data as a Case Creation Archive for later submission. Case Creation Archives are stored as files with the file name extension `.car`.

To learn more about BEA Support and support cases, see the BEA Customer Support Guidebook, which you can download from the BEA eSupport website.

## Security

### Authentication

To safeguard your domains, Guardian requires valid login credentials for all communications between Guardian and your Guardian domains. Whenever you conduct an evaluation or activate a domain, Guardian prompts you for the username and password of an Administrator or Monitor account on the target domain. You can choose to store the username and password so you do not have to enter them for every evaluation. All usernames, passwords, and server names persisted on disk are encrypted.

### Data Encryption

Any passwords, usernames, or server names persisted on disk are encrypted. This encryption helps prevent the disclosure of any clear text data that could compromise the security of your domain. SSL encryption is available for communication between Guardian and your domains and between Guardian and BEA. Guardian uses 128 bit open source encryption for SSL.

### Secure Transmission

Secure Sockets Layer (SSL) encryption is available for all communication with BEA over the Internet, and all communication with Guardian Agents in your target domain(s). Please note that Guardian uses 128 bit open source encryption for SSL. If you want to use SSL, there are three types of communication to consider:

- Target domain communication - To use SSL encryption for communications between BEA Guardian and your target domain(s), select the https:// communications protocol option in the Domain Activation Wizard. For instructions, see Activate Domain on page 47 of Tasks.
- Signature downloads - To use SSL encryption when downloading signatures from BEA Support, select Require SSL in the Guardian Preferences configuration page. This will also set SSL encryption for uploading signature usage statistics (see Privacy on page 25). For instructions on configuring your Guardian preferences, see Preferences on page 44 of Tasks.
- Support case creation - To use SSL encryption when opening support cases with BEA Support, select Require SSL in the Guardian Preferences configuration page. For instructions on configuring your Guardian preferences, see Preferences on page 44 of Tasks.

## Privacy

When you download signatures into Guardian from BEA Support, BEA collects high level statistics about your signature usage, including the number of times each signature was evaluated and detected. No customer data is included in the usage statistics. This information is used only in aggregate to assess the effectiveness of each signature. This data is crucial to the continuous improvement of BEA Guardian.

The signature usage statistics contain the following information:

- `signature id` — This is the unique identifier for the signature.
- `type` — This is the category of the signature.
- `fired` — This is the number of times the signature was considered for use. This also includes the number of times the signature was disqualified before evaluation due to targeting products not present on the domain.
- `evaluated` — This is the number of times the signature was actually compared against the target domain.
- `detected` — This is the number of times the signature was actually found on the target domain

The following is a sample signature usage statistic:

`<?xml version="1.0" encoding="UTF-8"?>
<usage>
<signature id="123456.sig" type="Evaluation" fired="30" evaluated="18" detected="2" />
<signature id="234567.sig" type="Evaluation" fired="30" evaluated="20" detected="1" />
</usage>`

## Key Tasks

There are many ways to configure and use Guardian to diagnose the health of your domains. However, there are four essential tasks that can be considered the primary functions of Guardian. These are as follows:

- Activate Domain
- Inventory Domain
- Evaluate Domain
- Update Guardian

The following sections provide a brief description of each of these tasks. For a complete description of all Guardian tasks and procedures, see Tasks.

### Activate Domain

Activating a domain prepares the domain for evaluation and conducts an initial inventory of the domain configuration.

To activate a domain, use the Domain Activation Wizard. For instructions, see Activate Domain on page 26 of Tasks.

### Inventory Domain

A Domain Inventory is a snapshot of all of the configuration details for a domain as it exists at that moment. The results are displayed in a Domain Inventory Overview in the Document Pane. The inventory is also added to the Inventory History folder in the Domain Explorer. Domain Inventories are also generated automatically whenever you activate or evaluate domains.

To inventory a domain, use the Inventory Wizard. For instructions, see Inventory Domain on page 27 of Tasks.

### Evaluate Domain

To detect which signatures apply to your domain, you conduct an evaluation. Guardian collects data about your domain environment, and identifies which signatures apply to the domain.When the evaluation is complete, the results are displayed in an Evaluation Summary. The Evaluation Summary lists all of the detected signatures, along with the severity level, description, and recommended remedy for each.

You can review the Evaluation Summary to determine your response to any signatures that are detected. If you need more help resolving the potential problem identified by the signature, you can use Guardian to create and submit a BEA support case.

For instructions on conducting evaluations, see Evaluate Domain on page 27 of Tasks.

### Update Guardian

BEA Support Engineers create new signatures every day, and new application enhancements to Guardian are also periodically released. The Guardian Update feature enables Guardian to connect directly to the Guardian Update site to automatically download and install new signatures and product updates. To update Guardian on servers that do not have Internet access, you can perform a manual update.

For instructions for performing both automatic and manual updates, see Updates and Upgrades on page 81 of Tasks.

## Example Scenarios

The following scenarios are examples of some of the different ways you can use Guardian to find problems before they impact your environment.

### Scenario 1: Development Cycle Evaluations

As you develop an application and migrate from development to quality assurance to production, you can run an evaluation at each stage. Guardian will help ensure that each phase of your development process is compliant with BEA best practices.

### Scenario 2: Heavy Load Evaluations

Some signatures are designed to evalute runtime domain settings. Running an evaluation under heavy load can detect potential problems that would not otherwise be detected. BEA recommends conducting these evaluations during load and performance testing.

### Scenario 3: Application Update Evaluations

After you update an existing application, you can run an evaluation to assess the deployment. Guardian will help you find any potential problems that could impact your upgrade.

### Scenario 4: Vendor Software Update Evaluations

After you install a new BEA patch, service pack, or upgrade, or install or upgrade third party software, you can run an evaluation to identify any new issues that may have been introduced.

### Scenario 5: Post Repair Evaluations

If Guardian earlier detected a signature, and you subsequently applied the remedy or made other changes to your system, you can run an evaluation to confirm that the signature is no longer detected and no new issues were introduced.

### Scenario 6: Post Domain Change Evaluations

If you made changes to your domain configuration or settings, you can run an evaluation to confirm that the result is compliant with BEA best practices.

### Scenario 7: Scheduled Overnight Evaluations

If you are concerned about domain settings being incorrectly changed overnight, or your domain is approaching certain resource limits, you can schedule evaluations to run overnight. You can review the Evaluation Summary in the morning and decide if any detected signatures merit further investigation.

### Scenario 8: Heartbeat Evaluations

Guardian evaluations are designed to have as minimal an impact on throughput and CPU usage as possible. If your domain has extra capacity, you can schedule Guardian to run evaluations at regular intervals; for example, every 15 minutes. Then, if any changes are made or certain thresholds are reached, you can be notified quickly.

### Scenario 9: Diagnostic Evaluations

If you notice a problem on your domain, you can run an evaluation. Even if an earlier evaluation detected no signatures, something may have changed since that time to cause the new problem. Guardian can be your first line of defense in diagnosing and repairing domain problems.

## Supported Configurations

Supported Configurations are the environments in which the BEA Guardian application can be installed and run. This is distinct from the Supported Targets, which are the environments that Guardian can target for evaluations.

Note: | Guardian requires Java Version 5 or above.

Guardian supports the following environments:

Table 1-11 Supported Operating Systems
Operating System | Vendor/Version
--- | ---
Windows | XP, 2003, 2000
Linux | Red Hat Enterprise Linux 3, 4
Note: | Requires Mozilla

Table 1-12 Supported Java Runtime Versions
Java Runtime Environment Version | Vendor
--- | ---
V5 (also known as V1.5) or above | JRockit, Sun

## Supported Targets

Supported Targets are the environments that BEA Guardian can target for evaluations. This is distinct from Supported Configurations, which are the environments in which the Guardian application itself can be installed and run.

Basically, Guardian can target any platform for evaluation that allows it to install and communicate with the Guardian Agent. In addition, the Guardian Agent itself must have access to a specific set of Java system information properties and methods. The BEA products capable of supporting these operations are based on WebLogic Server versions 8.1 and above.

The following BEA product versions are supported:

Note: | For the most current information on Supported BEA product versions, please see the Guardian 1.1 Release Notes.

Table 1-13 Supported BEA Product Versions
BEA Product | Versions
--- | ---
AquaLogic Data Services Platform | 2.0 and above
AquaLogic Service Bus | 2.1 and above
JRockit JDK | Please see Guardian 1.1 Release Notes.
WebLogic Communications Platform SIP Server | 3.0 and above
WebLogic Integration | 8.1 and above
WebLogic Platform | 8.1 and above
WebLogic Portal | 8.1 and above
WebLogic RFID Enterprise Server | 1.1 2.0
WebLogic Server | 8.1 and above
WebLogic Virtual Edition | 1.1