Cisco ACE XML Gateway User Guide (Software Version 6.1) - Managing the Policy [Cisco ACE XML Gateways]

Table Of Contents

Managing the Policy

About Policies

Working with Subpolicies

About the Shared Subpolicy

Creating a Subpolicy

Changing the Active Subpolicy

Deploying from a Subpolicy

Deleting a Subpolicy

Copying Objects Between Subpolicies

Reorganizing the Policy

Migrating Policy Objects

Exporting and Importing Policies with PPF Files

Exporting the Policy to a PPF

Importing a Policy

Miscellaneous Policy Administration Tasks

Saving a Policy to the Archive History

Restoring a Policy

Comparing Policy Versions

Automated Policy Review

Discarding Policy Changes

Policy Statistics Information

Clearing the Policy History

Policy Component Search by ID

Managing the Policy

This chapter describes how to manage an ACE XML Gateway policy. It covers these topics:

•About Policies

•Working with Subpolicies

•Copying Objects Between Subpolicies

•Exporting and Importing Policies with PPF Files

•Miscellaneous Policy Administration Tasks

About Policies

The policy contains the complete set of rules and behaviors that control how the ACE XML Gateway handles traffic. As the primary development environment for a policy, the ACE XML Manager web console provides many features for policy administration and maintenance. In particular, these features are available in the Policy Manager.

While logged in to the console as a user with administrative privileges, you can view the Policy Manager page by clicking the Policy Manager link near the bottom of the Policy section of the navigation menu.

The Policy Manager page is organized into these areas:

•Last Deployed refers to the version of the policy as last deployed. This is the version of the policy currently enforced at the ACE XML Gateway.

•Manager Policy contains controls applicable to the working version of the policy, that is, the one currently under development in the console. Among other tasks, you can save the current working version to the policy history list, without deploying the policy, and view change information.

•The policy history list shows past versions of the policy. When you deploy the policy, the policy version as deployed is automatically saved to the policy archive. Also, you can manually save the current working version of the policy to the history list at any time.

•When the ACE XML Manager is configured for approval-based deployment, the Approved or Deploy settings appear, depending on the role of the logged in user:

–The Approved pane lists those policies that are approved, and available to be deployed.

–The Deploy row of the working policy's section enables an administrator to begin the process of deploying the working policy. If approval-based deployment is enabled and you are not the administrator, this area is named Submit and you can use it to request administrative approval of unapproved policies.

As the single point for controlling the Gateway's rules and behaviors, a policy can grow to contain a large number of objects and service definitions. Subpolicies enable you to organize policy objects within the policy. Since access to subpolicies can be controlled in the web console, they can divide a policy into areas of concern corresponding to different teams that develop or administer the policy.

This chapter covers these features, as well as other considerations for developing and maintaining the ACE XML Gateway policy.

Working with Subpolicies

A subpolicy allows you to organize objects and settings within a policy. A policy can have any number of subpolicies. Subpolicies facilitate team-based development, since they partition objects of concern to different development teams.

By default, the Manager policy contains a predefined subpolicy named Shared. If no other subpolicy is ever added to the policy, the fact that the Shared subpolicy is the context of your policy work will be transparent to you. To use subpolicy features, you will need to define additional subpolicies.

You can place objects in a particular subpolicy by making it active in the console, and then creating the object in the subpolicy. Once a policy object has been created in the subpolicy, it can only be modified when that subpolicy is active in the console.

Objects can be moved between subpolicies. Using the PPF import/export process, you can selectively copy objects from one subpolicy to another. This process is useful for reorganizing objects among subpolicies, as well as migrating objects between environments that otherwise use different subpolicies.

About the Shared Subpolicy

The predefined Shared subpolicy has several unique properties for a subpolicy. The objects and resources it contains are available for use in other subpolicies. (The contents of other subpolicies are unavailable to other subpolicies, including to Shared.)

Figure 30-1 Shared in relation to user-defined subpolicies

The Shared subpolicy must be active for other subpolicies to be created or removed. In this sense, Shared is the parent of other subpolicies. Accordingly, to transfer subpolicy definitions between environment, you must export a PPF file from the Shared subpolicy and import to the target environment. This replicates the subpolicy definitions (but not the contents of those subpolicies) from the target to the source policies.

Keep in mind, however, that Shared does not contain the subpolicies in any other sense. That is, the contents of other subpolicies are not part of Shared. Each subpolicy must be deployed or removed independently to change the policy.

The export process allows you to write a policy to a file for archiving or sharing. Policies are written to a Portable Policy Format (PPF) file. When exporting from Shared, only the objects in Shared are written to the file. When exporting from a user-defined subpolicy, parts of Shared may be included in the generated PPF file as well as the contents of the active subpolicy. (For more on exporting PPFs, see "Exporting and Importing Policies with PPF Files" section.)

Since resources in Shared can be used across subpolicies, it will usually hold objects with broad applicability, such as security certificates and port definitions.

A few types objects must be in Shared. These include:

•Content screening rules, both custom and built-in screening rules

•The "Public" authorization group of the Shared subpolicy. This is an internal authorization group to which "public" handlers are assigned.

•The default HTTP port (port 80)

The web console prevents you from attempting to move these object. Otherwise, policy objects can be distributed among subpolicies in various ways. However, service definitions are not intended to be split between subpolicies, that is, you should not have a handler in the Shared subpolicy that routes to a service descriptor in another subpolicy.

While you can use resources that are defined in Shared from other subpolicies, you cannot modify the Shared resources except from the Shared subpolicy. To change resources in Shared, like any subpolicy, you need to make it the active subpolicy in the web console.

As mentioned, objects in other subpolicies can use the objects in Shared. Therefore, Shared is a good place to keep objects that may need to be used across subpolicies, such as HTTP(S) ports 80 and 443, certificate authorities, common back end HTTP servers, and so on.

To ensure the stability of object dependencies from subpolicies to the Shared subpolicy, only the deployed version of Shared is visible in other subpolicies. To make Shared resources available to other subpolicies, or changes in Shared visible in other subpolicies, you must first deploy from Shared. Until deployed, the objects in Shared are unavailable in other subpolicies.

Creating a Subpolicy

To create a subpolicy:

Step 1 As a user with Administrator privileges in the console, set the active subpolicy to Shared.

Creating a new subpolicy requires Shared to be the active policy. If the navigation bar names a subpolicy other than Shared as the active subpolicy, use the Switch button to make Shared the active subpolicy. If the Switch button does not make the Shared subpolicy available to you, you do not have sufficient access privileges to perform this task.

Step 2 In the navigation menu, click the Subpolicies link.

If the Subpolicies link does not appear in the navigation menu, you are not logged in as a user with administrator privileges. You must be an administrator to create subpolicies.

Step 3 Click the Create a New Subpolicy button on the Subpolicies page.

Step 4 In the New Subpolicy page, enter a unique name of the new subpolicy in the Subpolicy Name field.

Step 5 Click Save Changes.

The name of the new subpolicy appears on the Subpolicies page. You can switch to the subpolicy to start developing objects in it immediately.

You may also need to enable access to the new subpolicy for web console users. In the account settings for a user, the web console administrator can set the user to have access to specific subpolicies or to "any subpolicy." Users who are configured to have "any subpolicy" access automatically have access to new subpolicies as they are created. Users with access to select subpolicies will need to have their account changed to include the new subpolicy, if appropriate, from the User Administration page.

Changing the Active Subpolicy

After you create a subpolicy, users who want to start working on the subpolicy can use the Switch button at the top of the console to activate the subpolicy.

The Switch button only appears in the console if more than one subpolicy (other than Shared) exists in the policy and the currently logged in user has access privileges to more than one subpolicy.

When a user makes a particular subpolicy active, it remains active across logins for that user. That is, after logging out and then logging back in, the activated subpolicy will still be active in the console.

Deploying from a Subpolicy

To deploy the objects in a subpolicy, make the subpolicy active and then use the standard deployment procedure to complete the deployment.

Note To deploy a subpolicy, the user needs to have access privileges to Shared as well as the subpolicy that is being deployed.

