eyeball xmpp server administrator guide

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

Eyeball XMPP Server v9.5

Administrator Guide


1. Eyeball XMPP Server Overview

Overview

This documentation is intended to be a comprehensive guide for configuring and running the Eyeball XMPP Server, which is based on the XMPP (Extensible Messaging and Presence Protocol) standard.

The goal of XMPP is to provide an XML protocol for synchronous and asynchronous communication for client-to-client, client-to-server, and server-to-server messaging, although the primary use for XMPP is instant messaging (IM). The Eyeball XMPP Server is a scalable, distributed server, which enables client-to-client text communication in one domain.

Figure 1. Architecture overview


The Eyeball XMPP Server consists of two components: an edge server component and a state server component (see Figure 1). XMPP Clients such as Eyeball Messenger 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 XMPP 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 XMPP Server.

In order to scale an Eyeball XMPP 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.

Server-to-server communication is supported by server dialback and SASL. In addition, TLS can be enabled to encrypt the communication between two XMPP domains.


2. XMPP Server System Requirements

System Requirements

Generally, there are two ways to run the XMPP Server: locally or on a cloud server provider such as Amazon AWS, Microsoft Azure or Google Cloud. The recommended configurations are Amazon AWS and local. In either case, it is suggested that the combined CPU usage will not be higher than 75% (adjusted to the number of cores on the system).

Amazon AWS

64-bit Ubuntu 14.04LTS is recommended. Preinstalled images are available from http://cloud-images.ubuntu.com/releases/14.04/release/. HVM virtualization of a m3.large instance type is recommended.

In case of Amazon AWS it is not recommended to run a local MySQL server, but rather Amazon RDS MySQL instance should be used. Since the database component of the XMPP Server is used as a cache (stated) backup it is expected that db.m3.large instance will be sufficient.

Local installation

The minimum recommended configuration is a an Intel Xeon E5 2670 CPU with 8GB RAM running a 64-bit Ubuntu 14.04LTS OS. The local database instance should have at least 8GB RAM with at least MySQL version 5.5.

Following table shows minimum suggested version of a library per distribution

Package name Ubuntu Server 14.04

openssl 1.0.1f-1ubuntu2.5

libidn11 1.28-1ubuntu2

unixodbc 2.2.14p2-5ubuntu5

mysql-server-5.5

Note, that as always it is suggested to keep the packages updated

http://cloud-images.ubuntu.com/releases/14.04/release/

http://cloud-images.ubuntu.com/releases/14.04/release/


3. XMPP Server Installation

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

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

1. Configuration Files

There are two configuration files, one for xmppd, and another for stated usually named xmppd.conf and stated.conf. The minimal parameter set required to successfully start the server is generated during the steps described in the XMPP Server Configuration.

2. Database Installation

The XMPP Server has been tested for use with MySQL, PostgreSQL and Oracle XE databases. If you do not have your database installed already, install it according to XMPP Server Database.

3. ODBC Driver Installation

The ODBC driver must be installed an all servers including both the <dbhost> and all server hosts.

You will now need to istall the ODBC driver.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/4.+XMPP+Server+Configuration

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/10.+XMPP+Server+Database


Below are the drivers required for each database type:

MySQL: mysql-connector-odbc.i386

PostgreSQL: postgresql-odbc.i386

Oracle: oracle-instantclient-basic.i386

4. ODBC Driver manager

For installation instructions refer to install documents that come with the driver or driver manager you are using. For this example we will assume that the DSN (Data Source Name) that you have chosen is 'myDSN', and the driver manager you are using is unixODBC. An example '/etc/odbc.ini' file for a MySQL database might look like:

[myDSN]

Driver = MySQL

SERVER = localhost (or ip address)

PORT = 3306

DATABASE = eyeball

OPTION = 3

The corresponding entry in '/etc/odbcinst.ini' might look like this:

[MySQL]

Description = ODBC for MySQL

Driver = /usr/lib/libmyodbc3.so

Setup = /usr/lib/libodbcmyS.so

FileUsage = 1

You can use the driver manager's test utility to test ODBC connectivity to database once you have created the database schema and a database user.

5. Database Configuration in the conf file

Specify the ODBC data source name and user in the xmppd and stated configuration files. in xmppd.conf:

database_host = myDSN

database_user = <dbuser>


log_database_host = myDSN

log_database_user = <dbuser>

in stated.conf

database_host = myDSN

database_user = <dbuser>

6. Database Configuration - additional

PostgreSQL:

If you are installing multiple Eyeball server products, this step is repeated in all the server INSTALL guides and is only needed to be performed once.

In the 'postgresql.conf' file on the <dbhost> set:

listen_addresses = '<dbhost>'

In the 'pg_hba.conf' file on the <dbhost> set the desired user access method for example you might

choose:

local all all trust

host all all <dbhost-segment>/16 trust

.. where <dbhost-segment> could look like '192.168.1.0' to allow

connections from any 192.168.1.x hosts

Oracle:

These steps must be performed on each server host.

Ensure that '/etc/odbc.ini' has the IP address of the <dbhost> as the 'ServerName' value.


Ensure that the 'tnsnames.ora' entry matches the DSN in '/etc/odbc.ini'.

Ensure that the ORACLE_HOME environment variable is set.

Example:

ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server

Ensure the LD_LIBRARY_PATH environment variable is set.

Example:

LD_LIBRARY_PATH=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server/lib

Ensure the ORACLE_SID environment variable is set. The SID value must match the DSN and

'tnsnames.ora' entry.

Example:

ORACLE_SID=XE

7. Database Users

The database user's password for the server is stored outside of the configuration file in encrypted form. Create the password file for its database connection using the 'ebpasswd' utility in the tools directory.

When using Oracle XE, use the same database username to connect both the stated and xmppd server processes.

$ ./ebpasswd -d -u<dbuser> -p<password> > eyeball.auth

Set the server's password_file in both the xmppd.conf and stated.conf

password_file = <..path>/eyeball.auth

You must also create this user in your database and grant appropriate privileges to this user.


MySQL:

$ mysql -h<dbhost> -uroot -p -e"GRANT CREATE, SELECT, INSERT, DELETE, UPDATE on

<dbname>.* TO <dbuser> IDENTIFIED BY '<dbpassword>';"

Change 'localhost' in the following statement to reflect the host you wish to connect from:

$ mysql -h<dbhost> -uroot -p -e"GRANT CREATE, SELECT, INSERT, DELETE, UPDATE on

<dbname>.* TO <dbuser>@'localhost' IDENTIFIED BY '<dbpassword>';"

PostgreSQL:

Set current user to 'postgres':

$ su - postgres

Locate the 'createdb.sh' that comes with PostgreSQL and create the database.

If you are installing multiple Eyeball server products, this step is repeated in all the server INSTALL guides and is only needed to be performed once.

$ createdb <dbname>

Locate the 'createuser' script and create your user as shown below:

$ /usr/bin/createuser <dbuser>

Shall the new role be a superuser? (y/n) n

Shall the new role be allowed to create databases? (y/n) y

Shall the new role be allowed to create more new roles? (y/n) n

CREATE ROLE

Edit the postgreSQL schema files and replace the table owner 'postgres' to your <dbuser>.

Oracle:

With Oracle XE, the database and user are one in the same. The created user is also the database that the schema will be imported into.

If you are installing multiple Eyeball server products, these steps are repeated in all the server


Use the web interface supplied by XE to create the user/database (start apache first).

http://<dbhost>:8087/apex/

Go to Administration->Database Users and create a user with all the User Privileges selected.

Use 'sqlplus' to create the user/database:

CREATE USER <dbuser> IDENTIFIED BY <dbpassword> DEFAULT TABLESPACE users TEMPORARY

TABLESPACE temp QUOTA UNLIMITED ON users;

CREATE ROLE <dbrole>;

GRANT CREATE session, CREATE table, CREATE SEQUENCE, CREATE TRIGGER TO <dbrole>;

GRANT <dbrole> TO <dbuser>;

8. Database Schema

The database schema is created using the schema files located in the 'tools'

directory of the package. Use the the following syntax to enter the schema.

Note: the following should be executed from the <dbhost>.

MySQL example:

cat schema.mysql | mysql -u<dbuser> -p<dbpassword> <dbname>

cat schema.shared.mysql | mysql -u<dbuser> -p<dbpassword> <dbname>

postgreSQL example:

cat schema.postgreSQL | psql <dbname>

cat schema.shared.postgreSQL | psql <dbname>

Oracle example:

cat schema.oracle | sqlplus <dbuser>/<dbpassword>

cat schema.shared.oracle | sqlplus <dbuser>/<dbpassword>


