$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 serusers@iptel.org -- that is the mailing
   list of the ser community. To participate in the mailing list, subscribe
   at the following web address:

      http://mail.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: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.