Eyeball Networks AnyFirewall Server V10 Administrator Guide

Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved.
Eyeball AnyFirewall™ Server v10
Administrator Guide

1. AFS Introduction
Introduction
This documentation is intended to be a comprehensive guide for configuring and running the Eyeball
AnyFirewall™ Server. The Eyeball AnyFirewall™ Server is an implementation of STUN and TURN (i
ncludes implementations of IETF RFC - 5389, RFC - 5766, RFC - 5780, RFC - 6062) as part of Eyeball’s
AnyFirewall™ Technology.

2.1. AFS Features Overview
Overview
The Eyeball AnyFirewall™ Server enables clients behind firewalls to communicate with peers. The STUN
protocol enables a client to learn its NAT firewall type, and to determine the best way to communicate
with peers. If a client can communicate directly with a peer, without using the AnyFirewall™ Server to
relay data, that may often be preferred; however, in the cases when this is not possible, clients may
allocate ports on the server. These ports can then be used to send and receive data to/from peers that
the client may have otherwise been unable to communicate with due to the NAT firewall the client is
behind.
Icon
The AnyFirewall™ Server supports UDP, TCP and TLS for relaying.
Client to AnyFirewallTM
Server AnyFirewallTM
Server to Peer
UDP UDP
TCP UDP
TCP TCP
TLS UDP
TLS TCP
Table 1: Protocols and protocol translation supported by AnyFirewall™ Server.
The server can be used in combination with other components in a VoIP deployment such as SIP proxies,
gateways, softswitches or application servers. Used in combination with soft clients such as Eyeball
Messenger SDK, based on the Eyeball AnyFirewall™ Engine, AnyFirewall™ Server interacts seamlessly
with media servers and media relays.
While the main area of application is voice-over-IP, the AnyFirewall™ Server can be used to support
firewall traversal for other applications such as distributed gaming platforms or file sharing/file transfer
applications.
A sample data flow using the AnyFirewall™ server with two SIP softclients is outlined in figure 1. Client
applications – such as those equipped with Eyeball AnyFirewall™ Engine - use the server to detect their
public IP address and port (using STUN) or to allocate ports for relaying data.

Figure 1: AnyFirewall Server performing STUN / TURN services

2.2. AFS Clustering
Clustering
The Eyeball AnyFirewall™ Server can be clustered using DNS SRV as a load balancing mechanism.
Icon
In order to add an AnyFirewall™ Server to the cluster, it is sufficient to add another server machine and
allow clients to connect to the new server. All AnyFirewall™ Servers should use the same database to
allow information to be shared among servers.

2.3. AFS Security
Security
The Eyeball AnyFirewall™ Server prevents unauthorized access to its resources by requiring a shared
username/password mechanism between server and clients. Any allocation of resources on the
AnyFirewall™ Server requires authentication.
The authentication mechanism is based on long term credentials, as defined by STUN. Long term
credentials (username and password) are stored in the database (in the account table, see Section 12.3.
Database Tables) and are usually generated by a provisioning system when an account for a user is
setup. In a typical application environment, those username and passwords are the same as on a SIP
proxy.

2.4. AFS Bandwidth Throttling
Bandwidth Throttling
Traffic for a user is throttled using a common token bucket algorithm that allows for short-term traffic
bursts, but prevents a user from misusing server resources. If such throttling is not required, the
parameter enable_token_per_user_throttling in the config file should be set to no. This throttling can be
controlled with the help of config parameters user_token_per_second and user_bucket_duration.
Similarly, there is a provision for the server’s overall throttling as well. This behavior is controlled by config
parameter server_token_per_second and server_bucket_duration.

2.5. AFS Wiretapping
Wiretapping
Due to the increasing demands on ISPs to employ wiretapping, Eyeball AnyFirewall™ Server enables an
ISP to save the traffic of certain users, which can also easily be associated with the source, destination,
time, and duration of the call.
The traffic for each wiretapped call is stored in two files: one for each direction. The location of the files is
determined by the wiretap_dir option in the server’s configuration file (see Section 5.1.2. Stun Relay
Configuration). The format of the name of each file is as follows:
<User>-<CurrentTime>-<SourceIP>-<DestinationIP>-<DestinationPort>.topeer.tap
<User>-<CurrentTime>-<SourceIP>-<DestinationIP>-<DestinationPort>-toclient.tap

