eyeball sip server v8.0 administrator guide

Copyright © 2002-2015 Eyeball Networks Inc. Patented and patents pending. All rights reserved.

Eyeball SIP Server v8.0

Administrator Guide

Last Modified: January 2013



1. Eyeball SIP Server: Introduction

Introduction

This documentation is intended to be a comprehensive guide for configuring and running the Eyeball SIP Server.


2. Eyeball SIP Server: Overview

Overview

The Eyeball SIP Server is a fully SIP compliant (RFC 3261) stateless proxy . The main functions of the SIP Server include:

SIP-based call and message forwarding

User authentication by user name and password (WWW and proxy authentication)

Peer-to-peer audio/video calls

Text based server configuration file

Database backend for administration and statistics Scalable distributed processing

Figure 1: Eyeball SIP Server Architecture Overview


The Eyeball SIP Server consists of two components: an edge server component and a state server component (see Figure 1). Clients connect only to edge servers ; state servers are internal servers and

should not be accessible directly from the Internet. Edge servers and state servers communicate with each other and with the database.

In the simplest possible configuration, one edge and one state server are required and both server components can run on the same machine. In addition, both server components of the Eyeball SIP

Server interface with a database to obtain user information (used for authentication, etc.) and to perform user activity registration. In addition, each server component uses the database to obtain the status and location of the other server components ( edge and state) forming the Eyeball SIP Server.

In order to scale an Eyeball SIP Server installation, it is sufficient to start additional edge or state server

components during run-time on additional computers giving the database as a parameter in the server’s configuration file. The new server(s) will automatically be integrated into the existing server components without additional configuration requirement or interruption of the service. Once the new server is started,

it can immediately process requests from clients (edge server) or will take load off the already existing server components (state server). In the same manner, it is possible to dynamically take out single servers, e.g., for maintenance reasons. This will not lead to an interruption of the service, the remaining server components will automatically take over the load from the server that was removed.


3. Eyeball SIP Server: System Requirements

System Requirements

The Eyeball SIP Server has been certified for RedHat Enterprise Linux 6.x (64-bit) and CentOS 6.x (64-bit).

Eyeball Networks does not guarantee the correct execution of the servers on other than the certified distributions.

The current distribution of the SIP Server was tested using unixODBC, which is freely available from http://www.unixodbc.org/. The server may be configured to use more than one ODBC data source for

fault tolerance and load balancing purposes. In this case, the server will randomly connect to one of the data sources and automatically switch in case of failures.

Server Requirements

RHEL 6.x x64 CentOS 6.x x64

Pentium IV or higher

2 GB RAM

10 GB disk space

MySQL 4.1 or above

Apache HTTP server 2.0

PHP 4.3 or higher 128 Kbps IP or greater TCP/IP network connection

http://www.unixodbc.org/


4. Eyeball SIP Server: Installation

Installation

The Eyeball SIP Server package contains the binaries of both edge and state server components ( sipd and stated) and the necessary scripts, tools and documentation to install the Eyeball SIP Server.

A valid license file (obtained from Eyeball Networks) is required to start the each edge server (sipd). State servers are unlicensed components and do not require access to a license file.

For details on installation and setup, please refer to the INSTALL file found in the root directory of the

Eyeball SIP Server package. This file contains a description of the installation and initial configuration of the server components.


5. Eyeball SIP Server: Server Configuration

Server Configuration

The configuration files, sipd.conf and stated.conf, are required to run the Eyeball SIP Server. In order for

the server to access the configuration file, it must be readable by the owner of the server process. If not specified by –c command line argument, both server processes will look for their configuration files in the /etc system directory.

5.1. Eyeball SIP Server: sipd.conf

5.2. Eyeball SIP Server: stated.conf 5.3. Eyeball SIP Server: Scalability


5.1. Eyeball SIP Server: sipd.conf

sipd.conf

In the following sections, we give detailed descriptions of the configuration parameters for sipd. Most of the values should not be changed. The following parameters are available, starting with the parameters that must be changed in order to get the server running.

Network Configuration

Parameters Description

bind_address

Specify this numeric IP address to bind the service to a specific local interface or to any local interfaces. A system may have more than one

network interface. Use ifconfig command to get a list of available interfaces. Type “ any” if you wish to bind to all interfaces. If a specific interface is given, the server will allow connection only through that

interface.

private_address

Specify this numeric IP address that will be used to communicate with the state server and other SIP Edge Proxy Servers. The administration port

used to access the command line interface will also listen on this address. If this field is not specified, it will default to the bind address.

public_address Specify this numeric IP address that will be put in Via headers in SIP

messages. If this field is not specified, it will default to the bind address.

sip_port

Specifies the port where the SIP Server listens to UDP and TCP client requests. By default, the SIP port is set to 5060. Clients send messages

to this port. Since clients initiate the connection to the server, you must make sure that clients can reach this port. This can be done by running the server outside a firewall, opening this port on the firewall, etc.

websocket_port Specifies the port where the SIP Server listens for WebSockets connections. By default set to 5555.


sip_tcp_port

Specifies the port where the SIP Server listens to TCP client requests. This is usually set as the TCP port 443 for HTTP tunneling and TCP port

80. Clients can send messages to this port. Since clients initiate the connection to the server, you must make sure that clients can reach this port. This can be done by running the server outside a firewall, opening

this port on the firewall, etc.

sip_tls_port

Specifies the port where the SIP Server listens to TLS client requests. This is usually set as the default SIP TLS port 5061. If this is not set or is

set to 0, no TLS port will be opened for client requests. Clients can send messages to this port. Since clients initiate the connection to the server, you must make sure that clients can reach this port. This can be done by

running the server outside a firewall, opening this port on the firewall, etc. Once this parameter is given, the TLS subsystem must be configured using the other TLS related parameters in the configuration file. By

default, the TLS port is not set. Please refer to Section 8 TLS Configuration.

domain_name

This is the SIP domain used by SIP Server. If an incoming SIP message

is addressed to a different domain, the message is forwarded. If an incoming SIP message is addressed to this domain, it is processed. No default value provided. You must configure this parameter. For simplicity,

you may use the IP address of the server as the domain. This parameter takes a string value.

forward_udp_port This UDP port defaults to 7021. It is used to receive UDP packets

forwarded from other SIP servers within the distributed server.

forward_tcp_port This TCP port defaults to 7020. It is used to receive TCP packets forwarded from other SIP servers within the distributed server.

tcp_connections

This defines the maximum number of simultaneous TCP connections that the server will accept. This parameter can be used to limit the allowed number of incoming TCP connections. By default, the maximum number

of TCP connections is 90,000.

tls_connections

This defines the maximum number of simultaneous TLS connections that the server will accept. This parameter can be used to limit the allowed

number of incoming TLS connections. By default, the number of TLS connections is 90,000.

tcp_connection_timeout

This defines the duration (in seconds) for which TCP/TLS connections are

kept open without any messages being sent or received. By default, there is no connection timeout, i.e., TCP connections are kept open. Maximum value is 32,000 seconds.

tcp_sendbuffer_size Specify to change the TCP send buffer size. The default is 10,240 bytes (10 KB).

recvbuffer_size Specify to change the TCP receive buffer size. The default is 133,072

bytes (128 KB).

num_threads Specify the number of worker threads. The default is 16.


SIP Behavior

Parameter Description

max_sip_message_size

(No change required)

