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