Deploying from within a subpolicy propagates only the contents of that subpolicy to the Gateway, not the objects in any other subpolicy, including Shared.

In general, only a single subpolicy can be deployed at a time, except when approval-based deployment is enabled. In this case, the administrator can deploy all at once those subpolicies that are approved for deployment.

Deleting a Subpolicy

You can delete a subpolicy by clicking the remove link next to it on the Subpolicies page.

To delete a subpolicy, the subpolicy must be empty. It cannot contain virtual services, authenticators, or other policy objects. The easiest way to remove objects from a subpolicy is to switch to the subpolicy and reset the policy from there. That is, after making the subpolicy you want to remove the active policy, click the Policy Manager link. From the Manager Policy area of the Policy Manager, click the Reset Policy button and complete the reset policy process.

When finished, make the Shared subpolicy active again and try removing the subpolicy again from the Subpolicies page. When you confirm deletion, the subpolicy is immediately removed from the console.

Copying Objects Between Subpolicies

The ACE XML Manager enables console users to copy policy objects between different subpolicies. While not limited to these scenarios, this feature is primarily intended to support the ability to reorganize objects among subpolicies and migrate objects between policy environments that have different subpolicies

You can copy objects between subpolicies using the Portable Policy Format (PPF) import/export mechanism. The PPF import process merges the objects from a source PPF into the target subpolicy in the Manager, that is, in general, objects that existed in the target subpolicy that were not in the source PPF are retained alongside the imported objects.

The PFF import/export process can run in several modes. In one mode, the Manager imports a subpolicy from a PPF file only if the identities of the source and target subpolicies match. In another mode, the Manager imports the subpolicy even if the source and target subpolicies differ, so that objects can be moved or migrated between subpolicies. This scenario is shown in Figure 30-2.

Figure 30-2 Import from one subpolicy to another

In the import example shown in Figure 30-2, the source PPF would have been generated from the Shared subpolicy. Its contents are imported into the subpolicy mySubpol3. Notice that the target subpolicy does not have to be active in the Manager web console for it to be the import target.

An additional import option applies when the source PPF contains a subpolicy other than Shared. When exporting from a non-Shared subpolicy, the PPF file may contain objects of Shared as well as objects from the user-defined subpolicy. When importing the PPF, you are given the option of also including the contents of Shared in the merge. If selected, both source subpolicies are merged into the target subpolicy, as shown in Figure 30-3.

Figure 30-3 Import from Shared and subpolicy to another subpolicy

The following sections describe the steps for moving objects between subpolicies to reorganize a policy and to migrate policy objects.

Reorganizing the Policy

In many cases, a simple policy can sensibly occupy a single subpolicy. However, as the policy grows, the need usually arises for a better organizational model for the policy, one based upon subpolicies.

The following steps provide general steps for reorganizing policy contents by subpolicies, in this case, by moving objects from Shared into a user-defined subpolicy on the same Manager. However, the steps apply as well to simply moving misplaced objects between subpolicies.

For detailed steps, along with background information on exporting and importing PPF files, see "Exporting and Importing Policies with PPF Files" section.

The general steps for moving subpolicy contents:

Step 1 Switch the active subpolicy in the Manager web console to the one from which you want to move objects. To reorganize objects from Shared into subpolicies, first make Shared the active subpolicy.

Step 2 In the Policy Manager page, export the policy to a PPF file by clicking the Export button next to the policy version you want to export.

To export a working policy that has not been deployed yet, you will first need to save the policy to the policy history.

Step 3 Choose the subpolicy that you want to move the objects to, creating a new subpolicy if needed. This destination can be either on the same Manager or a different Manager instance. Log in to the appropriate Manager and switch to the destination subpolicy.

Step 4 In the Policy Manager, click the Import Saved Policy button.

Note For details importing and exporting policies, see "Exporting and Importing Policies with PPF Files" section.

Step 5 In the Upload Policy File page, browse to the PPF file you generated from the source subpolicy.

Step 6 Choose the button labelled Import the contents of the subpolicy in the PPF into "[target subpolicy]", the option for importing objects even if the identities of the source and target subpolicies differ.

If there is more than one subpolicy in the target environment, choose the target subpolicy from the drop-down menu. This would be the new subpolicy to which objects from Shared will be moved.

Figure 30-4 Selecting the import target

Note Only the subpolicies to which the current console user has access privileges appear in the menu.

Step 7 Choose whether the contents of Shared, if present in the source file, should be included or excluded from the import. If reorganizing from Shared to user-defined subpolicies, be sure to enable the option labeled: Include the contents of the PPF's "Shared" subpolicy in the import into "[target subpolicy]".

If the PPF was generated from Shared and you choose the first option, excluding the contents of Shared, nothing will be imported.

Step 8 Click Upload Policy File.

Step 9 In the Import Options page, choose the handler groups to be imported into the target subpolicy. Choose from the service definitions to be moved to the target subpolicy from those originally in the Shared subpolicy.

For a reorganization, it is likely that a subset of the available handler groups would be chosen for import, with the handler groups not imported at this time imported into other subpolicies later.

Step 10 When finished importing the PPF, manually remove the objects from the source subpolicy, Shared in this case. This complete the move of the objects from the source to the target subpolicy.

Step 11 Deploy from both Shared and then the target subpolicy to have the change reflected in the policy at the Gateway, and to ensure the policy compiles and deploys without error.

Notice that if importing from a PPF that contains a user-defined subpolicy and Shared, you can choose to import Shared or only those objects in the user-defined subpolicy.

Migrating Policy Objects

Thorough testing is normally required for a policy before it is placed in a production environment with live traffic. For this reason, policies are usually developed and tested in a test environment before promotion to production. The procedure described in Reorganizing the Policy can be used for policy migration as well as policy reorganization. Policy migration is the process by which development artifacts graduate from one environment to another in their life cycle, for example, from development environment to QA or from QA environment to production. After a target environment (production, for instance) is seeded with a policy imported from the source environment (such as development), the export/import process can be repeated to propagate subsequent changes to the policy.

The ability to update policy objects only applies to objects that have been created in the target policy through the export/import process. If an object is manually created in the target policy, the ACE XML Manager cannot associate it with a corresponding object in the source (testing or development) policy, even if the objects have the same names in their respective policies. When you import objects with the PPF mechanism, the association between objects in the source and target policies are retained. If the original objects are kept in the source subpolicy, changes to it can be applied later to the target policy. Thus, the object copy procedure can be used as a basis for policy migration. When needed, changes to the source objects can be applied to the target environment by the export/import PPF procedure.

Since the source and target subpolicies can be different, subpolicies can be organized sensibly for each environment, without having to duplicate the complete production policy in a given development environment, for instance. Figure 30-5 illustrates an example scenario.

Figure 30-5 Migrating policies with PPF export/import

While the subpolicies may be different, for object updates to work through this mechanism, the source and target objects must have the same identity. In other words, the target objects must have been created by exporting from the source and importing into the target environment.

Two objects that are duplicates, including by name, but have been created separately are not subject to this update capability.

The steps for performing PPF export and import for the purposes of policy migration are similar to those described in section "Reorganizing the Policy" section. The primary difference is that the original objects in the source subpolicy must be retained. If they are, subsequent changes to them can be propagated to the production environment by repeating the procedure. Also note that this procedure can be used across environments, that is, by copying and updating objects from one ACE XML Manager to another or across Gateway clusters.

Certain settings may need to be changed when migrating the policy between network environments. For example, in the development environment, the ACE XML appliances may not be able to access the actual backend services being virtualized. Certain types of testing, such as performance testing, may adversely impact production-level infrastructure. Before promotion, therefore, you may need to modify the policy to change backend service settings, along with other settings.

The policy settings that may need to be modified when the policy is migrated include:

•Private keys, since public/private keypairs are generally host-specific.

•The published hostname clients use to address virtual services at the Gateway. (This hostname is visible in generated WSDL files, which may need to be regenerated and published from the new environment.)

