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