Snom 4S Media Server Use and care manual













4
S
Administrator‘s
Manual
snom 4S
Calling Card System
Version 1.00
snom 4S Calling Card Application Chain
PSTN Network
SIP User Agents
snom 105
Softphone
snom 200
snom 4S
Registrar/Proxy
4
S
snom 4S
Media Server
4
S
SIP/PSTN
Gateway
Breakout
© 2004 snom technology AG
Application Server


snom technology AG • 3
snom 4S Calling Card System Version 1.00
Administrator Manual
1. Edition 2004
© 2004 snom technology Aktiengesellschaft. All Rights Reserved.
This document is supplied by snom technology AG for information purposes only to licensed
users of the snom 4S Calling Card´s Module and is supplied on an “AS IS” basis, that is,
without any warranties whatsoever, express or implied.
Information in this document is subject to change without notice and does not represent any
commitment on the part of snom technology AG. The software described in this document
is furnished under a license agreement and may be used only in accordance with the terms
of that license agreement. It is against the law to copy or use this software except as
specically allowed in the license. No part of this document may be reproduced, republished
or retransmitted in any form or by any means whatsoever, whether electronically or
mechanically, including, but not limited to, by way of photocopying, recording, information
recording or through retrieval systems, without the express written permission of snom
technology AG.

snom technology AG • 3
Table of Contents
1. Overview ................................................................5
2. Usage Scenario.......................................................7
3. Components ...........................................................9
3.1. SNOM 4S Proxy/Registrar .................................................... 10
3.2. SNOM 4S Mediaserver......................................................... 10
3.3. The Application Server ........................................................ 10
The Web Server.................................................................................................................................................................................... 11
The Database Server..................................................................................................................................................................... 11
The Application Logic.................................................................................................................................................................... 12
4. Installation...........................................................13
4.1. Installing the SNOM 4SProxyRegistrar ................................... 13
The Proxy Script................................................................................................................................................................................... 13
4.2. Installing the SNOM 4S Mediaserver ..................................... 18
Creating the Calling Card Account............................................................................................................................. 18
4.3. Installing the Application Server ........................................... 19
Installing the Web server ....................................................................................................................................................... 20
Installing the Database Server and the Calling Card database....................................... 21
Installing the Scripts ..................................................................................................................................................................... 25
5. Conguration .......................................................27
5.1. Conguring the interface between Proxy/Registrar and
Mediaserver ............................................................................. 27
Conguring the Dial Plan......................................................................................................................................................... 27
5.2. Conguring the interface between SNOM 4S Mediaserver and
Application Server..................................................................... 29
The HTTP GET interface ............................................................................................................................................................ 29
The XML state script ...................................................................................................................................................................... 30
6. Administering the Calling Card System.................33
6.1. Generating new Calling Cards .............................................. 33

4 • Table of Contents
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 5
6.2. Setting rates...................................................................... 34
6.3. Viewing card or rate information........................................... 34
Footnotes ................................................................................ 35
Index .......................................................................37

4 • Table of Contents
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 5
1
1. Overview
The SNOM 4S Calling Card (S4SCC) Module integrates the SNOM
4S Registrar/Proxy, the SNOM 4S Mediaserver and a back-end application
server to provide a fully-edged calling card system for pre-paid VoIP-to-
PSTN telephony.
It provides:
• PIN-based authentication and authorization
• Real-time accounting of calls.
• Customizable Interactive Voice Response (IVR) with full
multi-language support1
• Automatic generation of calling cards
• Web-based administration GUI
The S4SCC is accessed by registering with the SNOM 4S Proxy/
Registrar (S4SPR). The S4SPR handles primary authentication and keeps
track of all active users.
At the core of the calling card system lies the SNOM 4S
Mediaserver (S4SMS). The S4SMS is a versatile media server, which
provides media encoding/decoding as well as sophisticated back-to-back
user agent (B2BUA) functionality.
The S4SMS exposes a scriptable state engine, through which the
CC service can be adapted to individual needs.
At the end of the application chain lies an SIP/PSTN gateway,
which is external to the system. Any RFC3261-compliant SIP/PSTN
gateway is suitable.

6 • Overview
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 7
1

6 • Overview
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 7
2
2. Usage Scenario
End-Users of the S4SCC system buy a telephone card with a 12-
digit card ID and a secret 4-digit PIN. They access the system with an
S4SCC-compliant SIP user agent (SUA).
The client needs to register with the calling card operator’s SIP
domain, using the card ID as the SIP user name and the PIN as the SIP
password.
Example:
Operator’s SIP domain: cccall.com
IP address of SIP registrar in charge of cccall.com: 123.123.123.123
Card number: 123456789012
PIN: 1234
Register Command
REGISTER sip:123.123.123.123 SIP/2.0
From: <sip:[email protected]>;tag=XXXX
To: <sip:[email protected]>
....
Upon receiving this REGISTER request, the registrar sends back
an
SIP/2.0 407 Proxy Authentication Required
The user enters his password (alternatively, he may have
precongured it with his SUA) and the SUA re-sends the REGISTER
request with the required authentication information. If the authentication
information matches the database of valid and active calling cards, the
registrar sends back a
SIP/2.0 200 OK

