Snom 4S Media Server Use and care manual

Administrator‘s
Manual
snom 4S
SIP Proxy/Registrar
Version 2.30

snom technology AG • 3
snom 4S Registrar Proxy Version 2.30 User Manual
© 2003 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 registrar proxy 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
Welcome to the
SIP World!
SIP is becoming more and more accepted in the area of VoIP.
Many companies are working on SIP solutions and making great products
that will make telephony much easier and better.
SIP without a proxy makes no sense. Entering IP addresses to nd
another user cannot be the future of telephony. Locating http web content
and nding email users has become a part of todays communication
behavior and sure will be part of telephony in the near future.
snom 4S stands for “snom soft switch for small and medium
enterprises“. We started the work on this proxy with the goal to give
business a feature rich, robust and simple to use core component. Over
time, we found that it can also be used in other environments like Internet
telephony service provider. We added features that are necessary for
billing and worked on remote management support. If you set up a server
farm, you can create a robust solution that will continue operations even
under adverse conditions.
This product is a proxy/location server with built-in registrar
which means this software is also responsible for locating users. Needless
to say, the proxy is stateful, which means that is is capable of nding
users on a priority based schedule. However, for simplicity we call ist just
“proxy”.
Features like follow me and group calling are supported. As long
as the involved user agents support features, the proxy will he happy to
pass them through. That also includes instant messaging and presence
information. The proxy supports “store & forward”, when a user is not
logged in he or she may receive the message after loggin in. However
media services like mailbox and music on hold are not part of the software.
You should use a media server for this.
Interoperability is important to us. We have tried to stick to the
SIP standard as well as possible and tested the phones of other vendors.

4 • Welcome
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 5
We hope that this will help to build up a ourishing VoIP telephone
industry in which the products of the different vendors work together like
the products in the computer industry do today. We believe that having a
choice is good for you and therefore good for us.
This manual gives you a brief introduction to VoIP and SIP,
explains the installation process for Windows and Linux and shows how
to run the SIP proxy. For additional snom 4S information, please visit
our Web site at http://snom.com and if you have any comments and
suggestions about snom 4S, please contact us through snom technology
AG’s support link Web site. We would appreciate your feedback.
And, of course, you can reach us at sip:[email protected]
Thank you and have fun using the snom 4S!
Dr. Christian Stredicke Nicolas Peter-Pohland

4 • Welcome
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 5
Table of Contents
Welcome to the SIP World! ........................................3
Read This First ...........................................................9
Upgrades................................................................................... 9
Additional Information................................................................. 9
Scripting.................................................................................. 10
The Voice over Internet Protocol..............................11
Why SIP?................................................................................. 11
Open Standards ....................................................................... 12
What You Can Expect and What Not ............................................ 13
The SIP Architecture ................................................15
User Agents ............................................................................. 15
Proxies.................................................................................... 16
Location Server ........................................................................ 16
Registrars ................................................................................ 17
Media Server............................................................................ 17
Gateways ................................................................................ 17
B2BUA .................................................................................... 19
Installation ..............................................................21
Update to 2.30 from Previous Versions ........................................ 21
Windows Installation ................................................................. 23
Uninstalling in Windows ............................................................. 24
Linux Installation ...................................................................... 24
Manual Starting..................................................................................................................................................................................... 24
Automatic Starting ........................................................................................................................................................................... 25
Licensing ..................................................................27
Accessing the web server .......................................................... 27
Entering the license code ........................................................... 28

