Policy Managers Guide
|
 |
 |
|
|
 |
 |
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:
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:
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.
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.
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:
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.
|
Indicates the Action that the Policy Import tool will perform. Supported values are |
|
|
Specifies the application node that holds the administration policy. If this parameter is commented out, the default value of |
|
|
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. |
|
|
Specifies the amount of time (in milliseconds) to wait between context retries. DEFAULT: 100ms. |
|
|
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. |
|
|
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
|
|
|
Specifies whether you want to log debug information. Default: 0
|
|
|
Specifies the Enterprise domain name, as assigned during the installation of the Administration Application. Default: |
|
|
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: |
|
|
Specifies the mode of operation the Policy Import tool. Values are Note: This parameter can also be passed in as a command-line parameter |
|
|
Specifies the For automation or starting the policy loader without user intervention, uncomment this parameter. |
|
|
Specifies an encrypted password file. To set up a password file, use the For information on how to use the |
|
|
Specifies a private key used to decrypt the password stored and encrypted in the For more information about the |
|
|
Specifies the directory path from which to import policy files. For example: ../examples/policy. The path may be relative. Default: " |
|
|
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
|
|
|
Specifies the time (in milliseconds) to wait for the server to respond. Should be longer for loading large files. May set to infinite |
|
|
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. |
|
|
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 |
|
|
Specifies the username for the administrator (optional). The |
For more information on the configuration parameters, refer to the following topics:
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.
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.
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.
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
After you complete the configuration file, you can run the Policy Import tool and import your policy files.
To run the Policy Import tool:
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.
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.
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.
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.
|
|
|