6f8444197851a3ad32c85af4cf8670f18d4111bf
[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   urgue you to read latest ISSUES (available from SER website 
16   too) and check for potential problems in this release.
17   
18
19 TOC
20
21 1. Supported Architectures and Requirements
22 2. Howto Build ser From Source Distribution
23 3. Quick-Start Installation Guide
24    A) Getting Help
25    B) Disclaimers
26    C) Quick Start
27    D) ser with Persistent Data Storage
28 4. Troubleshooting
29
30
31
32 +--------------------------------------------------------+
33 | CAUTION: the 0.8.11 release include changes which      |
34 | are incompatible with scripts and databases used       |
35 | in previous versions. Care is advised when upgrading   |
36 | from previous releases to 0.8.11.                      |
37 +--------------------------------------------------------+
38
39
40
41 1. Supported Architectures and Requirements
42 -------------------------------------------
43
44 Supported arhitectures: Linux/i386, Linux/armv4l, FreeBSD/i386, OpenBSD/i386
45 Solaris/sparc64 
46 (for other arhitectures the Makefiles might need to be edited)
47
48 There are various configuration options defined in the Makefile.
49
50 Requirements:
51
52
53 - gcc or icc : gcc >= 2.9x; 3.[12] recommended (it will work with older version
54   but it might require some options tweaking for best performance)
55 - bison or yacc (Berkley yacc)
56 - flex
57 - GNU make (on Linux this is the standard "make", on FreeBSD and Solaris is
58  called "gmake") version >= 3.79.
59 - sed and tr (used in the makefiles)
60 - GNU tar ("gtar" on Solaris) and gzip if you want "make tar" to work
61 - GNU install or BSD install (on Solaris "ginstall") if you want "make
62   install", "make bin", "make sunpkg" to work
63 - libmysqlclient & libz (zlib) if you want mysql support (the mysql module)
64 - libexpat if you want the jabber gateway support (the jabber module)
65
66
67 OS Notes:
68
69 - FreeBSD/OpenBSD: make sure gmake, bison or yacc & flex are installed
70 - Solaris: as above; you can use Solaris's yacc instead of bison. You might
71   need also gtar and ginstall.
72 - Windows: it works in windows (only the core, w/o shared mem. support) but you
73   must install a recent cygwin version (http://www.cygwin.com/) and also 
74   install a newer regex library version (>=0.12). 
75     
76
77 2. Howto Build ser From Source Distribution
78 -------------------------------------------
79
80 (NOTE: if make doesn't work try gmake  instead)
81
82 - compile with default options:
83
84 make   #builds only ser core, equivalent to make ser
85 make modules
86
87 or make all #builds everything
88
89 - compile with profiling
90
91 make PROFILE=-pg all
92
93 -compile debug mode version
94
95 make mode=debug all
96
97 -compile debug version with profiling
98
99 make mode=debug PROFILE=-pg all
100
101 -compile only the print module
102
103 make modules=modules/print modules
104
105 -compile all the modules except textops
106
107 make exclude_modules="CVS textops" modules
108
109 -compile with the "tm" module statically linked and with profiling
110
111 make static_modules=tm PROFILE=-pg all
112
113 -compile with gcc-3.2 instead of gcc
114
115 make CC=gcc-3.2 all
116
117 or
118
119 CC=gcc-3.2 make all
120
121
122
123 Make targets:
124
125 Clean:
126
127 make clean   (clean the modules too)
128 make proper  (clean also the dependencies)
129 make distclean (the same as proper)
130 make mantainer-clean (clean everything, including auto generated files,
131  tags, *.dbg a.s.o)
132
133 Compile:
134
135 make proper
136 make
137 (or gmake on non-Linux systems)
138 make modules 
139 or make modules exclude_modules="CVS print" etc.
140
141 Make tags:
142
143 make TAGS
144
145 Create a tar.gz with the sources (in ../):
146
147 make tar
148
149 Create a tar.gz with the binary distribution (in ../):
150
151 make bin
152
153 Create a gzipped solaris package (in ../):
154
155 make sunpkg
156
157 Create debian packages (in ../):
158
159 make deb
160
161 or
162
163 dpkg-buildpackage
164
165 Install:
166
167 make prefix=/usr/local  install
168
169
170
171 3. Quick-Start Installation Guide
172 ----------------------------------------------
173
174 A) Getting Help
175
176 This guide gives you instructions on how to set up the SIP Express 
177 Router (ser) on your box quickly. In case the default configuration
178 does not fly, check documentation at ser site
179   http://www.iptel.org/ser/
180
181 If the documentation does not resolve your problem you may try contacting 
182 us by E-mail at serusers@iptel.org -- that is the mailing list of ser
183 community from which you can get most rapid help. To participate in the
184 mailing list, subscribe at the following web address:
185   http://mail.iptel.org/mailman/listinfo/serusers
186
187 If you are concerned about your privacy, you may post your questions to 
188 iptel.org's helpline at serhelp@iptel.org.
189
190 B) Disclaimers
191  
192 Note well the default "quick-start" configuration is very simple in order 
193 to be easily installable. It provides minimum features. Particularly, 
194 authentication is by default disabled, which means anyone can register using
195 any name with the server. (This is on purpose to avoid installation 
196 dependencies on MySQL which is needed for storing user credentials.)
197
198
199 C) Quick Start
200
201 The following step-by step guide gives you instructions how to install the 
202 sql-free distribution of ser. If you need persistancy and authentication, 
203 then you have to install additional MySql support -- proceed to section D)
204 after you are finished with C).
205
206 1) Download an RPM or debian package from our site
207     http://www.iptel.org/ser
208 If you don't use an rpm or debian based distro, try our tar.gz'ed binaries
209  (ser-$(version)_$(os)_$(arch).tar.gz, e.g: ser-0.8.8_linux_i386.tar.gz).
210 If you use Solaris 8 you can try our solaris package.
211
212 2) install the package
213 RPM:
214     rpm -i <package_name>
215 debian:
216     dpkg -i <package_name>
217 tar.gz:
218     cd /; tar zxvf <package_name>_os_arch.tar.gz
219     (it will install in /usr/local/, and the configuration file in
220      /usr/local/etc/ser/ser.cfg)
221 Solaris:
222     gunzip <package_name>.gz ; pkgadd -d <package_name>
223     
224 3) start the server
225 RPM:
226     /etc/init.d/ser start
227 debian:
228     ser is started automatically after the install
229     (in case something fails you can start it wiht /etc/init.d/ser start)
230 tar.gz:
231     the tar.gz does not include an init.d script, you'll have to create one of
232     your own or adapt one from the source distribution (debian/init.d,
233     rpm/ser.init.*, gentoo/ser.init)
234     You can start ser directly with /usr/local/sbin/ser.
235 Solaris:
236     see tar.gz.
237     
238 4) optionally, watch server's health using the
239    serctl utility
240     - to do so, first set the environment variable SIP_DOMAIN to your domain 
241       name, e.g., in Bourne shell, call
242         export SIP_DOMAIN="myserver.foobar.com"
243         - if you are using other than 'localhost' mysql server for maintaining
244           subscriber database, change the variable 'SQL_HOST' to the proper
245           host name in the serctl script
246     - run the serctl utility
247         /usr/sbin/serctl moni
248       or
249         /usr/local/sbin/serctl moni (if you installed from a tar.gz or solaris
250         package)
251 5) Register with the server using your favorite
252    SIP User Agent. You may want to look at configuration
253    hints for use of iptel.org site at
254      http://www.iptel.org/phpBB/viewforum.php?forum=1&8
255    For example, users of Windows Messenger need to set
256    in Tools->Options->Accounts the foolowing values:
257      Sign-in Name: <username>@<your_server_address>
258      Advanced->Configure Settings (on)
259      Advanced->Server: <your_server_address>
260      Connect Using: UDP
261
262
263
264 D) ser with Persistent Data Storage
265
266 The default configuration is very simple and features many simplifications. 
267 In particular, it does not authenticate users and loses User Location 
268 database on reboot. To provide persistency, keep user credentials and remember 
269 users' locations across reboots, ser can be configured to use MySQL. Before you 
270 proceed, you need to make sure MySQL is installed on your box.
271
272
273 1) Download the package containing mysql support for ser from: 
274     http://www.iptel.org/ser/
275     (rpm and deb provided, most of the binary tar.gz distributions and the 
276      solaris package include it; if it is not present you'll have to rebuild
277      from the source).
278 2) install the package
279     rpm -i <package_name>
280     or
281     dpkg -i <package_name>
282 3) create MySQL tables
283         - if you have a previously installed SER on your system, use
284         /usr/sbin/ser_mysql.sh create
285           to convert your SER database into new structures
286         - otherwise, if this is your very first installation, use
287         /usr/sbin/ser_mysql.sh create
288           to create SER database structures
289    (you will be promted for password of MySql "root" user)
290 4) configure ser to use SQL
291     uncomment all lines in configuration file ser.cfg which are related to 
292     authentication:
293     - loadmodule "/usr/lib/ser/modules/mysql.so"
294     - loadmodule "/usr/lib/ser/modules/auth.so"
295     - modparam("usrloc", "db_mode", 2)
296     - modparam("auth", "calculate_ha1", yes)
297     - if (!www_authorize("iptel.org", "subscriber")) {
298         www_challenge("iptel.org", "0"); 
299         break;
300       }; 
301 5) be sure to replace realm, the first parameter in www_* actions, 
302    with name of your server; some broken UAC implementations don't 
303    authenticate otherwise; the authentication command in your
304    configuration script should look then like this:
305       if (!www_authorize("myserver.foobar.com", "subscriber")) {
306         www_challenge("myserver.foobar.com", "0"); 
307         break;
308       }
309 6) restart the server
310     /etc/init.d/ser restart
311 7) you can now start  managing the server using the serctl utility; 
312    you need to first set the environment variable SIP_DOMAIN to your 
313    local SIP realm, e.g.,
314        export SIP_DOMAIN="myserver.foobar.com"
315
316    a) watch the server status using 'serctl moni'
317    b) try to login with your SIP client as user 'admin' with password 'heslo'
318    c) try adding new users using 
319        'serctl add <name> <password> <email>'
320
321
322 4. Troubleshooting
323 ------------------
324
325 Q: Windows Messenger authentication fails. 
326
327 A: The most likely reason for this problem is a bug in Windows Messenger. 
328 WM only authenticates if server name in request URI equals authentication 
329 realm. After a challenge is sent by SIP server, WM does not resubmit the 
330 challenged request at all and pops up authentication window again. If you 
331 want to authenticate WM, you need to set up your realm value to equal server 
332 name. If your server has no name, IP address can be used as realm too.
333
334 Q: SIP requests are replied by ser with "483 Too Many Hops" or 
335    "513 Message Too Large"
336
337 A: In both cases, the reason is probably an error in request routing script 
338    which caused an infinite loop. You can easily verify whether this happens 
339    by watching SIP traffic on loopback interface. A typical reason for misrouting 
340    is a failure to match local domain correctly. If a server fails to recognize 
341    a request for itself, it will try to forward it to current URI in believe it 
342    would forward them to a foreign domain. Alas, it forwards the request to itself 
343    again. This continues to happen until value of max_forwards header field reaches 
344    zero or the request grows too big. Solutions is easy: make sure that domain matching 
345    is correctly configured. A quick way to achieve that is to introduce a config
346    option to ser.cfg: alias=domainname, where domainname shall be replaced with
347    name of domain, which you wish to server and which appears in request-URIs.