Seas Module

SEAS module relies on the Transaction Module (TM module) for operation.

Using the SEAS module requires to have an Application Server running and connected to a particular instance of Kamailio.

At the moment, the only Application Server that works with SEAS is WeSIP Application Server, which can be downloaded from www.wesip.eu, and used freely for non-comercial purposes.

The listen_sockets string tells SEAS where to listen for incoming connections of Application Servers. It has the form: "ip:port". SEAS will open two server-sockets on that IP, at the specified port, and another at port+1. Application Servers must be configured to connect to that port.

In case this parameter is ommited, SEAS listens on the default IP which Kamailio is using, and opens the ports 5080 and 5081 to listen for Application Servers.

...
modparam("seas", "listen_sockets","127.0.0.1:5080")
...

Creates a new transaction (if it isn't already created) and sends the SIP Request and transaction information to the Application Server specified in the parameter. Every Application Server connected to Kamailio through the SEAS module, must be identified with a different name.

This function can be used within REQUEST_ROUTE.

...
if (!as_relay_t("app_server_1")) { 
log("Error sending to app server"); 
t_reply("500","App Server not connected"); 
}
...

SipServlets achieve the most of it when they can be deployed along with HttpServlets, in the same Application Server (also known as Servlet Container). This environment truly realizes the power of converged voice/data networks: Http protocol represents one of the most powerful data transmission protocols used in modern networks (think of the SOAP web-services protocol), and SIP is the protocol of choice in most of the modern and future voice over IP (VoIP) networks for the signaling part. So an Application Server capable of combining and leveraging the power of these two APIs will be the most successful.

Convergence of SIP and HTTP protocols into the same Application Server offers, amongst others, the following key advantages:

-It doesn’t require to have 2 different servers (Http and Sip) so it relieves from maintenance problems, and eases user and configuration provisioning.

-It offers great convenience to the application programmer to have all the classes related to the different protocols handled within the same code.

-As it eases development of interactive and multimedia services, realizing the power of well-known web-services and intermixing them with new voice services.

These are some simple, but suggestive examples of services that could be developed within a converged Http/Sip servlet:

-IP Centrex: through the use of the Web-interface, users could have a layout of the office in a web page, and see what phones were ringing at a given moment, so they could pick-up a call ringing in another phone in their own desktop. Or they could forward a call to another party by clicking on the web page and selecting which of the office phones it had to be transferred to.

-Voicemail: users could upload an audio file to the server through a web-page, to be used as the automatic answering message, and then also download their voicemail through the web-page, or organize the messages and remove the old ones.

-Instant Messaging: users could continue a voice call by starting or joining a new Instant Messaging session carried over a web-page.

-Click-to-dial: users could initiate SIP sessions only by clicking a link on a web page, without the need of the Web-Browser being SIP-aware nor needing even a SIP phone: the server could handle all the logic so the user who clicked could receive a call from the server’s SIP network.

The topmost element in the XML configuration file is the "server" which has 2 xml attributes, called "port" and "shutdown". The former specifies a port on which the WeSIP AS will listen for the shutdown command, and the latter is the magic word that will make the server shutdown.

<Server port="8005" shutdown="SHUTDOWN" >

if you send the magic word "SHUTDOWN" to the port 8005 of the localhost, the server will stop cleanly.

Nested within the Server element, must be a "Service" element, with an attribute called "name" which specifies the name for the service. This attribute is not very relevant, you can call it whatever you like.

Within the Service element must be two or more elements: the connectors and the engines. A connector is the instance that will receive messages from the network. You can specify HTTP connectors and/or SIP connectors. Every connector needs an attribute called "className" which specifies which class will be responsible for receiving the messages from the network. For HTTP connectors, the classname must be "org.apache.catalina.connector.http.HttpConnector" and for SIP connectors "com.voztele.sipservlet.connector.SipConnector".

The SIP Connector uses 4 attributes:

className="com.voztele.sipservlet.connector.SipConnector"

specifies the classname of the connector.

minProcessors="5"

specifies the minimum number of SIPprocessor instances (and threads in the pool) to process incoming SIP messages. More processors should allow more load to be processed. This is the minimum number of instances, even if they are spare and not working.

maxProcessors="10"

specifies the maximum number of SIP processors used (a negative value specifies that there is no limit).

addresses="localhost:5060"

Specifies the SIP address and port in which the Application Server from which the Application Server will process the SIP messages. This Addres is where Kamailio listens for the messages, so in fact, Kamailio is listening on them, but Kamailio passes the messages to WeSIP, so WeSIP must be aware of this IP/port.

listen = tcp:localhost:5060
listen = udp:localhost:5060

Within the SIP Connector element there must be an ExtraProperties element, containing nestes Property elements. Each property element specifies a parameter for the SIP Stack. Each property is specified by a key and a value. The most significant keys are:

The Engine must also be nested within the Server element, along with the Connectors. It must have a "name" attribute with whatever name you feel like. It needs to have another attribute called "defaultHost" which will be the default host to which to pass the incoming request (in HTTP/1.0 the requests dont have a Host header, so they will be passed to this default host, in SIP, this attribute doesn't have a meaning.). In order to have this Engine handling also SIP messages, the "className" attribute of the Engine must be "com.voztele.sipservlet.core.ConvergedEngine".

Within the Engine, there can be one or more Hosts, each one specified within a "Host" element nested in the engine.

A mapper is used to map an incoming request to one or another SIP or HTTP host. In case it is a SIP request, the mapping is done based on the sip.xml deployment descriptor rules. The classname of the SIP mapper MUST BE "com.voztele.sipservlet.core.EngineSipMapper". The "mapper" element must also have a "protocol" attribute, specifying which protocol this mapper handles. In case of the SIP mapper it must be "SIP/2.0". The HTTP mapper's classname must be "org.apache.catalina.core.StandardEngineMapper" and the protocol attribute "HTTP/1.1"

The authentication in HTTP is performed in Apache-Tomcat through Realms. The memory realm is (textual copy from the Apache-Tomcat javadoc"): "Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles."

The classname must be "org.apache.catalina.realm.MemoryRealm"

A "pathname" attribute can be specified to tell the Realm which file contains the usernames, passwords and roles. If not specified, it is "conf/wesip-users.xml"

A Host represents a VirtualHost in HTTP/1.1 servers, so the requests will be dispatched to one or another virtual host depending on the Host: header. In SIP this doesn't make much sense, because there's no such Host: header, and virtual hosting is not done in this way. Every host must have a "name" attribute which specifies the name of the virtual host, it must also have a "nameSip" attribute which MUST MATCH the IP or hostname _and_ port" specified in Kamailio listen parameters and in the Sip Connector the hostname and the port must be separated with an underscore. for example: nameSip="localhost_5060" or nameSip="192.168.1.1_5060" The next important attribute that must have the Host element is "appBase" which declares the directory where the WEB and SIP applications reside. It usually is a directory called apps in the directory from which the server runs. The attribute "unpackWARs" says the WeSIP Application Server to unpack the Web or Sip Application Archives (.war or .sar extensions) found inside the appBase directory. It should usually be set to "true". The "port" attribute specifies the port where this host is going to receive SIP messages . This only has to do with the SIP protocol, not with HTTP. It must be the same as the port specified in Kamailio parameter "listen_sockets" (for the seas module). The "autoDeploy" attribute tells the host to monitor the "appBase" directory for new application archives (.sar or .war) so they can automatically be deployed. This parameter should be set to "true". The "className" used for the Host _must_be_ "com.voztele.sipservlet.core.ConvergedHost"

Hosts must also have a nested Mapper element, but when the mapper is inside a Host (and not in an Engine) the classnames must be "com.voztele.sipservlet.core.SipHostMapper" for the "SIP/2.0" protocol and "org.apache.catalina.core.HttpHostMapper" for the "HTTP/1.1" protocol. (2 mappers must be nested inside the Host).

debug=3            # debug level (cmd line: -dddddddddd)
fork=yes
log_stderror=no    # (cmd line: -E)
check_via=no    # (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)
port=5060
children=4
loadmodule "/usr/local/lib/kamailio/modules/sl.so"
loadmodule "/usr/local/lib/kamailio/modules/tm.so"
loadmodule "/usr/local/lib/kamailio/modules/rr.so"
loadmodule "/usr/local/lib/kamailio/modules/maxfwd.so"
loadmodule "/usr/local/lib/kamailio/modules/usrloc.so"
loadmodule "/usr/local/lib/kamailio/modules/registrar.so"
loadmodule "/usr/local/lib/kamailio/modules/textops.so"
loadmodule "/usr/local/lib/kamailio/modules/seas.so"
loadmodule "/usr/local/lib/kamailio/modules/mi_fifo.so"

modparam("mi_fifo", "fifo_name", "/tmp/openser_fifo")
modparam("usrloc", "db_mode",   0)
modparam("rr", "enable_full_lr", 1)
modparam("seas", "listen_sockets", "127.0.0.1:5080");

route{
       if (!mf_process_maxfwd_header("10")) {
               sl_send_reply("483","Too Many Hops");
               exit;
       };
       if (msg:len >=  2048 ) {
               sl_send_reply("513", "Message too big");
               exit;
       };
       if (!method=="REGISTER")
               record_route();
       if (loose_route()) {
               append_hf("P-hint: rr-enforced\r\n");
               route(1);
       };
       if (uri==myself) {
               if (method=="REGISTER") {
                       save("location");
                       exit;
               };
               lookup("aliases");
               if (!uri==myself) {
                       append_hf("P-hint: outbound alias\r\n");
                       route(1);
               };
               if (!lookup("location")) {
                       sl_send_reply("404", "Not Found");
                       exit;
               };
               append_hf("P-hint: usrloc applied\r\n");
       };
       route(1);
}
route[1] {
                if(!as_relay_t("app_server_one")){
                       t_reply("500","Application Server error");
               }
}

debug=9            # debug level (cmd line: -dddddddddd)
fork=yes
log_stderror=yes    # (cmd line: -E)

check_via=no    # (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)
port=5060
children=4

reply_to_via=1
listen = tcp:localhost:5060 
listen = udp:localhost:5060 

mpath="/home/elias/src/sipservlet/seas"

loadmodule "modules/tm/tm.so"
loadmodule "modules/seas/seas.so"
loadmodule "modules/mi_fifo/mi_fifo.so"

modparam("mi_fifo", "fifo_name", "/tmp/openser_fifo")
modparam("seas", "listen_sockets","127.0.0.1:5080")

route{
                if(!as_relay_t("app_server_1")){
                        t_reply("500","Application Server error");
                }

}

<Server port="8005" shutdown="SHUTDOWN" debug="0">
  <Service name="WeSIP-Standalone">
    <Connector className="org.apache.catalina.connector.http.HttpConnector"
        port="8080" minProcessors="5" maxProcessors="75"
        enableLookups="true" address="localhost" acceptCount="10" debug="10" />
        <Connector className="com.voztele.sipservlet.connector.SipConnector"
        minProcessors="5" maxProcessors="75"
        addresses="localhost:5060" >
               <ExtraProperties>
                       <Property key="com.voztele.javax.sip.SER_ADDRESS" value="127.0.0.1:5080" />
                       <Property key="javax.sip.STACK_NAME" value="app_server_one" />
                       <Property key="com.voztele.javax.sip.THREAD_POOL_SIZE" value="10" />
               </ExtraProperties>
       </Connector>
    <Engine name="Standalone" defaultHost="localhost" debug="10"
       className="com.voztele.sipservlet.core.ConvergedEngine">

        <Logger className="org.apache.catalina.logger.SystemOutLogger"
           timestamp="true"/>
        <Mapper className="org.apache.catalina.core.StandardEngineMapper" protocol="HTTP/1.1"/>
        <Mapper className="com.voztele.sipservlet.core.EngineSipMapper" protocol="SIP/2.0"/>
        <Realm  className="org.apache.catalina.realm.MemoryRealm" />
        <Host name="localhost" nameSip="localhost_5060" debug="10" appBase="webapps" unpackWARs="true"
        port="5060" autoDeploy="true" className="com.voztele.sipservlet.core.ConvergedHost">
               <Mapper className="com.voztele.sipservlet.core.SipHostMapper" protocol="SIP/2.0"/>
               <Mapper className="org.apache.catalina.core.HttpHostMapper" protocol="HTTP/1.1"/>
     </Host>
  </Engine>
</Service>
</Server>

As the SIP URI is one of the most used types in a SIP message, a special structure has been defined to describe the contents of it. A URI is always included inside a SIP header, or may be in the first line of a SIP Request (as the request URI).

The codification of any URI is as follows:

Figure 2.5. SEAS-codification of a SIP URI (byte meanings are shown)

What follows is an example of a SIP URI codification with the SEAS protocol.

Figure 2.6. Example of a SEAS SIP URI codification

The first byte in the encoded-URI structure, gives the index where the URI starts, counting from the beginning of the SIP header where it appears. The next two bytes are flags indicating known fields present in the URI (such as port, host, user, etc.).

All the following bytes are uri-start based pointers to the fields that are present in the URI, as specified by the flags. They must appear in the same order shown in the flags, and only appear if the flag was set to 1.

The end of the field, will be the place where the following pointer points to, minus one (note that all the fields present in a URI are preceded by 1 character, ie sip[:user][:passwod][@host][:port][;param1=x][;param2=y][?hdr1=a][&hdr2=b]) it will also be necessary to have a pointer at the end, pointing two past the end of the URI, so that the length of the last header can be computed.

The reason to have the “other parameters” and headers flags at the beginning (just after the strictly URI stuff), is that it will be necessary to know the length of the parameters section and the headers section. The parameters can appear in an arbitrary order, they won't be following the convention of transport-ttl-user-method-maddr-lr, so we can't rely on the next pointer to compute the length of the previous pointer field, as the ttl parameter can appear before the transport parameter. So the parameter pointers must have 2 bytes: pointer+length.

To and From headers follow the same structure, so the same codification structure has been used to describe both. The structure is depicted in the drawing:

Figure 2.7. SEAS codification of From and To headers

The contact header is one of those SIP headers that can be combined, which means that if several headers of the same type are present in the message, they can be aggregated in a single header, having the header values separated by a comma. Thus, a single Contact header can contain more than one contact-value. For this reason, the Contact codification is composed of a several Contact codifications concatenated, and a byte at the beginning telling how much Contact codifications are present. The code is depicted in the following drawing:

Figure 2.8. SEAS codification of a Contact header

Both Route and Record-Route headers follow an identical structure, and it is also permitted to combine several headers into one, with their bodies (or header values) separated by commas. In this case, both kinds of headers follow the same structure, defined as follows:

Figure 2.9. SEAS codification of a Route Header

These two kinds of headers carry mime type and subtype definitions in the form “type/subtype” (ie. text/xml, application/sdp or whatever). For internal handling of this headers, SER codifies the known types and subtypes into a single 32 bit integer, with the highest two bytes giving the mime type, and the lowest two bytes giving the subtype.

The difference is that Accept header can also be combined, carrying more than one header value in a single header row. Thus the Accept header has a leading byte giving the number of mime type/subtype integers present, while the Content-Type only uses 4 bytes (a 32-bit integer) giving the type/subtype.

SIP has inherited the authentication scheme from HTTP, which is based on a digest scheme. There are several headers regarding these authorization scheme, namely Proxy-Authenticate, WWW-Authenticate, Authorization and Proxy-Authorization. All of them can be codified using the same schema, which is as follows:

Figure 2.10. SEAS codification of Authentication/Authorization headers

For each field present, there are 2 bytes, one pointing the place where it starts, the next giving how long this field is. The URI is a special case, and is composed of 1 byte telling how long is the URI structure, and then the encoded URI structure.

Allow headers carry request methods that a user agent or proxy understands or is willing to accept. In SER, request methods are codified into a 32-bit integer, each of its bits signals a different kind of header. The Allow header is codified copying that integer into the payload of the header.

The content-disposition is encoded within 2 bytes: the first is a header-start based pointer to where the content-disposition value starts, and the second is its length. If there are parameters present, each of them uses 1 byte pointing to where the parameter name starts, and 1 byte pointing to where the parameter value starts. From these two values, the parameter name and value lengths can be inferred.

The content length header is codified as a 4-byte unsigned integer, in network byte order.

The Cseq header is codified using 9 bytes. The first one is a number corresponding to the internal value that SER assigns to that request method (the method ID). The following 4 bytes are an unsigned 32-bit integer according to the Cseq number. The next two bytes are the header based pointer to the beginning of the Cseq number and its length, and two more bytes pointing to the beginning of the method name and its length.

The expires header is composed of 6 bytes. The first four bytes are an unsigned 32-bit integer with the parsed value of the header (which is the number of seconds before a request expires). Then follows 1 byte pointing to the beginning of the header value (the expires value as a string) and a byte giving the length of the value.