The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The Cisco Policy Suite provides the Policy Builder as an interface for policy management. Policies translate a Service Provider’s business rules into actionable, logical processing methods that the Cisco Policy Suite enforces on the network.
The Cisco Policy Suite ships with some standard base policies that serve as a starting point for customization to suit a Service Provider's specific business rules.
This section covers the following topics:
Saving Policy Builder Configuration Data to a Client Repository
Saving Policy Builder Configuration Data to a Runtime Repository
The Policy Builder uses a Subversion version control repository to store the configuration data created in the UI. The data entered in the UI is translated into XML (Eclipse Modeling Framework xmi files) when saved.
As work is done in the UI, changes are saved to a temporary directory on the pcrfclient01. (The directory is specified in the Repository configuration dialog.) Therefore, you can log out and back in and the latest changes will remain. However, if someone else makes a change and commits, then your local changes are lost.
There are two options for saving configuration changes:
When saving to the client repository, the configuration is pushed to Subversion, but it is saved in a client only repository and not copied over to the runtime environment repository. If you 'Publish to Runtime', the configuration is saved to the client repository and also copied to the runtime environment repository. The CPS servers check the runtime environment repository for changes and will update automatically when changes are committed.
Typically, publishing configuration changes to a lab environment to run tests is best. And then when satisfied with the test results, you can publish the new configuration to a production environment.
As Subversion is a source code tracking repository, each version of a configuration is numbered and stored in the Subversion repository history. Therefore, it is also possible to revert to any version of a configuration. The Policy Builder does not have a way to do this via the GUI, but using the Subversion command line tools, any version of the configuration can be made the current revision. For more information, refer to Subversion documentation for how to use the command line tools.
The CPS deployment installs Subversion and creates a default client and runtime repository. The Subversion repositories are synced using Subversion's Master/Slave replication between the pcrfclient01 and pcrfclient02 nodes.
The Policy Builder start screen shows a dialog that lets you define repositories and choose a repository to check out for editing. A repository definition named “Repository” is installed by default and uses the default client repository (http://pcrfclient01/repos/configuration). The default PB user (qns-svn) with the default password is also setup.
Use this procedure to change any of the following details of client repository:
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list in the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | Click the Edit button. |
Step 4 | In the Repository dialog box, make the required changes. |
Step 5 | Click OK to save the changes to the repository definition. |
This procedure removes a repository from Cisco Policy Builder. This procedure does not delete the actual Subversion repository, just the definition for access in the Policy Builder.
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list on the Choose Policy Builder data... dialog box to select the desired repository. |
Step 3 | Click OK to open the Policy Builder GUI. |
Step 4 | Make the necessary modifications in the Policy Builder. |
Step 5 | To save the modifications done, select , or click the diskette icon on the Policy Builder GUI or use CTRL-S on the keyboard. |
Step 6 | Enter a commit message for the modifications done. |
Step 7 | Click OK. The modified configurations are saved to the client repository for later updating and publishing to the runtime environment. |
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. | ||
Step 2 | Use the drop-down list on the Choose Policy Builder data... dialog box to select the desired repository. | ||
Step 3 | Click OK to open the Policy Builder GUI. | ||
Step 4 | Make changes to configuration data as necessary. For example, if you move from configuration to another configuration without saving the changes, a pop-up Are you sure? dialog box for saving the changes is displayed. | ||
Step 5 | Click
Yes to save the changes. If you want to disable this
notification, click
. This opens
Preferences window.
| ||
Step 6 | Check
Expert
Mode (silently auto-save changes) flag to enable auto-save option.
| ||
Step 7 | Once flag is checked, click Apply and OK to save the changes. |
To put changes into effect and have the Cisco Policy Builder server recognize the configuration changes made in your client session, use the Publish option and save the changes to the server repository.
Note | To save the practice version, publish the client repository to the server. This is the version the server uses for production. |
Do not publish to the Policy Builder unless you are completely satisfied with the configuration data in your client repository.
Use the Policy Builder interface to either commit or set up a commit repository.
Verify your work either by going to a web browser or by looking at the config.properties file.
Unpublish with an SVN delete and restore.
When you are ready to put your Policy Builder changes into production, you need to publish them to Subversion. This preserves version history.
CPS supports to save the unpublished commit messages in a property file into the file system. This file is saved in the user directory under the selected repository location. For different users, Policy Builder will generate different property files.
Policy Builder saves the unpublished commit messages into the file system for the following cases:
When loading Publish dialog box ( ) then saved commit message, if any, appears for that user in Commit Message pane.
While publishing the policy configuration, if publish fails then the entered commit message is saved into the file system.
While publishing the policy configuration, if publish succeeds then remove the message from file for the logged in user.
If you click Cancel on Publish dialog box then the entered commit message is saved into the file system.
If you click Cross (x) on Publish dialog box then the entered commit message is saved into the file system.
When loading Saving to Repository dialog box ( ) then saved commit message, if any, appears for that user in Commit Message pane.
While saving to client repository, if operation fails then the entered commit message is saved into the file system.
While saving to client repository, if operation succeeds then remove the message from file for the logged in user.
If you click Cancel on Saving to Repository dialog box then the entered commit message is saved into the file system.
If you click Cross (x) on Saving to Repository dialog box then the entered commit message is saved into the file system.
Step 1 | To publish in
Cisco Policy Builder, select
Publish dialog box appears.
. The
|
Step 2 | If you have already set up the repository to publish to, just enter a commit message. |
Step 3 | If you have not set up the repository, select Add New Repository from the Publish to: drop-down list and enter the required details for the new repository. For more information, refer to Adding a Client Repository Definition. |
Step 4 | Verify the
changes to Production repository:
|
During publishing, if there are any errors, the Publish dialog box will display the list of unresolved errors.
Note | Policy Builder does not report errors for read-only objects. |
The errors are created in the session and are updated accordingly as the errors are resolved or are newly introduced with respect to their IDs.
The format of error string is as:
<Object_Name> <Feature_Name> :: <Error_String>
If you click No, then the publish does not happen.
If you click Yes then the commit message is amended to include a note that you have committed with # errors. For example, “User forced the Publish with 3 unresolved errors: <user's commit message>”.
You can mask the errors if needed where an error is reported by Policy Builder but can still be loaded by the Policy Server. This allows configuration of CPS so that the specified errors are not displayed and you do not ignore the list of unresolved errors and the real errors are not lost amongst a list of acceptable errors.
The file named maskPublishErrors.txt file is created in the folder /etc/broadhop/pb on Cluster Manager (CM). After creating the file, run build_all.sh from CM to rebuild CPS package and push the changes to each VM. The file is populated with the exact message displayed in the GUI. No wildcarding is allowed (so as to prevent accidentally filtering out important messages). The GUI does not display any messages that are in the maskPublishErrors.txt file. The GUI does not count any messages that are in the maskPublishErrors.txt file. If all of the errors in the list are masked because they are in the file then clicking OK in the Publish dialog will not cause the override dialog to be displayed.
A repository definition named Publish Repository is installed by default and uses the default Runtime repository (http://pcrfclient01/repos/run). The default Policy Builder user (qns-svn) with the default password is also setup. The Runtime repository matches the value setup in the /etc/broadhop/qns.conf file.
The qns.conf file is read by all of the active Policy Server and Policy Director nodes and when the policy server process starts up, it checks out the configuration from the Runtime repository.
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list on the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | After selecting the required repository, click OK. |
Step 4 | Make changes to Policy Configuration data as necessary. |
Step 5 | Select . |
Step 6 | Use the drop-down list to select <Add New Repository>. The Repository dialog box appears. |
Step 7 | Enter the necessary values and click OK to save your work. |
Step 8 | Enter a commit message and click OK to publish to the new repository. |
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list on the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | After selecting the required repository, click OK. |
Step 4 | Make changes to Policy Configuration data as necessary. |
Step 5 | Select . |
Step 6 | Use the drop-down list to select the desired repository. |
Step 7 | In the Repository dialog box, make your changes. |
Step 8 | Click OK to save the changes to the repository definition. |
Step 9 | Enter a commit message and click OK to publish to the new repository. |
This procedure removes a runtime repository definition from the Cisco Policy Builder. This procedure does not delete the actual Subversion repository, just the definition for access in the Policy Builder.
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list on the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | After selecting the required repository, click OK. |
Step 4 | Make changes to Policy Configuration data as necessary. |
Step 5 | Select . |
Step 6 | Use the drop-down list to select the desired repository. |
Step 7 | Click Remove. A confirmation dialog appears. |
Step 8 | Click OK to delete the repository. |
Step 9 | Click Cancel to close the dialog box. |
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list in the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | After selecting the required repository, click OK. |
Step 4 | Make changes to Policy Configuration data as necessary. |
Step 5 | Select . |
Step 6 | Use the drop-down list to select the desired repository. |
Step 7 | Enter a commit message. |
Step 8 | Click OK. The data will be saved to the client repository for later updating and publish to the runtime environment. |
You may have several variations of your client repository. One may reflect the configuration currently published to the server. Another might be developed for test purposes.
There are two ways to switch to a different repository:
There are two main SVN repositories (repos) in the system.
Repository publish which contains ONLY the currently running set of policies.
Runtime repository which contains a copy of the currently running set of policies along with copies of all previous sets.
To rollback Policy Builder changes, there are two methods:
Rollback the configuration repository Policy Builder and then perform a publish as described in Unpublished Changes.
Rollback the runtime repository Policy Builder uses and the configuration repository Policy Builder uses.
For more information, refer to Published Changes.
If you do not want to save the changes, click the Revert link on the Policy Builder start window. All changes that have not been committed to a repository will be removed.
Step 1 | Open a browser and enter the URL of the Cisco Policy Builder. |
Step 2 | Use the drop-down list in the Choose Policy Builder data repository... dialog box to select the desired repository. |
Step 3 | Click the
Revert link. A confirmation dialog appears.
The Revert link is only available if there are uncommitted local changes. |
Step 4 | Click OK to revert changes to the repository definition. |
Step 1 | Check the
configuration repository name Policy Builder uses (config_repo). To check the
name, use the following steps:
| ||
Step 2 | To locate the
‘r’ number in the repository used by Policy Builder, execute the following
command:
svn log http://pcrfclient01/repos/<config_repo> | more The <config_repo> value comes from Step 1.d. The following is an example of the svn log command, where <config_repo> is configuration as shown in Step 1.d. svn log http://pcrfclient01/repos/configuration | more
------------------------------------------------------------------------
r367 | qns-svn | 2015-06-18 12:15:34 -0600 (Thu, 18 Jun 2015) | 1 line
second try
------------------------------------------------------------------------
r364 | qns-svn | 2015-06-17 15:46:19 -0600 (Wed, 17 Jun 2015) | 1 line
corrected java issue
------------------------------------------------------------------------
r361 | qns-svn | 2015-06-16 15:38:28 -0600 (Tue, 16 Jun 2015) | 1 line
Added new Policies
------------------------------------------------------------------------
r358 | qns-svn | 2015-06-16 15:06:57 -0600 (Tue, 16 Jun 2015) | 1 line
""
------------------------------------------------------------------------
r355 | qns-svn | 2015-06-16 14:58:41 -0600 (Tue, 16 Jun 2015) | 1 line
""
------------------------------------------------------------------------
r352 | qns-svn | 2015-06-16 14:52:29 -0600 (Tue, 16 Jun 2015) | 1 line
| ||
Step 3 | Execute the
following command to delete the current version from the configuration
repository Policy Builder uses:
svn delete http://pcrfclient01/repos/<config_repo> -m ‘deleting for rollback’ Use the <config_repo> value from Step 1.d. The following is an example of the svn delete command where <config_repo> is configuration. svn delete http://pcrfclient01/repos/configuration -m ‘deleting for rollback’ | ||
Step 4 | Execute the
following command to restore the Policy Builder configuration repository to a
previous version.
svn cp http://pcrfclient01/repos/<config_repo>@<r_number> http://pcrfclient01/repos/<config_repo> -m ‘rolling back to <r_number>’ The <r_number> value is from Step 2.a and the <config_repo> value is from Step 1.d. The ‘-m’ option should be used to add a comment indicating what is being done. The following is an example of the svn copy command with the <r_number> set to 361 and the <config_repo> set to configuration: svn cp http://pcrfclient01/repos/configuration@361 http://pcrfclient01/repos/configuration -m ‘rolling back to 361’ | ||
Step 5 | Execute the
following command to verify if the rollback is successful:
svn log http://pcrfclient01/repos/<config_repo> | more The <config_repo> value is from Step 1.d. The following is an example of the svn copy command: svn log http://pcrfclient01/repos/configuration | more ---------------------------------------------------------------------- r367 | qns-svn | 2015-06-18 12:15:34 -0600 (Thu, 18 Jun 2015) | 1 line rolling back to 361 -----------------------------------------------------------------------
| ||
Step 6 | Open Policy Builder and verify the polices to which you have rolled back. Normally the customer should be able to verify the policies in Policy Builder. | ||
Step 7 | Perform a publish in Policy Builder and make sure to add a comment indicating that the publish is being done to complete the rollback. For example, “publishing to complete rollback to <r_number>”. |
The Systems node in the Reference Data tab represents the Cisco Policy Suite runtime environment as it exists in the network environment.
System: There must always be at least one system defined in the Policy Builder. The system represents the customer deployment. In HA, the system represents a set of PCRF clusters that share the same session database. System is used to define any common things across the clusters, such as load balancing, and so on.
Cluster: Each system contains one or more clusters - each of which represents a single High-Availability (HA) site environment. A cluster is used for define the configurations related to the blades. A cluster shares the same set of policy directors (that communicates as a group). A customer can take a fully installed PCRF and replicate it to a second cluster.
Each cluster can contain node instances. A node instance corresponds to a physical node in a deployment cluster such as a session manager or load balancer. It is very rare that a deployed system needs to have node instances configured in the Policy Builder. Configurations flow downhill, meaning that if you define a Plugin Configuration for Unified API at the system level, each cluster and subsequently each instance gets that configuration by default.
There are two types of clusters: HA and GR. This document discusses HA clusters. For information related to GR clusters, refer to CPS Geographic Redundancy Guide for this release.
Note | In an HA environment you should not make any configuration in Cluster node. |
Plug-in configuration done at cluster level overrides the same definition at system level. For example, if you configure Custom Reference Data at cluster level, it will override the Custom Reference Data configuration done at system level.
There is a default deployment configuration for mobile and WiFi deployments. system-1 is the default system name and cluster-1 is the default cluster name.
If a customer wants to change the system name, they need to change it in qns.conf (/etc/broadhop/qns.conf) file also to reflect it in Policy Builder:
-Dcom.broadhop.run.systemId=<system name>
After installation, use this procedure to set up your Cisco Policy Builder by using an example populated with default data. You can change anything that does not apply to your deployment.
Step 1 | Click the
Reference Data tab, and then click the
Systems node to display the
Systems tree.
| ||||||||||||||||||||||||
Step 2 | Click
System... under
Create
Child: to open the
System pane on the right side.
| ||||||||||||||||||||||||
Step 3 | Fill in the
Name field, and provide a description of this
system. Enter the rest of the parameters based on your network requirements.
| ||||||||||||||||||||||||
Step 4 | If the created
system needs to be used, then after publishing, the following property needs to
be updated in the
qns.conf configuration file:
-Dcom.broadhop.run.systemId=<system name> where <system name> is the system name defined in the Step 3. |
A soft delete session is an entry in the session database which maintains session data after session stop with an auto-generated unique primary key, but still maintains needed secondary keys. This allows messages which come after session stop to still be processed while also allowing a session with the same primary key to be immediately created. The CPS code determines when soft delete sessions are required and what secondary keys are needed.
At install time, a system, cluster, and instance are set up. If you need to change the cluster definition, or want to add others, use these steps.
Step 1 | Begin with a
system at the
Systems node in the
Reference
Data tab.
| ||||||||||||||||||||||||||||||||||||||
Step 2 | Click the
Cluster link to set up your first cluster.
Since some data is relevant at the cluster level, you always have at least one cluster, even if it is a cluster of one instance. The following parameters can be configured for the Cluster:
| ||||||||||||||||||||||||||||||||||||||
Step 3 | From the
Systems tree, open up the cluster that you just added and check the plug-in
configurations.
Any of the configurations you specify here are used at the cluster level only and cascade down to the instance level if no configuration is set on the instance. At this point, the plug-ins are available to the cluster but are not configured. Click any one of them to open the detailed page in the right pane, and check and set your own configuration data. However, there is rarely a need to use the Threading Configuration or the Async Threading Configuration unless instructed to do so. | ||||||||||||||||||||||||||||||||||||||
Step 4 | If the created
cluster needs to be used, then after publishing, following property needs to be
updated in the
qns.conf configuration file:
-Dcom.broadhop.run.clusterId=<cluster name> where, <cluster name> is the cluster name defined in Policy Builder. |
Step 1 | Begin with a Cluster at the Systems node in the Reference Data tab. |
Step 2 | Under
Create
Child:, click the
Instance link to open the
Instance pane.
|
Step 3 | Type the Name and Description. |
Step 4 | From the
Systems tree, open up the instance node that you just
added and check the plug-in configurations.
At this point, plug-ins are available but not configured at the instance level. Click any one of the plug-ins to open the detailed page in the right pane and check and set your own configuration data. Any of the configuration data you have here are used at the instance level, overriding any plug-ins set at the system level or the cluster level. |