Skip navigation.
Downloads | Product Documentation | Support

Policy Managers Guide

# Importing Policy Data

This section provides instructions and information on how to load your policy data. Before you begin, you should understand the basic concepts of the BEA WebLogic Enterprise Security policy model as described in Security Administration in the Introduction to BEA WebLogic Enterprise Security. You should also know how to edit text files containing program parameters and environment variables for the operating system you are using.

This section covers the following topics:

- Policy Import Tool
- Configuring the Policy Import Tool
- Running the Policy Import Tool
- Errors that Halt the Policy Importing Process

# Policy Import Tool

The Policy Import tool is a Java utility that provides an alternate method of entering policy data (rather than through the Administration Console). The main purpose of using this tool is to reduce the amount of manual data entry required. The Policy Import tool lets you load policy data into the database, distribute that policy, and remove policy data from the database. The Policy Import tool reads and imports policy data that is stored as text using a proprietary format. Each policy element is stored in a separate file, referred to as a policy file. For information on the specific format of these policy elements, see Creating Policy Data Files.

The Policy Import tool has the following features:

- Multi-threaded architecture-Allows for more efficient policy loading.
- Separation of policy elements-Loads multiple files with each file corresponding to one policy element.
- Optimized-Fast import of large policies during initial import.
- Policy Distribution-After importing, use the Policy Import tool to distribute the policy.

Note: Before you can use the Policy Import tool to distribute policy, you must configure the distribution file and enable the policy distribution feature in the distribution configuration file of the policy loader.

- Removing Policy-You can also use the Policy Import tool to remove policy elements from the database.

Note: When running the Policy Import tool on a large policy, the number of records processed may not be synchronized. If multiple threads are used to import the data, when one thread completes before the other cannot be determined. If the threads are set too high, a message may appear indicating that the number of records processed is not synchronized. This is normal and is not a problem for the Policy Import tool.

For a description of the content of Policy files, see Policy Data Files.

Note: If you want to store users, groups, and their attributes in an external store, you can use the Metadata Directory tool, as described in the Administration Application Installation Guide. You cannot import these policy elements using the Policy Import tool.

When exporting the policy, the configuration resources are saved to the following files: `object_config` and `objattr_config`. These two files are not loaded by the policy loader by default. If you want to load the configuration resources, you need to create a directory and copy `object_config`, `objattr_config`, and `binding` into that directory. Rename `object_config` to `object` and `objattr_config` to `objattr`. Then you can configure the policy loader to load these files into this new directory.

# Configuring the Policy Import Tool

The Policy Import tool relies on the configuration file for information on how to load the policy files. You only need to modify the configuration file if you the change the location of the policy files or you want to change some configuration options. The `Domain` parameter is required for successful import. The Policy Import tool uses default values for the other parameters, which are all optional.

This section covers the following topics:

- Setting Configuration Parameters
- Sample Configuration File

## Setting Configuration Parameters

Each configuration parameter has the following format:

>     <Parameter> <Value>

The file paths in the configuration file depend on the directory from which you run the Policy Import tool. You may use the full path filename to avoid directory dependency. Spaces are allowed between parameters and between new lines. Parameter names are case insensitive. Table 5-1 lists the parameters you need to configure for the Policy Import tool.

To create the configuration file (see Listing 5-1 for a complete sample), you need a text editor such as Notepad. Create the file by entering the necessary parameters and parameter values. The following sections describe the contents of a sample configuration file, with a detailed explanation of each parameter and its default value.

Enter the following parts of the configuration file in the format described. These are only sample entries. Your entries depend on the names you create and where your files are stored. An italics font is used here to represent variables that you replace with your own parameter names. You do not need to list the parameters in the configuration file in this order.

There is a sample of a Policy Import configuration file named `policy_loader_sample.conf` located in the ...`/examples/policy` directory. You can modify this file for your own use. BEA recommends that you use this file as a template and customize it for your particular needs.

Note: The configuration parameters are listed in alphabetical order in Table 5-1. This is not the order in which they are listed in the `policy_loader_sample.conf` file.

####

Table 5-1 Configuration Parameters