2.6. AFS Eyeball Server Management
Eyeball Server Management
Eyeball AnyFirewall™ Server comes packaged with Eyeball Server Management, a web-based
application that simplifies the administration and monitoring of the server products from Eyeball Networks,
including the Eyeball AnyFirewall™ Server, SIP Proxy Server, and XMPP Server.
There are three different components of the ESM:
 User Administration: add, remove, or disable user accounts, modify account settings, and view
usage statistics for an account
 Server Statistics: provides service usage statistics for servers
 Server Monitoring: provides real-time state and load information about your company’s servers

3. AFS System Requirements
System Requirements
The Eyeball AnyFirewall™ Server has been certified for Red Hat Enterprise Linux 6.x (64-bit) , CentOS
6.x (64-bit) and Ubuntu Server 12.04 (64-bit) or upgraded version. Eyeball Networks does not guarantee
the correct execution of the servers on anything other than the certified distributions.
The current distribution of the Eyeball AnyFirewall™ 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 failure.
System Requirements
 RHEL 6.x (64-bit)
CentOS 6.x (64-bit)
Ubuntu 12.04 (64-bit)
 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
 Two 128 Kbps IP or greater TCP/IP network connections
The Eyeball AnyFirewall™ Server requires two IP addresses and listens on several different ports as
depicted in figure 2. The figure shows the default ports recommended for a standard installation. The
authentication and exchange of credentials is handled using the TLS connection on the primary IP
address. The STUN/STUN-Relay TLS, TCP, and the UDP ports are used for the allocation of TCP and
UDP ports on the server. In order to support HTTP proxy tunneling, both TLS and TCP ports should be
set to 443, using different IP addresses.

Figure 2: AnyFirewall™ Server IP address and port usage

4. AFS Installation
Installation
The Eyeball AnyFirewall™ Server package contains the server program binary (afwd) and the necessary
scripts, tools and documentation to install the Eyeball AnyFirewall™ Server.
Icon
For details on installation and setup, please refer to the INSTALL file found in the root directory of the
Eyeball AnyFirewall™ Server package. This file contains a description of the installation and initial
configuration of the server components.

5. AFS Server Configuration
Server Configuration
The configuration file, afwd.conf, is required to run the Eyeball AnyFirewall™ Server. A configuration file
can be created by following the steps outlined in the INSTALL file found in the server package.
Icon
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, afwd searches for the afwd.conf configuration file
in the local directory.
 5.1. AFS afwd.conf
 5.2. AFS Example configuration file

6. AFS TLS Configuration
TLS Configuration
The Eyeball AnyFirewall™ Server needs to be configured in order to allow outgoing and incoming
connections using TLS. To enable TLS connections to and from the Eyeball AnyFirewall™ Server, the
corresponding parameters of the configuration file must be set (see Section 5. Server Configuration). 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 (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 keyfileprivkey.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 name of your server's hostname must be the host name of the server on which
AFS is running. The certificate request file is generated as follows:
/> openssl req -new -key privkey.pem -out cert.csr
Icon
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 a 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.7.
Licensing). 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.

7.1. Password File
Password File
The password file is generated during the installation (see Section 12.1. Provisioning). 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 (non-encrypted
text) 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)
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.

7.2. User Accounts: pass3des
User Accounts: pass3des
The tool pass3des, found in the Eyeball AnyFirewall™ 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 7.1. Password File). The Eyeball AnyFirewall™ 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.

8. AFS Command Line Arguments
Command Line Arguments
AnyFirewall™ Server supports the following command line arguments.
Command Line
Argument
Description
-c, --config
<filename>
Specify the configuration file. The configuration file is necessary to run AnyFirewall™
Server.
-v, --verbose
<level>
Sets the verbosity level of the Eyeball AnyFirewall™ Server for logging. A higher
verbosity level means a more verbose mode.
The following levels are defined:
0: Only write critical problems to the log file that cause abnormal server termination.
These errors are mainly attributed to being unable to connect to the database or to
open specific ports. The Eyeball AnyFirewall™ Server cannot continue operation
once these problems are encountered.
1: Writes critical errors.
2: This is the default level. Writes non-critical errors.
3: Writes message requests.
4: Writes triggered events and requests.
5: Writes multiple messages per request to the log file.
The default, and recommended value, is 2.
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 Eyeball AnyFirewall™ Server runs as a background daemon. Using
this option will run the server in the foreground. The server output will be written to
standard output.
-V, --version Print Eyeball AnyFirewall™ Server version information and exit.
-h, --help Print help information and exit.