9. Database Migration

This section is only important if you are upgrading from a previous installation of the Eyeball XMPP Server that did not have inter-domain support. Due to the inter-domain support within this version of the server, the users within the `contact` field in the `xmppsubscriptions` table should include the domain of the server. If the domain does not yet xist within the `Contact` field, it can be added by executing the following command (where your-domain is the domain for your server):

update xmppsubscriptions

set contact = CONCAT(contact, "@your-domain.com")

where contact not like "%@%"

10. Create a guest user account

The server uses Triple DES protected passwords for user accounts. The server must be configured with 3

Triple DES keys. `gen3deskey' can be found in the tools directory and generates three 64-bit keys

suitable for Triple DES.

Run `gen3deskey' to generate the 3 keys as one long string. $ <..path>/gen3deskey

85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d

Then add this to the password file as the password for user '3des':

$ <..path>/ebpasswd -d -u3des -p85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d >>

<..path>/eyeball.auth

In the tools directory you will find a basic user provisioning command line tool for adding, updating, removing, enabling, and disabling user accounts. Edit the provision.pl script and set the 3 Triple DES keys to those you set in the password file.

my $des_hex_key = '85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d';

With the 3 keys now set in the password file and the provisioning tool, add a guest user account with the following command. Inside the tools directory, the provision.pl script can find the pass3des binary to run.

$ cd tools

If you use Eyeball Network's AnyFirewall Server schema created...

http://provision.pl/

http://provision.pl/


$ ./provision.pl -aadd -uguest -ppassword -f | isql myDSN <dbuser> <password> -v

.. otherwise use the following:

$ ./provision.pl -aadd -uguest -ppassword | isql myDSN <dbuser> <password> -v

The above example uses 'isql' an ODBC connect utility that is supplied with unixODBC's ODBC driver manager.

11. TLS Configuration

The server requires to be configured in order to service TLS connections. Using OpenSSL, create the keyfile. When asked, enter the pass phrase or password. The password you choose must be entered again when creating the certificate request or when generating a self-signed certificate.

$ openssl genrsa -des3 -out privkey.pem 2048

The TLS username and password must be inserted into the server's password file. Append the tls username and password to the file using the 'ebpasswd' utility in the tools directory.

$ ./ebpasswd -d -utls -ppassword >> <..path>/eyeball.auth

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

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

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 <..path>/privkey.pem -out cert.pem -days 365

Set the tls user name, keyfile, and certificate values in the configuration file:

#

# TLS

#

tls_user = tls


tls_cert_file = <..absolute-path>/cert.pem

tls_cert_keyfile = <..absolute-path>/privkey.pem

12. License Configuration

Set the license parameters in the configuration file to their respective values. The license name and files are provided to you by Eyeball Networks.

Example (replace 'your-company' with the name of your license as obtained from Eyeball Networks):

#

# Licensing

#

license_name = your-company

license_cert_file = <..absolute-path>/your-company.crtpvk.pem

eyeball_cert_file = <..absolute-path>/eyeball-root.crt.pem

13. Server-to-Server Configuration

The server supports server dialback in addition to SASL for establishing server-to-server connections. To configure server dialback or SASL, specify the server-to-server listening port, most commonly port 5269. In 'xmppd.conf':

xmpp_server_port = 5269

In addition, for SASL, secrets must be created and inserted into the database table XMPPPeerDomains for each domain you are peering with. Use the pass3des utility to encrypt the secrets with the key specifically generated for the server in the previous step. Encrypt the incoming and outgoing secrets, specify the servers key, the domain you are peering with, and the secret.

$ ./tools/pass3des 85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d eyeball.com

password

964a72c60dcaa776cb86a3cc18905401

$ ./tools/pass3des 85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d eyeball.com

password2

964a72c60dcaa776bc96aa1fb4d5caf6

Add the encrypted secrets to the database table xmpppeerdomain, specifying the domain you are peering with, and its active status.


$ mysql <dbname> -h<dbhost> -uroot -p \

-e"INSERT INTO xmpppeerdomain set \

domain='eyeball.com', \

incomingpassword='964a72c60dcaa776cb86a3cc18905401', \

outgoingpassword='964a72c60dcaa776bc96aa1fb4d5caf6', \

active='Y';"

14. Start the Server

Start the server by issuing the following commands: $ <..path>/stated -c <..path>/stated.conf

$ <..path>/bin/xmppd -c <..path>/xmppd.conf

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

15. Start and Stop Scripts

There are start and stop bash scripts in the tools directory: init.d-stated and init.d-xmppd. There are two lines that you may need to modify, depending on the location of your binaries, and the options that you want to specify.

In init.d-stated:

binary="/usr/local/eyeball/bin/stated

options="-c /usr/local/eyeball/etc/stated.conf -s ALL"

In init.d-xmppd:

binary="/usr/local/eyeball/bin/xmppd"

options="-c /usr/local/eyeball/etc/xmppd.conf"

Copy these scripts to the /etc/init.d directory and rename them. This also causes the servers to start up automatically when the computer is restarted.

$ cp tools/init.d-stated /etc/init.d/stated

$ cp tools/init.d-xmppd /etc/init.d/xmppd

To start up the servers using the scripts, issue the following commands:

$ /etc/init.d/stated start


$ /etc/init.d/xmppd start

To shutdown the servers using the scripts, issue the following commands:

$ /etc/init.d/xmppd stop

$ /etc/init.d/stated stop

16. BOSH configuration with Apache and Ubuntu

The XMPP server supports XEP-0206 (XMPP Over BOSH) so that XMPP feature can be used from standard web browsers or in environments where access to standard XMPP ports is blocked.

BOSH implementation requires implementation of HTTP on the server side (within XMPP server process), however in order to simplify the implementation and improve stability the XMPP process only implements minimal portions of HTTP and thus can not be used directly by BOSH clients. To provide full HTTP implementation for BOSH clients, a proxy server is used. Eyeball recommended proxy server is Apache with proxy module enabled.

Even though other proxy servers such a nginx are known to work, this guide provides instructions for configuration of the Apache HTTP server.

http://xmpp.org/extensions/xep-0206.html

http://wiki.nginx.org/Main


Following are the instructions for installation and configuration of Apache web server on a Ubuntu based machine

Install apache server

sudo apt-get install apache2

Install mod_proxy

sudo a2enmod proxy_connect

sudo a2enmod proxy_http

sudo a2enmod proxy

Make sure that the following files exist in /etc/apache2/mods-enabled/ directory: proxy.conf, proxy.load

Add the following lines to /etc/apache2/sites-enabled/000-default

ProxyPass /http-bind/ http://XMPP-SERVER-BOSH-IP:BOSH-PORT/

ProxyPassReverse /http-bind/ http://XMPP-SERVER-BOSH-IP:BOSH-PORT/

Where XMPP-SERVER-BOSH-IP is the IP address that the XMPP server is listening on

Configure BOSH listening port (BOSH-PORT above) by modifying the xmppd.conf file

bosh_enable = y

bosh_port_no = BOSH-PORT

BOSH support should be enabled at this point


4. XMPP Server Configuration

Server Configuration

The Eyeball XMPP Server is configured using a configuration file for each server component, xmppd and stated.

For a basic installation and the necessary parameters to be set, please refer to the installation procedure as outlined in the XMPP server installation

Read more in Configuration Files and Scalability.

The configuration files, xmppd.conf and stated.conf, are required to run the Eyeball XMPP 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.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/3.+XMPP+Server+Installation

https://eyeballnetworks.atlassian.net/wiki/display/docs/4.1.+Configuration+Files

https://eyeballnetworks.atlassian.net/wiki/display/docs/4.2.+Scalability


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.

Parameter Description

bind_address

(No need to be changed)

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

server. If it is set to any then server will select one from available interfaces other than 127.0.0.1

database_host

(Must be changed)

See database_host for xmppd.conf .

database_user

(Must be changed)

See database_user for xmppd.conf.

password_file

(Must be changed)

See password_file for xmppd.conf.

pid_file


The XMPP State Server writes the process ID to this file. This is

/var/run/stated.pid by default. Please ensure that the file can be written by the

server process owner.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/Database+Connection

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/xmppd.conf


https://eyeballnetworks.atlassian.net/wiki/display/docs/4.1.1.+xmppd.conf




log_file


This is the State Server log file. This is /var/log/stated.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.

Parameter Name

Alternate Parameter Name

Value Description

-h --help display this help and exit

-a --address <x.x.x.x> server IP address

-l --force-local always publish local address

-p --port <n> server port for first instance

-c --config <file> specify configuration file

