Modifying the return value of cfg_set* functions, in order to make
[sip-router] / INSTALL
1 $Id$
2
3
4      ===========================================
5
6      SIP Express Router (ser) Installation Notes
7
8              http://www.iptel.org/ser/
9
10      ===========================================
11
12   This memo gives you hints how to set up SER quickly. To 
13   understand how SER works and how to configure it properly,
14   read admin's guide available from SER website. We also
15   urge you to read latest ISSUES (available from SER website 
16   too) and check for potential problems in this release.
17   Users of previous releases are encouraged to read NEWS to
18   learn how to move to this new SER version.
19   
20
21 TOC
22
23 1. Supported Architectures and Requirements
24 2. Howto Build ser From Source Distribution
25 3. Quick-Start Installation Guide
26    A) Getting Help
27    B) Disclaimers
28    C) Quick Start
29    D) ser with Persistent Data Storage
30 4. Troubleshooting
31
32
33
34 1. Supported Architectures and Requirements
35 -------------------------------------------
36
37 Supported operating systems: Linux, FreeBSD, NetBSD, OpenBSD, Solaris, Darwin
38 Supported architectures: i386, x86_64 (amd64), armv4l, sparc64, powerpc,
39  powerpc64
40 Experimental architectures: mips1, mips2, sparc32, alpha
41
42 (for other architectures the Makefiles might need to be edited)
43
44 There are various configuration options defined in the Makefile.
45
46
47 Requirements:
48
49 - gcc or icc : gcc >= 2.9x; 3.[12] recommended (it will work with older version
50   but it might require some options tweaking for best performance)
51 - bison or yacc (Berkley yacc)
52 - flex
53 - GNU make (on Linux this is the standard "make", on *BSD and Solaris is
54  called "gmake") version >= 3.79.
55 - sed and tr (used in the makefiles)
56 - GNU tar ("gtar" on Solaris) and gzip if you want "make tar" to work
57 - GNU install, BSD install or Solaris install if you want "make
58   install", "make bin", "make sunpkg" to work
59 - libmysqlclient & libz (zlib) if you want mysql support (the mysql module)
60 - libexpat if you want the jabber gateway support (the jabber module)
61 - libxml2 if you want to compile the cpl-c (CPL support) or pa (presence) 
62 modules
63 - libradiusclient-ng (> 5.0) if you need radius support (the auth_radius,
64 group_radius, uri_radius and avp_radius modules)
65 - libpq if you need postgres support (the postgres module)
66
67
68 OS Notes:
69
70  FreeBSD/OpenBSD/NetBSD: make sure gmake, bison or yacc & flex are installed.
71   
72   FreeBSD 5.4:
73   
74   If you want to compile all the modules, you will need the following packages:
75   - mysql-client-* (any version, install one of the mysql*-client ports) for
76   libmysqlclient
77   - postgresql-libpqxx-2.4.2_1 (/usr/ports/databases/postgresql-libpqxx) for
78   libpq
79   - expat-1.95.8 (/usr/ports/textproc/expat2) for libexpat
80   - libxml2-2.6.18 (/usr/ports/textproc/libxml2) for libxml2
81   - radiusclient-0.4.7 (/usr/ports/net/radiusclient) for libradiusclient-ng 
82   NOTE: you'll need to add radiusclient_ng=4 to the gmake command line if you
83   use the 0.4.* version.
84   
85   Compile example (all the modules and ser in a tar.gz):
86      gmake bin radiusclient_ng=4 include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
87
88   OpenBSD 3.7
89   - mysql-client-4.0.23 (/usr/ports/databases/mysql) for libmysqlclient
90   - expat-1.95.6 (/usr/ports/textproc/expat) for libexpat
91   - libxml-2.6.16p0 (/usr/ports/textproc/libxml) for libxml2
92   - radiusclient-ng-0.5.1 from 
93    http://download.berlios.de/radiusclient-ng/radiusclient-ng-0.5.1.tar.gz
94    (you need to download and install it, since there is no "official" 
95    openbsd port for it) for libradiusclient-ng 
96   Compile example (all the modules and ser in a tar.gz):
97      gmake bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius pa"
98
99   NetBSD 2.0
100   - mysql-client-4.1.12 (/usr/pkgsrc/databases/mysql4-client) for libmysqlclient
101   - expat-1.95.8nb2 (/usr/pkgsrc/textproc/expat) for libexpat
102   - libxml2-2.6.19 (/usr/pkgsrc/textproc/libxml2) for libxml2
103   - radiusclient-ng-0.5.1 (see OpenBSD)
104   
105   Compile example (all the modules and ser in a tar.gz):
106      gmake bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius pa"
107
108  Solaris 10
109  
110   As above; you can use Solaris's yacc instead of bison. You might
111   need also gtar and ginstall. If you don't have ginstall you can use Solaris
112   install, just make sure it's in the PATH (it's usually in /usr/sbin) and
113   add INSTALL=install either to the environment or to the make command line
114   (e.g.: gmake INSTALL=install all).
115   
116   Needed packages:
117   [TODO]
118   
119   Compile example (all the modules and ser in a tar.gz):
120      gmake bin INSTALL=install include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
121
122  Linux
123
124  Needed packages for compiling all the modules:
125   Debian:
126       - libmysqlclient-dev for libmysqlclient
127       - libpq-dev for libpq
128       - libexpat1-dev for libexpat
129       - libxml2-dev for libxml2
130       - libradiusclient-ng-dev for libradiusclient (you can download the 
131       package from http://apt.sip-router.org/debian/dists/unstable/main/binary-i386/libradiusclient-ng-dev_0.5.1-0.5_i386.deb ).
132       NOTE: you can get up-to-date ser packages or libradiusclient packages
133       from http://apt.sip-router.org: add to your /etc/apt/sources.list the
134       following lines:
135          deb http://apt.sip-router.org/debian testing main contrib non-free
136          deb http://apt.sip-router.org/debian unstable main contrib non-free
137       and then: apt-get update; apt-get install libradiusclient-ng-dev
138       (or, if you want to use the pre-built modules:
139        apt-get install ser ser-cpl-module ser-jabber-module ser-mysq-module ser-pa-module ser-postgres-module ser-radius-modules )
140
141
142   Compile example (all the modules and ser in a tar.gz):
143      make bin include_modules="mysql jabber cpl-c auth_radius group_radius uri_radius postgres pa"
144
145
146 2. Howto Build ser From Source Distribution
147 -------------------------------------------
148
149 (NOTE: if make doesn't work try gmake  instead)
150
151 SER is split in four main parts: The core, the modules, the utilties, and scripts/examples
152 When you build, you can decide to build only the core, the modules, both, or all.
153
154 Compile SER core only:
155 make   #builds only ser core, equivalent to make ser
156
157 Compile modules except some explicitly excepted (see below)
158 make modules  
159
160 Compile all:
161 make all
162
163 Explicitly excepted modules (default in <=0.9.x):
164 By default make all will not build modules that require external libraries or
165 that are considered to be "experimental". The modules that have external
166 dependencies are: mysql, jabber, cpl-c, auth_radius, group_radius, uri_radius,
167 avp_radius, postgres, pa.
168
169 Including groups of modules (available in >0.9.x):
170 Instead of compiling the default modules only, you can specify groups of
171 modules to include, according to their status:
172 standard - Modules in this group are considered a standard part of SER (due to widespread usage)
173     but they have no dependencies (note that some of these interplay with external systems.
174     However, they don't have compile or link dependencies).
175
176 standard-dep -  Modules in this group are considered a standard part of SER (due to widespread usage)
177     but they have dependencies that most be satisfied for compilation.
178     NOTE! All presence modules (dialog, pa, presence_b2b, rls, xcap) have been included in this
179     group due to interdependencies
180
181 stable - Modules in this group satisfy specific or niche applications, but are considered
182     stable for production use. They may or may not have dependencies
183
184 experimental - Modules in this group are either not complete, untested, or without enough reports
185     of usage to allow the module into the stable group. They may or may not have dependencies.
186
187 To compile core with standard modules:
188 make group_include="standard" all
189
190 To compile all modules (provided you have all the required libraries installed) use:
191 make group_include="standard standard-dep stable experimental" all
192
193 There are also in addition some "convenience" groups:
194
195 mysql - Include all modules dependent on mysql
196
197 radius - Include all modules on radiusclient
198
199 presence - Include all the presence modules
200
201 Ex. to make a standard installation with mysql, use:
202 make group_include="standard mysql" all
203
204 In addition to group_include (or instead), you can use 
205 include_modules="modA modB"
206 to specify exactly the modules you want to include, ex.
207 make include_modules="mymodule" modules
208
209 You can also explicitly skip modules using skip_modules. Let's say you want all the standard
210  and standard-dep modules except domain:
211 make group_include="standard standard-dep" skip_modules="domain" all
212
213 NOTE!!! As this mechanism is very powerful, you may be uncertain which modules wwill be included.
214 Just replace all (or modules) with print-modules and you will see which modules will be included
215 and excluded, ex:
216 make print-modules
217 will show which modules are excluded by default.
218
219 If you want to install or to build a binary package (a tar.gz with ser and
220  the modules), substitute "all" in the above command with "install" or "bin".
221
222
223 More compile examples:
224
225 - compile with profiling
226
227 make PROFILE=-pg all
228
229 -compile debug mode version
230
231 make mode=debug all
232
233 -compile debug version with profiling
234
235 make mode=debug PROFILE=-pg all
236
237 -compile only the print module
238
239 make modules=modules/print modules
240
241 -compile all the "default" modules except textops and vm
242
243 make skip_modules="textops vm" modules
244
245 -compile all default modules and include uri_radius (not compiled by default):
246
247 make include_modules="uri_radius" modules
248
249 -compile all the modules from the modules subdirectory (even the one excluded
250 by default):
251
252 make exclude_modules="" modules
253
254 -compile all the modules from the modules subdirectory excluding vm:
255
256 make exclude_modules=vm modules
257
258 or
259
260 make exclude_modules="" skip_modules=vm modules
261
262
263 -compile with the "tm" module statically linked and with profiling
264
265 make static_modules=tm PROFILE=-pg all
266
267 -compile with gcc-3.2 instead of gcc
268
269 make CC=gcc-3.2 all
270
271 or
272
273 CC=gcc-3.2 make all
274
275
276
277 Make targets:
278
279 Clean:
280
281 make clean   (clean the modules too)
282 make proper  (clean also the dependencies)
283 make distclean (the same as proper)
284 make mantainer-clean (clean everything, including auto generated files,
285  tags, *.dbg a.s.o)
286
287 Compile:
288
289 make proper
290 make
291 (or gmake on non-Linux systems)
292 make modules 
293 or make modules exclude_modules="CVS print" etc.
294
295 Make tags:
296
297 make TAGS
298
299 Create a tar.gz with the sources (in ../):
300
301 make tar
302
303 Create a tar.gz with the binary distribution (in ../):
304
305 make bin
306
307 Create a gzipped solaris package (in ../):
308
309 make sunpkg
310
311 Create debian packages (in ../):
312
313 make deb
314
315 or
316
317 dpkg-buildpackage
318
319 Install:
320
321 make prefix=/usr/local  install
322
323 Note: If you use prefix parameter in make install then you also need
324 to use this parameter in previous make commands, i.e. make, make modules,
325 or make all. If you fail to do this then SER will look for the default
326 configuration file in a wrong directory, because the directory of the
327 default configuration file is hard coded into ser during compile time. 
328 When you use a different prefix parameter when installing then the 
329 directory hard coded in ser and the directory in which the file will be 
330 installed by make install will not match. (You can specify exact location
331 of the configuration file using -f parameter of ser).
332
333 For example, if you do the following:
334 make all
335 make prefix=/ install
336
337 Then the installation will put the default configuration file into
338 /etc/ser/ser.cfg (because prefix is /), but ser will look for the file
339 in /usr/local/etc/ser/ser.cfg (because there was no prefix parameter
340 in make all and /usr/local is the default value of prefix).
341
342 Workaround is trivial, use the same parameters in all make commands:
343 make prefix=/ all
344 make prefix=/ install
345
346 That applies to other make parameters as well (for example parameters
347 "modules" or "excluded_modules").
348
349
350 3. Quick-Start Installation Guide
351 ----------------------------------------------
352
353 A) Getting Help
354
355 This guide gives you instructions on how to set up the SIP Express 
356 Router (ser) on your box quickly. In case the default configuration
357 does not fly, check documentation at ser site
358   http://www.iptel.org/ser/
359 to learn how to configure SER for your site.
360
361 If the documentation does not resolve your problem you may try contacting 
362 our user forum by E-mail at serusers@iptel.org -- that is the mailing list 
363 of ser community. To participate in the mailing list, subscribe at the 
364 following web address:
365   http://mail.iptel.org/mailman/listinfo/serusers
366
367 To participate in our commercial support program, contact info@iptel.org.
368 The support program will provide you with most timely and accurate help
369 for configuration, integration, development and any other technical
370 activity.
371
372
373 B) Disclaimers
374  
375 Note well the default "quick-start" configuration is very simple in order 
376 to be easily installable. It provides minimum features. Particularly, 
377 authentication is by default disabled, which means anyone can register using
378 any name with the server. (This is on purpose to avoid installation 
379 dependencies on MySQL which is needed for storing user credentials.)
380
381
382 C) Quick Start
383
384 The following step-by step guide gives you instructions how to install the 
385 sql-free distribution of ser. If you need persistence and authentication, 
386 then you have to install additional MySql support -- proceed to section D)
387 after you are finished with C).
388
389 1) Download an RPM or debian package from our site
390     http://www.iptel.org/ser
391 If you don't use an rpm or debian based distribution, try our tar.gz'ed binaries
392  (ser-$(version)_$(os)_$(arch).tar.gz, e.g: ser-0.8.8_linux_i386.tar.gz).
393 If you use Solaris 8 you can try our solaris package.
394 If you use Gentoo Linux you do not have to download a package.
395
396 2) install the package
397 RPM:
398     rpm -i <package_name>
399 debian:
400     dpkg -i <package_name>
401 gentoo:
402     emerge ser
403         (or if use only stable packets:
404          ACCEPT_KEYWORDS="~x86" emerge ser)
405 tar.gz:
406     cd /; tar zxvf <package_name>_os_arch.tar.gz
407     (it will install in /usr/local/, and the configuration file in
408      /usr/local/etc/ser/ser.cfg)
409 Solaris:
410     gunzip <package_name>.gz ; pkgadd -d <package_name>
411 *BSD:
412     pkg_add package_name
413     
414 3) start the server
415 RPM + gentoo:
416     /etc/init.d/ser start
417 debian:
418     ser is started automatically after the install
419     (in case something fails you can start it with /etc/init.d/ser start)
420 tar.gz:
421     the tar.gz does not include an init.d script, you'll have to create one of
422     your own or adapt one from the source distribution (debian/init.d,
423     rpm/ser.init.*, gentoo/ser.init)
424     You can start ser directly with /usr/local/sbin/ser.
425 Solaris:
426     see tar.gz.
427     
428 4) optionally, watch server's health using the
429    serctl utility
430     - to do so, first set the environment variable SIP_DOMAIN to your domain 
431       name, e.g., in Bourne shell, call
432         export SIP_DOMAIN="myserver.foobar.com"
433         - if you are using other than 'localhost' mysql server for maintaining
434           subscriber database, change the variable 'SQL_HOST' to the proper
435           host name in the serctl script
436     - run the serctl utility
437         /usr/sbin/serctl moni
438       or
439         /usr/local/sbin/serctl moni (if you installed from a tar.gz or solaris
440         package)
441
442 5) Register with the server using your favorite
443    SIP User Agent. You may want to look at configuration
444    hints for use of iptel.org site at
445      http://www.iptel.org/phpBB/viewforum.php?forum=1&8
446    For example, users of Windows Messenger need to set
447    in Tools->Options->Accounts the following values:
448      Sign-in Name: <username>@<your_server_address>
449      Advanced->Configure Settings (on)
450      Advanced->Server: <your_server_address>
451      Connect Using: UDP
452
453
454
455 D) ser with Persistent Data Storage
456
457 The default configuration is very simple and features many simplifications. 
458 In particular, it does not authenticate users and loses User Location database 
459 on reboot. To provide persistence, keep user credentials and remember users' 
460 locations across reboots, ser can be configured to use MySQL. Before you proceed, 
461 you need to make sure MySQL is installed on your box. Your MySQL server must be 
462 configured to deal with a large number of connection. To increase it, set the 
463 following line in [mysqld] section of your configuration file:
464
465    set-variable    = max_connections=500
466
467 1) Download the package containing mysql support for ser from: 
468     http://www.iptel.org/ser/
469     (rpm and deb provided, most of the binary tar.gz distributions and the 
470      solaris package include it; if it is not present you'll have to rebuild
471      from the source).
472         For gentoo please include 'mysql' to your USE variable in /etc/make.conf
473         or give it as variable to the emerge command.
474 2) install the package
475     rpm -i <package_name>
476     or
477     dpkg -i <package_name>
478         or
479         emerge ser
480         (if do not want to put 'mysql' into your USE variable you can type:
481          USE="mysql" emerge ser)
482 3) create MySQL tables
483         - if you have a previously installed SER on your system, use
484         /usr/sbin/ser_mysql.sh reinstall 
485           to convert your SER database into new structures
486         - otherwise, if this is your very first installation, use
487         /usr/sbin/ser_mysql.sh create
488           to create SER database structures
489    (you will be prompted for password of MySql "root" user)
490 4) configure ser to use SQL
491     uncomment all lines in configuration file ser.cfg which are related to 
492     authentication:
493     - loadmodule "/usr/lib/ser/modules/mysql.so"
494     - loadmodule "/usr/lib/ser/modules/auth.so"
495     - loadmodule "/usr/lib/ser/modules/auth_db.so"
496     - modparam("usrloc", "db_mode", 2)
497     - modparam("auth", "calculate_ha1", yes)
498     - modparam("auth_db", "password_column", "password")
499     - if (!www_authorize("iptel.org", "subscriber")) {
500         www_challenge("iptel.org", "0"); 
501         break;
502       }; 
503 5) be sure to replace realm, the first parameter in www_* actions, 
504    with name of your server; some broken UAC implementations don't 
505    authenticate otherwise; the authentication command in your
506    configuration script should look then like this:
507       if (!www_authorize("myserver.foobar.com", "subscriber")) {
508         www_challenge("myserver.foobar.com", "0"); 
509         break;
510       }
511 6) restart the server
512     /etc/init.d/ser restart
513 7) you can now start  managing the server using the serctl utility; 
514    you need to first set the environment variable SIP_DOMAIN to your 
515    local SIP realm, e.g.,
516        export SIP_DOMAIN="myserver.foobar.com"
517
518    a) watch the server status using 'serctl moni'
519    b) try to login with your SIP client as user 'admin' with password 'heslo'
520    c) try adding new users using 
521        'serctl add <name> <password> <email>'
522
523
524 4. Troubleshooting
525 ------------------
526
527 Q: Windows Messenger authentication fails. 
528
529 A: The most likely reason for this problem is a bug in Windows Messenger. 
530 WM only authenticates if server name in request URI equals authentication 
531 realm. After a challenge is sent by SIP server, WM does not resubmit the 
532 challenged request at all and pops up authentication window again. If you 
533 want to authenticate WM, you need to set up your realm value to equal server 
534 name. If your server has no name, IP address can be used as realm too.
535
536 Q: SIP requests are replied by ser with "483 Too Many Hops" or 
537    "513 Message Too Large"
538
539 A: In both cases, the reason is probably an error in request routing script 
540    which caused an infinite loop. You can easily verify whether this happens 
541    by watching SIP traffic on loopback interface. A typical reason for misrouting 
542    is a failure to match local domain correctly. If a server fails to recognize 
543    a request for itself, it will try to forward it to current URI in believe it 
544    would forward them to a foreign domain. Alas, it forwards the request to itself 
545    again. This continues to happen until value of max_forwards header field reaches 
546    zero or the request grows too big. Solutions is easy: make sure that domain matching 
547    is correctly configured. A quick way to achieve that is to introduce a config
548    option to ser.cfg: alias=domainname, where domainname shall be replaced with
549    name of domain, which you wish to server and which appears in request-URIs.