6 • Contents
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 7
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
Domains ...................................................................29
Deriving settings ...................................................................... 29
Creating a domain ................................................................... 30
Deleting a domain..................................................................... 31
Edit a domain........................................................................... 31
Going to a domain context ......................................................... 31
Backup ................................................................................... 32
Scripting...................................................................33
Background ............................................................................. 33
Script Structure........................................................................ 34
Quotes................................................................................................................................................................................................................ 34
Case....................................................................................................................................................................................................................... 35
Statements.............................................................................. 35
if.................................................................................................................................................................................................................................. 35
foreach............................................................................................................................................................................................................... 36
return................................................................................................................................................................................................................... 37
Variables ................................................................................. 37
Scope................................................................................................................................................................................................................... 37
Types.................................................................................................................................................................................................................... 37
Operators....................................................................................................................................................................................................... 38
Functions................................................................................. 39
Denition........................................................................................................................................................................................................ 39
Calling................................................................................................................................................................................................................. 40
String Functions ................................................................................................................................................................................... 40
Parsing Functions ............................................................................................................................................................................... 42
SIP functions............................................................................................................................................................................................. 44
Registration Related Functions....................................................................................................................................... 45
Proxy Related Functions........................................................................................................................................................... 46
Other Functions..................................................................................................................................................................................... 48
Callbacks................................................................................. 49
on_request................................................................................................................................................................................................... 49
on_response .............................................................................................................................................................................................. 51
on_register .................................................................................................................................................................................................. 52
challenge ........................................................................................................................................................................................................ 52
get_user .......................................................................................................................................................................................................... 54
on_new_user............................................................................................................................................................................................ 54
user_directory......................................................................................................................................................................................... 55
require_billing ......................................................................................................................................................................................... 56
on_denial........................................................................................................................................................................................................ 57

6 • Contents
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 7
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
on_unroutable......................................................................................................................................................................................... 58
General Setup...........................................................59
General Settings....................................................................... 59
SIP Port............................................................................................................................................................................................................. 59
STUN port...................................................................................................................................................................................................... 60
TCP threshold........................................................................................................................................................................................... 60
Log Level ........................................................................................................................................................................................................ 60
Log Filename............................................................................................................................................................................................. 60
HTTP port....................................................................................................................................................................................................... 61
HTTP User and Password......................................................................................................................................................... 61
Conguration in XML..................................................................................................................................................................... 61
User Accounts ..........................................................63
Purpose................................................................................... 63
Setting up accounts from the web interface.................................. 64
Uploading user accounts from le .............................................. 64
Storing information .................................................................. 65
Registration .............................................................67
Registration Settings ................................................................. 67
Require Authorization................................................................................................................................................................... 67
Min and Max registration time......................................................................................................................................... 68
Default Q ........................................................................................................................................................................................................ 68
Reject Registrations Across NAT .................................................................................................................................. 68
Example Registrations ............................................................... 69
Snom 200 .................................................................................................................................................................................................... 70
Microsoft Messenger .................................................................................................................................................................... 71
Routing ....................................................................73
Protected Destinations................................................................................................................................................................ 73
Max Forwards........................................................................................................................................................................................... 74
Call Log File ................................................................................................................................................................................................ 74
Tel Domain................................................................................................................................................................................................... 74
ENUM Sufx................................................................................................................................................................................................ 74
NAT Gateway............................................................................................................................................................................................ 74
Do not signal loose routing.................................................................................................................................................. 75
Do not Record-Route if Route is present.......................................................................................................... 75
Sequential Forking Time .......................................................................................................................................................... 76
Dial Plan.................................................................................. 77

8 • Contents
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 9
How it works.............................................................................................................................................................................................. 77
Example 1: Setting up overlap dialling............................................................................................................... 79
Example 2: North American Dial Plan .................................................................................................................. 80
Example 3: Do not allow cell phone numbers to certain users........................................ 80
Example 4: Using ENUM ............................................................ 81
Error-Information ..................................................................... 82
Message Handling ....................................................85
Store & Forward ....................................................................... 85
Welcome Message..................................................................... 85
DNS ..........................................................................87
What is DNS? ........................................................................... 87
Setup DNS............................................................................... 87
Server Farm Operation .............................................................. 89
ENUM...................................................................................... 90
Registering Phones ..................................................91
snom 100 Registration............................................................... 91
Microsoft Messenger Registration ................................................ 92
Maintenance.............................................................93
Registered Users ...................................................................... 93
Call Logs ................................................................................. 94
Condition for Logging a Call................................................................................................................................................ 94
Call Logs in the Web Interface........................................................................................................................................ 95
Pending Calls ............................................................................................................................................................................................ 96
Call Log File Format........................................................................................................................................................................ 96
SIP Message Flow ..................................................................... 97
Logging ................................................................................... 99
Index .....................................................................101