8 • Usage Scenario
snom technology AG • 9
2
Via:....
From: <sip:[email protected]>;tag=XXXX
To: <sip:[email protected]>
X-SNOM-CCTOKEN: 98765432
This response contains a proprietary “token”2, which provides
the SUA with a secure way of accessing the S4SCC without needing to
re-authenticate at each request. The token is valid for the duration of the
registration. Upon re-registering, a new token is issued. The client needs to
be compliant with this protocol extension.
Once the registration sequence described above has been
completed, the user can place calls, which will be charged to his calling
card.
The S4SCC application server backend contains a rate table that
determines which country and city codes can be accessed and how much
they cost. Each calling card is assigned to one rate table in order to allow
the operator to offer different cards with different pricing models.
The user places a call by dialing the telephone number of
his (PSTN) counterpart. The S4SCC will verify that this is a reachable
destination and establish the connection via the SIP/PSTN breakout
gateway.
Accounting starts after the media connection between SUA and
PSTN counterpart has been established.
The SNOM 4S Mediaserver at the core of the system goes through
a state transition after each billing period. Based on this transition, the
accounting database is updated and real-time balance information is
sent to the SUA3. All accounting and billing is based on this real-time
accounting information.

8 • Usage Scenario
snom technology AG • 9
3
3. Components
The main components have already been described. The following
image shows their interaction.

10 • Components
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 11
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
3
3.1. SNOM 4S Proxy/Registrar
The S4SPR acts as the authentication and authorization gateway
to the system. Its user information needs to be synchronized with the
user database in the application server.
It forwards all authenticated calls to the media server, which
is congured through the dial plan. The token-based authentication/
authorization is congured using a proxy script.
The actual settings and scripts will be described in the
“Conguration” section.
3.2. SNOM 4S Mediaserver
The calling card system core component is a special B2BUA within
the media server4. It is based on the model of a state machine, which can be
scripted through a simple XML-based conguration language.
Although it is based on a state machine model, it is stateless in that
it keeps no call state in its memory space5.
All call state is kept in the application server (AS; see below). The
Mediaserver interacts with the AS through simple HTTP GET requests. It
initializes state for each call through a request to
http://<application_server>/cc/cc_init.php.
This request generates a session ID and passes it back to the Calling
Card B2BUA. This session ID is used in all interactions with the application
server.
3.3. The Application Server
The application server consists of:
1. A web server (Apache)
2. A database server (MySQL)

10 • Components
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 11
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
3
3. The application logic (written in PHP and Perl)
The Web Server
We are currently using Apache 2.0.48 with SSL support. No other
special features are needed.
The Database Server
We are currently using MySQL 4.0.16. No special features are
needed.
The database itself is quite simple, with an ERD given below:

12 • Components
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 13
3
The Application Logic
Most of the application logic is written PHP 4. For some batch
utilities we use Perl 5. The main scripts are:
1 cc_init.php Initializes state for one call. Validates
card number and destination
number.
Returns: session ID
2 cc_rate.php Sets the most important parameters
for the calling card module:
balance, credit, rate, period
As a side effect, instantiates the
main server side objects (cc_call and
cc_customer)
3 cc_charge.php Charges the card one unit at the set
rate. Accounting is done in real time
by writing to the DB
Returns current balance
4 cc_call_end.php Writes CDR to database. Ends call.
A cc_generate_cards.php Generates a new batch of calling
cards and sends result as
(“Card ID”;”PIN”) to Email specied
B cc_import_cards.php Imports cards from a le
C cc_show_cardInfo.php Displays Calling Card information
D cc_import_rate.php Imports rate information from a le
E cc_show_rate.php Displays rate information
Pages 1-4 are used to interact with the Mediaserver.
Pages A-E are used to administer the system.

12 • Components
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 13
4
4. Installation
Installation consists of the following main steps:
• Install the SNOM 4S Proxy/Registrar
• Install the SNOM 4S Mediaserver
• Install the Application Server
o Install the Web server
o Install the Database Server
o Import the Callingcard database
o Include the PHP scripts to a directory served by the Web
server
4.1. Installing the SNOM 4SProxyRegistrar
There are no special installation procedures beyond the standard
SNOM 4S Proxy/Registrar installation.
Please refer to the SNOM 4S Proxy/Registrar documentation.
Once installed, you will need to set up the SIP domain for the CC
system and congure your DNS accordingly. We will assume the domain
name cccall.com.
Please also verify that the Proxy script needed for the “X-SNOM-
CCTOKEN” extension is included.
The Proxy Script
The following proxy script needs to be set:

