Snom 4S SIP Proxy, 4S Proxy 2.44 Administrator's Manual

Administrator‘s
Manual

snom 4S

SIP Proxy
Version 2.44

snom 4S Proxy Version 2.44 Administrator Manual

3. Edition 2005 (Version 2.44.6)

© 2005 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 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
specifically 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 Foreword .......................................................7

1.1 Software Updates from 2.42 ............................................ 7

1.2 Software Updates from 2.2x ............................................ 8

1.3 Additional Information .................................................... 8

2 Installation ...................................................9

2.1 Windows ....................................................................... 9

2.1.1 Installation

..............................................................................................................................................................................

9

2.1.2 Uninstalling in Windows

...................................................................................................................................

13

2.2 Linux .......................................................................... 13

2.3 Command Line Options ................................................. 14

2.4 Migrating 2.42 Files ...................................................... 15

2.7 DNS Setup .................................................................. 15

2.7.1 DNS Example

..................................................................................................................................................................

16

2.7.2 Using the Proxy without DNS

...................................................................................................................

17

3 Domains ......................................................19

3.1 Creating a domain ....................................................... 20

3.2 Deleting a domain ........................................................ 20

3.3 Edit a domain .............................................................. 21

3.4 Going to a domain context ............................................ 21

3.5 Determining the Domain Context ................................... 21

3.5.1 Purpose

....................................................................................................................................................................................

21

3.5.2 Usage

..........................................................................................................................................................................................

22

3.6 Backup ....................................................................... 22

4 Login ...........................................................25

4.1 Sessions ..................................................................... 25

4.2 Login .......................................................................... 25

4.3 Creation of Accounts .................................................... 26

4.4 Logout ........................................................................ 27

5 System Settings ..........................................29

4 • Table of Contents

[ S N O M 4 S P R O X Y M A N U A L ]

5.1 License ....................................................................... 29

5.2 Port Bindings ............................................................... 30

5.2.1 Binding to the right address

......................................................................................................................

30

5.2.2 Receiving forwarded packets

....................................................................................................................

31

5.2.3 SIP, HTTP and RADIUS Port

.......................................................................................................................

32

5.2.4 STUN Settings

................................................................................................................................................................

32

5.3 System Settings .......................................................... 33

5.3.1 Logging

....................................................................................................................................................................................

33

5.3.2 Caches

.......................................................................................................................................................................................

34

5.3.3 Subscription Size

.......................................................................................................................................................

35

5.3.4 Unavailable Hosts

.....................................................................................................................................................

35

5.3.5 Agents

.......................................................................................................................................................................................

36

5.3.6 Number Guessing

.....................................................................................................................................................

36

5.3.7 Directories

...........................................................................................................................................................................

36

5.3.8 Email

............................................................................................................................................................................................

37

5.3.9 Configuration in XML

............................................................................................................................................

38

5.4 Security Settings ......................................................... 38

5.4.1 https/http Access

......................................................................................................................................................

38

5.4.2 Administrator Access

...........................................................................................................................................

40

5.4.3 Importing Certificates

.........................................................................................................................................

40

5.5 Billing Settings ............................................................ 41

5.5.1 RADIUS Settings

........................................................................................................................................................

42

5.5.2 RADIUS Scripting

......................................................................................................................................................

43

5.6 Domain Determination/Administration ............................ 45

5.7 Routing Settings .......................................................... 45

5.7.1 Max Forwards

.................................................................................................................................................................

45

5.7.2 ENUM Suffix

......................................................................................................................................................................

46

5.7.3 Route Other Requests

........................................................................................................................................

46

5.7.4 Loose Routing

.................................................................................................................................................................

46

5.7.5 Loose Routing Flag

..................................................................................................................................................

47

5.7.6 Always Record-Route

...........................................................................................................................................

47

5.7.7 Record-Route for SUBSCRIBE

.................................................................................................................

47

5.7.8 Symmetric Responses

........................................................................................................................................

48

5.8 Redundancy ................................................................ 48

5.8.1 Shutting servers down

.......................................................................................................................................

49

5.8.2 DNS considerations

................................................................................................................................................

49

5.8.3 Refresh rate considerations

........................................................................................................................

50

5.8.4 How Replication Works

......................................................................................................................................

50

5.8.5 Exceptions

...........................................................................................................................................................................

51

5.8.6 Settings

...................................................................................................................................................................................

51

5.8.7 Security

...................................................................................................................................................................................

52

snom technology AG • 5

[ S N O M 4 S P R O X Y M A N U A L ]

5.9 Appearance ................................................................. 52

6 System Status .............................................55

6.1 Server Log .................................................................. 55

6.2 Call Log ...................................................................... 55

6.3 Current Calls ............................................................... 56

6.4 SIP Trace .................................................................... 57

6.5 Replication Trace .......................................................... 58

6.6 Unavailable Hosts ........................................................ 58

6.7 Memory Usage ............................................................ 58

6.8 System Information ..................................................... 59

7 Domain Settings ..........................................61

7.1 Settings ...................................................................... 61

7.1.1 Similar Settings

...........................................................................................................................................................

61

7.1.2 Emergency Location Information

.......................................................................................................

61

7.1.3 Authorization

...................................................................................................................................................................

62

7.1.4 Canonical Names

.......................................................................................................................................................

63

7.2 Registration Preferences ............................................... 63

7.2.1 Self-Setup

............................................................................................................................................................................

63

7.2.2 Min/Max Registry Time

.....................................................................................................................................

64

7.2.3 Default Probability

...................................................................................................................................................

64

7.3 Dial Plan ..................................................................... 64

7.3.1 How it works

....................................................................................................................................................................

64

7.3.2 Call Pickup

...........................................................................................................................................................................

67

7.3.4 DND Feature Codes

................................................................................................................................................

67

7.3.5 Example 1: North American Dial Plan

.........................................................................................

68

7.3.6 Example 2: Do not allow cell phone numbers to certain users

...............

68

7.4 Controlling .................................................................. 69

7.4.1 Defining Rates

...............................................................................................................................................................

69

7.4.2 Defining Groups

...........................................................................................................................................................

70

7.4.3 Controlling Data

..........................................................................................................................................................

70

7.5 Address Books ............................................................. 71

7.5.1 Number Guessing

.....................................................................................................................................................

71

7.5.2 Defining Address Book Groups

..............................................................................................................

71

7.5.3 Setting Up an Address Book

......................................................................................................................

72

7.6 Error-Information ......................................................... 72

7.7 Script ......................................................................... 73

7.8 Account Administration ................................................. 73

7.8.1 Purpose

....................................................................................................................................................................................

73

7.8.2 Setting up an account from the web interface

...............................................................

74

6 • Table of Contents

[ S N O M 4 S P R O X Y M A N U A L ]

7.8.3 Setting up a hunt group and pickup group

..........................................................................

76

7.8.4 Changing Normal User Settings

...........................................................................................................

77

7.8.4.1 Authentication Name

............................................................................................................................................

77

7.8.4.2 Single Registration

..................................................................................................................................................

77

7.8.4.3 3rd Party Registration

........................................................................................................................................

77

7.8.4.3 User-Visible Settings

............................................................................................................................................

78

7.8.5 Importing a list of users

..................................................................................................................................

78

7.8.6 Account List

.......................................................................................................................................................................

80

7.8.7 Storing information

................................................................................................................................................

80

7.9 Plug and Play .............................................................. 81

7.9.1 Server Detection

........................................................................................................................................................

81

7.9.2 Setting Groups

..............................................................................................................................................................

82

7.9.3 MAC Addresses

.............................................................................................................................................................

83

7.9.4 Settings

...................................................................................................................................................................................

83

7.9.5 Software Version

........................................................................................................................................................

84

7.10 Registered Users .......................................................... 84

7.11 Other Status Information .............................................. 85

7.12 LED Notifications .......................................................... 85

7.12.1 Dialog-State Notifications

.............................................................................................................................

86

7.12.2 Domain State Notification

.............................................................................................................................

88

7.12.3 Call Pickup and Takeover

.................................................................................................................................

89

8 Call Hunting ................................................91

8.1 Defining Stages ........................................................... 91

8.2 Defining the Algorithm .................................................. 92

8.3 Default Actions ............................................................ 93

snom technology AG • 7

1 Foreword

Before you start using the proxy and continue with the rest of this

manual please read the following important notes.

1.1 Software Updates from 2.42

There are some important changes in version 2.44 that you

should consider when updating the software version.

First of all, the license model has changed. Instead of keeping the
number of currently registered users, the proxy now counts the number of
known users. The number of registrations does not matter. This reduces
the load for license counting on the proxy significantly and solves many
problems that we had with the old license model.

Second, we decided to remove the double-directory mechanism
that was found in the 2.42 version. This double-layered directory
structure caused many problems in the scanning of the directory and the
programmability of the first directory layer caused problems when the
program was changed.

Several features were removed. This step simplified the proxy
significantly and increased its stability. For example, the welcome message
is not supported in the default configuration of the proxy. Message store­and-forward has also been removed.

On the other hand, the 2.44 version of the proxy comes with a
scriptable RADIUS support at its core and a simple hot-standby support
without the need to a redundant file system. Compared with the 2.42
version, there are several new features like pickup groups. Detailed
information about the changes between the release can be found in the
proxy release notes.

1

8 • Foreword

[ S N O M 4 S P R O X Y M A N U A L ]

1.2 Software Updates from 2.2x

The 2.3x edition of the proxy uses the same license keys as the
previous versions. However, because of the domain concept, the license
checking algorithm had to be changed and the new proxy now checks
the hostnames directly against the found IP address. Therefore, the list
of hostnames should now include the IP address of the host. If you have
problems with this, please contact mailto:[e-mail], please include
the old license information. We will give you a new license key in this
case.

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 configuration data
from the 2.2x proxy versions into the new version. Some of the settings
need manual update.

Therefore, if you update the proxy, we ask you to save old
configuration information for later reference. You can do this easily by
storing the web content of the relevant configuration pages to a file (the
downloading of XML-Files is described below).

You can always find information about the changes at our web
site, http://snom.com/download/proxy-release-notes.pdf.

1.3 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/white_papers.html 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 manual.

We also keep a list of bug fixes in the release notes, which is
available at the software download site at http://snom.com/down4s.html.
Before you make a software update, you may check this document if the
update is necessary or not.

1

snom technology AG • 9

2 Installation

2.1 Windows

2.1.1 Installation

Tip: If you are doing an update, you need to stop and uninstall

the old proxy first (see below on how to do this).

After double clicking on the setup executable, the installations

program starts up. Press Next to begin the installation.

2

10 • Installation

[ S N O M 4 S P R O X Y M A N U A L ]

At the beginning of the installation the setup program asks you to
accept the license conditions. Please read them carefully, then select the
“accept” button and press “next” to accept the conditions. If you decline,
the installation will be aborted.

After accepting the license agreement, the next screen asks you
to enter a few basic installation settings. You should have received the list
of the hostnames and the matching license code with the purchase of this
product, please enter this into the respective fields.

You need to define on which ports the proxy will operate. This is
important because otherwise it will be hard for you to find the right port.

The http port defines where the web server of the proxy can
be accessed. The default port for web servers is 80, and if you are not
running any other web services on the computer, port 80 is a good choice.
Otherwise, choose a free port and write the port number down somewhere
so you don’t have to search for it. If you don’t fill in any data or cancel the

2

snom technology AG • 11

[ S N O M 4 S P R O X Y M A N U A L ]

dialog, port 80 will be used. From a service perspective, it is ok to choose
a different port than port 80.

The SIP port defines where the SIP traffic is expected. The default
port is 5060, but in case you are running a proxy on the same host you
will probably have to choose a different port. If you are using DNS SRV to
locate the proxy, choosing a different port than port 5060 reduces the risk
of attacks on the proxy.

The settings in this mask can be changed later. You can continue
installation even if some information is missing; however you should
remember the http port, because otherwise you will have a hard time
locating the web server of the product.

You can then select the location where the proxy’s files will be
put. The installation program proposes a reasonable location but if you
want to you can change it. After this, the installation asks you for the
location where the proxy information will be put. This directory needs
write access and will contain the information for registered users. The

2

12 • Installation

[ S N O M 4 S P R O X Y M A N U A L ]

installation program proposes a location relative to the proxy installation
directory, but it might be useful to specify a different location for this, e.g.
a temporary directory. It is important that the directory exists; the proxy
will not create this directory.

The installation process is then ready to start. Usually it will take
only a few seconds to copy the necessary files. At the end of the installation
process you are asked if you want to start the proxy immediately. If you
do so, the program will be started as a regular program and will not be
visible in the services dialog of the operating system until you reboot the
machine.

After finishing the setup wizard, check that the proxy is running.
If you do not want to reboot your system (because it is running other
critical applications), you can also manually start the service in the services
section of the Windows control interface.

Check that the installation has been successful by checking the
Services field of Windows. Open the services Window and look for “snom

2

snom technology AG • 13

[ S N O M 4 S P R O X Y M A N U A L ]

4S Proxy”. The status should be “Started”. If this is not the case you
should invoke the proxy by selecting “start”. In this case, we recommend
rebooting the system to make sure that the proxy is running after the
reboot.

After making sure the proxy is running, you should connect to
the proxy to a web browser. In order to do this, you can connect to the
address of the local computer (http://localhost:8080 if you are running the
web browser on the same machine). If the http port is already occupied
by other programs, the proxy will try to use ports 5068, 5069, 5070 and
so on. It is important that you connect to the proxy to a web browser,
because that is the only way to control the proxy.

If you have trouble locating the http port, you can use the netstat
command (netstat –b for Windows). You should then see the proxy process
running on the local machine.

2.1.2 Uninstalling in Windows

To uninstall the proxy, first stop it in the services window. Then
go to the Software Window and click on “remove” for snom 4S Proxy.

2.2 Linux

After you downloaded the RPM from our web site you can either
install it via the graphical administration frontend of your Linux distribution
or you can use the command line interface (CLI).