This defines the maximum size in bytes of SIP messages accepted by the

server. The server discards messages longer than this value. If this parameter is omitted, the default value is 65536.

register_contact


This option is only valid for UDP. If enabled, the SIP server will use the

address from the Contact header, otherwise source address information of the incoming UDP packet will be used. By default set to yes.

Valid values: Y, y, N, n

register_challenge


If this parameter is set to “yes”, server will challenge for authentication

(WWW Digest) when it receives a SIP REGISTER message. Setting this parameter to “no” allows any client/user to register to the server. The default

setting is yes.

proxy_challenge


If this parameter is set to “yes”, server will use proxy authentication

whenever applicable, such as when a SIP INVITE message is received. The

default setting is yes.

stat_reg_timeout


Users that have registered will be removed for statistical purposes after this

timeout. It defaults to 7200 seconds (two hours). Users that have been

registered for more than this time, but have neither re-registered nor logged out, will be expired and removed from the count of online users. Their registration will also be added to the SipLoginsHistory table.

stat_calls_timeout


Established calls will be removed for statistical purposes after this timeout. It

defaults to 1,209,600 seconds (two weeks). Calls that are started but not ended within this time will be added to the CallsHistory table.


Administration


admin_port


The server listens to this TCP port to receive telnet connections for administrative

commands using the command line interface. The connections to the administration port are protected by password. See in the succeeding sections for the complete list of

administrative commands.

Password File


password_file

This file contains the encrypted passwords and user names for various purposes, such as the password for the server’s command-line interface (user cli), the triple-DES encryption key (user 3des), the key for the TLS certificate key file (user tls), and the

database user and password.

Log Files



log_file


This is the SIP Server log file. It is set to /var/log/sipd.log by default. Depending

on the verbosity level specified by the –v command line argument, the server

writes many or few messages to the log file. Please ensure that the file can be written by the server process owner.

log_max_file_size


This is the maximum size of the SIP Server log file. It is automatically rotated

when the maximum size is reached. The default value is 10,000,000 bytes. Upon rotation, the old log file is renamed (a sequence number is appended to the file name) and stays in the same directory.

log_max_file_count


This is the maximum number of the SIP Server log files. The default value is

100. When the maximum is reached, new log files will be saved with numbers starting at 1.

pid_file


The SIP Server writes the process ID to this file. It is set to /var/run/sipd.pid by

default. Please ensure that the file can be written by the server process owner.

Database Connection


database_host

It is possible to define more than one host by providing additional database_host entries in the configuration file. The XMPP Server will randomly select one of them and switch in case of failures.

database_user

(Recommended to be changed)

A username used to connect to the database. This user should have INSERT,

DELETE, UPDATE and SELECT privileges. The password for the database user specified here is stored in an encrypted format in the password file (see

password_file). This is specified during Eyeball database installation.

log_database_host

(usually the same as database_host)

(see database_host above)

log_database_user (see database_user above)


logging_interval


This value specifies the database logging interval in minutes. The value defines

how frequently usage statistics of the SIP Server are written to the database

(see Section 12.2 Statistics). The default value, selected when the parameter is not specified, is 15 minutes.

TLS Certificate


tls_cert_file

(Must be changed)

Name of the file containing the certificate required for TLS. If sip_tls_port is

specified, this must be provided. Otherwise the server will not start. The server certificate is expected in PEM format. Any intermediate CA certificates that must

be installed in addition to the server certificate must be appended to the server certificate file.

tls_cert_keyfile

(Must be changed)

Name of the file containing the certificate key required for TLS. If sip_tls_port is

specified, this must be provided. Otherwise the server will not start.

tls_cert_user

(Must be changed)

Name of the user authorized to access the certificate key specified by

tls_cert_keyfile. The username is associated with the password required to access

the certificate key file. The password is stored in the password file using the ebpasswd utility as described in the INSTALL document.

Example

A sample configuration file for the sipd edge server is given below. # Configuration file used by Eyeball SIP Proxy Edge Server (sipd)

# This file provides startup/run parameters


# Copyright (c) 2006 Eyeball Networks Inc. All rights reserved. Patents pending.

# network configuration

bind_address = 32.40.50.60

private_address = 192.168.2.11

sip_port = 5060

sip_tcp_port = 443

sip_tcp_port = 80

sip_tls_port = 5061

domain_name = my.sip.domain.com

# administration

admin_port = 7010

password_file = /usr/local/eyeball/conf/eyeball.auth

# log files

log_file = /usr/local/eyeball/logs/sipd.log

pid_file = /usr/local/eyeball/logs/sipd.pid

# connection to database

database_host = eyeball

database_user = server

# SIP behaviour

register_challenge = yes

proxy_challenge = yes

# licensing

license_name = your-company

license_cert_file = /usr/local/eyeball/your-company.crtpvk.pem

eyeball_cert_file = /usr/local/eyeball/eyeball-root.crt.pem.tics

# tls certificate

tls_cert_file = /usr/local/eyeball/conf/tlscert.crt

tls_cert_keyfile = /usr/local/eyeball/conf/tlscert.key

tls_cert_user = tls


5.1.1. Eyeball SIP Server: Network Configuration

Network Configuration

Parameters Description

bind_address

Specify this numeric IP address to bind the service to a specific local interface or to any local interfaces. A system may have more than one network interface. Use ifconfig command to get a list of available

interfaces. Type “ any” if you wish to bind to all interfaces. If a specific interface is given, the server will allow connection only through that interface.

private_address

Specify this numeric IP address that will be used to communicate with the state server and other SIP Edge Proxy Servers. The administration port used to access the command line interface will also listen on this address.

If this field is not specified, it will default to the bind address.

public_address Specify this numeric IP address that will be put in Via headers in SIP messages. If this field is not specified, it will default to the bind address.

sip_port

Specifies the port where the SIP Server listens to UDP and TCP client requests. By default, the SIP port is set to 5060. Clients send messages to this port. Since clients initiate the connection to the server, you must

make sure that clients can reach this port. This can be done by running the server outside a firewall, opening this port on the firewall, etc.

sip_tcp_port

Specifies the port where the SIP Server listens to TCP client requests.

This is usually set as the TCP port 443 for HTTP tunneling and TCP port 80. Clients can send messages to this port. Since clients initiate the connection to the server, you must make sure that clients can reach this

port. This can be done by running the server outside a firewall, opening this port on the firewall, etc.


sip_tls_port

Specifies the port where the SIP Server listens to TLS client requests. This is usually set as the default SIP TLS port 5061. If this is not set or is

set to 0, no TLS port will be opened for client requests. Clients can send messages to this port. Since clients initiate the connection to the server, you must make sure that clients can reach this port. This can be done by

running the server outside a firewall, opening this port on the firewall, etc. Once this parameter is given, the TLS subsystem must be configured using the other TLS related parameters in the configuration file. By

default, the TLS port is not set. Please refer to Section 8 TLS Configuration.

domain_name

This is the SIP domain used by SIP Server. If an incoming SIP message

is addressed to a different domain, the message is forwarded. If an incoming SIP message is addressed to this domain, it is processed. No default value provided. You must configure this parameter. For simplicity,

you may use the IP address of the server as the domain. This parameter takes a string value.

forward_udp_port This UDP port defaults to 7021. It is used to receive UDP packets

forwarded from other SIP servers within the distributed server.

forward_tcp_port This TCP port defaults to 7020. It is used to receive TCP packets forwarded from other SIP servers within the distributed server.