•The development and production networks may differ in availability of certain types of services, such as LDAP servers, backend service providers, and so on. Connection settings for these types of resources may need to be modified at migration time.

Exporting and Importing Policies with PPF Files

From the Policy Manager page you can export the deployed or approved policy, or any policy from the Policy History. When you export a policy, the ACE XML Manager converts all the policy objects to an external format and writes the data to a file. The file uses a proprietary format called Portable Policy Format, identified by the extension .ppf.

You can use the file to perform a transfer by loading it into another ACE XML Manager, and then deploying the policy to the ACE XML Gateways in the target Manager's control. You can also use PPF files to make copies of policies for backup purposes.

The export/import process lets you move policy components selectively; that is, you do not need to export the entire policy. When exporting, you are offered the option of selecting the handler groups to export. Along with the handlers in the handler groups you select, the objects they reference are exported, such as certificates, server objects, and so on.

When exporting a specific subpolicy, if the source subpolicy is one other than the Shared subpolicy, elements of Shared may also be included in the export. At import time, you are given the option of importing the contents from the source and either including or excluding the contents of Shared.

Exporting the Policy to a PPF

To export the policy to a file:

Step 1 As an Administrator or Privileged user with the Operations role, make the subpolicy that you want to export active.

Step 2 Click the Policy Manager link in the navigation menu.

Step 3 In the Policy Manager, click the Export button next to the policy to archive. You can export the currently deployed version of the policy or one saved to the policy history.

Note To archive the current working policy, you must first save it to the policy history by clicking the Save To History button. You can then archive the saved policy version.

The Export Policy page appears.

Figure 30-6 Export Policy

Step 4 In the Filename field, type a name for the generated policy archive file. If you are exporting from a policy version with a description, the Manager generates a default name based on the description. You do not need to add the .ppf extension to the name. The extension is appended to the filename automatically.

Step 5 If the policy contains public/private keypair resources, a checkbox appears that enables you to include the resource in the exported file. Its default setting is to be disabled, since such resources are extremely sensitive. If you do not include it, however, exported objects that depend on the resource will not work properly upon import until you manually modify their resource references.

If you want to include the resources in the file, select the option labelled Include Public/Private Keypair Resources.

Step 6 Optionally, uncheck handler groups that are not to be included in the archive.

Rather than exporting all service definitions, you can export the selected handler groups. Handler groups that are not included in the export are not created when the policy is imported.

The Check All and Uncheck All links provide an easy way to include or exclude all handler groups.

Step 7 Click Export Policy.

The ACE XML Manager creates the archive file using the name you specified.

Step 8 In the dialog box, choose a location to save the file and click OK to save the archive file.

The policy is now saved as a .ppf file. It can now be imported into other Manager environments or into another subpolicy.

Importing a Policy

Importing a Portable Policy Format (.ppf) file into the ACE XML Manager restores it in the Manager web console, where it can be modified or deployed to the ACE XML Gateway. As with policy export, the parts of a policy can be imported selectively. When you import a portion of a policy, it can be merged with the existing policy, so that its changes are blended in with the existing policy (as opposed to completely replacing the existing settings).

If there are objects in the PPF that are the same as objects in the working policy (including by object name), duplicate objects will be created in the working policy unless the object in the PPF was generated by an export from the working policy. For more information, see "Migrating Policy Objects" section. In most cases, the policy import process will be used with an empty target policy or to introduce new objects to a policy.

To import a .ppf file from your local filesystem, follow these steps:

Step 1 Click the Policy Manager link in the navigation menu.

Step 2 Click the Import Saved Policy button in the working policy section of the Policy Manager.

The Step 1 of 3: Upload Policy File page appears.

Step 3 Specify the .ppf file to import by either typing the path to the file in the Policy File field or browsing to the file in the file chooser dialog.

Step 4 You can set Do not show detailed content of subpolicies. It reduces the level of detail normally shown on the following import policy pages. If this option is not selected, the next page displays the list of subpolicies for importing. If selected, the list of handler groups for the subpolicy will not appear, and all handler groups from chosen subpolicies will be imported. Also, with this option selected, the list of changes introduced by the import procedure will be collapsed. To view detailed information, click the expand control for the specific subpolicy.

Step 5 Click the Upload Policy File button.

The Step 2 of 3: Import Options page appears.

Step 6 Depending on how it was generated, a PPF can include the contents of several subpolicies. In the Import Mode settings, choose how you want subpolicies to be handled in the import. Options are:

•Import the contents of the selected subpolicies in the PPF into the subpolicies with the same name

This option allows you to import the contents of several selected subpolicies in the PPF into the target subpolicies using one operation. For each subpolicy from the PPF, the import strategy is the following:

–If a subpolicy with the same name exists in the current policy and you have access to it, the content of the subpolicy in the PPF will be imported into the subpolicy with the same name from the current policy.

–If there is no subpolicy with the same name in the current policy, a new subpolicy with the same identity will be created and the content of the subpolicy in the PPF will be imported into the created subpolicy.

Note To create a new subpolicy, you need to be logged in as an administrator.

–If the source and target subpolicies have different names and you do not have administrator privileges to create a new subpolicy with the same identity, nothing is imported.

•Import the contents of the selected subpolicies in the PPF into "[subpolicy name]"

Moves the objects from the selected subpolicies in the PPF into the target subpolicy regardless of the identities of the source and target subpolicies. With this option selected, objects can be moved between different subpolicies.

If there is more than one subpolicy in the target environment to which you have access privileges, they appear in the drop-down menu. Choose the target subpolicy from the menu.

Step 7 Optionally, uncheck objects that are not to be imported.

The checkboxes on the Import Options page enable you to select objects according to handler group or object type.

Note If the target policy contains custom content screening rules and you include content screening rules in the import, the custom rules are overwritten by the imported policy. In effect, custom content screening rules will be deleted if a policy is imported that does not include those rules. To ensure custom rules are not overwritten, remove the check box selection for custom screening rules.

Unless you are sure that you do not need an object from the policy, leave its box checked. The default set of options imports all objects.

Step 8 Click the Import Policy button.

The Merge with Working Policy page uses the Policy Comparison display to show changes that importing the policy would introduce.

Step 9 Optionally, reject individual changes to policy objects.

Removing the checkmark from the box that appears next to a policy object indicates that the ACE XML Manager is not to make the change the checkbox represents. If you are not sure whether to accept or reject a change, use the default settings.

Step 10 Click the Save Changes button.

The Recent Saved Policy Versions section of the Policy Manager shows the newly imported policy. The new objects and other changes that importing the policy has introduced now appear in the ACE XML Manager web console.

Miscellaneous Policy Administration Tasks

This section lists other administration tasks applicable to policy management, including saving a policy within the policy manager, performing policy comparisons, and so on.

Saving a Policy to the Archive History

The Policy Manager allows you to restore, view, or compare past versions of the policy.

When a policy is deployed, the policy archive is populated automatically with the policy version deployed to the Gateway. The current working policy can also be saved manually. This is useful, for example, for preserving a save point for a policy in development.

To save the current working policy to the policy history manually, follow these steps:

Step 1 Log in to the web console as the Administrator user or Privileged user with the Operations role.

Step 2 Set the active subpolicy to the Shared subpolicy.

In the navigation bar at the top of the Dashboard page, Shared appears to the left of the Switch button.

Step 3 Click the Policy Manager link in the Policy Administration section of the navigation menu.

The ACE XML Manager displays the Policy Manager page.

Step 4 Type an informative description of the working policy into the Version Description field.

It is recommended that you make the description as informative as possible. It may be the only information available to distinguish this policy from potentially many others.

Step 5 Click the Save to History button.

The Recent Saved Policy Versions and Policy History logs display the archived policy with a unique identifier, timestamp, and description you provided.

Using the controls that appear next to the policy entry, you can now specify other operations on the policy, such as:

•viewing the archived policy in the console

•restoring the policy by rolling back the current working policy to the archived one

•exporting it, to save a copy of it to your local disk as a .ppf file

Restoring a Policy

