INSTALL: updates for v4.0.0
[sip-router] / INSTALL
1
2      ==================================================
3
4           Kamailio SIP Server Installation Notes
5
6                  http://www.kamailio.org
7
8      ==================================================
9
10   Welcome! This is an amazingly flexible, robust
11   and secure SIP server built on years of experience in several Open
12   Source projects. It's a merge of the SIP Express Router (SER) and the
13   Kamailio (OpenSER) products produced by a joint development team. When
14   not explicitely mentioned, SIP server refers to any of these two
15   applications.
16
17   This memo gives you hints how to set up the SIP server quickly.
18   
19   You can find similar tutorial and many more on project's web site:
20     - http://www.kamailio.org/w/documentation/
21     - http://www.kamailio.org/wiki/
22   
23
24 Table of Contents
25 =================
26
27 1. SIP Server Flavours
28 2. Supported Architectures and Requirements
29 3. Howto Build SIP Server From the Source Distribution
30    3.1 Kamailio Fast Track Installation
31    3.2 Details Installing from Source Code
32      A) Set SIP Server Flavour
33      B) Build Commands
34 4. Quick-Start Installation Guide
35    A) Getting Help
36    B) Disclaimers
37    C) Quick Start
38    D) SIP Server with Persistent Data Storage
39 5. Troubleshooting
40
41
42
43 1. SIP Server Flavours
44 ----------------------
45
46 The two major SIP server flavours are:
47   - SIP Express Router (aka SER)
48   - Kamailio (former OpenSER)
49
50 Starting with version 3.0.0, the two SIP server flavours are built from
51 same source code tree. In version 4.0.0 the two source code trees were
52 merged even more, so a combined module directory is now used.
53
54 Kamailio flavor is the one built by default. SER is, historically speaking, the
55 first open source SIP server started in 2001. Kamailio forked from SER in
56 2005 under the initial name OpenSER.
57
58 Starting with version 3.1.0 the differences between the two flavours are
59 very few, Kamailio enabling next compile time flags:
60   - internal statistics
61   - application server extensions in tm module
62
63 In version 4.0.0 the modules were merged into one set and the merger
64 between the two products was completed.
65
66 Kamailio is now the default flavour. Switching between flavours is a matter
67 of 'make' command parameters.
68
69 Several installation tutorials for Kamailio are available on the web wiki:
70   - http://www.kamailio.org/wiki/
71
72
73 2. Supported Architectures and Requirements
74 -------------------------------------------
75
76 Supported operating systems:
77  - Linux (Debian, Ubuntu, Fedora, RedHat, CentOS, OpenSUSE, Gentoo, a.s.o.)
78  - FreeBSD, NetBSD, OpenBSD, Dragonfly BSD
79  - Solaris
80  - OS/X, Darwin
81
82 Partially supported
83  - Windows+Cygwin (core + static modules only, no IPv6, no
84    TCP, no dynamic modules)
85
86 Supported architectures
87  - i386, x86_64 (amd64), armv4l, sparc64, powerpc, powerpc64
88
89 Experimental architectures:
90  - mips1, mips2, sparc32, alpha
91
92 (for other architectures the Makefiles might need to be edited)
93
94 There are various configuration options defined in the Makefile.
95
96
97 Requirements:
98
99 - gcc or icc : gcc >= 2.9x; 3.[12] recommended (it will work with older version
100   but it might require some options tweaking for best performance)
101 - bison or yacc (Berkley yacc)
102 - flex
103 - GNU make (on Linux this is the standard "make", on *BSD and Solaris it is
104   called "gmake") version >= 3.80 (recommended 3.81).
105 - sed and tr (used in the makefiles)
106 - GNU tar ("gtar" on Solaris) and gzip if you want "make tar" to work
107 - GNU install, BSD install or Solaris install if you want "make
108   install", "make bin", "make sunpkg" to work
109 - libmysqlclient & libz (zlib) if you want Mysql support (the db_mysql module)
110 - libxml2 if you want to compile the cpl-c (CPL support) or pa (presence) 
111    modules
112 - libradiusclient-ng (> 5.0) if you need radius support (the auth_radius,
113   group_radius, uri_radius and avp_radius modules)
114 - libpq if you need PostgreSQL support (the db_postgres module)
115 - libexpat if you want the jabber gateway support (the jabber module) or the
116   XMPP gateway support
117 - libxml2 if you want to use the cpl-c (Call Processing Language) or
118   the presence modules (presence and pua*)
119 - libradius-ng -libs and devel headers- if you want to use functionalities
120   with radius support - authentication, accounting, group support, etc
121 - unixodbc - libs and devel headers - if you want UNIXODBC support as
122   DB underlayer
123 - libxmlrpc-c3 - libs and devel headers - if you want to have XML-RPC support
124   for the Management interface (MI)
125 - libperl - libs and devel headers - if you want PERL connector to support
126   perl scripting from you config file (perl module)
127 - libsnmp9 - libs and devel headers - if you want SNMP client functionality 
128   (SNMP AgentX subagent) for Kamailio
129 - libldap libs and devel headers v2.1 or greater - if you want LDAP support
130 - libconfuse and devel headers - if you want to compile the carrierroute
131   module
132 - libpcre libs and devel headers - if you want to compile the lcr and dialplan
133   modules
134 - libsctp devel headers - if you want to compile the SCTP transport in the core
135 - libssl devel headers (openssl project) - if you want to compule the TLS module
136 - linunistring - for the Websockets module
137
138
139 OS Notes:
140
141  FreeBSD/OpenBSD/NetBSD: make sure gmake, bison or yacc & flex are installed.
142   
143   FreeBSD 5.4:
144   ------------
145   If you want to compile all the modules, you will need the following packages:
146   - mysql-client-* (any version, install one of the mysql*-client ports) for
147     libmysqlclient
148   - postgresql-libpqxx-2.4.2_1 (/usr/ports/databases/postgresql-libpqxx) for
149     libpq
150   - expat-1.95.8 (/usr/ports/textproc/expat2) for libexpat
151   - libxml2-2.6.18 (/usr/ports/textproc/libxml2) for libxml2
152   - radiusclient-0.4.7 (/usr/ports/net/radiusclient) for libradiusclient-ng 
153   NOTE: you'll need to add radiusclient_ng=4 to the gmake command line if you
154   use the 0.4.* version.
155   
156   Compile example (all the modules and SIP server core in a tar.gz):
157      gmake bin radiusclient_ng=4 include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
158
159   OpenBSD 3.7
160   -----------
161   - mysql-client-4.0.23 (/usr/ports/databases/mysql) for libmysqlclient
162   - expat-1.95.6 (/usr/ports/textproc/expat) for libexpat
163   - libxml-2.6.16p0 (/usr/ports/textproc/libxml) for libxml2
164   - radiusclient-ng-0.5.1 from 
165    http://download.berlios.de/radiusclient-ng/radiusclient-ng-0.5.1.tar.gz
166    (you need to download and install it, since there is no "official" 
167    openbsd port for it) for libradiusclient-ng 
168
169   Compile example (all the modules and SIP server core in a tar.gz):
170      gmake bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius pa"
171
172   NetBSD 2.0
173   ----------
174   - mysql-client-4.1.12 (/usr/pkgsrc/databases/mysql4-client) for libmysqlclient
175   - expat-1.95.8nb2 (/usr/pkgsrc/textproc/expat) for libexpat
176   - libxml2-2.6.19 (/usr/pkgsrc/textproc/libxml2) for libxml2
177   - radiusclient-ng-0.5.1 (see OpenBSD)
178   
179   Compile example (all the modules and SIP server in a tar.gz):
180      gmake bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius pa"
181
182   Solaris 10
183   ----------
184   As above; you can use Solaris's yacc instead of bison. You might also
185   need gtar and ginstall. If you don't have ginstall you can use Solaris
186   install, just make sure it's in the PATH (it's usually in /usr/sbin) and
187   add INSTALL=install either to the environment or to the make command line
188   (e.g.: gmake INSTALL=install all).
189   
190   Needed packages:
191   [TODO]
192   
193   Compile example (all the modules and SIP server in a tar.gz):
194      gmake bin INSTALL=install include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
195
196   Linux
197   -----
198   Needed packages for compiling all the modules:
199   * Debian:
200       - libmysqlclient-dev for libmysqlclient
201       - libpq-dev for libpq
202       - libexpat1-dev for libexpat
203       - libxml2-dev for libxml2
204       - libradiusclient-ng-dev for libradiusclient
205           - other libraries are needed for some other modules,
206             see README of the module you want to use
207     Both SER and Kamailio flavours have APT deb repositories that allow you to
208         install the binaries easily - see the web sites for more details:
209           - http://kamailio.org
210
211  Cygwin  (alpha state, partial support)
212  --------------------------------------
213  make sure make, bison, flex, minires and minires-devel (needed for the
214  resolver functions) are installed.
215  
216  Only building SIP server's core and some static modules is supported for now.
217  Stuff known not to work:
218            - IPv6 (cygwin doesn't support it yet)
219            - TCP (the tcp code heavily depends on file descriptor passing 
220              between processes, which is not yet supported by cygwin)
221            - dynamic modules (non statically linked -- not supported because
222              backlinking doesn't work in windows by design)
223
224
225   Compile example (all the modules and SIP server in a tar.gz):
226      make bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
227
228
229 3. Howto Build SIP Server From Source Distribution
230 --------------------------------------------------
231
232 (NOTE: if make doesn't work try gmake instead)
233
234 3.1 Kamailio Fast Track Installation
235 ....................................
236
237
238 If you are familiar with Unix/Linux  build tools aready and you installed
239 required dependency, then you can just follow this section, otherwise
240 skip over it.
241
242 To get the SIP server installed, in the folder with source code run:
243
244   make cfg
245   make all
246   make install
247
248 If you want to install with additional modules, for example with mysql and
249 tls, run:
250
251   make include_modules="db_mysql tls" cfg
252   make all
253   make install
254
255 3.2 Details Installing from Source Code
256 .......................................
257
258
259 A) Set SIP Server Flavour
260
261 If you don't have a clean source tree, first do:
262    make proper
263
264 To build Kamailio flavour, you don't need to do anything special, continue to
265 read the section 3.B).
266
267 To build SER flavour, you have to run first:
268    make FLAVOUR=ser cfg
269
270 The parameter 'FLAVOUR=ser' must be given all the time when make target
271 is 'cfg'.
272
273 B) Build Commands
274
275   SIP server is split in four main parts: The core, the modules, the
276   utilties, and scripts/examples.  When you build, you can decide to build
277   only the core, the modules, both, or all.
278
279 * Compile SIP server core only:
280         make
281
282 Compile modules except some explicitly excepted (see below)
283         make modules  - all modules in the modules/ directory 
284         make modules-all or make every-module  - all the modules 
285
286 * Compile all:
287         make all
288
289 * Explicitly excepted modules:
290   By default make all will not build modules that require external libraries or
291   that are considered to be "experimental". For example, modules that have external
292   dependencies are: db_mysql, jabber, cpl-c, auth_radius, group_radius, uri_radius,
293   avp_radius, db_postgres, db_berkely, carrierroute, ...
294
295 Including groups of modules:
296   Instead of compiling the default modules only, you can specify groups of
297   modules to include, according to their status:
298   - standard - Modules in this group are considered a standard part of SIP server
299     (due to widespread usage) but they have no dependencies (note that some of
300         these interplay with external systems.
301     However, they don't have compile or link dependencies).
302
303   - db - Modules in this group use databases and need a database driver to run.
304     Included are drivers for the text mode db (dbtext) and for dumping
305     large ammount of data to files (db_flatstore). See also the mysql or
306     postgres groups.
307
308   - standard_dep -  Modules in this group are considered a standard part of SIP
309     server(due to widespread usage)
310     but they have dependencies that most be satisfied for compilation.
311     NOTE! All presence modules (dialog, pa, presence_b2b, rls, xcap) have been
312         included in this group due to interdependencies
313
314   - stable - Modules in this group satisfy specific or niche applications,
315     but are considered stable for production use. They may or may not have
316         dependencies
317
318   - experimental - Modules in this group are either not complete, untested, or
319     without enough reports of usage to allow the module into the stable group.
320         They may or may not have dependencies.
321
322 There is another set of groups mainly used by Kamailio flavour, where modules
323 are grouped based on Debian packaging rules. For example:
324    - kstandard - Kamailio flavour's standard modules
325
326    - kpresence - Kamailio flavour's SIMPLE presence server modules
327
328 * To compile core with standard modules:
329         make group_include="standard" all
330
331 * To compile all modules (provided you have all the required libraries installed) use:
332         make group_include="standard standard-dep stable experimental" all
333
334   There are also in addition some "convenience" groups:
335
336         mysql           - Include all the db modules dependent and the mysql db driver
337         postgres        - Include all the db modules and the postgres db driver
338         radius          - Include all modules on radiusclient
339         presence        - Include all the presence modules
340
341   Ex. to make a standard installation with Mysql, use:
342         make group_include="standard mysql" all
343
344   In addition to group_include (or instead), you can use 
345         include_modules="modA modB"
346   to specify exactly the modules you want to include, ex.
347         make include_modules="mymodule" modules
348
349   You can also explicitly skip modules using skip_modules. Let's say you want all
350   the standard and standard-dep modules except domain:
351         make group_include="standard standard-dep" skip_modules="domain" all
352
353   NOTE!!! As this mechanism is very powerful, you may be uncertain which
354   modules that will be included. Just replace all (or modules) with print-modules
355   and you will see which modules will be included and excluded, ex:
356         make print-modules
357   will show which modules are excluded by default.
358
359   If you want to install or to build a binary package (a tar.gz with
360   SIP server core and the modules), substitute "all" in the above command with
361   "install" or "bin".
362
363
364 * More compile examples:
365
366   - compile with profiling
367         make PROFILE=-pg all
368   - compile debug mode version
369         make mode=debug all
370   - compile debug version with profiling
371         make mode=debug PROFILE=-pg all
372   - compile only the print module
373         make modules=modules/print modules
374   - compile by default only the print module, in debuging mode and with 
375     profiling:
376         make cfg modules=modules/print mode=debug PROFILE=-pg
377         make all
378   - change & save the  modules list without rebuilding the whole config
379     (so that already compiled modules won't be re-compiled by 
380     make all/make modules):
381         make modules-cfg include_modules="mysql postgress"
382   - change only the compile/build options, without changing the modules list:
383         make cfg-defs CPU=ultrasparc PROFILE=-pg
384   - compile by default all the usual modules + mysql and postgres, optimized 
385      for pentium-m and for space (saves both the build options and the module 
386      list)
387         make cfg include_modules="mysql postgres" CPU=pentium-m CC_EXTRA_OPTS=-Os
388         make all
389    - compile all the "default" modules except textops and vm
390         make skip_modules="textops vm" modules
391    - save the above option in the make config, so that all make commands
392      will use it by default:
393         make cfg skip_modules="textops vm"
394    - compile all default modules and include uri_radius (not compiled by default):
395         make include_modules="uri_radius" modules
396    - compile all the modules from the modules subdirectory (even the one excluded
397      by default):
398         make exclude_modules="" modules
399    - compile all the modules from the modules subdirectory excluding vm:
400         make exclude_modules=vm modules
401      or
402         make exclude_modules="" skip_modules=vm modules
403    - compile with the "tm" module statically linked and with profiling
404         make static_modules=tm PROFILE=-pg all
405    - compile with gcc-3.2 instead of gcc
406         make CC=gcc-3.2 all
407      or
408         CC=gcc-3.2 make all
409
410 Make targets:
411 =============
412
413 Configure:
414 ----------
415
416   * make cfg or make config - force config and module list regeneration
417   
418
419   Example: 
420         make cfg include_modules=mysql mode=debug
421   All future make invocations will include the mysql module and will build in debug mode
422
423   Note: if config.mak doesn't exist (e.g. initial checkout or after a make 
424   proper) or if Makefile.defs was changed, the config will be re-generated
425   automatically by the first make command. For example:
426         make cfg  include_modules=db_mysql; make all
427   is equivalent to 
428         rm config.mak modules.lst; make include_modules=db_mysql.
429
430   * make cfg-defs  (force config regeneration, but don't touch the module list)
431
432   Example:
433         make cfg-defs CPU=ultrasparc CC_EXTRA_OPTS=-Os PROFILE=-pg
434
435         make modules-cfg
436   or
437         make modules-list
438   saves the module list, without regenerating the build config
439   Example:
440         make modules-list include_modules="tls" skip_modules="print"
441
442 Clean:
443 ------
444
445   * make clean          - clean the base and modules too
446   * make proper         - clean also the dependencies and the config, but not the module list
447   * make distclean      - the same as proper
448   * make maintainer-clean - clean everything, including make's config, saved 
449                           module list, auto generated files, tags, *.dbg a.s.o
450   * make clean-all      - clean all the modules in modules/*
451   * make proper-all     - like make proper but for all the  modules in modules/*
452
453   Config clean:
454
455   * make clean-cfg (cleans the compile config)
456   * make clean-modules-cfg (cleans the modules list)
457
458   Reduced" clean:
459
460   * make local-clean    - cleans only the core, no libs, utils or modules
461   * make clean-modules  - like make clean, but cleans only the modules
462   * make clean-libs     - like make clean, but cleans only the libs
463   * make clean-utils    - like make clean, but cleans only the utils
464   * make proper-modules - like make proper, but only for modules
465   * make proper-libs    - like make proper, but only for libs
466   * make proper-utils   - like make proper, but only for utils
467
468 Compile:
469 --------
470   * make proper
471   optional: make cfg  <various cfg. options that should be saved>
472   * make
473   or gmake on non-Linux systems
474   * make modules 
475   or make modules exclude_modules="CVS print" etc.
476
477 Other make targets:
478 -------------------
479   Make tags:
480         make TAGS
481
482   Create a tar.gz with the sources (in ../):
483         make tar
484
485   Create a tar.gz with the binary distribution (in ../):
486         make bin
487
488   Create a gzipped solaris package (in ../):
489         make sunpkg
490
491   Create debian packages (in ../):
492         make deb
493
494   or
495         dpkg-buildpackage
496
497 Documentation:
498 --------------
499
500   Regenerate the README for all the "default" modules (include_modules,
501   skip_modules a.s.o can be used to alter the module list).
502         make README
503
504   Generates a manpage for all the modules that support it (.xml file in the
505   module directory).
506         make man
507
508   Generates README file for modules/foo.
509         make modules=modules/foo modules-readme
510
511 Install:
512 --------
513
514         make prefix=/usr/local  install
515
516   Note: If you use prefix parameter in make install then you also need
517   to use this parameter in previous make commands, i.e. make, make modules,
518   or make all. If you fail to do this then SIP Router will look for the default
519   configuration file in a wrong directory, because the directory of the
520   default configuration file is hard coded into SIP server during compile time. 
521   When you use a different prefix parameter when installing then the 
522   directory hard coded in SIP server and the directory in which the file will be 
523   installed by make install will not match. (You can specify exact location
524   of the configuration file using -f parameter of SIP server).
525
526   For example, if you do the following:
527         make all
528         make prefix=/ install
529
530   Then the installation will put the default configuration file into
531   /etc/ser/ser.cfg or /etc/kamailio/kamailio.cfg (because prefix is /),
532   but SIP server will look for the file in /usr/local/etc/ser/ser.cfg or
533   /usr/local/etc/kamailio/kamailio.cfg (because there was no prefix parameter
534   make all and /usr/local is the default value of prefix).
535
536   Workaround is trivial, use the same parameters in all make commands:
537         make prefix=/ all
538         make prefix=/ install
539   or save the desired prefix in the make config (e.g.: make cfg prefix=/).
540
541   That applies to other make parameters as well (for example parameters
542   "modules" or "excluded_modules").
543
544
545 4. Quick-Start Installation Guide
546 ---------------------------------
547
548 A) Getting Help
549
550   This guide gives you instructions on how to set up the SIP server
551   (SER or Kamailio) on your box quickly. In case the default configuration
552   does not fly, please check the documentation at the SIP server web site
553   http://www.kamailio.org to learn how to configure SIP server for your site.
554
555   If the documentation does not resolve your problem you may try contacting 
556   our user forum by E-mail at sr-users@lists.sip-router.org -- that is the
557   mailing list of the SIP server community. To participate in the mailing list,
558   please subscribe at the following web address:
559
560   http://lists.sip-router.org/cgi-bin/mailman/listinfo
561
562 B) Disclaimers
563  
564   Note well the default "quick-start" configuration is very simple in order 
565   to be easily installable. It provides minimum features. Particularly, 
566   authentication is by default disabled, which means anyone can register using
567   any name with the server. (This is on purpose to avoid installation 
568   dependencies on a database, which is needed for storing user credentials.)
569
570 C) Quick Start
571
572   The following step-by step guide gives you instructions how to install the 
573   SQL-free distribution of SIP server. If you need persistence and
574   authentication, then you have to install additional database support --
575   proceed to section D) after you are finished with C).
576
577   1) Download an RPM or debian package from site
578
579     ****** site not available yet
580
581   If you don't use an rpm or debian based distribution, try our tar.gz'ed
582   binaries
583
584   ******* not available yet
585
586   If you use Solaris 8 you can try our solaris package.
587   If you use Gentoo Linux you do not have to download a package.
588
589   2) Install the package
590         RPM:
591                 rpm -i <package_name>
592         debian:
593                 dpkg -i <package_name>
594         gentoo:
595                 emerge ser
596                           or
597                         emerge kamailio
598                 (or if use only stable packets: ACCEPT_KEYWORDS="~x86" emerge ser
599                 or ACCEPT_KEYWORDS="~x86" emerge kamailio)
600         tar.gz:
601                 cd /; tar zxvf <package_name>_os_arch.tar.gz
602                 (it will install in /usr/local/, and the configuration file in
603                 /usr/local/etc/ser/ser.cfg or /usr/local/etc/kamailio/kamailio.cfg)
604         Solaris:
605                 gunzip <package_name>.gz ; pkgadd -d <package_name>
606         *BSD:
607                 pkg_add package_name
608     
609   3) Start the server
610
611         RPM + gentoo:
612                 /etc/init.d/ser start
613                           or
614                 /etc/init.d/kamailio start
615         debian:
616                 SER or Kamailio is started automatically after the install
617                 (in case something fails you can start it with '/etc/init.d/ser start'
618                         or '/etc/init.d/kamailio start')
619         tar.gz:
620         Solaris:
621                 the tar.gz does not include an init.d script, you'll have to create one of
622                 your own or adapt one from the source distribution (pkg/debian/init.d,
623                 pkg/rpm/ser.init.*, pkg/gentoo/ser.init, pkg/kamailio/rpm/kamailio.init,
624                         pkg/kamailio/deb/debian/kamailio.init, a.s.o.)
625                 You can start SIP server directly with /usr/local/sbin/ser or
626                         /usr/local/sbin/kamailio.
627     
628   4) optionally, watch server's health using the
629         serctl or kamctl utility
630
631     - to do so, first set the environment variable SIP_DOMAIN to your domain 
632       name, e.g., in Bourne shell, call
633         export SIP_DOMAIN="myserver.foobar.com"
634         - if you are using other than 'localhost' mysql server for maintaining
635           subscriber database, change the variable 'SQL_HOST' to the proper
636           host name in the serctl script
637     - run the serctl utility
638         /usr/sbin/serctl moni
639       or
640         /usr/sbin/kamctl moni
641       or
642         /usr/local/sbin/serctl moni (if you installed SER flavour from a tar.gz
643                 or solaris package)
644       or
645         /usr/local/sbin/kamctl moni (if you installed Kamailio flavour from a
646                 tar.gz or solaris package)
647
648   5) Connect SIP phones
649
650   Register with the server using your favorite SIP User Agent. You may want to look 
651   at configuration hints for use of various clients on iptel.org site at
652      http://www.iptel.org/phpBB/viewforum.php?forum=1&8
653
654   In most cases, you need to set the following options:
655
656         Proxy server:   host name of your server
657         Domain:         the sip domain your server is configured to handle
658         User name:      the account name for your device
659         Auth user:      the ID used for authentication
660         Secret/Password:        The configured authentication password
661
662 D) SIP Server with Persistent Data Storage
663 ------------------------------------------
664
665   The default configuration is very simple and features many simplifications. 
666   In particular, it does not authenticate users and loses User Location database 
667   on reboot. To provide persistence, keep user credentials and remember users' 
668   locations across reboots, SIP server can be configured to use a database, like MySQL. 
669   Before you proceed, you need to make sure MySQL is installed on your box. Your
670   MySQL server must be configured to deal with a large number of
671   connection. To increase it, set the following line in [mysqld] section
672   of your my.ini configuration file:
673
674    set-variable    = max_connections=500
675
676   1) Download the package containing mysql support for SIP server from: 
677     
678     **** site not available yet
679
680     (rpm and deb provided, most of the binary tar.gz distributions and the 
681      solaris package include it; if it is not present you'll have to rebuild
682      from the source).
683         For gentoo please include 'mysql' to your USE variable in /etc/make.conf
684         or give it as variable to the emerge command.
685
686   2) install the package
687     rpm -i <package_name>
688     or
689     dpkg -i <package_name>
690         or
691         emerge ser
692         or
693         emerge kamailio
694         (if do not want to put 'mysql' into your USE variable you can type:
695          USE="mysql" emerge ser)
696
697   3.1) create MySQL tables for SER flavour
698         - if you have a previously installed SER on your system, use
699         /usr/sbin/ser_mysql.sh reinstall 
700           to convert your SER database into new structures
701         - otherwise, if this is your very first installation, use
702         /usr/sbin/ser_mysql.sh create
703           to create SER database structures
704    (you will be prompted for password of MySql "root" user)
705
706   3.2) create MySQL tables for Kamailio flavour
707         - if you have a previously installed Kamailio on your system, use
708         /usr/local/sbin/kamdbctl reinstall 
709           to convert your Kamailio database into new structures
710         - otherwise, if this is your very first installation, use
711         /usr/local/sbin/kamdbctl create
712           to create Kamailio database structures
713    (you will be prompted for password of MySql "root" user)
714
715   4) configure SIP server to use SQL
716     uncomment all lines in configuration file ser.cfg or kamilio.cfg which are
717         related to authentication:
718     - loadmodule "db_mysql.so"
719     - loadmodule "auth.so"
720     - loadmodule "auth_db.so"
721     - modparam("usrloc", "db_mode", 2)
722     - modparam("auth", "calculate_ha1", yes)
723     - modparam("auth_db", "password_column", "password")
724     - if (!www_authorize("sip-router.org", "subscriber")) {
725         www_challenge("sip-router.org", "0"); 
726         break;
727       }
728
729   5) be sure to replace realm, the first parameter in www_* actions, 
730    with name of your server; some broken UAC implementations don't 
731    authenticate otherwise; the authentication command in your
732    configuration script should look then like this:
733       if (!www_authorize("myserver.foobar.com", "subscriber")) {
734         www_challenge("myserver.foobar.com", "0"); 
735         break;
736       }
737
738   6) restart the server
739     /etc/init.d/ser restart
740           or
741     /etc/init.d/kamailio restart
742
743   7) you can now start  managing the server using the serctl or kamctl utility; 
744    you need to first set the environment variable SIP_DOMAIN to your 
745    local SIP realm, e.g.,
746        export SIP_DOMAIN="myserver.foobar.com"
747
748    a) watch the server status using 'serctl moni' or 'kamctl moni'
749    b) try to login with your SIP client as user 'admin' with password 'heslo'
750    c) try adding new users using 
751        'serctl add <name> <password> <email>'
752              or
753        'kamctl add <username> <password>'
754
755
756 4. Troubleshooting
757 ------------------
758
759 Q: Windows Messenger authentication fails. 
760
761 A: The most likely reason for this problem is a bug in Windows Messenger. 
762 WM only authenticates if server name in request URI equals authentication 
763 realm. After a challenge is sent by SIP server, WM does not resubmit the 
764 challenged request at all and pops up authentication window again. If you 
765 want to authenticate WM, you need to set up your realm value to equal server 
766 name. If your server has no name, IP address can be used as realm too.
767
768 Q: SIP requests are replied by SIP server with "483 Too Many Hops" or 
769    "513 Message Too Large"
770
771 A: In both cases, the reason is probably an error in request routing script 
772    which caused an infinite loop. You can easily verify whether this happens 
773    by watching SIP traffic on loopback interface. A typical reason for
774    misrouting is a failure to match local domain correctly. If a server
775    fails to recognize a request for itself, it will try to forward it to
776    current URI in believe it would forward them to a foreign
777    domain. Alas, it forwards the request to itself again. This continues
778    to happen until value of max_forwards header field reaches zero or
779    the request grows too big. Solutions is easy: make sure that domain
780    matching is correctly configured. A quick way to achieve that is to
781    introduce a config option to ser.cfg or kamailio.cfg: alias=domainname,
782    where domainname shall be replaced with name of domain, which you wish to
783    server and which appears in request-URIs.