-s --server <type> specify SIP, XMPP, or ALL

(default)

-n --number-instances <n> number of instances

-v --verbose <n> verbosity level (0/1)


4.1. Configuration Files

Configuration Files

The configuration files, xmppd.conf and stated.conf, are required to run the Eyeball XMPP 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.

xmppd.conf


xmppd.conf

xmppd.conf

In the following sections, we provide detailed descriptions of the configuration parameters for xmppd. Most of the values are not required for a standard installation, but can be changed if necessary.

The following parameters are available, starting with the parameters that must be changed in order to get the server running:

bind_address

private_address

xmpp_port

xmpp_server_port

domain_name

forward_tcp_port

tcp_connections

tcp_connection_ timeout

tcp_sendbuffer_ size

recvbuffer_size

num_threads

server_to_server

allow_all_domains

server_require_sasl

server_require_tls

admin_port

broadcast_user

password_file

log_file

pid_file

database_host


database_user

log_database_host

log_database_user

logging_interval

enable_auth_library

auth_library

in_band_registration

password_change

server_multicast_limit

disable_md5_auth

bosh_enable

bosh_port_no

Read more about each parameter in the following pages:

Network Configuration

Server to Server Communication

Administration

Password File

Log Files

Database Connection

Licensing

Authentication Module

In-band Registration

Multicast

Force Plaintext Authentication

BOSH

PubSub

CPU Usage Settings

TLS Configuration

Message settings

Custom Namespace

Client TLS Configuration

Chat Room settings

Example




Available parameters:


bind_address

(Must be changed)

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 (except 127.0.0.1). 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 XMPP Edge 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.

xmpp_port


Specifies the port where the Eyeball IM Server listens to TCP client requests. By default, the XMPP port is set to 5222. Additional ports may be specified, such as port 443 for HTTPS tunneling and port 80. 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.


xmpp_server_port


Specifies the port where the Eyeball IM Server listens to TCP server-to-server connection requests. By default, the XMPP port is set to 5269.

domain_name

(Must be changed)

This is the XMPP domain used by Eyeball IM Server. If an incoming XMPP stream is addressed to a different domain, the message is forwarded. If an incoming XMPP stream 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_tcp_port


This TCP port defaults to 7020 It is used to receive TCP packets forwarded from other Eyeball IM 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.

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.

message_queue_size


Specify the size of message queue of worker threads. The default

value is 300.

max_request_size (No need to be changed)

Maximum request size for a single request. Default size is 1048576


enable_cloud

(Need to be changed if necessary)

Enable cloud public IP address detection. Available values yes or no. Default is yes. If the value is yes then cloud_type configuration should also have some valid value.

When the parameter is enabled, the XMPP server will contact an external entity or query the cloud provider's metadata service to obtain the instance's external (public) IP address.

cloud_type

(Need to be changed if necessary)

Cloud type to detect public IP address. Available value is ec2. This configuration will be ignored if enable_cloud is no.






server_to_server

(may be changed)

Enable or disable server-to-server communications. Set this to “Y” to enable and “N” to disable. By default, server-to-server communications is disabled. This option can also be controlled using the command line interface.

allow_all_domains

(may be changed)

When server-to-server communications is enabled, set to “Y” to allow servers of all domains to communicate. If this is set to “N”, communication will only be

allowed for domains specified in the XmppPeerDomains database table. By

default, this is set to “N”. This option can also be controlled using the command line interface.

server_require_

sasl

(may be changed)

Incoming server-to-server streams require SASL if this is set to “Y”. If this option

and server_require_tls is set to “N”, server dialback will also be available

for those streams as an authentication option. By default, this is set to “N”. If this is set to “N”, SASL can be required for specific domains by setting

the IncomingRequireSASL column in the XmppPeerDomains table to “Y”.

This option can also be controlled using the command line interface.

server_require_

tls

(may be changed)

Incoming server-to-server streams require TLS if this is set to “Y”. If this option

and server_require_sasl is set to “N”, server dialback will also be available

for those streams as an authentication option. By default, this is set to “N”. This option can also be controlled using the command line interface.


Administration

Administration



admin_port

(No change required)

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 below for the complete list of administrative commands.

broadcast_user

(should be changed)

The broadcast user has the ability to send broadcast messages. This could be useful in situations where the system administrator needs to send a message to ‘online’, ‘offline’, ‘all’ or individual users. This user must be provisioned as with any other user.


Password File

Password File

Available parameter:


password_file

(Must be changed)

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 ), and the database user and password. A suggested

file name is “ eyeball.auth ”.


Log Files



log_enable

(y|Y, n|N)

Enable or disable log. By default logging is enabled.

log_file


This is the Eyeball IM Server log file. This is /var/log/xmppd.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 Eyeball IM 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 Eyeball IM 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 XMPP Server writes the process ID to this file. This is

/var/run/xmppd.pid by default. Please ensure that the file can be written

by the server process owner.

use_syslog

(y | n)

The logs will divert to system log. Default is n.

out_file

<File path>

Location of debug file path. In this file debug trace of server will be stored.


Database Connection

Database Connection



database_host

(Recommended to be changed)

It is possible to define more than one host by providing additional

database_host entries in the configuration file. The Eyeball IM 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 the

password_file tag in 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

