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