Sometimes you may make changes to a working policy that have unexpected effects. You may find that you have accidentally disabled services, or removed settings that would be a lot of work to restore. One of the most common uses of archived policies is to protect you against such problems by saving that state of a policy that is known to work.

You can recover the earlier working state of the ACE XML Gateway by loading and deploying an archived policy, a process known as restoring or rolling back a policy.

Caution When you restore an archived policy, all of its settings replace all of the settings currently in effect. This means that, for example, if the current policy exposes services that are not defined in the restored policy, or if the restored policy lacks some authenticators that are defined in the one it replaces, some consumers may lose contact with some services. Make sure you know which service descriptors, routes, authenticators, and other policy objects are likely to change before you restore a policy, and be prepared to spend some time inspecting the resulting configuration and logs in order to ensure that all needed service connections are restored properly.

To restore a policy:

Step 1 As an Administrator or a Privileged user with the Operations role in the console, set the active subpolicy to the Shared subpolicy.

Step 2 Click the Policy Manager link in the Policy Administration section of the navigation menu.

Step 3 In the Policy Manager page, find the policy to restore.

The ACE XML Manager archives policies in the Recent Saved Policy Versions history, at the bottom of the Policy Manager page. To view older archives, click the View Full History link in the policy history banner.

To restore a policy that has been removed from the ACE XML Gateway instance, you must first upload the policy archive file from your offline storage using the Import Saved Policy button in the Import pane of the working policy section. After uploading, the policy appears in the policy archive lists.

Step 4 If the policy was archived on a different Gateway instance then you may need to migrate it before restoring.

Step 5 Click the Import Policy button to load the policy into the ACE XML Manager web console for compilation and deployment.

The settings and objects defined by the archived policy replace those currently defined in the ACE XML Manager.

Step 6 Click the Deploy button to begin the usual deployment process.

The ACE XML Manager compiles and deploys the archived policy, making it the currently active policy in the ACE XML Gateway instance.

Comparing Policy Versions

The Policy Comparisons page (Figure 30-7) shows differences between two policy versions. It appears automatically at various points in policy development, such as when you deploy the policy. You can also compare two versions of a policy manually from the Policy Manager. In the Policy Manager, you can compare any two previous versions of a policy from the policy history list. A version of the policy is saved to the list at each deployment and when saved directly using the Save To History button.

Figure 30-7 Compare Policies Page

As shown in figure, the Policy Comparison page shows the differences between two policy versions as indicated by these icons:

•A blue plus sign indicates objects being added by the new policy.

•A red x indicates removed objects.

•An orange exclamation point indicates modified objects.

To compare policies manually:

Step 1 Access the policy manager by clicking the Policy Manager link in the navigation menu.

Step 2 To compare the current, working policy against the one deployed at the ACE XML Gateway, click the Compare to Deployed button. This button appears in the working policy area of the page, next to the Review label.

Step 3 To compare two policy versions in the history list, click the Compare Policies link next to the policy archive heading, Recent Saved Policy Versions.

Step 4 In the Select Policy Versions page, click the policy versions to be compared.

Note that the first field contains the policy referred to in the comparison page as policy A, and the lower field contains policy B.

Step 5 Click Compare Policies.

The Compare Policies page shows the differences between the policies you selected. The policy versions you selected are displayed at the top of the page.

Step 6 Click the Go Back button to compare more versions of the policy.

When reviewing a policy, an administrator sees the same Policy Comparisons page, and can accept or reject policy changes in similar fashion. Before approving the policy, the administrator can reject changes that would cause problems. The resulting approved policy incorporates only those changes that the administrator accepts.

Automated Policy Review

The ACE XML Manager can conduct an automated review of a specific approved or working policy, examining it for security issues or consistency problems. In the Approved and -- working policy -- panes of the Policy Manager page, you'll find a Policy Review button.

When you click this button, the ACE XML Manager examines the specified policy version and displays informative warnings if it finds any potential problems. Using the information in these warnings as a guide, you can correct the problems by editing the policy.

Discarding Policy Changes

To discard all changes made to a policy since its initial, installed state, click the Reset Policy button in the Manager Policy area of the Policy Manager.

The ACE XML Manager restores the policy to its initial, empty state, as shown in the compare changes page for the operation. Only proceed if you are sure you want to discard all changes.

Clicking the Reset Policy button discards all changes that have made to the policy. It is very important to note that this action cannot be undone.

Policy Statistics Information

The Policy Statistics page contains the total number of subpolicies, total number of the components in every subpolicy and in the whole policy, number of records in the policy history, and the cluster size. If one of the values exceeds recommended maximum, a warning message will appear.

Recommended values are:

•total subpolicies: 100

•max components per subpolicy: 1000

•total components in policy: 10000

•max records in history: 5000

•cluster size: 1024 Mb

Note that "component" means an internal manager object. The number of visible objects is less than the number of internal objects. For example, one virtual service consists of three internal components: handler, service and access provision. A number of the default components in the shared subpolicy such as: preferences, content security rules and base configuration, impact on the policy statistics too.

The term "cluster size" means the amount of disk space occupied by the cluster data.

Clearing the Policy History

Over the course of time, the size of policy artifacts on disk tends to increase, particularly as policy versions are added to the policy history. Eventually the size of the policy can cause problems with system resources. The feature allows you to remove the old saved and hidden policies from history and all policy components related to them in order to free the disk space.

The Clean History page contains information about the policy history (the number of entries per subpolicy) and the disk space occupied by the cluster.

Clearing the Policy History can be customized by two options:

•Trim history to: The number of recently saved policy history files that you want to retain. Additional history files that are older are deleted from the policy.

•Mode: If there are subpolicies in the Manager, this option lets you specify whether to clear history files for the current subpolicy only or for all subpolicies.

When parameters are selected and the proceed button pressed, the next "Preview changes" page will appear.

Warning Policy cleaning process cannot be undone. If you think you may need to revert to a previously saved policy, make sure you have archived a backup copy of the policy, before you click the Proceed button. When you accept it, the cleaning process will start.

To back up the system, perform the following steps:

Step 1 Access the appliance shell on the appliance you want to backup.

Step 2 Choose Advanced Options > Run Bash.

Step 3 Use the backup command to generate the backup file, as follows:

backup -all <filename>

Where filename is the name of the tgz file that will contain the backup archive. For example:

backup -all applianceBackup.tgz

The -all switch causes all data to be backed up, including network and Gateway configuration settings, the policy filestore, and log files. Alternatively, you can just specify a subset of the data to be backed up by using a command switch, such as:

backup -filestore applianceBackup.tgz

The filestore switch causes all data except log information to be backed up. To back up only log data, use either the -userlog (for the event log), -auditlog, or -traffic switches.

If you do not specify command options, only the network and Gateway configurations are backed up.

For more information, see the section "Backing Up and Restoring the System" in the "Cisco ACE XML Gateway Administration Guide".

Step 4 When the process is completed, the final page with results will appear.

The actual number of remaining policy entries may be greater than the specified due to relations between subpolicies. For example, the following policy entries are never removed during the cleaning process:

•first approved policy; last approved, last deployed policies;

•policies submitted for approval (required in two-stage deployment).

Policy Component Search by ID

This feature allows you to locate a policy component based on its ID, irrespective of the subpolicy where the component is located. The component ID is usually mentioned in the Exception Notification email, which is sent when an exception occurs during the service request processing. This is useful, for example, to quickly find the virtual service or handler associated with the exception message.

To perform the search, enter the 16-hexadecimal digit ID in the field on the Policy Manager page. In the case you have permission to view the component, the search will be performed in the last deployed policy. If you do not have privileges to access the component, the informative message will tell you the location of the component. When a component is not found, the "object missing" error will appear.

	Cisco ACE XML Gateway User Guide (Software Version 6.1)
	Managing the Policy