(usually the same as 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 Eyeball IM Server are written to the database (see Section 10. Database ). The default value, selected when the parameter is not explicitly specified, is 15 minutes.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/Password+File

https://eyeballnetworks.atlassian.net/wiki/display/docs/10.+Database


Licensing

Licensing


license_name


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


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.






auth_library_enable

(y|Y,n|N)

If any auth library is used then value should be set to ‘y’ or ‘Y’ otherwise it must be ‘n’ or ‘N’. If the value is set to ‘y’ then the next option must be given.

auth_library

(Full path to auth library)

The full path to auth library should be given. If the value of

‘enable_auth_library’ is ‘n’ then the value of this option is ignored.






in_band_registration

(y|Y,n|N)

Prevent or allow user to register new account or cancel existing account.

password_change

(y|Y,n|N)

Prevent or allow user to change their password.


Multicast

Multicast



server_multicast_limit Maximum limit for multicasting message and presence.






disable_md5_auth

(y|Y,n|N)

Force plain text authentication or enable md5 authentication


BOSH

BOSH



bosh_enable

(y|Y,n|N)

Enable or disable BOSH service.

bosh_port_no

The port number where BOSH service will listen.

Default is 5280. Ignore when bosh_enable is ‘n’.

bosh_tls_port_no

The port number where BOSH TLS service will listen.

The port number where BOSH service will listen for tls

connection. Which supports sslv2 and sslv3. Default is 5281.

Ignore when bosh_enable is 'n'.


PubSub



pubsub_persist_items

(y|Y,n|N)

Whether items will persist or not

pubsub_deliver_notifications

(y|Y,n|N)

A subscription option. Whether subscriber will receive notification or not.

pubsub_deliver_payloads

(y|Y,n|N)

A subscription option. Whether payload will be delivered with notification

pubsub_publish_model

(publishers | subscribers)

If "publishers" then only publishers can publish item to a node.

If "subscribers" then both publishers and subscribers can publish item to a node.

pubsub_include_publisher

(y|Y,n|N)

Whether publisher jid will be included in notification.

pubsub_max_items

(integer)

The maximum number of items to persist. Default 2^30.

pubsub_max_payload_size

(integer)

The maximum payload size in bytes. Default 512KB.

pubsub_notify_config

(y|Y,n|N)

Whether to notify subscribers when the node configuration changes.

pubsub_notify_delete

(y|Y,n|N)

Whether to notify subscribers when the node is deleted.


pubsub_notify_retract

(y|Y,n|N)

Whether to notify subscribers when items are removed from the node.

pubsub_notify_sub

(y|Y,n|N)

Whether to notify owners about new subscribers and unsubscribes.

pubsub_tempsub

(y|Y,n|N)

Whether to make all subscriptions temporary, based on subscriber presence.

pubsub_subscribe

(y|Y,n|N)

Whether to allow subscriptions.

pubsub_access_model

(roster | open)

Who may subscribe and retrieve items. Default access model for a node will be this value.

pubsub_purge_offline

(y|Y,n|N)

Whether to purge all items when the relevant publisher goes offline.

pubsub_send_last_published_item

(never | on_sub)

When to send the last published item.

pubsub_presence_based_delivery

(y|Y,n|N)

Whether to deliver notifications to available users only.

pubsub_item_expire

(integer)

Number of seconds after which to automatically purge items. Default 31536000 and minimum 300 second.

pubsub_node_expire_check

(y|Y,n|N)

Enable or disable check for expired nodes.

pubsub_node_expire_day

(integer)

The number of days after that an inactive node will be considered as expired. Default 7 days


CPU Usage Settings

CPU Usage Settings



tolerable_cpu_usage


If the CPU usage is more than x% then server will not receive

any new connection. Default 90%.

cpu_usage_check_timeout


Server calculates CPU usage after every x seconds. Default is

set to 300 second. It cannot be less than 15 second.


TLS Configuration

TLS Configuration



tls_cert_file

<File path> Location of TLS certifcate file. This file should be signed from any certified authority. Though self signed certificate can be used for testing purpose.

.

tls_cert_keyfile

<File path>

Location of TLS key file.

tls_cert_user

(String)

TLS username for the given key file. This username need to be set into '.auth' file.


Message settings

Message settings



send_message

(contact | all | db)

if send_message set to "contact", then server will allow user

to send message only to roster list. If "all‟, then user can send

message to any user. If "db‟, then database settings will be

considered. Default value is "contact‟.

offline_message

(y|n)

If the value is set to "y" then message will be saved as offline, if

"n" then messages will be discarded when user is offline.

auto_send_offline_messages

(y|Y, n|N)

If it is enabled then user will get offline messages automatically. Otherwise user have to retrieve offline messages manually. By deafult this option is disabled.


force_jid_case_sensitivity

(yes, no)

Behaviour if yes No need to lower case (normalize) JIDs and process them exactly as received

Behaviour if no Normalize (in our case lower case) JIDs (basically leave the behaviour as now)


Custom Namespace

Custom Namespace



allowed_namespace

(String)

Allowed list of custom namespace. User will be able to send iq request from client to client using these valid namespaces. Config file can have multiple entries for this.






client_tls_support (y,Y|n,N)

TLS connection enable to connect. Client will be

able to send starttls.

client_require_tls (y,Y|n,N)

TLS connection is must. Client must send starttls

to connect.

client_old_ssl_port_support (y,Y|n,N)

Client will be able to connect using old ssl

port.


Chat Room settings

Chat Room settings



chat_room_service

(Not mandatory)

Chat service name, default is

conference.domain .

chat_room_log (y,Y|n,N)

Enable logging for chat room messages.


Example

Example

A sample configuration file for the xmppd edge server is given below.

# Configuration file used by XMPP Server (xmppd)

# This file provides startup/run parameters

# Copyright (c) 2001-2011 Eyeball Networks Inc. All rights reserved. Patents pending.

# network configuration

bind_address = 32.40.50.60

private_address = 192.168.2.12

xmpp_server_port = 5269

xmpp_port = 5222

xmpp_port = 443

xmpp_port = 80

#

# Cloud settings

#

# enable_cloud = yes/no

# cloud_type = ec2

domain_name = my.xmpp.domain.com

forward_tcp_port = 7020

tcp_connections = 90000

tcp_connection_timeout = 5600

tcp_sendbuffer_ size = 10240

recvbuffer_size = 133072

num_threads = 16

message_queue_size = 300

max_request_size = 1048576

# server-to-server communcation

server_to_server = y

allow_all_domains = n

server_require_sasl = n


server_require_tls = n

# administration

admin_port = 7011

broadcast_user = <username>

# password file

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

# log files

log_enable= y

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

log_max_file_size = 10000000

log_max_file_count = 100

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

use_syslog = n

out_file = /usr/local/eyeball/logs/xmpp.out

# connection to database

database_host = eyeball

database_user = server

log_database_host = eyeball

log_database_user = server

logging_interval = 15

# 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

# Authentication Module

auth_library_enable = y

auth_library = /usr/local/eyeball/authmodule/libebauth.so

# In-band Registration

in_band_registration = y

password_change = y

# Multicast

server_multicast_limit = 20

# Force Plaintext Authentication

disable_md5_auth = y

# BOSH

bosh_enable = y

bosh_port_no = 5280

bosh_tls_port_no = 5281

# PubSub

pubsub_persist_items = y

pubsub_deliver_notifications = y

pubsub_deliver_payloads = y

pubsub_publish_model = subscribers

pubsub_include_publisher = y

pubsub_max_items = 100

pubsub_max_payload_size = 1024


pubsub_notify_config = y

pubsub_notify_delete = y

pubsub_notify_retract = y

pubsub_notify_sub = y

pubsub_tempsub = y

pubsub_subscribe = y

pubsub_access_model = open

pubsub_purge_offline = n

pubsub_send_last_published_item = never

pubsub_presence_based_delivery = n

pubsub_item_expire = 31536000

pubsub_node_expire_check = n

pubsub_node_expire_day = 365

# CPU Usage Settings

tolerable_cpu_usage = 80

cpu_usage_check_timeout = 3600

# TLS Configuration

tls_cert_user = tls

tls_cert_file = /usr/local/eyeball/cert.pem

tls_cert_keyfile = /usr/local/eyeball/prevkey.pem

# Message settings

send_message = all

offline_message = y

auto_send_offline_messages = y

# Custom Namespace

allowed_namespace = eyeball:namespace:a

allowed_namespace = my:namespace:custom

# Client TLS Configuration

client_tls_support = y

client_require_tls = n

client_old_ssl_port_support = y

# Chat Room Settings

chat_room_service = muc

chat_room_log = y


5. Scalability

Scalability

The following sections of this user manual describe scalability of the Eyeball XMPP Server.

Introduction

Adding an XMPP Edge Server

Removing an XMPP Edge Server

Adding an XMPP State Server

Removing an XMPP State Server

Configuration with Load Balancers


Introduction

Introduction

In order to add a new edge server to a cluster of servers, it is only necessary to setup a

new xmppd 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 ensure that end user or client requests can access 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.




To add an XMPP Edge Server, first start the server by issuing ONE of the following commands:

$ /etc/init.d/xmppd start

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

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

2. The XMPP Edge Server should write an entry into the XmppServerHistory database table.

The other XMPP Edge Servers and XMPP State Servers are unaware of the presence of the new XMPP Edge Server, except after a user logs in.

3. A record of the user will be updated in the XmppResources database table that indicates that the

user is connected to the new XMPP Edge Server. 4. When there are messages directed to this user, XMPP messages will be forwarded to the new

XMPP Edge Server. 5. The new Edge Server should use same domain_name, password_file. 6. The new Edge Server should use same database. Database Connection configurations should

point out to same database.

While the XMPP Edge Servers do not maintain a list of other XMPP Edge Servers, the server load is distributed using DNS load balancing, where different XMPP clients connect to different XMPP 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 _xmpp-client._tcp.mydomain.com

_xmpp-client._tcp.mydomain.com has SRV record 0 100 5222 xmpp1.mydomain.com.



In addition, entries in the firewall may be required to allow incoming TCP packets to reach the new XMPP Edge Server.




To remove an XMPP Edge Server, enter ONE of the following commands:

$ /etc/init.d/xmppd stop

$ kill `cat xmppd.pid`

When an XMPP Edge Server is properly shutdown, all TCP connections to that XMPP Edge Server will be closed and users will be logged out.

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




XMPP 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 XMPP State Servers and XMPP Edge Servers.

To add a XMPP 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 XMPP

(for the above command use ‘–s ALL’ if you are running a SIP Server as well)

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

$ ps ax

The XMPP State Server will register itself in the StateServerRegistry database table.

The XMPP Edge Server will periodically check the entries in this table and send queries to the new XMPP State Server.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/stateserverregistry




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

$ /etc/init.d/stated stop

$ kill `cat stated.pid`

The XMPP State Server will continue running for 10 to 20 seconds, to allow time for the XMPP Edge Servers to update their internal lists of XMPP State Servers and stopping making queries to the XMPP State Server that is shutting down.

If the XMPP State Server is terminated improperly, the XMPP Edge Servers may experience timeouts connecting to the XMPP State Server. This error condition should only last for at most 20 seconds, after which the Eyeball XMPP Server will resume normal operation.


Configuration with Load Balancers

In order to configure a large XMPP cluster a Load Balancer needs to be used. There are two kinds of traffic that need to be load balanced: XMPP traffic and BOSH traffic.

Load Balancing standard XMPP traffic

XMPP maintains a long-lived TCP connection over which it sends and receives XML stanzas. If the TCP connection is dropped it can be reestablished with any XMPP server in the cluster since the XMPP state is consistent across the cluster. Therefore, there are no special requirements for the load balancer in this case.

Load Balancing BOSH traffic

BOSH is implemented on top of HTTP. In addition, a BOSH context is kept on each XMPP server instance, therefore all BOSH requests for the same session must arrive to the same XMPP server. Therefore, there are two ways to load balance it: HTTP session stickiness and IP affinity.

In case of IP affinity, the load balancer will note the first time when it receives a TCP connection from a specific IP address and for all future connections coming from that address will use the server that it used for the first connection.

In case of BOSH, the flow is more complicated:

1. BOSH client sends BOSH request to the load balancer for the first time 2. For each BOSH request that the load balancer receives it checks if cookies belonging to it are

attached in the request 1. If cookies are present and valid, the load balancer passes the request on to the server

that was used before 2. Otherwise, the load balancer chooses the destination server, creates a cookie and

attaches it to the response that it forwards to the client 3. The client must attach the cookie it receives from the load balancer in all future requests

otherwise requests might be redirected to BOSH servers that don't have the context created

Using Amazon Elastic Load Balancer

Amazon ELB does not support IP affinity and another load balancer needs to be used in this case (for example nginx or HAProxy). To configure cookies:

1. Select a load balancer instance and choose Description 2. In the Port Configuration section, choose Edit

1. Choose Enable Load Balancer Generated Cookie Stickiness 2. Set the Expiration Period to 86400 seconds (24 hours)

http://xmpp.org/rfcs/rfc6120.html#stanzas



6. XMPP Server Password Settings

Password Settings

Encrypted passwords and keys are stored in '.auth' file. It contains database password, command line interface (CLI) password and password encryption key (3des).

Password File <Password Settings>

User Accounts: pass3des


Password File <Password Settings>

Password File

The edge server component of the Eyeball XMPP 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 XMPP Server installation package is used to encrypt the contents of the password file.

The password file is generated during the installation (see 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)

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.





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

user’s passwords in the database and used for provisioning ( see Section 10.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 Password File). The Eyeball XMPP 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. XMPP Server Command Line Arguments

Command Line Arguments

All XMPP and State server run time settings can be modified in <xmppd.conf> and <stated.conf> files. After any modification in these files needs XMPP/State server restart.

xmppd

stated


xmppd

xmppd

The xmppd executable supports the following command line arguments:

Command Line Description

-c, --config

<filename> Specifies the configuration file. The configuration file is necessary to run the xmppd

server component.

-v, --

verbose

<level>

Set verbosity level of Eyeball XMPP 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 XMPP stanza is written to the log file. The default and recommended value is 4 (log TCP connections and disconnections). 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 XMPP 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 Eyeball XMPP Server version information and exits.

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


stated

stated

The stated executable supports the following command line arguments:

Command Line 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. This setting should not be changed.

-l, --force-local Force server to use EC2 local interface


8. XMPP Server - Starting and Stopping the Server

Starting and Stopping the Server

In order to run the Eyeball XMPP 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/xmppd start

When the Eyeball XMPP 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 command line interface port. This can be done

using the command telnet localhost 7011 (port 7011 is used for the command line interface in the

default configuration).

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

In the event of an unsuccessful startup, the Eyeball IM 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 XMPP 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 server may be stopped with:

/etc/init.d/stated stop

/etc/init.d/xmppd stop

Unless specified by –f option to run in foreground, the Eyeball XMPP Server runs as daemon in the

background.


9. XMPP Server Command Line Interface

Command Line Interface

The Eyeball XMPP 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’.

It is HIGHLY RECOMMENDED that this password be changed 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 xmppd.conf. Several simultaneous connections to the

administration port are possible.

Connection to the administration port can be established using the telnet or nc commands. The

administration port is specified in the server configuration file.

The Eyeball XMPP Server supports the following administrative commands:

Administrative commands

Description


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

verbose

<level> Change the verbosity level of Eyeball XMPP Server to <level>. For the description of verbosity levels, please refer to Section 12. XMPP Server Log Files.

server to

server [y/n]

Enable or disable server-to-server communications. Set this to “y” to enable and “n” to disable. By default, server-to-server communications is disabled. This option can also be

controlled using the xmppd.conf configuration file.

allow all

domains [y/n]

When server-to-server communications is enabled, set to “y” to allow servers of all domains to communicate. If this is set to “n”, communication will only be allowed for

domains specified in the XmppPeerDomains database table.

By default, this is set to “n”. This option can also be controlled using the

xmppd.conf configuration file.

server

require sasl

[y/n]

Incoming server-to-server streams require SASL if this is set to “y”. If this option and server require tls is set to “n”, server dialback will also be available for those streams as an authentication option. By default, this is set to “n”. If this is set to “n”, SASL can

be required for specific domains by setting the IncomingRequireSASL column in

the XmppPeerDomains table to “y”. This option can also be controlled using the


server

require tls

[y/n]

Incoming server-to-server streams require TLS if this is set to “y”. If this option and server require sasl is set to “n”, server dialback will also be available for those streams as an authentication option. By default, this is set to “n”. This option can also be controlled using the


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 Eyeball XMPP Server.

connections Print the currently active TCP and TLS connections.

users Display the number of online user resources and total users.

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

messages Display the number of instant messages, file transfers, presence stanzas, iq stanzas, and keep-alives.

settings Display the current settings of the server.

shutdown Shut down the server.

version Print the server version.

uptime Print the server running time.


10. XMPP Server Inter-domain Communication

Inter-domain Communication

Eyeball XMPP Server supports server dialback and SASL connection methods for inter-server communication. In addition, TLS is supported to encrypt inter-server communication.

The connection methods chosen to interact with a new domain depends on the settings of the other domain.

The database is used to specify peering and authentication methods.

The CLI of the Eyeball XMPP Server allows enabling server-to-server communication and selection of SASL or dialback method on the fly. However, enabling server-to-server communication requires the correct entries in the database.


Specifying a peering method

Specifying a peering method

In order to specify a peering method, set the OutgoingAuthMethod column of the XmppPeerDomains table to one of " auto", " SASL", or " dialback" (see Section 10.3. Inter-domain Communication). Setting the " Active" column to " N" will disable peering with that realm. Incoming and outgoing peering methods need not be the same. For example, it is possible to specify dialback for incoming and SASL for outgoing connections.


Enabling SASL

Enabling SASL

SASL secrets must be created and inserted into the database table xmpppeerdomains for each domain you are peering with. Use the pass3des utility to encrypt the secrets with the 3DES key specifically generated for each server. For each server, encrypt the incoming and outgoing secrets, specify the server’s key, the domain you are peering with, and the secret on realm a.net:

$ ./tools/pass3des 85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d

b.net password

$ ./tools/pass3des 85987523cbab6d892f645d762a9745f86bbaf7d5b0cdc16d b.net

password2

Add the encrypted secrets to the database table xmpppeerdomains, specifying the domain you are peering with.


Forcing TLS or SASL for incoming connections

Forcing TLS or SASL for incoming connections

Specify either server_require_tls or server_requires_sasl to force incoming peer connections to use TLS or SASL.

Both can be enabled and disabled via the command line interface CLI.


Setting up DNS SRV for Server Callback

Setting up DNS SRV for Server Callback

In case, server dialback is used for inter-domain communication, it is necessary to create DNS SRV settings to allow other servers to locate the XMPP domain.

The following example illustrates the required DNS SRV setting for two edge servers (port 5269 is used for inter-domain traffic):

_xmpp-server._tcp.mydomain.com has SRV record 0 100 5269 xmpp1.mydomain.com

_xmpp-server._tcp.mydomain.com has SRV record 0 100 5269 xmpp2.mydomain.com


Example <Inter-domain Communication>

Example

The following describes how to setup the Eyeball XMPP server to peer with a domain ‘sample.net’ using dialback.

1. set the xmpp_server_port configuration parameter to port 5269 in the configuration file: xmpp_server_port = 5269

2. set the server_to_server configuration parameter in the configuration file: server_to_server = y 3. Specify the servers you would like to peer with by inserting a record of the server into the

database (this applies to both incoming and outgoing connections).

To allow realm ‘sample.net’ to peer with this server, add a record to the XmppPeerDomains table.

INSERT INTO XmppPeerDomains SET Domain = "sample.net", OutgoingAuthMethod =

"dialback"

4. peering is now enabled via dial back, start/restart the Eyeball XMPP Server.

https://eyeballnetworks.atlassian.net/wiki/display/docs/xmpppeerdomain


11. XMPP Server Database

Database

This section describes how the Eyeball XMPP Server uses the database and how to setup new accounts. The database tables can be created using the database schema file(s) included in the Eyeball XMPP server package. This script will also create a few test accounts, which can be used to test the Eyeball XMPP Server. 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.

MySQL

XMPP server uses the event_scheduler mechanism of MySQL. By default, it is disabled. In order to enable it set the event-scheduler parameter in your MySQL configuration file to ON.


10.1 Provisioning

The Eyeball IM Server installation package contains a sample script that can be used for provisioning. The following sections describe how the provisioning can be done manually without using the script.

Accounts

Contact Lists


Accounts

Accounts

Adding and removing user accounts requires accessing the accounts 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)