tcp_connections

This defines the maximum number of simultaneous TCP connections that the server will accept. This parameter can be used to limit the allowed number of incoming TCP connections. By default, the maximum number

of TCP connections is 90,000.

tls_connections

This defines the maximum number of simultaneous TLS connections that the server will accept. This parameter can be used to limit the allowed

number of incoming TLS connections. By default, the number of TLS connections is 90,000.

tcp_connection_timeout

This defines the duration (in seconds) for which TCP/TLS connections are

kept open without any messages being sent or received. By default, there is no connection timeout, i.e., TCP connections are kept open.

tcp_sendbuffer_size Specify to change the TCP send buffer size. The default is 10,240 bytes

(10 KB).

recvbuffer_size Specify to change the TCP receive buffer size. The default is 133,072 bytes (128 KB).

num_threads Specify the number of worker threads. The default is 16.


5.1.2. Eyeball SIP Server: SIP Behavior

SIP Behavior


max_sip_message_size


This defines the maximum size in bytes of SIP messages accepted by the

server. The server discards messages longer than this value. If this

parameter is omitted, the default value is 65536.

register_challenge


If this parameter is set to “yes”, server will challenge for authentication

(WWW Digest) when it receives a SIP REGISTER message. Setting this

parameter to “no” allows any client/user to register to the server. The default setting is yes.

proxy_challenge


If this parameter is set to “yes”, server will use proxy authentication

whenever applicable, such as when a SIP INVITE message is received. The default setting is yes.

stat_reg_timeout


Users that have registered will be removed for statistical purposes after this

timeout. It defaults to 7200 seconds (two hours). Users that have been registered for more than this time, but have neither re-registered nor logged out, will be expired and removed from the count of online users. Their

registration will also be added to the SipLoginsHistory table.

stat_calls_timeout


Established calls will be removed for statistical purposes after this timeout. It

defaults to 1,209,600 seconds (two weeks). Calls that are started but not

ended within this time will be added to the CallsHistory table.


5.1.3. Eyeball SIP Server: Administration

Administration


admin_port


The server listens to this TCP port to receive telnet connections for administrative

commands using the command line interface. The connections to the administration port

are protected by password. See in the succeeding sections for the complete list of administrative commands.


5.1.4. Eyeball SIP Server: Password File

Password File


password_file

This file contains the encrypted passwords and user names for various purposes, such as the password for the server’s command-line interface (user cli), the triple-DES

encryption key (user 3des), the key for the TLS certificate key file (user tls), and the database user and password.


5.1.5. Eyeball SIP Server: Log Files

Log Files


log_file


This is the SIP Server log file. It is set to /var/log/sipd.log by default. Depending

on the verbosity level specified by the –v command line argument, the server

writes many or few messages to the log file. Please ensure that the file can be written by the server process owner.

log_max_file_size


This is the maximum size of the SIP Server log file. It is automatically rotated

when the maximum size is reached. The default value is 10,000,000 bytes. Upon rotation, the old log file is renamed (a sequence number is appended to the file name) and stays in the same directory.

log_max_file_count


This is the maximum number of the SIP Server log files. The default value is

100. When the maximum is reached, new log files will be saved with numbers starting at 1.

pid_file


The SIP Server writes the process ID to this file. It is set to /var/run/sipd.pid by

default. Please ensure that the file can be written by the server process owner.


5.1.6. Eyeball SIP Server: Database Connection

Database Connection


database_host

It is possible to define more than one host by providing additional database_host entries in the configuration file. The XMPP Server will randomly select one of them and switch in case of failures.

database_user

(Recommended to be changed)

A username used to connect to the database. This user should have INSERT,

DELETE, UPDATE and SELECT privileges. The password for the database user specified here is stored in an encrypted format in the password file (see

password_file). This is specified during Eyeball database installation.

log_database_host

(usually the same as database_host)

(see database_host above)

log_database_user (see database_user above)

logging_interval


This value specifies the database logging interval in minutes. The value defines

how frequently usage statistics of the SIP Server are written to the database (see Section 12.2 Statistics). The default value, selected when the parameter is

not specified, is 15 minutes.


5.1.7. Eyeball SIP Server: Licensing

Licensing


license_name

(Must be changed)

Name of your license that is provided by Eyeball Networks Inc. Your organization

must have a valid production license in order to run Eyeball Server components.

The license name is delivered through the Eyeball Software download page.

license_cert_file

(Must be changed)

Name of the file containing your certificate and the private key of your

organization. This file is provided by Eyeball Networks Inc. through the Eyeball

Software Download page. This file must be kept secret.

eyeball_cert_file


Name of the file containing the certificate of Eyeball Networks Inc. This file is

provided to you by Eyeball Networks Inc. through the Eyeball Software

Download page.


5.1.8. Eyeball SIP Server: TLS Certificate

TLS Certificate


tls_cert_file

(Must be changed)

Name of the file containing the certificate required for TLS. If sip_tls_port is

specified, this must be provided. Otherwise the server will not start. The server

certificate is expected in PEM format. Any intermediate CA certificates that must be installed in addition to the server certificate must be appended to the server certificate file.

tls_cert_keyfile

(Must be changed)

Name of the file containing the certificate key required for TLS. If sip_tls_port is

specified, this must be provided. Otherwise the server will not start.

tls_cert_user

(Must be changed)

Name of the user authorized to access the certificate key specified by

tls_cert_keyfile. The username is associated with the password required to access the certificate key file. The password is stored in the password file using the ebpasswd utility as described in the INSTALL document.


5.1.9. Eyeball SIP Server: Example

Example

A sample configuration file for the sipd edge server is given below. # Configuration file used by Eyeball SIP Proxy Edge Server (sipd)

# This file provides startup/run parameters

# Copyright (c) 2006 Eyeball Networks Inc. All rights reserved. Patents pending.

# network configuration

bind_address = 32.40.50.60

private_address = 192.168.2.11

sip_port = 5060

sip_tcp_port = 443

sip_tcp_port = 80

sip_tls_port = 5061

domain_name = my.sip.domain.com

# administration

admin_port = 7010

password_file = /usr/local/eyeball/conf/eyeball.auth

# log files

log_file = /usr/local/eyeball/logs/sipd.log

pid_file = /usr/local/eyeball/logs/sipd.pid

# connection to database

database_host = eyeball

database_user = server

# SIP behaviour

register_challenge = yes

proxy_challenge = yes

# licensing

license_name = your-company

license_cert_file = /usr/local/eyeball/your-company.crtpvk.pem

eyeball_cert_file = /usr/local/eyeball/eyeball-root.crt.pem.tics

# tls certificate

tls_cert_file = /usr/local/eyeball/conf/tlscert.crt

tls_cert_keyfile = /usr/local/eyeball/conf/tlscert.key

tls_cert_user = tls


5.2. Eyeball SIP Server: stated.conf

stated.conf

Below, we give detailed descriptions of the configuration parameters for the stated server component. These parameters must be added to the state server’s configuration file.


bind_address Specify this numeric IP address that will be used to communicate with the edge server.

database_host

(Must be changed)

See database_host for sipd.conf.

database_user

(Must be changed)

See database_user for sipd.conf.

password_file

(Must be changed)

See password_file for sipd.conf.

pid_file


The SIP State Server writes the process ID to this file. It is set to /var/run/stated.pid by default.

