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.

http://www.unixodbc.org/


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.

http://www.openssl.org/


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 [email protected]

Technical Support [email protected]

Corporate Headquarters:

102-100 Park Royal West Vancouver, BC V7T 1A2 Canada

Tel. +1 604.921.5993 Fax +1 604.921.5909

http://www.eyeball.com/

mailto:[email protected]

mailto:[email protected]

Eyeball Networks AnyFirewall Server V10 Administrator Guide

Software

Transcript of Eyeball Networks AnyFirewall Server V10 Administrator Guide