Merge pull request #125 from Metaswitch/new_config_options

[Reviewer: Ellie] Document new config options

docs/Clearwater_Configuration_Options_Reference.md

@@ -38,7 +38,8 @@ This section describes options for the basic configuration of a Clearwater deplo
 * `ralf_hostname` - a hostname that resolves by DNS round-robin to all Ralf nodes in the cluster. Should include the port (usually 9888). This is also used (without the port) as the Origin-Realm of the Diameter messages Ralf sends. Optional if no Ralf nodes exist.
 * `cdf_identity` - a Diameter identity that represents the address of an online Charging Function. Subscribers provisioned through Ellis will have this set as their Primary Charging Collection Function on P-Charging-Function-Addresses headers on responses to their successful REGISTERs, and Bono will add similarly in originating requests.
 * `xdms_hostname` - a hostname that resolves by DNS round-robin to all Homer nodes in the cluster. Should include the port (usually 7888).
-* `hss_hostname` - the hostname of your external HSS, if you have one. The port defaults to 3868 - this cannot be set by static configuration, but can be controlled by setting `hss_realm` and having appropriate NAPTR/SRV records for Diameter.
+* `hss_realm` - this sets the Destination-Realm of your external HSS. When this field is set, Homestead will then attempt to set up multiple Diameter connections using an SRV lookup on this realm.
+* `hss_hostname` - this sets the Destination-Host of your external HSS, if you have one. Homestead will also try and establish a Diameter connection to this host (on port 3868) if no SRV-discovered peers exist.
 * `signup_key` - this sets the password which Ellis will require before allowing self-sign-up.
 * `turn_workaround` - if your STUN/TURN clients are not able to authenticate properly (for example, because they can't send the @ sign), this specifies an additional password which will authenticate clients even without a correct username.
 * `smtp_smarthost` - Ellis allows password recovery by email. This sets the SMTP server used to send those emails.
@@ -65,7 +66,11 @@ This section describes optional configuration options, particularly for ensuring
     * `pcscf` - a Record-Route header is only added just after requests come from or go to a P-CSCF - that is, at the start of originating handling and the end of terminating handling
     * `pcscf,icscf` - a Record-Route header is added just after requests come from or go to a P-CSCF or I-CSCF - that is, at the start and end of originating handling and the start and end of terminating handling
     * `pcscf,icscf,as` - a Record-Route header is added after requests come from or go to a P-CSCF, I-CSCF or application server - that is, at the start and end of originating handling, the start and end of terminating handling, and between each application server invoked
+* `force_hss_peer` - when set to an IP address or hostname, Homestead will create a connection to the HSS using this value, but will still use the `hss_realm` and `hss_hostname` settings for the Destination-Host and Destination-Realm Diameter AVPs. This is useful when your HSS's Diameter configuration does not match the DNS records.
 * `hss_mar_lowercase_unknown` - some Home Subscriber Servers (particularly old releases of OpenIMSCore HSS) expect the string 'unknown' rather than 'Unknown' in Multimedia-Auth-Requests when Clearwater cannot tell what authentication type is expected. Setting this option to 'Y' will make Homestead send requests in this format.
+* `hss_mar_force_digest` - if Clearwater cannot tell what authentication type a subscriber is trying to use, this forces it to assume 'SIP Digest' and report that in the Multimedia-Auth-Request, rather than 'Unknown'.
+* `hss_mar_force_aka` - if Clearwater cannot tell what authentication type a subscriber is trying to use, this forces it to assume 'Digest-AKA-v1' and report that in the Multimedia-Auth-Request, rather than 'Unknown'.
+* `force_third_party_reg_body` - if the HSS does not allow the IncludeRegisterRequest/IncludeRegisterResponse fields (which were added in 3GPP Rel 9) to be configured, setting `force_third_party_reg_body=Y` makes Clearwater behave as though they had been sent, allowing interop with application servers that need them.
 * `enforce_user_phone` - by default, Clearwater will do an ENUM lookup on any SIP URI that looks like a phone number, due to client support for user-phone not being widespread. When this option is set to 'Y', Clearwater will only do ENUM lookups for URIs which have the user=phone parameter.
 * `enforce_global_only_lookups` - by default, Clearwater will do ENUM lookups for SIP and Tel URIs containing global and local numbers (as defined in RFC 3966). When this option is set to ‘Y’, Clearwater will only do ENUM lookups for SIP and Tel URIs that contain global numbers.
 * `hs_listen_port` - the Diameter port which Homestead listens on. Defaults to 3868.
@@ -79,7 +84,6 @@ This section describes optional configuration options, particularly for ensuring
 * `icscf_uri` - the SIP address of the external I-CSCF integrated with your Sprout node (if you have one).
 * `scscf_uri` - the SIP address of the Sprout S-CSCF. This defaults to `sip:$sprout_hostname:$scscf;transport=TCP` - this includes a specific port, so if you need NAPTR/SRV resolution, it must be changed to not include the port.
 * `additional_home_domains` - this option defines a set of home domains which Sprout and Bono will regard as locally hosted (i.e. allowing users to register, not routing calls via an external trunk). It is a comma-separated list.
-* `hss_realm` - this sets the realm of your external HSS. When this field is set, Homestead will then attempt to set up multiple Diameter connections.
 * `billing_realm` - this sets the Destination-Realm on Diameter messages to your external CDR. CDR connections are not based on this but on configuration at the P-CSCF (which sets the P-Charging-Function-Addresses header).
 * `diameter_timeout_ms` - determines the number of milliseconds Homestead will wait for a response from the HSS before failing a request. Defaults to 200. `
 * `max_peers` - determines the maximum number of Diameter peers which Ralf or Homestead can have open connections to at the same time.