1. Introduction

1.1 Revision

� Version 0.1 12/02/2002

1.2 Why SER

SER is an open-source project that aims to make available a fully functional and scalable Session Initiated Protocol suite.� Call processing is described with a concise scripting language that offers the flexibility of regular expressions and the ability to interface with 3^rd party applications for the purposes of call accounting and authorization.

1.3 Where to get SER

SER is available for download from ftp://ftp.berlios.de/pub/ser

The newest release may be found in the folder /latest

1.4 Installation

Installing SER on a RedHat Linux distribution is a simple matter of unzipping the downloaded file and using your favorite package manager.

Example /root>rpm �i ser-08.10-2.i386.rpm

You can start the service with /etc/rc.d/init.d/ser start

You now have a functioning SIP server, but what can you do with it?� At this point not very much.� With an SIP client, such as Microsoft MSN Messenger 4.6, you can register with the server, send Instant Messages to other logged on clients of the same server, and even have voice conversations with them.�

That sounds pretty good, but maybe you�d like to add a little more security, or make you server accessible to others.

1.4.1 �DNS SVR Resource Records

It is important that your SIP clients can connect to your server for purposes of registration and call control.� You might even want to have a redundant server to handle calls if your primary server is unavailable.

These requirements can be meet by using DNS SVR Resource Records, available in BIND 8.X and up releases.

The format for a SVR RR is this:

�� _service._protocol�� SVR Priority Weight�� Port hostname

In this case we want to establish an entry for our primary SIP server, gateway.mydomain.com, that will listen on UDP port 5060.� The entry will look like this:

�� _sip._udp�� SRV�� 0 �0�� 5060� gateway.mydomain.com

After reloading your zone file you can verify that the entry is working by using dig.

�� dig �t SRV _sip._udp.mydomain.com

The results should look something like this:

; <<>> DiG 9.1.0 <<>> -t SRV _sip._udp.mydomain.com

;; global options:� printcmd

;; Got answer:

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32654

;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 2, ADDITIONAL: 1

;; QUESTION SECTION:

;_sip._udp.mydomain.com.�� IN�� SRV

;; ANSWER SECTION:

_sip._udp.mydomain.com.�� 86400�� IN�� SRV�� 0 0 5060 gateway.mydomain.com.

;; AUTHORITY SECTION:

mydomain.com.�� 86400�� IN�� NS�� ns3.elsewhere.com.

mydomain..com�� 86400�� IN�� NS�� gateway. mydomain.com.

;; ADDITIONAL SECTION:

gateway. mydomain.com.�� 86400�� IN�� A�� 192.168.0.150

;; Query time: 6 msec

;; SERVER: 192.168.0.150#53(192.168.0.150)

;; WHEN: Tue Dec� 3 08:34:17 2002

;; MSG SIZE� rcvd: 132

1.4.2 Adding a database for client information

By leveraging a MySQL database, we can provide support for user credentials, and keeping track of where the clients are logged on during server restarts.

1.4.2.1 MySQL setup

The package you downloaded has scripts to create the required database and establish permissions for the accounts need.� A recent release of MySQL is recommended.� Earlier versions may have problems with the syntax required to set permissions on the database.

If you do not already have a copy of MySQL installed, download it from your http://www.mysql.com

Once you have MySQL installed and started, execute /usr/sbin/ser_mysql.sh.

You can verify that the database has been created, and correct permissions assigned by using the mysql management tool and these steps:

Mysql> select * from user;

| %�� | ser�� | 4e633cf914a735a0 | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� |

| localhost�� | ser�� | 4e633cf914a735a0 | Y�� | Y�� | Y�� | Y�� | Y�� | Y�� | Y�� | Y�� | Y�� | Y�� | N�� | Y�� | Y�� | Y�� |

| %�� | serro | 7cb73a267cb7bd5f | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N� ��| N�� | N�� | N�� |

| localhost�� | serro | 7cb73a267cb7bd5f | Y�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� | N�� |

The above results show that the two user, ser and serro, have been created and granted the permissions needed to access the database.� Note that in the above example the permissions have been modified to deny access to these accounts from any system(%) other than local host.

mysql> connect ser;

Connection id:�� 294

Current database: ser

mysql> show tables;

+-----------------+

| Tables_in_ser�� |

+-----------------+

| acc� �� |

| active_sessions |

| aliases� �� |

| config�� |

| event�� |

| grp�� |

| location�� |

| missed_calls�� |

| pending�� |

| phonebook�� |

| reserved�� |

| silo�� |

| subscriber�� |

| version�� |

+-----------------+

14 rows in set (0.00 sec)

mysql> select * from subscriber;

This last query shows that you have one user account defined and it has administrator privileges.

We�ll need to add another account to be the administrator for your realm, which we will do after the next section.

1.4.2.2 Modify SER configuration

Now that we have a working MySQL database, we need to modify the configuration file for ser, located on a RedHat 7.X install in /etc/ser.� The following changes need to be made.

Uncomment this line:� loadmodule "//usr/lib/ser/modules/mysql.so

Comment this line:� modparam("usrloc", "db_mode",�� 0)

Uncomment this line:� modparam("usrloc", "db_mode", 2)

Uncomment this line:� modparam("auth", "calculate_ha1", yes)

Uncomment this line: modparam("auth", "password_column", "password")

Change (uri==�myself�) to (uri=~�mydomain.com�)

Uncomment these lines and change all instances of iptel.org to mydomain.com

�� if (!www_authorize("mydomain.com", "subscriber")) {

�� www_challenge("mydomain.com", "0");

�� break;

�� };

We�re now ready to restart ser.� On RedHat use /etc/rc.d/init.d/ser restart

