|
|
The AquaLogic Enterprise Security Administration Server includes two tools to assist you in managing the contents of the policy store: an import tool and an export tool. Using these tools you can perform the following tasks:
For information about writing policy files, see Advanced Topics. The following sections describe how to use the policy import and export tools:
This section provides instructions and information on how to import policy data to the policy store. It covers the following topics:
| Note: | As of AquaLogic Enterprise Security version 2.5, policy loading is now transactional: all policies are loaded, or none. In addition, the BLMContextManager API has been updated to include transactional methods. |
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 non-XML, easy to read 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 Advanced Topics.
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 Advanced Topics.
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. |
|
|||
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
|
|||
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.
|
|||
Specifies an encrypted password file. To set up a password file, use the
asipassword 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 more information, see
asipassword in the Administration Reference.
|
|||
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 asipassword utility. Default: ../ssl/password.key. For more information, see
asipassword in the Administration Reference.
|
|||
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.
|
For more information on the configuration parameters, refer to the following topics:
Including the 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 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.
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/ales30-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.
# Required
## In addition to this file, asi.properties is read in from the ALES_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 ALES 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
#### Encrypted password file
#### To set up a password file, use asipassword 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
#### 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 ALES Admin console server is still coming up then you need to retry
#### the BLM API Authentication. In most cases the ALES 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
#### 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 data files as described in Advanced Topics. 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.
On a Microsoft Windows platform, run
policyloader.batpolicyloader.sh| 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 distribution privileges granted to you. |
| Note: | 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.
When an Object Exists Error occurs—indicating 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 generates a file named <filename>.<version> (for example, object.1 , object.2) and the error message is logged in the configured error file.
Once the policy loader has finished, you need to check to see if there are any versioned files. If there are such files, this indicates that there were errors in certain files and only the problematic lines from those files have been placed in the versioned files. You can now correct the mistakes in the versioned files and re-run the policy loader in the recover mode. You can do this in two ways. Either:
Now the loader will only try to load the highest version files that has not already been previously loaded. If you corrected priv.1 and there are still problems, then the loader will now generate priv.2 with just the lines that filed. You now have to make the fix in priv.2 and rerun the policy loader in the recover mode. You need to keep doing this until the policy loader does not generate any new version files and the error log file does not have any errors listed in it for the last run.
Policy unloading works similar to policy loading except the order in which the files are read is reversed, and the policy is removed from the database instead of being added.
This section provides instructions and information on how to export policy data from the policy store. It covers the following topics:
Policy exporting allows you to output data from the policy database to text files called policy files. These policy files can be imported back to the same or another policy database using the Policy Import tool, as described in Importing Policy Data. This tool allows you to transfer your policy data easily to a production environment.
To perform policy exporting, you need access to the policy database. In general, you can access the policy database when you are the policy owner or the database administrator.
All the files that are exported by the Policy Export tool are supported by the Policy Import tool. All the files are created even though some files may not contain any records. There are two other files exported: object_config, and objattr_config, that contain the data for SSM configuration. These files also get loaded and are similar to object and objattr respectively in format. These files are split so as to differentiate policy elements from configuration elements. However, the object_config and objattr_config files can be merged into object and objattr respectively, if needed.
Before you begin, perform the following tasks:
Ensure that the directory is not write-protected. The free space that the export requires depends on the size of your existing policy. If your export fails because of insufficient disk space, add more space before attempting the export again. In addition, ensure that the full directory path contains no white space.
Depending on the database system, you need to have the database client installed and configured to connect to the policy database. Make sure all the environment settings are correct.
Make sure you can access the policy database. For example, for Sybase use the isql command or use the sqlplus command for Oracle. You must be the policy owner or database administrator to run the export tool. When exporting, you are asked to provide the information for policy owner, your database login id and password.
/bin subdirectory for the product installation.You must run the exporting scripts in this directory because the scripts need to locate some files relative to this directory.
On a Microsoft Windows platform, you can open a DOS command prompt window and change to this directory.
This procedure exports your policy from the database into formatted text files. You perform this export using the export tool included as part of the Administration Application.
To export the policy data on a Windows platform, perform the following steps:
the \bin directory in the product installation. By default, this directory location is C:\bea\ales30-admin\bin.PATH. Also, ensure that the client environment is set up properly.policyexporter.bat directory
where directory is the target directory for the exported policy files. Be sure to include the full path of the directory. This directory cannot contain white spaces.
When exporting the policy, the configuration resources are saved to the following files: object_config and objattr_config. The Policy Import tool does not import these two files by default. If you want to import 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 Import tool to import these to file in this new directory.
This procedure exports your policy from the database into formatted text files. You perform this export using the Policy Export tool included as part of the Administration Server.
Running the Policy Export tool on Sun Solaris requires the use of a shell script. If you do not normally use this shell or have difficulty running the tool, check with your UNIX system administrator to determine if it is available in your environment. For Linux, you can run this script from a Bourne shell.
To export the policy data on a UNIX platform, perform the following steps:
When exporting the policy, the configuration resources are saved to the following files: object_config and objattr_config. The Policy Import tool does not import these two files by default. If you want to import 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 Import tool to import these to file in this new directory.
Once you have exported the policy data, you can import the exported policy into policy database using the Policy Import tool. The exported policy files are in the format required by the Policy Import tool; however, you need to configure the tool to point to the exported file directory. You also need to create a policy distribution file distribution if you want the policy to be automatically distributed after the import completes. For additional information, see Importing Policy Data.
|