INSTALL
550bb8c3
 $Id$
 
cb7dae9d
 
e12e9092
 		===========================================
ea828a39
 
e12e9092
 		SIP Express Router (ser) Installation Notes
ea828a39
 
e12e9092
 			 http://www.iptel.org/ser/
ea828a39
 
e12e9092
 		===========================================
b8bc4cf8
 
e12e9092
 
    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.
f9882aab
   
 
e12e9092
 Contents
 
    1. Supported Architectures and Requirements
    2. Howto Build ser From Source Distribution
    3. Quick-Start Installation Guide
 
b8bc4cf8
 
 1. Supported Architectures and Requirements
 
e12e9092
    SER supports the following operating systems:
b8bc4cf8
 
e12e9092
       o  Linux, FreeBSD, NetBSD, OpenBSD, Solaris, Darwin
b8bc4cf8
 
e12e9092
    on these architectures:   
       
       o  i386, x86_64 (amd64), armv4l, sparc64, powerpc, powerpc64.
550bb8c3
 
e12e9092
    Additionally, there is experimental support for these architectures:
9d24a262
 
e12e9092
       o  mips1, mips2, sparc32, alpha
550bb8c3
 
e12e9092
    Other architectures and operating systems may work as well but have
    not been tested and may alterations to the Makefiles.
628e3a5a
 
550bb8c3
 
e12e9092
 1.1. Requirements
550bb8c3
 
e12e9092
    In order to build SER from its sources, you will need:
5b0cb4c6
 
e12e9092
       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
550bb8c3
 
e12e9092
    If you want to build some of the modules, you will have to fulfill
    additional requirements:
550bb8c3
 
acee3972
       o  libmysqlclient & libz (zlib) for MySQL support (the mysql module)
e12e9092
       o  libexpat for jabber gateway support (the jabber module)
facb6235
       o  libxml2 for the cpl-c (CPL support), pa (presence) and xmlrpc
 	     modules
e12e9092
       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)
facb6235
 	  o  libssl for SSL/TLS support (tls module).
9d24a262
 
e12e9092
 
 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.
9d24a262
   
e12e9092
          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).
9d24a262
   
e12e9092
    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
a02e3c46
      o  libradiusclient-ng-dev for libradiusclient
e12e9092
 
    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
9d24a262
 
e12e9092
       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
9d24a262
 
e12e9092
       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.
9d24a262
 
e12e9092
    To compile core with standard modules:
9d24a262
 
e12e9092
       $ make group_include="standard" all
9d24a262
 
e12e9092
    To compile all modules (provided you have all the required libraries
    installed) use:
550bb8c3
 
e12e9092
       $ make group_include="standard standard-dep stable experimental" all
247c2b65
 
e12e9092
    There are also in addition some "convenience" groups:
247c2b65
 
e12e9092
       o  mysql - include all modules dependent on mysql
247c2b65
 
e12e9092
       o  radius - include all modules on radiusclient
247c2b65
 
e12e9092
       o  presence - include all the presence modules
1ec7aeb1
 
e12e9092
    So, to make a standard installation with mysql, use:
247c2b65
 
e12e9092
       $ make group_include="standard mysql" all
1ec7aeb1
 
e12e9092
    In addition to group_include (or instead), you can use
    
       include_modules="modA modB"
1ec7aeb1
 
e12e9092
    to specify exactly the modules you want to include. For example, to
    only include "mymodule", run
1ec7aeb1
 
e12e9092
       $ make include_modules="mymodule" modules
1ec7aeb1
 
e12e9092
    You can also explicitly skip modules using skip_modules. Let's say you
    want all the standard and standard-dep modules except domain:
1ec7aeb1
 
e12e9092
       $ make group_include="standard standard-dep" skip_modules="domain" all
1ec7aeb1
 
e12e9092
    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
1ec7aeb1
 
e12e9092
       $ make print-modules
fd564b72
 
e12e9092
    thus will show which modules are build by default.
fd564b72
 
e12e9092
    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".
fd564b72
 
 
e12e9092
    Some More compile examples:
fd564b72
 
e12e9092
       o  compile with profiling
1ec7aeb1
 
e12e9092
             $ make PROFILE=-pg all
1ec7aeb1
 
e12e9092
       o  compile debug mode version
1ec7aeb1
 
e12e9092
             $ make mode=debug all
9d24a262
 
e12e9092
       o  compile debug version with profiling
9d24a262
 
e12e9092
             $ make mode=debug PROFILE=-pg all
9d24a262
 
e12e9092
       o  compile only the print module
247c2b65
 
e12e9092
             $ make modules=modules/print modules
247c2b65
 
e12e9092
       o  compile all the "default" modules except textops and vm
247c2b65
 
e12e9092
             $ make skip_modules="textops vm" modules
247c2b65
 
e12e9092
       o  compile all default modules and include uri_radius (not compiled
          by default):
247c2b65
 
e12e9092
             $ make include_modules="uri_radius" modules
247c2b65
 
e12e9092
       o  compile all the modules from the modules subdirectory (even the
          one excluded by default):
247c2b65
 
e12e9092
             $ make exclude_modules="" modules
247c2b65
 
e12e9092
       o  compile all the modules from the modules subdirectory excluding
          vm:
fc50bc47
 
e12e9092
             $ make exclude_modules=vm modules
fc50bc47
 
e12e9092
          or
fc50bc47
 
e12e9092
             $ make exclude_modules="" skip_modules=vm modules
fc50bc47
 
 
e12e9092
       o  compile with the "tm" module statically linked and with profiling
fc50bc47
 
e12e9092
             $ make static_modules=tm PROFILE=-pg all
fc50bc47
 
e12e9092
       o  compile with gcc-3.2 instead of gcc
fc50bc47
 
e12e9092
             $ make CC=gcc-3.2 all
fc50bc47
 
e12e9092
          or
247c2b65
 
e12e9092
             $ CC=gcc-3.2 make all
247c2b65
 
b2dec9c6
 
e12e9092
 2.2. Make Targets
b2dec9c6
 
e12e9092
    Targets for cleaning:
5b0cb4c6
 
e12e9092
       o  make clean - clean the core and the modules, too.
b2dec9c6
 
e12e9092
       o  make proper - additionally, clean the dependency (.d) files.
5b0cb4c6
 
e12e9092
       o  make distclean - the same as proper.
b2dec9c6
 
e12e9092
       o  make mantainer-clean - clean everything, including auto
          generated files, tags, *.dbg a.s.o)
247c2b65
 
e12e9092
    Compile:
247c2b65
 
e12e9092
       o  make proper
247c2b65
 
e12e9092
       o  make
          (or gmake on non-Linux systems)
247c2b65
 
e12e9092
       o  make modules 
          or make modules exclude_modules="CVS print" etc.
628e3a5a
 
e12e9092
    Make tags:
550bb8c3
 
e12e9092
       o  make TAGS
550bb8c3
 
e12e9092
    Create a tar.gz with the sources (in ../):
247c2b65
 
e12e9092
       o  make tar
247c2b65
 
e12e9092
    Create a tar.gz with the binary distribution (in ../):
247c2b65
 
e12e9092
       o  make bin
247c2b65
 
e12e9092
    Create a gzipped solaris package (in ../):
247c2b65
 
e12e9092
       o  make sunpkg
247c2b65
 
e12e9092
    Create debian packages (in ../):
bc5cc4ec
 
e12e9092
       o  make deb
bc5cc4ec
 
e12e9092
    or
5b0cb4c6
 
e12e9092
       o  dpkg-buildpackage
5b0cb4c6
 
e12e9092
    Install:
5b0cb4c6
 
e12e9092
       o  make prefix=/usr/local  install
5b0cb4c6
 
e12e9092
    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).
550bb8c3
 
e12e9092
    For example, if you do the following:
550bb8c3
 
e12e9092
       $ make all
       $ make prefix=/ install
6de5485d
 
e12e9092
    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).
6de5485d
 
e12e9092
    Workaround is trivial, use the same parameters in all make commands:
6de5485d
 
e12e9092
       $ make prefix=/ all
       $ make prefix=/ install
6de5485d
 
e12e9092
    That applies to other make parameters as well (for example parameters
    "modules" or "excluded_modules").
cb7dae9d
 
 
b8bc4cf8
 3. Quick-Start Installation Guide
cb7dae9d
 
e12e9092
 3.1. Getting Help
b8bc4cf8
 
e12e9092
    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/
b8bc4cf8
 
e12e9092
    to learn how to configure SER for your site.
b8bc4cf8
 
e12e9092
    If the documentation does not resolve your problem you may try contacting
    our user forum by E-mail at serusers@iptel.org -- that is the mailing
    list of the ser community. To participate in the mailing list, subscribe
    at the following web address:
fd62444c
 
e12e9092
       http://mail.iptel.org/mailman/listinfo/serusers
b8bc4cf8
 
e12e9092
 
 3.2. Disclaimers
cb7dae9d
  
e12e9092
    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
5b0cb4c6
     
e12e9092
             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
5b0cb4c6
     
e12e9092
       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.
     
a02e3c46
       4. Register with the server using your favorite SIP User Agent.
e12e9092
          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.
 
a02e3c46
          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:
e12e9092
 
             $ 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.
 
a02e3c46
 	 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:john@example.com sip:john.doe@example.com
 	    $ 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.