Parameter | Description
--- | ---
`Action` | Indicates the Action that the Policy Import tool will perform. Supported values are `LOAD` and `REMOVE (case insensitive).` `REMOVE` = Unloads the specific policy from the database. `ADD` = Loads the specific policy data into the database.
ApplicationNode | Specifies the application node that holds the administration policy. If this parameter is commented out, the default value of `admin` is used.
`BLMContext Retries` | Specifies the number of times retries should take place. If the WLES Administration Console server is still starting up, then you need to retry the BLM API Authentication. In most cases the WLES Administration Console server is always running. Default: 100.
`BLMContext Interval_ms` | Specifies the amount of time (in milliseconds) to wait between context retries. DEFAULT: 100ms.
`BulkSize` | Specifies the number of records to send at one time in a thread. Default: 200. Note: When there are multiple threads importing policy data, each processing a number of records, the number of records processed may result in an "out-of-sync" message. However, it does not harm the data when importing the policy. The policy import tool switches to single thread when importing some policy elements, such as resources and declarations, as the later records have dependency on earlier records.
`ConsoleDisplay` | Specifies whether to hide console interaction or not (yes/no). If you want to run the policy loader in the background as a batch process, set to `no`. Default: `yes` `no =` Error messages are not displayed on the console and the user is requested to enter their `Username` and `Password` if they are missing in the configuration file. `yes` = Error messages are displayed on the console. This parameter must be enabled if you want to type in your password on the command prompt, rather then use the one specified in the `password.xml` or in the configuration file.
`Debug` | Specifies whether you want to log debug information. Default: 0 `0` = Does not log debug information. `1` = Sends debug information to the file defined by: `ErrorLogFile.`
`Domain` | Specifies the Enterprise domain name, as assigned during the installation of the Administration Application. Default: `asidomain`. This parameter is required.
`ErrorLogFile` | Specifies the name of error log file. This file is produced if the Importing Tools fails while attempting to load a set of policy files. It contains error messages that describe the failures to assist you in correcting the errors. Default: `error.log`.
Mode | Specifies the mode of operation the Policy Import tool. Values are `INITIAL` or `RECOVER` (case insensitive). Use INITIAL mode the first time you run the Import Policy Tool to load a set of policy files. If you encounter errors in the initial load attempt, check the `ErrorLogFile` for a description of the error, correct the errors in the generated error file(s) (an error file is produced for each policy file that fails), and rerun the Import Policy Tool again, but this time in the RECOVER mode. This way the tool only attempts to load the generated error files. If the tool fails again, fix the errors, and run it again in RECOVER mode. Repeat until no errors are encountered. Note: This parameter can also be passed in as a command-line parameter `-recover` or `-initial`. Values for this parameter on the command line override values specified in the configuration file.
Password | Specifies the `password` for the administrator (optional). The `password` is case sensitive. If the `password` is not specified in the configuration file and the `ConsoleDisplay` parameter is enabled, you are prompted to enter one. Default: `weblogic`. For automation or starting the policy loader without user intervention, uncomment this parameter.
`PasswordFile` | Specifies an encrypted password file. To set up a password file, use the `asipasswd` utility. This utility prompts you for the alias (username) and the password of the user trying to import the policy and then saves the encrypted password in the `password.xml` file. Default: `../ssl/password.xml`. For information on how to use the `asipasswd` utility, "Using the asipasswd Utility to Configure the Metadirectory Password.
`PasswordKey File` | Specifies a private key used to decrypt the password stored and encrypted in the `password.xml` file. To set up a password file, use the `asipasswd` utility. Default: `../ssl/password.key`. For more information about the `asipasswd` utility, see "Using the asipasswd Utility to Configure the Metadirectory Password.
`Policy DirectoryPath` | Specifies the directory path from which to import policy files. For example: ../examples/policy. The path may be relative. Default: "`.`" (for relative)
`Policy Distribution` | Specifies whether the Policy Import tool will distribute policy. If the distribution file is in policy distribution path and PolicyDistribution parameter is set to yes, the policy will be distributed. Supports `YES` or `NO` setting. Default: `YES`. `YES` = The Policy Import tool distributes policy data. `NO` = The Policy Import tool does not distribute data. It only imports it into the database. The Administration Console can then be used to distribute data.
`requestTimeout` | Specifies the time (in milliseconds) to wait for the server to respond. Should be longer for loading large files. May set to infinite `(ASI.INFINITE`) for very large files. Default: 600000
`RunningThread` | Number of threads running concurrently to process the policy import. The value depends on the capacity of the database server. Commonly the optimal value is 2 - 4 or be larger for a high capacity database server. Default: 2.
`StopOnError` | Specifies the action to take after soft exceptions. Takes a value of 0 (Continue) or 1 (Terminate). Default: 0. Note: The Import Policy tool terminates on hard exceptions regardless of the `StopOnError` setting.
`Username` | Specifies the username for the administrator (optional). The `username` is case sensitive. If the `username` is not specified in the configuration file and the `ConsoleDisplay` parameter is enabled, then you are prompted to enter one. Default: `system`. Note: This user must have the privilege to import policy.

