Policy Managers Guide

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Importing and Exporting Policy Data

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:

 


Importing Policy Data

This section provides instructions and information on how to import policy data to the policy store. It covers the following topics:

Policy Import Tool

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: 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.

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

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 7-1 lists the parameters you need to configure for the Policy Import tool.

To create the configuration file (see Listing 7-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 7-1. This is not the order in which they are listed in the policy_loader_sample.conf file.

Table 7-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 ALES Administration Console server is still starting up, then you need to retry the BLM API Authentication. In most cases the ALES 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.

PasswordFile
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.
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 asipassword utility. Default: ../ssl/password.key. For more information, see asipassword in the Administration Reference.
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.
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

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.

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.

Sample Configuration File

Use the sample file shown in Listing 7-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/ales26-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 7-1 Sample Configuration File
# 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

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. Prepare your policy data files.
  2. 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.

  3. Create a configuration file to define your policy load.
  4. 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.

  5. Run the Policy Import tool.
  6. On a Microsoft Windows platform, run

    policyloader.bat

    On a UNIX platform, run:

    policyloader.sh
  7. 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 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.

Understanding How the Policy Loader Works

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.

 


Exporting Policy Data

This section provides instructions and information on how to export policy data from the policy store. It covers the following topics:

Policy Export Tool

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

Before you begin, perform the following tasks:

  1. Locate or create a target directory in which to store the policy files.
  2. 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.

  3. Ensure that the database client is installed and configured, and that you have access to the database.
  4. 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.

  5. Ensure that you can run the tools from the /bin subdirectory for the product installation.
  6. 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.

Exporting Policy Data on Windows Platforms

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:

  1. Open a command window and change to the \bin directory in the product installation. By default, this directory location is C:\bea\ales26-admin\bin.
  2. Ensure that the current path (.) is included your PATH. Also, ensure that the client environment is set up properly.
  3. At the command prompt, type the following command, and then press <Enter>:
  4. 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.

Exporting Policy Data on UNIX Platforms

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:

  1. Open a command window and change to BEA_HOME/ales26-admin/bin directory.
  2. From the command line, enter the following command:
  3. policyexporter.sh

  4. When the script prompts you for the directory in which to save the policy files, type the full path directory name, and then press <Enter>.
  5. When the script completes, a successful message appears.

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.

What's Next

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.


  Back to Top       Previous  Next