Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[mid-]registrar: Add high-level docs for the SIP PN Support
(cherry picked from commit cd8d771)
- Loading branch information
1 parent
93798a0
commit fd59535
Showing
5 changed files
with
197 additions
and
103 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| <section id="rfc-3327-support" xreflabel="Path (RFC 3327) Support"> | ||
| <title>Path Support (RFC 3327)</title> | ||
| <para> | ||
| The ®_module; module includes SIP Path header field support | ||
| according to | ||
| <ulink url="https://tools.ietf.org/html/rfc3327">RFC 3327</ulink>, | ||
| for usage in registrars and home-proxies. | ||
| </para> | ||
| <para> | ||
| A call to ®_save_f; stores, if path support is enabled | ||
| in the ®_module; module, the values of the Path | ||
| Header(s) along with the Contact information into usrloc. There are | ||
| three modes for building the reply to a REGISTER message which | ||
| includes one or more Path header fields: | ||
| </para> | ||
| <itemizedlist> | ||
| <listitem> | ||
| <para> | ||
| <emphasis>off</emphasis> - stores the value of the | ||
| Path headers into usrloc without passing it back to | ||
| the UAC in the reply. | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| <emphasis>lazy</emphasis> - stores the Path header and | ||
| passes it back to the UAC if Path-support is indicated | ||
| by the <quote>path</quote> param in the Supported HF. | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| <emphasis>strict</emphasis> - rejects the registration | ||
| with <quote>420 Bad Extension</quote> if there's a Path | ||
| header but no support for it is indicated by the UAC. | ||
| Otherwise it's stored and passed back to the UAC. | ||
| </para> | ||
| </listitem> | ||
| </itemizedlist> | ||
| <para> | ||
| A call to ®_lookup_f; always uses the Path header if | ||
| found, and inserts it as Route HF either in front of | ||
| the first Route HF, or after the last Via HF if no | ||
| Route is present. It also sets the destination URI to | ||
| the first Path URI, thus overwriting the received-URI, | ||
| because NAT has to be handled at the outbound-proxy of | ||
| the UAC (the first hop after client's NAT). | ||
| </para> | ||
| <para> | ||
| The whole process is transparent to the user, so no | ||
| config changes are required besides enabling one of the | ||
| "p0" / "p1" / "p2" flags when calling ®_save_f;. | ||
| </para> | ||
| </section> | ||
|
|
||
|
|
||
| <section id="rfc-5627-support" xreflabel="SIP GRUU (RFC 5627) Support"> | ||
| <title>GRUU Support (RFC 5627)</title> | ||
| <para> | ||
| The ®_module; module includes support for Globally Routable User | ||
| Agent URIs according to <ulink url="https://tools.ietf.org/html/rfc5627">RFC 5627</ulink>. | ||
| </para> | ||
| <para> | ||
| A call to ®_save_f; stores, if the phone supports GRUU, | ||
| the values of the SIP Instance along with the contact into usrloc. | ||
| The module will generate two types of GRUUs: | ||
| </para> | ||
| <itemizedlist> | ||
| <listitem> | ||
| <para> | ||
| <emphasis>public</emphasis> - exposes the underlying AOR, | ||
| constructed just by attaching the SIP Instance as the ;gr | ||
| parameter value. These are persistent, valid as long as the | ||
| contact registration is valid. | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| <emphasis>temporary</emphasis> - hides the underlying AOR | ||
| Each new Register request leads to the construction of a | ||
| new temporary GRUU, while Register requests with a different | ||
| Call-ID lead to the invalidation of all the previous generated | ||
| temporary GRUUs. | ||
| </para> | ||
| </listitem> | ||
| </itemizedlist> | ||
| <para> | ||
| A call to ®_lookup_f; will try to detect if the R-URI contains a | ||
| GRUU. If it does, it will route the request just for the Contact | ||
| that the specific AOR belongs to, without appending any other branches. | ||
| </para> | ||
| <para> | ||
| Even if the the GRUU handling during the registration process is | ||
| transparent to the user, so no config changes are required, you need | ||
| to take care of the GRUU specifics when handling mid-dialog requests. | ||
| </para> | ||
| <para> | ||
| As the GRUU will be present in the contact header of the initial | ||
| requests generated byt GRUU enabled devices, you will have to also | ||
| do a lookup() when receiving a mid-dialog request with the GRUU | ||
| indication in the RURI. | ||
| </para> | ||
| </section> | ||
|
|
||
|
|
||
| <section id="rfc-8599-support" xreflabel="SIP PN (RFC 8599) Support"> | ||
| <title>SIP Push Notification Support (RFC 8599)</title> | ||
| <para> | ||
| The ®_module; module includes support for standards-based SIP Push | ||
| Notifications, per | ||
| <ulink url="https://tools.ietf.org/html/rfc8599">RFC 8599</ulink>. | ||
| Support for the basic version of the draft can be enabled by switching | ||
| <xref linkend="param_pn_enable"/> to <emphasis>true</emphasis>. The | ||
| module also includes optional support for sending Push Notifications | ||
| during long-lived dialogs (<ulink url="https://tools.ietf.org/html/rfc8599#page-23">see RFC section 6</ulink>), | ||
| through the <xref linkend="param_pn_enable_purr"/> switch. | ||
| </para> | ||
| <para> | ||
| Essential mechanics behind the Push Notification (PN) support: | ||
| </para> | ||
| <itemizedlist> | ||
| <listitem> | ||
| <para> | ||
| the PN support is fully compatible with the existing logic and | ||
| enabling it does not impose any limitations, as the | ||
| ®_module; can simultaneously handle both SIP PN compliant | ||
| and standard SIP User Agents | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| OpenSIPS will raise a | ||
| <ulink url='usrloc#event_E_UL_CONTACT_REFRESH'>E_UL_CONTACT_REFRESH</ulink> | ||
| event any time a Push Notification needs to be sent to a | ||
| PN-enabled contact. The event includes the PN coordinates of | ||
| the contact -- they may be found in the Contact URI ('uri' | ||
| event parameter) and may be extracted using the {uri.param,name} | ||
| transformation. From here onwards, it is up to the script | ||
| developer to trigger the Push Notification, thus forcing a | ||
| re-registration from the device (e.g. possibly by sending an | ||
| HTTP POST with the rest_client module) | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| REGISTER processing is unchanged -- PN-enabled UAs are saved | ||
| just as regular UAs, with the former ones additionally having | ||
| the <emphasis>4</emphasis> bitflag set in the "Flags" field of | ||
| any MI listing of contacts, for differentiation purposes | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| initial INVITE processing is barely changed, with the ®_lookup_f; | ||
| function now additionally returning a value of | ||
| <emphasis role='bold'>2</emphasis> if the only | ||
| found contacts were PN-enabled contacts, all which required a | ||
| Push Notification. This means that PNs have been triggered for | ||
| each of them and t_relay() is not required, since they are not | ||
| reachable until they re-register! | ||
| </para> | ||
| <para> | ||
| Using the event_routing module, OpenSIPS will transparently | ||
| fork a new branch from the current INVITE on each | ||
| re-registration from these contacts within the accepted | ||
| <xref linkend="param_pn_refresh_timeout"/> | ||
| </para> | ||
| </listitem> | ||
| <listitem> | ||
| <para> | ||
| mid-dialog requests: In some cases (e.g. long-lived dialogs), | ||
| a PN may be required before being able to route a mid-dialog | ||
| request to a SIP UA. The <xref linkend="afunc_pn_process_purr"/> | ||
| async function will take care of triggering the PN event and | ||
| resuming the script as soon as a re-registration from the | ||
| concerned contact is received. | ||
| </para> | ||
| </listitem> | ||
| </itemizedlist> | ||
| <para> | ||
| For more information or examples, refer to the documentation of the | ||
| "pn_xxx" module parameters or the OpenSIPS blog posts around the | ||
| "SIP Push Notification" topic. | ||
| </para> | ||
| </section> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -36,6 +36,9 @@ | |
| </listitem> | ||
| </itemizedlist> | ||
| </para> | ||
|
|
||
| &supported_rfc; | ||
|
|
||
| </section> | ||
|
|
||
| <section id="sec-working-modes"> | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters