gzcompress: new module to compress/decompress SIP message body using zlib
[sip-router] / modules / gzcompress / doc / gzcompress_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 "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module is able to detect compressed body in received SIP message
20                 and decompress it as well as compress the body for outgoing SIP
21                 message.
22         </para>
23         <para>
24                 The decision of whether to do compression or decompression is made
25                 by detecting a special SIP header (default 'Content-Encoding') that
26                 matches a given value - both header name and value can be set via
27                 module parameters. If a SIP message is received with clear body and
28                 you want to compress the body for outgoing, add the header in config
29                 file. The header can be added to the local generated replies as well.
30         </para>
31         <para>
32                 In other words, if the header is present in incoming SIP message, its
33                 body is decompressed. If the header is present in outgoing SIP message,
34                 its body is compressed. Therefore inside configuration file, the body
35                 is in original format(e.g., plain text). In this way, the existing
36                 functions to handle content of the body work as usual (e.g., to strip
37                 codecs in sdp via sdpops or do substitutions via textops).
38         </para>
39         <para>
40                 The functions used to compress and decompress are from zlib
41                 library (http://zlib.net).
42         </para>
43         <para>
44                 NOTE: for the moment the module cannot be used with topoh module,
45                 overlapping in core event callbacks (will be fixed soon).
46         </para>
47         <para>
48                 The immediate benefit of compressing the body is to reduce the size
49                 of the SIP message, increasing the chances to stay under MTU for UDP
50                 packts. From observation, the compressed body is in between 50% to 67%
51                 smaller than the original size (e.g., a body of 431 bytes was
52                 compressed to 230).
53         </para>
54         <para>
55                 An use case can be when having peering traffic between two Kamailio
56                 servers. Before relaying to the other Kamailio,  use
57                 in config file: append_hf("Content-Encoding: gzip\r\n").
58         </para>
59         </section>
60         <section>
61         <title>Dependencies</title>
62         <section>
63                 <title>&kamailio; Modules</title>
64                 <para>
65                 The following modules must be loaded before this module:
66                         <itemizedlist>
67                         <listitem>
68                         <para>
69                                 <emphasis>none</emphasis>.
70                         </para>
71                         </listitem>
72                         </itemizedlist>
73                 </para>
74         </section>
75         <section>
76                 <title>External Libraries or Applications</title>
77                 <para>
78                 The following libraries or applications must be installed before running
79                 &kamailio; with this module loaded:
80                         <itemizedlist>
81                         <listitem>
82                         <para>
83                                 <emphasis>zlib</emphasis> compression library (http://zlib.net).
84                         </para>
85                         </listitem>
86                         </itemizedlist>
87                 </para>
88         </section>
89         </section>
90         <section>
91         <title>Parameters</title>
92         <section id="gzcompress.p.header_name">
93                 <title><varname>header_name</varname> (str)</title>
94                 <para>
95                         Name of the header that indicates compression or decompression has
96                         to be done.
97                 </para>
98                 <para>
99                 <emphasis>
100                         Default value is "Content-Encoding".
101                 </emphasis>
102                 </para>
103                 <example>
104                 <title>Set <varname>header_name</varname> parameter</title>
105                 <programlisting format="linespecific">
106 ...
107 modparam("gzcompress", "header_name", "Encoded")
108 ...
109 </programlisting>
110                 </example>
111         </section>
112         <section id="gzcompress.p.header_value">
113                 <title><varname>header_value</varname> (str)</title>
114                 <para>
115                         Name of the header that indicates compression or decompression has
116                         to be done.
117                 </para>
118                 <para>
119                 <emphasis>
120                         Default value is "gzip".
121                 </emphasis>
122                 </para>
123                 <example>
124                 <title>Set <varname>header_value</varname> parameter</title>
125                 <programlisting format="linespecific">
126 ...
127 modparam("gzcompress", "header_value", "tgz")
128 ...
129 </programlisting>
130                 </example>
131         </section>
132         <section id="gzcompress.p.sanity_checks">
133                 <title><varname>sanity_checks</varname> (integer)</title>
134                 <para>
135                         If set to 1, gzcompress module will bind to sanity module in order
136                         to perform sanity checks over received SIP request. Default
137                         sanity checks are done. It is useful to check if received request
138                         is well formated before proceeding to encoding/decoding.
139                 </para>
140                 <para>
141                 <emphasis>
142                         Default value is 0 (do not bind to sanity module).
143                 </emphasis>
144                 </para>
145                 <example>
146                 <title>Set <varname>sanity_checks</varname> parameter</title>
147                 <programlisting format="linespecific">
148 ...
149 modparam("gzcompress", "sanity_checks", 1)
150 ...
151 </programlisting>
152                 </example>
153         </section>
154
155         </section>
156         <section>
157         <title>Functions</title>
158         <section>
159                 <para>
160                         None.
161                 </para>
162         </section>
163         </section>
164 </chapter>
165