14 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 15
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
user_directory($user)
{
return rightstr($user,3);
}
on_register($user, $nat, $t) {
if ( $nat == “” ) {
$cctoken = random(100000,400000);
register($user,$t, $nat,$cctoken);
if ( registered($user) )
{
set_parameter($user, “cctoken”, $cctoken);
}
} # of nat
else {
if ( !$reject_nat_register) {
if ( $ka_regtime == “ “) { $t = 20; }
else {
$t = $ka_regtime;
}
$cctoken = random(100000,400000);
set_parameter($user, “cctoken”, $cctoken);
register($user,$t, $nat,$cctoken);
if ( registered($user) )
{
set_parameter($user, “cctoken”, $cctoken);
}
} # if !reject_nat
else {
reject_request(“406 Bad Contact (NAT)”);
}
}
}
on_request() {
$user = parse_user($request_uri);
if ($account != “” && get_parameter($account, “disabled”)) {
# someone disabled this account
reject_request(“402 Account Disabled”); # default
}
else if (parse_scheme($request_uri) == “tel”) {
# convert the telephone number into an enum sufx

14 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 15
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
proxy_dest($request_uri);
}
else {
# speed dial translation step:
parse_user($request_uri);
if (in_domain($from)) {
$speed = speed_dial(parse_user($from), $user);
if($speed != “”) {
$request_uri = create_number($speed);
$user = parse_user($request_uri);
}
}
$from_user = parse_user($from);
$cctoken = get_parameter($from_user,”cctoken”);
$sentToken = get_eld($user,”1”,”+”);
if ($sentToken == $cctoken)
{
if ( $method == “INVITE” )
{
if (known($user)) {
if ($method == “INVITE”) {
$type = get_parameter($user, “type”);
if ($type == “hunt”) {
proxy_hunt($user);
}
else {
proxy_normal_user($user);
}
} # method == INVITE
else if ($method == “MESSAGE” && !registered($user)) {
# store & forward:
store_message($user);
reject_request(“200 Message Delivered”); # default
}
else {
# default action
if (registered($user)) {
proxy_user($user, $seqfork_delay);
}

16 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 17
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
else {
reject_request(“404 Not Registered”);
}
} # other methods
} # known user
else {
# no for a known user:
if (!exec_dialplan(parse_url($from), $request_uri, $request_uri, $allow_
pattern)) {
reject_request(“404 Unknown User”); # default
}
}
} # if METHOD == INVITE
} # if tokens matched
else
{
reject_request(“403 Forbidden invalid OSP Token”);
}
} # else speed dial
} # on_request
# handle posts to the proxy domain, set the variables to the values
# provided in the post request.
on_post() {
if ($action == “create_user” && $account != “” && $username != “”) {
create_user($account, $username, $password);
set_parameter($account,”single”,”true”);
return “Ok”;
}
else if ($action == “delete_user” && $account != “”) {
delete_user($account);
return “Ok”;
}
else if ($action == “disable_user” && $account != “”) {
set_parameter($account, “disabled”, “true”);
return “Ok”;
}
else if ($action == “enable_user” && $account != “”) {
set_parameter($account, “disabled”, “false”);
return “Ok”;
}
else {
return “Unhandled Request”;
}
}

16 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 17
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
You can verify that the script is included by going to the “Domain
Preferences”->”Script” page of your SIP domains administration page on
the S4SPR.
If the script is not set, you can copy the script included above and
paste it into the text window. Then press “Save” and the script should be
loaded.

18 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 19
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
4.2. Installing the SNOM 4S Mediaserver
Creating the Calling Card Account
Make sure you have a Callingcard license. You can verify this by
looking at your license string, which should start with the string “snom-
media-cc1”.
Install the SNOM 4S Mediaserver as per its documentation.
Verify that the Calling Card state script is in the correct location.
It should be in
<Your Mediaserver’s runtime directory>/xml/callcard.xml
You can verify your Mediaserver’s runtime directory by checking
its start-up conguration le (/etc/rc.cong on SuSE Linux, /etc/
mediaserver.conf on RedHat).
Once you have veried this, go to the main administration page
of your Mediaserver.
• Click on Accounts.
• Type in the name of the account. We will assume “cc”.
• Select “Calling Card Type 4” from the “Type” pulldown.
• Click on “Add”
This creates the CC B2BUA on your SNOM 4S Mediaserver. This
account is the account addressed by the S4SPR’s dial plan (described
below).

18 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 19
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
You will also need to provide an SIP subdomain for the
Mediaservers and congure your DNS accordingly. We assume a domain
name of ms.cccall.com.
4.3. Installing the Application Server
The Application Server consists of
• A Web server:
• A Database server: MySQL 4.0.16
• The Calling Card database
• Application logic in the form of PHP4 and Perl5 scripts

20 • Installation
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
snom technology AG • 21
[ S N O M 4S CALLING C A R D S YSTEM A D M I N I S T R A T O R M ANUAL ]
4
You will also need cURL, a command-line handling URL utility.
This can be downloaded from http://curl.haxx.se/ .
In this section we will assume both the web server and the
database server to have been installed and running.
Here, we will only describe the installation steps that are specic
to the S4SCC system.
Installing the Web server
We recommend using Apache (version 2.0.x). Please refer to
www.apache.org for installation instructions of the Apache web server.
However, any Web server capable of serving PHP4 scripts will be
suitable.
Apache is congured through a conguration le called
httpd.conf.
The following excerpt shows the only settings specic to the
S4SCC:
LoadModule php4_module modules/libphp4.so
:
:
Alias /cc/ “/ourPHPDirectory/”
:
:
User snom