From 7618e7e7792f99bdaddcabf64126434b6a10f748 Mon Sep 17 00:00:00 2001 From: Stefan Sayer Date: Wed, 17 Mar 2010 13:05:24 +0000 Subject: [PATCH] - added some tutorials on how to get started - updated contributions licensing policy git-svn-id: http://svn.berlios.de/svnroot/repos/sems/trunk@1658 8eb893ce-cfd4-0310-b710-fb5ebe64c474 --- doc/COPYING | 4 + doc/doc_howtostart_noproxy.h | 177 +++++++++++++++++++++++++++++++ doc/doc_howtostart_simpleproxy.h | 91 ++++++++++++++++ doc/doc_howtostart_voicemail.h | 153 ++++++++++++++++++++++++++ doc/doxyref.h | 5 + 5 files changed, 430 insertions(+) create mode 100644 doc/doc_howtostart_noproxy.h create mode 100644 doc/doc_howtostart_simpleproxy.h create mode 100644 doc/doc_howtostart_voicemail.h diff --git a/doc/COPYING b/doc/COPYING index 175d2454..20ce1d99 100644 --- a/doc/COPYING +++ b/doc/COPYING @@ -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. ------------------------------------------------------------------------- diff --git a/doc/doc_howtostart_noproxy.h b/doc/doc_howtostart_noproxy.h new file mode 100644 index 00000000..c8a5f8e1 --- /dev/null +++ b/doc/doc_howtostart_noproxy.h @@ -0,0 +1,177 @@ +/*! \page howtostart_noproxy How to try out SEMS without setting up a proxy + + \section Introduction + +

+ 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. +

+ +

+ 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. +

+ + \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 http://iptel.org/service/. + + Any SIP phone, hardphone or softphone, can be used for testing. Cross-platform, + sip-communicator is recommended, for Linux + twinkle, 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 + voip-info . + Sipgate 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 /usr/local/etc/sems/sems.conf, we set + \code + load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;conference + \endcode +

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.

+ +

We also set

+ \code + application=conference + \endcode +

so that SEMS executes the conference application for an incoming call.

+ +

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 /usr/local/etc/sems/etc/reg_agent.conf (of course this user name bob and the password need to be set to the + ones used for testing):

+ \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 +

-D 3 sets the debug level higher so that we see what is going on, and -E 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.

+ +

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. +

+ +

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.

+ +

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 media_ip and + sip_ip options in sems.conf. Also, it might be that there is already someone using that port (default config: 5070), + in that case sip_port needs to be set.

+ + \section Running Running as daemon + If SEMS is started without the -E option, it will continue running as daemon in the background. The log can be seen in + syslog (e.g. with tail -f /var/log/daemon.log). + + \section Other_application Running other applications + If we want to run other applications, the load_plugins= and application= 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 +

+ 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. +

+ + To use a DSM application, we set in /usr/local/etc/sems/sems.conf + \code + load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;session_timer;dsm + application=mydsmapp + \endcode + + and in + /usr/local/etc/sems/etc/dsm.conf : + \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 . + +*/ \ No newline at end of file diff --git a/doc/doc_howtostart_simpleproxy.h b/doc/doc_howtostart_simpleproxy.h new file mode 100644 index 00000000..09d00d46 --- /dev/null +++ b/doc/doc_howtostart_simpleproxy.h @@ -0,0 +1,91 @@ +/*! \page howtostart_simpleproxy How to set up a simple proxy for trying out and using SEMS + + \section Introduction + +

+ This text describes how one can set up a simple SIP proxy in order to + try out services in SEMS. +

+

+ 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). +

+ + \section Installing_Kamailio Installing Kamailio + + To install Kamailio 3.0, there is excellent documentation on the + Kamailio website. 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 RUN_KAMAILIO=yes in /etc/default/kamailio. + + \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 /etc/kamailio/kamailio.cfg: + \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 # main request routing logic, + 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 sems.conf + 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 + +*/ \ No newline at end of file diff --git a/doc/doc_howtostart_voicemail.h b/doc/doc_howtostart_voicemail.h new file mode 100644 index 00000000..049c2d89 --- /dev/null +++ b/doc/doc_howtostart_voicemail.h @@ -0,0 +1,153 @@ + +/*! \page howtostart_voicemail How to set up the proxy for voicemail and voicebox in SEMS + + \section Introduction + +

+ This text describes how one can set up a SER based home proxy SIP proxy with voicemail and voicebox service + implemented in SEMS.

+ +

With minor modifications, this should work with home proxies implemented with + SER derivatives (Kamailio 1.x, OpenSIPS), + and also with sip-router (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. +

+ + \section voicemail_in_sems Features of a voicemail system with SEMS +

+ 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 +

+ + \section voicemail_parameters Parameters to voicemail applications +

+ 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. +

+

+ Example: + \verbatim + INVITE sip:1000@sems01.iptel.org:5080 SIP/2.0. + From: "sayer@iptel" ;tag=d3olt2dqvl. + To: . + ... + 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 +

+ +

+ 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). +

+ + \section voicemail_in_sems Components of voicemail and voicebox system in SEMS +

+ There is three applications involved in a voicemail/voicebox system in SEMS: voicemail, voicebox + and annrecorder. 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. +

+ +

+ 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). +

+ + \section msg_Storage Storage for voice message files and greetings +

+ 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. +

+

+ 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. +

+

+ The default storage module, msg_storage, 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! +

+ + \section did_uid Domain/User text or domain ID (DID) and user ID (UID) +

+ 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. +

+ + \section vm_modes Voicemail application modes +

+ 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 voicemail and both mode, the email address must be given as parameter. +

+ + \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 voicemail application. +*/ \ No newline at end of file diff --git a/doc/doxyref.h b/doc/doxyref.h index e92936fa..418ece8f 100644 --- a/doc/doxyref.h +++ b/doc/doxyref.h @@ -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