diff --git a/doc/Applications.txt b/doc/Applications.txt new file mode 100644 index 00000000..f4df77a6 --- /dev/null +++ b/doc/Applications.txt @@ -0,0 +1,183 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +Application Modules Documentation + + Documentation for the applications that come with SEMS. The + applications can be found in the apps/ directory and are installed by + default if they do not depend on special libraries (eg. liblame). A set + of [8]Example Applications that illustrate how to make use certain + aspects of the SEMS framework can be found in the apps/examples + directory. These are not installed by default. + +Announcement Applications + + Applications that play announcements to the caller. For plain + announcements, there is the announcement module. + * [9]Module Documentation: announcement Application + + Pre-call announcements can either be implemented using early media with + the early_announce application, + * [10]Module Documentation: early_announce Application + + or the session is established and after the announcement SEMS acts as + B2BUA, inviting the original r-uri, and finally reinviting the caller: + * [11]Module Documentation: ann_b2b Application + + Another possibility is to establish the session and then REFER the + caller: + * [12]Module Documentation: announce_transfer Application + + As SEMS can also do UAC authentication for a call using the uac_auth + component plugin ( ModuleDoc_uac_auth). An example where this is used + is the announce_auth example application: + * [13]Module Documentation: announce_auth Application + +Voicemail and Mailbox + + SEMS has a voicemail application, which send a recorded message via + Email (voicemail2email), saves the message to the voicebox, or does + both: + * [14]Module Documentation: voicemail Application + + Messages saved to voicebox can be listened to using the voicebox + application: + * [15]Module Documentation: voicebox Application + + The annrecorder application can be used to record a personal greeting + message.: + * [16]Module Documentation: annrecorder Application + + There is also a simpler mailbox application, which stores recorded + messages (in an IMAP server) and users can dial in to check their + messages: + * [17]Module Documentation: mailbox Application + +Conferencing + + SEMS can be a conference bridge with the conference application: + * [18]Module Documentation: conference Application + +Authentication for conference rooms (PIN entry) + + There are two possibilies how a PIN entry for conference rooms (or for + other services) can be implemented: after the PIN is collected and + verified against a XMLRPC authentication server, the call can be + connected to the conference room either using B2BUA, or it can be + transfered to the conference bridge using a (proprietary) REFER call + flow. The b2bua solution, which also gives the possibility to limit the + call time, is implemented in the conf_auth plugin: + * [19]Module Documentation: conf_auth Application + + The other call flow can be implemented using the pin_collect + application: + * [20]Module Documentation: pin_collect Application + +Web controlled conference rooms + + Using the webconference application, conference rooms can be controlled + from e.g. a web control page, or some other external mechanism: + * [21]Module Documentation: webconference Application + +Prepaid + + This is a signalling-only prepaid engine. + * [22]Module Documentation: prepaid_sip application plugin + +Click2Dial + + An xmlrpc-enabled way to initiate authenticated calls: + * [23]Module Documentation: click2dial application plugin + +Defining and developing applications as state machine charts + + The DSM module allows to define an application as simple, easy to read, + self-documenting, concise state diagram. This state machine definition + is then interpreted and executed by the DSM application. + * [24]DSM: State machine notation for VoIP applications + +Scripting SEMS with Python + + There are two application modules which embed a python interpreted into + SEMS: the ivr module and the py_sems module. + + The ivr module plugin embeds a python interpreter into SEMS. In it, + applications written in python can be run (mailbox, conf_auth, + pin_collect for example) and new applications can be prototyped and + implemented very quickly: + * [25]Module Documentation: ivr Application + + The ivr module has a simple to use, yet limited API, which uses + hand-written wrappers for the python bindings. + + py_sems uses a binding generator to make python classes from the SEMS + core C++ classes, thus exposing a lot more functionality natively to + python: + * [26]Module Documentation: py_sems Application + +Registering SEMS at a SIP registrar + + The reg_agent module together with the registar_client module can be + used to register at a SIP registrar. + * [27]Module Documentation: reg_agent Application + + * [28]Module Documentation: registrar_client Application + +Various applications + + xmlrpc2di ([29]Module Documentation: xmlrpc2di Application) exposes DI + interfaces as XMLRPC server. This is very useful to connect SEMS with + other software, that e.g. trigger click2dial calls, create + registrations at SIP registrar, do monitoring, etc. + * [30]Module Documentation: callback application plugin + + * [31]Module Documentation: auth_b2b application plugin + +Other components + + * [32]Module Documentation: diameter_client component plugin + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [33]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/AppDocExample.html + 9. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_announcement.html + 10. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_early_announce.html + 11. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_ann_b2b.html + 12. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_announce_transfer.html + 13. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_announce_auth.html + 14. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_voicemail.html + 15. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_voicebox.html + 16. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_annrecorder.html + 17. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_mailbox.html + 18. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_conference.html + 19. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_conf_auth.html + 20. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_pin_collect.html + 21. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_webconference.html + 22. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_sw_prepaid_sip.html + 23. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_click2dial.html + 24. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_dsm.html + 25. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_ivr.html + 26. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_py_sems.html + 27. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_reg_agent.html + 28. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_registrar_client.html + 29. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_xmlrpc2di.html + 30. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_callback.html + 31. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_auth_b2b.html + 32. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_diameter_client.html + 33. http://www.doxygen.org/index.html diff --git a/doc/ComponentModules.txt b/doc/ComponentModules.txt new file mode 100644 index 00000000..c6e25032 --- /dev/null +++ b/doc/ComponentModules.txt @@ -0,0 +1,34 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +Component Modules Documentation + + SEMS is extensible with modules. Component modules are modules which + implement functionality which can be used by other modules, e.g. by + application modules. + * [8]Module Documentation: registrar_client Application : + registrar_client + + * [9]Module Documentation: uac_auth component : uac_auth + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [10]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_registrar_client.html + 9. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_uac_auth.html + 10. http://www.doxygen.org/index.html diff --git a/doc/Howtostart_noproxy.txt b/doc/Howtostart_noproxy.txt new file mode 100644 index 00000000..f3f8fb0e --- /dev/null +++ b/doc/Howtostart_noproxy.txt @@ -0,0 +1,210 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +How to try out SEMS without setting up a proxy + +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. + +Requirements + + For compiling SEMS, as a minimum a C++ compiler and make is needed. In + debian, do + apt-get install g++ make + +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 [8]http://iptel.org/service/. + + Any SIP phone, hardphone or softphone, can be used for testing. + Cross-platform, [9]sip-communicator is recommended, for Linux + [10]twinkle, for Windows sip-communicator, xten eyebeam or NCH express. + +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 [11]voip-info . [12]Sipgate for example, provides + free DID numbers in Germany. + +Installing SEMS from source + + First, the SEMS source is downloaded from iptel.org and extracted: + $ wget ftp.iptel.org/pub/sems/sems-latest.tar.gz + $ tar xzvf sems-latest.tar.gz + + SEMS is compiled: + $ cd sems-x.y.z/ + $ make + + 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: + $ make install + + 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/ + +Installing SEMS from source + +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 + load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;conference + + 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 + application=conference + + 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): + domain=iptel.org + user=bob + display_name=bob + auth_user=bob + pwd=verysecret + +Testing the setup + + Now we can test the configuration by running SEMS from the command line + like this: + /usr/local/sbin/sems -f /usr/local/etc/sems/sems.conf -D 3 -E + + -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. + +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). + +Running other applications + + If we want to run other applications, the load_plugins= and + application= parameters need to be adapted. See [13]Application Modules + Documentation for a description of the shipped applications. + +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 + load_plugins=sipctrl;wav;uac_auth;registrar_client;reg_agent;session_timer;ds +m + application=mydsmapp + + and in /usr/local/etc/sems/etc/dsm.conf : + diag_path=/usr/local/lib/sems/dsm/ + load_diags=mydsmapp + register_apps=mydsmapp + + Then we paste this little script in + /usr/local/lib/sems/dsm/mydsmapp.dsm : + 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; + + 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 [14]DSM: State machine notation for VoIP + applications . + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [15]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. http://iptel.org/service/ + 9. http://www.sip-communicator.org/ + 10. http://twinklephone.com/ + 11. http://www.voip-info.org/wiki/view/DID+Service+Providers + 12. http://sipgate.de/ + 13. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/AppDoc.html + 14. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_dsm.html + 15. http://www.doxygen.org/index.html diff --git a/doc/Howtostart_simpleproxy.txt b/doc/Howtostart_simpleproxy.txt new file mode 100644 index 00000000..28c153d9 --- /dev/null +++ b/doc/Howtostart_simpleproxy.txt @@ -0,0 +1,115 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +How to set up a simple proxy for trying out and using SEMS + +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). + +Installing Kamailio + + To install Kamailio 3.0, there is excellent documentation on the + [8]Kamailio website. In debain lenny, or for example in Ubuntu 9.10, + one can install Kamailio with + $ wget http://www.kamailio.org/pub/kamailio/latest/packages/debian-lenny/kam +ailio_3.0.1_i386.deb + $ dpkg -i kamailio_3.0.1_i386.deb + + To activate kamailio, one needs to set RUN_KAMAILIO=yes in + /etc/default/kamailio. + +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: + 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; + } + } + + 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: + ... + 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")) { + ... + + 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. + +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= so that SEMS looks into the P-App-Name header to determine + which application to run: + 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 + + Note: + in this simple case, we could also have set application= and + used regular expression mapping in app_mapping.conf + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [9]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. http://www.kamailio.org/dokuwiki/doku.php#setup + 9. http://www.doxygen.org/index.html diff --git a/doc/Howtostart_voicemail.txt b/doc/Howtostart_voicemail.txt new file mode 100644 index 00000000..9abb1af7 --- /dev/null +++ b/doc/Howtostart_voicemail.txt @@ -0,0 +1,198 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +How to set up the proxy for voicemail and voicebox in SEMS + +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 ([8]Kamailio 1.x, [9]OpenSIPS), and + also with [10]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. + +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 + +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: + 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-000 +2b3abca3a;did=2f2091f5-ceff-11da-8220-0002b338cf3a;. + + 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). + +Features of a voicemail system with 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). + +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! + +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. + +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. + +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 + +Proxy configuration for ser-oob.cfg + + These route fragments could be inserted into a typical ser-oob or + default Kamailio configuration. + +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: + 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); + +Calling voicebox + + This should be added to SITE-SPECIFIC route: + 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); + } + +Recording the greeting + + This is very similar to the one above, and should be added to + SITE_SPECIFIC as well: + 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); + } + + 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. + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [11]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. http://kamailio.org/ + 9. http://opensips.org/ + 10. http://sip-router.org/ + 11. http://www.doxygen.org/index.html diff --git a/doc/Makefile b/doc/Makefile index 959d6995..b372cc43 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,16 @@ .PHONY: doc doc: make -C ../core doc + lynx -dump doxygen_doc/html/index.html >index.txt + lynx -dump doxygen_doc/html/howtostart_noproxy.html >Howtostart_noproxy.txt + lynx -dump doxygen_doc/html/howtostart_simpleproxy.html >Howtostart_simpleproxy.txt + lynx -dump doxygen_doc/html/howtostart_voicemail.html >Howtostart_voicemail.txt + + lynx -dump doxygen_doc/html/AppDoc.html >Applications.txt + lynx -dump doxygen_doc/html/ZRTP.html >ZRTP.txt + lynx -dump doxygen_doc/html/Tuning.html >Tuning.txt + lynx -dump doxygen_doc/html/ComponentDoc.html >ComponentModules.txt + .PHONY: fulldoc fulldoc: diff --git a/doc/Tuning.txt b/doc/Tuning.txt new file mode 100644 index 00000000..91228205 --- /dev/null +++ b/doc/Tuning.txt @@ -0,0 +1,59 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +Tuning SEMS for high load + + For high load, there are several compile and run time options to make + SEMS run smoothly. + + When running SEMS, make sure that you have the ulimit for open files + (process.max-file-descriptor) set to an value which is high enough. You + may need to adapt raise the system wide hard limit (on Linux see + /etc/security/limits.conf), or run SEMS as super user. Note that an + unlimited open files limit is not possible, but it is sufficient to set + it to some very high value (e.g. ulimit -n 100000). + + There is a compile-time variable that sets a limit on how many RTP + sessions are supported concurrently, this is MAX_RTP_SESSIONS. You may + either add this at compile time to your value, or edit Makefile.defs + and adapt the value there. + + SEMS uses one thread per session (processing of the signaling). This + thread sleeps on a mutex (the session's event queue) most of the time + (RTP/audio processing is handled by the [8]AmMediaProcessor threads, + which is only a small, configurable, number), thus the scheduler should + usually not have any performance issue with this. The advantage of + using a thread per call/session is that if the thread blocks due to + some blocking operation (DB, file etc), processing of other calls is + not affected. The downside of using a thread per session is that you + will spend memory for the stack for every thread, which can fill up + your system memory quickly, if you have many sessions. The default for + the stack size is 1M, which for most cases is quite a lot, so if memory + consumption is an issue, you could adapt this in [9]AmThread, at the + call to pthread_attr_setstacksize. Note that, at least in Linux, the + memory is allocated, but if a page is not used, the page is not really + consumed, which means that most of that empty memory space for the + stack is not really consumed anyway. If you allocate more than system + memory for stack, though, thread creation may still fail with ENOMEM. + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [10]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/classAmMediaProcessor.html + 9. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/classAmThread.html + 10. http://www.doxygen.org/index.html diff --git a/doc/ZRTP.txt b/doc/ZRTP.txt new file mode 100644 index 00000000..27f0b224 --- /dev/null +++ b/doc/ZRTP.txt @@ -0,0 +1,107 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +ZRTP encryption + +Introduction + + ZRTP is a key agreement protocol to negotiate the keys for encryption + of RTP in phone calls. It is a proposed public standard: [8]ZRTP: Media + Path Key Agreement for Secure RTP. + + Even though it uses public key encryption, a PKI is not needed. Since + the keys are negotiated in the media path, support for it in signaling + is not necessary. ZRTP also offers opportunistic encryption, which + means that calls between UAs that support it are encrypted, but calls + to UAs not supporting it are still possible, but unencrypted. The + actual RTP encryption is done with [9]SRTP. For more information about + ZRTP, see the [10]Zfone project, the [11]draft and the [12]wikipedia + article. + +ZRTP in SEMS + + Since the version 1.0 SEMS supports ZRTP with the use of the [13]Zfone + SDK. + + To build SEMS with ZRTP support, install the SDK and set WITH_ZRTP=yes + in Makefile.defs, or build with + $ make WITH_ZRTP=yes + + The conference application is enabled to tell the caller the SAS phrase + if it is compiled with WITH_SAS_TTS option, set in + apps/conference/Makefile. For this to work, the [14]flite + text-to-speech synthesizer version 1.2 or 1.3 is needed. + +Online demo + + Call +sip:[15]secureconference@iptel.org + + or +sip:[16]zrtp@iptel.org + + for a test drive of ZRTP conferencing. If you call that number with a + ZRTP enabled phone, you should be told the SAS string that is also + displayed in your phone. Press two times the hash (##) while in the + call to read out the SAS string again. + +How to use ZRTP in your application + + Have a look at the conference application on how to add ZRTP support in + your application. There is a void AmSession::onZRTPEvent(zrtp_event_t + event, zrtp_stream_ctx_t *stream_ctx) event that is called with the + appropriate ZRTP event type and the zrtp stream context, if the state + of the ZRTP encryption changes. The zrtp_event are defined in the Zfone + SDK, e.g. ZRTP_EVENT_IS_SECURE. + +Licensing + + The Zfone SDK is licensed under the Affero GPL v3. As SEMS is licensed + under GPL 2+, you may use SEMS under GPLv3 and link with libZRTP under + Affero GPL v3. You may use the resulting program under the restrictions + of both GPLv3 and AGPLv3. + + Note that due to the nature of the GPL, without written consent of the + authors of SEMS as with any other non-free library, it is not possible + to distribute SEMS linked to specially licensed commercial version of + the libZRTP SDK, nor the AGPL version. If in doubt, talk to your + lawyer. + +Phones with ZRTP + + * [17]Zfone turns every softphone into a secure phone by tapping into + the RTP sent and received + * [18]Twinkle is a very good free softphone for Linux. It can speak + ZRTP with the use of GNU [19]libzrtpcpp. + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [20]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. http://tools.ietf.org/html/draft-zimmermann-avt-zrtp + 9. http://www.ietf.org/rfc/rfc3711.txt + 10. http://zfoneproject.com/ + 11. http://tools.ietf.org/html/draft-zimmermann-avt-zrtp + 12. http://en.wikipedia.org/wiki/ZRTP + 13. http://zfoneproject.com/prod_sdk.html + 14. http://cmuflite.org/ + 15. mailto:secureconference@iptel.org + 16. mailto:zrtp@iptel.org + 17. http://zfoneproject.com/ + 18. http://twinklephone.com/ + 19. http://www.gnutelephony.org/index.php/GNU_ZRTP + 20. http://www.doxygen.org/index.html diff --git a/doc/index.txt b/doc/index.txt new file mode 100644 index 00000000..35328b2a --- /dev/null +++ b/doc/index.txt @@ -0,0 +1,84 @@ + * [1]Main Page + * [2]Related Pages + * [3]Namespaces + * [4]Data Structures + * [5]Files + * [6]Directories + * [7]Examples + +SEMS Documentation + +News & Changes + + * [8]Changelog (from 0.10.0-rc1 onwards) + +General + + * [9]SEMS Readme file + +How to get started + + * [10]How to try out SEMS without setting up a proxy + * [11]How to set up a simple proxy for trying out and using SEMS + * [12]How to set up the proxy for voicemail and voicebox in SEMS + +User's documentation + + * [13]SEMS core configuration parameters + * [14]Compilation instructions + * [15]Application Modules Documentation + * [16]DSM: State machine notation for VoIP applications + * [17]ZRTP encryption + * [18]Tuning SEMS for high load + +Developer's documentation + + * [19]SEMS Design Overview + * [20]Application Development Tutorial + * [21]Example Applications + * [22]Component Modules Documentation + +Web sites + + * Main: SEMS website [23]http://iptel.org/sems + * sems & semsdev Lists: List server [24]http://lists.iptel.org + * Bugs: Bug tracker: [25]http://tracker.iptel.org/browse/SEMS + +Outdated documentation bits + + * [26]Changes in SEMS from 0.9 versions to 0.10 + * Configure-Sems-Ser-HOWTO + __________________________________________________________________ + + + Generated on Wed Mar 17 14:15:58 2010 for SEMS by [27]doxygen 1.6.1 + +References + + 1. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/index.html + 2. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/pages.html + 3. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/namespaces.html + 4. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/annotated.html + 5. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/files.html + 6. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/dirs.html + 7. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/examples.html + 8. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/changelog.html + 9. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/Readme.html + 10. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/howtostart_noproxy.html + 11. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/howtostart_simpleproxy.html + 12. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/howtostart_voicemail.html + 13. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/sems.conf.sample.html + 14. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/Compiling.html + 15. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/AppDoc.html + 16. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ModuleDoc_dsm.html + 17. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ZRTP.html + 18. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/Tuning.html + 19. http://www.iptel.org/files/semsng-designoverview.pdf + 20. http://www.iptel.org/sems/sems_application_development_tutorial + 21. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/AppDocExample.html + 22. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/ComponentDoc.html + 23. http://iptel.org/sems + 24. http://lists.iptel.org/ + 25. http://tracker.iptel.org/browse/SEMS + 26. file://localhost/home/stefan/devel/sems/trunk/doc/doxygen_doc/html/whatsnew_0100.html + 27. http://www.doxygen.org/index.html diff --git a/doc/doc_applications.h b/doc/src/doc_applications.h similarity index 100% rename from doc/doc_applications.h rename to doc/src/doc_applications.h diff --git a/doc/doc_componentmods.h b/doc/src/doc_componentmods.h similarity index 100% rename from doc/doc_componentmods.h rename to doc/src/doc_componentmods.h diff --git a/doc/doc_exampleapps.h b/doc/src/doc_exampleapps.h similarity index 100% rename from doc/doc_exampleapps.h rename to doc/src/doc_exampleapps.h diff --git a/doc/doc_howtostart_noproxy.h b/doc/src/doc_howtostart_noproxy.h similarity index 100% rename from doc/doc_howtostart_noproxy.h rename to doc/src/doc_howtostart_noproxy.h diff --git a/doc/doc_howtostart_simpleproxy.h b/doc/src/doc_howtostart_simpleproxy.h similarity index 100% rename from doc/doc_howtostart_simpleproxy.h rename to doc/src/doc_howtostart_simpleproxy.h diff --git a/doc/doc_howtostart_voicemail.h b/doc/src/doc_howtostart_voicemail.h similarity index 100% rename from doc/doc_howtostart_voicemail.h rename to doc/src/doc_howtostart_voicemail.h diff --git a/doc/doc_tutorialapps.h b/doc/src/doc_tutorialapps.h similarity index 100% rename from doc/doc_tutorialapps.h rename to doc/src/doc_tutorialapps.h diff --git a/doc/doc_zrtp.h b/doc/src/doc_zrtp.h similarity index 100% rename from doc/doc_zrtp.h rename to doc/src/doc_zrtp.h diff --git a/doc/doxyref.h b/doc/src/doxyref.h similarity index 100% rename from doc/doxyref.h rename to doc/src/doxyref.h