Policy Server Guides › Policy Server Administration Guide › Policy Server Tools › XPSExport

XPSExport

The XPSExport tool supports the following tasks for migrating Policy Store data:

• Export all the security data.
• Export all the policy data.
• Export all the configuration data.
• Export a portion of the policy data.

You can export a subset of policy data by specifying the identifier of a root object. Specify this identifier in the command line or in a file (using the -xf parameter). Only those objects that do not have a parent class can be exported. For example, to export a realm object, you specify the identifier (XID) of the parent domain for the realm.

You can also create and edit a custom export file using the "shopping cart", or XCart, capability in XPSExplorer (XPSExplorer -xf). You can set the import mode (ADD, OVERLAY, REPLACE, or DEFAULT) on a per object basis in the XCart file. You can then pass the XCart file to XSPExport using the -xf parameter.

Consider the following factors:

• XPSExport does not export keys from the key store. Use the smkeyexport command for this purpose.
• When moving policies from one environment to another, some objects that are environment–specific are included in the export file. Examples of these objects include:
  • Any Trusted hosts
  • Any HCO Policy Server settings
  • Any Authentication scheme URLs
  • Any Password services redirects
  • Any Redirect responses

Depending on the mode you select when using XPSExport, these objects could possibly be added to the new environment or can overwrite existing settings. Be sure that you do not adversely affect environment settings when importing the objects.

Syntax

The syntax of the XPSExport is following:

XPSExport output_file [-xo object_XID] [-xo-add object_XID] [-xo-replace object_XID]
[-xo-overlay object_XID] [-xf file_name] [-xb] [-xe] [-xp] [-xs] [-xc] [-xi] [-xm]
[-f] [-fm] [-q] [-m <number>[%]] [-pass <passphrase>][-npass] [-comment comment] 
[-cf commentpath] [-?] [-vT] [-vI] [-vW] [-vE] [-vF] [-l log_file] [-e err_file] 

Parameters

output_file

The output XML file.

-xo object_XID

Specifies one or more objects for granular export. You can optionally specify one of the following export types:

-xo-add object_XID

Specifies only additions are done during an import.

-xo-replace object_XID

Overwrites the policy data during an import.

-xo-overlay object_XID

Updates the policy data during an import.

-xf file_name

(Optional) Specifies the absolute name of a file that contains the list of XIDs of objects to be exported.

The entries in the file have the following format:

CA.SM::UserDirectory@0e-255e2456-556d-40fb-93cd-f2fed81f656e

ADD = CA.SM::AuthScheme@0d-4afc0e41-ae25-11d1-9cdd-006008aac24b

REPLACE = CA.SM::Agent@01-cb8b3401-a6aa-4794-964e-c569712269c0

OVERLAY = CA.SM::Domain@03-7bdf31f2-44d7-4d7b-a8f5-5de2eaa0b634

These entries correspond to the following command-line parameters:

-xo CA.SM::UserDirectory@0e-255e2456-556d-40fb-93cd-f2fed81f656e
-xo-add CA.SM::AuthScheme@0d-4afc0e41-ae25-11d1-9cdd-006008aac24b
-xo-replace CA.SM::Agent@01-cb8b3401-a6aa-4794-964e-c569712269c0
-xo-overlay CA.SM::Domain@03-7bdf31f2-44d7-4d7b-a8f5-5de2eaa0b634

-xb

(Optional) Exports all the objects of a policy store, including the location of the policy store. The policy store location is set on the Data tab of the Policy Server Management Console.

Important! Any Policy Server to which you import this data uses the policy store that is specified during the export. For example, you export data from Policy Server A, which uses an ODBC database as a policy store. Later, you import the data into Policy Server B, which uses Active Directory as a policy store. The location of the Active Directory policy store for Policy Server B is replaced with the ODBC database location for Policy Server A.

-xe

(Optional) Exports the object types that are related to the execution environment.

-xp

(Optional) Exports the object types that are related to the policies.

The -xe and -xp options cannot be used with -xo, -xo-add, -xo-replace, -xo-overlay, or -xf.

Important! The -xe and -xp options supersede the -xa option to extract all policy data, except federation related objects. You can also use the -xb option, which lets you backup the entire policy store, including Policy Server location-specific data, such as the policy store location.

-xs

(Optional) Exports the entire security data.

-xc

(Optional) Exports the entire configuration data.

-xi

(Optional) Exports the object types that were initially installed.

Example: AgentType

-xm

(Optional) Exports the objects that are specified in an ExtractManifest object.

-f

(Optional) Overwrites the output file.

-fm

(Optional) Uses less memory, but affects the performance.

-q

(Optional) Suppresses progress messages.

-m <number>[%]

(Optional) Indicates that progress messages are output after every <number> of objects.

If the optional percent sign ("%") is included, then <number> is a percentage of the total objects, not a number of objects.

Default: Ten percent.

-pass <passphrase>

(Optional) Specifies the passphrase that is required for encryption of sensitive data. This passphrase must be at least eight characters long and must contain at least one digit, one uppercase, and one lowercase character. The passphrase can contain a space that is enclosed in quotes. If not specified as a command-line option, the export process prompts for a passphrase when sensitive data is being exported.

-npass

(Optional) Specifies that no passphrase is used.

Important! Sensitive data is exported as clear text.

-comment

(Optional) Adds a comment to the output file.

-cf commentpath

(Optional) Obtains the comment from the <commentpath> and adds it to the output file.

-?

Displays command-line help.

-nb

(Optional) Averts the beeps on error.

-vT

(Optional) Sets the verbosity level to TRACE.

