sipwise
/
sems
mirror of https://github.com/sipwise/sems.git
1
0
Fork 0
Code Issues Releases Wiki Activity

- added some tutorials on how to get started

Browse Source 
- updated contributions licensing policy


git-svn-id: http://svn.berlios.de/svnroot/repos/sems/trunk@1658 8eb893ce-cfd4-0310-b710-fb5ebe64c474
sayer/1.4-spce2.6
Stefan Sayer 17 years ago
parent dc58254f33
commit 7618e7e779
5 changed files with 430 additions and 0 deletions
Show Stats Download Patch File Download Diff File

4
doc/COPYING
Unescape View File

@ -27,6 +27,10 @@ IMPORTANT NOTES
but the SEMS software is copyrighted by FhG, IPTEGO GmbH and portions by
its contributors.
5) Contributions to the core and existing modules are required
to have the copyright signed over to the copyright holder of the
core or the respective module, or alternatively license modifications
under the Simplified BSD License.
-------------------------------------------------------------------------

177
doc/doc_howtostart_noproxy.h
Unescape View File

@ -0,0 +1,177 @@
/*! \page howtostart_noproxy How to try out SEMS without setting up a proxy
\section Introduction
<p>
This text describes how one can try out services in SEMS without
setting up a proxy. This is the simplest way to try services in SEMS,
or start with developing a service.
</p>
<p>
The way this works is that SEMS registers to a SIP server (registrar) with one account (bob),
just like any other SIP phone, and we call SEMS from another account (alice). If the
SIP server provides DID calling from the PSTN, we can use any landline or mobile
phone for testing or using the service.
</p>
\note What is not possible with this method is to use applications, which need
additional information for a call, from the subscriber data. For example,
in order to send a voicemail as email, the SEMS server needs the email
address to send the mail to.
\section Requirements
For compiling SEMS, as a minimum a C++ compiler and make is needed. In debian,
do \code apt-get install g++ make \endcode
\subsection publicsip With a public SIP server
Two accounts at a public SIP server are needed.
We recommend to use iptel.org's SIP service for testing, an account
can be registered for free at <a href="http://iptel.org/service/">http://iptel.org/service/</a>.
Any SIP phone, hardphone or softphone, can be used for testing. Cross-platform,
<a href="http://www.sip-communicator.org">sip-communicator</a> is recommended, for Linux
<a href="http://twinklephone.com">twinkle</a>, for Windows sip-communicator,
xten eyebeam or NCH express.
\subsection pstnsip With a PSTN DID provider
Alternatively a PSTN DID provider can be used. In that case, we can test and use the
service with any phone. A list of DID providers is for example available at
<a href="http://www.voip-info.org/wiki/view/DID+Service+Providers">voip-info</a> .
<a href="http://sipgate.de">Sipgate</a> for example, provides free DID numbers in
Germany.
\section Installing Installing SEMS from source
First, the SEMS source is downloaded from iptel.org and extracted:
\code
$ wget ftp.iptel.org/pub/sems/sems-latest.tar.gz
$ tar xzvf sems-latest.tar.gz
\endcode
SEMS is compiled:
\code
$ cd sems-x.y.z/
$ make
\endcode
\note Compilation may fail for some modules due to missing dependencies.
For most modules, that can be ignored for the moment.
Then SEMS is installed:
\code
$ make install
\endcode
This will install
- configuration in /usr/local/etc/sems/
- the sems binary in /usr/local/sbin/sems
- modules in /usr/local/lib/sems/plug-in/
- audio files in /usr/local/lib/sems/audio/
\subsection
\section Configuring_application Configuring the application for SEMS
There are many many modules shipped with SEMS, applications like announcement, voicemail,
conference, etc, codec modules, and some things like SIP registrar client.
Now we configure SEMS to load the conference application and execute the conference application
for incoming calls. We also set it to have itself register to our SIP server.
In <b>/usr/local/etc/sems/sems.conf</b>, we set
\code
load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;conference
\endcode
<p> to load the modules we need; sipctrl loads the SIP stack, wav is for reading WAV files and for the G711 codec,
uac_auth is the module which implements authentication, registrar_client facilitates registration at a SIP server,
and reg_agent is the application that uses registrar_client to have SEMS register at a SIP server.</p>
<p> We also set </p>
\code
application=conference
\endcode
<p> so that SEMS executes the conference application for an incoming call.</p>
<p> We want SEMS to register at a SIP server, so we need to tell it about the user name and the password, this is set
in <b>/usr/local/etc/sems/etc/reg_agent.conf</b> (of course this user name bob and the password need to be set to the
ones used for testing):</p>
\code
domain=iptel.org
user=bob
display_name=bob
auth_user=bob
pwd=verysecret
\endcode
\section Trying Testing the setup
Now we can test the configuration by running SEMS from the command line like this:
\code
/usr/local/sbin/sems -f /usr/local/etc/sems/sems.conf -D 3 -E
\endcode
<p> <b>-D 3</b> sets the debug level higher so that we see what is going on, and <b>-E</b> makes SEMS start in the foreground
and go to daemon mode. It also makes the log appear on the terminal and not in the system log file.</p>
<p> If everything is alright, SEMS starts up with a lot of messages, and hopefully no ERROR. There should also be some messages
appearing which show that SEMS registered successfully to the SIP server.
</p>
<p> Now we can call bob from the other phone or our PSTN telephone. In the SEMS log, we see the call appearing, and on the phone
we hear a message saying that we are the first participant in the conference.</p>
<p> If it doesnt work.... we examine the log for the ERROR that occured. Possibly, depending on the network setup,
we need to change the interface that SEMS is running on; this can be changed by setting the <b>media_ip</b> and
<b>sip_ip</b> options in sems.conf. Also, it might be that there is already someone using that port (default config: 5070),
in that case <b>sip_port</b> needs to be set. </p>
\section Running Running as daemon
If SEMS is started without the <b>-E</b> option, it will continue running as daemon in the background. The log can be seen in
syslog (e.g. with <b> tail -f /var/log/daemon.log</b>).
\section Other_application Running other applications
If we want to run other applications, the <b>load_plugins=</b> and <b>application=</b> parameters need to be adapted.
See \ref AppDoc for a description of the shipped applications.
\section DSM_application Creating and running a simple DSM applications
<p>
The DSM is a service development platform, that makes it simple to create powerful services. The service logis is defined
as a state machine, and the DSM application interprets this state machine for the calls, evaluating when to change state,
and which actions to execute.
</p>
To use a DSM application, we set in <b>/usr/local/etc/sems/sems.conf </b>
\code
load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;session_timer;dsm
application=mydsmapp
\endcode
and in
<b>/usr/local/etc/sems/etc/dsm.conf </b>:
\code
diag_path=/usr/local/lib/sems/dsm/
load_diags=mydsmapp
register_apps=mydsmapp
\endcode
Then we paste this little script in /usr/local/lib/sems/dsm/mydsmapp.dsm :
\code
initial state BEGIN {
playFile(/usr/local/lib/sems/audio/webconference/first_participant.wav
};
transition "file ends" BEGIN - noAudioTest -> TYPING;
state TYPING;
transition "typed a key" BEGIN - keyTest(#key < 10) / {
set($myfile=/usr/local/lib/sems/audio/webconference/);
append($myfile, #key);
append($myfile, .wav);
playFile($myfile);
} -> TYPING;
transition "BYE received" (BEGIN, TYPING) - hangup / stop(false) -> END;
state END;
\endcode
This little script welcomes the caller, and then plays the key that the caller entered. More documentation about DSM and
examples are in apps/dsm/doc, and also \ref ModuleDoc_dsm .
*/