8 • Contents
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 9
Read This First
Before you read this manual please note the following three
important notes.
Upgrades
The 2.30 edition of the proxy does not require any additional
licenses. However, it is a major version update that could also carry the
name 3.0. In order not to confuse the licensing terms we chose the name
2.30.
The proxy keeps many of the proven concepts of the previous
versions, however introduces scripting and domains which makes it hard
for the installation process to automatically convert the conguration
data from the previous proxy versions into the new version. Some of the
settings need manual revision.
Therefore, if you update the proxy, we ask you to save old
conguration information for later reference. You can do this easily by
storing the web content of the relevant conguration pages to a le.
The installation process has been inproved especially for the
RedHat Linux edition and should now work smoothly on most systems.
That was especially on the 2.22 version one of the biggest problems for
installation.
Additional Information
This manual does not cover all topics that are related to the
usage of the proxy. We keep a list of frequently asked questions (FAQ) on
our website at http://snom.com/faq_en.php for specialized topics such as
remote management via shell script. They also contain topics that affect
other SIP components like the media server or the phones. These FAQ will
be kept up-do-date on a higher frequency than this proxy.

10 • Read This First
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 11
We also keep a list of bugxes in the Release Notes which is
available at the software download site at http://snom.com/down4s_
en.php. Before you make a software update, you make check this
document if the update is necessary or not.
Scripting
This version introduces “Scripting”. That means you may program
your proxy to exactly meet your requirements.
However, it is not a must. The default script takes the settings
from the web interface and allows the operation of the proxy that ts most
small and medium business requirements. So if you are not interested in
scripting you may skip the scripting chapter of this manual.

10 • Read This First
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 11
The Voice over
Internet Protocol
Today there is a wide choice of different switched network
products. Telephones have now been being built for more than a century,
and their technology is well-understood and proven. Why choose a
different technology?
Modern communication infrastructures transport much more than
just one application: email, http, les, instant messages, videos, music,
so it is only natural to include voice in the list of applications and use one
infrastructure for all of them.
Voice is a real time application. Sending voice over the Internet
Protocol is called “VoIP”. The delay between sending a packet to the
network and receiving it needs to be minimal and constant and this makes
specic demands on this application.
Most network equipment can already full this real time
requirement. Virtually all switches currently on sale support a VLAN with
different priorities in the network, and the vast majority of higher layer
network equipment supports some means of transporting packets with
different qualities (DiffSrv). The LAN usually supports a bandwidth of
100 MBit/s, which is more than enough to allow voice to ow through
the network, and adherence to a certain set of rules ensures that this
bandwidth is enough to supply superior telephone quality. The Internet
backbone’s ability to transport large loads is increasing on a daily basis,
and global communications are now ruled by the Internet. Making calls
over the public Internet for example between Europe and North America
works with a surprisingly good quality.
Why SIP?
There has been a “protocol war” regarding the “best” way to set
up a phone call. In the mid 90s, H.323 was the rst attempt to unify the
1.

12 • VoIP Protocol
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 13
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
VoIP industry under a common standard,and move the world of telephony
into the computer industry, using most of the methods known from ISDN.
Seen however from today’s perspective, the resulting technology was too
complex, so products based on this technology did not work well together.
The late introduction of “supplementary services” (H.450.x) not only
introduced another level of complexity, but was also simply too late.
By the late 90s, the Session Initial Protocol (SIP) had been
proposed (RFC 25431). SIP follows the paradigms of the Internet, and is
built upon the same principles used by http and email. Moreover, it has
found an enthusiastic community of researchers and developers who like
the idea of applying Internet technology to real time communications.
More and more applications are being put into SIP, telephony being just
one of them.
So far more than 200 drafts have been proposed for extending
the SIP protocol. All kinds of solutions are being addressed in these
documents, and the highly dynamic eld of this new real time
communication technology is resulting in evolutionary pressure to nd the
best common denominator. RFC3261 can be seen as the core or a series
of new RFC that dene the rules of the new telephony industry just like
DNS, HTTP and other standards already did for the world wide web.
Most of the “big players” have jumped on the SIP train. Microsoft
Messenger 4.7 is based on SIP and Cisco Systems offers SIP extensions
to most of its products. International organizations like ETSI host SIP
interoperability events, and next generation mobile technology will be
integrated with, if not based on, SIP (see http://www.3gpp.org for more
details).
Other protocols like MEGACO (H.248) seem to play only a role
in niches. The “Skinny” protocol proposed by Cisco Systems can only be
used by Cisco proprietary products which limits the choice signicantly.
Other vendors like Siemens also extend their PBX solutions by more
or less propretary solutions. We believe that can only be a temporary
solution, as customers do not want to be dependant upon a single supplier
for their most critical systems.
Open Standards
Open standards dene the rules of the game. Interoperability
allows customers to choose between the products of different vendors and
1.