For the graphical installation please consult the documentation of
your Linux distribution for details how to install 3rd party software.

If you use the CLI you need to be root to install the software.
Please go the directory where you saved the RPM after downloading. If
this is the first installation of the snom 4S proxy on this host from a RPM
package please use the following command to install the software:

rpm -ihv snomproxy-2.44.*.rpm

If you already installed an older RPM version of the proxy please
use the following command instead:

rpm -Uhv snomproxy-2.44.*.rpm

14 • Installation

[ S N O M 4 S P R O X Y M A N U A L ]

The output of both commands will just show some hashes (#)
and then return to the command prompt without any message if no error
occurred.

After you installed the software please load the file /etc/sysconfig/
snomproxy in your favorite editor and verify that you are satisfied with the
default settings (SIP port: 5060, HTTP port: 80, Configuration directory:
/var/lib/snomproxy).

Note: during the installation values from /etc/rc.config or /etc/
snomproxy.conf if they exists will be copied to /etc/sysconfig/snomproxy.
The usage of /etc/rc.config or /etc/snomproxy.conf is deprecated and
only the values from /etc/sysconfig/snomproxy will be considered for the
future.

When you are satisfied with the configuration values please start
the proxy with the following command:

/etc/init.d/snomproxy start

Note: the process will not be started automatically any more like
it was with the old snom tarball installation, because user interactions
are not possible during a RPM installation, but the port settings should be
verified by the user before starting the process.

2.3 Command Line Options

--log n: Specify the log level between 0 and 9. 9 means as much

messages as possible, 0 means only the most important messages.

--http-port n: Explicitly specify the http port number. The old

name –html-port can also be used.

--https-port n: Explicitly specify the https port number.

--sip-port n: Explicitly specify the sip port number.

--dir d: Specify the root directory for the proxy. This is important

as the proxy will search files in this directory.

--no-daemon: Don’t run the process as daemon in the background,

run it as normal process.

--version: Print the version number and exit.

snom technology AG • 15

[ S N O M 4 S P R O X Y M A N U A L ]

--license-hostname: Explicitly set the license hostname or
hostnames (use quotes to allow space between the hostnames). This can
be used to override the settings in the settings.

--license-code: Explicitly set the license code. This can be used
to override the settings in the settings.

2.4 Migrating 2.42 Files

If you want to use the files that you used from the 2.42 or
previous versions, you need to move some files. You can do this relatively
easy in Linux. The following shell script should do the job for you if you
are moving to flat directory structures.

cp –R runtime runtime-old; cd runtime
for i in *; do if [ -d $i ]; then pushd $i; for j in *; do if [ -d $j ];
then pushd $j; cp -R * ..; popd; rm -Rf $j; fi; done; popd; fi; done

2.7 DNS Setup

After you install the proxy, you need to make sure it can be found.
Depending on the sophistication of your installation, you need to set up
some DNS entries. This manual does not describe how you change the
DNS entries; for this purpose, please consult the manual of the DNS tool
that you are using.

As long as you are using plain IP Version 4 addresses, you
don’t need to change anything with DNS. This might be appropriate
in a completely private network with only one proxy server at a fixed
address.

SIP uses several DNS levels. The first level is called NAPTR and
this is a way to determine on a flexible way where a service can be found.
ENUM is built upon this level. If you want to locate your proxy using
ENUM, you will probably need the support of additional tools. DNS SRV
is a way to specify addresses for a specific service. Using this level, you
can specify several servers for one address. This enables redundancy and
scalability. DNS SRV is also a way to specify other port numbers than
the default port number for a service. DNS A is the simple DNS address
resolution mechanism we know from the old days that resolves exactly
one address.

16 • Installation

[ S N O M 4 S P R O X Y M A N U A L ]

We recommend setting up DNS SRV so that you can redirect the
SIP services to a different host than your main server. This way, you can
use the same email addresses for a user as the sip address.

2.7.1 DNS Example

To use the DNS SRV support, you need to define entries for “_sip._
udp” and “_sip._tcp” for your domain and assign weights and probabilities
to the different hosts that serve these services. A configuration file for
Linux might look like this:

$TTL 1D
anycom.de. IN SOA fox.anycom.de. hostmaster.anycom.de. (
2002050111 ; serial
1D ; refresh
2H ; retry
1W ; expiry
1D ) ; minimum

IN NS fox
IN NS ns2.anycomns.de.
MX 10 mail.anycom.de.

_sip._tcp.anycom.de. IN SRV 0 5 5060 sip-server.anycom.de.
IN SRV 0 1 5060 test.anycom.de.
IN SRV 1 5 5060 www.anycom.de.
_sip._udp.anycom.de. IN SRV 0 5 5060 sip-server.anycom.de.
IN SRV 0 1 5060 test.anycom.de.
IN SRV 1 5 5060 www.anycom.de.
_stun._udp.anycom.de. IN SRV 0 5 3478 sip-server.anycom.de.
localhost IN A 127.0.0.1
ns IN A 232.145.142.95
anycom.de. IN A 232.145.142.95
sip IN A 232.145.142.97

In this example, there are three choices for accessing the proxies
for anycom.de. The first two, (sip-server.anycom.de and test.anycom.de)
have the weight 0, and as long as one of them is up they will be contacted.
Only if both of them are down, will the service go to www.anycom.de. The
probability of contacting sip-server is 5/6, the probability of contacting
1/6, as the preference sum is 6. That means that most of the load goes
to sip-server.

snom technology AG • 17

[ S N O M 4 S P R O X Y M A N U A L ]

2.7.2 Using the Proxy without DNS

In small installation, you may not have access to DNS or you
simple don’t want to spend time on setting up DNS. If you decide to
use this approach, you must set the outbound proxy of all user agents
in your system to the address of the proxy. This applies to the phones;
it also applies to other user agents like the media server and the PSTN
gateway.

This also means that you will not be able to have a redundant
system setup. Because of this and for the sake of simple system extension,
we recommend to use DNS setup.

18 • Installation

[ S N O M 4 S P R O X Y M A N U A L ]

snom technology AG • 19

3 Domains

The snom 4S proxy supports multiple domains on one proxy. This
is a powerful feature that allows a proper routing or requests according to
the SIP and IETF paradigm of DNS domains.

A domain defines a specific view on the proxy. Each domain
has its own log, its own user list, its own dial plan, its own registration
policy, its own password, its own welcome message policy, and so on. This
concept is sometimes called “hoteling” as it makes the proxy look like a
hotel where guest can rent a room.

This makes it very easy to host separate domains with only one
proxy process and only one proxy port. This is important for ITSP; however
it is also helpful to set up a productive system and a testing system for
customers who have only one primary domain.

Domains have a primary name and alias names. The primary
name is used to identify the domain while the alias names are used to
redirect requests to the primary domain. This is useful when a host can
be found in different ways, for example by its DNS SRV name, by its DNS
A name, or by its IP address. In this case, you would use the DNS SRV
name as a primary domain name and the DNS A name and the IP address
as alias.

In order to make the domain matching processing deterministic,
domain and alias names must be unique. It is not allowed to use the same
name as alias for different domains.

You can use as many domains as you want. It does not affect a
number of licences counted by the licensing part of the proxy. In contrast,
when you‘re planning to register a large number of user agents, the
domain concept helps balancing the load. Therefore, you should consider
separating your customer base in separate domains, if possible.

3

20 • Domains

[ S N O M 4 S P R O X Y M A N U A L ]

3.1 Creating a domain

To create a domain, you must log on with the administrative
account of the proxy. Go to the domain administration web page and
enter the primary name of the domain. If you wish to assign alias names
for the domain, you may enter them in the alias field. Press the Add
button to add the domain.

If the domain already exists (the primary domain names match)
the alias names are modified. Please notice that you can not change the
primary name after the domain has been created. However, you can
change the alias names for the domain.

You should enter any DNS name or IP address under which that
domain can be found by clients. If the proxy receives a request with a
domain name in the request URI domain that is not in the list, it will
not process it in a domain context. If you want to use the configuration
features, you should also consider using the “sip” plus domain name DNS
name.

3.2 Deleting a domain

If you want to remove a domain, click on the delete symbol next
to the domain list entry. The domain data will actually not be removed; it
will be renamed to a different name in the same directory. That means if
you want to recover the domain settings, you have to manipulate the file
in your file system.

However, we strongly recommend thinking twice before removing
a domain.

3

snom technology AG • 21

[ S N O M 4 S P R O X Y M A N U A L ]

3.3 Edit a domain

Clicking on the edit button in the domain list will fill out the
domain creation form at the bottom of the web page. You can then edit
the settings in that form.

However, to change the primary domain you need to remove that
domain first and then enter the domain names again.

3.4 Going to a domain context

To go to a domain context, just click on the primary name in
the domain list. The proxy will then display all information in the domain
context as if you logged on in the domain context.

3.5 Determining the Domain Context

3.5.1 Purpose

Operating the proxy in a multiple domain environment gives the
snom proxy advantages against other SIP proxy products. However, the
determination of the domain may have different requirements, depending
on the environment.

The decision affects the visibility of calls in the domain context
(for domain administrators). This is important for the controlling feature
as well as for the other tracing features.

Also a call must be in a domain in order to be subject to billing.
Normally it does not matter in which domain a context goes, because the
billing format will make sure that the right domain and user is charged.

The question in what domain context a request is processed is
related to the question which domain is used for challenging. The proxy
uses by default the from header to determine which user initiates the
call (it can be changed by a script). The username usually contains the
domain (like in „[e-mail]“), so that the domain is clear. The
domain is not checked for alias names, so that the proxy will challenge

3

22 • Domains

[ S N O M 4 S P R O X Y M A N U A L ]

using the literal domain name. This is necessary in order not to confuse
the user-agents.

3.5.2 Usage

When a request comes into the proxy, it must make a decision
under which domain context the request should be processed. The
administrator may set the behavior in the Domain Routing web page.

By default, the proxy checks the Request URI for a domain name.
This behavior is ok in most cases. If the request uses loose routing and
the topmost route entry point to this proxy, this route is taken instead.

If you select the “From” header, the domain will be determined
based on the From-header of the request. The „To“ option works similar.

The “URI-From-To” option first tries to find a valid domain in the
URI (maybe also the first route), then the “From”-Header and finally in
the “To”-header. This option is helpful if you want to make as many good
matches if possible. However, this option might cause confusion in some
cases.

If a domain could not be assigned to a domain by the above
rules, you may explicitly determine which domain is being used.

If you re-route requests to “foreign” domains, make sure that the
dial plan includes the domains that you planned. This is a typical source
for misunderstandings.

3.6 Backup

Domains are stored in XML-files in the file system. That means
you can copy and edit them with a plain text editor. You can also put

3

snom technology AG • 23

[ S N O M 4 S P R O X Y M A N U A L ]

them under revision control (for example with CVS) and make sure that
nobody overwrites them with some unproven settings. The proxy reads
the information only during start-up (they are kept in memory) and
overwrites them when changes are made. Therefore, if you want to make
manual changes you must first shut down the proxy before you do the
changes.

The directory in which the domain settings are stored is set up
during the installation process. The domains of stored in the runtime
directory as directory and contain a file named “domain.xml”.

However, if you change the files in the file system, you need to
restart the proxy as it caches the information related to the domains.

3

24 • Domains

[ S N O M 4 S P R O X Y M A N U A L ]

3

snom technology AG • 25

4 Login

Before you can use the proxy, you must log on to the system. The
login screen has a couple of features that are described here.

4.1 Sessions

The interaction with the web server of the proxy is based on
sessions. The login screen creates a session and sets the permissions for
the session.

Each session has a list of variables associated with it. These
variables are kept through the whole session and may be modified by the
interaction of the user.

One of the session variables is the language that is used for the
communication with the user. The login screen offers several languages
on the right top of the screen. By clicking on a button the user selected
the preferred language. Note that only English is available in the domain
and administrator mode.

4.2 Login

There are three modes for login: (system) administrator mode,
domain administrator mode and user mode.

The system administrator mode has all privileges on the system.
To log in, you need to enter the name of the administrator, the password
and select the Administrator in the pull down menu. By default, the name
is “admin” without a password. If you want to protect your system, you
should change this (see below on how to do this).

The domain administrator mode has rights restricted to a specific
domain. To login as domain administrator, just enter the password (no
username) and select the domain from the pull down menu. By default,
the password is empty.

4

26 • Login

[ S N O M 4 S P R O X Y M A N U A L ]

If you want to log on as a specific user, enter the username and

the password for that user and select the domain of that user.

Depending on your login type, the proxy will load the starting

page for the login type.

If there are too many domains on the system, the appearance
of the system changes. In this case, there is no more pull down menu.
Instead, the login screen will just prompt for a username and a password.
If you want to log on as administrator in this mode, just enter the username
of the administrator and the password. If you want to log in as domain
administrator, enter the domain name and the password. If you want to
log in as user, enter the username followed by the at symbol and the
domain and enter the password.

4.3 Creation of Accounts

If you allow that users set accounts up themselves, there will
be a link on the logon screen that will lead users to the account creation
prompt.

In this prompt, the user has to fill in information about his identity
and desired passwords. As soon as the information has been filled in (and

4

snom technology AG • 27

[ S N O M 4 S P R O X Y M A N U A L ]

you have set up the necessary email server information), the user will
receive an email that informs him about his hew account.

After creating the account, the proxy will go back to the login
screen. The account information is already filled in; the user just has to
enter the password again (for confirmation and showing the user how it
works). Then the user will be lead to the index page of the user mode.

Note that this mode is primarily intended for trusted environments
where the system administrator does not want to be bothered with the
setup of accounts. Because each account setup will require another license
you should consider if you want to allow this feature.

4.4 Logout

On every web page, you will find a logout link. If you use this link,
the proxy will delete the session and redirect you to the login page.

If you don’t log out explicitly, the proxy will delete the session
after a timeout (see settings of the administrator mode).

4

28 • Login

[ S N O M 4 S P R O X Y M A N U A L ]

4

snom technology AG • 29

5 System

Settings

5.1 License

There are a number of license modes available for the proxy.
When you downloaded the demonstration version from the Internet, you
will probably have a demonstration license key. This license key is valid
independently from the host names that you enter. However it will become
invalid after the indicated date. Please notice that it is not possible to
overwrite the demonstration license key with another demonstration
license key.

When you buy the proxy from snom, you will receive a license
key. This license key depends on the host names that you enter in the first
field. The „Hostnames“ field has a function to uniquely identify this copy
of the snom SIP proxy. Therefore, when requesting the license key from
snom you should use the DNS names of the host which will run the proxy.
You should also include the IP address of this host. Examples are „proxy.
mycompany.com 213.43.34.12“ or „sip.mycompany.com mycompany.net

32.43.12.32“. Please always use fully qualified DNS names including dots.
When you are using private addresses, please also specify a fully qualified
DNS name so that snom can clearly identify the copy of the SIP proxy.

5

30 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

The proxy counts the number of accounts. This is done once after
the proxy starts, therefore for large installations starting the proxy may
take some time. Whenever you create a new account or delete an account,
the proxy changes the number of used accounts. You can see the number
of currently used accounts in the license web page.

This license model is a change to the previous proxy versions. The
previous model counted the number of registered user agents. However,
this model created a lot of confusion and made it almost unpredictable how
many licenses are used (users constantly registering and deregistering).
Therefore we decided to change the license model to the much more
simple account counting model.

To see the possible license types please refer to the data sheet.
After entering the license code, you can see the administration menu of
the SIP proxy.

5.2 Port Bindings

The proxy offers a powerful way of configuring the IP identity of
the proxy. Normally, you don’t have to do any changes on this configuration
web site. However, when you are using the proxy on a device that has
more than one IP address or in a DMZ, this page can help solving your
problems.

In principle, the proxy needs to address two different issues for
each port. The first question is on which IP address it should bind the port;
the second is what identity it should show (for example when sending a
SIP packet).

5.2.1 Binding to the right address

To help selecting the IP address where to bind to, the proxy will
search your host for IP addresses and show them in the pull down menu. If
you explicitly select them, the proxy will use them. If you choose “Default
Address”, the proxy will search a public address and if there is no public
address get a private address. If you select “Public Address”, the proxy
will select only a public address; if you select “Private Address”, the proxy
will select only a private address. “Public Address 2” will select the second
public address, which is helpful for automatic setup of the change-IP port
for STUN.

5

snom technology AG • 31

[ S N O M 4 S P R O X Y M A N U A L ]

You can also put manually addresses on the list of available
addresses. There are two fields at the bottom of the page where you may
specify them. These addresses will also be offered in the pull down menu
as if they had been found on the host.

5.2.2 Receiving forwarded packets

If you forward packets to the proxy from a firewall or NAT, the
proxy needs to act as if it was using this address. If you are doing this, you
need to specify which address the proxy should use. The default selection
is “Bind Address” which means that the proxy is using the address which it
bound to. If you want to use something else than bind address, you must
specify which port the proxy should assume.

5

32 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

If you choose to operate the proxy in a DMZ, you should make
sure that the proxy can be reached both from private as well as from public
addresses via the address which you have specified. Sometimes this is not
possible with NAT equipment which forwards packets only between public
Internet and the private network.

5.2.3 SIP, HTTP and RADIUS Port

The standard port for SIP is 5060, the standard port for HTTP is
port 80, and the standard port for RADIUS is 6025. Depending on your
specific needs you might want to choose other ports.

Choosing a different port than the standard port increases the
security, because for robots searching the Internet it is not so easy to
probe ports (there are approximately 65,000 of them per host). However,
you must make sure that clients are able to locate the port. For SIP, this
can be done easily using the DNS setup shown before. The proxy opens a
UDP port and a TCP port on this port number.

The SIP replication port is a dedicated port that the proxy uses
for replication. If you don’t use replication you can leave this port on port
number 0.

For http, this is more difficult as web browsers not use DNS SRV
for locating the server. Here you should consider if the user needs to
access the web interface of the proxy directly. If this is not the case, we
recommend picking a random port number. This will reduce the number
of DoS attacks on the proxy.

The RADUS port is only used as client port. In principle, you can
choose any port (if your RADIUS server accepts this). RADIUS works only
on UDP.

5.2.4 STUN Settings

The settings for the STUN port are a little bit different from the
other settings. STUN operates on four sockets. The ports 1 and 2 run on
the same IP address, ports 3 and 4 should run on a different IP address.

If you don’t have a second IP address available on your host,
you cannot run STUN properly. See the RFC3489 for more details. If you
have two addresses available, be sure that you bind the SIP ports only

5

snom technology AG • 33

[ S N O M 4 S P R O X Y M A N U A L ]

5

to a specific IP address, because otherwise you will have trouble when
someone wants to reach your proxy on the SIP port.

On the STUN ports, it does not make sense to run them on virtual
addresses. Sending back packets will change the origin of the STUN
responses so that the receiver will have a wrong source address in the
response.

In the previous versions of the proxy, we spoofed IP addresses.
While this approach made it possible to run STUN on hosts that have only
one IP address (e.g. in hosted services environments), it could disturb
ARP caches and generally is not a good practice. Therefore we decided to
give up this tricky approach.

5.3 System Settings

After you set the license and configured the ports, you should
take a look at the system settings.

5.3.1 Logging

The proxy includes some mechanisms that should help you to
find out what is going on on the proxy.

The Log Level defines how many messages you will see in the
logs. Log level 0 means that only the most urgent messages are visible;
log level 9 means that as much as possible is reported.

If the the log filename is set, the proxy will write the log into the
provided file (apart from the internal log which is available from the web
interface). Because logging over a long time may generate very long files,
the proxy may change the log file every day. If you want this feature,
include a dollar sign in the filename. The proxy will then replace the dollar
sign with the day. Then you can delete the superfluous log files day by
day.

The Internal Call Trace Length tells the proxy, how many finished
calls it should keep in memory. This list can be accessed by the web
interface to give you an overview on the activities on the proxy.

The proxy keeps a list of the last SIP packets. You can access this
list also through the web interface. The Internal SIP Trace Length is the
length of this list.

34 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

The Internal LOG Length is the number of log messages that the

proxy keeps in memory for the display on the web interface.

5.3.2 Caches

The proxy uses in several places caches. This avoids multiple
loading and saving of information with the associated CPU load. For
example, the proxy tries to load user data only once from the hard disk
until it needs space for another user. The proxy keeps track which cache
entries were used recently and this way optimizes the proxy performance
statistically.

The cache size is a trade off between speed and memory. If you
make the cache size bigger, the speed will generally increase. If you
make the cache size smaller, you need less memory space. In any case,
you should not make the caches to big, because then the computer will

snom technology AG • 35

[ S N O M 4 S P R O X Y M A N U A L ]

5

start paging RAM to the hard disk, which has negative effects for the
performance.

Using a cache size of ten entries is a reasonable start. If you
are running on a powerful system, you can increase the cache size. As a
rule of thumb, the cache size should be around twice the number of calls
that are running through the proxy at the same time. In this case, the
associated users have a good chance that they are kept in memory during
the whole call. For example, for a E1 connectivity you would choose a
cache size of 60. However, you should keep an eye on the memory size
of the proxy.

The proxy does not free memory, therefore reducing the cache size
will not reduce the proxy process size (only a restart will have this effect).
However, it will stop or slow down the growth of memory demand.

5.3.3 Subscription Size

The proxy contains agents that collect data and then distributes
it to parties that subscribed for the information. This process is called
“exploding”, as one incoming message may trigger a lot of outgoing
messages. The term makes clear that is has an impact on the proxy
performance.

The Maximum Number of Subscriptions tells the proxy how
many subscribers it should accept for a single resource. This limits the
performance impact on subscriptions to a reasonable range. The default
value is 100 subscribers. The design of the proxy does not suggest much
higher numbers; please be careful when increasing this number cause it
can have a negative impact on the peak performance of the proxy.

5.3.4 Unavailable Hosts

When the proxy fails to deliver a message because the host is not
responding at all, it usually is not good to try this address again too soon.
For example, if you are using a redundant PSTN gateway setup and your
primary gateway breaks, you don’t want to try this address over and over
again for every single packet. You would prefer to try again for example
every minute.

For this purpose, the Unavailable Host TTL (time to live) has been
put into the proxy. It is the number of seconds that the proxy considers
an IP address and port unavailable after a request timeout.

36 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

In networks that contain components that are often rebooted,
this setting may have annoying effects. For example, when users start
and stop soft phones without proper deregistering, you better keep this
value at value zero.

5.3.5 Agents

The proxy includes two agents. The presence agent relays presence
information, the dialog agents collects dialog-state information.

The dialog agent looks at the messages that are flowing through
the proxy and tries to determine the dialog state from the messages. This
is a useful feature for user agents that do not support this new feature.
However, it has several problems associated with it. Dialog state may
already be set up without any SIP traffic (for example, a phone going off
hook). The dialog agent has no chance to construct dialog state in this
case and will not be able to report the state correctly. Therefore, it is
better to use user agents that support this feature themselves.

The presence agent merely relays presence information. The
primary goal of this agent is to take the exploding load off the user agents.
If you turn the agent off, user agents are still able to publish presence
information peer to peer through the proxy.

If you are not sure weather you should turn the agents on or off,
we recommend to turn them off.

5.3.6 Number Guessing

Number guessing is a snom-proprietary way of completing user
input on the phone. When the phone tries to complete a number, it sends
a request to the proxy. The response may contain a list of possible number
that the user might wants to enter. The proxy checks the address books of
the user and the call history for this information.

5.3.7 Directories

The proxy stores account information in subdirectories. The
previous version of the proxy supports a script command that calculated
a top directory for an account group. The default behaviour was to return
the first character of the user name.

snom technology AG • 37

[ S N O M 4 S P R O X Y M A N U A L ]

5

This approach has a couple of disadvantages. First of all, it reduces
the performance of the proxy significantly and increases the internal
complexity of the proxy. It does not increase the performance of the file
system, as modern file systems use latest technologies to implement
very efficient hashes on file names. Finally, it makes it very dangerous to
change the hash function while the proxy is already set up.

These disadvantages convinced us to remove the layered
directories by default. For new installations, the proxy will select no hash
function. In this configuration, the proxy will not generate a single tier
directory structure.

If you perform an update (a configuration file is already available),
the proxy will pick the leftstr(1) hash function, which was the default in
the previous proxy versions.

If you believe in hashing, you can select two other hash functions.
The rightstr(3) function returns the last three digits of the account name.
This will create around 1000 directories (if you are only using telephone
numbers), which makes the directory lookup efficient enough and makes
it relatively easy for you to manually locate a user.

The md5-12 function calculates a randomly-distributed hash
over the user name and picks the first twelve bits from it. For readability
purposes it converts this number into a hexadecimal number, which will
be the directory name. While it will make it pretty hard for you to locate
a specific user, it has a good performance behaviour. The function will
make sure that you are not using more than 4096 entries. The advantage
of this hash function is that redundant file systems have to replicate only
relatively small pieces of the file system (which is also the case for the
rightstr(3) hash function).

5.3.8 Email

The proxy is able to send emails. In order to use this feature, you
need to give the proxy an identity and a SMTP server. Please note that the
proxy does not support Authenticated SMTP.

The SMTP server may be a DNS name or an IP address. Please
don’t use port numbers behind the name; the proxy expects the SMTP
server on the standard port.

38 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

The Email URl is the email address that will be used for sending
emails. It must include the “@” character. The display name is the name
that will be rendered to the user.

More and more email servers require that users log into a POP3
account before they can send emails. This makes sending SPAM messages
more difficult. If you enter a POP3 account together with a password, the
proxy will first log into this POP3 account. The server address is the same
as for the SMTP (also on the standard port).

5.3.9 Configuration in XML

Because all configuration information is kept in XML file format,
you can easily retrieve the configuration information in this format.
Just click on the link at the bottom of the web page to see the general
configuration of the proxy. You can save this configuration in any file you
like. To upload the configuration from such a file, use the file selection box
at the bottom of the web page and upload the file. This way you can also
easily distribute configuration files over several redundant proxies.

5.4 Security Settings

5.4.1 https/http Access

The proxy supports a secure web access starting from version

2.42. In the Security Settings web page you may specify the behavior of
the SSH/TLS subsystem for the web server.

snom technology AG • 39

[ S N O M 4 S P R O X Y M A N U A L ]

5

First of all, you can control, when the web server accepts secure

or insecure connections. This can be done on access type basis:

• Login and Account Creation Access: This affects the login page and
the page where users may set up accounts.

• User Mode Access: This setting affects the user access web pages
(also for hunt group administration).

• Domain Admin Mode Access: All web pages that are accessed by the
domain administrator.

• System Admin Mode Access: All web pages that are accessed by the
system administrator.

• Settings and Software Provisioning Access: Web pages that serve
settings and software update information.

40 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

All other web pages (images, software images) are transferred

insecure.

Typically, it is ok to require https for all access which is done with a
web browser (as most web browsers support https access). Because most
user agents don’t support secure downloading of settings and firmware
update, it might be necessary to allow unsecured access to settings.

Also, you should normally allow all possible ciphers. Only if you
feel that certain ciphers are insecure, you should disable them.

5.4.2 Administrator Access

To protect the access to the web server, you can set up a user
name and a password for the web server. Remember that this provides
only basic security, as the content of the web page is transmitted without
encryption over the network and the passwords can easily monitored by
network specialists. However, it avoids that everybody can easily access
the proxy.

The default session timeout is one hour (3600 seconds). This
should be reasonable in most environments; however if you want to
change this you can do that with this setting.

This setting must be at least one minute (60 seconds). If this
is not the case, the proxy chooses automatically one hour as session
timeout. If the timeout is more than 10 days, the proxy reduces it to 10
days.

5.4.3 Importing Certificates

Normally, the proxy automatically generates a syntactically
correct certificate automatic („self signed certificate“). However, most
web browsers will complain about the presented certificate.

You may buy certificates from a number of trusted vendors. You
can see and edit this list in your browser and search the Internet for
vendors. Typically, when you order a certificate, you receive a text file
that looks like the one below:

-----BEGIN CERTIFICATE----­MIIDTDCCArWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB9MQswCQYDVQQGEwJERTET
MBEGA1UECBMKU29tZS1TdGF0ZTEPMA0GA1UEBxMGQmVybGluMRAwDgYDVQQKEwdz
bm9tIEFHMRgwFgYDVQQDEw9zbm9tIFZvSVAgUGhvbmUxHDAaBgkqhkiG9w0BCQEW
DWluZm9Ac25vbS5jb20wHhcNMDQwMTIzMTA1OTE5WhcNMDgxMjI3MTA1OTE5WjB9

snom technology AG • 41

[ S N O M 4 S P R O X Y M A N U A L ]

5

MQswCQYDVQQGEwJERTETMBEGA1UECBMKU29tZS1TdGF0ZTEPMA0GA1UEBxMGQmVy
bGluMRAwDgYDVQQKEwdzbm9tIEFHMRgwFgYDVQQDEw9zbm9tIFZvSVAgUGhvbmUx
HDAaBgkqhkiG9w0BCQEWDWluZm9Ac25vbS5jb20wgZ8wDQYJKoZIhvcNAQEBBQAD
gY0AMIGJAoGBAKjMMf0yoVr3WhkTurLO5qWDeYsJgx1ldw1usLE2xKXevofo7Sla
ZUbGXAwEV84GZu8dhx2P5uSCGthoOQyR23oESJHH/bQ3NjqxsxbjPJE5paplKRn+
S1CeqVHyhxNRqLslV5wGQ+01qD58bdnzmqWaYvKjTK92WqGA1uywmeh1AgMBAAGj
gdswgdgwHQYDVR0OBBYEFC3jMasGM/ZvMg3YBNytQKC+d8MFMIGoBgNVHSMEgaAw
gZ2AFC3jMasGM/ZvMg3YBNytQKC+d8MFoYGBpH8wfTELMAkGA1UEBhMCREUxEzAR
BgNVBAgTClNvbWUtU3RhdGUxDzANBgNVBAcTBkJlcmxpbjEQMA4GA1UEChMHc25v
bSBBRzEYMBYGA1UEAxMPc25vbSBWb0lQIFBob25lMRwwGgYJKoZIhvcNAQkBFg1p
bmZvQHNub20uY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEA
BGWgA+OWrj+6FAt6jmtOAW0RBzIDouvvUEwBe2IyRuz6GKmSGCGzTHmr5s1KheAO
7lEmCK1qCIAWZ7bx0/V3nQkpNLy2YCxPAEnssIol0ru/bJZk9HoMvCgYf4KRje3G
VMuv3SZ4bPD9QRZRc2VOAjjDk/TLkBnHp36dB3pvvzc=

-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY----­MIICWwIBAAKBgQCozDH9MqFa91oZE7qyzualg3mLCYMdZXcNbrCxNsSl3r6H6O0p
WmVGxlwMBFfOBmbvHYcdj+bkghrYaDkMkdt6BEiRx/20NzY6sbMW4zyROaWqZSkZ
/ktQnqlR8ocTUai7JVecBkPtNag+fG3Z85qlmmLyo0yvdlqhgNbssJnodQIDAQAB
AoGAFE8FEK6fxT8PYwcBpnPIQk+wNu89DDNiAIa50YiCXmaPS/DVX+1VVA+XkYaQ
PeR9S/WkhQUERaf1rOXVP1LpMfH+YyZj7smYvZy6S/R6sCCW3dSu1MbnYrRa7KXq
Y12Wi3tGvKCfJ1oRtrYdCq7+3AuJr3tNiu9hSfUK+okfC8ECQQDQ4puzPOHyk6c9
TZl1mzH2QauC0Qu6Tcy4Qn2qLHFSIYi7IA3jIdi3fCHlPF16HKRTkPFat5kNuE0d
X0RIHiqxAkEAzt7c1EWKHCHGFmiFCGDXUO3u3Df/A8xflANiMybvygagYq16OTe0
KCp2h2wpAF+uBOOiQPv/0Hzic7w9wHMDBQJAYonD8XXTEN/ekOi+b+BaXVT1V6zN
34E8BeA378MvYhM3sS6Z3n/lAAmq47zqS+SfEFzbvnPF29cJacW7LFouwQJAFTse
ItL4N6bns4kKji+SKYYhy4wbqgIhlQk73NAUMAG6GCaBsrmazbx96awaESXAsFPE
ZTL3sCgA/avGEqg7GQJAO+LbZQThaC1TP4fvFRb5Y2Q1Uf6DKgq/XMpY8eFE71RS
+ZlDDoerDAm7tg1ndj803IQEFpXLfnFBsATMMchvJA==

-----END RSA PRIVATE KEY-----

To import a certificate, store the certificate in a file and use the
import dialog at the bottom of the web page. The proxy will then present
this certificate when a client connects to the web server.

5.5 Billing Settings

The snom 4S proxy 2.44 supports RADIUS billing. This is by far
the most popular billing method, which is now wholeheartedly supported
by the proxy.

42 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

5.5.1 RADIUS Settings

The RADIUS server IP is the IP address of the RADIUS Server
(e.g. 1.2.3.4). This setting does not support DNS resolution, you must
enter the IP address here.

The RADIUS Access Port is the first port of the RADIUS server for
Access requests. Typically, this port is 1812.

The RADIUS Accouting Port is the port for Accounting requests.
Typically this port is 1813. Some RADIUS servers accept any kind or
request on the same port, in this case you can enter that port number in
both Access and Accounting Port.

The RADIUS timeout is the time between RADIUS packets.
RADIUS uses UDP transport layer, that means packets may get lost. If the
proxy does net get a response, it will retry to send the requet, the RADIUS
timeout is the number of milliseconds that it will wait between the retries.
The default value is 1000 ms.

The RADIUS retries defines how many times the proxy will retry
to send the request. The default value here is 3. If you use 1000 ms
timeout and 3 retries, the proxy might block for three seconds before a
request will be answered.

The RADIUS NAS IP:Port is the local identity that will be used in
the RADIUS requests. RADIUS servers usually check this setting against
their local settings, effectively making this setting a shared secret.
The format that you should use for this setting is IP-Address:Port, e.g.

1.2.3.5:5060.

snom technology AG • 43

[ S N O M 4 S P R O X Y M A N U A L ]

5

The RADIUS Secret is another way to increase the security. The

format is a plain string, e.g. bigsecret.

5.5.2 RADIUS Scripting

There are many different RADIUS implementations out there. We
tried to make the RADIUS as flexible as possible. The explanations in this
paragraph should help to understand it. These explanations apply to the
default script.

RADIUS is used when the RADIUS server IP setting is set.
Otherwise, the proxy will implicitly assume that a “virtual” RADIUS server
accepts any call.

If there is a RADIUS server set, the proxy will filter out INVITE
requests that establish a new dialog. Depending on your security
settings, the proxy will first make sure that the user in the From header
authenticated itself against the proxy (using SIP Digest authentication).
For those requests, it will send a RADIUS Access request with the following
content:

• The NAS IP Address is set to what is provisioned in the web
interface.

• The User Name is set to the user name port of the From header.

• The Password is set according to the RADIUS rules using the shared
secret, the authenticator and the user password

• The NAS Port is set to what you provisioned in the web interface

5060.

• The NAS Port Type is set to 5 (virtual).

• The Calling Station ID is set to the Addr-Spec of the From header,
for example “sip:[e-mail]”.

• The Acct Session ID is set to the Call-ID of the SIP request.

If the RADIUS response is 2 (Access Accept), the proxy will extract
the Session Timeout parameter (27) and set the session timeout for this
call to the provided value. This value is used in the header P-Session­Timeout header and indicates attached user agents how long the session
will last. The snom 4S NAT Filter will use this setting to limit the duration
of the call. This makes it possible to implement prepaid services.

44 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

If the Radius response is anything else that Access Accept (for
example, no response at all), the proxy will reject the call with the code
“403 Call Rejected”.

If the call proceeds, the proxy will eventually receive a 200 Ok
response on the INVITE. It then will send a Start Accounting request to
the RADIUS server. This request has the following parameters:

• The NAS IP Address and the Acct Session ID are the same like in
the RADIUS Access request.

• The Acct Authentic parameter is set to 1 (Radius).

• The User Name, the NAS Port, the NAS Port Type and the Calling
Station ID are set like in the RADIUS Access request.

• The Called Station ID is set similar like the Calling Station ID, but
taken from the To header.

• The Acct Status Type is set to 1 (Start).

• The vendor specific extension 6618 is set to parameter 28, the local
date (time zone of the proxy) when the 200 code was received.

The proxy will not wait for a proper response to that request

(however it will retry on UDP level if there is not response).

When the call ends, the proxy will send a Stop Accounting request.

It has the following parameters set:

• The NAS IP Address, the Acct Session ID, the Acct Authentic, the
User Name, the NAS Port, the NAS Port Type, the Calling Station ID,
the Called Station ID are set like in the Start Accounting request.

• The Acct Status Type is set to 2 (Stop).

• The Acct Session Time contains the duration of the call.

• The Disconnect Cause is always set to “BYE”.

• The vendor specific extension 6618 is set to Parameter 29, the local
date of the disconnect time

• The vendor specific extension 6618 is set to Parameter 28 is set like
in the Start Accounting request.

Please note that there will be no Stop Accounting request without
BYE request. That means you should always make sure that at least one
side of the call disconnects properly. For example, the snom 4S NAT Filter
will generate a BYE request if one of several timeout reasons fire.

snom technology AG • 45

[ S N O M 4 S P R O X Y M A N U A L ]

5

In the case of a server failure (proxy becomes unavailable), the
server must be able to deal with this situation. If you want to use the
proxy in a prepaid environment, you must reset locks in the RADIUS
server that deny Access Requests when the RADIUS server believes that
there is a call going on.

5.6 Domain Determination/
Administration

The settings on these web pages define how the proxy determines
the domain and make it possible to manage domains. This is described
above in the previous chapter.

5.7 Routing Settings

The most important thing that the proxy does is routing requests.
The system administration view on the routing defined the basic behaviour.
There are more settings available on domain level.

5.7.1 Max Forwards

Messages in SIP may hop over a number of proxies, and sometimes
the path contains loops. Sometimes the loops are endless, and in these
situations the criterion for rejecting a message is to look at the number of
hops the request has done so far.

46 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

This setting controls how many hops a request can make before it
is rejected as an endless loop. 70 is the default value; in many environments
you can significantly lower this value.

5.7.2 ENUM Suffix

When converting a tel URL into a URL, the proxy needs a suffix for
the translated telephone number. By default, this is “e164.arpa”. However,
in some environments you want to choose a different name. This can be
set up with this setting.

5.7.3 Route Other Requests

If SIP messages do not affect any of the known domains of the
proxy, the proxy needs to make a decision what to do with it. In principle,
it has two possibilities: Forward them or reject them.

Forwarding them allows user agents to use the proxy as outbound
proxy no matter what action they want to do; on the other hand it might
create a lot of traffic especially when REGISTER messages are used to
keep NAT bindings open. Therefore, you may define the policy how to
handle these messages.

REGISTER messages are never routed. If someone wants to
register with a proxy, he or she must go directly to the registrar.

5.7.4 Loose Routing

The designers of SIP decided to use two ways of routing. This
unfortunate decision did not only cause a terrible confusion in the SIP
stack implementations, it also created incompatibilities between old
and new implementations. The compatible way of doing loose routing
uses a flag that is not strictly compatible with the specified way, but is
compatible with previous implementations. If you have equipment that is
strictly following the latest SIP draft, you must use the RFC3261 style of
loose routing.

SIP messages flow from a user agent client (UAC) through a
number of proxies to another user agent, the user agent server (UAS).
This creates a path, the “routing path” that needs to be remembered for
further messages. For instance, if a proxy wants to carry out billing, it

snom technology AG • 47

[ S N O M 4 S P R O X Y M A N U A L ]

5

needs to see all messages between the user agents to determine how
long the call took.

To do this, a proxy can insert a header into requests that indicates
that it would like to stay in the routing path in future requests. Unfortunately,
the first proposals for doing this did this in a complicated way that can
cause problems under certain circumstances. For this reason, “loose
routing” was developed, a new and better way of routing messages. For
more information see the SIP standard RFC3261 or the literature available
on this topic. The snom 4S supports both routing methods.

Although loose routing is mandatory for new SIP equipment
and is compatible with the old routing method (“strict routing”), some
equipment can still cause headaches. You can use the old-style routing by
turning this flag on. If you know your equipment does not have a problem
with loose routing, turn the flag off. If in doubt, it is better to turn this
flag on.

5.7.5 Loose Routing Flag

Unfortunately, RFC3261 specifies a routing flag for loose routing
which is not compatible with the RFC2543. To be compatible with RFC2543,
you should use the compatibility mode; some newer (however intolerant)
equipment forces the usage of the RFC3261 syntax. In these cases you
need to go to the strict RFC3261 usage.

5.7.6 Always Record-Route

Some old equipment does not like to see both recorded routing
elements and an already available route path in the SIP header at the
same time. In these cases it might help to switch this flag off; however
the price of this is that the proxy is probably not in the route of future
requests any more. This means you will not be able to see a proper call
log even if the phone calls have been made successfully.

5.7.7 Record-Route for SUBSCRIBE

Subscriptions are usually not interesting for the proxy. Actually,
they increase the load on the proxy. Especially when there is a lot of traffic
for notifications (e.g. presence publishes), it saves performance if the
proxy does not route these requests.

48 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

We recommend turning Record Route for SUBSCRIBE on when
you want to see the traffic going through the proxy or when this routing
is not critical for the performance of the proxy.

5.7.8 Symmetric Responses

Another unfortunate decision is SIP was to allow UDP packets to
be sent from a port which does not read UDP ports. While this makes the
implementation of SIP user agents a little bit easier, it makes it impossible
to operate that user agent behind NAT.

However, most user agents send from the same port where they
expect messages and are able to operate behind NAT. Therefore, it makes
sense to send responses back to the exact origin where they came from.
If you turn that flag on, the proxy will behave that way.

In order to be 100 % compliant to the SIP specification, this
setting is set to false by default.

However, in order to operate devices behind NAT, we strongly
recommend to use the snom 4S NAT Filter to solve these problems.

5.8 Redundancy

When DNS SRV is used, two snom 4S proxies can handle the
requests of a user agent. This has the advantage, that one of these servers
may fail and the other servers continue service. This allows installation
of a very robust system. If you run the proxies at completely different
locations, you will be able to continue service even if one of the locations
does not have power. This mechanism can also be used to implement
“hot swapping” of server hardware. It is important to know that you can
buy standard hardware and still operate the system with an excellent
availability.

Please keep in mind that for a successful professional operation of
the servers, you need an alarm system that checks the physical availability

snom technology AG • 49

[ S N O M 4 S P R O X Y M A N U A L ]

5

of the servers (e.g. using SNMP). If one of your servers fails and thanks to
redundancy the service goes on, nobody will otherwise notice the server
failure.

5.8.1 Shutting servers down

When a server fails while it is processing calls, these calls will
mostly continue until the parties hang up. However, the proxy is not able
to bill these calls as the necessary billing information gets lost during
the shutdown (see the explanations on RADIUS). Therefore, system
administrators that schedule service should remove the servers from the
DNS SRV list so that the user agents choose different hosts during the
service period. Therefore, you should make the DNS time to live periods
short enough so that you can schedule updates within a reasonable
amount of time.

5.8.2 DNS considerations

If you want redundancy, you must use DNS SRV. This way the
SIP packets will be routed to one of your server farm proxies. The SRV
priority will define which proxy is the “primary” server and which one
is the “secondary” server. However, from the proxy point of view, this
distinction does not make a difference.

To support devices that don’t perform DNS SRV lookups, you must
use a machine that operates on the DNS A address. Unfortunately, many
low-cost SIP user agents do not support DNS SRV and therefore you need
to select one machine on you server farm to serve for the DNS A record.
If you don’t set up domains on this proxy, it serves as packet distribution
proxy. However, you should make this machine and its environment as
stable as possible.

Please keep also in mind that other components can also affect
the reliability of the system. If you save the proxy runtime files on a NFS
server, this NFS server might become bottleneck for the overall stability
(you should not use a network server for storing the files anyway). Other
examples include DHCP server, PSTN gateways, network routers, and
power supply.

50 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

5.8.3 Refresh rate considerations

Database replication causes additional traffic for the proxies.
Therefore, if you have a highly reliable system, it is tolerable to choose long
refresh intervals for registrations (for example, one hour). However, you
have to keep in mind that a call attempt also causes database replication
across the server farm, as the proxies exchange data for the call lists.

If your system is not particularly set up for reliability and has
enough CPU power available for the proxy, you should choose shorter
registration refresh intervals (one hour or less). In an office environment
with less than 1000 users, database replication should not be a major
performance problem.

5.8.4 How Replication Works

The core replication algorithm is simple. Whenever the proxy
would write something to the file system, it schedule that file for sending
it to the other proxy.

For this purpose, the proxy keeps an internal list of pending
replications. For example, when a lot of files must be replicated in a short
time, the proxy will replicate file by file and wait for every file for the
acknowledgement from the other proxy.

You can put the whole proxy file system into the replication list
by manually pressing the link on the replication web page. The proxy will
actually not put all files in (this could become a very long list), instead it
puts in the root directory “.” and subsequently resolve the subdirectories
during the replication process. If you set up redundancy the first time,
you should use this manual replication to synchronize the two proxies
explicitly.

When the other proxy goes down, the proxy will remember
what files have not been replicated. As soon as the other proxy becomes
available again, it will notify the proxy about this and the proxy sends the
outstanding files to that proxy.

The replication is done using SIP packets. When the proxy starts
up, it opens a special port for the replication that is dedicated to replication
traffic. If you want, you can configure a firewall so that only the replication
traffic between the proxies is allowed and other packets are dropped.

snom technology AG • 51

[ S N O M 4 S P R O X Y M A N U A L ]

5

When both proxies are down, there is a certain problem starting
up. The proxy will try to send a packet to the other side. After a certain
timeout it will realize that there is no response from the other side and it
will start up as primary proxy. This mechanism makes sure that there is
a reasonable start up procedure for example after a power failure of the
whole data center.

Using SIP message means also that the files are put into packets.
When you use UDP transport layer, the maximum size for a file is a little
bit less than 64 KB. Therefore, the proxy will not replicate files with a
bigger size. Usually, files on the snom 4S proxy don’t become so big,
therefore it should not be a problem.

To make replication more robust, you may use TCP transport
layer. In order to do this, just append the “;transport=tcp” to the other
proxy setting (for example, “sip:1.2.3.4:4444;transport=tcp”).

5.8.5 Exceptions

Some files should not be replicated. The proxy ignores files with
the “.log” extension. All other files are replicated, including domain data,
alias and files that might have been created by script commands. File that
you put into the proxy directory by directly writing to the file system are
only replicated when you start the manual replication (by clicking the link
on the web page).

Some of the core settings of the proxy are not replicated. These
settings include the replication proxy address, the port binding settings
(http, sip, stun, radius), the license information and the log filename. All
other settings are replicated, that means after the initial set up of the
secondary proxy you can just trigger manually replication of all other
settings. Also, if you then change a setting on the primary (or secondary)
server, the proxy will replicate that information to the other side.

5.8.6 Settings

To set up redundancy, you need to enter the address of the other
proxy. Typically this will be IP addresses; however it can also be DNS
addresses. You should be careful that the address cannot be resolved by
DNS SRV because the proxy will then randomly select one of the servers
in the DNS SRV list. You can do this by appending the port number behind

52 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

the address. In this case, the proxy will resolve the address using DNS
A.

For making the exchange of registration information more secure,
you can enter a username and a password. This will be used by the proxy
for challenging incoming replication requests. However, the information
itself is transported insecure. This feature is not available in the 2.44
version.

5.8.7 Security

Replication information implies that sensitive information is
transported via the network. The proxy transports the files in clear text,
which means that eavesdropper will see the information as if they would
have access to the file system.

Also, an attacker can send information directly to the replication
port. The proxy currently does not check the identity of the sender
(checking the IP address would not help as an attacker can easily spoof
the source address).

Therefore, we urge you to close the respective ports for public
access. Future updates of the proxy will include a challenging mechanism
known from user agent authentication and TLS transport layer.

5.9 Appearance

You can customize the look of the proxy to a large degree.

The banner text is the text that you see on the top of the web
page. It is printed on the banner image. Both can be changed very easily
by changing the settings. You can also easily put your logo on the web
page.

snom technology AG • 53

[ S N O M 4 S P R O X Y M A N U A L ]

5

If you want, you can completely change the layout of the web
pages of the proxy. The html directory describes the path where the proxy
will look for customized web pages. If you are interested in designing your
own web pages, please contact snom. However, the customization will
take a significant effort.

54 • System Settings

[ S N O M 4 S P R O X Y M A N U A L ]

5

snom technology AG • 55

6 System Status

After setting the proxy up you might be interested in the system
status. Like in the setup, there is a differentiation between system status
and domain status. This chapter describes how to check the system
status.

6.1 Server Log

The proxy keeps a certain number of logs message after the fifo
principle in memory. You can access these log messages through the web
interface. To clear the log, go to the bottom and click on “Clear”.

6.2 Call Log

A call is logged when the proxy received an INVITE that has been
authenticated properly (so it would trigger a RADIUS request). First, the
call goes into the Current Calls list. After the proxy receives a BYE of the
call times out, it goes into the Call Log.

6

56 • Specifi c Account Types

[ S N O M 4 S P R O X Y M A N U A L ]

The call log has the following fields:

• Date/Time: The date and time when the call started (in GMT).

• Duration: The duration of the call in hours, minutes and seconds.

• From: The originator of the call. If you click on the originator, you
see all SIP packets that were involved in this call.

• To: The call’s destination.

The call log stores only the last 100 calls (unless changed in the
settings) and discards older calls. The call log is only reliable in so far as
the involved network elements follow the loose routing of the proxy. If
network elements violate this rule, the packets do not flow through the
proxy and the proxy is not able to determine the length of the call.

Please remember that the call log is sensitive information and
should not be accessible to unauthorized persons. See the comments on
security in this manual.

If the value of “Trace per Call” (in Admin mode, System Settings)
is set to a value bigger than zero, you will see a link in the call list. By
clicking on this link, you can see the SIP messages that were part of this
call.

6.3 Current Calls

Similar to the finished calls the proxy keeps a list about the not­finished calls. The web server displays the current calls in the same fashion
as the finished calls. Because the current calls are not finished there is not
duration information available.

6

snom technology AG • 57

[ S N O M 4 S P R O X Y M A N U A L ]

6.4 SIP Trace

Should a problem occur, a look at the messages that went though
the proxy can be very helpful. If you go to the SIP Trace web page, a list
of the last messages appears on the screen.

The list has the following elements:

• Time: The time when the packet was sent or received.

• Type: The type indicates whether the packet was received (R) or
transmitted (T). By clicking on the symbol you get a list of all packets
that have the same call-ID as the packet.

• Source/Destination: Here you can see which transport layer (UDP or
TCP) was used, the IP address of the source or destination, and the
port that was involved.

• Header: Here you can see the first line of the SIP message.

By clicking on the header line, you get the whole packet:

The proxy actually keeps more messages than are displayed on
this list. This is necessary because it may take some time until the user
clicks on a specific packet and the proxy does not know when the old
packets are no longer needed. If you have a lot of packets flowing through
the proxy, it might be that older packets are no longer available.

6

58 • Specifi c Account Types

[ S N O M 4 S P R O X Y M A N U A L ]

6.5 Replication Trace

The replication trace is similar to the SIP trace, but filtered by
replication messages. This way, you can keep a better overview on these
two issues.

6.6 Unavailable Hosts

The proxy keeps a list of IP addresses that did not respond to SIP
messages. This feature is necessary when a server becomes unavailable
and messages have to take a different path. However, it can be surprising
in testing environment where servers are sometimes taken from the
network. The web interface offers a view of the list.

The system administrator can check the list to determine if
the proxy has avoided sending packets to a location that has become
unavailable.

6.7 Memory Usage

The proxy is supposed to run for a long time without restarting.
Therefore, the memory usage is very important to ensure system
stability.

Under normal circumstances, the proxy should allocate around
10-15 MB of memory for the operation. Most of the memory is used for
storing history information that can be accessed via the web browser (call
logs, packet trace).

The web interface gives information on the number of allocated
objects. This information might be more helpful for indicating memory hot
spots than a pure memory usage number. The memory usage is divided
by domains also.

6

snom technology AG • 59

[ S N O M 4 S P R O X Y M A N U A L ]

6.8 System Information

The system information web page shows you what version of the
proxy you have and what license type you are using. You also see how
many licenses you are currently using on that system.

6

60 • Specifi c Account Types

[ S N O M 4 S P R O X Y M A N U A L ]

6

snom technology AG • 61

7 Domain

Settings

7.1 Settings

7.1.1 Similar Settings

Some of the domain settings are similar to the settings on system
level. The Log Level, the Internal Call Trace Length, the Internal SIP Trace
Length and the Internal LOG Length are similar to the settings on system
level.

The Email settings affect emails that are sent from domain level.
See the explanations on system level.

The http password is checked when you log in as domain
administrator. Please enter the password twice in order to change it
successfully.

7.1.2 Emergency Location Information

Currently there is a discussion on how emergency location
information can be provided to the fire and police departments. This is a
difficult topic and there is no common standard available today. We offer
a simple approach to provide information based on the authenticated user
in the From header of a request. The user has to provide the location
information, the proxy just copies that information into the INVITE
request.

The E911 Location header is inserted into INVITE packets when
the location information is available for a specific user. The setting on this
web page merely specifies the name of the header as this has not been
standardized yet.

7

62 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.1.3 Authorization

Authorization deals with the problem that users first must make
sure that they really are who they pretend to be. This is important when
users want to access valuable resources, specifically resources that cost
money. For example, calls that go to PSTN should be authenticated before
they are forwarded to the PSTN gateway.

The default script uses the following algorithm for checking the
authorization:

• If the packet is already part of an existing call, there is no authorization
check. This avoids many problems with hanging up where the proxy
would reject a BYE because of non-existing credentials.

• Otherwise, it checks if the Authorization code in the SIP packet. If
the authorization matches the From header, the proxy accepts the
packet.

• If the packet is not accepted, it checks if the request-URI addresses
a user on the proxy. If this is the case and this step is enabled in the
web interface, the proxy accepts the packet.

• If the packet is still not accepted, it checks if the Via-count is one
(that means the packet comes directly from a UA). If this is the case
and the source IP address matches the list of trusted IP addresses,
the proxy accepts the packet.

• Otherwise if the via count is at least two, it checks if the packet
comes from a trusted IP address and has a P-Asserted-Identity
header set. That means, someone who the proxy trusts has already
made sure that the packet can be trusted.

• Otherwise the packet will be rejected.

If the script finds that the packet is authenticated (except for
accessing a local resource), it inserts a P-Asserted-Identity header. That
means, even if the proxy believes that the packet is ok because the user
agent is on the list of trusted IP addresses, it will insert the header.

The list of trusted IP addresses is a white space-separated list of
entries of the following format:

• You can use the plain IPv4 format for the IP address, for example

192.168.0.1

snom technology AG • 63

[ S N O M 4 S P R O X Y M A N U A L ]

7

• You can also use a subnet mask associated with the IP address.
Put the number of used it’s behind a slash symbol, for example

192.168.0.0/24. This pattern would match 192.168.0.29, but not

192.168.1.1.

• The name localhost stands for the local IP address.

Please note that is you have a user without a password, this user
will not be challenged. If someone finds out about this, he can easily
abuse all the resources that are available to that user. Therefore, if you
care about security, you should make sure that users have a reasonable
password.

7.1.4 Canonical Names

When you call a user on the proxy, you might call an alias name
on an alias domain name. Some user agents have a problem with this.
Specifically, a PSTN gateway will have problems inserting the right caller­ID in this case. Therefore, we added a feature that changes the To- and
From-header if they are known to the proxy.

The normalization procedure also inserts the name that you store
along with the account. This is a nice feature as many user agents are
able to display the “display-name” on the screen. Then you will always see
the display name when someone calls through the proxy.

7.2 Registration Preferences

7.2.1 Self-Setup

Sometimes you want that users set their account up themselves.
For example, in an office environment users sometimes should be able
to set up an account without having administration rights. The procedure
how this will be done is described in the login chapter.

However, be careful with this feature. Every account that is
being set up adds another license to the system. Therefore, we strongly
recommend not using this feature for an open community, for example on
the public Internet.

64 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.2.2 Min/Max Registry Time

With these two settings you control for how long a user agent may
register. The minimum value limits the number of REGISTER requests,
which may be important if you have many user agents. The maximum
number limits the time until a registration problem stabilizes.

7.2.3 Default Probability

The default probability defines with which probability a user is
available. Most user agents today don’t provide this parameter any more
and most of the time it is not used any more by the proxy. However, if you
perform sequential forking this parameter is still important. A value of 1
is a good default value.

7.3 Dial Plan

7.3.1 How it works

The dial plan is a flexible way to tell the proxy what to do with
calls that do not go to a registered user. If you have a “standard” problem,
using the dial plan via the web interface can easily solve your problem;
if you want to do something more advanced, you better use the scripting
interface instead.

The algorithm for checking the dial plan is simple:

snom technology AG • 65

[ S N O M 4 S P R O X Y M A N U A L ]

7

• Determine the source user/group by looking at the “From” header of
the request (take only a look at the URL provided there)

• Determine the destination by looking at the “To”-Header

• Go through the dial plan and take the first match found as result (if
there is no match, allow the request). Note that in previous versions
the proxy was taking the last match (this was a bug). The proxy now
follows the numbering what is shown on the left side.

Checking the user/group limits the pattern to a specific list of
users. This way you could, for example, grant the sales people the right
to make international calls, while everybody else is limited to local calls.
Looking at the destination you can find out if the call is local, international,
going to the boss, and so on.

The matching process is done using the following “wildcards”:

• ‘?’ matches any character as long as there is one.

• ‘$’ matches a E164 number (0-9, #, * and also + and -).

• ‘*’ matches any character multiple times, even if there is no
character.

• ‘%’ matches E164 numbers multiple times, even if there is no
digit.

• ‘~’ matches one of the domain alias

• ‘=’ matches the PSTN gateway.

• ‘[a-z]’ matches a character range (in this example from a to z).

The comparison process includes the sip identifier at the beginning

of the URL.

The action can be one of the following:

• “Forward” directs the call to the provided URi pattern, typically a
PSTN gateway. The argument must be a complete URI, for example
sip:[e-mail].

• “Call User” tells the proxy to fork the request to all registered users.
You must provide the user as argument, without a scheme before it
and without a domain name behind it.

• “Deny” tells the proxy to forbid this number (error code 403
Forbidden).

66 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

• “Redirect” tells the proxy to redirect the call to the URI (including
scheme and domain) in the argument.

• “Redial” tells the proxy to search the last dialled number and forward
the request to that number. The argument tells the proxy what user
to take for that redial (the format is like Call User).

• “Pickup” initiates a pickup of a ringing call (see description below).

• “Takeover” initiates a pickup of an established call (see description
below).

• “DND” functions are also described below.

• “Incomplete” tells the proxy to signal that more digits are
expected.

• “Not Found” triggers the proxy to send a “404 Not Found” error
code.

The destination pattern may include some special variables:

user[:[start][:[length]]]: The username of the destination. If the

start position is present, a substring starting
at position start is taken. If the length
parameter is present, only length characters
are copied.

host: The host name of the destination.

port: The port of the destination. If no port is

available, the default port (5060) is used.

cport: The port of the destination preceded wit a

colon. If no port is present, this variable
returns the empty string.

url: The complete destination url.

p:parm: This pattern will extract a parameter stored

in the user settings. For example, p:xyz gets
the parameter xyz from the user which is
addressed in the To-field.

If you use an “f” in front of the names, you access the from
instead of the to (for example, “fhost” instead of “host”). This is helpful
when you want to select the destination depending on the source (for
example, when reaching the mailbox with a number like “*69”). The fp
fetched a parameter from the From-header user.

snom technology AG • 67

[ S N O M 4 S P R O X Y M A N U A L ]

7

A typical destination pattern could be “sip:{user:1}@192.168
.0.248:5060”. In this example, the first digit of the dialled number is
removed and sent to a PSTN gateway.

7.3.2 Call Pickup

The proxy may initiate a call pickup for an account that is being
called or which has a call going on. In order to use this feature you must
use the dialog agent feature on the proxy and the call destination must
be an account on this proxy. Both hunt groups and normal accounts may
be picked up.

The argument to the pickup is the account number. Please do not
specify the complete SIP URL. The account must be part of the domain.
You may use the patterns described above to generate the account number
(for example, “{fuser:3}” on number *11401 will pick up the call from
account 401).

When an entry in the dial plan matches the pattern, the proxy
searches the incomplete calls of the account. It takes the first call which
is not connected and redirects the pick up call.

The proxy has to route the pick up INVITE to the final destination,
because the user agent does not have this route. Therefore, the incomplete
call is marked for pickup; if you dial a ringing call that is nor marked for
pickup, the proxy will handle the request transparently. For picking up a
ringing call the result will normally be that the pickup does not work.

7.3.4 DND Feature Codes

The proxy supports redirection of calls to specific numbers when
a user is not available or does not want to be disturbed. While this feature
can be used easily from the web interface, it is inconvenient to dial a
number and have the same functionality.

The user that will be affected by the dial plan entry is the first word
of the argument list. The arguments are separated by a space character.

The user enters the DND feature code as a telephone number.
Therefore, the call must be forwarded to a media server account, where
the user hears an announcement “thank you for your feature code”. The
URI for this announcement if for all feature codes the second word of the
argument.

68 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

The optional third argument tells the proxy where to redirect a

call (home number or road number).

Corresponding to the web interface there are four codes:

DND On: This puts the user offline. All calls will go directly to the

mailbox.

DND Off: This puts the user online. The calls will go to the registered

user.

DND Home: This tells the proxy that the user can be reached at his

home number. If the third argument is not present, the proxy will
take the last home number. If the third argument is present, the
proxy will set the home number accordingly.

DND Road. The proxy will redirect the calls to the provided third

argument. This is a simple call redirection.

7.3.5 Example 1: North American Dial Plan

This example is suitable for a proxy located in the USA.

Rule Mode User/Group Pattern Argument

1 Incomplete * *

2 Forward * sip:911*@~* sip:911@gw1

3 Forward * sip:[1-9]$$$$$$@~* sip:{user}@gw2

4 Forward * sip:0[1-9]$$$$$$$$$@~* sip:{user}@gw2

5 Forward * sip:00%@~* sip:{user}@gw2

Rule 1 defaults all calls (not for registered users) to „incomplete“.
Rule 2 redirects all emergency calls to the gateway number one, which
could be connected a local analog line. Rule 3 redirects local calls (7 digits
not starting with 0) to the second gateway; rule 4 does this for national
calls (a prefix of 0 indicates a national call). International calls start with
two 0s and get redirected in any case to the gateway; this works only if
the gateway is able to generate incomplete responses.

7.3.6 Example 2: Do not allow cell phone numbers
to certain users

In this example, only certain users may call cell phone numbers
(400-499 and 101). This example makes sense if the users 101 and 400-

snom technology AG • 69

[ S N O M 4 S P R O X Y M A N U A L ]

7

499 are listed in the “well known” user list in the User Management list.
This example is for Germany.

Rule Mode User/Group Pattern Destination

1 Incomplete * sip:$@~*

2 Incomplete * sip:$$@~*

3 Forward * sip:$$$%@~* sip:{user}@gw

4 Deny * sip:01$$$$$$$$$%@~*

5 Forward sip:4$$@~* sip:01$$$$$$$$$%@~* sip:{user}@gw

6 Forward sip:101@~* sip:01$$$$$$$$$%@~* sip:{user}@gw

Rules 1-3 redirects call to the gateway if at least three digits are
available. Rule 4 defines an exception to this rule if the number starts
with 01 and has at least 11 digits (like 01721234567). These numbers are
denied for all users, and rules 5 and 6 define the exception to this rule:
users 400-499 and user 101 is allowed to place these calls.

7.4 Controlling

In office environments, the controlling department typically
needs to distribute the telephone bill on cost or profit centers at the end
of each month. The snom 4S proxy supports this task with the controlling
settings.

Controlling is not billing. The information that you receive from
the controlling module does normally not match the exact cost that a call
caused. This is because the real price for a call depends on many factors
like day of the week, time of day, duration, special offers and so on.
However, the controlling module can generate fair data to distribute the
cost onto the cost and profit centers in an office.

The controlling feature is not supposed to be used for large scale
installations. If you want to bill users, please use the billing features of
the proxy.

7.4.1 Defining Rates

First of all, you need to specify what rates you use. This is done
by using patterns (like the patterns used in the dial plan module). If
you want to match several patterns for one rate, just put space between

70 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

the patterns. You can define a new group by using the last empty line;
to remove a group, just remove the name of that group. The price is
measured in units per minute.

The “Normal” type beautifies the destination URL before feeding
into the rate pattern matching algorithm. That means that it strips the
domain name (if it is in the domain context) and removes the scheme
and parameters. This is typically ok if you run the proxy in an office
environment.

The proxy takes the first match it finds. If you want to enforce
that one rule is considered before another one, you need to use a name
that is lexically smaller than the following rule. In this case, you want to
use numbers like “01 Local” and “02 National”.

7.4.2 Defining Groups

In many environments, you want to group users into cost or profit
centers. This is also done with patterns.

Again, the proxy matches the pattern from top to bottom and if
you want to ensure that some patterns are searched first, you need to set
the names accordingly.

7.4.3 Controlling Data

By selecting the controlling data webpage, you will receive a
report in Microsoft Excel format. The sheet will be automatically opened
in your web browser (if it supports the Microsoft format). Otherwise, you
need to save the sheet in a separate file and open it manually.

The controlling sheet contains information about the last three
months. The number of calls and the accumulated duration is available.
The sheet sorts the users by groups and calculated the sum per group and

snom technology AG • 71

[ S N O M 4 S P R O X Y M A N U A L ]

7

connection type. All calculations are done by formulas, so that changes in
the data are automatically reflected in the sums.

7.5 Address Books

The proxy stores address information in several places:

• For each user a list of missed and placed calls is kept together
with the account information; this address source is automatically
included in the number completion process.

• The name information of the account is part of the domain address
book; no specific action is required to use this address book.

• Every account may have its own private address book;

• Within a domain, group address books are available.

7.5.1 Number Guessing

When a user starts dialing a number of the phone, the phone
typically searches the local database for completions of this number. This
approach is fast and hits the numbers on the call history and the private
address book; however this approach has the disadvantage that addresses
can not be shared with other devices and group members and that it is
often hard to set up address book in the end device. Also, the limited
memory on many end devices reduces the number of available contacts.

In order to make SIP telephony a more enjoyable experience,
the proxy searches the above listed address sources for completions of
numbers. This mechanism works between snom phones and the snom
4S; however other vendors can easily integrate this feature into their
products.

7.5.2 Defining Address Book Groups

To set up an address book group, enter a name for the group
and set the members. The members may be defined using the pattern
matching rules known from the dial plan. You also need to specify an
administrator for this group. This account will be able to set and change
the actual address book.

72 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.5.3 Setting Up an Address Book

The administration of the address book is described in the user

manual.

7.6 Error-Information

Error-Information is not directly part of the routing. This feature
merely provides the user agent client with additional information if a
request fails. This is typically a SIP URL of a media server account which
reads out the error aloud (for example, „The number you have dialled is
temporarily not available“).

Should something go wrong, a telephone system usually generates
error reports. In many cases the exact error messages are visible at the
protocol level, but the user does not get more than a busy tone. SIP offers
improved error information to users. The error information may be on
a web page (e.g. http://www.company.com/error-explanations/err_404.
htm), but it may also be a SIP URL. While most VoIP phones can not
display http content, they can place a call to an announcement server
that reads out the error message. This means that the system is much

snom technology AG • 73

[ S N O M 4 S P R O X Y M A N U A L ]

7

smarter than traditional telephone systems. You can even customize the
announcements according to your special requirements.

You can simply set up the error information redirection by selecting
the appropriate error type and enter the destination that should be put
into the response.

If you don’t define a destination for a specific error code, the proxy
will take the generic destination. This generic destination may include the
pattern “{code}” which will be replaced with the error-code (e.g. “404”).
If your media server understands additional parameters in the number
(as the snom 4S Media Server), then you can set up one error explanation
account for all codes.

If you leave the generic destination empty and no specific code
has been set up, no error-information will be generated.

For the available error messages, please refer to RFC3261 and
the extensions that apply. The proxy includes a list of the most frequently
used error messages.

7.7 Script

Scripting is a powerful way to customize the behaviour of the
proxy. However, it is a complex topic that is out of scope of this document.
Please check additional information on how to use the scripting of the
proxy (for example the Script FAQ in the whitepaper section on http://
snom.com).

7.8 Account Administration

7.8.1 Purpose

Just like you specify Email accounts you may setup SIP user
accounts on the proxy. These accounts must always occur in the context
of a domain.

For example if you set up the account “bob” in the domain
“company.com”, you could call that account with the SIP URL sip:
[e-mail]. If you specify alias names as well, you could call

74 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

bob also under these alias names without about having to register these
alias names as well. For example, you could set up bob.miller and bm
as alias and then what would also be reachable under the SIP URL sip:
[e-mail] and [e-mail]. Please notice that user
names are case insensitive. if you set up alias names for the domain
as well, for example “company.net”, Bob would be also reachable under
the SIP URL sip:[e-mail], sip:[e-mail] and sip:
[e-mail].

Users may register more than one time with the proxy. When
a user agent registers with the proxy it also says how probable that
registration is. When the proxy is trying to find that account, it will send
out the request to all registered users, one after another if it is an invite
request. For more details, see below on sequential forking.

Sometimes that this behaviour is undesirable, because you know
that there can be at most one registration. This is often the case if you
want to try registration with the user agents and that changes its IP
address constantly or if he registers a device that exists only once (for
example, the fax machine). In this case you use a single registration.

Like with an e-mail account, you may specify credential information
with the account. This information consists of a user name and a password.
The user name is usually identical to the account name; however you may
specify a different name if you want to make authentication even more
secure. The password is not transmitted directly in SIP and therefore
provides a good mechanism to make sure that the user is the one that he
or she pretends to be. However, if you choose a four of five digit PIN code
it is relatively easy to guess that PIN code by an observer by trying out all
possible combinations. A secure code therefore must have at least several
million or billion valid combinations.

Just like with the administration, the names for the account must
be unique. Of course it does not make sense to use an alias name as
primary account name somewhere else.

7.8.2 Setting up an account from the web
interface

You can easily set up accounts from the web interface. To do so,
make sure you are in a domain context and go to the “add normal user”
web page.

snom technology AG • 75

[ S N O M 4 S P R O X Y M A N U A L ]

7

In the Account Identity part you find the “Account Name”. This
will be the primary (canonical) name of that account. In the “Alias” field
you can fill in a list of space-separated alias names for that account.

If you want that this account may answer authentication
challenges for other accounts, fill in the “Answer Challenging for Account­Pattern”. This is a space-separated list of account names. The name may
contain the pattern matching wildcards known from the dial plan (e.g. 41*
matches all accounts starting with 41). See below 3rd party registration.

The Identity is the display name for that account. If you turn the
canonical user name feature on, the proxy will automatically insert this
name into the call packets. If you using the Japanese version of the proxy,
you may also insert a “reading” field that will be used when you search a
user.

76 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

To make the web and SIP access safe, you should provide web and
SIP passwords. Please remember that if you don’t provide a SIP password,
practically everyone can spoof the identity and use the resources of the
proxy that this user has. If you don’t provide a web password, practically
everyone cal log in to the web interface and check which calls that user
made recently.

If you provide a ring melody URI, the proxy will automatically
insert that string into INVITE packets. User agents that understand the
Alert-Info header will then ring with a different ringing melody.

You should also provide the Email information. The proxy will
then be able to send emails, for example when that user misses a call.

If you press the add button, that user will be added to the data
base.

7.8.3 Setting up a hunt group and pickup group

Setting up a hunt group or a pickup group is similar to setting up
a normal user. However, on this web page only the basic information for
that hunt group is provided. You must go into the hunt group later to set
up the details.

snom technology AG • 77

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.8.4 Changing Normal User Settings

There are a couple of settings associated with a normal user
account. The settings are divided into user-visible and user-invisible
settings.

7.8.4.1 Authentication Name

Usually the proxy assumes that the authentication name is
identical to the account name. However, sometimes you want to change
this. In these cases, you can enter a different name in the authentication
name field.

7.8.4.2 Single Registration

By checking “Single Registration” you may allow the user to
register only one contact. Previously registered contacts are dropped
when a new registration is received. This feature is helpful when user
agents register from changing addresses and you want to avoid that the
proxy tried to reach that user on dangling addresses.

7.8.4.3 3rd Party Registration

In some cases you want to allow an account to register on behalf
of somebody else. This make for example sense if your B2BUA wants
to register accounts locally. But it could also be used for non-REGISTER
messages, for example if you want to allow that an accounts places calls
on behalf of someone else.

Instead of changing all affected accounts, the snom proxy allows
the domain administrator to specify the affected accounts by a pattern
(“Answer Challenging for Account-Pattern”). The pattern is a list of patterns
known from the dial plan that is matched against the account name that

78 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

is challenged. If there is a match, the proxy accepts challenges from the
3rd party account.

For example, when you put the patterns “41* 42*” in the Answer
Challenging for Account-Pattern setting, the account with this setting may
register accounts on behalf 411, 412, 413, 420, 421 and so on. Because
this affects the security of those accounts, this setting can only be changed
by the system administrator.

7.8.4.3 User-Visible Settings

Most of the user-related settings may be set by the user himself.
This makes the setup process much more flexible and takes load away
from the system administrator.

The user visible settings are described in a separate document,
which should be made accessible to users.

7.8.5 Importing a list of users

Sometimes you want to load more than one user at the time.
In this case you can prepare the file that contains the line for each user
account that you want to set up.

7.8.5.1 Old Proxy Format

Proxy version 2.40 defined its own format for importing users.
The line has the following format.

The first word in the line identifier is account name, sometimes
referred to as the primary account name. The second word defines the
user name, the third word defines the password. If the fourth word is
set to true, the account will be set up a single registration account. The
following words are taken as alias names of the account.

If the line starts with the hash symbol (“#”), it is read as a
comment.

Uploading accounts from file does not affect the other accounts
of the domain as long as they do not occur in the file. This is a change to
the behaviour of the previous releases of the proxy.

To upload such files go to the bottom of the web page, select the
file and upload it by pushing the upload button.

snom technology AG • 79

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.8.5.2 Importing Accounts from Spreadsheet
Tools

To import data from a spreadsheet tool, you need to set up one
header line that contains the name of the fields that you like to import.
You can choose any name; however the following names are reserved for
proxy-internal use.

alias The alias field defines the names of the account. The field is

separated by space; the first name is the primary name of the
account and the other fields contain the alias names of the
account. Example: 123 fred.feuerstein f.feuerstein ff

display_name This is the name as is should be displayed to the user. Example:

Fred Feuerstein.

email_address This email address is used to send Emails to that user (e.g.

fred@flintstone.com)

email_ missed „true“ if the user should receive an email when he missed a

call

email_register „true“ if the user should receive an email when he gets

registered or deregistered

mb_target The SIP URI for the mailbox of the user (e.g. sip:fred@flintstone.

com)

mb_timeout The time in seconds after which the proxy should redirect the

call to the mailbox

name, pass The name and password as it should be used for challenging.

The name is typically identical to the first alias name.

red_location The redirection destination. „road“ means that the redirection

goes to the road number, „offline“ means all calls go to the
mailbox, „home“ means the user should be reachedat home,
„office“ (which is the default) means the user should be located
at thisregistered contacts.

red_road The redirection destination when the user is on the road

red_target The redirection destination when the user is at „home“

ring_melody The ring melody that should be used when the user is being

called. The default value is „default“, other valid values are
„melody1.wav“ … „melody8.wav“.

single If set to „true“ the user may register only one contact.

webpass The web password for this user

80 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

registrations,
domain, last_
mwi, messages,
mwi, type

These names are reserved for internal use by the proxy.

A typical example would look like this:

alias display_name email_address mb_target
101 cc c.clever carl.clever Carl Clever [e-mail] 9101@[e-mail]
105 dd duck dogbert d.duck Dogbert Duck [e-mail] 9104@[e-mail]
107 rs ron sum r.sum Ronald Sum [e-mail] 9107@[e-mail]

The table must be saved as in unicode format (separated by

TAB).

7.8.6 Account List

To see which accounts are currently available for the proxy, just

go the show list.

To delete an account, just click on the delete button next to the
account. And to edit an account, click on the edit button. Please remember
that changing the primary name of an account requires that you first
delete the account and then set up a new account.

By clicking on the “Enabled” icon, you can disable or enable the
account. Disabled users can be called, but can not initiate calls.

7.8.7 Storing information

The proxy creates a file for every user account. This file is located
in the directory named after the primary name of the user account. Alias
also create files which point to the primary account. All account related
files are in XML format and you can edit them with a plain text editor. You
can put them under revision control and make backups like you do with
other normal files.

In contrast to the domain files, the proxy does not cache account
files. They all loaded on demand and if a change occurs it is written back

snom technology AG • 81

[ S N O M 4 S P R O X Y M A N U A L ]

7

to the file system. Therefore, it is not recommended to modify these files.
If you change a file, it might get overwritten by the proxy without taking
notice of the new content. If you modify files you might end up with highly
indeterministic and very difficult to fix problems.

7.9 Plug and Play

The proxy supports a mechanism for the automatic configuration
of user agents. Using this mechanism, you can plug an user agent into the
network without any manual setup on that phone.

7.9.1 Server Detection

The very first step in the automatic configuration is DHCP (dynamic
host configuration protocol, RFC 2131). This protocol usually provides an
IP address, the netmask, the default IP gateway and the DNS server.
Often, it also provides the domain name and the name of the host in the
network. These settings are used in the detection process.

Some DHCP servers offer a setting of a “SIP server” as well.
This setting tells the user agent explicitly, where the SIP server of the
network is located. However, as this feature is not widely available today,
the automatic configuration process may work also without it (see below).
This option has the code 120.

Before a client can download its settings, it needs to locate the
configuration server (in this case, the proxy). This is done in the following
steps:

• If the DHCP server provides the SIP server, the user agent contacts
this address according to the SIP host location rules (DNS NAPTR,
DNS SRV, DNS A).

• If the DHCP server provided a domain name, the user agent tries to
contact the host with the name „sip“ in that domain (for example,
if the domain is company.com it will try sip.company.com). This
location is also done using the SIP host location rules (RFC3262).

• If a username and a proxy name have been specified on the user agent
(manually), it will contact the SIP server on the specified location
(for example, if the user agent registers as sip:[e-mail],
it will contact company.com).

82 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

• Otherwise, it will use the setting „setting_server“ and download the
settings from that location. If none of the steps succeed, the user
agent uses a default value (for snom phones, for example http://
www.snom.com/snom360/snom360.htm).

Practically, that means you should try the following setups:

• If your DHCP server provides a SIP server setting, use it. Set the
DNS entries (preferably DNS SRV) accordingly. If you want to keep
things simple, you can just specify the IP address of the proxy in this
DHCP option; in this case you don’t need to change anything in the
DNS server.

• If your DHCP server provides a setting for the domain name (most
servers do), you should put the name of your domain there. In this
case, you must set your DNS server up accordingly and the host
„sip“ in this network must resolve to the proxy.

7.9.2 Setting Groups

You may define a number of setting groups. The definition is
silimar to the definition of address books (see 12.4). You simple have to
specify a group name, its members and an administrator account.

The group name can be any string; however the groups are sorted
alphabetically and the search for groups start from the top. It is a good
hint to use names that come first for special groups and names that come
late for generic groups. For example, you can name setting exceptions
with a prefix “1-” to make sure that they are searched first.

The members are a space-separated list of patterns. You can
use the same patterns as in the dial plan, including the symbols “*”,
“%” or “?”. The administrator identified the account which is allowed to
administer the settings group (see below).

If you specify a group with only a “*” pattern, anonymous devices
may retrieve their configuration information from this group as well. This

snom technology AG • 83

[ S N O M 4 S P R O X Y M A N U A L ]

7

has the big advantage that you can use the installation wizard on the
phone to set up the account without having to set up the MAC address on
the proxy.

You may delete groups by clicking the delete button. You can edit

a group by re-defining a group.

7.9.3 MAC Addresses

If you want to make sure that a phone with a specific MAC address
gets a specific extension number, you need to enter this assignment in the
MAC address table setup in the domain.

Just enter the MAC address that you want to assign in the empty
field at the bottom and put the account number into the right field. Don’t
enter the “:” symbols between the digits. If you enter incomplete MAC
address, the proxy will automatically complete it with the “000413” prefix
of snom phones. If you want to remove an assignment, just clear the
respective field in the list and press “Save”.

7.9.4 Settings

The setting names and their meanings depend on the used
products. Please refer to the product documentation for this purpose.

However, the snom 4S offers a set of standardized settings. These
settings are the language, the tone scheme and the time zone which can
be selected via a select input.

The programmable keys can be assigned like on the snom 200.
Please refer to the snom 200 manual for more information.

84 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

The music on hold (MOH) server may also be specified. Other
settings can be set by their name and their value. To delete one of these
other settings, remove the setting name from the list.

7.9.5 Software Version

You can specify which endpoints should receive which software
versions. There are two principle ways to do this:

• You put the images in the directory for the domain and let the proxy
serve the files from the built-in web server. In this case, you must
not use any path names and no scheme to describe the location of
the image (allowing path names would open a security hole).

• You put an http URL into the field. The phones are then responsible
for retrieving them.

Before the proxy offers a software version, it matches some
fields. The “vendor” field represents the manufacturer of the end point,
the product the product name (for snom, the vendor name is “snom”, the
product “snom100” for snom 100, “snom105” for snom 105, “snom200”
for snom 200, “snom220” for snom 200 and so on). The account field
contains a list (space-separated) of patterns that is matched against the
account. The locations indicate where the software can be found.

Please note that you need to run version 2.01h or higher on the
snom phones to use this update mechanism.

7.10 Registered Users

To see which users are registered at the proxy, you can go to
Status/Registered Users. You will see a list of the users sorted by account
name and probability. On top you see the current local time.

The columns have the following meaning:

• User: The account that is used as identification in the proxy. This
corresponds to the “telephone number” of the user within the proxy
realm.

• Registrar: The registrar the user is registered on. This is one of the
names listed in the hostnames.

snom technology AG • 85

[ S N O M 4 S P R O X Y M A N U A L ]

7

• Contact: This field has two components. One is the path used to
route requests to the destination, the other the contact where the
user can be reached. The path is optional.

• User-Agent: The user agent identification tells the proxy if a license
is required.

• User-Agent: This is the unique identification that the proxy has
chosen for that user agent.

• Expires: The expiry time in seconds. If you click on the link behind
this number, you get to the SIP message trace that is associated
with the registration.

• GRUU: The GRUU is a unique identification for this registration.

• Delete: If you click on the symbol, the registration is removed. This
is helpful if you want to manually remove a registration (otherwise
you would have to wait until it is expired).

7.11 Other Status Information

The Call Logs and Current Calls have already been described in
the system administrator chapter. The domain administrator has access to
the calls that were affecting the selected domain.

The SIP Trace shows all SIP messages that went through the
domain. The domain log shows all log messages that are available in
the domain. The Information page shows version information about the
proxy.

7.12 LED Notifications

In a PBX environment, you want to see the status of incoming
calls and the status of your colleagues. The snom 4S proxy supports two
methods to do this. The first method uses a document that is currently
being in the IETF (dialog-state). The second method uses a simple
notification method that informs interested subscribers about the call
state of the whole domain.

86 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

7

7.12.1 Dialog-State Notifications

The previous versions of the proxy had a “dialog agent” which
was monitoring the incoming and outgoing packets of the proxy. From
these packets, it was trying to determine the call state of extensions. This
approach was sound from a theoretical point of view; however it caused
problems because all potential subscriptions had to be watched at all
times. Also, rebooting the system caused problems.

The new proxy is call-aware. That means it keeps internal records
about the ongoing calls. This is not necessary from a SIP standards
perspective; however it is helpful in a PBX-like environment. Because
usually there is a relatively small number of calls (compared e.g. to the
number of accounts), it is much easier to keep track of what’s going on on
the system. As a consequence, the notification to the interested parties
(phones with LED) is much easier.

When a user agent subscribes for dialog-state, the proxy will not
forward the subscription request, but handle it itself. The subscription
may look like this:

SUBSCRIBE sip:[e-mail];user=phone SIP/2.0
Via: SIP/2.0/UDP 192.168.166.158:2051;branch=z9hG4bK­go7nn80g7cos;rport
From: <sip:[e-mail]>;tag=kxgn1jxhdg
To: <sip:[e-mail];user=phone>;tag=7gl2k40526
Call-ID: 3c2766b88165-b5443khgrphb@snom360
CSeq: 27 SUBSCRIBE
Max-Forwards: 70
Contact: <sip:401@192.168.166.158:2051;line=jfolol7h>
Event: dialog
Accept: application/dialog-info+xml
Expires: 3600
Content-Length: 0

In this example, the extension 401 in the domain domain.com
would like to receive notifications when the state of extension 444 changes.
The subscription mechanism follows RFC3265.

When the state of extension 444 changes, the proxy sends a
notification. That notification includes an attachment which contains the
necessary information about that extension. See the following example:

NOTIFY sip:105@192.168.166.229:5060;line=4ys37kpm SIP/2.0
v: SIP/2.0/UDP 192.168.0.1:5060;branch=z9hG4bK-9ffce0289b4503f00c0c1
59dc58423f0
f: <sip:[e-mail];user=phone>;tag=wbq0fsxbjr

snom technology AG • 87

[ S N O M 4 S P R O X Y M A N U A L ]

t: <sip:[e-mail]>;tag=7bah0gudnq
i: 3c267009b2f8-97gqnpru7npf@192-168-166-229
CSeq: 672 NOTIFY
Max-Forwards: 70
Event: dialog
Subscription-State: active
c: application/dialog-info+xml
l: 506

<?xml version=“1.0“?>
<dialog-info xmlns=“urn:ietf:params:xml:ns:dialog-info“
version=“672“ state=“full“ entity=“sip:[e-mail]“><dialog
id=“dummy“ call-id=“3c32563262ba-ymw754lt1n49@192-168-191-254“ direc
tion=“initiator“><state>confirmed</state><local><identity>sip:466063
[e-mail];user=phone</identity><target uri=“sip:46606393@domain.
com;user=phone“/></local><remote><identity>sip:[e-mail]</
identity><target uri=“sip:[e-mail]“/></remote></dialog></
dialog-info>

The proxy always sends full updates. The attachment does not
really show what calls are going on on that extension, the proxy aggregates
the call states so that there will be only the most important call state
propagated to the user agent. The notification essentially contains two
important things:

• The state of the call. It can be “early” which means that the call is
ringing; “confirmed” means that the call is connected. Please note
that there is no “terminated” state, because the proxy always sends
absolute state.

• The Call-ID of the most important call. That ID is required when the
call should be picked up.

• The direction of the call can be “initiator” or “recipient”.

• The SIP URI of the caller and the callee is included in the local
and remote identity part. This information is also important for call
pickup.

When a user agent wants to pick up a call, it should send an
INVITE request to the proxy with the header “Replaces” set to the Call-ID
in the XML attachment directed to the target URI in the attachment. An
example could look like this:

INVITE sip:[e-mail] SIP/2.0
Via: SIP/2.0/UDP 192.168.166.158:2051;branch=z9hG4bK­eega5da2s6ki;rport
From: <sip:[e-mail]>;tag=2b9z6djnhi

88 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

To: <sip:[e-mail]>
Call-ID: 3c28d0db04e2-by5grmyr94n4@snom360
CSeq: 1 INVITE
Max-Forwards: 70
Contact: <sip:[e-mail];gruu=bu8m0mwa>
Replaces: 0024-0032-C0B1648A-0@192.168.0.247
Accept: application/sdp
Content-Type: application/sdp
Content-Length: 420

v=0
o=root 1666958159 1666958159 IN IP4 192.168.166.158
s=call
c=IN IP4 192.168.166.158
t=0 0
m=audio 54630 RTP/AVP 0 101
a=rtpmap:0 pcmu/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv

7.12.2 Domain State Notification

The domain state notification works in a completely different way.
Here the user agent registers for a dummy account that will inform about
all the state changes in the domain.

If you are implementing new user agents, you should not use
the domain state notification method as there is not accepted standard
for this. It is needless to say that this way of subscription requires that
you have a trusted zone in your domain, because every user can see the
whole activity in you domain.

In the domain preferences you will find a link to “LED groups”,
which contains a setting “Account for Subscriptions”. Your user agents
must subscribe for this extension with a packet like this:

SUBSCRIBE sip:[e-mail] SIP/2.0
Call-ID: 897B55CB897B55CB.68@192.168.125.240
CSeq: 1 SUBSCRIBE
From: <sip:[e-mail]>;tag=00505102375b
To: <sip:[e-mail]>
Via: SIP/2.0/UDP 192.168.125.240:5060;branch=z9hG4bK-00505102375b
Event: presence;IE-KeyPatternPG=1
Max-Forwards: 70
Expires: 3600

snom technology AG • 89

[ S N O M 4 S P R O X Y M A N U A L ]

Contact: sip:100@192.168.125.240
Accept: application/IE-KeyPatternText
Content-Length: 0

The parameter “IE-KeyPatternPG” indicates which LED-row that
user agent is interested in. However, the proxy will always send all rows to
all user agents. The content-type must be “application/IE-KeyPatternText”.
The proxy will send notifications whenever the state of one of the extension
changes that you set up in the LED Groups.

There are twenty LED groups available. Each group will show
different extensions on the LED. Typically, a group consists of sales agents,
secretaries etc. For example, you might want to define group 1 as the
group of sales agents, group 2 as the group of secretaries and so on. The
phone must select the group by it’s own (setting on the phone), because
the proxy always sends all groups in the notification.

In each group, you may define up to 24 LED. For each LED, you
can define which extension number will define the status of the LED. To
make the display easier, the proxy shows the list of extension numbers in
two rows. The first row shows extensions 1-12, the second row extensions
13-24. The extension number must be an existing account in this domain
(e.g. “123”). It is not possible to monitor the state of a SIP URI or the
status of other domain extensions.

Implementing call park and pickup is independent from the LED
status indication. Please use the dial plan to implement these functions.

7.12.3 Call Pickup and Takeover

The proxy may initiate a call pickup for an account that is being
called. In order to use this feature you must use the dialog agent feature
on the proxy and the call destination must be an account on this proxy.

Both hunt groups and normal accounts may be picked up. The
argument to the pickup is the account number. Please do not specify the
complete SIP URL. The account must be part of the domain.

You may use the patterns described above to generate the account
number (for example, “{fuser:3}” on number *11401 will pick up the call
from account 401).

When an entry in the dial plan matches the pattern, the proxy
searches the incomplete calls of the account. It takes the first call which
is not connected and redirects the pick up call.

90 • Domain Settings

[ S N O M 4 S P R O X Y M A N U A L ]

The proxy has to route the pick up INVITE to the final destination,
because the user agent does not have this route. Therefore, the incomplete
call is marked for pickup; if you dial a ringing call that is nor marked for
pickup, the proxy will handle the request transparently. For picking up a
ringing call the result will normally be that the pickup does not work.

Takeover is similar to call pickup. The difference is that takeover
will search for established calls, while pickup searches for not established
calls. While picking up already requires a strong trust relationship, taking
over a call requires even stronger trust. Usually, the takeover feature is
used to pick a parked call from a park server or to retrieve a call from the
waiting queue. Therefore, you should choose patterns that restrict the
takeover only to your park orbits and your waiting queues.

In the example below, there is a park orbit called “1010”. When a
user agent calls 611000, it will be redirected to the park orbit. This way,
the user agent may park the call (and refer it to the calling party). To pick
it up again, it just has to call 621000.

snom technology AG • 91

8 Call Hunting

“Call hunting” is a powerful way of finding a user for a telephone
call. Instead of merely ringing all users registered with the SIP account,
call hunting calls other users sequentially or in parallel. You can specify
the time that the proxy spends on each stage as well as other attributes
such as ringing melody. If nobody picks up the call, the proxy may redirect
the call to a default destination.

In addition, you may specify several aliases for a hunt account.
Depending on which alias is being called, you may define a different entry
stage for each alias. You can also specify the algorithm that the proxy
uses for going to the next stage.

In order to use the call hunting service, you need to create a
“Hunt Group” account. See the section on creating an account to learn
how to do this. The hunt settings are controlled in the “Call Hunting” tab
of the account settings (see the picture below).

8.1 Defining Stages

Every stage lists one or more numbers, a delay for the stage
and a ring tone. The number field contains all numbers that should ring
during this stage. The “number” may be a SIP URL or simply an extension
number that the proxy automatically converts into a valid SIP URL.

If a number is present in two consecutive stages, the proxy will
not stop ringing and then restart — it will keep on ringing with the ringing
melody of the previous stage. If a number is not on the next stage, the
proxy stops the user agent from ringing.

The delay value indicates how long the stage should last
(in seconds). If you do not provide a value in this field, the proxy will
automatically choose a value of 10 seconds.

The ringing melody that you select for the stage is proposed by
the proxy in the call setup message. This feature depends on the SIP user

8

92 • Hunting

[ S N O M 4 S P R O X Y M A N U A L ]

8

agent that is used. If it does not support this feature, it will ring with its
default ringing melody.

When you create a hunt account, it does not contain stages in
the beginning. Whenever you want to add another stage, simply fill in
the empty line and press the save button. The proxy will then create a
new empty line for your next entry and so on. To remove a line, clear all
numbers from the respective stage. If you wish to move a line, you need
to move the data of all the lines manually.

8.2 Defining the Algorithm

The proxy defines several algorithms for call hunting.

• Round robin: This algorithm always tries all stages no matter which
stage the algorithm starts with. This means that if you start with the
second stage, the proxy will go to the first stage after reaching the
end. This is the default algorithm.

• Until End: If you use this algorithm, the proxy will not perform a
wrap-around like the round robin. This mode is helpful if the numbers
on the list do not have equal priority.

• Only x stages: The proxy also defines modes where only a limited
number of stages are executed. In principle, this mode behaves like
the round robin mode, but limits the number of search steps.

snom technology AG • 93

[ S N O M 4 S P R O X Y M A N U A L ]

8

8.3 Default Actions

If nobody picks up the call, the proxy tries to find a default
destination. If you specify the default target, the proxy will perform a
final stage to search for the user. If you do not provide a time for this
stage, the proxy will keep ringing the numbers in this stage until the caller
hangs up.

If the default target also fails or was not specified, the proxy will
answer the call with the answer code that you provided. You may specify
a plain ASCII message here like “Call Hunting was not successful” or “The
number could not be found”.

You may also specify a SIP return code. In this case, you should
choose a 4xx-class code. To do this, simply put the error code in front of
the message like “404 This was not found”. By default, the proxy will use
code 480.

94 • Hunting

[ S N O M 4 S P R O X Y M A N U A L ]

8

Reader‘s Feedback

snom technology AG welcomes your evaluation of this manual and any suggestions
you may have. These help us to improve the quality and usefulness of our
documentation.

Please send your comments and suggestions to:

snom technology AG

Attention: Marketing Department

Pascalstr. 10B, 10587 Berlin, Germany

Fax: [phone]

Manual Name: snom 4S Proxy 2.44 Admin Manual (Jan 27, 2005)

Excellent Good Fair Poor

How would you rate the document
overall?

   

Are the installation instructions
effective?

   

Are the configuration instructions
effective?

   

Is the document properly organized?

   

Are the illustrations usefull and easy
to understand?

   

Are the suggested and default
values useful?

   

Did you find any errors in the document (please reference page)?

How might we improve this manual?

Name Title

Company

Telephone ( )

Thank you for taking time to fill out this form.

snom 4S Proxy
Administrator Manual

27. Jan 2005, Version 2.44
© 2005 snom technology AG
All rights reserved.
Subject to change without notice.

snom technology AG
Pascalstr. 10B
10587 Berlin, Germany
Phone: [phone]
mailto:[e-mail]
http://www.snom.com
sip:[e-mail]