RestComm is a robust, powerful platform that will facilitate building comprehensive real-time communication solutions. The steps below will help you get started with ease.
Warning
On a production system, please take into consideration the following:
MMS can get into a bad state and report "Too many open files" error because of Linux default value on the total number of file descriptors.
You can go to the following sites to see how to increase the maximum number of open files in your server:
http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files/
http://amitbhayani.blogspot.fr/2010/01/javanetsocketexception-too-many-open.html
Running RestComm on JBoss
JBoss Security
Running a secure application is dependent on multiple factors. Restcomm runs on JBoss which implies that system security implemention can be handled at JBoss level. Please see the link below on how you can make your server environment more secure. https://community.jboss.org/wiki/SecureJboss?_sscc=t
Download
TelScale-Restcomm-JBoss-AS7-XX.XX.GA.zipUsing a terminal of your choice, extract the content of
TelScale-Restcomm-XX.XX.GA.zipto a local directory on your computer. The root directoy into which you extract the content of the .zip file will be referred to as $RESTCOMM_HOME.Go to
$RESTCOMM_HOME/telscale-media/telscale-media-server/binchange the permission of the
run.shas followssudo chmod +x ./run.sh
then start the TelScale Media Server as follows
sudo ./run.sh
If all is correctly started you will see the following at the end of the bash terminal window
[MainDeployer] [[[[[[[[[ Mobicents Media Server: release.version=3.0.0.FINAL Started ]]]]]]]]]
Open another terminal and proceed as follows:
Go to
$RESTCOMM_HOME/binchange the permissions of all the
.shfiles in the bin directory as followssudo chmod +x ./*.shStart RestComm by running the following command
sudo ./standalone.sh -c standalone-sip.xmlIf RestComm is correctly started you will see the following at the end of the terminal
INFO [Version] TelScale Sip Servlets 6.1.3.GA-TelScale (build: Git Hash=r8947f2732ee64c76566ed6c0b236204c048538e1 date=201306131639) Started. 17:30:05,854 INFO [Version] ============================================================================== == == == Thank you for running TelScale == == Carrier Grade Communications Platform by the creators of Mobicents == == Copyright 2011-2013 Telestax, Inc. == == http://www.telestax.com/ == == == ==============================================================================
Running RestComm on Tomcat
Download
TelScale-Restcomm-Tomcat-XX.XX.GA.zipUsing a terminal of your choice, extract the content of
TelScale-Restcomm-Tomcat-XX.XX.GA.zipto a local directory on your computer. The root directoy into which you extract the content of the .zip file will be referred to as $RESTCOMM_HOME.Go to
$RESTCOMM_HOME/telscale-media/telscale-media-server/binchange the permission of the
run.shas followssudo chmod +x ./run.sh
then start the TelScale Media Server as follows
sudo ./run.sh
If all is correctly started you will see the following at the end of the bash terminal window
[MainDeployer] [[[[[[[[[ Mobicents Media Server: release.version=3.0.0.FINAL Started ]]]]]]]]]
Open another terminal and proceed as follows:
Go to
$RESTCOMM_HOME/binchange the permissions of all the
.shfiles in the bin directory as followssudo chmod +x ./*.shThe content of the bin directory should be similar to the list below
bootstrap.jar digest.sh tomcat-juli.jar catalina.bat setclasspath.bat tomcat-native.tar.gz catalina.sh setclasspath.sh tool-wrapper.bat catalina-tasks.xml shutdown.bat tool-wrapper.sh commons-daemon.jar shutdown.sh version.bat commons-daemon-native.tar.gz startup.bat version.sh cpappend.bat startup.sh digest.bat telestax-license.xml
Start RestComm by running the following command
sudo ./catalina.sh runIf RestComm is correctly started on Tomcat, you will see an output similar to the one below
Started. 2013-08-15 19:02:46,903 INFO [Version] (main) ============================================================================== == == == Thank you for running TelScale == == Carrier Grade Communications Platform by the creators of Mobicents == == Copyright 2011-2013 Telestax, Inc. == == http://www.telestax.com/ == == == ============================================================================== Aug 15, 2013 7:02:50 PM org.apache.catalina.startup.Catalina start INFO: Server startup in 14090 ms
Before you start using Restcomm, you must change the default password. Please follow the steps below
Open your browser and go to http://127.0.0.1:8080/restcomm-management Enter the following information: - Email/Account SID = administrator@company.com - Password = RestComm - Press the Login button
You will see a screen similar to the one below
In the screen below, change the password and update.
Once the password has been changed, you can now log into the Admin Management interface and start using Restcomm.
Restcomm comes prepackaged with multiple example applications designed to help you quickly get started. For more demos and configuration details please visit www.telestax.com/doc
Start a SIP phone (see below) and dial 1234@127.0.0.1:5080. You will hear a welcome message.
Warning
Some SIP phones have codec incompatibility issues, in the above example, we used Ekiga. You may also try Jitsi or Sflphone.RestComm is a robust, powerful platform that will facilitate building comprehensive real-time communication solutions. The steps below will help you get started with ease.
Warning
On a production system, please take into consideration the following:
MMS can get into a bad state and report "Too many open files" error because of Linux default value on the total number of file descriptors.
You can go to the following sites to see how to increase the maximum number of open files in your server:
http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files/
http://amitbhayani.blogspot.fr/2010/01/javanetsocketexception-too-many-open.html
Running RestComm on JBoss
JBoss Security
Running a secure application is dependent on multiple factors. Restcomm runs on JBoss which implies that system security implemention can be handled at JBoss level. Please see the link below on how you can make your server environment more secure. https://community.jboss.org/wiki/SecureJboss?_sscc=t
Download
TelScale-Restcomm-JBoss-AS7-XX.XX.GA.zipUsing a terminal of your choice, extract the content of
TelScale-Restcomm-XX.XX.GA.zipto a local directory on your computer. The root directoy into which you extract the content of the .zip file will be referred to as $RESTCOMM_HOME.Go to
$RESTCOMM_HOME/telscale-media/telscale-media-server/binchange the permission of the
run.shas followssudo chmod +x ./run.sh
then start the TelScale Media Server as follows
sudo ./run.sh
If all is correctly started you will see the following at the end of the bash terminal window
[MainDeployer] [[[[[[[[[ Mobicents Media Server: release.version=3.0.0.FINAL Started ]]]]]]]]]
Open another terminal and proceed as follows:
Go to
$RESTCOMM_HOME/binchange the permissions of all the
.shfiles in the bin directory as followssudo chmod +x ./*.shStart RestComm by running the following command
sudo ./standalone.sh -c standalone-sip.xmlIf RestComm is correctly started you will see the following at the end of the terminal
INFO [Version] TelScale Sip Servlets 6.1.3.GA-TelScale (build: Git Hash=r8947f2732ee64c76566ed6c0b236204c048538e1 date=201306131639) Started. 17:30:05,854 INFO [Version] ============================================================================== == == == Thank you for running TelScale == == Carrier Grade Communications Platform by the creators of Mobicents == == Copyright 2011-2013 Telestax, Inc. == == http://www.telestax.com/ == == == ==============================================================================
Running RestComm on Tomcat
Download
TelScale-Restcomm-Tomcat-XX.XX.GA.zipUsing a terminal of your choice, extract the content of
TelScale-Restcomm-Tomcat-XX.XX.GA.zipto a local directory on your computer. The root directoy into which you extract the content of the .zip file will be referred to as $RESTCOMM_HOME.Go to
$RESTCOMM_HOME/telscale-media/telscale-media-server/binchange the permission of the
run.shas followssudo chmod +x ./run.sh
then start the TelScale Media Server as follows
sudo ./run.sh
If all is correctly started you will see the following at the end of the bash terminal window
[MainDeployer] [[[[[[[[[ Mobicents Media Server: release.version=3.0.0.FINAL Started ]]]]]]]]]
Open another terminal and proceed as follows:
Go to
$RESTCOMM_HOME/binchange the permissions of all the
.shfiles in the bin directory as followssudo chmod +x ./*.shThe content of the bin directory should be similar to the list below
bootstrap.jar digest.sh tomcat-juli.jar catalina.bat setclasspath.bat tomcat-native.tar.gz catalina.sh setclasspath.sh tool-wrapper.bat catalina-tasks.xml shutdown.bat tool-wrapper.sh commons-daemon.jar shutdown.sh version.bat commons-daemon-native.tar.gz startup.bat version.sh cpappend.bat startup.sh digest.bat telestax-license.xml
Start RestComm by running the following command
sudo ./catalina.sh runIf RestComm is correctly started on Tomcat, you will see an output similar to the one below
Started. 2013-08-15 19:02:46,903 INFO [Version] (main) ============================================================================== == == == Thank you for running TelScale == == Carrier Grade Communications Platform by the creators of Mobicents == == Copyright 2011-2013 Telestax, Inc. == == http://www.telestax.com/ == == == ============================================================================== Aug 15, 2013 7:02:50 PM org.apache.catalina.startup.Catalina start INFO: Server startup in 14090 ms
Restcomm comes prepackaged with multiple example applications designed to help you quickly get started.
Start a SIP phone (see below) and dial
1234@127.0.0.1:5080
. You will hear a welcome message.
Warning
Some SIP phones have codec incompatibility issues, in the above example, we used Ekiga. You may also try Jitsi or Sflphone.The application bound to the number 1234 can be found at <filename>$RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/hello-play.xml</filename>.
You must first activate Text-to-Speech before you can proceed.
You must get an API key from
http://www.voicerss.org
in order to proceed with this section. You can register for a free
account and an API key will be emailed to you. Once you have the API
key, open the
$RESTCOMM_HOME/standalone/deployments/restcomm.war/WEB-INF/conf/restcomm.xml
file and find the speech-synthesizer VoiceRSS section. Add your API
key as shown below and restart RestComm
<speech-synthesizer class="org.mobicents.servlet.restcomm.tts.VoiceRSSSpeechSynthesizer"> <service-root>http://api.voicerss.org</service-root> <apikey>2901c0aXXXXXXXXXXXXXX</apikey>
Start a SIP phone dial
1235@127.0.0.1:5080
. You will hear a welcome message in multiple languages.
The application bound to the number 1235 can be found at $RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/hello-world.xml.
This demo creates a simple IVR system
Activate DTMF using Ekiga
Make sure your DTMF setting in Ekiga is set to RFC2833. In order to set it correctly, go to the menu Edit->Preference->Protocols->SIP Settings->DTMF Mode
You may also use SFLPHONE instead of Ekiga
Start a SIP phone dial
1236@127.0.0.1:5080
. You will hear a message asking you to enter a digit and press
star. If the digit is correctly received, Restcomm will replay the
number you entered.
The application bound to the number 1236 can be found at <filename>$RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/gather/hello-gather.xml</filename>. and <filename>$RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/gather/gather.jsp</filename>.
This demo makes a call from one SIP phone to another. The Demo uses
the SIP noun. You can calll any SIP account. All you have to do is
change the content of the
dial-sip.xml
In order to use this demo, you may use the default accounts, Alice and Bob, and register them on two separate SIP phones. Start both SIP phones and make sure Alice and Bob are registerd with the password (1234). These users come pre-configured with Restcomm for test purposes.
Start Two SIP Phone Sessions
If you are using the SIP sflphone here is what to do:
Start first instance ex. - sflphone
Start second instance ex. - sudo sflphone
In the application
dial-sip.xml
you can change the default to
sip:alice@127.0.0.1:5061?
This will allow you to make a call to Alice. Note that Alice must be registered on port 5061 for the call to succeed.
From the the phone on which Bob is registerd, dial the number
1237
. The phone on which Alice is registered will ring and the
connection will be made when you answer the call.
The application bound to the number 1237 can be found at $RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/dial/sip/dial-sip.xml.
This demo makes a call from one SIP Client to Another. The demo uses the Client noun
In order to use this demo, you must have user Alice and Bob registered on two separate SIP phones. Start both SIP phones and make sure Alice and Bob are registerd with the password (1234). These users come pre-configured with Restcomm for test purposes.
Start Two SIP Phone Sessions
You can start the second instance of your SIP phones by prepending
the executable with
sudo
. If you are using the SIP sflphone here is what to do:
Start first instance ex. - sflphone
Start second instance ex. - sudo sflphone
From the phone on which Bob is registerd, dial the number
1238
. The phone on which Alice is registered will ring and the
connection will be made when you answer the call.
The application bound to the number 1238 can be found at <filename>$RESTCOMM_HOME/standalone/deployments/restcomm.war/demos/dial/client/dial-client.xml</filename>.
Advanced Examples
Please go to this chapter for more examples Chapter 7, Advanced RestComm Examples .
This demo Lets a user join a conference as a moderator and the other
user as a participant. The participant will dial
1310
and will hear a hold music. The moderator will dial
1311
and the hold music will stop and the conference will be started.
Most SIP phones will require you to register before you can make a call. You can use the default accounts, Alice and Bob with password (1234)to register.
Start Two SIP Phone Sessions
You can start the second instance of your SIP phones by prepending
the executable with
sudo
. If you are using the SIP sflphone here is what to do:
Start first instance ex. - sflphone
Start second instance ex. - sudo sflphone
From the phone on which Bob is registerd, dial the number
1310
. From the phone on which Alice is registered, dial
1311
The application is bound to the number 1310 and 1311 can be found at http://127.0.0.1:8080/restcomm/demos/dial/conference/dial-conference.xml and at http://127.0.0.1:8080/restcomm/demos/dial/conference/dial-conference-moderator.xml
Advanced Examples
Please go to this chapter for more examples Chapter 7, Advanced RestComm Examples .
This example is built using the Restcomm Visual Designer. You can register a SIP phone with the user bob or alice and password (1234). Then dial 1239. You will hear a welcome message.
The application is bound to the number 1239. The link to the rvdSayVerbDemo is below: http://127.0.0.1:8080/restcomm-rvd/#/designer/rvdSayVerbDemo All project created with Restcomm Visual Designer are stored in the directory: $RESTCOMM_HOME/standalone/deployments/restcomm-rvd.war/workspace
This demo uses the Gather verb to get user input and map it to the corresponding modules. You can register a SIP phone with the user bob or alice and password (1234). Then, dial 1240. You will hear a welcome message asking you to press 1 for Sales or 2 for Technical Support.
The application is bound to the number 1240. The link to the rvdSayVerbDemo is below: http://127.0.0.1:8080/restcomm-rvd/#/designer/rvdCollectVerbDemo All project created with Restcomm Visual Designer are stored in the directory: $RESTCOMM_HOME/standalone/deployments/restcomm-rvd.war/workspace
This demo uses the External Services to Restcomm to an external program for more complex solutions. There are two parts to this demo application, the RVD app and the external servlet http://127.0.0.1:8080/RvdExternalServicesDemo/rvdESdemo which manages the logic. You can register a SIP phone with the user bob or alice and password (1234). Then, dial 1241. You will be asked to enter a customer ID. You can enter number 11 or 12. You will hear a corresponding welcome message depending on the customer ID you entered.
The application is bound to the number 1241. The link to the rvdSayVerbDemo is below: http://127.0.0.1:8080/restcomm-rvd/#/designer/rvdESDemo All project created with Restcomm Visual Designer are stored in the directory: $RESTCOMM_HOME/standalone/deployments/restcomm-rvd.war/workspace The RvdExternalServicesDemo.war file is deployed in the directory $RESTCOMM_HOME/standalone/deployments/
In order for TelScale RestComm to function properly it must first be
configured. In this chapter we will cover
the settings for TelScale RestComm and it's respective plug-ins. In
order to make TelScale RestComm easy to manage
all of the configuration is done in only one file. The file is located
at
RESTCOMM_HOME/WEB-INF/webapps/restcomm/conf/restcomm.xml
and is composed of the sections that follow.
Note
TelScale RestComm provides a default set of plug-ins for the storage engine, fax service, SMS aggregator, automatic speech recognition, and speech synthesis. All these services are pluggable and TelScale RestComm is not limited to any service provider or software platformz.
The runtime-settings are used by TelScale RestComm at runtime to customize it's behavior. A list of the runtime settings and a description is provided below.
Table 2.1. Runtime Settings
| Element | Description |
|---|---|
| api-version | The version of the TelScale RestComm API that we will be executing by default. |
| prompts-uri | The location where the audio prompts are located. |
| cache-path | The local path the cache folder. |
| cache-uri | The HTTP URI to the cache folder. |
| recordings-path | The local path to the folder containing the recordings. |
| recordings-uri | The HTTP URI to the folder containing the recordings. |
| error-dictionary-uri | The HTTP URI to the TelScale RestComm error dictionary. |
| external-ip | The IP to use for out-bound SIP REGISTER requests. This is useful when you want to report a different IP than the one TelScale RestComm picked by default. |
| use-to | If set to true TelScale RestComm will use the To header to determine the destination. If set to false TelScale RestComm will use the Request URI to determine the destination. |
| outbound-proxy-user | The user name used to authenticate with the outbound proxy. (Optional) |
| outbound-proxy-password | The password used to authenticated with the outbound proxy. (Optional) |
| outbound-proxy-uri | The SIP URI to the outbound proxy. Note: Do not prepend 'sip:' to the proxy uri. If necessary the port can be included, for example alice@localhost:5080 |
| fallback-outbound-proxy-user | The user name used to authenticate with the fallback outbound proxy. (Optional) |
| fallback-outbound-proxy-password | The password used to authenticated with the fallback outbound proxy. (Optional) |
| fallback-outbound-proxy-uri | The SIP URI to the fallback outbound proxy. Note: Do not prepend 'sip:' to the proxy uri. If necessary the port can be included, for example alice@localhost:5080 |
| allow-fallback | Set this to true so Restcomm will fallback to the backup proxy in case of failed calls |
| max-failed-calls | Maximum number of failed call before switching from primary to fallback outbound proxy |
| allow-fallback-to-primary | Allow fallback from Backup to Primary proxy in case fail called at backup proxy. |
TelScale Restcomm Resource Security. The security model is based on role based access control. TelScale RestComm defines a set of permissions that can be defined for each role. There are two predefined roles Administrator and Developer. The Developer role can be configured or removed all together depending on your needs but the Administrator role can not be changed. The Administrator role can not be modified or removed and it has access to every resource.
First we will define the list of permissions and what they mean.
Table 2.2. TelScale RestComm Permissions
| Permission | Description |
|---|---|
| Create | The role has access to create a type resource. |
| Read | The role has access to read a type of resource. |
| Modify | The role has access to modify a type of resource. |
| Delete | The role has access to delete a type of resource. |
These permissions apply to every resource exposed by the Restful APIs. Once a role is defined it can be specified for new Account resources that are created.
Note
If no role is specified when creating a new Account resource then the new Account will inherit the security role of the account that created it. If this role is the Administrator role the system may become compromised.
Wildcard Permission. The asterisk '*' is a wildcard that means grant all permissions and can be used in place of typing out all the permissions.
To see how this all comes together please check out the
restcomm.xml
configuration
file.
The default auto provisioning API used by TelScale RestComm.
Table 2.3. VoIP Innovations Settings
| Element | Description |
|---|---|
| login | The user name configured in the VoIP Innovations Portal under API users. |
| password | The password configured in the VoIP Innovations Portal under API users. |
| endpoint | The end point ID of the end point that will be used by TelScale RestComm |
| uri | The path to the VoIP Innovations service end point. |
The data access object manager is used to gain access to the data store that TelScale RestComm will use.
The default data access object manager is based on MyBatis and provides access to RDBM systems.
Table 2.4. MyBatis Settings
| Element | Description |
|---|---|
| configuration-file | The path to the mybatis.xml configuration file. |
| data-files | The path to the data files used to store the database tables. |
| sql-files | The path to the XML files containing the SQL statements that will be executed by the database. |
The media server manager is responsible for all the media servers managed by TelScale RestComm.
Table 2.5. Media Server Manager Settings
| Property | Description |
|---|---|
| local-address | The local IP address for the MGCP stack. |
| local-port | The local port for the MGCP stack. |
| remote-address | The IP address for the media server. |
| remote-port | The port for the media server. |
| response-timeout | In milliseconds the maximum amount of time to wait for a response from the media server before abandoning the request. This does NOT apply to RQNT/NOTIFY request/response. |
| external-address | Sometimes there is interest to use a different address in the SDP than the IP address the media server is reporting. This parameter if set tells TelScale RestComm to patch the Connection attribute in the SDP on behalf of the media server to the specified IP address. Note: TelScale RestComm will only do NAT resolution when necessary so if your server already has a routable IP address setting this parameter will have no effect. |
The SMS aggregator is responsible for the handling of SMS messages on behalf of TelScale RestComm.
Requirements. The default SMS aggregator is SMS over IP as used by VoIP Innovations. Therefore, an account must be created @ http://www.voipinnovations.com before any text messages can be sent.
Below is a list of settings that must be configured to send text messages.
Table 2.6. SMS Aggregator Settings
| Element | Description |
|---|---|
| outbound-prepend-string | A string that you would like to prepend to the destination address. For example, to use service from VoIP Innovations a '#' must be prepended to every destination address. |
| outbound-endpoint | The SIP endpoint to which outbound SMS messages should be sent. Note: Do not prepend sip: to the endpoint. |
The fax service sends faxes out on behalf of TelScale RestComm.
Requirements. The default fax service is provided by Interfax. Therefore, an account must be created @ http://www.interfax.net before any faxes can be sent.
Table 2.7. Fax Service Settings
| Element | Description |
|---|---|
| user | The user name used to authenticate with Interfax. |
| password | The password used to authenticate with Interfax. |
This speech recognizer turns speech into text on behalf of TelScale Restcomm.
Requirements. The default speech recognizer uses the ASR service provided by iSpeech. Therefore, an account must be created @ http://www.ispeech.org before any speech can be converted to text.
Table 2.8. Speech Recognizer Settings
| Element | Description |
|---|---|
| api-key | The Web API key provided by iSpeech. This is used as an authentication token for the service. |
The speech synthesizer turns text to speech on behalf of TelScale RestComm.
Requirements. The default speech synthesizer uses the TTS service provided by VoiceRSS. Therefore, an account must be created @ http://www.voicerss.org before any text can be converted to speech.
Table 2.9. VoiceRSS Speech Synthesizer Settings
| Element | Description |
|---|---|
| service-root | The VoiceRSS service root URI. |
| apikey | The API key used to authenticate with the VoiceRSS. |
| languages | A list of male and female speakers for different languages. These can be replaced with other alternatives provided by VoiceRSS. |