uac: docs - examples with rpc commands having params numbers converted to string
[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
541         </section>
542
543         <section>
544                 <title>Functions</title>
545                 <section id="uac.f.uac_replace_from">
546                         <title>
547                                 <function moreinfo="none">uac_replace_from(display,uri)</function>
548                         </title>
549                         <para>
550                         Replace in FROM header the <emphasis>display</emphasis> name and
551                         the <emphasis>URI</emphasis> part.
552                         </para>
553                         <para>
554                         <emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
555                         can include pseudo-variables.
556                         </para>
557                         <para>
558                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
559                         </para>
560                         <para>NOTE: Previous versions of this function added double quotes automatically to 
561                         display variable. That is no longer the case, if you expect that behavior, you will 
562                         have to add the quotes by yourself.
563                         </para>
564                         <para>
565                         If you set restore_mode to AUTO, the URI will be modified automatically in
566                         all subsequent requests and replies in that dialog.
567                         </para>
568                         <para>
569                                 There are two ways in which the AUTO mode can be achieved.
570                         </para>
571                         <para>
572                                 One uses the rr module and appends to the Record-Route header a parameter
573                                 containing some strings from which the original and new URI can be computed.
574                                 The problem with this mode is that it relies on the fact the parties will
575                                 send the Route exactly as it was received. In case there is a change, the
576                                 resulting URIs will not be correct.
577                         </para>
578                         <para>
579                                 The other one uses the dialog module to store the original and new URI.
580                                 If you already use dialog module in your configuration, this is the advisable mode.
581                                 All you need to do to use this is to call dlg_manage() before calling uac_replace_from().
582                                 It works by storing the URIs as dialog variables and registering callbacks in dialog 
583                                 module for in dialog requests.
584                         </para>
585                         <example>
586                                 <title><function>uac_replace_from</function> usage</title>
587                                 <programlisting format="linespecific">
588 ...
589 # replace both display and uri
590 uac_replace_from("$avp(s:display)","$avp(s:uri)");
591 # replace only display and do not touch uri
592 uac_replace_from("batman","");   # display is replaced with: batman
593 uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
594 # remove display and replace uri
595 uac_replace_from("","sip:robin@gotham.org");
596 # remove display and do not touch uri
597 uac_replace_from("","");
598 ...
599                                 </programlisting>
600                         </example>
601                 </section>
602                 <section id="uac.f.uac_replace_from_uri">
603                         <title>
604                                 <function moreinfo="none">uac_replace_from(uri)</function>
605                         </title>
606                         <para>
607                                 Replace in FROM header the <emphasis>URI</emphasis> part
608                                 without altering the display name.
609                         </para>
610                         <para>
611                         <emphasis>URI</emphasis> parameter can include pseudo-variables.
612                         </para>
613                         <para>
614                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
615                         </para>
616                         <example>
617                                 <title><function>uac_replace_from</function> usage</title>
618                                 <programlisting format="linespecific">
619 ...
620 uac_replace_from("sip:batman@gotham.org");
621 ...
622                                 </programlisting>
623                         </example>
624                 </section>
625                 <section id="uac.f.uac_restore_from">
626                         <title>
627                                 <function moreinfo="none">uac_restore_from()</function>
628                         </title>
629                         <para>
630                         This function will check if the FROM URI was modified and will
631                         use the information stored in header parameter to restore
632                         the original FROM URI value.
633                         </para>
634                         <para>
635                         This function can be used from REQUEST_ROUTE.
636                         </para>
637                         <example>
638                                 <title><function>uac_restore_from</function> usage</title>
639                                 <programlisting format="linespecific">
640 ...
641 uac_restore_from();
642 ...
643                                 </programlisting>
644                         </example>
645                 </section>
646                 <section id="uac.f.uac_replace_to">
647                 <title>
648                                 <function moreinfo="none">uac_replace_to(display,uri)</function>
649                         </title>
650                         <para>
651                         Replace in TO header the <emphasis>display</emphasis> name and
652                         the <emphasis>URI</emphasis> part.
653                         </para>
654                         <para>
655                         <emphasis>display</emphasis> and <emphasis>URI</emphasis> parameters
656                         can include pseudo-variables.
657                         </para>
658                         <para>
659                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
660                         </para>
661                         <para>NOTE: Previous versions of this function added double quotes automatically to 
662                         display variable. That is no longer the case, if you expect that behavior, you will 
663                         have to add the quotes by yourself.
664                         </para>
665                         <example>
666                                 <title><function>uac_replace_to</function> usage</title>
667                                 <programlisting format="linespecific">
668 ...
669 # replace both display and uri
670 uac_replace_to("$avp(display)","$avp(uri)");
671 # replace only display and do not touch uri
672 uac_replace_to("batman","");   # display is replaced with: batman
673 uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
674 # remove display and replace uri
675 uac_replace_to("","sip:robin@gotham.org");
676 # remove display and do not touch uri
677 uac_replace_to("","");
678 ...
679                                 </programlisting>
680                         </example>
681                 </section>
682                 <section id="uac.f.uac_replace_to_uri">
683                         <title>
684                                 <function moreinfo="none">uac_replace_to(uri)</function>
685                         </title>
686                         <para>
687                                 Replace in TO header the <emphasis>URI</emphasis> part
688                                 without altering the display name.
689                         </para>
690                         <para>
691                         <emphasis>URI</emphasis> parameter can include pseudo-variables.
692                         </para>
693                         <para>
694                         This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
695                         </para>
696                         <para>
697                         If you set restore_mode to AUTO, the URI will be modified automatically in
698                         all subsequent requests and replies in that dialog.
699                         </para>
700                         <para>
701                                 There are two ways in which the AUTO mode can be achieved.
702                         </para>
703                         <para>
704                                 One uses the rr module and appends to the Record-Route header a parameter
705                                 containing some strings from which the original and new URI can be computed.
706                                 The problem with this mode is that it relies on the fact the parties will
707                                 send the Route exactly as it was received. In case there is a change, the
708                                 resulting URIs will not be correct.
709                         </para>
710                         <para>
711                                 The other one uses the dialog module to store the original and new URI.
712                                 If you already use dialog module in your configuration, this is the advisable mode.
713                                 All you need to do to use this is to call dlg_manage() before calling uac_replace_to().
714                                 It works by storing the URIs as dialog variables and registering callbacks in dialog 
715                                 module for in dialog requests.
716                         </para>
717
718                         <example>
719                                 <title><function>uac_replace_to</function> usage</title>
720                                 <programlisting format="linespecific">
721 ...
722 uac_replace_to("sip:batman@gotham.org");
723 ...
724                                 </programlisting>
725                         </example>
726                 </section>
727                 <section id="uac.f.uac_restore_to()">
728                         <title>
729                                 <function moreinfo="none">uac_restore_to()</function>
730                         </title>
731                         <para>
732                         This function will check if the TO URI was modified and will
733                         use the information stored in header parameter to restore
734                         the original TO URI value.
735                         </para>
736                         <para>
737                         This function can be used from REQUEST_ROUTE.
738                         </para>
739                         <example>
740                                 <title><function>uac_restore_to</function> usage</title>
741                                 <programlisting format="linespecific">
742 ...
743 uac_restore_to();
744 ...
745                                 </programlisting>
746                         </example>
747                 </section>
748                 <section id="uac.f.uac_auth">
749                         <title>
750                                 <function moreinfo="none">uac_auth()</function>
751                         </title>
752                         <para>
753                         This function can be called only from failure route and will 
754                         build the authentication response header and insert it into the
755                         request without sending anything.
756                         </para>
757                         <para>
758                         This function can be used from FAILURE_ROUTE.
759                         </para>
760                         <example>
761                                 <title><function>uac_auth</function> usage</title>
762                                 <programlisting format="linespecific">
763 ...
764 modparam("uac","auth_username_avp","$avp(auser)")
765 modparam("uac","auth_password_avp","$avp(apass)")
766 modparam("uac","auth_realm_avp","$avp(arealm)")
767
768 request_route {
769    ...
770    if(is_method("INVITE")) {
771       t_on_failure("TRUNKAUTH");
772    }
773    ...
774 }
775
776 failure_route[TRUNKAUTH] {
777
778     if (t_is_canceled()) {
779         exit;
780     }
781     if(t_check_status("401|407")) {
782         $avp(auser) = "test";
783         $avp(apass) = "test";
784         uac_auth();
785         t_relay();
786         exit;
787     }
788 }
789 ...
790                                 </programlisting>
791                         </example>
792                 </section>
793                 <section id="uac.f.uac_req_send">
794                         <title>
795                                 <function moreinfo="none">uac_req_send()</function>
796                         </title>
797                         <para>
798                         This function sends a SIP message from the configuration file.
799                         The message is built out of $uac_req(...) pseudo-variable.
800                         </para>
801                         <para>
802                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
803                         BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
804                         </para>
805                         <example>
806                                 <title><function>uac_req_send</function> usage</title>
807                                 <programlisting format="linespecific">
808 ...
809 $uac_req(method)="OPTIONS";
810 $uac_req(ruri)="sip:kamailio.org";
811 $uac_req(furi)="sip:kamailio.org";
812 $uac_req(turi)="sip:kamailio.org";
813 $uac_req(callid)=$(mb{s.md5});
814 uac_req_send();
815 ...
816                                 </programlisting>
817                         </example>
818                 </section>
819                 <section id="uac.f.uac_reg_lookup">
820                         <title>
821                                 <function moreinfo="none">uac_reg_lookup(uuid, dst)</function>
822                         </title>
823                         <para>
824                         This function sets the PV dst to SIP URI that correspond to uuid
825                         in uac registrations table. uuid and dst must be pseudo-variables.
826                         </para>
827                         <para>
828                         This function can be used from ANY_ROUTE.
829                         </para>
830                         <example>
831                                 <title><function>uac_reg_lookup</function> usage</title>
832                                 <programlisting format="linespecific">
833 ...
834
835 if(uac_reg_lookup("$rU", "$ru"))
836 {
837     lookup("location");
838 }
839 ...
840                                 </programlisting>
841                         </example>
842                 </section>
843                 <section id="uac.f.uac_reg_status">
844                         <title>
845                                 <function moreinfo="none">uac_reg_status(uuid)</function>
846                         </title>
847                         <para>
848                         This function returns the current registration status for the uuid.
849                         </para>
850                         <para>
851                         Return values:
852                         <itemizedlist>
853                         <listitem>
854                                 <para>
855                                 1 - a valid registration exists.
856                                 </para>
857                         </listitem>
858                         <listitem>
859                                 <para>
860                                 -1 - uuid does not exist or an error occurred while executing
861                                 the function.
862                                 </para>
863                         </listitem>
864                         <listitem>
865                                 <para>
866                                 -2 - a registration attempt is ongoing (and currently there is
867                                 no valid registration).
868                                 </para>
869                         </listitem>
870                         <listitem>
871                                 <para>
872                                 -3 - registration is disabled.
873                                 </para>
874                         </listitem>
875                         <listitem>
876                                 <para>
877                                 -99 - no valid registration, waiting for new registration attempt.
878                                 </para>
879                         </listitem>
880                         </itemizedlist>
881                         </para>
882                         <para>
883                         This function can be used from ANY_ROUTE.
884                         </para>
885                         <example>
886                                 <title><function>uac_reg_status</function> usage</title>
887                                 <programlisting format="linespecific">
888 ...
889 $var(status) = uac_reg_status("$rU");
890 ...
891                                 </programlisting>
892                         </example>
893                 </section>
894                 <section id="uac.f.uac_reg_request_to">
895                         <title>
896                                 <function moreinfo="none">uac_reg_request_to(user, mode)</function>
897                         </title>
898                         <para>
899                         This function can be used to send an authenticated request to a remote user in 
900                         the uac registrations table. It sets the request-uri, dst-uri and auth_*_avp
901                         pv's to the values that correspond to the supplied user.
902                         </para>
903                         <para>
904                         The mode indicates whether the user should match the local uuid (mode=0), or the username (mode=1).
905                         </para>
906                         <para>
907                         The auth_*_avp module parameters must be set to valid pv&apos;s.
908                         </para>
909                         <para>
910                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
911                         </para>
912                         <example>
913                                 <title><function>uac_reg_request_to</function> usage</title>
914                                 <programlisting format="linespecific">
915 ...
916
917 if(uac_reg_request_to("$fU", 0))
918 {
919         xlog("L_NOTICE", "Found remote user [$rU] on [$rd] via [$du]");
920         t_on_failure("REMOTE_AUTH");
921
922         t_relay()
923 }
924 ...
925 failure_route[REMOTE_AUTH] {
926         if ($T_reply_code == 401 or $T_reply_code == 407) {
927                 xlog("L_NOTICE", "Remote asked for authentication");
928                 uac_auth()
929         }
930 }
931 ...
932                                 </programlisting>
933                         </example>
934                 </section>
935                 <section id="uac.f.uac_reg_enable">
936                         <title>
937                                 <function moreinfo="none">uac_reg_enable(attr, val)</function>
938                         </title>
939                 <para>
940                         Enable a remote registration record based on a filter specified by
941                         attribute and value. The attribute can be: l_uuid, l_username,
942                         r_username or auth_username. The value is what should be matched
943                         against the value of the attribute in the remote registration record.
944                 </para>
945                 <para>
946                         The SIP processing is done on the next timer routine.
947                 </para>
948                 <example>
949                 <title><function>uac_reg_enable</function> usage</title>
950                         <programlisting format="linespecific">
951 ...
952    uac_reg_enable("l_uuid", "account123");
953 ...
954                         </programlisting>
955                 </example>
956                 </section>
957
958                 <section id="uac.f.uac_reg_disable">
959                         <title>
960                                 <function moreinfo="none">uac_reg_disable(attr, val)</function>
961                         </title>
962                 <para>
963                         Disable a remote registration record based on a filter specified by
964                         attribute and value. The attribute can be: l_uuid, l_username,
965                         r_username or auth_username. The value is what should be matched
966                         against the value of the attribute in the remote registration record.
967                 </para>
968                 <para>
969                         The SIP processing is done on the next timer routine.
970                 </para>
971                 <example>
972                 <title><function>uac_reg_disable</function> usage</title>
973                         <programlisting format="linespecific">
974 ...
975    uac_reg_disable("l_uuid", "account123");
976 ...
977                         </programlisting>
978                 </example>
979                 </section>
980
981                 <section id="uac.f.uac_reg_refresh">
982                         <title>
983                                 <function moreinfo="none">uac_reg_refresh(luuid)</function>
984                         </title>
985                 <para>
986                         Refresh the uac remote registration record based on local uuid. If
987                         the record was already loaded, new values are taken from database,
988                         otherwise a new record is created.
989                 </para>
990                 <example>
991                 <title><function>uac_reg_refresh</function> usage</title>
992                         <programlisting format="linespecific">
993 ...
994    uac_reg_refresh("account123");
995 ...
996                         </programlisting>
997                 </example>
998                 </section>
999         </section>
1000         <section>
1001                 <title>Pseudo Variables</title>
1002                 <itemizedlist>
1003                         <listitem><para>
1004                                 <emphasis>$uac_req(key)</emphasis>
1005                         </para></listitem>
1006                 </itemizedlist>
1007                 <para>
1008                 Exported pseudo-variables are documented at &kamwikilink;.
1009                 </para>
1010         </section>
1011
1012         <section>
1013                 <title>Event Routes</title>
1014                 <section id="uac.ert.uac_reply">
1015                         <title>
1016                                 <function moreinfo="none">event_route[uac:reply]</function>
1017                         </title>
1018                 <para>
1019                         Event route executed for the final reply of the branch for the
1020                         request sent with uac_req_send(). The associated $uac_req(evroute)
1021                         has to be set to 1. If the request is challenged for authentication
1022                         with 401/407, then the event_route is executed twice, first for
1023                         401/407 and second for final reply of the transaction.
1024                 </para>
1025                 <example>
1026                 <title><function>event_route[uac:reply]</function> usage</title>
1027                         <programlisting format="linespecific">
1028 ...
1029 $uac_req(method)="OPTIONS";
1030 $uac_req(ruri)="sip:kamailio.org";
1031 $uac_req(furi)="sip:kamailio.org";
1032 $uac_req(turi)="sip:kamailio.org";
1033 $uac_req(callid)=$(mb{s.md5});
1034 $uac_req(evroute)=1;
1035 uac_req_send();
1036 ...
1037 event_route[uac:reply] {
1038     xlog("received reply code is: $uac_req(evcode)\n");
1039 }
1040 ...
1041                         </programlisting>
1042                 </example>
1043                 </section>
1044         </section>
1045
1046         <section>
1047                 <title>Counters</title>
1048                 <itemizedlist>
1049                         <listitem><para>
1050                                 <emphasis>regtotal</emphasis>: Total number of registrations
1051                         </para></listitem>
1052                         <listitem><para>
1053                                 <emphasis>regactive</emphasis>: Total number of active registrations (successfully registered with service)
1054                         </para></listitem>
1055                         <listitem><para>
1056                                 <emphasis>regdisabled</emphasis>: Total number of disabled registrations (no longer active)
1057                         </para></listitem>
1058                 </itemizedlist>
1059         </section>
1060         <section>
1061                 <title>RPC Commands</title>
1062                 <section id="uac.r.uac.reg_dump">
1063                         <title>
1064                                 <function moreinfo="none">uac.reg_dump</function>
1065                         </title>
1066                 <para>
1067                 Dump the content of remote registration table from memory.
1068                 </para>
1069                 <example>
1070                 <title><function>uac.reg_dump</function> usage</title>
1071                         <programlisting format="linespecific">
1072 ...
1073    kamcmd uac.reg_dump
1074 ...
1075                         </programlisting>
1076                 </example>
1077
1078                 </section>
1079                 <section id="uac.r.uac.reg_info">
1080                         <title>
1081                                 <function moreinfo="none">uac.reg_info</function>
1082                         </title>
1083                 <para>
1084                         Return the details of a remote registration record based on
1085                         a filter. The command has two parameter: attribute and value.
1086                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1087                         The value is what should be matched against the value of the attribute
1088                         in the remote registration record.
1089                 </para>
1090                 <para>
1091                         The state of the registration is reflected in the flags field:
1092                         <itemizedlist>
1093                         <listitem><para>
1094                         1 (2^0) - registration profile is disabled
1095                         </para></listitem>
1096                         <listitem><para>
1097                         2 (2^1) - registration in progress
1098                         </para></listitem>
1099                         <listitem><para>
1100                         4 (2^2) - registration succeeded
1101                         </para></listitem>
1102                         <listitem><para>
1103                         8 (2^3) - registration in progres with authentication
1104                         </para></listitem>
1105                         <listitem><para>
1106                         16 (2^4) - registration initialized (after loading from database,
1107                         the registration process was initialized)
1108                         </para></listitem>
1109                 </itemizedlist>
1110                 </para>
1111                 <example>
1112                 <title><function>uac.reg_info</function> usage</title>
1113                         <programlisting format="linespecific">
1114 ...
1115    kamcmd uac.reg_info l_uuid account123
1116    kamcmd uac.reg_info l_uuid s:12345678
1117 ...
1118                         </programlisting>
1119                 </example>
1120                 </section>
1121
1122                 <section id="uac.r.uac.reg_enable">
1123                         <title>
1124                                 <function moreinfo="none">uac.reg_enable</function>
1125                         </title>
1126                 <para>
1127                         Enable a remote registration record based on
1128                         a filter. The command has two parameter: attribute and value.
1129                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1130                         The value is what should be matched against the value of the attribute
1131                         in the remote registration record.
1132                 </para>
1133                 <example>
1134                 <title><function>uac.reg_enable</function> usage</title>
1135                         <programlisting format="linespecific">
1136 ...
1137    kamcmd uac.reg_enable l_uuid account123
1138    kamcmd uac.reg_enable l_uuid s:12345678
1139 ...
1140                         </programlisting>
1141                 </example>
1142                 </section>
1143
1144                 <section id="uac.r.uac.reg_disable">
1145                         <title>
1146                                 <function moreinfo="none">uac.reg_disable</function>
1147                         </title>
1148                 <para>
1149                         Disable a remote registration record based on
1150                         a filter. The command has two parameter: attribute and value.
1151                         The attribute can be: l_uuid, l_username, r_username or auth_username.
1152                         The value is what should be matched against the value of the attribute
1153                         in the remote registration record.
1154                 </para>
1155                 <example>
1156                 <title><function>uac.reg_disable</function> usage</title>
1157                         <programlisting format="linespecific">
1158 ...
1159    kamcmd uac.reg_disable l_uuid account123
1160    kamcmd uac.reg_disable l_uuid s:12345678
1161 ...
1162                         </programlisting>
1163                 </example>
1164                 </section>
1165
1166                 <section id="uac.r.uac.reg_reload">
1167                         <title>
1168                                 <function moreinfo="none">uac.reg_reload</function>
1169                         </title>
1170                 <para>
1171                         Reload the records from database for remote registrations.
1172                 </para>
1173                 <example>
1174                 <title><function>uac.reg_reload</function> usage</title>
1175                         <programlisting format="linespecific">
1176 ...
1177    kamcmd uac.reg_reload
1178 ...
1179                         </programlisting>
1180                 </example>
1181                 </section>
1182
1183                 <section id="uac.r.uac.reg_refresh">
1184                         <title>
1185                                 <function moreinfo="none">uac.reg_refresh</function>
1186                         </title>
1187                 <para>
1188                         Load one record by l_uuid from database for remote registrations.
1189                         If the record exists in memory, it will be replaced with the new
1190                         values loaded from database.
1191                 </para>
1192                 <example>
1193                 <title><function>uac.reg_refresh</function> usage</title>
1194                         <programlisting format="linespecific">
1195 ...
1196    kamcmd uac.reg_refresh account123
1197    kamcmd uac.reg_refresh s:12345678
1198 ...
1199                         </programlisting>
1200                 </example>
1201                 </section>
1202
1203                 <section id="uac.r.uac.reg_active">
1204                         <title>
1205                                 <function moreinfo="none">uac.reg_active</function>
1206                         </title>
1207                 <para>
1208                         Control if the module should do remote registrations or not. Setting
1209                         to 1 enables remote registrations for all records and 0 disables
1210                         doing them.
1211                 </para>
1212                 <example>
1213                 <title><function>uac.reg_active</function> usage</title>
1214                         <programlisting format="linespecific">
1215 ...
1216    kamctl rpc uac.reg_active 0
1217    kamctl rpc uac.reg_active 1
1218 ...
1219                         </programlisting>
1220                 </example>
1221                 </section>
1222
1223         </section>
1224
1225         <section>
1226                 <title>Remote Registration</title>
1227                 <para>
1228                 The module can register contact addresses to remote REGISTRAR servers.
1229                 You have to add records to uacreg table. The table stores following
1230                 attributes:
1231                 </para>
1232
1233                 <itemizedlist>
1234                         <listitem><para>
1235                         <emphasis>l_uuid</emphasis> - local unique user id, e.g.,:
1236                         12345678
1237                         </para></listitem>
1238                 </itemizedlist>
1239                 <itemizedlist>
1240                         <listitem><para>
1241                         <emphasis>l_username</emphasis> - local user name, e.g.,: test
1242                         </para></listitem>
1243                 </itemizedlist>
1244                 <itemizedlist>
1245                         <listitem><para>
1246                         <emphasis>l_domain</emphasis> - local domain, e.g.,:
1247                         mysipserver.com
1248                         </para></listitem>
1249                 </itemizedlist>
1250                 <itemizedlist>
1251                         <listitem><para>
1252                         <emphasis>r_username</emphasis> - remote username, e.g.,:
1253                         test123
1254                         </para></listitem>
1255                 </itemizedlist>
1256                 <itemizedlist>
1257                         <listitem><para>
1258                         <emphasis>r_domain</emphasis> - remote domain, e.g.,:
1259                         sipprovider.com
1260                         </para></listitem>
1261                 </itemizedlist>
1262                 <itemizedlist>
1263                         <listitem><para>
1264                         <emphasis>realm</emphasis> - remote relam, e.g.,:
1265                         sipprovider.com
1266                         </para></listitem>
1267                 </itemizedlist>
1268                 <itemizedlist>
1269                         <listitem><para>
1270                         <emphasis>auth_username</emphasis> - authentication username,
1271                         e.g.,: test123
1272                         </para></listitem>
1273                 </itemizedlist>
1274                 <itemizedlist>
1275                         <listitem><para>
1276                         <emphasis>auth_password</emphasis> - authentication password,
1277                         e.g.,: xxxxxx
1278                         </para></listitem>
1279                 </itemizedlist>
1280                 <itemizedlist>
1281                         <listitem><para>
1282                         <emphasis>auth_proxy</emphasis> - SIP address of authentication
1283                         proxy, e.g.,: sip:sipprovider.com
1284                         </para></listitem>
1285                 </itemizedlist>
1286                 <itemizedlist>
1287                         <listitem><para>
1288                         <emphasis>expires</emphasis> - expiration time for registration,
1289                         in seconds, e.g.,: 360
1290                         </para></listitem>
1291                 </itemizedlist>
1292                 <itemizedlist>
1293                         <listitem><para>
1294                         <emphasis>flags</emphasis> - the state of the registration, see <xref linkend="uac.r.uac.reg_info"/>
1295                         </para></listitem>
1296                 </itemizedlist>
1297                 <itemizedlist>
1298                         <listitem><para>
1299                         <emphasis>reg_delay</emphasis> - delay initial registration with at least reg_delay seconds, e.g.,: 3
1300                         </para></listitem>
1301                 </itemizedlist>
1302                 <para>
1303                 The module takes care of sending REGISTER and refresh registrations
1304                 before they expire.
1305                 </para>
1306                 <para>
1307                 When calls come in, you have to run uac_reg_lookup() that will detect
1308                 if the call is coming from a remote SIP provider and can change the
1309                 R-URI to local username@domain. Afterwards you can run location lookup.
1310                 </para>
1311
1312                 <example>
1313                 <title><function>lookup remote registrations</function> usage</title>
1314                         <programlisting format="linespecific">
1315 ...
1316     if(uac_reg_lookup("$rU", "$ru")) {
1317         xlog("request from a remote SIP provider [$ou => $ru]\n");
1318     }
1319     lookup("location");
1320 ...
1321                         </programlisting>
1322                 </example>
1323         </section>
1324 </chapter>
1325