Cisco ACE XML Gateway User Guide (Software Version 6.1) Preface Introducing the Cisco ACE XML Gateway Basic Concepts First Steps Working with Virtual Services Working with Handlers, Routes, and Service Descriptors Controlling Access to Services Authenticating Requests to Backend Systems Editing and Maintaining Virtual Services Using Variables in Paths Validating Messages Processing SOAP Messages XML Encryption and XML Signature Transforming Messages with XSLT Configuring Destination Server Settings Working with Ports and Hostnames Working with JMS Traffic Working with TIB/RV and MQ Services Working with ebXML Traffic Securing Traffic with SSL/TLS Configuring Reactor Processing Caching Service Responses Mapping HTTP Error Responses Setting Global Traffic Rules Securing Web Applications Working with Virtual Web Applications Working with Profiles Developing Rules and Signatures Managing Resource Files Deploying the Policy Managing the Policy Publishing Service Information Monitoring System Status Managing Web Console Users Managing Gateway Clusters Configuring the Manager Web Console Using the ACE XML Manager SOAP API Troubleshooting Log Messages	Download this chapter Managing the Policy Download the complete book Cisco ACE XML Gateway User Guide Book-Length PDF (PDF - 10 MB) Feedback Table Of Contents Managing the Policy About Policies Working with Subpolicies About the Shared Subpolicy Creating a Subpolicy Changing the Active Subpolicy Deploying from a Subpolicy Deleting a Subpolicy Copying Objects Between Subpolicies Reorganizing the Policy Migrating Policy Objects Exporting and Importing Policies with PPF Files Exporting the Policy to a PPF Importing a Policy Miscellaneous Policy Administration Tasks Saving a Policy to the Archive History Restoring a Policy Comparing Policy Versions Automated Policy Review Discarding Policy Changes Policy Statistics Information Clearing the Policy History Policy Component Search by ID Managing the Policy This chapter describes how to manage an ACE XML Gateway policy. It covers these topics: •About Policies •Working with Subpolicies •Copying Objects Between Subpolicies •Exporting and Importing Policies with PPF Files •Miscellaneous Policy Administration Tasks About Policies The policy contains the complete set of rules and behaviors that control how the ACE XML Gateway handles traffic. As the primary development environment for a policy, the ACE XML Manager web console provides many features for policy administration and maintenance. In particular, these features are available in the Policy Manager. While logged in to the console as a user with administrative privileges, you can view the Policy Manager page by clicking the Policy Manager link near the bottom of the Policy section of the navigation menu. The Policy Manager page is organized into these areas: •Last Deployed refers to the version of the policy as last deployed. This is the version of the policy currently enforced at the ACE XML Gateway. •Manager Policy contains controls applicable to the working version of the policy, that is, the one currently under development in the console. Among other tasks, you can save the current working version to the policy history list, without deploying the policy, and view change information. •The policy history list shows past versions of the policy. When you deploy the policy, the policy version as deployed is automatically saved to the policy archive. Also, you can manually save the current working version of the policy to the history list at any time. •When the ACE XML Manager is configured for approval-based deployment, the Approved or Deploy settings appear, depending on the role of the logged in user: –The Approved pane lists those policies that are approved, and available to be deployed. –The Deploy row of the working policy's section enables an administrator to begin the process of deploying the working policy. If approval-based deployment is enabled and you are not the administrator, this area is named Submit and you can use it to request administrative approval of unapproved policies. As the single point for controlling the Gateway's rules and behaviors, a policy can grow to contain a large number of objects and service definitions. Subpolicies enable you to organize policy objects within the policy. Since access to subpolicies can be controlled in the web console, they can divide a policy into areas of concern corresponding to different teams that develop or administer the policy. This chapter covers these features, as well as other considerations for developing and maintaining the ACE XML Gateway policy. Working with Subpolicies A subpolicy allows you to organize objects and settings within a policy. A policy can have any number of subpolicies. Subpolicies facilitate team-based development, since they partition objects of concern to different development teams. By default, the Manager policy contains a predefined subpolicy named Shared. If no other subpolicy is ever added to the policy, the fact that the Shared subpolicy is the context of your policy work will be transparent to you. To use subpolicy features, you will need to define additional subpolicies. You can place objects in a particular subpolicy by making it active in the console, and then creating the object in the subpolicy. Once a policy object has been created in the subpolicy, it can only be modified when that subpolicy is active in the console. Objects can be moved between subpolicies. Using the PPF import/export process, you can selectively copy objects from one subpolicy to another. This process is useful for reorganizing objects among subpolicies, as well as migrating objects between environments that otherwise use different subpolicies. About the Shared Subpolicy The predefined Shared subpolicy has several unique properties for a subpolicy. The objects and resources it contains are available for use in other subpolicies. (The contents of other subpolicies are unavailable to other subpolicies, including to Shared.) Figure 30-1 Shared in relation to user-defined subpolicies The Shared subpolicy must be active for other subpolicies to be created or removed. In this sense, Shared is the parent of other subpolicies. Accordingly, to transfer subpolicy definitions between environment, you must export a PPF file from the Shared subpolicy and import to the target environment. This replicates the subpolicy definitions (but not the contents of those subpolicies) from the target to the source policies. Keep in mind, however, that Shared does not contain the subpolicies in any other sense. That is, the contents of other subpolicies are not part of Shared. Each subpolicy must be deployed or removed independently to change the policy. The export process allows you to write a policy to a file for archiving or sharing. Policies are written to a Portable Policy Format (PPF) file. When exporting from Shared, only the objects in Shared are written to the file. When exporting from a user-defined subpolicy, parts of Shared may be included in the generated PPF file as well as the contents of the active subpolicy. (For more on exporting PPFs, see "Exporting and Importing Policies with PPF Files" section.) Since resources in Shared can be used across subpolicies, it will usually hold objects with broad applicability, such as security certificates and port definitions. A few types objects must be in Shared. These include: •Content screening rules, both custom and built-in screening rules •The "Public" authorization group of the Shared subpolicy. This is an internal authorization group to which "public" handlers are assigned. •The default HTTP port (port 80) The web console prevents you from attempting to move these object. Otherwise, policy objects can be distributed among subpolicies in various ways. However, service definitions are not intended to be split between subpolicies, that is, you should not have a handler in the Shared subpolicy that routes to a service descriptor in another subpolicy. While you can use resources that are defined in Shared from other subpolicies, you cannot modify the Shared resources except from the Shared subpolicy. To change resources in Shared, like any subpolicy, you need to make it the active subpolicy in the web console. As mentioned, objects in other subpolicies can use the objects in Shared. Therefore, Shared is a good place to keep objects that may need to be used across subpolicies, such as HTTP(S) ports 80 and 443, certificate authorities, common back end HTTP servers, and so on. To ensure the stability of object dependencies from subpolicies to the Shared subpolicy, only the deployed version of Shared is visible in other subpolicies. To make Shared resources available to other subpolicies, or changes in Shared visible in other subpolicies, you must first deploy from Shared. Until deployed, the objects in Shared are unavailable in other subpolicies. Creating a Subpolicy To create a subpolicy: Step 1 As a user with `Administrator` privileges in the console, set the active subpolicy to Shared. Creating a new subpolicy requires Shared to be the active policy. If the navigation bar names a subpolicy other than Shared as the active subpolicy, use the Switch button to make Shared the active subpolicy. If the Switch button does not make the Shared subpolicy available to you, you do not have sufficient access privileges to perform this task. Step 2 In the navigation menu, click the Subpolicies link. If the Subpolicies link does not appear in the navigation menu, you are not logged in as a user with administrator privileges. You must be an administrator to create subpolicies. Step 3 Click the Create a New Subpolicy button on the Subpolicies page. Step 4 In the New Subpolicy page, enter a unique name of the new subpolicy in the Subpolicy Name field. Step 5 Click Save Changes. The name of the new subpolicy appears on the Subpolicies page. You can switch to the subpolicy to start developing objects in it immediately. You may also need to enable access to the new subpolicy for web console users. In the account settings for a user, the web console administrator can set the user to have access to specific subpolicies or to "any subpolicy." Users who are configured to have "any subpolicy" access automatically have access to new subpolicies as they are created. Users with access to select subpolicies will need to have their account changed to include the new subpolicy, if appropriate, from the User Administration page. Changing the Active Subpolicy After you create a subpolicy, users who want to start working on the subpolicy can use the Switch button at the top of the console to activate the subpolicy. The Switch button only appears in the console if more than one subpolicy (other than Shared) exists in the policy and the currently logged in user has access privileges to more than one subpolicy. When a user makes a particular subpolicy active, it remains active across logins for that user. That is, after logging out and then logging back in, the activated subpolicy will still be active in the console. Deploying from a Subpolicy To deploy the objects in a subpolicy, make the subpolicy active and then use the standard deployment procedure to complete the deployment. Note To deploy a subpolicy, the user needs to have access privileges to Shared as well as the subpolicy that is being deployed. Deploying from within a subpolicy propagates only the contents of that subpolicy to the Gateway, not the objects in any other subpolicy, including Shared. In general, only a single subpolicy can be deployed at a time, except when approval-based deployment is enabled. In this case, the administrator can deploy all at once those subpolicies that are approved for deployment. Deleting a Subpolicy You can delete a subpolicy by clicking the remove link next to it on the Subpolicies page. To delete a subpolicy, the subpolicy must be empty. It cannot contain virtual services, authenticators, or other policy objects. The easiest way to remove objects from a subpolicy is to switch to the subpolicy and reset the policy from there. That is, after making the subpolicy you want to remove the active policy, click the Policy Manager link. From the Manager Policy area of the Policy Manager, click the Reset Policy button and complete the reset policy process. When finished, make the Shared subpolicy active again and try removing the subpolicy again from the Subpolicies page. When you confirm deletion, the subpolicy is immediately removed from the console. Copying Objects Between Subpolicies The ACE XML Manager enables console users to copy policy objects between different subpolicies. While not limited to these scenarios, this feature is primarily intended to support the ability to reorganize objects among subpolicies and migrate objects between policy environments that have different subpolicies You can copy objects between subpolicies using the Portable Policy Format (PPF) import/export mechanism. The PPF import process merges the objects from a source PPF into the target subpolicy in the Manager, that is, in general, objects that existed in the target subpolicy that were not in the source PPF are retained alongside the imported objects. The PFF import/export process can run in several modes. In one mode, the Manager imports a subpolicy from a PPF file only if the identities of the source and target subpolicies match. In another mode, the Manager imports the subpolicy even if the source and target subpolicies differ, so that objects can be moved or migrated between subpolicies. This scenario is shown in Figure 30-2. Figure 30-2 Import from one subpolicy to another In the import example shown in Figure 30-2, the source PPF would have been generated from the Shared subpolicy. Its contents are imported into the subpolicy mySubpol3. Notice that the target subpolicy does not have to be active in the Manager web console for it to be the import target. An additional import option applies when the source PPF contains a subpolicy other than Shared. When exporting from a non-Shared subpolicy, the PPF file may contain objects of Shared as well as objects from the user-defined subpolicy. When importing the PPF, you are given the option of also including the contents of Shared in the merge. If selected, both source subpolicies are merged into the target subpolicy, as shown in Figure 30-3. Figure 30-3 Import from Shared and subpolicy to another subpolicy The following sections describe the steps for moving objects between subpolicies to reorganize a policy and to migrate policy objects. Reorganizing the Policy In many cases, a simple policy can sensibly occupy a single subpolicy. However, as the policy grows, the need usually arises for a better organizational model for the policy, one based upon subpolicies. The following steps provide general steps for reorganizing policy contents by subpolicies, in this case, by moving objects from Shared into a user-defined subpolicy on the same Manager. However, the steps apply as well to simply moving misplaced objects between subpolicies. For detailed steps, along with background information on exporting and importing PPF files, see "Exporting and Importing Policies with PPF Files" section. The general steps for moving subpolicy contents: Step 1 Switch the active subpolicy in the Manager web console to the one from which you want to move objects. To reorganize objects from Shared into subpolicies, first make Shared the active subpolicy. Step 2 In the Policy Manager page, export the policy to a PPF file by clicking the Export button next to the policy version you want to export. To export a working policy that has not been deployed yet, you will first need to save the policy to the policy history. Step 3 Choose the subpolicy that you want to move the objects to, creating a new subpolicy if needed. This destination can be either on the same Manager or a different Manager instance. Log in to the appropriate Manager and switch to the destination subpolicy. Step 4 In the Policy Manager, click the Import Saved Policy button. Note For details importing and exporting policies, see "Exporting and Importing Policies with PPF Files" section. Step 5 In the Upload Policy File page, browse to the PPF file you generated from the source subpolicy. Step 6 Choose the button labelled Import the contents of the subpolicy in the PPF into "[target subpolicy]", the option for importing objects even if the identities of the source and target subpolicies differ. If there is more than one subpolicy in the target environment, choose the target subpolicy from the drop-down menu. This would be the new subpolicy to which objects from Shared will be moved. Figure 30-4 Selecting the import target Note Only the subpolicies to which the current console user has access privileges appear in the menu. Step 7 Choose whether the contents of Shared, if present in the source file, should be included or excluded from the import. If reorganizing from Shared to user-defined subpolicies, be sure to enable the option labeled: Include the contents of the PPF's "Shared" subpolicy in the import into "[target subpolicy]". If the PPF was generated from Shared and you choose the first option, excluding the contents of Shared, nothing will be imported. Step 8 Click Upload Policy File. Step 9 In the Import Options page, choose the handler groups to be imported into the target subpolicy. Choose from the service definitions to be moved to the target subpolicy from those originally in the Shared subpolicy. For a reorganization, it is likely that a subset of the available handler groups would be chosen for import, with the handler groups not imported at this time imported into other subpolicies later. Step 10 When finished importing the PPF, manually remove the objects from the source subpolicy, Shared in this case. This complete the move of the objects from the source to the target subpolicy. Step 11 Deploy from both Shared and then the target subpolicy to have the change reflected in the policy at the Gateway, and to ensure the policy compiles and deploys without error. Notice that if importing from a PPF that contains a user-defined subpolicy and Shared, you can choose to import Shared or only those objects in the user-defined subpolicy. Migrating Policy Objects Thorough testing is normally required for a policy before it is placed in a production environment with live traffic. For this reason, policies are usually developed and tested in a test environment before promotion to production. The procedure described in Reorganizing the Policy can be used for policy migration as well as policy reorganization. Policy migration is the process by which development artifacts graduate from one environment to another in their life cycle, for example, from development environment to QA or from QA environment to production. After a target environment (production, for instance) is seeded with a policy imported from the source environment (such as development), the export/import process can be repeated to propagate subsequent changes to the policy. The ability to update policy objects only applies to objects that have been created in the target policy through the export/import process. If an object is manually created in the target policy, the ACE XML Manager cannot associate it with a corresponding object in the source (testing or development) policy, even if the objects have the same names in their respective policies. When you import objects with the PPF mechanism, the association between objects in the source and target policies are retained. If the original objects are kept in the source subpolicy, changes to it can be applied later to the target policy. Thus, the object copy procedure can be used as a basis for policy migration. When needed, changes to the source objects can be applied to the target environment by the export/import PPF procedure. Since the source and target subpolicies can be different, subpolicies can be organized sensibly for each environment, without having to duplicate the complete production policy in a given development environment, for instance. Figure 30-5 illustrates an example scenario. Figure 30-5 Migrating policies with PPF export/import While the subpolicies may be different, for object updates to work through this mechanism, the source and target objects must have the same identity. In other words, the target objects must have been created by exporting from the source and importing into the target environment. Two objects that are duplicates, including by name, but have been created separately are not subject to this update capability. The steps for performing PPF export and import for the purposes of policy migration are similar to those described in section "Reorganizing the Policy" section. The primary difference is that the original objects in the source subpolicy must be retained. If they are, subsequent changes to them can be propagated to the production environment by repeating the procedure. Also note that this procedure can be used across environments, that is, by copying and updating objects from one ACE XML Manager to another or across Gateway clusters. Certain settings may need to be changed when migrating the policy between network environments. For example, in the development environment, the ACE XML appliances may not be able to access the actual backend services being virtualized. Certain types of testing, such as performance testing, may adversely impact production-level infrastructure. Before promotion, therefore, you may need to modify the policy to change backend service settings, along with other settings. The policy settings that may need to be modified when the policy is migrated include: •Private keys, since public/private keypairs are generally host-specific. •The published hostname clients use to address virtual services at the Gateway. (This hostname is visible in generated WSDL files, which may need to be regenerated and published from the new environment.) •The development and production networks may differ in availability of certain types of services, such as LDAP servers, backend service providers, and so on. Connection settings for these types of resources may need to be modified at migration time. Exporting and Importing Policies with PPF Files From the Policy Manager page you can export the deployed or approved policy, or any policy from the Policy History. When you export a policy, the ACE XML Manager converts all the policy objects to an external format and writes the data to a file. The file uses a proprietary format called Portable Policy Format, identified by the extension `.ppf`. You can use the file to perform a transfer by loading it into another ACE XML Manager, and then deploying the policy to the ACE XML Gateways in the target Manager's control. You can also use PPF files to make copies of policies for backup purposes. The export/import process lets you move policy components selectively; that is, you do not need to export the entire policy. When exporting, you are offered the option of selecting the handler groups to export. Along with the handlers in the handler groups you select, the objects they reference are exported, such as certificates, server objects, and so on. When exporting a specific subpolicy, if the source subpolicy is one other than the Shared subpolicy, elements of Shared may also be included in the export. At import time, you are given the option of importing the contents from the source and either including or excluding the contents of Shared. Exporting the Policy to a PPF To export the policy to a file: Step 1 As an `Administrator` or `Privileged` user with the `Operations` role, make the subpolicy that you want to export active. Step 2 Click the Policy Manager link in the navigation menu. Step 3 In the Policy Manager, click the Export button next to the policy to archive. You can export the currently deployed version of the policy or one saved to the policy history. Note To archive the current working policy, you must first save it to the policy history by clicking the Save To History button. You can then archive the saved policy version. The Export Policy page appears. Figure 30-6 Export Policy Step 4 In the Filename field, type a name for the generated policy archive file. If you are exporting from a policy version with a description, the Manager generates a default name based on the description. You do not need to add the `.ppf` extension to the name. The extension is appended to the filename automatically. Step 5 If the policy contains public/private keypair resources, a checkbox appears that enables you to include the resource in the exported file. Its default setting is to be disabled, since such resources are extremely sensitive. If you do not include it, however, exported objects that depend on the resource will not work properly upon import until you manually modify their resource references. If you want to include the resources in the file, select the option labelled Include Public/Private Keypair Resources. Step 6 Optionally, uncheck handler groups that are not to be included in the archive. Rather than exporting all service definitions, you can export the selected handler groups. Handler groups that are not included in the export are not created when the policy is imported. The Check All and Uncheck All links provide an easy way to include or exclude all handler groups. Step 7 Click Export Policy. The ACE XML Manager creates the archive file using the name you specified. Step 8 In the dialog box, choose a location to save the file and click OK to save the archive file. The policy is now saved as a `.ppf` file. It can now be imported into other Manager environments or into another subpolicy. Importing a Policy Importing a Portable Policy Format (.ppf) file into the ACE XML Manager restores it in the Manager web console, where it can be modified or deployed to the ACE XML Gateway. As with policy export, the parts of a policy can be imported selectively. When you import a portion of a policy, it can be merged with the existing policy, so that its changes are blended in with the existing policy (as opposed to completely replacing the existing settings). If there are objects in the PPF that are the same as objects in the working policy (including by object name), duplicate objects will be created in the working policy unless the object in the PPF was generated by an export from the working policy. For more information, see "Migrating Policy Objects" section. In most cases, the policy import process will be used with an empty target policy or to introduce new objects to a policy. To import a `.ppf` file from your local filesystem, follow these steps: Step 1 Click the Policy Manager link in the navigation menu. Step 2 Click the Import Saved Policy button in the working policy section of the Policy Manager. The Step 1 of 3: Upload Policy File page appears. Step 3 Specify the `.ppf` file to import by either typing the path to the file in the Policy File field or browsing to the file in the file chooser dialog. Step 4 You can set Do not show detailed content of subpolicies. It reduces the level of detail normally shown on the following import policy pages. If this option is not selected, the next page displays the list of subpolicies for importing. If selected, the list of handler groups for the subpolicy will not appear, and all handler groups from chosen subpolicies will be imported. Also, with this option selected, the list of changes introduced by the import procedure will be collapsed. To view detailed information, click the expand control for the specific subpolicy. Step 5 Click the Upload Policy File button. The Step 2 of 3: Import Options page appears. Step 6 Depending on how it was generated, a PPF can include the contents of several subpolicies. In the Import Mode settings, choose how you want subpolicies to be handled in the import. Options are: •Import the contents of the selected subpolicies in the PPF into the subpolicies with the same name This option allows you to import the contents of several selected subpolicies in the PPF into the target subpolicies using one operation. For each subpolicy from the PPF, the import strategy is the following: –If a subpolicy with the same name exists in the current policy and you have access to it, the content of the subpolicy in the PPF will be imported into the subpolicy with the same name from the current policy. –If there is no subpolicy with the same name in the current policy, a new subpolicy with the same identity will be created and the content of the subpolicy in the PPF will be imported into the created subpolicy. Note To create a new subpolicy, you need to be logged in as an administrator. –If the source and target subpolicies have different names and you do not have administrator privileges to create a new subpolicy with the same identity, nothing is imported. •Import the contents of the selected subpolicies in the PPF into "[subpolicy name]" Moves the objects from the selected subpolicies in the PPF into the target subpolicy regardless of the identities of the source and target subpolicies. With this option selected, objects can be moved between different subpolicies. If there is more than one subpolicy in the target environment to which you have access privileges, they appear in the drop-down menu. Choose the target subpolicy from the menu. Step 7 Optionally, uncheck objects that are not to be imported. The checkboxes on the Import Options page enable you to select objects according to handler group or object type. Note If the target policy contains custom content screening rules and you include content screening rules in the import, the custom rules are overwritten by the imported policy. In effect, custom content screening rules will be deleted if a policy is imported that does not include those rules. To ensure custom rules are not overwritten, remove the check box selection for custom screening rules. Unless you are sure that you do not need an object from the policy, leave its box checked. The default set of options imports all objects. Step 8 Click the Import Policy button. The Merge with Working Policy page uses the Policy Comparison display to show changes that importing the policy would introduce. Step 9 Optionally, reject individual changes to policy objects. Removing the checkmark from the box that appears next to a policy object indicates that the ACE XML Manager is not to make the change the checkbox represents. If you are not sure whether to accept or reject a change, use the default settings. Step 10 Click the Save Changes button. The Recent Saved Policy Versions section of the Policy Manager shows the newly imported policy. The new objects and other changes that importing the policy has introduced now appear in the ACE XML Manager web console. Miscellaneous Policy Administration Tasks This section lists other administration tasks applicable to policy management, including saving a policy within the policy manager, performing policy comparisons, and so on. Saving a Policy to the Archive History The Policy Manager allows you to restore, view, or compare past versions of the policy. When a policy is deployed, the policy archive is populated automatically with the policy version deployed to the Gateway. The current working policy can also be saved manually. This is useful, for example, for preserving a save point for a policy in development. To save the current working policy to the policy history manually, follow these steps: Step 1 Log in to the web console as the `Administrator` user or `Privileged` user with the `Operations` role. Step 2 Set the active subpolicy to the Shared subpolicy. In the navigation bar at the top of the Dashboard page, Shared appears to the left of the Switch button. Step 3 Click the Policy Manager link in the Policy Administration section of the navigation menu. The ACE XML Manager displays the Policy Manager page. Step 4 Type an informative description of the working policy into the Version Description field. It is recommended that you make the description as informative as possible. It may be the only information available to distinguish this policy from potentially many others. Step 5 Click the Save to History button. The Recent Saved Policy Versions and Policy History logs display the archived policy with a unique identifier, timestamp, and description you provided. Using the controls that appear next to the policy entry, you can now specify other operations on the policy, such as: •viewing the archived policy in the console •restoring the policy by rolling back the current working policy to the archived one •exporting it, to save a copy of it to your local disk as a `.ppf` file Restoring a Policy Sometimes you may make changes to a working policy that have unexpected effects. You may find that you have accidentally disabled services, or removed settings that would be a lot of work to restore. One of the most common uses of archived policies is to protect you against such problems by saving that state of a policy that is known to work. You can recover the earlier working state of the ACE XML Gateway by loading and deploying an archived policy, a process known as restoring or rolling back a policy. Caution When you restore an archived policy, all of its settings replace all of the settings currently in effect. This means that, for example, if the current policy exposes services that are not defined in the restored policy, or if the restored policy lacks some authenticators that are defined in the one it replaces, some consumers may lose contact with some services. Make sure you know which service descriptors, routes, authenticators, and other policy objects are likely to change before you restore a policy, and be prepared to spend some time inspecting the resulting configuration and logs in order to ensure that all needed service connections are restored properly. To restore a policy: Step 1 As an `Administrator` or a `Privileged` user with the `Operations` role in the console, set the active subpolicy to the Shared subpolicy. Step 2 Click the Policy Manager link in the Policy Administration section of the navigation menu. Step 3 In the Policy Manager page, find the policy to restore. The ACE XML Manager archives policies in the Recent Saved Policy Versions history, at the bottom of the Policy Manager page. To view older archives, click the View Full History link in the policy history banner. To restore a policy that has been removed from the ACE XML Gateway instance, you must first upload the policy archive file from your offline storage using the Import Saved Policy button in the Import pane of the working policy section. After uploading, the policy appears in the policy archive lists. Step 4 If the policy was archived on a different Gateway instance then you may need to migrate it before restoring. Step 5 Click the Import Policy button to load the policy into the ACE XML Manager web console for compilation and deployment. The settings and objects defined by the archived policy replace those currently defined in the ACE XML Manager. Step 6 Click the Deploy button to begin the usual deployment process. The ACE XML Manager compiles and deploys the archived policy, making it the currently active policy in the ACE XML Gateway instance. Comparing Policy Versions The Policy Comparisons page (Figure 30-7) shows differences between two policy versions. It appears automatically at various points in policy development, such as when you deploy the policy. You can also compare two versions of a policy manually from the Policy Manager. In the Policy Manager, you can compare any two previous versions of a policy from the policy history list. A version of the policy is saved to the list at each deployment and when saved directly using the Save To History button. Figure 30-7 Compare Policies Page As shown in figure, the Policy Comparison page shows the differences between two policy versions as indicated by these icons: •A blue plus sign indicates objects being added by the new policy. •A red x indicates removed objects. •An orange exclamation point indicates modified objects. To compare policies manually: Step 1 Access the policy manager by clicking the Policy Manager link in the navigation menu. Step 2 To compare the current, working policy against the one deployed at the ACE XML Gateway, click the Compare to Deployed button. This button appears in the working policy area of the page, next to the Review label. Step 3 To compare two policy versions in the history list, click the Compare Policies link next to the policy archive heading, Recent Saved Policy Versions. Step 4 In the Select Policy Versions page, click the policy versions to be compared. Note that the first field contains the policy referred to in the comparison page as policy A, and the lower field contains policy B. Step 5 Click Compare Policies. The Compare Policies page shows the differences between the policies you selected. The policy versions you selected are displayed at the top of the page. Step 6 Click the Go Back button to compare more versions of the policy. When reviewing a policy, an administrator sees the same Policy Comparisons page, and can accept or reject policy changes in similar fashion. Before approving the policy, the administrator can reject changes that would cause problems. The resulting approved policy incorporates only those changes that the administrator accepts. Automated Policy Review The ACE XML Manager can conduct an automated review of a specific approved or working policy, examining it for security issues or consistency problems. In the Approved and -- working policy -- panes of the Policy Manager page, you'll find a Policy Review button. When you click this button, the ACE XML Manager examines the specified policy version and displays informative warnings if it finds any potential problems. Using the information in these warnings as a guide, you can correct the problems by editing the policy. Discarding Policy Changes To discard all changes made to a policy since its initial, installed state, click the Reset Policy button in the Manager Policy area of the Policy Manager. The ACE XML Manager restores the policy to its initial, empty state, as shown in the compare changes page for the operation. Only proceed if you are sure you want to discard all changes. Clicking the Reset Policy button discards all changes that have made to the policy. It is very important to note that this action cannot be undone. Policy Statistics Information The Policy Statistics page contains the total number of subpolicies, total number of the components in every subpolicy and in the whole policy, number of records in the policy history, and the cluster size. If one of the values exceeds recommended maximum, a warning message will appear. Recommended values are: •total subpolicies: 100 •max components per subpolicy: 1000 •total components in policy: 10000 •max records in history: 5000 •cluster size: 1024 Mb Note that "component" means an internal manager object. The number of visible objects is less than the number of internal objects. For example, one virtual service consists of three internal components: handler, service and access provision. A number of the default components in the shared subpolicy such as: preferences, content security rules and base configuration, impact on the policy statistics too. The term "cluster size" means the amount of disk space occupied by the cluster data. Clearing the Policy History Over the course of time, the size of policy artifacts on disk tends to increase, particularly as policy versions are added to the policy history. Eventually the size of the policy can cause problems with system resources. The feature allows you to remove the old saved and hidden policies from history and all policy components related to them in order to free the disk space. The Clean History page contains information about the policy history (the number of entries per subpolicy) and the disk space occupied by the cluster. Clearing the Policy History can be customized by two options: •Trim history to: The number of recently saved policy history files that you want to retain. Additional history files that are older are deleted from the policy. •Mode: If there are subpolicies in the Manager, this option lets you specify whether to clear history files for the current subpolicy only or for all subpolicies. When parameters are selected and the proceed button pressed, the next "Preview changes" page will appear. Warning Policy cleaning process cannot be undone. If you think you may need to revert to a previously saved policy, make sure you have archived a backup copy of the policy, before you click the Proceed button. When you accept it, the cleaning process will start. To back up the system, perform the following steps: Step 1 Access the appliance shell on the appliance you want to backup. Step 2 Choose Advanced Options > Run Bash. Step 3 Use the backup command to generate the backup file, as follows: `backup -all <filename>` Where filename is the name of the tgz file that will contain the backup archive. For example: `backup -all applianceBackup.tgz` The `-all` switch causes all data to be backed up, including network and Gateway configuration settings, the policy filestore, and log files. Alternatively, you can just specify a subset of the data to be backed up by using a command switch, such as: `backup -filestore applianceBackup.tgz` The filestore switch causes all data except log information to be backed up. To back up only log data, use either the `-userlog` (for the event log), `-auditlog`, or `-traffic` switches. If you do not specify command options, only the network and Gateway configurations are backed up. For more information, see the section "Backing Up and Restoring the System" in the "Cisco ACE XML Gateway Administration Guide". Step 4 When the process is completed, the final page with results will appear. The actual number of remaining policy entries may be greater than the specified due to relations between subpolicies. For example, the following policy entries are never removed during the cleaning process: •first approved policy; last approved, last deployed policies; •policies submitted for approval (required in two-stage deployment). Policy Component Search by ID This feature allows you to locate a policy component based on its ID, irrespective of the subpolicy where the component is located. The component ID is usually mentioned in the Exception Notification email, which is sent when an exception occurs during the service request processing. This is useful, for example, to quickly find the virtual service or handler associated with the exception message. To perform the search, enter the 16-hexadecimal digit ID in the field on the Policy Manager page. In the case you have permission to view the component, the search will be performed in the last deployed policy. If you do not have privileges to access the component, the informative message will tell you the location of the component. When a component is not found, the "object missing" error will appear.
	Terms & Conditions \| Privacy Statement \| Cookie Policy \| Trademarks