12 • VoIP Protocol
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 13
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
opens up competition below the system level. This can be advantageous
for the customer, as the computer hardware industry has shown.
Many vendors therefore advertise their usage of an “open
standard”, dening this term as “we make the way our standard works
public”. However, this cannot really be called “standard” if only one vendor
is using it. The disadvantage is that customers still have a limited choice
of products they can buy.
There is no one objective denition of an open standard. However,
something approaching an open standard could be reached if a signicant
number of vendors offered products using the same standard, giving
customers the possibility of combining products to create a system. SIP
is just such a standard.
What You Can Expect and What Not
Telephony is more than making calls from A to B. SIP supports
all kinds of transfers, call parking and call picking, user searches (Follow-
me), mailbox support, and all the other features known from traditional
telephony. In addition to this, telephones can now indicate their willingness
to receive calls and the probability of nding a specic user.
You can call a PSTN number from a SIP phone just as you did ten
years ago. The network will usually be set up to terminate these calls on
a gateway which translates the packet stream into a switched network
signal. You can also dial email-like numbers like “sip:fred.intstone@
megaportal.com”, and you can reach your sales team under the same
telephone number and email address.
Internet telephony is still a “best effort” communications
technology and does not always necessarily support the quality of
transport telephony requires. If you are placing a phone call over the
public Internet, there is no guarantee that a packet will be transported
within a reasonable time. Usually there is acceptable quality, but it may
happen that calls suddenly break off, that there is signicant delay, or
that packet loss causes stuttering. It is important that users know what
to expect: Cell phone users know that driving through a tunnel may break
the call, and Internet telephony users must be aware that talking for free
over their DSL atrate may compromise call quality.
1.

14 • VoIP Protocol
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 15
1.

14 • VoIP Protocol
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 15
The SIP
Architecture
This paragraph is intended to serve only as a basic introduction to
the SIP world. for more detailed information please refer to the available
literature on this topic.
User Agents
User agents play a central role in SIP. They are normally the
endpoints of the communication. Typical examples for a user agent are
telephones, gateway and media servers.
User agents typically fulll the following tasks:
• they play and record audio,
• they compress and uncompress the digital audio,
• they do echo compensation if there is a need for this,
• they compensate for packet jitter and packet loss,
• they look for the destination,
• they retrieve their conguration information,
• they keep track of phones that offer a call pickup,
• they publish their state upon request,
• they determine and publish the probability of nding somebody,
• they terminate one or more identities,
• they redirect calls when nobody picks up,
• they are part of a virtual LAN,
• they search address books (LDAP),
• they search internet addresses (DNS A, DNS SRV),
• they usually include a web server,
• they send an receive instant messaging information,
• they publish network management information (SNMP),
• they behave like normal computers on the network (DHCP, DNS).
2.

16 • SIP Architecture
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 17
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
As you can see, in contrast to the traditional PBX model, SIP user
agents fulll most of the tasks that are needed in telephony. This follows
the model of the intelligent client which made the PC so popular as it is
today.
A user agent may be client or server in a SIP transaction. The
user agent client (UAC) is the user agent that requests something, the user
agent server (UAS) answers this request. The role may change during a
call, depending on who wants to initiate something. For example, A may
initiate a call to B. Then A will be the user agent client while B the is the
user agent server. When B decides to hang up, B will be the user agent
client while A is the user agent server.
Proxies
Proxies forward requests and help the user agent carry out its
tasks. Stateless proxies just forward messages and serve as a “hop” on
the path from a user agent client to a user agent server. The rules for
hopping may depend on all kinds of rules, e.g. traversing NAT using a
stateless proxy.
Stateful proxies keep a list of pending requests. This way proxies
can forward requests to different destinations at the same time. When
the responses come back from the destinations, the proxy merges the
responses, determines the best result and passes it down to the user
agent that sent the request (UAC). The snom 4S proxy is a stateful proxy
with some B2BUA extensions.
Location Server
From RFC3261 we read: “A location service is used by a SIP
redirect or proxy server to obtain information about a callee‘s possible
location(s). It contains a list of bindings of address-of-record keys to zero
or more contact addresses. The bindings can be created and removed in
many ways; this specication denes a REGISTER method that updates
the bindings.”
In other words, the location server nds out where a request to a
domain the proxy feels responsible for should go.
2.

