Table of Contents
SER is built around a processing core that receives SIP messages and enables the basic functionality of handling SIP messages. Most of SERs functionality is offered through its modules, much like the Apache web server. By having a modular architecture, SER is able to have a core that is very small, fast, and stable. SER modules expose functionality that can be utilized in the SER configuration file, ser.cfg. The ser.cfg configuration file controls which modules shall be loaded and defines how the modules shall behave by setting module variables. You can think of the ser.cfg file as the brains of the SIP router.
ser.cfg has seven main logical sections:
Global Definitions Section. This portion of ser.cfg usually contains the IP address and port to listen on, debug level, etc. Settings in this section affect the SER daemon itself;
Modules Section. This section contains a list of external libraries that are needed to expose functionality not provided by the core as noted above. These modules are shared object .so files and are loaded with the loadmodule command;
Module Configuration Section. Many of the external libraries specified in the Modules Section need to have parameters set for the module to function properly. These module parameters are set by use of the modparam command, which takes this form: modparam(module_name, module_parameter, parameter_value)
Main Route Block. The main route block is analogous to a C programs main function. This is the entry point of processing a SIP message and controls how each received message is handled;
Secondary Route Blocks. In addition to the main route block, ser.cfg may contain additional route blocks that can be called from the main route block or from other secondary route blocks. A secondary route block is analogous to a subroutine;
Reply Route Block. Optional reply route blocks may be utilized to handle replies to SIP messages. Most often these are OK messages;
Failure Route Block. Optional failure route blocks may be used when special processing is needed to handle failure conditions such as a busy or timeout;
It is important to understand the SIP protocol and the various types of messages that are used in SIP signalling. Of course, by following the instructions in this document, you will get a working setup. However, before starting to tweak and adapt to your needs, we recommend that you do yourself a favour and read up on SIP. Please refer to http://www.iptel.org/ser/doc/sip_intro/sip_introduction.html as a good introduction. http://www.iptel.org/sip/siptutorial.pdf provides more depth. The official SIP RFC can be found at http://www.ietf.org/rfc/rfc3261.txt for those interested.
In order to understand ser.cfg properly, you need to understand three SIP concepts:
SIP transaction: A SIP message (and any resends) and its direct (most often immediate) response (ex. User agent sends REGISTER to SER and receives OK);
SIP dialog: A relationship between (at least) two SIP phones that exists for some time (ex. Dialog is established with an INVITE message and ended by a BYE message);
Session: An actual media stream of audio between the SIP phones;
These concepts are hard to understand and you may want to revisit this section when you have read later sections or studied the ser.cfg in this document. The concepts are used in the sections below to explain some things commonly confused.
NOTE: If you look at a SIP message, you can identify messages in a particular SIP transaction by looking at the Cseq number in the header. Each SIP dialog will have a Call-Id header (as well as one ID called a tag for each peer in the dialog)
You can think of ser.cfg as a script that is executed every time a new SIP message is received. For example, a user agent (UA) (Johns SIP phone) wanting to INVITE another UA (Joans SIP phone) to a conversation (John makes a call to Joan). John sends an INVITE SIP message to SER and ser.cfgs main route{} block will start at the top and execute through the commands found there.
The processing continues until it reaches a point where processing is finished and a decision is made whether to send the INVITE to Joan (using the t_relay() command), to send John a reply with an error (using sl_send_reply()), or just drop the whole INVITE (by reaching the end of the main route or break;), which, of course, is not recommended.
Joan will answer the INVITE with an OK message. The OK is a direct response to the initial INVITE and this message is handled by the last section in an on_reply_route[x]. If Joan didnt respond, or responded with an error (busy, etc), the failure_route[x] is called.
Finally, John will send an ACK to tell Joan that everything was received and accepted.
NOTE 1: The described behaviour is dependent on using t_relay() in ser.cfg. Your SER is then said to be transaction stateful (see also next section)
NOTE 2: An INVITE dialogue also includes provisional responses (trying, your call is important to us) before the OK, but we will not concern ourselves with these for simplicity.
So, how is all this handled in ser.cfg? All SIP messages starting a new SIP transaction will enter the top of the main route{}. In the above, Johns INVITE starts a transaction that is answered with OK from Joan.
You have a lot of freedom in how SIP messages are handled in ser.cfg. For example, to record that Joan is online, you use the save(location) function for all REGISTER messages from Joans IP phone. A call to lookup(location) will retrieve where Joans IP phone can be found so that that a call can be made. Also, very limited info about Joans phone can be stored in the form of flags using the setflags() function. (From version 0.9.0 there is also support for attribute-value pairs that can be loaded/stored for a given subscriber, but more on this later).
The consequence of ser.cfg as a routing logic script is that you have to make sure that each SIP message type is handled correctly (flows through the script in a correct fashion) and that each possible response in a transaction is appropriately handled by reply or failure routes to realize what you want (forward on busy etc). This can be quite complex and opens up for many possible errors. Especially when changes to ser.cfg easily affect more than the messages you intended to target. This is usually the root cause of SER administrators that question whether SER is RFC3261 compliant or not. SER is RFC3261 compliant from point of view of can it properly process any particular SIP message, however any seemingly harmless error in ser.cfg can have dramatic impact on the SIP router and cause SER to deviate from RFC3261 compliance.
This document presents a reference design with a corresponding ser.cfg to enable you to quickly set up SER to do what most people would like SER to do.