502f2b7383cf08f6389c3cfecaf1eeda3928b97b
[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, NetBSD/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/NetBSD: 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 *BSD:
224     pkg_add package_name
225     
226 3) start the server
227 RPM:
228     /etc/init.d/ser start
229 debian:
230     ser is started automatically after the install
231     (in case something fails you can start it wiht /etc/init.d/ser start)
232 tar.gz:
233     the tar.gz does not include an init.d script, you'll have to create one of
234     your own or adapt one from the source distribution (debian/init.d,
235     rpm/ser.init.*, gentoo/ser.init)
236     You can start ser directly with /usr/local/sbin/ser.
237 Solaris:
238     see tar.gz.
239     
240 4) optionally, watch server's health using the
241    serctl utility
242     - to do so, first set the environment variable SIP_DOMAIN to your domain 
243       name, e.g., in Bourne shell, call
244         export SIP_DOMAIN="myserver.foobar.com"
245         - if you are using other than 'localhost' mysql server for maintaining
246           subscriber database, change the variable 'SQL_HOST' to the proper
247           host name in the serctl script
248     - run the serctl utility
249         /usr/sbin/serctl moni
250       or
251         /usr/local/sbin/serctl moni (if you installed from a tar.gz or solaris
252         package)
253 5) Register with the server using your favorite
254    SIP User Agent. You may want to look at configuration
255    hints for use of iptel.org site at
256      http://www.iptel.org/phpBB/viewforum.php?forum=1&8
257    For example, users of Windows Messenger need to set
258    in Tools->Options->Accounts the foolowing values:
259      Sign-in Name: <username>@<your_server_address>
260      Advanced->Configure Settings (on)
261      Advanced->Server: <your_server_address>
262      Connect Using: UDP
263
264
265
266 D) ser with Persistent Data Storage
267
268 The default configuration is very simple and features many simplifications. 
269 In particular, it does not authenticate users and loses User Location 
270 database on reboot. To provide persistency, keep user credentials and remember 
271 users' locations across reboots, ser can be configured to use MySQL. Before you 
272 proceed, you need to make sure MySQL is installed on your box.
273
274
275 1) Download the package containing mysql support for ser from: 
276     http://www.iptel.org/ser/
277     (rpm and deb provided, most of the binary tar.gz distributions and the 
278      solaris package include it; if it is not present you'll have to rebuild
279      from the source).
280 2) install the package
281     rpm -i <package_name>
282     or
283     dpkg -i <package_name>
284 3) create MySQL tables
285         - if you have a previously installed SER on your system, use
286         /usr/sbin/ser_mysql.sh create
287           to convert your SER database into new structures
288         - otherwise, if this is your very first installation, use
289         /usr/sbin/ser_mysql.sh create
290           to create SER database structures
291    (you will be promted for password of MySql "root" user)
292 4) configure ser to use SQL
293     uncomment all lines in configuration file ser.cfg which are related to 
294     authentication:
295     - loadmodule "/usr/lib/ser/modules/mysql.so"
296     - loadmodule "/usr/lib/ser/modules/auth.so"
297     - modparam("usrloc", "db_mode", 2)
298     - modparam("auth", "calculate_ha1", yes)
299     - if (!www_authorize("iptel.org", "subscriber")) {
300         www_challenge("iptel.org", "0"); 
301         break;
302       }; 
303 5) be sure to replace realm, the first parameter in www_* actions, 
304    with name of your server; some broken UAC implementations don't 
305    authenticate otherwise; the authentication command in your
306    configuration script should look then like this:
307       if (!www_authorize("myserver.foobar.com", "subscriber")) {
308         www_challenge("myserver.foobar.com", "0"); 
309         break;
310       }
311 6) restart the server
312     /etc/init.d/ser restart
313 7) you can now start  managing the server using the serctl utility; 
314    you need to first set the environment variable SIP_DOMAIN to your 
315    local SIP realm, e.g.,
316        export SIP_DOMAIN="myserver.foobar.com"
317
318    a) watch the server status using 'serctl moni'
319    b) try to login with your SIP client as user 'admin' with password 'heslo'
320    c) try adding new users using 
321        'serctl add <name> <password> <email>'
322
323
324 4. Troubleshooting
325 ------------------
326
327 Q: Windows Messenger authentication fails. 
328
329 A: The most likely reason for this problem is a bug in Windows Messenger. 
330 WM only authenticates if server name in request URI equals authentication 
331 realm. After a challenge is sent by SIP server, WM does not resubmit the 
332 challenged request at all and pops up authentication window again. If you 
333 want to authenticate WM, you need to set up your realm value to equal server 
334 name. If your server has no name, IP address can be used as realm too.
335
336 Q: SIP requests are replied by ser with "483 Too Many Hops" or 
337    "513 Message Too Large"
338
339 A: In both cases, the reason is probably an error in request routing script 
340    which caused an infinite loop. You can easily verify whether this happens 
341    by watching SIP traffic on loopback interface. A typical reason for misrouting 
342    is a failure to match local domain correctly. If a server fails to recognize 
343    a request for itself, it will try to forward it to current URI in believe it 
344    would forward them to a foreign domain. Alas, it forwards the request to itself 
345    again. This continues to happen until value of max_forwards header field reaches 
346    zero or the request grows too big. Solutions is easy: make sure that domain matching 
347    is correctly configured. A quick way to achieve that is to introduce a config
348    option to ser.cfg: alias=domainname, where domainname shall be replaced with
349    name of domain, which you wish to server and which appears in request-URIs.