When did everything start?

History of OpenSER/SER starts back in 2001/2002, when Andrei Pelinescu-Oncliul started the project at Fraunhofer FOKUS Institute, Berlin, Germany. It was joined in short time by Bogdan-Andrei Iancu. The other core developers completed the team of five: Daniel-Constantin Mierla, Jan Janak and Jiri Kuthan. Since autum 2002 when the project was made open source under GPL, the five leaded the project till 2005, all of them being most of the time reasearchers at FhG FOKUS. The main rule of the project was that any contribuited code has to be reviewed by the developer who wrote the initial version to whom the code applies. The decisions about releases were taken upon agreement of all core developers.

SER became a powerful SIP server in a short time, contributors from outside of the institure joined very soon: Juha Heinanen, mainly with RADIUS and enum support, Maxim Sobolev and Adrian Georgescu with NAT traversal solutions, Elena-Ramona Modroiu with couple of handful modules.

In 2004 (my guess), iptelorg.com, a private company was founded with main focus on SER-based business. During 2004 and 2005, three core developers moved to iptelorg.com, one of them being co-founder of the company. The other two, continued with FhG FOKUS until few months before starting OpenSER in June 2005.

Design and versioning

As expected, the two SIP servers have same internal design: core and modules. The core includes key components like transport layer (UDP/TCP/TLS server, SIP parser, database abstract interface). The modules implements the features-side of the server: authentication, authorization and accounting, user location and registrar, transaction support and many others you will discover in this document.

Versioning uses three numbers X.Y.Z. X denotes the version and it is increased when architectural changes were introduced. In OpenSER case X was kept to 0 until the 'MUST' requirements of RFC3261 were completed. Y is the major revision and it is increased when new features are introduced in stable version. Z is the minor revision and denotes fixes to a major revision.

Although some people try to suggest that by its release policy, OpenSER is very likely to be not very stable, the time proved the contrary. OpenSER release policy has a clear schedule and very good reasons. Each cycle starts with 5-6 months of development. Then follows a period of 1-2 months with code frozen and heavy testing. Afterwards is the time for packaging and new major release. The reason of doing often releases, but still ensure the stability, is to allow the administrators of OpenSER-based platform to migrate easily to new versions. By letting the development to last for ages the acumulated code will be hard to be tested thoroughly and the amount of changes will make the upgrade process very tough.

This kind of release policy is adopted by other major player in the VoIP area, namely Asterisk.

OpenSER 0.9.4

This is the first official release of the SIP server under name 'OpenSER', on the 14th of June, 2005. A snapshot of SER branch rel_0_9_0 was taken, the code was tested, some new features from unstable version were backported, the documentation for modules was completely updated.

The new modules introduced are:

• alias_db - simple alias management with database storage only.

• avpops - powerful module that allow complex operations. It introduced the first implementation for variable-like support in configuration file.

• dispatcher - load balancing using hash algorithms over parts if SIP requests

• lcr - least cost routing module - backport in 0.9.5

• speeddial - server side short dialing

About one month later, SER released 0.9.3 as new stable version, basically using the code tested and prepared during spring by the team members which started OpenSER.

OpenSER 1.0.0

The big step to versiong '1' was acomplished by adding support for TLS - the last big requirement of RFC3261. OpenSER became the first open source SIP server which had TLS support, on the 10th of October 2005. These release introduced for the first time the idea of pseudo-variables, unifying the concept of AVP and references to parts of SIP messages. Several months after, similar concept was adopted in SER under the name 'select'.

There were lot of improvements to 'avpops' module which allowed many arithmetic and string operations. 'exit' and 'return' statements were introduced in config along with 'switch' and return code. The configuration script got more functions to manage the destionation address (outboud address), accounting added support for multi-leg calls (one record per leg, when server has to deal with call forwarding), nathelper became capable of sending SIP OPTIONS requests to keep the pinhole open in the NAT.

The new modules introduced are:

• uac - user agent client functionalities: anonymization and authentication done by server.

• uac_redirect - user agent client behavior for handling 3XX redirect replies.

OpenSER 1.1.0