16 • SIP Architecture
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 17
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
Registrars
User agents register with a registrar. When a request for the user
agent arrives at the registrar, it redirects the request to the location that
was previously stored in the internal database.
The registrar is the part of the location server that can be
controlled with REGISTER requests. So snom 4S Proxy/Location Server
would be a better name for the product.
Media Server
Strictly speaking, the media server is just a special kind of user
agent. Typically it is able to deal with several calls at the same time and
is a located on a PC or workstation.
The media server has the following tasks:
• Implement mailbox function. When a user is absent, the user
agent of the stateful proxy redirects the call to the mailbox, so that
the caller may leave a message. The owner of the mailbox calls the
mailbox directly to listen to messages.
• Implement music on hold. Using a fat client, all kinds of music
tastes can be played with highest possible quality.
• Implement call parking. Calls can be parked on the media server
until a user picks the call for processing. In the meantime, the
caller can enjoy the music on hold, using DTMF keys to select his
favourites.
• Implement conferencing services. Three or more persons dial
into the conference server, which mixes the audio streams for
each participant and also noties them of participants joining and
leaving the conference. The conference server also checks the
credentials of participants joining the conference. The snom 4s is
an example of this technology.
Gateways
From a SIP perspective, the gateway is also just a user agent.
Instead of playing the audio stream on a speaker, it sends it to the PSTN
2.

18 • SIP Architecture
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 19
network and instead of getting voice from a microphone it retrieves
signals from the switched network.
There are three kinds of gateways; PSTN, proxy signalling and
NAT gateways.
Depending on the nature of the gateway, it may serve one, two,
four, thirty, sixty or more channels at the same time.
Other gateways may translate the signal to existing H.323
networks or other proprietary technology networks. These gateways
are sometimes called signalling gateways. snom does not produce SIP
gateways. Examples of such gateways are manufactured by Cisco,
Mediatrix, Sonus and Vegastream. The snom 4S gateway is a SIP NAT
gateway software enabling Linux computers to be SIP-aware.
B2BUA
The back-to-back user agent (B2BUA) looks like a user agent, but
is a network component like a proxy. Making a call though a B2BUA puts
two user agents back to back. This has several advantages:
One side can be SIP, the other side can be anything, including
H.323, MGCP or SS#7. That solves many tricky interoperability problems.
Operations like transfer or keeping calls alive can be initiated by the
B2BUA. That makes it possible to use dumb components which are not
able to support these features.
The price for these advantages is an increased complexity in the
software that is sometimes hard to handle. For example, initiating a transfer
between H.323 and SIP devices is very complex and complicated.
2.

18 • SIP Architecture
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 19
Installation
Update to 2.30 from Previous Versions
Version 2.30 introduces a domain concept which is not directly
compatible to previous versions. The conguration information is stored
in a central directory, along with all other conguration information. The
previous versions used a more distributed approach.
Figure 3-1: Installation Welcome Screen
3.

20 • Installation
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
snom technology AG • 21
[ S N O M 4S PR O X Y / R E G I S T R A R M ANUAL ]
All conguration information is now stored in an XML-based for-
mat in the le system. This approach makes it easier to maintain the soft-
ware across the various platforms and allows you to use standard tools
to maintain the conguration data e.g. for backup or revision control. The
XML les can be retrieved via the web interface which simplies the sup-
port for the product across the Internet.
Although much of the interface remains the same, the software
update process cannot automatically convert the old conguration infor-
mation into the new format. Therefore, it is necessary to enter the con-
guration information up again.
In case that you use an extensive dial plan, we recommend tak-
ing a look at the scripting interface as it solves most of the open issues
with the table based dial plan. However, for simple installations you can
still use the dial plan.
Figure 3-2: Installation License Agreement
3.