Merge pull request #287 from Metaswitch/options_poll_behaviour

[Reviewer: Seb] Options poll behaviour

docs/OPTIONS_poll_support.md

@@ -0,0 +1,80 @@
+# SIP OPTIONS poll support in Clearawater
+
+Clearwater uses SIP OPTIONS polls internally for some of our health checking
+functionality. These OPTIONS polls can also be used from external clients for
+health checking of the Sprout process. This section gives details on how we
+expect these OPTIONS messages to be formed, so that they are handled correctly
+by the system. Sending OPTIONS polls through a Clearwater deployment to other
+nodes or endpoints is also fully supported; these messages will be treated
+similarly to any other SIP flow, subject to the same checks on subscriber
+registration state etc.
+
+## Correctly forming OPTIONS polls
+The Sprout process will handle certain OPTIONS messages statelessly, without the
+need to send any requests off to subscriber state stores; the decision of when
+to do this is based on the URI they are sent to (detail on this below). This is
+for use by health checking and monitoring tools, so that they do not need to
+act as a full SIP endpoint and register with the system. Sprout will handle an
+OPTIONS message in this way if:
+
+-   the req_uri is classified as 'node local'
+-   the message contains either
+    -   no route headers
+    -   a single route header, also classified as 'node local'
+
+So, to poll Sprout with a SIP OPTIONS message, you simply need to make sure you
+are in line with the two points above. We are already using this for our Monit
+based health checking. An example of these poll messages looks like:
+
+```
+OPTIONS sip:poll-sip@10.0.10.1:5054 SIP/2.0
+Via: SIP/2.0/TCP 10.0.10.1;rport;branch=z9hG4bK-1234
+Max-Forwards: 2
+To: <sip:poll-sip@10.0.10.1:5054>
+From: poll-sip <sip:poll-sip@10.0.10.1>;tag=1234
+Call-ID: poll-sip-1234
+CSeq: 1234 OPTIONS
+Contact: <sip:10.0.10.1>
+Accept: application/sdp
+Content-Length: 0
+User-Agent: poll-sip
+```
+
+Which should get a 200 OK response:
+
+```
+SIP/2.0 200 OK
+Via: SIP/2.0/TCP 10.0.10.1;rport=56141;received=10.0.10.1;branch=z9hG4bK-1234
+Call-ID: poll-sip-1234
+From: "poll-sip" <sip:poll-sip@10.0.10.1>;tag=1234
+To: <sip:poll-sip@10.0.10.1>;tag=z9hG4bK-1234
+CSeq: 1234 OPTIONS
+Content-Length:  0
+```
+
+### Node local URIs
+To determine if a URI is 'node local' Sprout compares it to the list of
+identities we associate with the node when creating the stack at start of day.
+To see what your Sprout process considers its local identities to be, you can
+check the beginning of your sprout logs, under the log line `Local host
+aliases:`. As an example, on an EC2 based Sprout node, you will see something
+like the following:
+
+```
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:836: Local host aliases:
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  10.0.10.1
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  scscf.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  10.0.10.1
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  ec2-52-207-234-0.compute-1.amazonaws.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  mmtel.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  cdiv.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  memento.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  gemini.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  icscf.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  bgcf.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  scscf.sprout.example.com
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  52.207.234.0
+07-11-2017 12:25:57.539 UTC [7f5a1ed73780] Status stack.cpp:843:  sprout.example.com
+```
+
+The source code for classifying URIs can be found [here.](https://github.com/Metaswitch/sprout/blob/dev/src/uri_classifier.cpp)

mkdocs.yml

@@ -53,6 +53,7 @@ pages:
   - Geographic redundancy: Geographic_redundancy.md
   - IPv6: IPv6.md
   - SIP Interface Specifications: SIP_Interface_Specifications.md
+  - SIP OPTIONS poll support: OPTIONS_poll_support.md
   - Automatic Clustering and Configuration Sharing: Automatic_Clustering_Config_Sharing.md
   - Provisioning Subscribers: Provisioning_Subscribers.md
 - Failure Recovery: