From fd59535cef357a618162438756d2f726c4cffd7e Mon Sep 17 00:00:00 2001 From: Liviu Chircu Date: Fri, 29 May 2020 22:07:16 +0300 Subject: [PATCH] [mid-]registrar: Add high-level docs for the SIP PN Support (cherry picked from commit cd8d77143f73e90c8688004dd7b817c1d3db7cf7) --- lib/reg/doc/supported_rfc.xml | 185 ++++++++++++++++++ modules/mid_registrar/doc/mid_registrar.xml | 2 + .../mid_registrar/doc/mid_registrar_admin.xml | 3 + modules/registrar/doc/registrar.xml | 2 + modules/registrar/doc/registrar_admin.xml | 108 +--------- 5 files changed, 197 insertions(+), 103 deletions(-) create mode 100644 lib/reg/doc/supported_rfc.xml diff --git a/lib/reg/doc/supported_rfc.xml b/lib/reg/doc/supported_rfc.xml new file mode 100644 index 00000000000..4050ce9224f --- /dev/null +++ b/lib/reg/doc/supported_rfc.xml @@ -0,0 +1,185 @@ +
+ Path Support (RFC 3327) + + The ®_module; module includes SIP Path header field support + according to + RFC 3327, + for usage in registrars and home-proxies. + + + 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: + + + + + off - stores the value of the + Path headers into usrloc without passing it back to + the UAC in the reply. + + + + + lazy - stores the Path header and + passes it back to the UAC if Path-support is indicated + by the path param in the Supported HF. + + + + + strict - rejects the registration + with 420 Bad Extension 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. + + + + + 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). + + + 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;. + +
+ + +
+ GRUU Support (RFC 5627) + + The ®_module; module includes support for Globally Routable User + Agent URIs according to RFC 5627. + + + 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: + + + + + public - 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. + + + + + temporary - 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. + + + + + 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. + + + 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. + + + 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. + +
+ + +
+ SIP Push Notification Support (RFC 8599) + + The ®_module; module includes support for standards-based SIP Push + Notifications, per + RFC 8599. + Support for the basic version of the draft can be enabled by switching + to true. The + module also includes optional support for sending Push Notifications + during long-lived dialogs (see RFC section 6), + through the switch. + + + Essential mechanics behind the Push Notification (PN) support: + + + + + 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 + + + + + OpenSIPS will raise a + E_UL_CONTACT_REFRESH + 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) + + + + + REGISTER processing is unchanged -- PN-enabled UAs are saved + just as regular UAs, with the former ones additionally having + the 4 bitflag set in the "Flags" field of + any MI listing of contacts, for differentiation purposes + + + + + initial INVITE processing is barely changed, with the ®_lookup_f; + function now additionally returning a value of + 2 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! + + + 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 + + + + + + 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 + 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. + + + + + 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. + +
diff --git a/modules/mid_registrar/doc/mid_registrar.xml b/modules/mid_registrar/doc/mid_registrar.xml index d033e744d0c..da7b8cc0fb5 100644 --- a/modules/mid_registrar/doc/mid_registrar.xml +++ b/modules/mid_registrar/doc/mid_registrar.xml @@ -3,12 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ mid_registrar"> +mid_registrar_save()"> mid_registrar_lookup()"> + diff --git a/modules/mid_registrar/doc/mid_registrar_admin.xml b/modules/mid_registrar/doc/mid_registrar_admin.xml index ba8dc6c555d..abe155d5550 100644 --- a/modules/mid_registrar/doc/mid_registrar_admin.xml +++ b/modules/mid_registrar/doc/mid_registrar_admin.xml @@ -36,6 +36,9 @@ + + &supported_rfc; +
diff --git a/modules/registrar/doc/registrar.xml b/modules/registrar/doc/registrar.xml index 5aaae008b59..0fd57eb77ce 100644 --- a/modules/registrar/doc/registrar.xml +++ b/modules/registrar/doc/registrar.xml @@ -3,6 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ registrar"> +save()"> lookup()"> @@ -10,6 +11,7 @@ + diff --git a/modules/registrar/doc/registrar_admin.xml b/modules/registrar/doc/registrar_admin.xml index 4d211011d64..ba05de32190 100644 --- a/modules/registrar/doc/registrar_admin.xml +++ b/modules/registrar/doc/registrar_admin.xml @@ -6,110 +6,12 @@
Overview - The module contains REGISTER processing logic. -
- PATH support - - Register module includes Path support (according to RFC 3327) - for usage in registrars and home-proxies. - - - A call to save(...) stores, if path-support is enabled - in the registrar-module, the values of the Path - Header(s) along with the contact into usrloc. There are - three modes regarding the reply to a REGISTER including - one or more Path HFs: - - - - - off - stores the value of the - Path headers into usrloc without passing it back to - the UAC in the reply. - - - - - lazy - stores the Path header and - passes it back to the UAC if Path-support is indicated - by the path param in the Supported HF. - - - - - strict - rejects the registration - with 420 Bad Extension 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. - - - - - A call to lookup(...) 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). - - - The whole process is transparent to the user, so no - config changes are required beside setting the - registrar-parameters use_path and - path_mode. - -
- -
- GRUU support - - Register module includes GRUU support (according to RFC 5627) - for usage in registrars and home-proxies. - - - A call to save(...) stores, if the phone supports GRUU, - the values of the SIP Instance along with the contact into usrloc. - The registrar module will generate two types of GRUUs : - - - - - public - 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. - - - - - temporary - 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. - - - - - A call to lookup(...) 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. - - - 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 the sequential - requests. - - - 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 sequential request with the GRUU - indication in the RURI. - -
+ + The module contains SIP REGISTER request processing logic, per RFC + 3261. On top of this support, several extensions are available: + + &supported_rfc;