91
doc/doc_howtostart_simpleproxy.h
Unescape View File

@ -0,0 +1,91 @@
/*! \page howtostart_simpleproxy How to set up a simple proxy for trying out and using SEMS
\section Introduction
<p>
This text describes how one can set up a simple SIP proxy in order to
try out services in SEMS.
</p>
<p>
We will use the Kamailio 3.0 default proxy installation, and add a route SERVICES
which adds the application name, and forwards the call to SEMS. The same configuration
can be used with the original SER (iptel.org/ser), sip-router (sip-router.org) or other
SER derivatives, like OpenSIPS (opensips.org).
</p>
\section Installing_Kamailio Installing Kamailio
To install Kamailio 3.0, there is excellent documentation on the <a href = "http://www.kamailio.org/dokuwiki/doku.php#setup">
Kamailio website</a>. In debain lenny, or for example in Ubuntu 9.10, one can install Kamailio with
\code
$ wget http://www.kamailio.org/pub/kamailio/latest/packages/debian-lenny/kamailio_3.0.1_i386.deb
$ dpkg -i kamailio_3.0.1_i386.deb
\endcode
To activate kamailio, one needs to set <b>RUN_KAMAILIO=yes</b> in <b>/etc/default/kamailio</b>.
\section adding_service_route Adding a service route
Kamailio processes all requests according to the logic that is set in the route section of its configuration file, which is
a very flexible one. In order to have services executed when some special numebrs are called (e.g. 200 and 300), we add another
route to <b>/etc/kamailio/kamailio.cfg</b>:
\code
route[SERVICES] {
if ($rU=~"^200.*") {
remove_hf("P-App-Name");
append_hf("P-App-Name: echo\r\n");
$ru = "sip:" + $rU + "@" + "127.0.0.1:5070";
route(RELAY);
exit;
}
if ($rU=~"^300.*") {
remove_hf("P-App-Name");
append_hf("P-App-Name: conference\r\n");
$ru = "sip:" + $rU + "@" + "127.0.0.1:5070";
route(RELAY);
exit;
}
}
\endcode
This route block can be added anywhere, for example at the end, or between the PSTN and the SERVICES routes.
Then, in the main route section, which is the one marked with the comment <em># main request routing logic</em>,
we call our SERVICES-route, preferably before (or after) the PSTN route:
\code
...
if ($rU==$null) {
# request with no Username in RURI
sl_send_reply("484","Address Incomplete");
exit;
}
route(SERVICES);
route(PSTN);
# apply DB based aliases (uncomment to enable)
##alias_db_lookup("dbaliases");
if (!lookup("location")) {
...
\endcode
Now, if we register a phone to the server, and call the 200 or the 300 number, the INVITE gets sent to 127.0.0.1:5070, with
the application that is to be called, added as header to the INVITE.
\section setting_up_sems Setting up SEMS to select the application
If we load several applications in SEMS, we can select which application to execute by the P-App-Name header. In <b>sems.conf</b>
we set application=$(apphdr) so that SEMS looks into the P-App-Name header to determine which application to run:
\code
application=$(apphdr)
load_plugin=sipctrl;wav;gsm;ilbc;speex;session_timer;conference;echo
sip_ip=127.0.0.1
sip_port=5070
media_ip=some.public.ip.here
\endcode
\note in this simple case, we could also have set application=$(mapping) and used regular expression mapping in app_mapping.conf
*/

