26 Dec
2012
26 Dec
'12
9:25 a.m.
Module: sip-router
Branch: pd/outbound
Commit: 11b7630b3f3423dd5697b9c1938f34ee851d325e
URL:
http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=11b7630…
Author: Peter Dunkley <peter.dunkley(a)crocodile-rcs.com>
Committer: Peter Dunkley <peter.dunkley(a)crocodile-rcs.com>
Date: Wed Dec 26 14:24:58 2012 +0000
modules_k/path: Updated module documentation for outbound
---
modules_k/path/README | 53 +++++++++++++++++++++---------------
modules_k/path/doc/path_admin.xml | 13 +++++++++
2 files changed, 44 insertions(+), 22 deletions(-)
diff --git a/modules_k/path/README b/modules_k/path/README
index df84d45..7624c54 100644
--- a/modules_k/path/README
+++ b/modules_k/path/README
@@ -8,7 +8,7 @@ Edited by
Andreas Granig
- Copyright � 2006 Inode GmbH
+ Copyright © 2006 Inode GmbH
__________________________________________________________________
Table of Contents
@@ -83,18 +83,18 @@ Chapter 1. Admin Guide
1.1. Path insertion for registrations
- For registrations in a scenario like "[UAC] -> [P1] -> [REG]", the
+ For registrations in a scenario like “[UAC] -> [P1] -> [REG]”, the
"path" module can be used at the intermediate proxy P1 to insert a Path
header into the message before forwarding it to the registrar REG. Two
functions can be used to achieve this:
- * add_path(...) adds a Path header in the form of "Path:
- <sip:1.2.3.4;lr>" to the message using the address of the outgoing
+ * add_path(...) adds a Path header in the form of “Path:
+ <sip:1.2.3.4;lr>” to the message using the address of the outgoing
interface. A port is only added if it's not the default port 5060.
If a username is passed to the function, it is also included in the
- Path URI, like "Path: <sip:username@1.2.3.4;lr>".
+ Path URI, like “Path: <sip:username@1.2.3.4;lr>”.
* add_path_received(...) also add a Path header in the same form as
above, but also adds a parameter indicating the received-URI of the
- message, like "Path: <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>".
+ message, like “Path: <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”.
This is especially useful if the proxy does NAT detection and wants
to pass the NAT'ed address to the registrar.
If the function is called with a username, it's included in the
@@ -105,12 +105,12 @@ Chapter 1. Admin Guide
If the NAT'ed address of an UAC is passed to the registrar, the
registrar routes back subsequent requests using the Path header of the
registration as Route header of the current request. If the
- intermediate proxy had inserted a Path header including the "received"
+ intermediate proxy had inserted a Path header including the “received”
parameter during the registration, this parameter will show up in the
Route header of the new request as well, allowing the intermediate
proxy to route to this address instead of the one propagated in the
Route URI for tunneling through NAT. This behaviour can be activated by
- setting the module parameter "use_received".
+ setting the module parameter “use_received”.
2. Dependencies
@@ -121,7 +121,9 @@ Chapter 1. Admin Guide
The following modules must be loaded before this module:
* The "rr" module is needed for outbound routing according to the
- "received" parameter.
+ “received” parameter.
+ * The "outbound" module is needed for outbound routing as per RFC
+ 5626.
2.2. External Libraries or Applications
@@ -135,7 +137,7 @@ Chapter 1. Admin Guide
3.1. use_received (int)
- If set to 1, the "received" parameter of the first Route URI is
+ If set to 1, the “received” parameter of the first Route URI is
evaluated and used as destination-URI if present.
Default value is 0.
@@ -152,12 +154,19 @@ modparam("path", "use_received", 1)
4.3. add_path_received()
4.4. add_path_received(user)
-4.1. add_path()
+4.1. add_path()
- This function is used to insert a Path header in the form "Path:
- <sip:1.2.3.4;lr>", where "1.2.3.4" is the address of the
outgoing
+ This function is used to insert a Path header in the form “Path:
+ <sip:1.2.3.4;lr>”, where “1.2.3.4” is the address of the outgoing
interface.
+ If the “outbound” module was loaded before this module, and outbound is
+ required for this request, the header will be in the form “Path:
+ <sip:flowtoken@1.2.3.4;lr;ob>”, where “flowtoken” is the RFC 5636
+ flow-token that can be used to identify the source and local address
+ and transport the request was received on, and where “1.2.3.4” is the
+ address of the outgoing interface.
+
This function can be used from REQUEST_ROUTE.
Example 1.2. add_path usage
@@ -168,10 +177,10 @@ if (!add_path()) {
};
...
-4.2. add_path(user)
+4.2. add_path(user)
- This function adds a Path header in the form "Path:
- <sip:user@1.2.3.4;lr>".
+ This function adds a Path header in the form “Path:
+ <sip:user@1.2.3.4;lr>”.
Meaning of the parameters is as follows:
* user - The username to be inserted as user part.
@@ -186,10 +195,10 @@ if (!add_path("loadbalancer")) {
};
...
-4.3. add_path_received()
+4.3. add_path_received()
- This function adds a Path header in the form "Path:
- <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>", setting it's own outgoing
+ This function adds a Path header in the form “Path:
+ <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting it's own outgoing
address as domain-part, and the address the request has been received
from as received-parameter.
@@ -203,10 +212,10 @@ if (!add_path_received()) {
};
...
-4.4. add_path_received(user)
+4.4. add_path_received(user)
- This function adds a Path header in the form "Path:
- <sip:user@1.2.3.4;received=sip:2.3.4.5:1234;lr>", setting 'user'
as
+ This function adds a Path header in the form “Path:
+ <sip:user@1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting 'user' as
username part of address, it's own outgoing address as domain-part, and
the address the request has been received from as received-parameter.
diff --git a/modules_k/path/doc/path_admin.xml b/modules_k/path/doc/path_admin.xml
index b0fd913..d68e360 100644
--- a/modules_k/path/doc/path_admin.xml
+++ b/modules_k/path/doc/path_admin.xml
@@ -87,6 +87,11 @@
parameter.
</para>
</listitem>
+ <listitem>
+ <para>
+ The "outbound" module is needed for outbound routing as per RFC 5626.
+ </para>
+ </listitem>
</itemizedlist>
</para>
</section>
@@ -142,6 +147,14 @@ modparam("path", "use_received", 1)
of the outgoing interface.
</para>
<para>
+ If the <quote>outbound</quote> module was loaded before this module, and
outbound is
+ required for this request, the header will be in the form
+ <quote>Path: <sip:flowtoken@1.2.3.4;lr;ob></quote>, where
<quote>flowtoken</quote>
+ is the RFC 5636 flow-token that can be used to identify the source and local address
and
+ transport the request was received on, and where <quote>1.2.3.4</quote> is
the address of
+ the outgoing interface.
+ </para>
+ <para>
This function can be used from REQUEST_ROUTE.
</para>
<example>