For more information on the configuration parameters, refer to the following topics:

- Username and Password
- Policy Import Parameters
- StopOnError Parameter

### Username and Password

Including the username and password in the configuration file is optional and is not recommended because it could be viewed by others who are not authorized to import policy. The username and password can be encrypted and stored in the `password.xml` file. You should set the `PasswordFile` and `PasswordKeyFile` for the policy to automatically retrieve the password using the alias as the username specified in the configuration file. If you do not include these parameters and the console display is enabled (the default setting), you are prompted to enter their values when you run the Policy Import tool. If one of the two parameters is not included in the configuration file and the console display is disabled, the Policy Import tool logs an error and terminates. When entered, the password is not displayed for security reasons.

### Policy Import Parameters

This section of the configuration file specifies parameters that the Policy Import tool uses to import policy data. There are three policy import parameters: `PolicyDirectoryPath`, `RunningThread` and `BulkSize`.

The`PolicyDirectoryPath` parameter specifies the directory path for the policy files. When you start the Policy Import tool, it looks in the directory pointed by `PolicyDirectoryPath` for valid files. The directory path is either a relative or full path. If the value is left empty or the value is a period (.), the current directory of the Policy Import tool is assumed. For example:

>     PolicyDirectoryPath ../examples/policy

The `RunningThread` parameter specifies the number of running threads and depends on the hardware configuration of the database server. The default number is 3. For most database servers, you want to use a value from 2 to 4. For a high-capacity database server, where a high CPU speed and large memory size are allocated, increase this number to improve import performance. If you set this value too high, it may hinder the performance of the Policy Import tool. If this is the case, you can observe `database` `busy` warning messages in the server log file.

The `BulkSize` parameter denotes the size of each bulk load data block per thread in the Policy Import tool; that is, the number of entries imported in a single load using a single connection between server and the database. Increase the parameter value to lessen the time to initiate a connection. If you enter too high a value, the import process slows, which in turn requires higher `RequestTimeout` and `ConnectionTimeout` values. The optimal value is between 50 and 300.

### StopOnError Parameter

In the event of an error, the `StopOnError` parameter determines whether the Policy Import tool continues importing other policy files or terminates. This parameter takes two values: 0, which means continue and only stop on hard exceptions; or 1, which means stop on any error. The Policy Import tool reports an error if a policy file does not exist or if it cannot be opened for reading. At times, the Policy Import tool also logs an `ObjectExistsException` when you are trying to import a policy element that already exists. The exceptions are just messages to inform the user that the Policy Import tool tried to load a policy element, but it was already there. These importing exceptions do not cause the Policy Import tool to terminate.

## Sample Configuration File

Use the sample file shown in Listing 5-1 to guide you through the process of creating your configuration file. Each parameter description includes comments, indicated by the `#` symbol. The sample configuration file assumes that all of your policy files are located in the directory specified by `BEA_HOME``/wles42-admin/examples/policy`.

Note: Be sure to use forward slashes (/) when specifying the policy file directory path.

The sample configuration file also assumes that no policy distribution is performed.

Listing 5-1 Sample Configuration File

>     # Required

>     ## In addition to this file, asi.properties is read in from the WLES_HOME/config
>     ## directory.  Any parameters set here will override values defined there.

>     #### policy domain name, as set in policy database during database installation
>     Domain asidomain

>     # Optional

>     #### A WLES administrator user id and password.
>     #### If either Username or password is not provided, they can be
>     #### entered at prompt (case sensitive).
>     #### They should be same as stored in database.
>     #Username system

>     #### By default password need to be entered at prompt.
>     #### Since it will stored in clear text.
>     #### For automation or starting policy loader without user intervention
>     #### uncomment.
>     #PassWord weblogic

>     #### Encrypted password file
>     #### To set up a password file, use asipasswd utility tool
>     PasswordFile ../ssl/password.xml

>     #### Password key file
>     PasswordKeyFile ../ssl/password.key

>     #### This is the application node that holds the administration policy.
>     #### If commented out it assumes the dafult value of "admin".
>     ApplicationNode admin

>     #### Time in milliseconds to wait for server to respond (10 mins here)
>     #### Should be longer for loading large files,
>     #### possibily infinite (ASI.INFINITE) if very large files
>     RequestTimeout 600000

>     #### Number of Threads Running concurrently
>     #### The value depends on the capacity of the database server
>     #### commonly the optimal value is 2 - 4, or could be larger for high capacity
>     #### DB server
>     RunningThread 2