Launched on the 10th of July, 2006, this release confirmed the maturity of TLS and pseudo-variables concept. It introduces many new modules and features in OpenSER, being another big step further. The core got support for serial forking and DNS NAPTR for service discovery. OpenSERCtl script got significat refurbishing, with new modular concept. A new designed 'statistics' support allow admins to watch the internal state of OpenSER. AVPOPS module introduced unified notation for pseudo-variables along with avp_sb_query() which allow to execute any SQL statement and load the result in AVPs.

Other major achievement with this release was the addoption of OpenSER in official Debian distributions (unstable and testing). Just for the records, at that time SER was not yet included in Debian. The project may have been considered young by some people, but it has inherited the history of SER and it has accumulated during the first year of activity over 60 contributors. The activity on mailing lists and forums was reflecting a comunity of over 1000 members.

The new modules introduced are:

• dialog - call stateful support.

• osp - mutilateral peering support with OSP.

• path - PATH extension support (RFC3327).

• siptrace - ability to log SIP traffic to meet legal requirements.

• statistics - added support for user defined statistics in configuartion script.

• unixodbc - database conectivity module based on uniodbc library.

How to use this guide

This guide is in four parts. Part I is an introduction. It discusses core concepts around OpenSER and its operation. It informs you about the modules that are distributed with OpenSER, and discusses briefly the protocols and technology that OpenSER works with.

Part II is the tutorial. It provides fully working and tested configuration files, and walks you through them, line by line. It puts the statements in context and explains why they operate the way they do. It goes on to discuss how and why you would want to emply that functionality. Starting with a very simple configuration file of a basic proxy, it adds in more and more features, and leaves the reader (hopefully), with a decent grounding in how get all the basic things working in OpenSER

Part III concerns itself with some advanced topics. Including Security, performance, and scalability, it discusses key issues about how to get OpenSER to do what you want it to do, but in a production environment. It points you in the right direction for questions you might have about more advanced features, and hopefully leaves the reader with a decent picture of what is capable with OpenSER.

The fourth and final part is a catalogue of reference information, helping you with third part application configuration, providng SIP call-flow examples, and generally is a place to put all associated information that I couldnt or wouldnt put into the main guide!

reference sections for installation, what to do first, how to read the guide, where to get latest version etc

RTP

RTp uses UDP for transport over IP. This means it uses a connection-less method of communication, which is great for getting as much data transmitted to the destination as soona s possible, but does not offer any guarantee of delivery as its major drawback. RTP compensates for this defficiency in two ways:

Firstly, it issues a sequence numbers to its packets, along with a timestamp and allows for synhronisation. It also employs the use of RTCP (RTP Control Protocol), which is designed to provide fault diagnosis, quality monitoring, and other useful information that allows SIP UA's to more accurately determine the validity of the information it is recieving.

RTP provides transport for a variety of media, but audio and viedo remain the most common.

SDP

SDP stands for Session Description Protocol, and it is used to handle the session negotiation process within a SIP transaction. an SDP packet is often carried as the message body of a SIP request. This is exemplified in section x.x

As part of a session (SIP) INVITE, an SDP offer is made, detailing a number of characteristics that define the proposed session. The response to this (via SIP, from the UAS), acknowledges acceptance, or offers alternative session parameters, or declines the proposed session with no alternatives offered.

