"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/db_http/doc/db_http_admin.xml" (16 Apr 2019, 16235 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "db_http_admin.xml": 2.4.5_vs_3.0.0.

    1 <!-- Module User's Guide -->
    2 
    3 <chapter>
    4     <title>&adminguide;</title>
    5     
    6     <section id="overview" xreflabel="Overview">
    7     <title>Overview</title>
    8     <para> This module provides access to a database that is implemented
    9     as a HTTP server. It may be used in special cases where traversing
   10     firewalls is a problem, or where data encryption is required.
   11     </para>
   12     <para>
   13     In order to use this module you must have a server that can communicate
   14     via HTTP or HTTPS with this module that follows exactly the format 
   15     decribed in the specifications section.
   16     </para>
   17     <para>
   18     The module can provide SSL, authentication, and all the functionalities
   19     of an opensips db as long as the server supports them ( except result_fetch).
   20     </para>
   21     <para>
   22     There is a slight difference between the url of db_http and
   23     the urls of the other db modules. The url doesn't have to contain
   24     the database name. Instead, everything that is after the
   25     address is considered to be a path to the db resource, it may be
   26     missing.
   27     </para>
   28     <para>
   29         Even if using HTTPS the url must begin with "http://" , and the
   30     SSL parameter for the module must be set to 1.
   31     </para>
   32 
   33     <example>
   34         <title>Setting db_url for a module</title>
   35         <programlisting format="linespecific">
   36 ...
   37 modparam("presence", "db_url","http://user:pass@localhost:13100")
   38 or
   39 modparam("presence", "db_url","http://user:pass@www.some.com/some/some")
   40 ...
   41 </programlisting>
   42         </example>
   43 
   44     </section>
   45 
   46     <section id="dependencies" xreflabel="Dependencies">
   47     <title>Dependencies</title>
   48     <section>
   49         <title>&osips; Modules</title>
   50         <para>
   51         This module does not depend on other modules.
   52         </para>
   53     </section>
   54 
   55     <section>
   56         <title>External Libraries or Applications</title>
   57         <itemizedlist>
   58             <listitem>
   59             <para>
   60                 <emphasis>libcurl</emphasis>.
   61             </para>
   62             </listitem>
   63         </itemizedlist>
   64 
   65         </section>
   66     </section>
   67     
   68     <section id="exported_parameters" xreflabel="Exported Parameters">
   69     <title>Exported Parameters</title>
   70     <section id="param_SSL" xreflabel="SSL">
   71         <title><varname>SSL</varname>(int)</title>
   72         <para>
   73         Whether or not to use SSL.
   74         </para>
   75         <para>If value is 1 the module will use https otherwise
   76         it will use http.
   77         </para>
   78         <para>
   79         <emphasis>  Default value is <quote> 0 </quote>.
   80         </emphasis>
   81         </para>
   82         <example>
   83         <title>Set <varname>SSL</varname> parameter</title>
   84         <programlisting format="linespecific">
   85 ...
   86 modparam("db_http", "SSL",1)
   87 ...
   88 </programlisting>
   89         </example>
   90     </section>
   91     <section id="param_cap_raw_query" xreflabel="cap_raw_query">
   92         <title><varname>cap_raw_query</varname>(int)</title>
   93         <para>
   94         Whether or not the server supports raw queries.
   95         </para>
   96         <para>
   97         <emphasis>  Default value is <quote>0</quote>.
   98         </emphasis>
   99         </para>
  100         <example>
  101         <title>Set <varname>cap_raw_query</varname> parameter</title>
  102         <programlisting format="linespecific">
  103 ...
  104 modparam("db_http", "cap_raw_query", 1)
  105 ...
  106 </programlisting>
  107         </example>
  108     </section>
  109     <section id="param_cap_replace" xreflabel="cap_replace">
  110         <title><varname>cap_replace</varname>(int)</title>
  111         <para>
  112         Whether or not the server supports replace capabilities.
  113         </para>
  114         <para>
  115         <emphasis>  Default value is <quote>0</quote>.
  116         </emphasis>
  117         </para>
  118         <example>
  119         <title>Set <varname>cap_replace</varname> parameter</title>
  120         <programlisting format="linespecific">
  121 ...
  122 modparam("db_http", "cap_replace", 1)
  123 ...
  124 </programlisting>
  125         </example>
  126     </section>
  127     <section id="param_cap_insert_update" xreflabel="cap_insert_update">
  128         <title><varname>cap_insert_update</varname>(int)</title>
  129         <para>
  130         Whether or not the server supports insert_update capabilities.
  131         </para>
  132         <para>
  133         <emphasis>  Default value is <quote>0</quote>.
  134         </emphasis>
  135         </para>
  136         <example>
  137         <title>Set <varname>cap_insert_update</varname> parameter</title>
  138         <programlisting format="linespecific">
  139 ...
  140 modparam("db_http", "cap_insert_update", 1)
  141 ...
  142 </programlisting>
  143         </example>
  144     </section>
  145     <section id="param_cap_last_inserted_id" xreflabel="cap_last_inserted_id">
  146         <title><varname>cap_last_inserted_id</varname>(int)</title>
  147         <para>
  148         Whether or not the server supports last_inserted_id capabilities.
  149         </para>
  150         <para>
  151         <emphasis>  Default value is <quote>0</quote>.
  152         </emphasis>
  153         </para>
  154         <example>
  155         <title>Set <varname>cap_last_inserted_id</varname> parameter</title>
  156         <programlisting format="linespecific">
  157 ...
  158 modparam("db_http", "cap_last_inserted_id", 1)
  159 ...
  160 </programlisting>
  161         </example>
  162     </section>
  163 
  164     <section id="param_field_delimiter" xreflabel="field_delimiter">
  165         <title><varname>field_delimiter</varname> (str)</title>
  166         <para>
  167         Character to be used to delimit fields in the reply.Only
  168         one char may be set.
  169         </para>
  170         <para>
  171         <emphasis>Default value is <quote>;</quote>
  172         </emphasis>
  173         </para>
  174         <example>
  175         <title>Set <varname>field_delimiter</varname> parameter</title>
  176         <programlisting format="linespecific">
  177 ...
  178 modparam("db_http", "field_delimiter",";")
  179 ...
  180 </programlisting>
  181         </example>
  182     </section>
  183 
  184     <section id="param_row_delimiter" xreflabel="row_delimiter">
  185         <title><varname>row_delimiter</varname> (str)</title>
  186         <para>
  187         Character to be used to delimit rows in the reply.Only
  188         one char may be set.
  189         </para>
  190         <para>
  191         <emphasis>Default value is <quote>\n</quote>
  192         </emphasis>
  193         </para>
  194         <example>
  195         <title>Set <varname>row_delimiter</varname> parameter</title>
  196         <programlisting format="linespecific">
  197 ...
  198 modparam("db_http", "row_delimiter","\n")
  199 ...
  200 </programlisting>
  201         </example>
  202     </section>
  203 
  204     <section id="param_quote_delimiter" xreflabel="quote_delimiter">
  205         <title><varname>quote_delimiter</varname> (str)</title>
  206         <para>
  207         Character to be used to quote  fields that require quoting
  208         in the reply.Only one char may be set.
  209         </para>
  210         <para>
  211         <emphasis>Default value is <quote>|</quote>
  212         </emphasis>
  213         </para>
  214         <example>
  215         <title>Set <varname>quote_delimiter</varname> parameter</title>
  216         <programlisting format="linespecific">
  217 ...
  218 modparam("db_http", "quote_delimiter","|")
  219 ...
  220 </programlisting>
  221         </example>
  222     </section>
  223 
  224     <section id="param_value_delimiter" xreflabel="value_delimiter">
  225         <title><varname>value_delimiter</varname> (str)</title>
  226         <para>
  227         The delimiter used to separate multiple fields of a single
  228         variable (see <xref linkend="http-variables"/>).
  229         Only one char may be set.
  230         </para>
  231         <para>
  232         <emphasis>Default value is <quote>,</quote>
  233         </emphasis>
  234         </para>
  235         <example>
  236         <title>Set <varname>value_delimiter</varname> parameter</title>
  237         <programlisting format="linespecific">
  238 ...
  239 modparam("db_http", "value_delimiter",";")
  240 ...
  241 </programlisting>
  242         </example>
  243     </section>
  244 
  245     <section id="param_timeout" xreflabel="timeout">
  246         <title><varname>timeout</varname> (int)</title>
  247         <para>
  248         The maximum number of milliseconds that the HTTP ops are allowed to last
  249         </para>
  250         <para>
  251         <emphasis>Default value is <quote>30000 ( 30 seconds )</quote>
  252         </emphasis>
  253         </para>
  254         <example>
  255         <title>Set <varname>timeout</varname> parameter</title>
  256         <programlisting format="linespecific">
  257 ...
  258 modparam("db_http", "timeout",5000)
  259 ...
  260 </programlisting>
  261         </example>
  262     </section>
  263 
  264     <section id="param_disable_expect" xreflabel="disable_expect">
  265         <title><varname>disable_expect</varname> (int)</title>
  266         <para>
  267         Disables automatic 'Expect: 100-continue' behavior in libcurl for requests over 1024 bytes in size.
  268         This can help reduce latency by saving a network round-trip for large records.
  269         For more information on this behavior please seee rfc2616 section 8.2.3.
  270         </para>
  271         <para>
  272         <emphasis>Default value is <quote>0 (off)</quote>
  273         </emphasis>
  274         </para>
  275         <example>
  276         <title>Set <varname>disable_expect</varname> parameter</title>
  277         <programlisting format="linespecific">
  278 ...
  279 modparam("db_http", "disable_expect",1)
  280 ...
  281 </programlisting>
  282         </example>
  283     </section>
  284 
  285 
  286 </section>
  287 
  288 <section id="exported_functions" xreflabel="exported_functions">
  289     <title>Exported Functions</title>
  290 
  291     This module does not export any functions.
  292         
  293 </section>
  294 
  295 
  296 <section>
  297     <title>Server specifications</title>
  298 
  299     <section>
  300         <title>Queries</title>
  301         <para>
  302         The server must accept queries as HTTP queries.
  303         </para>
  304         <para>
  305         The queries are of 2 types : GET and POST.Both
  306         set variables that must be interpreted by the server.
  307         All values are URL-encoded.
  308         </para>
  309         <para>
  310         There are several types of queries and the server can tell
  311         them apart by the query_type variable. Each type of query uses
  312         specific variables simillar to those in the opensips db_api.
  313         </para>
  314         <example>
  315         <title>Example query.</title>
  316         <programlisting format="linespecific">
  317 ...
  318 GET /presentity/?c=username,domain,event,expires HTTP/1.1
  319 ...
  320 </programlisting>
  321         </example>
  322     </section>
  323 
  324 
  325     <section id="http-variables">
  326         <title>Variables</title>
  327         <para>
  328         A description of all the variables. Each variable can have
  329         either a single value or a comma-separated list of values. Each
  330         variable has a special meaning and can be used only with
  331         certain queries.
  332         </para>
  333 
  334         <para>
  335         The table on which operations will take place will be encoded
  336         in the url as the end of the url ( www.some.com/users will point
  337         to the users table).
  338         </para>
  339 
  340         <itemizedlist>
  341             <listitem>
  342             <para>
  343                 k=
  344             </para>
  345             
  346             <para>
  347                 Describes the keys (columns) that will 
  348                 be used for comparison.Can have multiple values.
  349             </para>
  350             
  351             </listitem>
  352             
  353             <listitem>
  354             <para>
  355                 op=
  356             </para>
  357             
  358             <para>
  359                 Describes the operators that will 
  360                 be used for comparison.Can have multiple values.
  361             </para>
  362             
  363             </listitem>
  364             
  365             <listitem>
  366             <para>
  367                 v=
  368             </para>
  369             
  370             <para>
  371                 Describes the values that columns will be 
  372                 compaired against. Can have multiple values.
  373             </para>
  374             
  375             </listitem>
  376 
  377             <listitem>
  378             <para>
  379                 c=
  380             </para>
  381 
  382             <para>
  383                 Describes the columns that will be selected
  384                 from the result.Can have multiple values.
  385             </para>
  386 
  387             </listitem>
  388 
  389             <listitem>
  390             <para>
  391                 o=
  392             </para>
  393 
  394             <para>
  395                 The column that the result will be ordered by.
  396                 Has a single value.
  397             </para>
  398 
  399             </listitem>
  400 
  401             <listitem>
  402             <para>
  403                 uk=
  404             </para>
  405 
  406             <para>
  407                 The keys(columns) that will be updated.
  408                 Can have multiple values.
  409             </para>
  410 
  411             </listitem>
  412 
  413             <listitem>
  414             <para>
  415                 uv=
  416             </para>
  417 
  418             <para>
  419                 The new values that will be put in the columns.
  420                 Can have multiple values.
  421             </para>
  422 
  423             </listitem>
  424 
  425             <listitem>
  426             <para>
  427                 q=
  428             </para>
  429 
  430             <para>
  431                 Describes a raw query. Will only be used if
  432                 the server supports raw queries. Has a single
  433                 value.
  434             </para>
  435 
  436             </listitem>
  437 
  438             <listitem>
  439             <para>
  440                 query_type=
  441             </para>
  442 
  443             <para>
  444                 Describes the type of the current query.
  445                 Can have a single value as described in the
  446                 Query Types section.Has a single value.
  447                 Will be present in all queries except the
  448                 "SELECT" (normal query).
  449             </para>
  450 
  451             </listitem>
  452             
  453             
  454         </itemizedlist>
  455 
  456         
  457         <example>
  458         <title>Example query with variables.</title>
  459         <programlisting format="linespecific">
  460 ...
  461 GET /presentity/?c=username,domain,event,expires HTTP/1.1
  462 GET /version/?k=table_name&amp;v=xcap&amp;c=table_version HTTP/1.1 
  463 ...
  464 ...
  465 POST /active_watchers HTTP/1.1
  466 
  467 k=id&amp;v=100&amp;query_type=insert
  468 ...
  469 
  470 </programlisting>
  471         </example>
  472     </section>
  473     
  474 
  475 <section>
  476         <title>Query Types</title>
  477         <para>
  478         The types of the queries are described by the
  479         query_type variable. The value of the variable
  480         will be set to the exact name of the query.
  481         </para>
  482         <para>
  483         Queries for "SELECT" use GET and the rest use POST
  484         (insert, update, delete, replace, insert_update).
  485         </para>
  486 
  487         <itemizedlist>
  488             <listitem>
  489             <para>
  490                 normal query
  491             </para>
  492             <para>
  493                 Uses the k, op, v, c and o variables.
  494                 This will not set the query_type variable and
  495                 will use GET.
  496             </para>
  497             </listitem>
  498 
  499             <listitem>
  500             <para>
  501                 delete
  502             </para>
  503             <para>
  504                 Uses the k, op and v variables.
  505             </para>
  506             </listitem>
  507 
  508             <listitem>
  509             <para>
  510                 insert
  511             </para>
  512             <para>
  513                 Uses the k and v variables.
  514             </para>
  515             </listitem>
  516 
  517 
  518             <listitem>
  519             <para>
  520                 update
  521             </para>
  522             <para>
  523                 Uses the k,op,v,uk and uv  variables.
  524             </para>
  525             </listitem>
  526 
  527             <listitem>
  528             <para>
  529                 replace
  530             </para>
  531             <para>
  532                 Uses the k and v  variables. This is an optional
  533                 type of query. If the module is not configured to use it
  534                 it will not.
  535             </para>
  536             </listitem>
  537 
  538             <listitem>
  539             <para>
  540                 insert_update
  541             </para>
  542             <para>
  543                 Uses the k and v  variables. This is an optional
  544                 type of query. If the module is not configured to use it
  545                 it will not.
  546             </para>
  547             </listitem>
  548 
  549             <listitem>
  550             <para>
  551                 custom
  552             </para>
  553             <para>
  554                 Uses the q  variable. This is an optional
  555                 type of query. If the module is not configured to use it
  556                 it will not.
  557             </para>
  558             </listitem>
  559 
  560 
  561 
  562         </itemizedlist>
  563 
  564         <example>
  565         <title>More query examples.</title>
  566         <programlisting format="linespecific">
  567 
  568 ...
  569 POST /active_watchers HTTP/1.1
  570 
  571 k=id&amp;op=%3D&amp;v=100&amp;query_type=delete
  572 ...
  573 
  574 ...
  575 POST /active_watchers HTTP/1.1
  576 
  577 k=id&amp;op=%3D&amp;v=100&amp;uk=id&amp;uv=101&amp;query_type=update
  578 ...
  579 
  580 </programlisting>
  581         </example>
  582     </section>
  583 
  584     <section>
  585         <title>NULL values in queries</title>
  586         <para>
  587         NULL values in queries are represented as a string of length 1
  588         containing a single character with value '\0'.
  589         </para>
  590         <example>
  591         <title>NULL query example.</title>
  592         <programlisting format="linespecific">
  593 
  594 ...
  595 POST /active_watchers HTTP/1.1
  596 
  597 k=id&amp;op=%3D&amp;v=%00&amp;query_type=delete
  598 ...
  599 
  600 
  601 </programlisting>
  602         </example>
  603 
  604     </section>
  605 
  606 
  607     <section>
  608         <title>Server Replies</title>
  609         <para>
  610             If the query is ok (even if the answer is empty)
  611             the server must reply with a 200 OK HTTP reply with
  612             a body containing the types and values of the columns.
  613         </para>
  614         <para>
  615         The server must reply with a delimiter separated list of
  616         values and columns.
  617         </para>
  618         <para>
  619             Each element in the list must be seperated from the
  620             one before it by a field delimiter that must be the same 
  621             as the one set as a parameter from the script for the module.
  622             The last element of each line must not be followed by
  623             a field delimiter, but by a row delimiter.
  624         </para>
  625 
  626         <para>
  627         The first line of the reply must contain a list of the types
  628         of values of each column. The types can be any from the list:
  629         integer, string, str, blob, date.
  630         </para>
  631         <para>
  632         Each following line contains the values of each row from the result.
  633         </para>
  634 
  635         <para>
  636         If the query produced an error the server must reply with a
  637         HTTP 500 reply, or with a corresponding error code (404, 401).
  638         </para>
  639         <example>
  640         <title>Example Reply.</title>
  641         <programlisting format="linespecific">
  642 ...
  643 int;string;blob
  644 6;something=something;1000
  645 100;mine;10002030
  646 ...
  647 </programlisting>
  648         </example>
  649     </section>
  650 
  651 
  652     <section>
  653         <title>Reply Quoting</title>
  654         <para>
  655         Because the values may contain delimiters inside,
  656         the server must perform quoting when necessary (there is no
  657         problem if it does it even when it is not necessary).
  658         </para>
  659         <para>
  660         A quote delimiter must be defined and must be the same as
  661         the one set from the script ( by default it is "|" ).
  662         </para>
  663 
  664         <para>
  665         If a value contains a field ,  row  or a quote delimiter
  666         it must be placed under quotes. A quote delimiter inside a value
  667         must be preceeded by another quote delimiter.
  668         </para>
  669         
  670         <example>
  671         <title>Quoting Example.</title>
  672         <programlisting format="linespecific">
  673 ...
  674 int;string;blob
  675 6;|ana;maria|;1000
  676 100;mine;10002030
  677 3;mine;|some||more;|
  678 ...
  679 </programlisting>
  680         </example>
  681     </section>
  682 
  683     <section>
  684         <title>Last inserted id</title>
  685         <para>
  686         This is an optional feature and may be enabled if one wants
  687         to use it.
  688         </para>
  689         <para>
  690         In order to use this feature the server must place the id
  691         of the last insert in the 200 reply for each insert query.
  692         </para>
  693 
  694     </section>
  695 
  696     <section>
  697         <title>Authentication and SSL</title>
  698         <para>
  699         If the server supports authentication and SSL, the module
  700         can be enabled to use SSL. Authentication will always be used
  701         if needed.
  702         </para>
  703         <para>
  704         The module will try to use the most secure type of
  705         authentication that is provided by the server from:
  706         Basic, Digest,GSSNEGOTIATE and NTLM.
  707         </para>
  708 
  709     </section>
  710     
  711 
  712 </section>
  713 
  714 </chapter>
  715