>     #### If WLES Admin console server is still coming up then you need to retry
>     #### the BLM API Authentication. In most cases the WLES Admin console server will
>     #### always be running.
>     #### Configure the number of times retries should take place (DEFAULT 100)
>     BLMContextRetries 2

>     #### Configure the the amount of time in milli seconds to wait between context
>     #### retries (DEFAULT 100ms)
>     BLMContextInterval_ms 100

>     #### Size for each bulk load. I.e. number of entries loaded in a
>     #### single load(200 here)
>     BulkSize 200

>     #### To specify the the course of action after soft exceptions.
>     #### It takes in value of 0 (Continue) and 1 (Terminate).
>     #### Loader terminates on hard exceptions irrespective of StopOnError value.
>     #### (Terminate here)
>     StopOnError 0

>     #### Loading directory value for loading policy files, value is the
>     #### directory from which the files will be loaded.
>     #### Directory path may be a relative path
>     PolicyDirectoryPath .

>     #### To indicate whether to distribute policy in same operation.
>     #### If distribution file is in policyDistribution path and
>     #### PolicyDistribution parameter is not set to no the policy WILL be
>     #### distributed.
>     #### Parameter takes either yes or no (case insensitive). Default = YES
>     PolicyDistribution yes

>     #### File where all error messages are logged.
>     ErrorLogFile policyImporter.log

>     #### To indicate the Action that the Policy Import tool will perform.
>     #### Values are LOAD or REMOVE (case insensitive). Default = LOAD
>     #Action REMOVE

>     #### To indicate the Mode the Policy Import tool will be in
>     #### Values are INITIAL or RECOVER (case insensitive). Default = INITIAL
>     #### This parameter can also be passed in as a commandline parameter -recover or
>     #### -initial.
>     #### Values on the command line will override values specified in the
>     #### configuration file.
>     #Mode RECOVER

>     #### uncomment if you want to see debug information, Default = 0 (no debug)
>     #Debug 1

>     #### uncomment if you want to hide console interaction (yes/no), default = yes
>     #### If you want to run loader in background/in batch process, set this to no
>     ConsoleDisplay yes

# Running the Policy Import Tool

After you complete the configuration file, you can run the Policy Import tool and import your policy files.

To run the Policy Import tool:

1. Construct your policy files.

You can create your own policy files as described in Sample Policy Files or you can use files that you have exported from your policy database as described in Exporting Policy Data.

2. Create a configuration file to define your policy load.

You can use the`../examples/policy/policy_loader_sample.conf` file as a template for your configuration file. Additionally, for a sample configuration file, see Sample Configuration File.

3. Run the Policy Import tool.

On a Microsoft Windows platform, run

>     policyloader.bat

On a Unix platforms, run:

>     policyloader.sh

4. Check for errors in log file.

Note: If an error occurs, the Policy Loader terminates; you must restart the Policy Import tool. The name of the error file is defined in the your Policy Import tool configuration file by the `ErrorLogFile` parameter. In addition, to distribute policy you need distribute privileges granted to you.

Also, because the Policy Import tool is multi-threaded and each thread writes out to the log when it is complete, you cannot guarantee the order in which each load completes.

The Policy Import tool processes policy files according to a predefined order, and if the policy file is not found, it tries to load the next policy file in the proper order. Records imported successfully are committed to the database. After the import process begins, you cannot go back within the same process and edit changes you have made. If you want to change what you have done, you have to start a new import process. After the import process is complete, you may run the removal operation to reverse the import process.

Note: Because the policy object and configuration object are exported into separate files (`object` vs. `object_config`, and `objattr` vs. `objattr_config`), an application binding is still in one binding file. When loading the exported files, the exported configuration is not loaded by default; therefore, when loading the binding for a configuration, the loader may fail, because is unable to locate the configuration objects. According to the separation above, file "binding" must have the same separation also, `binding` and `binding_config`.

# Errors that Halt the Policy Importing Process

When an `Object Exists Error` occurs, meaning that you created a duplicate policy entry, the import process does not stop. When the Policy Import tool encounters an error other than the `Object Exists Error`, it stops the import process upon reaching the end of the files associated with the current parameter.

Similarly, when you use the `Action REMOVE` command to unload a policy, the removal process does not stop if it cannot locate the target policy entry. The Policy Import tool only stops when it encounters other kinds of errors, unless you set the configuration parameter `StopOnError` to zero. Therefore, if you want to continue the import process after encountering a minor error, set the `StopOnError` parameter to 0. When the import stops, you may correct the errors and run the Policy Import tool again.