Please ensure that the file can be written by the server process owner.


5.3. Eyeball SIP Server: Scalability

Scalability

See the following sections for more information on Scalability:

5.3.1. Eyeball SIP Server: Introduction

5.3.2. Eyeball SIP Server: Adding a SIP Edge Server

5.3.3. Eyeball SIP Server: Removing a SIP Edge Server

5.3.4. Eyeball SIP Server: Adding a SIP State Server

5.3.5. Eyeball SIP Server: Removing a SIP State Server


5.3.1. Eyeball SIP Server: Introduction

Introduction

In order to add a new edge server to a cluster of servers (see Figure 1 in Section 2 Overview), the only requirement is to setup a new sipd process on a new computer and configure it to connect to the main database using the database_host parameter in the new edge server’s configuration file. The new server

will automatically be discovered and integrated in the server cluster. The server administrators have to make sure that client’s requests are directed to the new edge server, for example, by adjusting the DNS settings accordingly.

The same procedure applies when adding a new state server with the exception that no additional setting

changes are required. New state servers are automatically integrated into the server cluster upon successful startup and the load is equally balanced among all available state servers.


5.3.2. Eyeball SIP Server: Adding a SIP Edge Server

Adding a SIP Edge Server

To add a SIP Edge Server, first start the server by issuing ONE of the following commands: $ /etc/init.d/sipd start

$ ./bin/sipd -c etc/sipd.conf

Confirm that the server is up and running by checking the log file.

The SIP Edge Server should write an entry into the SipEdgeServerHistory database table. The other SIP Edge Servers and SIP State Servers are unaware of the presence of the new SIP Edge Server, except after a user logs in. A record of the user will be updated in the SipLoginState database table that indicates

that the user is connected to the new SIP Edge Server. When there are calls directed to this user, SIP messages will be forwarded to the new SIP Edge Server.

While the SIP Edge Servers do not maintain a list of other SIP Edge Servers, the server load is distributed using DNS load balancing, where different SIP clients connect to different SIP Edge Servers.

In this case, DNS SRV entries need to be added to DNS tables. Please refer to the DNS SRV entries in the example below:

SRV _sip._udp.mydomain.com

_sip._udp.mydomain.com has SRV record 0 100 5060 sip1.mydomain.com.



In addition, entries in the firewall may be required to allow incoming UDP and/or TCP packets to reach the new SIP Edge Server.


5.3.3. Eyeball SIP Server: Removing a SIP Edge Server

Removing a SIP Edge Server

To remove a SIP Edge Server, enter ONE of the following commands:

$ /etc/init.d/sipd stop

$ kill `cat sipd.pid`

When a SIP Edge Server is properly shutdown, all TCP connections to that SIP Edge Server will be closed, users will be logged out, and active calls will added to the CallsHistory database table, but no

BYE messages will be generated. Please wait for a few seconds if the SIP Edge Server does not completely shutdown immediately, as it may be busy closing connections and logging users out.

SIP clients attempting to connect to the removed SIP Edge Server should fall back to one of the other SIP Edge Servers, which are discovered using a DNS SRV lookup.


5.3.4. Eyeball SIP Server: Adding a SIP State Server

Adding a SIP State Server

SIP State Servers are typically behind a firewall and invisible to the outside world. Private IP addresses

are typically used. The network configuration must allow UDP traffic between SIP State Servers and SIP Edge Servers.

To add a SIP State Server, first start the server by issuing ONE of the following commands:

$ /etc/init.d/stated start

$ ./bin/stated -c etc/stated.conf -s SIP

Confirm that the server is up and running by checking process list.

$ ps ax

The SIP State Server will register itself in the StateServerRegistry database table. The SIP Edge Server will periodically check the entries in this table and send queries to the new SIP State Server.


5.3.5. Eyeball SIP Server: Removing a SIP State Server

Removing a SIP State Server

To remove a SIP State Server, issue the ONE of the following commands:

$ /etc/init.d/stated stop

$ kill `cat stated.pid`

The SIP State Server will continue running for 10 to 20 seconds, to allow time for the SIP Edge Servers to

update their internal lists of SIP State Servers and stopping making queries to the SIP State Server that is shutting down.

If the SIP State Server is terminated improperly, the SIP Edge Servers may experience timeouts

connecting to the SIP State Server. This error condition should only last for at most 20 seconds, after which the SIP Proxy will resume normal operation.


6. Eyeball SIP Server: Password Settings

Password Settings

See the following sections for more information:

6.1. Eyeball SIP Server: Password File

6.2. Eyeball SIP Server: User Accounts: pass3des


6.1. Eyeball SIP Server: Password File

Password File

The edge server component of the Eyeball SIP Server uses a password file (usually named eyeball.auth) to store various passwords and keys in encrypted format, e.g., the password for the command line interface and the key for securing user passwords. The tool ebpasswd found in the Eyeball SIP Server

installation package is used to encrypt the contents of the password file. The password file is generated during the installation (see Section 4 Installation). It contains entries of the

form:

<entry>: <encrypted string>,

where <entry> denotes the purpose of the entry (e.g., 3des denotes the key used to encrypt user

passwords) and the encrypted string represents the actual password or key. The cleartext of the encrypted strings is not stored anywhere.

The following encrypted passwords and keys are by default found in the password file:

database password (defined during the installation)

command line interface password (default entry: cli)

key to encrypt the user passwords (default entry: 3des)

TLS key passphrase if TLS was configured (defined during the installation)

In order to change the value of an entry, i.e., a password or key, the ebpasswd tool can be used. The password for the command line interface can be changed directly from the CLI itself. It is recommended to change the key used to encrypt the user passwords (entry 3des) only if it was compromised. Otherwise

the whole set of user passwords must be re-encrypted.


6.2. Eyeball SIP Server: User Accounts: pass3des

pass3des

The tool pass3des, found in the Eyeball SIP Server installation package, is used to encrypt and decrypt

user’s passwords in the database and used for provisioning (see Section 12.1 Provisioning) or password changes.

pass3des implements 3DES symmetric encryption. The key used to encrypt user passwords is kept in the password file stored in the entry 3des (see Section 6.1 Password File). The Eyeball SIP Server uses this

key to access the user passwords stored in the database. In case this key needs to be changed, e.g., in case it was compromised, it is necessary to decrypt the user passwords with the old key and re-encrypt the passwords with a new key.


7. Eyeball SIP Server: Command Line Arguments

Command Line Arguments

7.1. Eyeball SIP Server: sipd

7.2. Eyeball SIP Server: stated


7.1. Eyeball SIP Server: sipd

sipd

The sipd executable supports the following command line arguments.

Command Line Argument

Description

-c, --config

<filename>

Specifies the configuration file. The configuration file is necessary to run the Eyeball

SIP Server.

-v, --

verbose

<level>

Set verbosity level of SIP Server for logging, the allowed range of values is from 0 to 5. Higher verbosity level means more verbose mode. With verbose level 0, only critical

issues are printed which do not allow the server to continue. With verbose level 5, every SIP message is written to the log file. The default and recommended value is 4 (log summaries of SIP messages).

Please note that higher verbosity levels may result in excessive logging, easily

exceeding several Mbytes/day. As more experience is gained during operation, the verbosity level can be reduced through the administration port (described below).

-f, --

foreground

By default, the SIP Server runs as a background daemon. Using this option will run the

server in foreground. The server output will be written to standard output.