9. AFS Starting and Stopping the Server
Starting and Stopping the Server
The installation package contains a startup and shutdown script for the AnyFirewall™ server, which
should be placed in/etc/init.d. This script can be used to safely start and stop the server.
The server can also be started manually. Unless specified by –f option to run in the foreground, the
Eyeball AnyFirewall™ Server runs as daemon. The Eyeball AnyFirewall™ Server can be configured to
start automatically when you start the computer. Please refer to the INSTALL document for details.
When run as daemon, i.e., without the –f option on the command line, the output of the Eyeball
AnyFirewall™ Server is redirected to the output file specified in the configuration file. Otherwise, the
standard output is used.
To ensure that the server is running, please connect to the administration port by running telnet localhost
7001 (using default configuration). You can also check if the process afwd is running using the ps –ef
command.
Common reasons for an unsuccessful startup of the AnyFirewall™ Server include the following:
 Cannot read the configuration file: the configuration file is not specified or the specified file cannot
be read.
 Error during initialization. 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.
AnyFirewall™ Server gives a detailed error message indicating the cause of the failure. You may need to
examine the log file for an exact cause.
It is important to stop the server either using the script or the shutdown command using the command line
interface (see Section 10. Command Line Interface). Otherwise, the process may not be shutdown
correctly and cause problems when trying to restart the server.
The AnyFirewall™ Server returns 0 on successful exit. To ensure that the server is not running after a
shutdown, check the process afwd is not running, e.g., using the ps –ef | grepafwd command.

10. AFS Command Line Interface
Command Line Interface
AnyFirewall™ Server can be monitored and administered using the command line interface available via
a telnet connection to the administration port of the server. Several simultaneous connections to the
administration port are possible.
Connection to the administration port can be established using the telnet commands. The administration
port is specified in the server configuration file.
AnyFirewall™ Server supports the following administrative commands.
Command Description
Help Print the list of available commands and a brief explanation of each command.
Settings Print the connection status of the AnyFirewall™ Server.
verbose
<level>
Change the verbosity level of AnyFirewall™ Server to <level>. For the description of
verbosity levels, please refer to Section 13. Log Files.
Uptime Print the server running time.
Shutdown Shut down the server.
rotate_log
This command 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. Example: Assume the current log file is named
afwd.log and the last renamed log file was named afwd.log.0000003. After issuing
rotate_log the current log file is renamed afwd.log.0000004 and a new log file afwd.log
is opened.
bye, quit,
exit, ^D
Close the connection to the administration port.
.

11. AFS User Provisioning
User Provisioning
User accounts are added to the system in one of several ways. The easiest is using the web-based
Eyeball Server Management system, which allows the creation and modification of user accounts with
only a few button clicks. Alternatively, the Eyeball AnyFirewall™ Server installation package also contains
a sample script that can be used for provisioning. To create a user account using this tool, execute the
following command from the directory where you installed the server:
./tools/provision.pl -f –a add –u user –p user_password | isql
<data_source_name><user><password>
The afwd password was created during the server installation. The –f option specifies that an account will
be created with permission to use the AnyFirewall™ Server. Note that the provision script must include
the des_hex_key that was modified during the installation process.
Finally, the database can be directly manipulated, as is explained in the next section.

12. AFS Database
Database
This section describes how the Eyeball AnyFirewall™ Server uses the database and how to setup new
accounts. The database tables can be created using the database script included in the Eyeball
AnyFirewall™ server package. This script will also create a few test accounts, which can be used to test
the server.
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 modified.
Icon
Please be aware that provisioning and gathering of statistics is also available through the Eyeball Server
Management application that was distributed with this package.