153
doc/doc_howtostart_voicemail.h
Unescape View File

@ -0,0 +1,153 @@
/*! \page howtostart_voicemail How to set up the proxy for voicemail and voicebox in SEMS
\section Introduction
<p>
This text describes how one can set up a SER based home proxy SIP proxy with voicemail and voicebox service
implemented in SEMS. </p>
<p>With minor modifications, this should work with home proxies implemented with
SER derivatives (<a href="http://kamailio.org">Kamailio</a> 1.x, <a href="http://opensips.org">OpenSIPS</a>),
and also with <a href="http://sip-router.org">sip-router</a> (e.g. Kamailio 3.0) based proxy configurations. For other types of
proxies or SIP platforms, it should give an idea of what is required to use a SEMS based voicemail system.
</p>
\section voicemail_in_sems Features of a voicemail system with SEMS
<p>
The voicemail system that comes with SEMS supports the following features
- voicemail2email and/or dial-in voicebox
- greeting only mode
- voicebox plays message count
- new and saved messages
- user can record personal greeting message (as a separate service number)
- multi-domain capable
- multi-language capable (e.g. as user setting), supports single-digits pre and post
- supports domain and user aliases (domain/user string or domain-ID (DID)/user-ID (UID) )
- prompts per domain/language
- default greeting message per domain/language
- configurable key bindings for menu
</p>
\section voicemail_parameters Parameters to voicemail applications
<p>
Usually, when a call should be sent to the voicemail system, the home proxy already knows some parts or all
of the user profile, for example the email address of a user, or the voicemail settings; for example the
user profile is already loaded from a DB (or LDAP, RADIUS, DIAMETER etc). For this reason, in a
SEMS based voicemail system, the proxy adds the relevant information as parameters to the INVITE request.
Those parameters are set in the P-App-Param header.
</p>
<p>
Example:
\verbatim
INVITE sip:1000@sems01.iptel.org:5080 SIP/2.0.
From: "sayer@iptel" <sip:sayer@iptel.org>;tag=d3olt2dqvl.
To: <sip:1000@iptel.org>.
...
P-App-Name: voicebox.
P-App-Param: usr=sayer;dom=iptel.org;lng=en;uid=3ab0a114-ceff-11da-8607-0002b3abca3a;did=2f2091f5-ceff-11da-8220-0002b338cf3a;.
\endverbatim
</p>
<p>
If the proxy does not support this, or does not have access to the user profile, there are two solutions:
- add another SER-based proxy in front of SEMS that has access to user profile, and adds those headers
- add the functionality for accessing the user profile to SEMS (e.g. access DB in SEMS)
For both solutions, the main complexity lies in the fact that the right user needs to be identified (with support for
multi domain, aliases, call forwarding etc).
</p>
\section voicemail_in_sems Components of voicemail and voicebox system in SEMS
<p>
There is three applications involved in a voicemail/voicebox system in SEMS: <em>voicemail</em>, <em>voicebox</em>
and <em>annrecorder</em>. Voicemail is the application that records a message, and sends the message as email or
stores it into the voicebox storage. Voicebox is the application that users can dial into, listen to their messages,
delete or save them. Annrecorder is an application that lets users record their personal greeting message.
</p>
<p>
If only voicemail2email is to be used, the voicemail application alone can be employed. In that case, the mode
must be set to voicemail (see voicemail application parameters below).
</p>
\section msg_Storage Storage for voice message files and greetings
<p>
The storage for voice messages is implemented in a separate module. This way for example a specialized adapter
to some replicated storage system can be implemented and loaded without changing the other applications.
</p>
<p>
A storage module only needs to support a few very simple functions: Create, get and delete messages, mark a message
as read, list a user's directory, and get the number of messages in the user's directory. The sender and the message
record time is encoded in the message name.
</p>
<p>
The default storage module, <a>msg_storage</a>, is an implementation that just uses the normal file system
calls (fopen(), readdir(), opendir() etc). As 'saved' flag, the mtime of the file is compared to the atime.
\note If your file system does not support atime, this will not work, i.e. all messages will always appear as unread!
</p>
\section did_uid Domain/User text or domain ID (DID) and user ID (UID)
<p>
If the platform supports user and domain aliases (e.g. sip.iptel.org and iptel.org, or numeric aliases), there may not be
a canonical user name available. For that case, the user ID and domain ID (canonical user/domain ID) may be used, by setting
UID/DID application parameters. This overrides the user name and domain name, so that the correct user and domain is identified.
</p>
\section vm_modes Voicemail application modes
<p>
The voicemail application has four modes:
- voicemail : send email (default)
- box : leave in voicebox (store in msg_storage)
- both : send email and leave in voicebox
- ann : just play greeting, don't record message.
For <em>voicemail</em> and <em>both</em> mode, the email address must be given as parameter.
</p>
\section vm_avps Voicemail specific AVPs
The following user AVPs should be configured in SerWeb to be user-configurable:
- voicemail : voicemail mode - 'voicemail', 'box', 'both', or 'ann'
- email: email address
- lang: language - selectable from those for which prompts are present
\section ser_commands Proxy configuration for ser-oob.cfg
These route fragments could be inserted into a typical ser-oob or default Kamailio configuration.
\subsection leaving_message Leaving a message
This should be added to native SIP destinations which are not found in usrloc, i.e. instead of replying
480 User temporarily not available, and in FAILURE_ROUTE:
\verbatim
append_hf("P-App-Name: voicemail\r\n");
append_hf("P-App-Param: mod=%$t.voicemail%|;eml='%$t.email%|';usr=%@ruri.user%|;snd='%@from.uri%|';dom=%@ruri.host%|;uid=%$t.uid%|;did=%$t.did%|;");
rewritehostport("voicemail.domain.net:5080");
route(FORWARD);
\endverbatim
\subsection calling_voicebox Calling voicebox
This should be added to SITE-SPECIFIC route:
\verbatim
if (uri=~"^sip:1000") { # 1000 is voicebox access number
append_hf("P-App-Name: voicebox\r\n");
append_hf("P-App-Param: usr=%@from.uri.user%|;dom=%@from.uri.host%|;lng=%$f.lang%|;uid=%$f.uid%|;did=%$f.did%|;\r\n");
rewritehostport("voicemail.domain.net:5080");
route(FORWARD);
}
\endverbatim
\subsection calling_annrecorder Recording the greeting
This is very similar to the one above, and should be added to SITE_SPECIFIC as well:
\verbatim
if (uri=~"^sip:1001") { # 1001 is recod greeting number
append_hf("P-App-Name: annrecorder\r\n");
append_hf("P-App-Param: usr=%@from.uri.user%|;dom=%@from.uri.host%|;lng=%$f.lang%|;uid=%$f.uid%|;did=%$f.did%|;typ=vm;\r\n");
rewritehostport("voicemail.domain.net:5080");
route(FORWARD);
}
\endverbatim
Note the type (typ) here; the annrecorder application can be used to record different greetings (e.g. away greeting when
recording message, or normal away greeting). This type can be used when sending a call to <em>voicemail</em> application.
*/

5
doc/doxyref.h
Unescape View File

@ -9,6 +9,11 @@
* \section general General
* \arg \ref Readme
*
* \section howtostart How to get started
* \arg \ref howtostart_noproxy
* \arg \ref howtostart_simpleproxy
* \arg \ref howtostart_voicemail
*
* \section userdoc User's documentation
* \arg \ref sems.conf.sample
* \arg \ref Compiling

Write Preview
Loading…
Cancel
Save