$Id$ =========================================== SIP Express Router (ser) Installation Notes http://www.iptel.org/ser/ =========================================== This memo gives you hints how to set up SER quickly. To understand how SER works and how to configure it properly, read admin's guide available from SER website. We also urge you to read latest ISSUES (available from SER website too) and check for potential problems in this release. Users of previous releases are encouraged to read NEWS to learn how to move to this new SER version. Contents 1. Supported Architectures and Requirements 2. Howto Build ser From Source Distribution 3. Quick-Start Installation Guide 1. Supported Architectures and Requirements SER supports the following operating systems: o Linux, FreeBSD, NetBSD, OpenBSD, Solaris, Darwin on these architectures: o i386, x86_64 (amd64), armv4l, sparc64, powerpc, powerpc64. Additionally, there is experimental support for these architectures: o mips1, mips2, sparc32, alpha Other architectures and operating systems may work as well but have not been tested and may alterations to the Makefiles. 1.1. Requirements In order to build SER from its sources, you will need: o gcc or icc : gcc >= 2.9x; version 3.1 or higher recommended (older versions will work but they may require some options tweaking for best performance) o bison or yacc (Berkley yacc) o flex o GNU make, version 3.79 or newer (on Linux this is the standard "make", on *BSD and Solaris it is called "gmake") o sed and tr (used in the makefiles) o GNU tar ("gtar" on Solaris) and gzip if you want "make tar" to work o GNU install, BSD install or Solaris install if you want "make install", "make bin", "make sunpkg" to work If you want to build some of the modules, you will have to fulfill additional requirements: o libmysqlclient & libz (zlib) for MySQL support (the mysql module) o libexpat for jabber gateway support (the jabber module) o libxml2 for the cpl-c (CPL support), pa (presence) and xmlrpc modules o libradiusclient-ng (> 5.0) for radius support (the acc_radius, auth_radius, avp_radius, and uri_radius modules) o libpq for PostgreSQL support (the postgres module) o libssl for SSL/TLS support (tls module). 1.2. Operating System Specific Notes 1.2.1. The BSDs Make sure to have gmake, bison or yacc, and flex installed. 1.2.2. FreeBSD 5.4 If you want to compile all the modules, you will need the following packages: o mysql-client-* (any version, install one of the mysql*-client ports) for libmysqlclient o postgresql-libpqxx-2.4.2_1 (/usr/ports/databases/postgresql-libpqxx) for libpq o expat-1.95.8 (/usr/ports/textproc/expat2) for libexpat o libxml2-2.6.18 (/usr/ports/textproc/libxml2) for libxml2 o radiusclient-0.4.7 (/usr/ports/net/radiusclient) for libradiusclient-ng NOTE: You will need to add radiusclient_ng=4 to the gmake command line for compiling SER if you use the 0.4.* version. Compile example (all the modules and ser in a tar.gz): $ gmake bin radiusclient_ng=4 \ include_modules="mysql jabber cpl-c auth_radius group_radius \ uri_radius postgres pa" 1.2.3. OpenBSD 3.7 If you want to compile all the modules, you will need the following packages: o mysql-client-4.0.23 (/usr/ports/databases/mysql) for libmysqlclient o expat-1.95.6 (/usr/ports/textproc/expat) for libexpat o libxml-2.6.16p0 (/usr/ports/textproc/libxml) for libxml2 o radiusclient-ng-0.5.1 from http://download.berlios.de/radiusclient-ng/radiusclient-ng-0.5.1.tar.gz (you need to download and install it, since there is no "official" openbsd port for it) for libradiusclient-ng 1.2.4. NetBSD 2.0 If you want to compile all the modules, you will need the following packages: o mysql-client-4.1.12 (/usr/pkgsrc/databases/mysql4-client) for libmysqlclient o expat-1.95.8nb2 (/usr/pkgsrc/textproc/expat) for libexpat o libxml2-2.6.19 (/usr/pkgsrc/textproc/libxml2) for libxml2 o radiusclient-ng-0.5.1 (see OpenBSD) 1.2.5. Solaris 10 You can use Solaris's yacc instead of bison. You might need also gtar and ginstall. If you don't have ginstall you can use Solaris install, just make sure it's in the PATH (it's usually in /usr/sbin) and add INSTALL=install either to the environment or to the make command line (e.g.: gmake INSTALL=install all). Needed packages: [TODO] 1.2.6. Debian GNU/Linux Needed packages for compiling all the modules: o libmysqlclient-dev for libmysqlclient o libpq-dev for libpq o libexpat1-dev for libexpat o libxml2-dev for libxml2 o libradiusclient-ng-dev for libradiusclient Debian currently still ships version 0.9.7. SER 2.0 will follow soon in the sid and lenny releases. 1.2.7. Red Hat Linux [TODO] 2. How To Build SER From a Source Distribution 2.1. Basics SER is split in four main parts: The core, the modules, the utilties, and scripts/examples. When you build SER, you can decide to build only the core, the modules, both, or all. To compile SER's core only: $ make If make doesn't work, try gmake instead. To compile a basic set of modules: $ make modules Compile core and the basic set of modules: $ make all By default no modules will be build that require external libraries or that are considered to be "experimental". Instead of compiling the default modules only, you can specify groups of modules to include, according to their status: o standard - modules in this group are considered a standard part of SER (due to widespread usage) but they have no dependencies (note that some of these interplay with external systems. However, they don't have compile or link dependencies). Only modules in this group are build by default. o standard-dep - modules in this group are considered a standard part of SER (due to widespread usage) but they have dependencies that must be satisfied for compilation. NOTE! All presence modules (dialog, pa, presence_b2b, rls, xcap) have been included in this group due to interdependencies o stable - modules in this group satisfy specific or niche applications, but are considered stable for production use. They may or may not have dependencies o experimental - modules in this group are either not complete, untested, or without enough reports of usage to allow the module into the stable group. They may or may not have dependencies. To compile core with standard modules: $ make group_include="standard" all To compile all modules (provided you have all the required libraries installed) use: $ make group_include="standard standard-dep stable experimental" all There are also in addition some "convenience" groups: o mysql - include all modules dependent on mysql o radius - include all modules on radiusclient o presence - include all the presence modules So, to make a standard installation with mysql, use: $ make group_include="standard mysql" all In addition to group_include (or instead), you can use include_modules="modA modB" to specify exactly the modules you want to include. For example, to only include "mymodule", run $ make include_modules="mymodule" modules You can also explicitly skip modules using skip_modules. Let's say you want all the standard and standard-dep modules except domain: $ make group_include="standard standard-dep" skip_modules="domain" all As this mechanism is very powerful, you may be uncertain which modules will be included. If you use the make target print-modules, you will receive a list of all modules that will be in included and excluded. The command $ make print-modules thus will show which modules are build by default. If you want to install or build a binary package (a tar.gz with ser and the modules), substitute "all" in the above command with "install" or "bin". Some More compile examples: o compile with profiling $ make PROFILE=-pg all o compile debug mode version $ make mode=debug all o compile debug version with profiling $ make mode=debug PROFILE=-pg all o compile only the print module $ make modules=modules/print modules o compile all the "default" modules except textops and vm $ make skip_modules="textops vm" modules o compile all default modules and include uri_radius (not compiled by default): $ make include_modules="uri_radius" modules o compile all the modules from the modules subdirectory (even the one excluded by default): $ make exclude_modules="" modules o compile all the modules from the modules subdirectory excluding vm: $ make exclude_modules=vm modules or $ make exclude_modules="" skip_modules=vm modules o compile with the "tm" module statically linked and with profiling $ make static_modules=tm PROFILE=-pg all o compile with gcc-3.2 instead of gcc $ make CC=gcc-3.2 all or $ CC=gcc-3.2 make all 2.2. Make Targets Targets for cleaning: o make clean - clean the core and the modules, too. o make proper - additionally, clean the dependency (.d) files. o make distclean - the same as proper. o make mantainer-clean - clean everything, including auto generated files, tags, *.dbg a.s.o) Compile: o make proper o make (or gmake on non-Linux systems) o make modules or make modules exclude_modules="CVS print" etc. Make tags: o make TAGS Create a tar.gz with the sources (in ../): o make tar Create a tar.gz with the binary distribution (in ../): o make bin Create a gzipped solaris package (in ../): o make sunpkg Create debian packages (in ../): o make deb or o dpkg-buildpackage Install: o make prefix=/usr/local install Note: If you use prefix parameter in make install then you also need to use this parameter in previous make commands, i.e. make, make modules, or make all. If you fail to do this then SER will look for the default configuration file in a wrong directory, because the directory of the default configuration file is hard coded into ser during compile time. When you use a different prefix parameter when installing then the directory hard coded in ser and the directory in which the file will be installed by make install will not match. (You can specify exact location of the configuration file using -f parameter of ser). For example, if you do the following: $ make all $ make prefix=/ install Then the installer will put the default configuration file into /etc/ser/ser.cfg (because prefix is /), but ser will look for the file in /usr/local/etc/ser/ser.cfg (because there was no prefix parameter in make all and /usr/local is the default value of prefix). Workaround is trivial, use the same parameters in all make commands: $ make prefix=/ all $ make prefix=/ install That applies to other make parameters as well (for example parameters "modules" or "excluded_modules"). 3. Quick-Start Installation Guide 3.1. Getting Help This guide gives you instructions on how to set up the SIP Express Router (ser) on your box quickly. In case the default configuration does not fly, check documentation at ser site http://www.iptel.org/ser/ to learn how to configure SER for your site. If the documentation does not resolve your problem you may try contacting our user forum by E-mail at firstname.lastname@example.org -- that is the mailing list of the ser community. To participate in the mailing list, subscribe at the following web address: http://lists.iptel.org/mailman/listinfo/serusers 3.2. Disclaimers Note well the default "quick-start" configuration is very simple in order to be easily installable. It provides minimum features. Particularly, authentication is by default disabled, which means anyone can register using any name with the server. (This is on purpose to avoid installation dependencies on MySQL which is needed for storing user credentials.) As soon as everything is working fine, you should advance to the more complex scenario described in section 3.4. 3.3. Quick Start The following step-by step guide gives you instructions how to install the sql-free distribution of ser. If you need persistence and authentication, then you have to install additional MySql support -- proceed to section D) after you are finished with C). 1. Download an RPM or debian package from our site http://www.iptel.org/ser If you don't use an rpm or debian based distribution, try our tar.gz'ed binaries (ser-$(version)_$(os)_$(arch).tar.gz, e.g: ser-0.8.8_linux_i386.tar.gz). If you use Solaris 8 you can try our solaris package. If you use Gentoo Linux you do not have to download a package. 2. Install the package o RPM: rpm -i <package_name> o Debian: dpkg -i <package_name> (or, if available in version 2.0 in your Debian release, just do apt-get install ser. In this case you don't need to download anything, of course). o gentoo: emerge ser (or if use only stable packets: ACCEPT_KEYWORDS="~x86" emerge ser) o tar.gz: $ cd /; tar zxvf <package_name>_os_arch.tar.gz (it will install in /usr/local/, and the configuration file in /usr/local/etc/ser/ser.cfg) o Solaris: $ gunzip <package_name>.gz ; pkgadd -d <package_name> o The BSDs: $ pkg_add package_name 3. Start the server o RPM + gentoo: /etc/init.d/ser start o Debian: ser is started automatically after the install (in case something fails you can start it with /etc/init.d/ser start) o tar.gz: the tar.gz does not include an init.d script, you'll have to create one of your own or adapt one from the source distribution (debian/init.d, rpm/ser.init.*, gentoo/ser.init). You can start ser directly with /usr/local/sbin/ser. o Solaris: see tar.gz. 4. Register with the server using your favorite SIP User Agent. Point it to the IP address or hostname of your server and use whatever username you like. 3.4 SER with Persistent Data Storage The default configuration is very simple and features many simplifications. In particular, it does not authenticate users and looses the user location database on reboot. To provide persistence, keep user credentials and remember users' locations across reboots, ser can be configured to use MySQL. 1. Before you proceed, you need to make sure MySQL is installed on your server. Your MySQL server must be configured to deal with a large number of connection. To increase it, set the following line in [mysqld] section of your configuration file: set-variable = max_connections=500 2. Download the package containing mysql support for ser from http://www.iptel.org/ser/ (rpm and deb provided, most of the binary tar.gz distributions and the solaris package include it by default; if it is not present you'll have to rebuild from the source). For gentoo please include 'mysql' to your USE variable in /etc/make.conf or give it as variable to the emerge command. 3. Install the package $ rpm -i <package_name> or $ dpkg -i <package_name> or $ USE="mysql" emerge ser 4. Create MySQL tables. If this is your first installation, you can do this using the command $ /usr/sbin/ser_mysql.sh create (if you use the .tar.gz packages, the script will be in /usr/local/sbin). If you a previously installed SER on your system, use $ /usr/sbin/ser_mysql.sh reinstall to convert your SER database into new structures. 5. Configure ser to use the database. A simple configuration that uses the database is provided as the file ser-advanced.cfg which will be installed in /etc/ser. In order to use it, either copy it over /etc/ser/ser.cfg or modify the start scripts to use the option "-f /etc/ser/ser-advanced.cfg". Since you most likely won't go back to the simple standard configuration, the first option will do: $ cp /etc/ser/ser-oob.cfg /etc/ser/ser.cfg 6. Restart the server $ /etc/init.d/ser restart 7. Create a domain and some users. The best way to do this is by using the serctl. The source package is available at http://ftp.iptel.org/pub/serctl/ There also may be binary packages for your system. Once you have installed serctl, create a domain. If your domain is example.com, you do: $ ser_domain add example.com example.com Yes, that would be example.com twice. The first occurence is the logical name you use for the domain, the second for the actual DNS name. You can state additional DNS names after that as well, such as "sip.example.com". These would then be aliases and can be used interchangably for being called (but not for necessarly for registering -- always use the first name for that). You add users in three steps. First, you add the user itself, the you assign one or more URIs to it and finally, you add credentials so that the user can register. $ ser_user add john $ ser_uri add john sip:email@example.com sip:firstname.lastname@example.org $ ser_cred add john john example.com example.com See the help text of ser_user, ser_uri, and ser_cred for more details. 8. Register with the server using your favorite SIP User Agent. Use the domain and user you insterted above. Remember that you may need to configure DNS for it to work.