1.4.2.3 Adding an admin for your realm

Now that we have a working database and ser is configured to use it, we need to add some users and at least one of them should have administrator privileges.� The administrator role becomes important if you want to use a web management tool such as serweb.

Basic account manipulation can be performed with the serctl script, located in /usr/local/sbin.

To add a user use these commands

serctl add JoeUser qwerty joe@mydomain.com

To make JoeUser an administrator, we need to logon to MySQL and modify the database.

mysql> connect ser;

mysql> update subscriber set perms=�admin� where USER_ID=�JoeUser�;

Query OK, 1 row affected (0.00 sec)

Rows matched: 1� Changed: 1� Warnings: 0

mysql> select * from subscriber;

| 4cefa7a4d3c8c2dbf6328520bd873a19 | JoeUser�� | qwerty |� |�� |�� | joe@mydomain.com�� | 2002-12-02 19:20:41 | 2002-12-02 20:29:46 | 80e0f273b2067d40277b49ff842bb9e3 | o�� |�� |�� | c79a8f8f08596baa84bb02c88884426d | mydomain.com | f322c94b8b2fbe557d43ab3ac9e05b3a | admin | 1�� | America/Los_Angeles |

The third from last field shows that Joe has been assigned admin privileges.

At this point Joe can logon to our server, but since he is the only user, there is not much he can do.� We can now add additional users using the serctl script, or now is a good time to look at installing serweb, which will allow users to subscribe to our service.

1.5 Installing SERweb

The SERWeb package can be downloaded from ftp://ftp.berlios.de/ser/latest/serweb

The pages associated with SERweb provide a starting point to customize your SIP user account management tools.

1.5.1 Installing SERweb

1.5.1.1 Installing SERweb default configuration

If you are installing this package on a server that does not host any other web pages, you can simply extract the files to the document directory of your web server.� This presumes that you have a working webserver.�

1.5.1.2 Installing SERweb custom file locations

In case your server performs multiple functions, and you want to just add the SERWeb tools to an existing web site, we will need to make changes to a number of the php files.� The following examples are from an Apache 2.0 on RedHat.

Unzip the files into a temporary directory, such as /root/serweb.� The directory will contain these files:

-rw-rw-r--�� 1 827�� 2020�� 18561 Sep 25 16:31 COPYING

drwxr-xr-x�� 2 827�� 2020�� 1024 Nov 27 16:43 CVS

-rw-rw-r--�� 1 827�� 2020�� 529 Sep 25 16:29 README

drwxr-xr-x�� 7 827�� 2020�� 1024 Nov 27 22:24 html

drwxr-xr-x�� 3 827�� 2020�� 2048 Sep 26 10:26 phplib

Move the html directory to the root of your web server:

mv html /usr/local/apache/htdocs/serweb

Move the phplib directory to your web server application directory:

Mv phplib /usr/local/apache/phplib

These files need to have the path to the libraries updated:

./admin/prepend.php

./user_interface/prepend.php

./user_interface/reg/prepend.php

For these files the variable: $_PHPLIB["libdir"]� = "../../phplib/"; becomes $_PHPLIB["libdir"]� = "../../../phplib/";

In the ./admin directory the files acl.php, index.php, and users.php will need their path to the forms library updated.� For this example, add ../ to the existing line

:require "../../../phplib/oohforms.inc";

In the ./user_interface directory the following files need the same change:

accounting.php find_user.php�� index.php�� missed_calls.php

my_account.php�� phonebook.php�� send_im.php

notification_subscription.php

Next these files in ./user_interface/reg need the same change, with an additional ../:

Finish.php�� get_pass.php�� index.php

The last changes occur in the config.php file to provide the location for graphic files, style sheets and time zone information.� Update the following variables:

$this->root_path="/serweb/";

�� $this->img_src_path =�� $this->root_path."img/";

�� $this->js_src_path =�� $this->root_path."styles/";

�� $this->style_src_path = $this->root_path."styles/";

�� $this->zonetab_file =�� "/usr/share/zoneinfo/zone.tab";��

//TZ zone descriptions file, usually: /usr/share/zoneinfo/zone.tab

1.5.2 Modifying SERweb configuration general

We need to update /usr/local/apache/htdocs/serweb/config.php to represent our realm.� The following variables need to be changed to our domain:

�� $this->realm="mydomain.com";

�� $this->domainname=" mydomain.com";

�� $this->web_contact="sip:JoeUser@ mydomain.com";

//address of pseudo sender

�� $this->default_domain=" mydomain.com";

�� $this->mail_header_from="Registration@ mydomain.com";

Additionally we will want to modify the section for Terms and Conditions, either replacing it with appropriate language for our services, or at least replacing iptel.org with our domain information.

1.6 Diagnostics and tools

Detailed information about the communications between clients and the SIP server is needed to isolate problems.� Two tools that can be used to gather such information are sipsak and ngrep.

1.6.1 Ngrep

Ngrep is a capable of listening in on network traffic and filtering it in much the same way as grep can locate patterns in files.� To monitor the communications between a client, joe, and the server the following command would be run on the server:

ngrep� -n 5060 �d eth0 joe

Since SIP communications are ASCII based, all events such as REGISTER, INVITE, SUBSCRIBE, etc. are captured.� The output of ngrep can identify problems with SIP addresses, or client identity.

Ngrep should be part of most modern distributions, or can be downloaded from http://sourceforge.net/projects/ngrep/

1.6.2 Sipsak

Sipsak can be used to determine if your server is responding to requests, and provide information on how your server would route SIP connections.� Sipsak and basic documentation on its use can be downloaded from http://sipsak.berlios.de