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