-vI

(Optional) Sets the verbosity level to INFO.

-vW

(Optional) Sets the verbosity level to WARNING (default).

-vE

(Optional) Sets the verbosity level to ERROR.

-vF

(Optional) Sets the verbosity level to FATAL.

-l log_file

(Optional) Outputs log to the specified file.

-e err_file

(Optional) Specifies the file to which errors and exceptions are logged. If omitted, stderr is used.

Example

XPSExport PolicyData.xml -xo CA.SM::UserDirectory@0e-255e2456-556d-40fb-93cd-f2fed81f656e
-xo-overlay CA.SM::Domain@03-7bdf31f2-44d7-4d7b-a8f5-5de2eaa0b634

Note: For granular exports, the export type is specified explicitly on the command line or is retrieved from the data dictionary. For dump exports, the export type attribute for all objects is Replace. A load import of the policy data overwrites all of the policy data in the policy store.

If the XPSExport tool encounters any errors in the command-line options, the tool aborts and records the errors in the exception file (or stderr). The export process also aborts when the export of any object fails. The appropriate errors are logged to the exception file (or stderr) and the XML output file (if it has been created) is deleted.

Add Policy Data

The diagram following shows a SiteMinder policy domain named Domain1 in the source policy store that has to be exported and imported to the target policy store.

The target policy store already has a domain with the same name, but there are differences between the two:

• The properties of Realm1 have been updated in the source policy store and consequently have different values from their counterparts in the target policy store.
• There is a Realm2 in Domain1 that does not exist in the target policy store.

To specify a granular import of only one object (Realm2) into the target policy store, the command line on export would look like this:

XPSExport gran-add.xml -xo-add CA.SM: :Domain@03-0fb7bd02-6986-4bb9-b240-c232358958b1 

After a successful import Domain1 in the target policy store has three realms. The properties of Realm1 are not updated, as shown in the figure following.

To specify a granular export of an explicitly specified object (domain) into the target policy store using the add method, use the following command:

XPSExport -ma -xo <object_XID>

-ma

Adds all the objects appearing after this parameter on the command line.

To specify a granular export of all the relevant objects of the explicitly specified object (domain) into the target policy store using the add method, use the following command:

XPSExport -ra -xo <object_XID>

-ra

Adds the relevant system objects of the objects appearing after this parameter on the command line.

Overlay Policy Data

The diagram following shows a SiteMinder policy domain named Domain1 in the source policy store that has to be exported and imported to the target policy store.

The target policy store already has a domain with the same name, but there are differences between the two:

• The properties of Realm1 have been updated in the source policy store and consequently have different values from their counterparts in the target policy store.
• There is a Realm2 in Domain1 that does not exist in the target policy store.

To specify a granular import where the target policy store is updated with the latest changes from the source policy store, the command line on export would look like this:

XPSExport gran-add.xml -xo-overlay CA.SM: :Domain@03-0fb7bd02-6986-4bb9-b240-c232358958b1 

After a successful import the properties of Realm1 on the target policy store are updated, as shown in the figure following.

To specify a granular export of an explicitly specified object (domain) into the target policy store using the overlay method, use the following command:

XPSExport -mo -xo <object_XID>

-mo

Overlays all the objects appearing after this parameter on the command line.

To specify a granular export of all the relevant objects of the explicitly specified object (domain) into the target policy store using the overlay method, use the following command:

XPSExport -ro -xo <object_XID>

-ro

Overlays the relevant system objects of the objects appearing after this parameter on the command line.

Replace Policy Data

The diagram following shows a SiteMinder policy domain named Domain1 in the source policy store that has to be exported and imported to the target policy store.

The target policy store already has a domain with the same name, but there are differences between the two:

• The properties of Realm1 have been updated in the source policy store and consequently have different values from their counterparts in the target policy store.
• There is a Realm2 in Domain1 that does not exist in the target policy store.

To duplicate the contents of the source policy store in the target policy store, the command line on export would look like this:

XPSExport gran-add.xml -xo-replace CA.SM: :Domain@03-0fb7bd02-6986-4bb9-b240-c232358958b1 

After a successful import Domain1 in the target policy store is exactly the same as Domain1 in the source policy store, as shown in the figure following.

To specify a granular export of an explicitly specified object (domain) into the target policy store using the replace method, use the following command:

XPSExport -mr -xo <object_XID>

-mr

Replaces all the objects appearing after this parameter on the command line.

To specify a granular export of all the relevant objects of the explicitly specified object (domain) into the target policy store using the replace method, use the following command:

XPSExport -rr -xo <object_XID>

-rr

Replaces the relevant system objects of the objects appearing after this parameter on the command line.

Merge Policy Data

When you migrate a domain object from one policy store to another, only the explicitly specified object (domain) is migrated. All the relevant objects of the domain (for example, user directories, agents, agent types) are not migrated to the target policy store. Without the relevant system objects, you cannot import the domain to a policy store.

To specify a granular export of an explicitly specified object (domain) into the target policy store using the merge method, use the following command:

XPSExport -mm -xo <object_XID>>

-mm

Merges all the objects appearing after this parameter on the command line.

To specify a granular export of all the relevant objects of the explicitly specified object (domain) into the target policy store using the merge method, use the following command:

XPSExport -rm -xo <object_XID>

-rm

Merges the relevant system objects of the objects appearing after this parameter on the command line.

Note: The Merge option is an alternative to the Add, Replace, or Overlay options. The Merge option is similar to the add option, the only difference being that this option adds not only the missing objects but also adds the missing attributes of the existing objects.