im_settings varchar(1)

pubsub_update varchar(1)

vcard_update varchar(1)

vcard_privacy varchar(1)

storage_update 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’). It can also be set to ‘A’, which means the user account has been abused and is also disabled. This can be used e.g. to temporarily deactivate a user without deleting the account so it can be activated later. In addition, the Accounts 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 10.4. Database Tables).


Contact Lists

Contact Lists

In order to add a contact for a user, for example, to automatically add a pre-defined contact to the contact list for a new user with some predefined contacts (e.g. ‘Support’), the table xmppsubscription must be modified. Usually, this is done by users from a client program (e.g., Eyeball Messenger), but it can also be added directly to the database, e.g., when setting up a new account. This table must also be filled with information when migrating users from a different presence server.

The table xmppsubscription contains the following columns:

Column Type

account_id integer

contact varchar(48)

contactgroup varchar(32)

state varchar(24)

contactdisplayname varchar(1024)

In order to add a contact directly to the database, only the fields account_id, contact, contactdisplayname, and contactgroup must be filled. The other fields are for internal usage only, e.g., updated when a contact changes its status.

The account_id contains the ID of the user who owns the contact list. The contact field contains the ID of the new contact. contactdisplayname is set to the display name and contactgroup to the group.

The contact list related information is cached in state servers and therefore will not be updated for users that have already been logged in. Therefore the information for a user in the table xmppsubscription should only be modified at the time a new account is created. Modifying the data after the first login is not recommended and should be avoided as it may lead to undesired results.