-V, --

version Prints the SIP Server version information and exits.

-h, --help Prints help information and exits.


7.2. Eyeball SIP Server: stated

stated

The stated executable supports the following command line arguments.

Command Line Argument Description

-c, --config

<filename>

Specifies the configuration file. The configuration file is necessary to run the stated server component.

-v, --verbose

<level> Sets the verbosity level. It can be either 0 (do not log) or 1 (log).

-h, --help Prints help information and exits.

-a, --address

<address> Server IP address

-p, --port <port> Server port for first instance

-n, --number-

instances <num> Number of stated processes on the machine.

-s, --server <type> Specify SIP, XMPP, or ALL (default). Specifies that the state server will service either SIP, XMPP, or all edge servers.


8. Eyeball SIP Server: TLS Configuration

TLS Configuration

The Eyeball SIP Server needs to be configured in order to allow outgoing and incoming connections using TLS. To enable TLS connections to and from the SIP Server, the parameter sip_tls_port must be set in the configuration file (see Section 5 Server Configuration) and a TLS certificate must be generated

and installed as described in this section. The server administrator must generate the TLS certificate and the TLS certificate key. Several options are available for generating the certificate. In this section, the procedure using the publicly available openssl toolkit is briefly outlined. Please refer to the openssl

website ( http://www.openssl.org) for further reference.

First, a keyfile must be generated. This keyfile is used to protect the certificate and must be specified in the configuration file (parameter tls_cert_keyfile, see Section 5 Server Configuration). Here is an example of how this can be done using openssl. /> openssl genrsa -des3 -out privkey.pem 2048

The program will ask for a password to protect the keyfile and generate the keyfile privkey.pem, which will

be password protected. The password must be added to the eyeball password file using the password utility ebpasswd. It is possible (but NOT recommended) to omit the password protection. The keyfile must be protected from unauthorized access as it protects the actual certificate and prevents others from using

the certificate.

After generating the keyfile, an actual certificate request can be generated. This means, a file is

generated that must be sent to a certificate authority (CA). Then the CA will issue a valid certificate for your server. The certificate request file is generated as follows:

/> openssl req -new -key privkey.pem -out cert.csr

http://www.openssl.org/


The resulting file cert.csr must be sent to the CA. The CA will then issue a valid certificate for your server, which must be placed in the appropriate directory and added to the configuration file using the parameter

tls_cert_file (see Section 5 Server Configuration).

Another option is to generate a self-signed certificate. This is NOT recommended because it provides no way for clients to actually verify the integrity and validity of the certificate with any trusted third-party. This should only be used for testing purposes. /> openssl req -new -x509 -key privkey.pem -out cert.pem -days 365

The resulting file cert.pem can be used as server certificate and must be added to an appropriate

directory and specified in the configuration file using the parameter tls_cert_file (see Section 5.1.1 Network Configuration). The certificate file is expected in PEM format. openssl can be used to convert certificates from other formats to PEM.

In some cases, it is necessary to install one or more intermediate CA certificates in addition to the actual

server certificate. These certificates should be appended to the server certificate file given in tls_cert_file.


9. Eyeball SIP Server: Peering with Other SIP Domains / SIP Proxies

Peering with Other SIP Domains / SIP Proxies

The Eyeball SIP Server supports peering with other SIP domains. Two files are used to restrict accepting

SIP INVITE messages from other domains/computers or forwarding SIP INVITE messages to other domains/computers. These two files are domain.allow and domain.deny, found in the configuration subdirectory. The Eyeball SIP Server uses a mechanism similar to the one employed on UNIX systems

(which uses host.allow and host.deny files).

domain.allow and domain.deny contain IP addresses or domain names. Each line in the file is an entry. Each entry is a rule that consists of two fields. The first field is a FROM or a TO. A FROM rule regulates where messages are accepted from, while a TO rule regulates where messages are forwarded. The

second field is an IP address, a sub-network, a hostname or a SIP domain name.

Rules in domain.allow specify other domains where SIP INVITE messages will be accepted from or forwarded to. Rules in domain.deny specify other domains where SIP INVITE messages will not be accepted from or forwarded to. The keyword ALL matches any possible IP address, hostname or domain

name, and can be used as a wildcard.

Example (domain.allow):

FROM 123.123.123.123

FROM 64.85.36.162

TO ALL


In the previous example, SIP messages are accepted when they were sent from the IP addresses 123.123.123.123 and 64.85.36.162. These messages are interpreted as messages from other SIP

domains and are not challenged. That means, any message received from those IP addresses will always be forwarded. The username and the proxy_challenge parameter in the configuration file (see Section 5 Server Configuration) will be ignored. In the above example, messages are forwarded to any other SIP

domain, IP address or hostname (indicated by the entry TO ALL).


9.1. Eyeball SIP Server: Forwarding Messages to Other SIP Proxies (TO rules)

Forwarding Messages to Other SIP Proxies (TO rules)

The basic access control mechanism for forwarding works as follows. First, the SIP message is parsed to obtain a target domain. Then domain.allow is searched for an entry matching the target domain. The

domain.deny is checked for an entry matching the target domain. The entries are checked one-by-one, starting from the beginning of the file. The check terminates when the first match is found. If a match is found in domain.allow, the message will be forwarded, and domain.allow is not checked. When the target

of a message is an IP address or hostname, the same mechanism applies. If no match is found, the proxy assumes the message should be forwarded.

Restricting the destination for a message is useful, for example, to restrict access to a PSTN gateway server.


9.2. Eyeball SIP Server: Accepting Messages from Other SIP Proxies (FROM rules)

Accepting Messages from Other SIP Proxies (FROM rules)

The access control mechanism employed when deciding whether or not to forward a message is applied to each incoming SIP INVITE message. It determines whether the message is authenticated, and then

whether to forward the message or not. The mechanism must be applied and configured carefully.

To determine whether a message is from a trusted source, the access control mechanism checks domain.allow and then domain.deny in the way described in previous subsection. If no match is found, the proxy assumes the message is from a trusted source.

The SIP proxy resolves SIP domains and hostnames as part of the startup phase. Each entry in the two

files, domain.allow and domain.deny, is checked to determine whether it represents an IP address, hostname, or SIP domain. This process works as follows:

When the entry represents an IP address, this IP address is added to the internal access control structures.

When the entry does not represent an IP address, the SIP proxy checks whether the entry represents a SIP domain. DNS SRV lookups are carried out for each of the protocols UDP, TCP, and TLS. When successful, the respective IP addresses are added to the internal access control structures.

When the entry does not represent an IP address and the DNS SRV lookup is unsuccessful, the SIP proxy tries to interpret the entry as a hostname. If the entry can be resolved to a valid IP address, this IP address is added to the internal access control structures.


9.2.1. Eyeball SIP Server: Examples

Examples

Defaults

By default, the Eyeball SIP Proxy does not accept messages from other SIP domains, but allows forwarding to any other SIP domain.

domain.allow:

TO ALL

domain.deny:

FROM ALL

Default-deny Strategy

The following example shows how to implement a default-deny strategy, denying access from and to any IP and SIP domain except for those specified in domain.deny.

In this example, messages to and from the SIP domain eyeball.com are accepted.

domain.allow:

TO eyeball.com

FROM eyeball.com


domain.deny:

FROM ALL

TO ALL

The domain eyeball.com is resolved during proxy startup, resulting in one or more IP addresses being added to the internal access control structures.

Default-allow Strategy

The following setting results in a default-allow strategy, i.e., messages are accepted and forwarded by default, with only the exceptions defined in domain.deny.

Specifying FROM ALL and/or TO ALL in domain.allow would lead to acceptance and forwarding of all messages as the search stops when the first match is found. Thus, the exceptions specified in

domain.deny would be ignored.

domain.allow:

domain.deny:

TO xyz.com

FROM 192.168.0.100

FROM 123.123.123.123

It is very important to carefully design the FROM rules. In the case of the default-allow strategy, it cannot be verified whether or not incoming SIP INVITE messages were really sent from the domain specified in

the message.


10. Eyeball SIP Server: Starting and Stopping the Server

Starting and Stopping the Server

In order to run the Eyeball SIP Server, both edge and state server components must be started. If you are using the init.d scripts provided in the installation package the server may be started with

/etc/init.d/stated start

/etc/init.d/sipd start

When SIP Server runs as daemon, the output is redirected to the file specified in the configuration. Otherwise, the standard output is used.

To ensure that the server is running, please connect to the administration port running the command telnet localhost 7010 (port 7010 is used for the command line interface in the default configuration). You

can also check that the process is running by using the ps –ef command.

In the event of an unsuccessful startup, the SIP Server exits with an error code for one of the following reasons:

Cannot read the configuration file. The configuration file is not specified or the specified file cannot be read.

Error during initialization. The Eyeball SIP Server gives a detailed error message on the console

or in the output file indicating the cause of the failure. The most common reasons include failure to obtain a license from Eyeball Monitoring Server, server ports are already in use, cannot read the database authentication file, or failure to connect to the database.

The servers may be stopped with:

/etc/init.d/stated stop

/etc/init.d/sipd stop

Unless specified by -f option to run in foreground, the Eyeball SIP Server runs as daemon in the background.


11. Eyeball SIP Server: Command Line Interface

Command Line Interface

The Eyeball SIP Server can be monitored and administered using the command line interface available

via a telnet connection to the administration port of the server.

Connection to the administration port is password protected. The initial default password is ‘eyeball’.

Changing this password is HIGHLY RECOMMENDED upon first login. The password is encrypted using the password utility ebpasswd and stored as user cli in the file specified by password_file in the sipd.conf. Several simultaneous connections to the administration port are possible.

Connection to the administration port can be established using the telnet command. The administration

port is specified in the server configuration file.

The SIP Server supports the following administrative commands.

Administrative Command

Description

help Print the list of available commands and a brief explanation of each command.

verbose

<level>

Change the verbosity level of SIP Server to <level>. For the description of verbosity levels, please refer to Section 13 Log Files.


rotate log

This command manually rotates the log file. The current log file is closed and a new log file is opened. The old log file is renamed (a sequence number is appended to

the file name) and stays in the same directory.

bye, quit,

exit, ^D Close the connection to administration port.

status Print the connection status of the SIP Server.

connections Print the currently active TCP and TLS connections.

users Display the number of online users and total users.

print users Display the online users, IP addresses, and ports.

messages Display the number of processed SIP messages and the messages per second processed during the last half a minute.

stun Display the number of processed STUN messages.

settings Display the current settings of the server.

shutdown Shut down the server.

version Print the server version.

uptime Print the server running time.


12. Eyeball SIP Server: Database

Database

This section describes how the Eyeball SIP Server uses the database and how to setup new accounts. The database tables can be created using the database script included in the Eyeball SIP Server package.

If you are running multiple Eyeball servers, it is recommended to use the same database for all servers to simplify the provisioning process.

Administrators only need to access the tables required for provisioning and statistics. All other tables are required for internal purposes only and should not be touched or changed.

Adding, removing or modifying information in database tables must be made with great care as it may

interfere with the proper operation of the server.


12.1. Eyeball SIP Server: Provisioning

Provisioning

Adding and removing user accounts requires accessing the account table in the database. The table has the following columns:

Column Type

account_id unsigned auto_increment

user_id varchar(32)

password varchar(32)

active varchar(1)

created datetime

In order to add a new user, the user’s ID (the name of the user, e.g., ‘eyeball’) and the password must be added to the account table. The server expects the password in encrypted format. The pass3des tool found in the archive in the tools subdirectory is used to encrypt the password. This tool implements a

3DES encryption of the password. The key is stored in the file eyeball.auth, the respective username is 3des.

The column active is used to define whether the user’s account is active (‘Y’) or not (‘N’). This can be

used e.g. to temporarily deactivate a user without deleting the account so it can be activated later. In

addition, the account table contains a timestamp of the time when the user account was created. This is automatically filled with the current timestamp when a new user is added (see Section 12.3 Database Tables).

The Eyeball SIP Server installation package also contains a sample script that can be used for provisioning.


12.2. Eyeball SIP Server: Statistics

Statistics

The Eyeball SIP Server periodically logs statistics and usage information to the database. In addition, each user’s activity, e.g., logins, is written to the database when such events occur. The information can be extracted from the table sipstatistics which is described in Section 12.3 Database Tables. This table

captures status and usage information of the SIP Server, which is periodically logged. The logging interval can be adjusted using the logging_interval parameter in the configuration file (see Section 5.1.1 Network Configuration). The information logged to this table covers the logging period. In order to obtain

information about a longer period of time, it is necessary to add the information from all logging intervals covering the request period. For that purpose, each row in the table indicates the date and time it was taken.

When used together with Eyeball clients, the Eyeball SIP Server also logs information about the call

completion rate. For each call, the SIP Server captures whether the call was completed Peer2Peer or using a relay server. If a relay server was used, the actual relay method (UDP, TCP, or TCP using HTTP tunnel) is given. Please refer to the table description in Section 12.3 Database Tables for more details.

In addition, each login (via SIP REGISTER) to the SIP Server and each call is logged to the database.

For that purpose, the database tables siploginhistory and sipcallhistory are used. The format of those two tables is described in Section 12.3 Database Tables.


12.3. Eyeball SIP Server: Database Tables

Database Tables

This section describes and summarizes all the database tables used by the Eyeball SIP Server. These

tables can be created by the installation script included in the server’s installation package. The access mode of each table is also specified. The fields mentioned are required for the proper operation of the server. Other tables and fields can be added on demand. The following database tables may optionally

be placed in a separate database for logging purposes: sipcallhistory; siploginhistory; sipserverhistory; and sipstatistics.

Accounts

Used to verify whether an account exists and still active ( Active = ’Y’). This is also used to verify the

password for the account. Password contains users’ passwords as a 3DES -encrypted password generated using the pass3des utility. The active column specifies whether the user account is active (Yes or No), or whether it is Abused (A). An abused account means that the user account has been abused

and is disabled, resulting in a failed login for the user. (SELECT)

CREATE TABLE àccount` (

àccount_id` int(10) unsigned NOT NULL auto_increment,

ùser_id` varchar(32) NOT NULL default ' ',

`password` varchar(32) NOT NULL default ' ',

àctive` varchar(1) NOT NULL default 'Y',

`created` datetime NOT NULL default '1970-01-01 00:00:00',

PRIMARY KEY (àccount_id`),

UNIQUE KEY àccount_user_index_idx` (ùser_id`)

)

Column Type Description

account_id integer(10) A unique identifier for the user account.


user_id varchar(32) The user ID associated with this account.

password varchar(32) The password used to access the account (this is encrypted when stored).

active varchar(1) Indicates whether the account is active (Y), not inactive (N), or abused (A).

created datetime The date/time the account was created.

accountdetail

This table holds detailed user account information. Other fields in this table (personal information, billing

information, etc.) can be added as necessary. (SELECT)

CREATE TABLE àccountdetail` (

àccount_id` int(10) unsigned NOT NULL default '0',

èmail` varchar(100) NOT NULL default ' ',

`firstname` varchar(40) NOT NULL default ' ',

`lastname` varchar(40) NOT NULL default ' ',

`birthday` date NOT NULL default '1970-01-01',

`gender` varchar(1) NOT NULL default 'M',

àddress` varchar(255) NOT NULL default ' ',

`city` varchar(40) NOT NULL default ' ',

`stateprovince` int(10) unsigned NOT NULL default '0',

`country` int(10) unsigned NOT NULL default '0',

`subscriptiontype` int(10) unsigned NOT NULL default '55288',

`recordtime` datetime default '1970-01-01 00:00:00',

PRIMARY KEY (àccount_id`)

)


account_id integer(10) A unique identifier for the user account.

email varchar(100) The email address associated with this account.

firstname varchar(40) The first name of the user associated with this account.

lastname varchar(40) The last name of the user associated with this account.

birthday date The birthday of the user associated with this account.

gender varchar(1) The gender of the user associated with this account.

address varchar(255) The address of the user associated with this account.

city varchar(40) The city portion of the address of the user associated with this account.

stateprovince integer(10) The state or province of the user associated with this account.

country integer(10) The country of the user associated with this account.

subscriptiontype integer(10) The type of subscription associated with this account.

recordtime datetime ??

sipcall


Users that are currently in an audio/video call. A record is inserted when a call is accepted by the other party. A record is deleted when the call is ended by either party. (INSERT, DELETE)

CREATE TABLE `sipcall` (

`callid` varchar(100) NOT NULL default ' ',

`caller` varchar(100) NOT NULL default ' ',

`callee` varchar(100) NOT NULL default ' ',

`starttime` datetime NOT NULL default '1970-01-01 00:00:00',

PRIMARY KEY (`callid`),

KEY `sipcall_caller_index_idx` (`caller`),

KEY `sipcall_callee_index_idx` (`callee`)

)


callid varchar(100) ??

caller varchar(100) ??

callee varchar(100) ??

starttime datetime The time the call started.

sipcallhistory

Records ended calls. A record is inserted when a call is ended by either party. (INSERT)

CREATE TABLE `sipcallhistory` (

`callid` varchar(100) NOT NULL default ' ',

`caller` varchar(100) NOT NULL default ' ',

`callee` varchar(100) NOT NULL default ' ',

`starttime` datetime NOT NULL default '1970-01-01 00:00:00',

`endtime` datetime default '1970-01-01 00:00:00',

PRIMARY KEY (`callid`),

KEY `sipcallhistory_index2_idx` (`caller`),

KEY `sipcallhistory_index3_idx` (`callee`)

)


callid varchar(100) ??

caller varchar(100) ??

callee varchar(100) ??

starttime datetime The time the call started.

endtime datetime The time the call ended.

serverconfig


Stores internal State Server information (UPDATE, SELECT)

CREATE TABLE `serverconfig` (

`name` varchar(32) NOT NULL default ' ',

`value` varchar(255) NOT NULL default ' ',

`recordtime` int(11) default NULL,

PRIMARY KEY (`name`)

)


name varchar(32) The name of the server.

value varchar(255) ??

recordtime integer(11) ??

siploginstate

Users that have registered to the SIP Server. A record is inserted when a user registers to the SIP Server. A record is updated when a user un-registers from SIP Server or registration expires. (INSERT, UPDATE)

CREATE TABLE `siploginstate` (

`siploginstate_id` int(10) unsigned NOT NULL auto_increment,


`proxyaddress` varchar(32) NOT NULL default ' ',

`contact` varchar(32) NOT NULL default ' ',

`login` datetime NOT NULL default '1970-01-01 00:00:00',

`expires` int(10) unsigned NOT NULL default '0',

`forwardaddress` varchar(32) NOT NULL default ' ',

`hash` int(10) unsigned NOT NULL default '0',

PRIMARY KEY (`siploginstate_id`),

KEY `siploginstate_index2_idx` (`hash`)

)


siploginstate_id integer(10) ??

account_id integer(10) The ID of the registered user.

proxyaddress varchar(32) The proxy address of the user.

contact varchar(32) ??

login datetime The date and time the user registered with the proxy server.

expires integer(10) ??

forwardaddress varchar(32) ??

hash integer(10) ??


siploginhistory

Users that un-registered from SIP Server. A record is inserted when a user un-registers or registration

expires. The reason for the logout is given as well: ‘N’ for normal deregistration, ‘E’ for expiry of the registration. The Contact column stores the source address the client used to login as a string in the format “<IP>:<port>/<protocol>”. (INSERT)

CREATE TABLE `siploginhistory` (

`siploginhistory_id` int(10) unsigned NOT NULL auto_increment,



`contact` varchar(100) NOT NULL default ' ',

`login` datetime NOT NULL default '1970-01-01 00:00:00',

`logout` datetime NOT NULL default '1970-01-01 00:00:00',

`reason` varchar(1) NOT NULL default 'N',

PRIMARY KEY (`siploginhistory_id`),

KEY `siploginhistory_acnt_index_idx` (`account_id`,`login`),

KEY `siploginhistory_log_index_idx` (`login`,`account_id`)

)


siploginhistory_id integer(10) A unique identifier for the table record.

account_id integer(10) The ID of the de-registered user.

proxyaddress varchar(32) The proxy address of the user.

contact varchar(100) The source address the user used to login. The format is <IP>:<port>/<protocol>.

login datetime The date and time the user registered with the proxy server.

logout datetime The date and time the user de-registered (or registration expired) with the proxy server.

reason varchar(1) The reason for the de-registration: ‘N’ for normal de-registration,

‘E’ for expiry of the registration.

sipstatistics

This table stores periodic usage statistics for the SIP Server (INSERT).

In addition to various parameters directly related to the SIP Server’s operation, the table also reveals

information about the call completion status. This information can only be collected if at least one Eyeball client was used in the call. The following columns cover the call completion status:

Status Description

callsudprelay Calls completed using UDP relay


callstcprelay Calls completed using TCP relay

callshttprelay Calls completed using TCP relay tunneled through HTTP

callsp2p Calls completed Peer2Peer

callsunknown Call completion could not be detected. This happens when all parties involved are non-Eyeball clients.

callsrelayerror An error occurred before the call could be completed. This usually indicates a network problem at the client.

CREATE TABLE `sipstatistics` (

`sipstatistics_id` int(10) unsigned NOT NULL auto_increment,

`sipserver_id` int(10) unsigned NOT NULL default '0',

`recordtime` datetime NOT NULL default '1970-01-01 00:00:00',


`connections` int(10) unsigned NOT NULL default '0',

ònlinecurrent` int(10) unsigned NOT NULL default '0',

ònlinemax` int(10) unsigned NOT NULL default '0',

`calls` int(10) unsigned NOT NULL default '0',

`callminutes` int(10) unsigned NOT NULL default '0',

`throughput` int(10) unsigned NOT NULL default '0',

`login` int(10) unsigned NOT NULL default '0',

`logout` int(10) unsigned NOT NULL default '0',

`callsinitiated` int(10) unsigned NOT NULL default '0',

`callsended` int(10) unsigned NOT NULL default '0',

`stun` int(10) unsigned NOT NULL default '0',

`callsp2p` int(10) unsigned NOT NULL default '0',

`callsudprelay` int(10) unsigned NOT NULL default '0',

`callstcprelay` int(10) unsigned NOT NULL default '0',

`callshttprelay` int(10) unsigned NOT NULL default '0',

`callsrelayerror` int(10) unsigned NOT NULL default '0',

`callsunknown` int(10) unsigned NOT NULL default '0',

àvgbps` int(10) unsigned default '0',

`peakbps` int(10) unsigned default '0',

PRIMARY KEY (`sipstatistics_id`)

)


sipstatistics_id integer(10) A unique identifier for the usage statistics record.

sipserver_id integer(10) The ID of the SIP server.

recordtime datetime ??

proxyaddress varchar(32) The proxy address of the server.

connections integer(10) The number of connections on the SIP server.

onlinecurrent integer(10) The number of current online connections.

onlinemax integer(10) The maximum number of online connections.

calls integer(10) The number of calls logged.

callminutes integer(10) The number of minutes in the calls logged.

throughput integer(10) ??

login integer(10) ??

logout integer(10) ??

callsinitiated integer(10) The number of calls initiated.

callsended integer(10) The number of calls ended.

stun integer(10) The number of calls that involved a STUN server.


callsp2p integer(10) The number of calls that involved P2P.

callsudprelay integer(10) The number of calls that involved UDP relay.

callstcprelay integer(10) The number of calls that involved TCP relay.

callshttprelay integer(10) The number of calls that involved HTTP relay.

callsrelayerror integer(10) The number of calls that had a relay error.

callsunknown integer(10) The number of calls that involved an unknown server.

avgbps integer(10) The average number of bits per second.

peakbps integer(10) The peak number of bits per second.

stateserverregistry

State Servers register here periodically to indicate that they are active (UPDATE, SELECT)

CREATE TABLE `stateserverregistry` (

àddress` varchar(32) NOT NULL default ' ',

`status` varchar(21) NOT NULL default ' ',

`recordtime` int(11) default NULL,

ùsercount` int(10) unsigned NOT NULL default '0',

`processid` int(10) unsigned NOT NULL default '0',

`messagecount` int(10) unsigned NOT NULL default '0',

`responsetime` int(10) unsigned NOT NULL default '0',

`servertype` varchar(4) NOT NULL default 'ALL',

PRIMARY KEY (àddress`)

)


address varchar(32) The address of the State Server

status varchar(21) The status of the State Server

recordtime integer(11) ??

usercount integer(10) ??

processid integer(10) ??

messagecount integer(10) ??

responsetime integer(10) ??

servertype varchar(4) The type of State Server


13. Eyeball SIP Server: Log Files

Log Files

The SIP Edge Proxy Server writes messages to the log file. By default, the log file is written to /var/log/sipd.log. Writing to /var/log/sipd.log may require root access. Make sure that sipd is run with the proper user

privileges to write to the log file. The location of the log file can also be specified in the sipd.conf configuration file with the log_file parameter.

Depending on the verbosity level 0 to 5, the log file may grow slowly or quickly in size. At verbosity level 0, only important messages or critical errors are logged. At verbosity level 5, all SIP messages are logged. The recommended verbosity level is 4, where summary information about each SIP message is

logged. The verbosity level is set to 4 by default, and can be changed using the –v command line argument on startup, as well as the verbose command in the command line interface.

When the log file grows too large, it may exceed the operating system file size limit, which may be 2GB in

certain cases. This may cause the server to stop working, blocking on trying to write to the log file. As

well, large log files may take a long time to load and to browse through. Rotating the log file solves this problem by renaming the current log file with a number appended, and opening a new log file to be written to.

The server automatically rotates the log file periodically, depending on the size of the current log file. This

eliminates the need for a server administrator to rotate the logs periodically, although it is still possible to rotate the log file by issuing the rotate log command in the command line interface. The automatic log rotation is configured by the log_max_file_size and log_max_file_count parameters in the sipd.conf

configuration file. By default, the log is rotated when it reaches 10 MB and a maximum of 100 log files are stored. When the maximum number of log files is reached, the server will overwrite log files in a cyclical manner. In other words, the server will write to sipd.log.000099, sipd.log.0000100, and then

sipd.log.0000001, sipd.log.0000002, and so on. This way, the last 1 GB of logs are preserved. Using that schema, sipd.log.0000002 can be more recently updated than sipd.log.0000050. The sequence of the log files can be determined by checking the time and date of the log files:

$ ls -l sipd.log.*


14. Eyeball SIP Server: Port Settings

Port Settings

The Eyeball SIP Server requires at least 3 ports to be accessible from the public Internet in order to allow SIP clients to connect. In addition to the default ports 5060 and 5061, the Eyeball SIP Server also listens for connections on ports 443 and port 80 in order to allow clients behind restricted firewalls and HTTP

proxies to connect.

Direction Destination Port Protocol Purpose

Incoming 5060 UDP/TCP SIP

5061 TCP SIP over TLS (if configured)

443 TCP SIP

80 TCP SIP

Outgoing 443 TCP

Connection to Eyeball licensing servers

ls1.eyeball.com, ls2.eyeball.com, ls3.eyeball.com

Table 1: Default incoming and outgoing port settings required to run the Eyeball SIP Server

In addition to the ports that need to be accessible from the public Internet, the Eyeball SIP Server

connects periodically (once every hour) to one of Eyeball Networks licensing servers. The default ports that must be opened in incoming and outgoing direction are listed in Table 1.


15. Eyeball SIP Server: Troubleshooting

Troubleshooting

If you have problems running either edge or state server and it cannot be resolved by following the steps outlined in the INSTALL file or by consulting this document, the log file should be sent to Eyeball Networks Inc. together with a detailed description of the problem.


16. Eyeball SIP Server: Further Information

Further Information

For a more detailed description of the installation process for the Eyeball SIP Server, please refer to the

documents included in the Eyeball SIP Server package, in particular INSTALL and README.


17. Eyeball SIP Server: Legal and Contact Information

Legal and Contact Information


Confidential Information: This Administrator’s Guide contains confidential and proprietary

information. The Administrator’s Guide has been provided to you in your capacity as a customer or evaluator of Eyeball Networks Inc.'s products. Unauthorized reproduction and distribution is prohibited unless specifically approved by Eyeball Networks Inc.

Eyeball, Eyeball.com, its logos, AnyBandwidth™ and AnyFirewall™ are trademarks of Eyeball Networks

Inc. All other referenced companies and product names may or may not be trademarks of their respective owners.

For more information visit Eyeball Networks Inc. at http://www.eyeball.com.

Department E-mail

Sales [email protected]

Technical Support [email protected]

Corporate Headquarters:

730 - 1201 West Pender

Vancouver, BC V6E 2V2

Canada

Tel. +1 604.921.5993

Fax +1 604.921.5909

http://www.eyeball.com/

mailto:[email protected]

mailto:[email protected]

eyeball sip server v8.0 administrator guide

Software

eyeball sip server interface

eyeball sip server v8

state server components

edge server component

eyeball networks

remaining server components

clients edge server

servers state servers