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