Merge pull request #7 from Metaswitch/number_routing

[Reviewer: Rob] Update with number routing

docs/IBCF.md

@@ -37,11 +37,18 @@ or by defining a default mapping to the trunk and exceptions for number ranges y
     *.3.2.1.2.4.2 IN NAPTR 1 1 "u" "E2U+sip" "!(^.*$)!sip:\\1@<local domain>!" .
     *.3.2.1.2.4.2.1 IN NAPTR 1 1 "u" "E2U+sip" "!(^.*$)!sip:\\1@<local domain>!" .
 
+You can also use ENUM to provide number portability information, for example
+
+    *.3.2.1.2.4.2 IN NAPTR 1 1 "u" "E2U+pstn:tel" "!(^.*$)!sip:\\1;npdi;rn=+242123@<local domain>!" .
+    *.3.2.1.2.4.2.1 IN NAPTR 1 1 "u" "E2U+pstn:tel" "!(^.*$)!sip:\\1;npdi@<local domain>!" .
+
 Refer to the [ENUM guide](ENUM) for more about how to configure ENUM.
 
 ## BGCF Configuration
 
-BGCF (Border Gateway Control Function) configuration is stored in the `bgcf.json` file in `/etc/clearwater` on each sprout node (both I- and S-CSCF).  The file stores mappings from SIP trunk IP addresses and/or host names to IBCF host names, and these mappings control which IBCF nodes are used to route to a particular destination. Multiple nodes can be specified.  In this case, Route headers are added to the message such that it is sent to the first node and the first node sends it to the second node and so on; the message is not tried at the second node if it fails at the first node.
+BGCF (Border Gateway Control Function) configuration is stored in the `bgcf.json` file in `/etc/clearwater` on each sprout node (both I- and S-CSCF).  The file stores two types of mappings. This first maps from SIP trunk IP addresses and/or host names to IBCF host names, and the second maps from a routing number (using prefix matching) to IBCF host names. These mappings control which IBCF nodes are used to route to a particular destination. Each entry can only apply to one type of mapping. 
+
+Multiple nodes to route to can be specified. In this case, Route headers are added to the message such that it is sent to the first node and the first node sends it to the second node and so on; the message is not tried at the second node if it fails at the first node.
 
 The file is in JSON format, for example.
 
@@ -54,8 +61,16 @@ The file is in JSON format, for example.
             {   "name" : "<route 2 descriptive name>",
                 "domain" : "<SIP trunk IP address or host name>",
                 "route" : ["<IBCF SIP URI>", "<IBCF SIP URI>"]
+            },
+            {   "name" : "<route 3 descriptive name>",
+                "number" : "<Routing number>",
+                "route" : ["<IBCF SIP URI>", "<IBCF SIP URI>"]
             }
         ]
     }
 
-There can be only one route to any given SIP trunk IP address or host name.  If there are multiple routes with the same destination IP address or host name, only the first will be used.
+There can be only one route set for any given SIP trunk IP address or host name.  If there are multiple routes with the same destination IP address or host name, only the first will be used. Likewise, there can only be one route set for any given routing number; if there are multiple routes with the same routing number only the first will be used. 
+
+A default route set can be configured by having an entry where the domain is set to `"*"`. This will be used by the BGCF if it is trying to route based on the the domain and there's no explicit match for the domain in the configuration. 
+
+There is no default route set if the BGCF is routing based on the routing number provided. 

docs/SIP_Interface_Specifications.md

@@ -281,6 +281,13 @@ The following RFCs are already supported by Clearwater.  Note that a number of t
 *   Mandatory on S-CSCF and UEs in an IMS network.
 *   Clearwater includes public GRUUs in these event notifications as of the Ninja Gaiden release. It does not support temporary GRUUs.
 
+### Number portability parameters in Tel URI ([RFC 4694](http://www.ietf.org/rfc/rfc4694.txt))
+
+*   Defines additional parameters in Tel URI for signalling related to number portability.
+*   Used in IMS in both Tel and SIP URIs for carrier subscription scenarios, and in IMS core for other number portability related scenarios.
+*   Optional according to [TS 24.229](http://www.3gpp.org/ftp/Specs/html-info/24229.htm).
+*   The `rn` and `npdi` parameters are supported by Clearwater; Clearwater doesn't currently support the other parameters defined in this RFC.
+
 ## Relevant to Clearwater but not currently supported
 
 These are the RFCs which are relevant to Clearwater and not yet supported.
@@ -355,13 +362,6 @@ These are the RFCs which are relevant to Clearwater and not yet supported.
 *   Not currently supported by Clearwater.
 *   Optional according to [TS 24.229](http://www.3gpp.org/ftp/Specs/html-info/24229.htm).
 
-### Number portability parameters in Tel URI ([RFC 4694](http://www.ietf.org/rfc/rfc4694.txt))
-
-*   Defines additional parameters in Tel URI for signalling related to number portability.
-*   Used in IMS in both Tel and SIP URIs for carrier subscription scenarios, and in IMS core for other number portability related scenarios.
-*   Optional according to [TS 24.229](http://www.3gpp.org/ftp/Specs/html-info/24229.htm).
-*   Not currently supported by Clearwater.
-
 ### Service URNs ([RFC 5031](http://www.ietf.org/rfc/rfc5031.txt))
 
 *   Defines a URN namespace to identify services.  IMS allows UEs to use such service URNs as target URIs when establishing a call.  In particular, it is mandatory for UEs to signal emergency calls using a service URN of the form urn:service:sos possibly with a subtype, and the P-CSCF must be able to handle these requests appropriately, routing to an E-CSCF.
@@ -518,4 +518,4 @@ The following is a brief explanation of each RFC, and its relevance to IMS.
 
 *   Defines a mechanism for a caller to control the answer mode at the target of the call. Use cases can include invoking some kind of auto-answer loopback.  Covers the Answer-Mode and Priv-Answer-Mode headers.
 *   In general is transparent to proxies (provided proxies pass headers through), but the RFC recommends the mechanism is not used in environments that support parallel forking.
-*   Optional according to [TS 24.229](http://www.3gpp.org/ftp/Specs/html-info/24229.htm) - and arguably not a good idea because of bad interactions with forking.
+*   Optional according to [TS 24.229](http://www.3gpp.org/ftp/Specs/html-info/24229.htm) - and arguably not a good idea because of bad interactions with forking.