10.2. Statistics

Statistics

The Eyeball IM 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 xmppserverstatistics which is described in Section 10.4. Database Tables. This table captures status and usage information of the Eyeball IM Server, which is periodically logged. The logging interval can be adjusted using the logging_interval parameter in the configuration file (see Section 4.1. Configuration Files ). 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.

In order to keep track of user’s logins, the table xmpploginhistory is used. The table stores user’s names, contact IP address and time of the last login and logout.

https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/4.1.+Configuration+Files


10.3. Inter-domain Communication

Inter-domain Communication

The table xmpppeerdomain entries define the peering method (‘auto’, ‘dialback’, ‘SASL’) and passwords. ‘auto’ means the Eyeball IM Server will automatically determine the method to connect during the handshaking process with the peer domain. The table also stores credential information for server-to-server connections for SASL. This table can also be used to limit the peer domains of the Eyeball IM Server. Setting the "Active" column to "N" for a particular domain will disable peering with that domain.

For more information, please refer to Section 9. Inter-domain Communication.

CREATE TABLE `xmpppeerdomain` (

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

ìncomingpassword` varchar(32) NOT NULL default ' ',

òutgoingpassword` varchar(32) NOT NULL default ' ',

òutgoingauthmethod` varchar(12) NOT NULL default 'auto',

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

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

PRIMARY KEY (`domain`)

)


10.4. Database Tables

Database Tables

This section describes and summarizes all the database tables used by the Eyeball IM Server. These tables are automatically generated by the installation and configuration scripts. 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 two database tables may optionally be placed in a separate database for logging purposes: xmppserverhistory and xmppserverstatistics.


account

account

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. (SELECT)

CREATE TABLE àccount` (

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

ùser_id` varchar(128) NOT NULL DEFAULT ' ',

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

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

ìm_settings` varchar(1) NOT NULL DEFAULT 'N' COMMENT 'Can send message out of

roster list',

`pubsub_update` varchar(1) NOT NULL DEFAULT 'N',

`vcard_update` varchar(1) NOT NULL DEFAULT 'N',

`vcard_privacy` enum('public','private','custom') NOT NULL DEFAULT 'custom',

`storage_update` varchar(1) NOT NULL DEFAULT 'N',

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

PRIMARY KEY (àccount_id`),

UNIQUE KEY àccount_user_index_idx` (ùser_id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=30 ;

Value Type

Y The account is active

N The account is inactive

A The account is set as abuser (inactive)


pubsub_affiliation

pubsub_affiliation

CREATE TABLE IF NOT EXISTS `pubsub_affiliation` (

ìd` int(10) NOT NULL AUTO_INCREMENT,

`node_id` varchar(50) NOT NULL,

`jid` varchar(256) NOT NULL,

àffiliation` varchar(500) NOT NULL,

ìs_admin_changed` int(1) NOT NULL DEFAULT '0',

PRIMARY KEY (ìd`)

) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=10 ;


pubsub_item

pubsub_item

CREATE TABLE IF NOT EXISTS `pubsub_item` (

`item_id` varchar(50) NOT NULL,

`node_Id` varchar(50) NOT NULL DEFAULT ' ',

`publisher_jid` varchar(256) NOT NULL DEFAULT ' ',

`payload` mediumtext NOT NULL,

`created` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,

PRIMARY KEY (`item_id`,`node_Id`)

) ENGINE=MyISAM DEFAULT CHARSET=latin1;


pubsub_node

pubsub_node

CREATE TABLE IF NOT EXISTS `pubsub_node` (

`node_id` varchar(50) NOT NULL DEFAULT ' ',

`persist_items` varchar(1) NOT NULL DEFAULT '1',

`deliver_notifications` varchar(1) NOT NULL DEFAULT '1',

`deliver_payloads` varchar(1) NOT NULL DEFAULT '1',

`publish_model` varchar(15) NOT NULL DEFAULT 'publishers',

`title` varchar(50) NOT NULL DEFAULT ' ',

`max_items` int(10) NOT NULL DEFAULT '1073741824',

`max_payload_size` int(10) NOT NULL DEFAULT '204800',

`notify_config` varchar(1) NOT NULL DEFAULT '0',

`notify_delete` varchar(1) NOT NULL DEFAULT '0',

`notify_retract` varchar(1) NOT NULL DEFAULT '0',

`notify_sub` varchar(1) NOT NULL DEFAULT '0',

`tempsub` varchar(1) NOT NULL DEFAULT '0',

`subscribe` varchar(1) NOT NULL DEFAULT '1',

`access_model` varchar(10) NOT NULL DEFAULT 'open',

PRIMARY KEY (`node_id`)

) ENGINE=InnoDB DEFAULT CHARSET=latin1;


pubsub_subscription

pubsub_subscription

CREATE TABLE IF NOT EXISTS `pubsub_subscription` (

`jid` varchar(256) NOT NULL DEFAULT ' ',

`node_id` varchar(50) NOT NULL DEFAULT ' ',

`subid` varchar(50) NOT NULL DEFAULT ' ',

`subscription_type` varchar(50) NOT NULL,

òption_include_body` int(1) NOT NULL DEFAULT '1',

òptions_deliver` int(1) NOT NULL DEFAULT '1',

èxpire_for_presence` varchar(50) NOT NULL,

èxpire_datetime` datetime NOT NULL DEFAULT '2213-07-06 16:17:53'



serverconfig

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`)

)


stateserverregistry

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`)

)


vcard

vcard

This table stores the vcard information of the user.

CREATE TABLE IF NOT EXISTS `vcard` (

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

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

`fullname` varchar(40) NOT NULL DEFAULT ' ',

`family_name` varchar(40) DEFAULT ' ',

`given_name` varchar(40) DEFAULT ' ',

`nick_name` varchar(40) DEFAULT ' ',

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

ùrl` varchar(100) DEFAULT ' ',

`street_address` varchar(100) DEFAULT ' ',

èxtended_address` varchar(100) DEFAULT ' ',

`locality` varchar(50) DEFAULT ' ',

`region` varchar(100) DEFAULT ' ',

`postal_code` varchar(50) DEFAULT ' ',

`country` varchar(100) DEFAULT ' ',

`telephone` varchar(50) DEFAULT ' ',

òrg_name` varchar(100) DEFAULT ' ',

òrg_unit` varchar(100) DEFAULT ' ',

`job_title` varchar(100) DEFAULT ' ',

`role` varchar(100) DEFAULT ' ',

`description` text NOT NULL,

ìmage_type` varchar(50) DEFAULT ' ',

ìmage` text NOT NULL, `subscriptiontype` int(10) unsigned NOT NULL DEFAULT '55288', `recordtime` datetime

DEFAULT '1970-01-01 00:00:00', PRIMARY KEY (àccount_id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8;


xmppblocklist

xmppblocklist

Contents of all users’ block lists are stored in this table. It contains rules such as which contact to block. (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppblocklist` (

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

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

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

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

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

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

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

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

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

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

KEY `xmppblocklist_user_index_idx` (àccount_id`,`listname`)



xmppblocklistname

xmppblocklistname

Names of block lists associated with each user are stored in this table (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppblocklistname` (


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

PRIMARY KEY (`account_id`)



xmppblocklistusage

xmppblocklistusage

Names of block lists associated with each resource are stored in this table. (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppblocklistusage` (


`listname` varchar(32) default NULL,

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

KEY `xmppblocklistusage_2_index_idx` (`account_id`,`listname`)



xmppchatroom

xmppchatroom

CREATE TABLE IF NOT EXISTS `xmppchatroom` (

`room_id` int(10) unsigned NOT NULL AUTO_INCREMENT,

`room_jid` varchar(96) NOT NULL,

`room_name` varchar(96) NOT NULL,

`room_description` varchar(96) DEFAULT NULL,

`thread_id` varchar(128) NOT NULL,

`to_multiparty` tinyint(4) NOT NULL,

`creation_time` datetime NOT NULL DEFAULT '1970-01-01 00:00:00',

`modification_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE

CURRENT_TIMESTAMP,

`canchangesubject` tinyint(4) NOT NULL,

`memberlimit` int(11) NOT NULL,

`publicroom` tinyint(4) NOT NULL,

`persistent` tinyint(4) NOT NULL,

`moderated` tinyint(4) NOT NULL,

`membersonly` tinyint(4) NOT NULL,

`locked` tinyint(4) NOT NULL,

`caninvite` tinyint(4) NOT NULL,

`password` varchar(48) DEFAULT NULL,

`candiscoveruser_id` tinyint(4) NOT NULL,

`logenabled` tinyint(4) NOT NULL,

`subject` varchar(100) DEFAULT NULL,

`usereservednick` tinyint(4) NOT NULL,

`canchangenick` tinyint(4) NOT NULL,

`canregister` tinyint(4) NOT NULL,

PRIMARY KEY (`room_jid`),

KEY `xmppchatroom_room_id_idx` (`room_id`)

) ENGINE=InnoDB DEFAULT CHARSET=latin1 AUTO_INCREMENT=16 ;


xmppchatroomaffiliation

xmppchatroomaffiliation

CREATE TABLE IF NOT EXISTS `xmppchatroomaffiliation` (

`room_id` int(10) unsigned NOT NULL,

ùser_id` varchar(96) NOT NULL,

àffiliation` enum('admin','owner','member','outcast') NOT NULL,

`date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE

CURRENT_TIMESTAMP,

PRIMARY KEY (`room_id`,ùser_id`(70))



xmppchatroomaffiliationhistory

xmppchatroomaffiliationhistory

CREATE TABLE IF NOT EXISTS `xmppchatroomaffiliationhistory` (



`affiliation` enum('admin','owner','member','outcast') NOT NULL,

`date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE

CURRENT_TIMESTAMP) ENGINE=MyISAM DEFAULT CHARSET=latin1;


xmppchatroomhistory

xmppchatroomhistory

CREATE TABLE IF NOT EXISTS `xmppchatroomhistory` (


`room_jid` varchar(96) NOT NULL,

`room_name` varchar(96) NOT NULL,

`room_description` varchar(96) NOT NULL,

`thread_id` varchar(128) NOT NULL,

`to_multiparty` tinyint(4) NOT NULL,

`creation_time` datetime NOT NULL DEFAULT '1970-01-01 00:00:00',

`modification_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON

UPDATE CURRENT_TIMESTAMP,

`canchangesubject` tinyint(4) NOT NULL,

`memberlimit` int(11) NOT NULL,

`publicroom` tinyint(4) NOT NULL,

`persistent` tinyint(4) NOT NULL,

`moderated` tinyint(4) NOT NULL,

`membersonly` tinyint(4) NOT NULL,

`locked` tinyint(4) NOT NULL,

`caninvite` tinyint(4) NOT NULL,

`password` varchar(48) DEFAULT NULL,

`candiscoveruser_id` tinyint(4) NOT NULL,

`logenabled` tinyint(4) NOT NULL,

`subject` varchar(100) DEFAULT NULL,

`usereservednick` tinyint(4) NOT NULL,

`canchangenick` tinyint(4) NOT NULL,

`canregister` tinyint(4) NOT NULL



xmppchatroomlog

xmppchatroomlog

CREATE TABLE IF NOT EXISTS `xmppchatroomlog` (

`id` int(10) unsigned NOT NULL AUTO_INCREMENT,


`sender` varchar(96) NOT NULL,

`nickname` varchar(255) DEFAULT NULL, `logtime` timestamp NOT NULL DEFAULT

CURRENT_TIMESTAMP ON UPDATE

CURRENT_TIMESTAMP,

`body` text,

`type` int(11) DEFAULT NULL,

KEY `xmppchatroomlog_idx` (`id`)

) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;


xmppchatroommembers

xmppchatroommembers

CREATE TABLE IF NOT EXISTS `xmppchatroommembers` (



`nickname` varchar(255) DEFAULT NULL,

`role` char(15) DEFAULT NULL,

`state` char(30) DEFAULT NULL,

`status` varchar(255) DEFAULT NULL,

PRIMARY KEY (`room_id`,`user_id`(70))



xmpploginhistory

xmpploginhistory

This table stores the login history. The Contact column stores the source address the client used to login as a string in the format “<IP>:<port>/<protocol>”. (INSERT)

CREATE TABLE `xmpploginhistory` (

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


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

`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',

PRIMARY KEY (`xmpploginhistory_id`),

KEY `xmpploginhistory_2_index_idx` (`account_id`,`login`)



xmppofflinemessage

xmppofflinemessage

Stores offline messages. (INSERT, SELECT, DELETE)

CREATE TABLE `xmppofflinemessage` (

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

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

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

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

`message` text NOT NULL,

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


PRIMARY KEY (`xmppofflinemessage_id`),

KEY `xmppofflinemessage_2_index_idx` (`touserid`,`messageid`)



xmpppeerdomain

xmpppeerdomain

This table stores credential information for server-to-server connections for SASL. This table can be used to limit the peer domains of the Eyeball IM Server.

CREATE TABLE `xmpppeerdomain` (


ìncomingpassword` varchar(32) NOT NULL default ' ',

òutgoingpassword` varchar(32) NOT NULL default ' ',

òutgoingauthmethod` varchar(12) NOT NULL default 'auto',

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





xmpppeerdomainconnection

xmpppeerdomainconnection

This table stores the current active server-to-server connections.

CREATE TABLE `xmpppeerdomainconnection` (


`state` varchar(12) NOT NULL default 'auto',

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

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

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




xmppprivatestorage

xmppprivatestorage

Stores private user data. (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppprivatestorage` (

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


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

`namespace` varchar(64) NOT NULL default ' ',

`data` text NOT NULL,

PRIMARY KEY (`xmppprivatestorage_id`),

KEY `xmppprivatestorage_2_index_idx` (`account_id`,`nodename`,`namespace`)



xmppresource

xmppresource

Presence and connection information of user resources that are logged in. (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppresource` (

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


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

`state` varchar(12) NOT NULL default ' ',


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

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

`serveraddress` varchar(23) NOT NULL default ' ',

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

`lastpresence` longtext NOT NULL,

PRIMARY KEY (`xmppresource_id`),

KEY `xmppresource_user_index_idx` (`account_id`,`resourcename`)



xmppserverhistory

xmppserverhistory

Records times when each XMPP Edge Server starts and stops. (INSERT)

CREATE TABLE `xmppserverhistory` (

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

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


`action` varchar(16) NOT NULL default ' ',


PRIMARY KEY (`xmppserverhistory_id`),

KEY `xmppserverhistory_2_index_idx` (`xmppserver_id`,`recordtime`)



xmppserverregistry

xmppserverregistry

This table stores instance information.

CREATE TABLE `xmppserverregistry` (



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

PRIMARY KEY (`address`)



xmppserverstatistics

xmppserverstatistics

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

CREATE TABLE `xmppserverstatistics` (

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


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

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

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

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

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

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

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

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

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

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

PRIMARY KEY (`xmppserverstatistics_id`),

KEY `xmppserverstatistics2_id_idx` (`serveraddress`,`recordtime`)



xmppsubscription

xmppsubscription

This table stores contact lists for users. This will likely be the largest table. (INSERT, UPDATE, SELECT, DELETE)

CREATE TABLE `xmppsubscription` (

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

`contactgroup` varchar(32) default NULL,

`state` varchar(24) NOT NULL default 'none',

`contactdisplayname` varchar(1024) default NULL,


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

PRIMARY KEY (`xmppsubscription_id`),

KEY `xmppsubscription_index2_idx` (`account_id`,`contact`)



12. XMPP Server Log Files

Log Files

The XMPP Edge Server writes messages to the log file. By default, the log file is written to /var/log/xmppd.log.

Note that writing to /var/log/xmppd.log may require root access. Make sure that xmppd 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 xmppd.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 XMPP messages are logged. The recommended verbosity level is 4, where TCP connections and disconnections are logged. The verbosity level is set to 2 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 xmppd.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 xmppd.log.000099, xmppd.log.0000100, and then xmppd.log.0000001, xmppd.log.0000002, and so on. This way, the last 1 GB of logs are preserved. While it may be confusing that xmppd.log.0000002 can be more recently updated than xmppd.log.0000050, the sequence of the log files can be determined by checking the time and date of the log files.

$ ls -l xmppd.log.*


13. XMPP Server Port Settings

Port Settings

The Eyeball XMPP Server requires at least 3 ports to be accessible from the public Internet in order to allow XMPP clients to connect. In addition to the default port 5222, the Eyeball XMPP 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 5222 TCP XMPP

5223 TLS XMPP

5280 TCP BOSH

5281 TLS BOSH

443 TCP XMPP

80 TCP XMPP

Outgoing 43 TCP

Connection to Eyeball licensing servers

ls 1.eyeball.com, ls2.eyeball.com, ls3.eyeball.com

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

In addition to the ports that need to be accessible from the public Internet, the Eyeball XMPP 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.


14. XMPP Server Message Broadcasting

Message Broadcasting

First, you will need to create a user account (eg: ‘SysAdmin’, Administrator’, etc) for your messages to be from, this is the user id that will appear in the ‘from’ field of your messages. Secondly, you must specify this username in the xmppd.conf file as the ‘broadcast_user’.

There are four options for sending messages; online, offline, all users (both on and offline), or an individual user. Use any XMPP client to login as your admin user and send a message to one of the values shown below for it reach the intended recipient(s):

1 To all online users your.domain/announce/online

2 To all offline users your.domain/announce/offline

3 To all users (online and offline) your.domain/announce/all

4 To an individual user the individual’s user name

Offline messages will be stored as an offline message that the user will receive the next time they sign in



15. XMPP Server XEP Support

XEP Support

XEP Description Industry Status

Eyeball Support

XEP-0004

Data forms Final Supported

XEP-0009

Jabber RPC Final Not Supported

XEP-0012

Last Activity Final Not Supported

XEP-0013

Flexible offline message retrieval Draft Supported

XEP-0016

Privacy Lists Draft Partial Support

XEP-0018

Invisible Presence Rejected Not Supported

XEP-0020

Feature negotiation Draft Partial support

XEP-0030

Service Discovery Final Supported

XEP-0033

Extended Stanza Addressing Draft Supported

XEP-0034

SASL Integration Approved Supported

XEP-0039

Statistics Gathering (deferred) Deferred Not Supported

XEP-0045

Multi User Chat Draft Supported

XEP-0047

In-Band Bytestreams Draft Not Supported




























XEP-0048

Bookmarks Draft Not Supported

XEP-0049

Private XML Storage Historical Use Supported

XEP-0050

Ad-Hoc Commands Draft Not Supported

XEP-0054

vCard-temp Historical Use Supported

XEP-0055

Jabber Search Historical Use Not Supported

XEP-0059

Result set management Draft Not Supported

XEP-0060

Publish-Subscribe Draft Supported

XEP-0065

SOCKS5 Bytestreams Draft Not Supported

XEP-0066

Out of Band Data Draft Not Supported

XEP-0068

Field Standardization for Data Forms Approved Partial support

XEP-0070

Verifying HTTP Requests via XMPP Draft Partial support

XEP-0071

XHTML-IM (client-side) Draft Partial support

XEP-0072

SOAP over XMPP Draft Not Supported

XEP-0073

Basic IM Protocol Suite Obsolete Supported

XEP-0077

In-Band Registration Final Supported

XEP-0078

Non-SASL Authentication Obsolete Supported

XEP-0079

Advanced Message Processing Draft Not Supported

XEP-0080

User Location Draft Supported

XEP-0082

XMPP Date and Time Profiles Approved Supported

XEP-0083

Nested Roster Groups Approved Not Supported

XEP-0084

User Avatar Draft Not Supported

XEP-0085

Chat State Notifications Final Supported

XEP-0092

Software Version Draft Not Supported
















































XEP-0095

Stream Initiation Draft Supported

XEP-0096

SI File Transfer Draft Not Supported

XEP-0106

JID escaping Draft Client Side

XEP-0107

User Mood Draft Not Supported

XEP-0108

User Activity Draft Partial support

XEP-0114

Jabber Component Protocol Historical Use Not Supported

XEP-0115

Entity Capabilities Draft Supported

XEP-0118

User Tune Draft Not Supported

XEP-0122

Data Forms Validation Draft Partial support

XEP-0124

HTTP-Bosh Draft Supported

XEP-0126

Invisibility Approved Supported

XEP-0128

Service Discovery Extensions Approved Not Supported

XEP-0130

Waiting Lists Historical Use Not Supported

XEP-0131

Stanza Headers and Internet Metadata Draft Not Supported

XEP-0133

Service Administration Approved Partial support

XEP-0136

Message archiving Draft Supported

XEP-0137

Publishing SI Requests Draft Partial support

XEP-0145

Annotations Historical Use Not Supported

XEP-0146

Remote controlling clients (client-side) Approved Not Supported

XEP-0148

Instant Messaging Intelligence Quotient Humorous Not Supported

XEP-0153

vCard-Based Avatars Historical Use Supported

XEP-0157

Contact Addresses for XMPP Services Approved Not Supported

XEP-0158

CAPTCHA Forms Draft Not Supported
















































XEP-0160

Best Practices for Handling Offline Messages Approved Partial support

XEP-0163

Personal Eventing Protocol Draft Not Supported

XEP-0166

Jingle Draft Supported

XEP-0167

Jingle RTP Sessions Draft Supported

XEP-0170

Recommended Order of Stream Feature Negotiation Approved Supported

XEP-0171

Language Translation Draft Not Supported

XEP-0172

User Nickname Draft Supported

XEP-0175

Best Practices for Use of SASL ANONYMOUS Approved Not Supported

XEP-0176

Jingle ICE-UDP Transport Method Draft Supported

XEP-0178

Best Practices for Use of SASL EXTERNAL with Certificates

Approved Not Supported

XEP-0182

Application-Specific Error Conditions Approved Supported

XEP-0138

Stream Compression Final Not Supported

XEP-0184

Message Delivery Receipts Draft Not Supported

XEP-0185

Dialback Key Generation and Validation Approved Not Supported

XEP-0191

Simple Communications Blocking Draft Not Supported

XEP-0198

Stream Management Draft Partial Supported

XEP-0199

XMPP Ping Final Partial support

XEP-0202

Entity Time Final Not Supported

XEP-0203

Delayed Delivery Final Not Supported

XEP-0205

Best Practices to Discourage Denial of Service Attacks Approved Partial Support

XEP-0206

XMPP over Bosh Draft Supported

XEP-0220

Server Dialback Experimental Supported

XEP-0221

Data Forms Media Element Draft Not Supported
















































XEP-0223

Persistent Storage of Private Data via PubSub Approved Not Supported

XEP-0227

Portable Import/Export Format for XMPP-IM Servers (proposed)

Draft Partial support

XEP-0233

Use of Domain-Based Service Names in XMPP SASL Negotiation

Experimental Not Supported

XEP-0234

Jingle File Transfer Experimental Supported

XEP-0235

OAuth Over XMPP Deferred Supported

XEP-0237

Roster Versioning Draft Not Supported

XEP-0238

XMPP Protocol Flows for Inter-Domain Federation Deferred Not Supported

XEP-0248

PubSub Collection Nodes Experimental Partial support

XEP-0256

Last Activity in Presence Draft Partial support

XEP-0278

Jingle Relay Nodes (experimental) Experimental Supported






















16. XMPP Server Troubleshooting

Troubleshooting

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

Further information and tips on using Eyeball XMPP Server can be found at XMPP Server FAQ


https://eyeballnetworks.atlassian.net/wiki/display/XMPPS/XMPP+Server+FAQ


17. XMPP Server Legal and Contact Information

Legal and Contact Information


Confidential Information: This Administration Guide contains confidential and proprietary information. The Administration 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]