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