SIP User Agents (UA's)

These are the endpoints in a SIP network, and each UA can be divided into two sub-components:

• User Agent Client (UAC): This entitiy initiaites requests. Imagine picking up your SIP phone to make a call. It is the UAC that makes the request to the SIP server (or sometimes directly to another UA), in order to try and establish a session.

• User Agent Server (UAS): This element of a UA is the one which generates responses to requests it has recieved. It is this part of your SIP phone that will play a ring-tone to notify you that another UA wishes to establish a session.

SIP Servers

There are three core pieces of functionality, defined within SIP RFC 3261, which are performed by SIP Servers. One or more (or all) can be performed by the same application or device, and this is exactly what OpenSER is capable of. Thes types of server, are:

• Registrar Sever: This server takes registration requests from UA's, and maintains information as to their location.

• Location Sever: This server replaces the user's AoR (Address of Record) with the contact address registered by user. This entity is complementary to Registrar Server

• Proxy Server: A SIP proxy recieves SIP messages (both requests and responses), that are gerneated by UA's, and forwards them on (either to the destination UA, or the next SIP Server in the route, as specified in the SIP message itself).

• Redirect Server: This conceptual SIP network entity recieves requests from a proxy or UA, and responds with a specific SIP response method, telling the originator of the request that the user is not available at that location, and indicates where the request should be sent in order to try again.

• Application Sever: this is the place were differet features are implemented, adding value to the VoIP platform. Among common features you can find advanced call control applications like call blocking or call baring, prepaid system, interactive call routing.

Media Servers (non-SIP)

It is worth noting that everything we have convered up to this point does not allow for many of the traditional functions we assoaciate with a telephone service. What about IVR's, or Voicemail? Where are the auto-attendants, and the music on hold features? Well this is where a media server comes in.

In order to have an active control of what happens during a call, a device has to be 'in the media stream', as it is often called. This means a separate network device has to act as a SIP UA in order to begin a session, and then can control the channel accordingly. This is how voicemail and many other features of its ilk operate.

REGISTER

The REGISTER method in SIP, is a request that initiates a transaction with a regsitrar server, in the manner depicted below:

This demonstrates the function of the registrar entity in simple terms. The UA informs the registrar of its location, allowing the server to maintain a record (valid for a pre-determined duration) of which IP address matches that SIP URI (Uniform Resource Indicator). In a more practical model additional information would be exchanged, for purposes like authentication.

INVITE

An INVITE is a SIP request method a UA would use to initiaite a session with another party. A simple example is shown below:

This demonstrates the initial message; the INVITE, being sent in an end-to-end model. The recieving UA reacts to the INVITE by sending a '180 Ringing'. This means it is responding with a specific SIP response code, as detailed in the SIP RFC (response code 180). The text attached to that response code is arbitrary, but often identical across platforms and implementations.

Once the use picks up the handset (i.e. accepts the call), a response with the code '200' is sent. This is always used as an 'OK' when used in response to a SIP request, and means that the request has been accepted.

The arrival of this 'OK' message from the callee is confirmed by the caller, by the use of another SIP request method; an ACK, and the media session can begin.

We left out all security, encryption, routing, timeouts, and the hundreds of other possiblities that can cause a SIP INVITE transaction to differ from this model, but as a bare minimum, all SIP sessions will have this as a minimum INVITE transaction to set up a session.

Session initiation with OpenSER

We've seen an example of the fact that SIP can operate in an end-to-end fashion, but where does OpenSER fit into this picture? An example of the same basic INVITE transaction is show below, but this time using OpenSER as a stateless proxy. Dont worry if you dont know what stateless refers to in this context, we'll explain later.

As you can see, a SIP proxy does not need to understand a SIP message in order to operate; it merely forwards them on. Typically a proxy will perform some kind of authentication, and can be separated, locically, from a UA, in three ways:

1. It never issues requests (for those taking note, the CANCEL method is the exception to this rule)

2. It has nothing to do with the media

3. It only operates on message headers, and does not concern itself with message bodies

A stateless proxy does not implement any timers, nor will it re-transmit any messages that have not had a response. A stateless proxy wont even keep track of a SIP transaction. It is perfectly happy to be removed from the chain of communications when it offers no additional value to the process, as identified here with the end-to-end transmission of the ACK

The consequences of this mean that if you want to offer VoIP services such as presence, music on hold, serial or parallel forking, or the many other things OpenSER is capable of, then we have to operate in a stateful way. A stateful transaction can be demonstrated by altering the previous example to the image show below:

Not only does the ACK now route via OpenSER, but furthermore, through use of the Record-Route header, all future SIP messagess will go via the server. This allows OpenSER to provide useful features, such as being able to tell whether a request was answered or not, or being able to fork two requests from one invite, responding accordingly and separately to each individual response.

Okay, so what is all this talk about 'transactions' and 'dialog's'? And when we say something is 'stateful', do we mean 'transactionally stateful' or 'dialog stateful'? Well its an important concept in SIP.

A transaction starts with a SIP request (such as an INVITE), and ends with a 'final response', which can be one of a variety of SIP responses. In between a request and its final response, there can be a number of provisional responses (or none).

A dialog can be thought of as a sequence of transactions. it is representative of a sip relationship between two end-points, and it is common to think of a regular phone call, from the moment you dial the number, to the moment one party hangs up, as a dialog.

OpenSER is a transaction satateful proxy. It is not dialogue stateful. Therefore it cannot, in its native state, know when a particular session has been terminated.

Network Address Translation (NAT) and SIP

Network Address Translators modify the IP address and port information for packets traversing from one network to another. In its most typical incarnation, this is to used to manage private network ranges, and allow them to interract with publicly routed networks.

There are several 'points of impact' where SIP finds NAT problematic, and it is not merely limited to NAT. RTP also has problems with NAT. Because SIP packets go out from a NATed client with their private (and un-routable) IP addresses coded into the message headers and SDP bodies, they are not processed by a NAT device, that operates only on the IP packets as they pass by. This then means that when the packets get to their destination, they are processed and responded to using completley useless source address information.

3 major implications of NAT

1. The VIA header problem: Responses to requests cannot he be routed back ot the originating party, as the supplied addressing information is not globally routable.

2. The CONTACT header problem: This refers to the fact that future requests would be routed incorrectly, again due to non-routable addresses being supplied.

3. The RTP problem: When the globally routable UA sends RTP traffic to a NATed UA that it has established a session with, the RTP traffic will never arrive. this is also known as The one-way audio problem.

There are several solutions to choose from to allow SIP to traverse NAT effectively. None of them is ideal, and much of it is external to SIP. The following sections refers to the three main problems caused by SIP (listed above), and discusses the techniques applied within the protocol, and common third party solutions, to the problems.

Authentication

This operates using MD5 hashing algorithms on a shared key, which is supplied via the challange/response mechanism required for authentication in SIP and OpenSER.

A request is challanged using SIP methods 401 or 407 (Authentication Required, and Proxy AUthentication Required, respectively). The request is then re-tried using the correct credentials. SIP UA's often cache the credtials required in order to avoid the overhead of further challange/response exchanges for future requests.

The call flow example below demonstrates OpenSER providing an authentication challenge for a UA transmitting an INVITE.

Encryption

As SIP is a text-based protocol, encryption prevents information contained in SIP messages being read by parties not involved in the SIP dialog. Transmission Transport Layer Security (TLS), and IP Security Protocol (IPSec) are methods of achieving a completely secure medium between two SIP endpoints involved in a dialog. SIP is encapsulated in IPSec tunnels, and the use of TLS has been extensively integrated into OpenSER's capabilities.

The message body of a SIP message may also be encrypted, allowing for security of all but the SIP message headers. This offers flexibility as the SIP message can traverse any standard proxy and the message will be correctly processed and routed, as a proxy will never need to analyse the message body.

Core logging in OpenSER

OpenSER, by default, logs to syslog. Alternatively, it can write log and debug information to STDERR. You can also alter the verbosity of openser's logging, and this can all be defined within the openser.cfg file, or at startup on the command line. The following table summarises these commands:

Some people set up their configuration files so that they can easily swap between development and production verbosity, as shown below. Note that as STDERR is commonly piped to the console from which the program was originally executed, that it is important the OpenSER is not allowed to fork when executed, to ensure all the program output is retained for troubleshooting.

debug=3
fork=yes
log_stderror=no

/* Comment out the above lines, and uncomment the three lines below to enter debugging mode
debug=7
fork=no
log_stderror=yes
*/

You might also find that it is useful, in development systems, to prevent openser performing DNS and reverse DNS lookups. This can be set upon execution or within the openser.cfg

dns=no          # (cmd. line equiv: -r) - default is "no"
rev_dns=no      # (cmd. line equiv: -R) - default is "no"

You can also create custom syslog setup's, with output going to separate files which can then be managed using log rotation software.

Logging Modules to use with OpenSER

Okay so you have a way for OpenSER to pipe out its own information to you, but what if it doesnt tell you what you need to know? Quite often, you will want to know about a specific transaction that is being processed, or you might want to know about the execution of a particular function you have.

OpenSER's 'xlog' module offers you the ability to output messages (to syslog or STDERR, as defined above). Moreover, it can also output the values of any 'pseudo-variables' that OpenSER has set. You can enter lines, such as the one below, into your openser.cfg at any point.

xlog("L_INFO", "SIP Request: method [$rm] from [$fu] to [$tu]\n");

.. which in turn will produce output specific to the particular SIP message OpenSER is currently processing, so you could expect to see something like:

SIP Request: method [INVITE] from [me@mydomain.com] to [you@yourdomain.com]