Merge pull request #255 from Metaswitch/sifc_and_difc_docs

Sifc and difc docs

docs/Backups.md

@@ -251,15 +251,19 @@ To backup the shared configuration:
     /etc/clearwater/bgcf.json
     /etc/clearwater/enum.json
     /etc/clearwater/s-cscf.json
+    /etc/clearwater/shared_ifcs.xml
+    /etc/clearwater/default_ifcs.xml
     ```
 
 ### Restoring Configuration
 
-To restore a previous backup, copy the four files listed above to `/etc/clearwater` on one of your sprout nodes. Then run the following commands on that node:
+To restore a previous backup, copy the six files listed above to `/etc/clearwater` on one of your sprout nodes. Then run the following commands on that node:
 
     cw-upload_shared_config
     cw-upload_bgcf_json
     cw-upload_enum_json
     cw-upload_scscf_json
+    cw-upload_shared_ifcs_xml
+    cw-upload_default_ifcs_xml
 
 See [Modifying Clearwater settings](Modifying_Clearwater_settings.md) for more details on this.

docs/Clearwater_Configuration_Options_Reference.md

@@ -203,6 +203,10 @@ This section describes optional configuration options, particularly for ensuring
     * Without an I-CSCF there is no way to prevent it from registering as different user accounts.
 * `disable_tcp_switch` - when set to 'Y', Clearwater disables UDP-to-TCP uplift on SIP messages.  This is useful when creating a deployment where all SIP is sent over UDP.  This option only affects Sprout nodes.
 * `sprout_impi_store` - this is the location of Sprout's IMPI store. It has the same format as `sprout_registration_store`. If not provided, Sprout uses the same value configured in `sprout_registration_store`.
+* `request_shared_ifcs` - when set to 'Y' Clearwater requests Shared iFC sets from the HSS. This option is enabled by default. Shared iFC sets can be configured on Clearwater in the `/etc/clearwater/shared_ifcs.xml` file.
+* `apply_default_ifcs` - when set to 'Y' Clearwater will apply any default iFCs specified by the operator in the `/etc/clearwater/default_ifcs.xml` file to initial requests who have no applicable iFCs associated with them. This option is not enabled by default.
+* `reject_if_no_matching_ifcs` - when set to 'Y' Clearwater will reject any initial requests that don't have any matching iFCs that can be applied to them. This option is not enabled by default.
+* `dummy_app_server` - this field allows the name of a dummy application server to be specified. If an iFC contains this dummy application server, then no application server will be invoked when this iFC is triggered.
 
 ### Experimental options
 

docs/Clearwater_SNMP_Statistics.md

@@ -107,6 +107,9 @@ Sprout nodes provide the following statistics:
 * The number of additional INVITEs sent due to public identities having multiple registered bindings.
 * The count, average, variance, and high and low watermarks for originating audio session setup time at the S-CSCF, indexed by time period.   For the purposes of these stats a call is considered to be an audio call if video is not specified in the SDP on the initial INVITE.  The session setup time is measured as the time between receiving the originating INVITE and sending the first successful response (e.g. 180 RINGING or 200 OK).
 * The count, average, variance, and high and low watermarks for originating video session setup time at the S-CSCF, indexed by time period.   For the purposes of these stats a call is considered to be a video call if video is specified in the SDP on the initial INVITE.  The session setup time is measured as the time between receiving the originating INVITE and sending the first successful response (e.g. 180 RINGING or 200 OK).
+* The number of Shared iFC set IDs retrieved from the HSS where the S-CSCF has no matching set of iFCs, indexed by time period.
+* The number of initial requests that had no matching iFCs to apply, indexed by time period.
+* The number of initial requests that attempted to use Default iFCs but had no matching ones, indexed by time period.
 
 ### Vellum statistics
 Vellum nodes provide the following statistics:

docs/Handling_Multiple_Failed_Nodes.md

@@ -68,9 +68,18 @@ If the Cassandra cluster isn't healthy, you must fix this up before continuing,
 
 Check the JSON configuration files on all Sprout nodes in the affected site:
 
-* Verify that `/etc/clearwater/enum.json` file is correct, fixing it up if is not.
-* Verify that `/etc/clearwater/s-cscf.json` file is correct, fixing it up if is not.
-* Verify that `/etc/clearwater/bgcf.json` file is correct, fixing it up if is not.
+* Verify that the `/etc/clearwater/enum.json` file is correct, fixing it up if it's not.
+* Verify that the `/etc/clearwater/s-cscf.json` file is correct, fixing it up if it's not.
+* Verify that the `/etc/clearwater/bgcf.json` file is correct, fixing it up if it's not.
+
+### Sprout - XML configuration
+
+Check the XML configuration files on all Sprout nodes in the affected site:
+
+* Verify that the `/etc/clearwater/shared_ifcs.xml` file is correct, fixing it up if it's not.
+* verify that the `/etc/clearwater/default_ifcs.xml` file is correct, fixing it up if it's not.
+
+Running one of the commands `sudo cw-validate_{shared|default}_ifcs_xml` will check if the specified file is syntactically correct.
 
 ### Recreate the etcd cluster
 

docs/Manual_Install.md

@@ -313,3 +313,56 @@ As an example, say you have one S-CSCF that supports billing, and one that doesn
 Then when you configure a subscriber in the HSS, you can set up what capabilities they require in an S-CSCF. These will also be integers, and you should make sure this matches with how you've set up the s-cscf.json file. In this example, if you wanted your subscriber to be billed, you would configure the user data in the HSS to make it mandatory for your subscriber to have an S-CSCF that supports capability 1.
 
 To change the I-CSCF configuration, edit this file on any Sprout node, then upload it to the shared configuration database by running `sudo cw-upload_scscf_json`.
+
+### Shared iFC configuration
+
+If the configuration option `request_shared_ifcs` is set to 'Y', the S-CSCF must be configured with any Shared iFC sets that may be sent to it by the HSS.
+
+You can configure Shared iFC sets on the S-CSCF by editing the `/etc/clearwater/shared_ifcs.xml` file.
+
+This file stores the iFCs in each Shared iFC set. The format of the file is as follows:
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <SharedIFCsSets>
+     <SharedIFCsSet>
+       <SetID>  <set id>  </SetID>
+       <InitialFilterCriteria>
+         <iFC>
+       </InitialFilterCriteria>
+       <InitialFilterCriteria>
+         <iFC>
+       </InitialFilterCriteria>
+     </SharedIFCsSet>
+   </SharedIFCsSets>
+
+The `set id` is an integer, and each Shared iFCs set must have a unique `set id`.
+The `iFC` is an iFC, in XML format.
+
+There must be exactly one `SharedIFCsSets` element, which can contain multiple `SharedIFCsSet` elements (the minimum number of `SharedIFCsSet` elements is zero).
+Each `SharedIFCsSet` element can contain multiple `InitialFilterCriteria` elements (the minimum number of `InitialFilterCriteria` elements is zero), and must contain exactly one unique `SetID` element.
+
+To change the Shared iFC configuration, edit this file on any Sprout node, then upload it to the shared configuration database by running `sudo cw-upload_shared_ifcs_xml`.
+To validate the Shared iFC configuration file before uploading it, run the command `sudo cw-validate_shared_ifcs_xml <file_location>` on the Sprout node the file is present on.
+To remove the Shared iFC configuration, run the command `sudo cw-remove_shared_ifcs_xml` on any Sprout node.
+
+### Default iFC configuration
+
+If you wish to apply iFCs by default to any subscribers who have no iFCs triggered on a request, these iFCs must be configured on the S-CSCF, and the configuration option `apply_default_ifcs` set to 'Y'.
+
+You can configure Default iFCs on the S-CSCF by editing the `/etc/clearwater/default_ifcs.xml` file.
+
+This file stores a list of Default iFCs. The format of the file is as follows:
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <DefaultIFCsSet>
+     <InitialFilterCriteria>
+       <iFC>
+     </InitialFilterCriteria>
+   </DefaultIFCsSet>
+
+The `iFC` is an iFC, in XML format.
+There must be exactly one `DefaultIFCsSet` element, which can can contain multiple `InitialFilterCriteria` elements (the minimum number of `InitialFilterCriteria` elements is zero).
+
+To change the Default iFC configuration, edit this file on any Sprout node, then upload it to the shared configuration database by running `sudo cw-upload_default_ifcs_xml`.
+To validate the Default iFC configuration file before uploading it, run the command `sudo cw-validate_default_ifcs_xml <file_location>` on the Sprout node the file is present on.
+To remove the Default iFC configuration, run the command `sudo cw-remove_default_ifcs_xml` on any Sprout node.

docs/Modifying_Clearwater_settings.md

@@ -30,6 +30,21 @@ To change one of these files:
 * Run one of `sudo cw-upload_{scscf|bgcf|enum}_json` depending on which file you modified.
 * The change will be automatically propagated around the site (by Clearwater's [automatic configuration sharing](Automatic_Clustering_Config_Sharing.md) functionality) and will start being used.
 
+## Modifying Sprout XML Configuration
+
+*This configuration can be freely modified without impacting service.*
+
+Some of the more complex sprout-specific configuration is stored in XML files.
+
+* `/etc/clearwater/shared_ifcs.xml` - contains information about all Shared iFC sets for the Sprout S-CSCF to use.
+* `/etc/clearwater/default_ifcs.xml` - contains information about all the Default iFCs for the Sprout S-CSCF to apply.
+
+To change one of these files:
+
+* Edit the file on *one* of your sprout nodes in each site.
+* Run one of `sudo cw-upload_{shared|default}_ifcs_xml` depending on which file you modified.
+* The change will be automatically propogated around the site (by Clearwater's [automatic configuration sharing](Automatic_Clustering_Config_Sharing.md) functionality) and will start being used.
+
 ## Modifying DNS Config
 
 *This configuration can be freely modified without impacting service*