097609f13f4457018198d5f21d1fd3eb7fdd5a21
[sip-router] / src / modules / uac / doc / uac_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16
17         <section>
18                 <title>Overview</title>
19                 <para>
20                 The <acronym>UAC</acronym> (User Agent Client) module provides some basic UAC
21                 functionalities like sending SIP requests, registering with a remote service,
22                 From: header manipulation (anonymization) and client authentication.
23                 </para>
24                 <para>
25                 The UAC module also supports sending a SIP request from the
26                 configuration file. See variable $uac_req(name) and the function
27                 uac_req_send().
28                 </para>
29                 <para>
30                 In addition, the module supports database-driven SIP registration functionality. See
31                 the uac_reg_lookup() function and dedicated section for remote
32                 registration configuration.
33                 </para>
34                 <para>
35                 Known limitations in this version:
36                 </para>
37                 <itemizedlist>
38                         <listitem>
39                         <para>
40                                 Authentication does not support qop auth-int, just qop auth;
41                         </para>
42                         </listitem>
43                         <listitem>
44                         <para>
45                                 CSeq is not increased automatically by uac_auth() during authentication
46                                 - the follow up request may be rejected. CSeq can be increased when
47                                 authenticating INVITE requests - dialog module has to be used, with
48                                 CSeq tracking feature enabled (see the readme of dialog module).
49                         </para>
50                         </listitem>
51                         <listitem>
52                         <para>
53                                 The <quote>uac_replace_*</quote> functions can only be run once on the same
54                                 SIP request. Try to save needed changes in a pseudovariable and
55                                 apply them once.
56                         </para>
57                         <para>
58                                 There is also a limitation regarding the use of the
59                                 <quote>msg_apply_changes()</quote> function together with the
60                                 <quote>uac_replace_*</quote> functions for messages that are
61                                 loose-routed (e.g. Re-INVITE requests). In this case you need
62                                 to call the <quote>loose_route()</quote> function after the
63                                 replace and msg_apply_changes. Otherwise Kamailio can create
64                                 replies with wrong From/To headers (e.g. for the 100 - Trying
65                                 reply in the Re-INVITE example).
66                         </para>
67                         </listitem>
68                 </itemizedlist>
69         </section>
70
71         <section>
72                 <title>Dependencies</title>
73                 <section>
74                         <title>&kamailio; Modules</title>
75                         <para>
76                         The following modules must be loaded before this module:
77                         <itemizedlist>
78                         <listitem>
79                         <para>
80                                 <emphasis>TM - Transaction Module</emphasis>
81                         </para>
82                         </listitem>
83                         <listitem>
84                         <para>
85                                 <emphasis>RR - Record-Route Module</emphasis>, but only if
86                                 restore mode for From: URI is set to <quote>auto</quote>.
87                         </para>
88                         </listitem>
89                         <listitem>
90                         <para>
91                                 <emphasis>Dialog Module</emphasis>, but only if
92                                 restore mode for From: URI is set to <quote>auto</quote> and
93                                 you want uac_replace_from or uac_replace_to to store the values
94                                 of the URIs as dialog variables.
95                         </para>
96                         </listitem>
97                         </itemizedlist>
98                         </para>
99                 </section>
100                 <section>
101                         <title>External Libraries or Applications</title>
102                         <para>
103                                 The following libraries or applications must be installed
104                                 before running &kamailio; with this module loaded:
105                                 <itemizedlist>
106                                 <listitem>
107                                 <para>
108                                         <emphasis>None</emphasis>
109                                 </para>
110                                 </listitem>
111                                 </itemizedlist>
112                         </para>
113                 </section>
114         </section>
115
116         <section>
117                 <title>Parameters</title>
118                 <section id="uac.p.rr_from_store_param">
119                         <title><varname>rr_from_store_param</varname> (string)</title>
120                         <para>
121                         Name of Record-Route header parameter that will be used to store
122                         an encoded version of the original FROM URI.
123                         </para>
124                         <para>
125                                 <emphasis>
126                                         This parameter is optional, it's default value being
127                                         <quote>vsf</quote>.
128                                 </emphasis>
129                         </para>
130                         <example>
131                                 <title>Set <varname>rr_from_store_param</varname> parameter</title>
132                                 <programlisting format="linespecific">
133 ...
134 modparam("uac","rr_from_store_param","my_param")
135 ...
136                                 </programlisting>
137                         </example>
138                 </section>
139                 <section id="uac.p.rr_to_store_param">
140                         <title><varname>rr_to_store_param</varname> (string)</title>
141                         <para>
142                         Name of Record-Route header parameter that will be used to store
143                         (encoded) the original TO URI.
144                         </para>
145                         <para>
146                                 <emphasis>
147                                         This parameter is optional, it's default value being
148                                         <quote>vst</quote>.
149                                 </emphasis>
150                         </para>
151                         <example>
152                                 <title>Set <varname>rr_to_store_param</varname> parameter</title>
153                                 <programlisting format="linespecific">
154 ...
155 modparam("uac","rr_to_store_param","my_param")
156 ...
157                                 </programlisting>
158                         </example>
159                 </section>
160                 <section id="uac.p.restore_mode">
161                         <title><varname>restore_mode</varname> (string)</title>
162                         <para>
163                         There are 3 modes of restoring the original FROM URI and the original TO URI:
164                         <itemizedlist>
165                         <listitem>
166                                 <para>
167                                 <quote>none</quote> - no information about original URI is
168                                 stored; restoration is not possible.
169                                 </para>
170                         </listitem>
171                         <listitem>
172                                 <para>
173                                 <quote>manual</quote> - all following replies will be restored,
174                                 but not also the sequential requests - this must be manually
175                                 updated based on original URI.
176                                 </para>
177                         </listitem>
178                         <listitem>
179                                 <para>
180                                 <quote>auto</quote> - all sequential requests and replies will
181                                 be automatically updated based on stored original URI. For this
182                                 option you have to set <quote>modparam("rr", "append_fromtag", 1)</quote>.
183                                 </para>
184                         </listitem>
185                         </itemizedlist>
186                         </para>
187                         <para>
188                                 <emphasis>
189                                         This parameter is optional, it's default value being
190                                         <quote>auto</quote>.
191                                 </emphasis>
192                         </para>
193                         <example>
194                                 <title>Set <varname>restore_mode</varname> parameter
195                                 </title>
196                                 <programlisting format="linespecific">
197 ...
198 modparam("uac","restore_mode","auto")
199 ...
200                                 </programlisting>
201                         </example>
202                 </section>
203                 <section id="uac.p.restore_dlg">
204                         <title><varname>restore_dlg</varname> (int)</title>
205                         <para>
206                         If set to 1, the module uses dialog variables to store initial and
207                         new values for From/To headers. The Dialog module has to be loaded and
208                         all calls that involve changes to From/To headers must be tracked.
209                         </para>
210                         <para>
211                                 <emphasis>
212                                         Default value of this parameter is 0.
213                                 </emphasis>
214                         </para>
215                         <example>
216                                 <title>Set <varname>restore_dlg</varname> parameter</title>
217                                 <programlisting format="linespecific">
218 ...
219 modparam("uac", "restore_dlg", 1)
220 ...
221                                 </programlisting>
222                         </example>
223                 </section>
224                 <section id="uac.p.restore_passwd">
225                         <title><varname>restore_passwd</varname> (string)</title>
226                         <para>
227                         String password to be used to encrypt the RR storing parameters. If
228                         empty, no encryption will be used.
229                         </para>
230                         <para>
231                                 <emphasis>
232                                         Default value of this parameter is empty.
233                                 </emphasis>
234                         </para>
235                         <example>
236                                 <title>Set <varname>restore_passwd</varname> parameter</title>
237                                 <programlisting format="linespecific">
238 ...
239 modparam("uac","restore_passwd","my_secret_passwd")
240 ...
241                                 </programlisting>
242                         </example>
243                 </section>
244                 <section id="uac.p.restore_from_avp">
245                         <title><varname>restore_from_avp</varname> (string)</title>
246                         <para>
247                         If defined and restore_mode is manual or auto, the avp is used to save
248                         the original from uri in order to be able to restore it in replies.
249                         That makes sense, if the original-uri can not be extracted from the original
250                         request, e.g. if msg_apply_changes() was used after calling uac_replace_from()
251                         or uac_replace_to().
252                         </para>
253                         <para>
254                                 If you create a dialog ( with dlg_manage() ) before calling uac_replace_from(),
255                         this avp will not be needed. The values of the uris will be stored as dialog variables.
256                         </para>
257                         <para><emphasis>
258                                         Default value of this parameter is empty.
259                                 </emphasis>
260                         </para>
261                         <example>
262                                 <title>Set <varname>restore_from_avp</varname> parameter</title>
263                                 <programlisting format="linespecific">
264 ...
265 modparam("uac","restore_from_avp","$avp(original_uri_from)")
266 ...
267                                 </programlisting>
268                         </example>
269                 </section>
270                 <section id="uac.p.restore_to_avp">
271                         <title><varname>restore_to_avp</varname> (string)</title>
272                         <para>
273                         If defined and restore_mode is manual or auto, the avp is used to save
274                         the original To URI in order to be able to restore it in replies.
275                         That makes sense if the original-uri can not be extracted from the original
276                         request, e.g. if msg_apply_changes() was used after calling uac_replace_to()
277                         </para>
278                         <para>
279                                 If you create a dialog ( with dlg_manage() ) before calling or uac_replace_to(),
280                                 this avp will not be needed. The values of the uris will be stored as dialog variables.
281                         </para>
282                         <para><emphasis>
283                                         Default value of this parameter is empty.
284                                 </emphasis>
285                         </para>
286                         <example>
287                                 <title>Set <varname>restore_to_avp</varname> parameter</title>
288                                 <programlisting format="linespecific">
289 ...
290 modparam("uac","restore_to_avp","$avp(original_uri_to)")
291 ...
292                                 </programlisting>
293                         </example>
294                 </section>
295                 <section id="uac.p.credential">
296                         <title><varname>credential</varname> (string)</title>
297                         <para>
298                         Contains a multiple definition of credentials used to perform
299                         authentication.
300                         </para>
301                         <para>
302                                 <emphasis>
303                                         This parameter is required if UAC authentication is used.
304                                 </emphasis>
305                         </para>
306                         <example>
307                                 <title>Set <varname>credential</varname> parameter</title>
308                                 <programlisting format="linespecific">
309 ...
310 modparam("uac","credential","username:domain:password")
311 ...
312                                 </programlisting>
313                         </example>
314                 </section>
315                 <section id="uac.p.auth_realm_avp">
316                         <title><varname>auth_realm_avp</varname> (string)</title>
317                         <para>
318                         The definition of an PV that might contain the realm to be used
319                         to perform authentication.
320                         </para>
321                         <para>
322                         When the PV value is an empty string or NULL when uac_auth() is called,
323                         the realm is taken from the reply and only username matching is done.
324                         This can be used if the realm upstream will be using is not known in advance.
325                         </para>
326                         <para><emphasis>
327                                 If you define it, you also need to define
328                                 <quote>auth_username_avp</quote>
329                                 (<xref linkend="uac.p.auth-username-avp-id"/>) and
330                                 <quote>auth_username_avp</quote>
331                                 (<xref linkend="uac.p.auth-password-avp-id"/>).
332                         </emphasis></para>
333                         <example>
334                                 <title>Set <varname>auth_realm_avp</varname> parameter</title>
335                                 <programlisting format="linespecific">
336 ...
337 modparam("uac","auth_realm_avp","$avp(i:10)")
338 ...
339                                 </programlisting>
340                         </example>
341                 </section>
342                 <section id="uac.p.auth_username_avp">
343                         <title><varname>auth_username_avp</varname> (string)</title>
344                         <para>
345                         The definition of an AVP that might contain the username to be used
346                         to perform authentication.
347                         </para>
348                         <para><emphasis>
349                                 If you define it, you also need to define
350                                 <quote>auth_realm_avp</quote>
351                                 (<xref linkend="uac.p.auth-realm-avp-id"/>) and
352                                 <quote>auth_username_avp</quote>
353                                 (<xref linkend="uac.p.auth-password-avp-id"/>).
354                         </emphasis></para>
355                         <example>
356                                 <title>Set <varname>auth_username_avp</varname> parameter</title>
357                                 <programlisting format="linespecific">
358 ...
359 modparam("uac","auth_username_avp","$avp(i:11)")
360 ...
361                                 </programlisting>
362                         </example>
363                 </section>
364                 <section id="uac.p.auth_password_avp">
365                         <title><varname>auth_password_avp</varname> (string)</title>
366                         <para>
367                         The definition of an AVP that might contain the password to be used
368                         to perform authentication.
369                         </para>
370                         <para><emphasis>
371                                 If you define it, you also need to define
372                                 <quote>auth_password_avp</quote>
373                                 (<xref linkend="uac.p.auth-password-avp-id"/>) and
374                                 <quote>auth_username_avp</quote>
375                                 (<xref linkend="uac.p.auth-password-avp-id"/>).
376                         </emphasis></para>
377                         <example>
378                                 <title>Set <varname>auth_password_avp</varname> parameter</title>
379                                 <programlisting format="linespecific">
380 ...
381 modparam("uac","auth_password_avp","$avp(i:12)")
382 ...
383                                 </programlisting>
384                         </example>
385                 </section>
386                 <section id="uac.p.reg_db_url">
387                         <title><varname>reg_db_url</varname> (string)</title>
388                         <para>
389                         DB URL to fetch account profiles for registration. This parameter
390                         must be set in order to enable remote registrations feature.
391                         </para>
392                         <para>The default value is "" (no value).</para>
393                         <example>
394                                 <title>Set <varname>reg_db_url</varname> parameter</title>
395                                 <programlisting format="linespecific">
396 ...
397 modparam("uac", "reg_db_url",
398     "&defaultdb;")
399 ...
400                                 </programlisting>
401                         </example>
402                 </section>
403
404                 <section id="uac.p.reg_timer_interval">
405                         <title><varname>reg_timer_interval</varname> (int)</title>
406                         <para>
407                         Timer interval (in seconds) at which registrations are managed, e.g. renewed as needed.
408                         </para>
409                         <para>
410                                 <emphasis>
411                                 The default value is 90 seconds.
412                                 </emphasis>
413                         </para>
414
415                         <example>
416                                 <title>Set <varname>reg_timer_interval</varname> parameter</title>
417                                 <programlisting format="linespecific">
418 ...
419 modparam("uac", "reg_timer_interval", 60)
420 ...
421                                 </programlisting>
422                         </example>
423                 </section>
424
425                 <section id="uac.p.reg_retry_interval">
426                         <title><varname>reg_retry_interval</varname> (int)</title>
427                         <para>
428                         Failed registration attempts will be retried after this interval
429                         (in seconds). The interval is not exact, retries may be
430                         attempted as much as reg_timer_interval secs earlier.
431                         If set to 0, failed registrations will be disabled permanently.
432                         </para>
433                         <para>The default value is 0 sec (disabled)</para>
434                         <example>
435                                 <title>Set <varname>reg_retry_interval</varname> parameter</title>
436                                 <programlisting format="linespecific">
437 ...
438 modparam("uac", "reg_retry_interval", 300)
439 ...
440                                 </programlisting>
441                         </example>
442                 </section>
443
444                 <section id="uac.p.reg_random_delay">
445                         <title><varname>reg_random_delay</varname> (int)</title>
446                         <para>
447                         Set a random reg_delay for each registration that has
448                         reg_delay set to 0 in the database.
449                         If set to 0, randomization will be disabled.
450                         </para>
451                         <para>The default value is 0 sec (disabled)</para>
452                         <example>
453                                 <title>Set <varname>reg_random_delay</varname> parameter</title>
454                                 <programlisting format="linespecific">
455 ...
456 modparam("uac", "reg_random_delay", 300)
457 ...
458                                 </programlisting>
459                         </example>
460                 </section>
461
462                 <section id="uac.p.reg_db_table">
463                         <title><varname>reg_db_table</varname> (string)</title>
464                         <para>
465                         DB table name to fetch user profiles for registration.
466                         </para>
467                         <para>
468                                 <emphasis>
469                                         This parameter is optional, it's default value being
470                                         <quote>uacreg</quote>.
471                                 </emphasis>
472                         </para>
473                         <example>
474                                 <title>Set <varname>reg_db_table</varname> parameter</title>
475                                 <programlisting format="linespecific">
476 ...
477 modparam("uac", "reg_db_table", "uacreg")
478 ...
479                                 </programlisting>
480                         </example>
481                 </section>
482
483                 <section id="uac.p.reg_contact_addr">
484                         <title><varname>reg_contact_addr</varname> (string)</title>
485                         <para>
486                         Address to be used to build contact address. Must be at least
487                         host part, can have port and parameters. Must not include 'sip:'.
488                         The username part of the Contact: URI will be the L_UUID field in the database.
489                         </para>
490                         <example>
491                                 <title>Set <varname>reg_contact_addr</varname> parameter</title>
492                                 <programlisting format="linespecific">
493 ...
494 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
495 ...
496                                 </programlisting>
497                         </example>
498                 </section>
499
500                 <section id="uac.p.reg_keep_callid">
501                         <title><varname>reg_keep_callid</varname> (int)</title>
502                         <para>
503                         If set to 0 (default), a new Call-Id will be generated for each
504                         registration attempt.
505                         If set to non-zero, the same Call-Id will be used for
506                         re-registrations, as recommended by RFC3261 section 10.2.4.
507                         A new Call-Id will be generated when a previous registration
508                         had failed.
509                         </para>
510                         <example>
511                                 <title>Set <varname>reg_keep_callid</varname> parameter</title>
512                                 <programlisting format="linespecific">
513 ...
514 modparam("uac", "reg_keep_callid", 1)
515 ...
516                                 </programlisting>
517                         </example>
518                 </section>
519
520
521                 <section id="uac.p.reg_active">
522                         <title><varname>reg_active</varname> (int)</title>
523                         <para>
524                                 If set to 0, no remote regisrations are done. In other words,
525                                 it can control at once if the module should do remote registratios
526                                 or not. It can be changed at runtime via rpc command
527                                 'uac.reg_active 0|1'.
528                         </para>
529                         <para>The default value is 1 (active).</para>
530                         <example>
531                                 <title>Set <varname>reg_active</varname> parameter</title>
532                                 <programlisting format="linespecific">
533 ...
534 modparam("uac", "reg_active", 0)
535 ...
536                                 </programlisting>
537                         </example>
538                 </section>
539
540                 <section id="uac.p.reg_gc_interval">
541                         <title><varname>reg_gc_interval</varname> (int)</title>
542                         <para>
543                         Timer interval (in seconds) at which remote registrations are cleaned
544                         up in case of failure or removed. When setting it take in consideration
545                         the maximum value for retransmission timeout, this param should be greater
546                         than it. This value also impacts how ofter the reload for remote
547                         registrations table can be executed -- the RPC command will fail if
548                         executed in less than reg_gc_interval value since the last reload.
549                         </para>
550                         <para>
551                                 <emphasis>
552                                 The default value is 150 seconds.
553                                 </emphasis>
554                         </para>
555
556                         <example>
557                                 <title>Set <varname>reg_gc_interval</varname> parameter</title>
558                                 <programlisting format="linespecific">
559 ...
560 modparam("uac", "reg_gc_interval", 60)
561 ...
562                                 </programlisting>
563                         </example>
564                 </section>
565
566         </section>
567
568         <section>
569                 <title>Functions</title>
570                 <section id="uac.f.uac_replace_from">
571                         <title>
572                                 <function moreinfo="none">uac_replace_from(display,uri)</function>
573                         </title>
574                         <para>
575                         Replace in FROM header the <emphasis>display</emphasis> name and
576                         the <emphasis>URI</emphasis> part.
577                         </para>
578                         <para>
579                         <emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
580                         can include pseudo-variables.
581                         </para>
582                         <para>
583                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
584                         </para>
585                         <para>NOTE: Previous versions of this function added double quotes automatically to 
586                         display variable. That is no longer the case, if you expect that behavior, you will 
587                         have to add the quotes by yourself.
588                         </para>
589                         <para>
590                         If you set restore_mode to AUTO, the URI will be modified automatically in
591                         all subsequent requests and replies in that dialog.
592                         </para>
593                         <para>
594                                 There are two ways in which the AUTO mode can be achieved.
595                         </para>
596                         <para>
597                                 One uses the rr module and appends to the Record-Route header a parameter
598                                 containing some strings from which the original and new URI can be computed.
599                                 The problem with this mode is that it relies on the fact the parties will
600                                 send the Route exactly as it was received. In case there is a change, the
601                                 resulting URIs will not be correct.
602                         </para>
603                         <para>
604                                 The other one uses the dialog module to store the original and new URI.
605                                 If you already use dialog module in your configuration, this is the advisable mode.
606                                 All you need to do to use this is to call dlg_manage() before calling uac_replace_from().
607                                 It works by storing the URIs as dialog variables and registering callbacks in dialog 
608                                 module for in dialog requests.
609                         </para>
610                         <example>
611                                 <title><function>uac_replace_from</function> usage</title>
612                                 <programlisting format="linespecific">
613 ...
614 # replace both display and uri
615 uac_replace_from("$avp(s:display)","$avp(s:uri)");
616 # replace only display and do not touch uri
617 uac_replace_from("batman","");   # display is replaced with: batman
618 uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
619 # remove display and replace uri
620 uac_replace_from("","sip:robin@gotham.org");
621 # remove display and do not touch uri
622 uac_replace_from("","");
623 ...
624                                 </programlisting>
625                         </example>
626                 </section>
627                 <section id="uac.f.uac_replace_from_uri">
628                         <title>
629                                 <function moreinfo="none">uac_replace_from(uri)</function>
630                         </title>
631                         <para>
632                                 Replace in FROM header the <emphasis>URI</emphasis> part
633                                 without altering the display name.
634                         </para>
635                         <para>
636                         <emphasis>URI</emphasis> parameter can include pseudo-variables.
637                         </para>
638                         <para>
639                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
640                         </para>
641                         <example>
642                                 <title><function>uac_replace_from</function> usage</title>
643                                 <programlisting format="linespecific">
644 ...
645 uac_replace_from("sip:batman@gotham.org");
646 ...
647                                 </programlisting>
648                         </example>
649                 </section>
650                 <section id="uac.f.uac_restore_from">
651                         <title>
652                                 <function moreinfo="none">uac_restore_from()</function>
653                         </title>
654                         <para>
655                         This function will check if the FROM URI was modified and will
656                         use the information stored in header parameter to restore
657                         the original FROM URI value.
658                         </para>
659                         <para>
660                         This function can be used from REQUEST_ROUTE.
661                         </para>
662                         <example>
663                                 <title><function>uac_restore_from</function> usage</title>
664                                 <programlisting format="linespecific">
665 ...
666 uac_restore_from();
667 ...
668                                 </programlisting>
669                         </example>
670                 </section>
671                 <section id="uac.f.uac_replace_to">
672                 <title>
673                                 <function moreinfo="none">uac_replace_to(display,uri)</function>
674                         </title>
675                         <para>
676                         Replace in TO header the <emphasis>display</emphasis> name and
677                         the <emphasis>URI</emphasis> part.
678                         </para>
679                         <para>
680                         <emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
681                         can include pseudo-variables.
682                         </para>
683                         <para>
684                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
685                         </para>
686                         <para>NOTE: Previous versions of this function added double quotes automatically to 
687                         display variable. That is no longer the case, if you expect that behavior, you will 
688                         have to add the quotes by yourself.
689                         </para>
690                         <example>
691                                 <title><function>uac_replace_to</function> usage</title>
692                                 <programlisting format="linespecific">
693 ...
694 # replace both display and uri
695 uac_replace_to("$avp(display)","$avp(uri)");
696 # replace only display and do not touch uri
697 uac_replace_to("batman","");   # display is replaced with: batman
698 uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
699 # remove display and replace uri
700 uac_replace_to("","sip:robin@gotham.org");
701 # remove display and do not touch uri
702 uac_replace_to("","");
703 ...
704                                 </programlisting>
705                         </example>
706                 </section>
707                 <section id="uac.f.uac_replace_to_uri">
708                         <title>
709                                 <function moreinfo="none">uac_replace_to(uri)</function>
710                         </title>
711                         <para>
712                                 Replace in TO header the <emphasis>URI</emphasis> part
713                                 without altering the display name.
714                         </para>
715                         <para>
716                         <emphasis>URI</emphasis> parameter can include pseudo-variables.
717                         </para>
718                         <para>
719                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
720                         </para>
721                         <para>
722                         If you set restore_mode to AUTO, the URI will be modified automatically in
723                         all subsequent requests and replies in that dialog.
724                         </para>
725                         <para>
726                                 There are two ways in which the AUTO mode can be achieved.
727                         </para>
728                         <para>
729                                 One uses the rr module and appends to the Record-Route header a parameter
730                                 containing some strings from which the original and new URI can be computed.
731                                 The problem with this mode is that it relies on the fact the parties will
732                                 send the Route exactly as it was received. In case there is a change, the
733                                 resulting URIs will not be correct.
734                         </para>
735                         <para>
736                                 The other one uses the dialog module to store the original and new URI.
737                                 If you already use dialog module in your configuration, this is the advisable mode.
738                                 All you need to do to use this is to call dlg_manage() before calling uac_replace_to().
739                                 It works by storing the URIs as dialog variables and registering callbacks in dialog 
740                                 module for in dialog requests.
741                         </para>
742
743                         <example>
744                                 <title><function>uac_replace_to</function> usage</title>
745                                 <programlisting format="linespecific">
746 ...
747 uac_replace_to("sip:batman@gotham.org");
748 ...
749                                 </programlisting>
750                         </example>
751                 </section>
752                 <section id="uac.f.uac_restore_to()">
753                         <title>
754                                 <function moreinfo="none">uac_restore_to()</function>
755                         </title>
756                         <para>
757                         This function will check if the TO URI was modified and will
758                         use the information stored in header parameter to restore
759                         the original TO URI value.
760                         </para>
761                         <para>
762                         This function can be used from REQUEST_ROUTE.
763                         </para>
764                         <example>
765                                 <title><function>uac_restore_to</function> usage</title>
766                                 <programlisting format="linespecific">
767 ...
768 uac_restore_to();
769 ...
770                                 </programlisting>
771                         </example>
772                 </section>
773                 <section id="uac.f.uac_auth">
774                         <title>
775                                 <function moreinfo="none">uac_auth()</function>
776                         </title>
777                         <para>
778                         This function can be called only from failure route and will 
779                         build the authentication response header and insert it into the
780                         request without sending anything.
781                         </para>
782                         <para>
783                         This function can be used from FAILURE_ROUTE.
784                         </para>
785                         <example>
786                                 <title><function>uac_auth</function> usage</title>
787                                 <programlisting format="linespecific">
788 ...
789 modparam("uac","auth_username_avp","$avp(auser)")
790 modparam("uac","auth_password_avp","$avp(apass)")
791 modparam("uac","auth_realm_avp","$avp(arealm)")
792
793 request_route {
794    ...
795    if(is_method("INVITE")) {
796       t_on_failure("TRUNKAUTH");
797    }
798    ...
799 }
800
801 failure_route[TRUNKAUTH] {
802
803     if (t_is_canceled()) {
804         exit;
805     }
806     if(t_check_status("401|407")) {
807         $avp(auser) = "test";
808         $avp(apass) = "test";
809         uac_auth();
810         t_relay();
811         exit;
812     }
813 }
814 ...
815                                 </programlisting>
816                         </example>
817                 </section>
818                 <section id="uac.f.uac_req_send">
819                         <title>
820                                 <function moreinfo="none">uac_req_send()</function>
821                         </title>
822                         <para>
823                         This function sends a SIP message from the configuration file.
824                         The message is built out of $uac_req(...) pseudo-variable.
825                         </para>
826                         <para>
827                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
828                         BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
829                         </para>
830                         <example>
831                                 <title><function>uac_req_send</function> usage</title>
832                                 <programlisting format="linespecific">
833 ...
834 $uac_req(method)="OPTIONS";
835 $uac_req(ruri)="sip:kamailio.org";
836 $uac_req(furi)="sip:kamailio.org";
837 $uac_req(turi)="sip:kamailio.org";
838 $uac_req(callid)=$(mb{s.md5});
839 uac_req_send();
840 ...
841                                 </programlisting>
842                         </example>
843                 </section>
844                 <section id="uac.f.uac_reg_lookup">
845                         <title>
846                                 <function moreinfo="none">uac_reg_lookup(uuid, dst)</function>
847                         </title>
848                         <para>
849                         This function sets the PV dst to SIP URI that correspond to uuid
850                         in uac registrations table. uuid and dst must be pseudo-variables.
851                         </para>
852                         <para>
853                         This function can be used from ANY_ROUTE.
854                         </para>
855                         <example>
856                                 <title><function>uac_reg_lookup</function> usage</title>
857                                 <programlisting format="linespecific">
858 ...
859
860 if(uac_reg_lookup("$rU", "$ru"))
861 {
862     lookup("location");
863 }
864 ...
865                                 </programlisting>
866                         </example>
867                 </section>
868                 <section id="uac.f.uac_reg_status">
869                         <title>
870                                 <function moreinfo="none">uac_reg_status(uuid)</function>
871                         </title>
872                         <para>
873                         This function returns the current registration status for the uuid.
874                         </para>
875                         <para>
876                         Return values:
877                         <itemizedlist>
878                         <listitem>
879                                 <para>
880                                 1 - a valid registration exists.
881                                 </para>
882                         </listitem>
883                         <listitem>
884                                 <para>
885                                 -1 - uuid does not exist or an error occurred while executing
886                                 the function.
887                                 </para>
888                         </listitem>
889                         <listitem>
890                                 <para>
891                                 -2 - a registration attempt is ongoing (and currently there is
892                                 no valid registration).
893                                 </para>
894                         </listitem>
895                         <listitem>
896                                 <para>
897                                 -3 - registration is disabled.
898                                 </para>
899                         </listitem>
900                         <listitem>
901                                 <para>
902                                 -99 - no valid registration, waiting for new registration attempt.
903                                 </para>
904                         </listitem>
905                         </itemizedlist>
906                         </para>
907                         <para>
908                         This function can be used from ANY_ROUTE.
909                         </para>
910                         <example>
911                                 <title><function>uac_reg_status</function> usage</title>
912                                 <programlisting format="linespecific">
913 ...
914 $var(status) = uac_reg_status("$rU");
915 ...
916                                 </programlisting>
917                         </example>
918                 </section>
919                 <section id="uac.f.uac_reg_request_to">
920                         <title>
921                                 <function moreinfo="none">uac_reg_request_to(user, mode)</function>
922                         </title>
923                         <para>
924                         This function can be used to send an authenticated request to a remote user in 
925                         the uac registrations table. It sets the request-uri, dst-uri and auth_*_avp
926                         pv's to the values that correspond to the supplied user.
927                         </para>
928                         <para>
929                         The mode indicates whether the user should match the local uuid (mode=0), or the username (mode=1).
930                         </para>
931                         <para>
932                         The auth_*_avp module parameters must be set to valid pv&apos;s.
933                         </para>
934                         <para>
935                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
936                         </para>
937                         <example>
938                                 <title><function>uac_reg_request_to</function> usage</title>
939                                 <programlisting format="linespecific">
940 ...
941
942 if(uac_reg_request_to("$fU", 0))
943 {
944         xlog("L_NOTICE", "Found remote user [$rU] on [$rd] via [$du]");
945         t_on_failure("REMOTE_AUTH");
946
947         t_relay()
948 }
949 ...
950 failure_route[REMOTE_AUTH] {
951         if ($T_reply_code == 401 or $T_reply_code == 407) {
952                 xlog("L_NOTICE", "Remote asked for authentication");
953                 uac_auth()
954         }
955 }
956 ...
957                                 </programlisting>
958                         </example>
959                 </section>
960                 <section id="uac.f.uac_reg_enable">
961                         <title>
962                                 <function moreinfo="none">uac_reg_enable(attr, val)</function>
963                         </title>
964                 <para>
965                         Enable a remote registration record based on a filter specified by
966                         attribute and value. The attribute can be: l_uuid, l_username,
967                         r_username or auth_username. The value is what should be matched
968                         against the value of the attribute in the remote registration record.
969                 </para>
970                 <para>
971                         The SIP processing is done on the next timer routine.
972                 </para>
973                 <example>
974                 <title><function>uac_reg_enable</function> usage</title>
975                         <programlisting format="linespecific">
976 ...
977    uac_reg_enable("l_uuid", "account123");
978 ...
979                         </programlisting>
980                 </example>
981                 </section>
982
983                 <section id="uac.f.uac_reg_disable">
984                         <title>
985                                 <function moreinfo="none">uac_reg_disable(attr, val)</function>
986                         </title>
987                 <para>
988                         Disable a remote registration record based on a filter specified by
989                         attribute and value. The attribute can be: l_uuid, l_username,
990                         r_username or auth_username. The value is what should be matched
991                         against the value of the attribute in the remote registration record.
992                 </para>
993                 <para>
994                         The SIP processing is done on the next timer routine.
995                 </para>
996                 <example>
997                 <title><function>uac_reg_disable</function> usage</title>
998                         <programlisting format="linespecific">
999 ...
1000    uac_reg_disable("l_uuid", "account123");
1001 ...
1002                         </programlisting>
1003                 </example>
1004                 </section>
1005
1006                 <section id="uac.f.uac_reg_refresh">
1007                         <title>
1008                                 <function moreinfo="none">uac_reg_refresh(luuid)</function>
1009                         </title>
1010                 <para>
1011                         Refresh the uac remote registration record based on local uuid. If
1012                         the record was already loaded, new values are taken from database,
1013                         otherwise a new record is created.
1014                 </para>
1015                 <example>
1016                 <title><function>uac_reg_refresh</function> usage</title>
1017                         <programlisting format="linespecific">
1018 ...
1019    uac_reg_refresh("account123");
1020 ...
1021                         </programlisting>
1022                 </example>
1023                 </section>
1024         </section>
1025         <section>
1026                 <title>Pseudo Variables</title>
1027                 <itemizedlist>
1028                         <listitem><para>
1029                                 <emphasis>$uac_req(key)</emphasis>
1030                         </para></listitem>
1031                 </itemizedlist>
1032                 <para>
1033                 Exported pseudo-variables are documented at &kamwikilink;.
1034                 </para>
1035         </section>
1036
1037         <section>
1038                 <title>Event Routes</title>
1039                 <section id="uac.ert.uac_reply">
1040                         <title>
1041                                 <function moreinfo="none">event_route[uac:reply]</function>
1042                         </title>
1043                 <para>
1044                         Event route executed for the final reply of the branch for the
1045                         request sent with uac_req_send(). The associated $uac_req(evroute)
1046                         has to be set to 1. If the request is challenged for authentication
1047                         with 401/407, then the event_route is executed twice, first for
1048                         401/407 and second for final reply of the transaction.
1049                 </para>
1050                 <example>
1051                 <title><function>event_route[uac:reply]</function> usage</title>
1052                         <programlisting format="linespecific">
1053 ...
1054 $uac_req(method)="OPTIONS";
1055 $uac_req(ruri)="sip:kamailio.org";
1056 $uac_req(furi)="sip:kamailio.org";
1057 $uac_req(turi)="sip:kamailio.org";
1058 $uac_req(callid)=$(mb{s.md5});
1059 $uac_req(evroute)=1;
1060 uac_req_send();
1061 ...
1062 event_route[uac:reply] {
1063     xlog("received reply code is: $uac_req(evcode)\n");
1064 }
1065 ...
1066                         </programlisting>
1067                 </example>
1068                 </section>
1069         </section>
1070
1071         <section>
1072                 <title>Counters</title>
1073                 <itemizedlist>
1074                         <listitem><para>
1075                                 <emphasis>regtotal</emphasis>: Total number of registrations
1076                         </para></listitem>
1077                         <listitem><para>
1078                                 <emphasis>regactive</emphasis>: Total number of active registrations (successfully registered with service)
1079                         </para></listitem>
1080                         <listitem><para>
1081                                 <emphasis>regdisabled</emphasis>: Total number of disabled registrations (no longer active)
1082                         </para></listitem>
1083                 </itemizedlist>
1084         </section>
1085         <section>
1086                 <title>RPC Commands</title>
1087                 <section id="uac.r.uac.reg_dump">
1088                         <title>
1089                                 <function moreinfo="none">uac.reg_dump</function>
1090                         </title>
1091                 <para>
1092                 Dump the content of remote registration table from memory.
1093                 </para>
1094                 <example>
1095                 <title><function>uac.reg_dump</function> usage</title>
1096                         <programlisting format="linespecific">
1097 ...
1098    kamcmd uac.reg_dump
1099 ...
1100                         </programlisting>
1101                 </example>
1102
1103                 </section>
1104                 <section id="uac.r.uac.reg_info">
1105                         <title>
1106                                 <function moreinfo="none">uac.reg_info</function>
1107                         </title>
1108                 <para>
1109                         Return the details of a remote registration record based on
1110                         a filter. The command has two parameter: attribute and value.
1111                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1112                         The value is what should be matched against the value of the attribute
1113                         in the remote registration record.
1114                 </para>
1115                 <para>
1116                         The state of the registration is reflected in the flags field:
1117                         <itemizedlist>
1118                         <listitem><para>
1119                         1 (2^0) - registration profile is disabled
1120                         </para></listitem>
1121                         <listitem><para>
1122                         2 (2^1) - registration in progress
1123                         </para></listitem>
1124                         <listitem><para>
1125                         4 (2^2) - registration succeeded
1126                         </para></listitem>
1127                         <listitem><para>
1128                         8 (2^3) - registration in progres with authentication
1129                         </para></listitem>
1130                         <listitem><para>
1131                         16 (2^4) - registration initialized (after loading from database,
1132                         the registration process was initialized)
1133                         </para></listitem>
1134                 </itemizedlist>
1135                 </para>
1136                 <example>
1137                 <title><function>uac.reg_info</function> usage</title>
1138                         <programlisting format="linespecific">
1139 ...
1140    kamcmd uac.reg_info l_uuid account123
1141    kamcmd uac.reg_info l_uuid s:12345678
1142 ...
1143                         </programlisting>
1144                 </example>
1145                 </section>
1146
1147                 <section id="uac.r.uac.reg_enable">
1148                         <title>
1149                                 <function moreinfo="none">uac.reg_enable</function>
1150                         </title>
1151                 <para>
1152                         Enable a remote registration record based on
1153                         a filter. The command has two parameter: attribute and value.
1154                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1155                         The value is what should be matched against the value of the attribute
1156                         in the remote registration record.
1157                 </para>
1158                 <example>
1159                 <title><function>uac.reg_enable</function> usage</title>
1160                         <programlisting format="linespecific">
1161 ...
1162    kamcmd uac.reg_enable l_uuid account123
1163    kamcmd uac.reg_enable l_uuid s:12345678
1164 ...
1165                         </programlisting>
1166                 </example>
1167                 </section>
1168
1169                 <section id="uac.r.uac.reg_disable">
1170                         <title>
1171                                 <function moreinfo="none">uac.reg_disable</function>
1172                         </title>
1173                 <para>
1174                         Disable a remote registration record based on
1175                         a filter. The command has two parameter: attribute and value.
1176                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1177                         The value is what should be matched against the value of the attribute
1178                         in the remote registration record.
1179                 </para>
1180                 <example>
1181                 <title><function>uac.reg_disable</function> usage</title>
1182                         <programlisting format="linespecific">
1183 ...
1184    kamcmd uac.reg_disable l_uuid account123
1185    kamcmd uac.reg_disable l_uuid s:12345678
1186 ...
1187                         </programlisting>
1188                 </example>
1189                 </section>
1190
1191                 <section id="uac.r.uac.reg_reload">
1192                         <title>
1193                                 <function moreinfo="none">uac.reg_reload</function>
1194                         </title>
1195                 <para>
1196                         Reload the records from database for remote registrations.
1197                 </para>
1198                 <example>
1199                 <title><function>uac.reg_reload</function> usage</title>
1200                         <programlisting format="linespecific">
1201 ...
1202    kamcmd uac.reg_reload
1203 ...
1204                         </programlisting>
1205                 </example>
1206                 </section>
1207
1208                 <section id="uac.r.uac.reg_refresh">
1209                         <title>
1210                                 <function moreinfo="none">uac.reg_refresh</function>
1211                         </title>
1212                 <para>
1213                         Load one record by l_uuid from database for remote registrations.
1214                         If the record exists in memory, it will be replaced with the new
1215                         values loaded from database.
1216                 </para>
1217                 <example>
1218                 <title><function>uac.reg_refresh</function> usage</title>
1219                         <programlisting format="linespecific">
1220 ...
1221    kamcmd uac.reg_refresh account123
1222    kamcmd uac.reg_refresh s:12345678
1223 ...
1224                         </programlisting>
1225                 </example>
1226                 </section>
1227
1228                 <section id="uac.r.uac.reg_active">
1229                         <title>
1230                                 <function moreinfo="none">uac.reg_active</function>
1231                         </title>
1232                 <para>
1233                         Control if the module should do remote registrations or not. Setting
1234                         to 1 enables remote registrations for all records and 0 disables
1235                         doing them.
1236                 </para>
1237                 <example>
1238                 <title><function>uac.reg_active</function> usage</title>
1239                         <programlisting format="linespecific">
1240 ...
1241    kamctl rpc uac.reg_active 0
1242    kamctl rpc uac.reg_active 1
1243 ...
1244                         </programlisting>
1245                 </example>
1246                 </section>
1247
1248         </section>
1249
1250         <section>
1251                 <title>Remote Registration</title>
1252                 <para>
1253                 The module can register contact addresses to remote REGISTRAR servers.
1254                 You have to add records to uacreg table. The table stores following
1255                 attributes:
1256                 </para>
1257
1258                 <itemizedlist>
1259                         <listitem><para>
1260                         <emphasis>l_uuid</emphasis> - local unique user id, e.g.,:
1261                         12345678
1262                         </para></listitem>
1263                 </itemizedlist>
1264                 <itemizedlist>
1265                         <listitem><para>
1266                         <emphasis>l_username</emphasis> - local user name, e.g.,: test
1267                         </para></listitem>
1268                 </itemizedlist>
1269                 <itemizedlist>
1270                         <listitem><para>
1271                         <emphasis>l_domain</emphasis> - local domain, e.g.,:
1272                         mysipserver.com
1273                         </para></listitem>
1274                 </itemizedlist>
1275                 <itemizedlist>
1276                         <listitem><para>
1277                         <emphasis>r_username</emphasis> - remote username, e.g.,:
1278                         test123
1279                         </para></listitem>
1280                 </itemizedlist>
1281                 <itemizedlist>
1282                         <listitem><para>
1283                         <emphasis>r_domain</emphasis> - remote domain, e.g.,:
1284                         sipprovider.com
1285                         </para></listitem>
1286                 </itemizedlist>
1287                 <itemizedlist>
1288                         <listitem><para>
1289                         <emphasis>realm</emphasis> - remote relam, e.g.,:
1290                         sipprovider.com
1291                         </para></listitem>
1292                 </itemizedlist>
1293                 <itemizedlist>
1294                         <listitem><para>
1295                         <emphasis>auth_username</emphasis> - authentication username,
1296                         e.g.,: test123
1297                         </para></listitem>
1298                 </itemizedlist>
1299                 <itemizedlist>
1300                         <listitem><para>
1301                         <emphasis>auth_password</emphasis> - authentication password,
1302                         e.g.,: xxxxxx
1303                         </para></listitem>
1304                 </itemizedlist>
1305                 <itemizedlist>
1306                         <listitem><para>
1307                         <emphasis>auth_proxy</emphasis> - SIP address of authentication
1308                         proxy, e.g.,: sip:sipprovider.com
1309                         </para></listitem>
1310                 </itemizedlist>
1311                 <itemizedlist>
1312                         <listitem><para>
1313                         <emphasis>expires</emphasis> - expiration time for registration,
1314                         in seconds, e.g.,: 360
1315                         </para></listitem>
1316                 </itemizedlist>
1317                 <itemizedlist>
1318                         <listitem><para>
1319                         <emphasis>flags</emphasis> - the state of the registration, see <xref linkend="uac.r.uac.reg_info"/>
1320                         </para></listitem>
1321                 </itemizedlist>
1322                 <itemizedlist>
1323                         <listitem><para>
1324                         <emphasis>reg_delay</emphasis> - delay initial registration with at least reg_delay seconds, e.g.,: 3
1325                         </para></listitem>
1326                 </itemizedlist>
1327                 <para>
1328                 The module takes care of sending REGISTER and refresh registrations
1329                 before they expire.
1330                 </para>
1331                 <para>
1332                 When calls come in, you have to run uac_reg_lookup() that will detect
1333                 if the call is coming from a remote SIP provider and can change the
1334                 R-URI to local username@domain. Afterwards you can run location lookup.
1335                 </para>
1336
1337                 <example>
1338                 <title><function>lookup remote registrations</function> usage</title>
1339                         <programlisting format="linespecific">
1340 ...
1341     if(uac_reg_lookup("$rU", "$ru")) {
1342         xlog("request from a remote SIP provider [$ou => $ru]\n");
1343     }
1344     lookup("location");
1345 ...
1346                         </programlisting>
1347                 </example>
1348         </section>
1349 </chapter>
1350