13. AFS Log Files
Log Files
The AnyFirewall™ Server writes messages to the log file. By default, the log file is written to
/var/log/afwd.log.
Writing to /var/log/afwd.log may require root privileges. Make sure that afwd 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 afwd.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, multiple messages per
request are logged in order to aid debugging. The recommended and default verbosity level is 2, but 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, and block the system from writing 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 afwd.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 afwd.log.000099, afwd.log.0000100, and then
afwd.log.0000001, afwd.log.0000002, and so on. This way, the last 1 GB of logs are preserved. While it
may be confusing that afwd.log.0000002 can be more recently updated than afwd.log.0000050, the
sequence of the log files can be determined by checking the time and date of the log files.

14. AFS Port Settings
Port Settings
The following table lists the default port settings of the Eyeball AnyFirewall™ Server in order to allow
clients to connect.
Direction
Destination
Port
Protocol Purpose
Incoming 3478 UDP UDP STUN and STUN Relay
3479 UDP UDP STUN and STUN Relay
443 TCP
TLS authentication for STUN Relay, and TLS STUN and
STUN Relay
80 TCP TCP STUN and STUN Relay
7001 TCP Command Line Interface (for administration)
Outgoing 443 TCP
Connection to Eyeball licensing servers
ls1.eyeball.com, ls2.eyeball.com, ls3.eyeball.com
Incoming/Outgoing 1024-65536 TCP/UDP Ports that are dynamically allocated to clients for relaying
Table 2: Default incoming and outgoing port settings required to run the Eyeball AnyFirewall™ Server
In addition to the ports that need to be accessible from the public Internet, the Eyeball AnyFirewall™
Server connects periodically (once every hour) to one of Eyeball Networks’ licensing servers. The default
ports that must be opened in incoming or outgoing direction are listed in Table2.
IMPORTANT NOTICE
It is important to note that it is necessary to allow outgoing connections to any TCP/UDP port for the relay
functionality to work correctly.

15. AFS Troubleshooting
Troubleshooting
By default, the AnyFirewall™ Server is run with verbosity level two. For troubleshooting, please change
the verbosity level to five by running the command line interface on the administration port.
 AnyFirewall™ Server does not start. The output file of the Eyeball AnyFirewall™ Server gives
clear indication of the failure. The most common reasons include:
o Cannot read configuration file. Make sure that the configuration file exists and is readable
by the owner of the server process.
o Cannot connect to the database. This can have several reasons that are detailed below.
o License problem. Make sure that the Eyeball AnyFirewall™ server has a valid license
and can connect to the Eyeball License Server.
o Cannot bind to certain ports. Make sure that the ports specified in the configuration file
are not used by other applications.
o A previous instance of the Eyeball AnyFirewall™ Server was not ended correctly and a
.pid file (configuration file parameter pid_file, please see Section 5.1.5. Log Files) still
exists. A possible reason for this problem is that the server was killed with SIGKILL, e.g.,
using kill -9. In this case, please remove the pid file manually and restart the server.
 AnyFirewall™ Server reports that it cannot connect to the database.
o Make sure that the server configuration file provides the proper connectivity parameters.
o Make sure that the database authentication file contains the database user specified by
the configuration file. This file is created during the Eyeball server configuration.
o Make sure that the database is configured to accept connection from the host running the
AnyFirewall™ Server. Attempt to establish a connection using the unixODBC client.
 AnyFirewall™ Server does not generate a log file. The name of the log file is specified in the
configuration file. Please make sure that the specified directory exists. Please also make sure
that the directory is writable by the server process owner.
If you have problems running the server, the log file should be sent to Eyeball Networks Inc.

16. AFS 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 at www.eyeball.com.
Department E-mail
Sales sales@eyeball.com
Technical Support techsupport@eyeball.com
Corporate Headquarters:
102-100 Park Royal
West Vancouver, BC V7T 1A2
Canada
Tel. +1 604.921.5993
Fax +1 604.921.5909

Eyeball Networks AnyFirewall Server V10 Administrator Guide

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (20)

Similar a Eyeball Networks AnyFirewall Server V10 Administrator Guide

Similar a Eyeball Networks AnyFirewall Server V10 Administrator Guide (20)

Último

Último (20)

Eyeball Networks AnyFirewall Server V10 Administrator Guide