Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Eyeball XMPP Server Administrator Guide

5,222 views

Published on

Eyeball Networks XMPP Server is a carrier-grade presence and instant messaging server, based on XMPP which supports deployments of up to 50 million + subscribers with 100% service uptime. In addition to XMPP, IM Server also supports federated presence and instant messaging with AIM, Google Talk, MSN, Yahoo!, and others.

XMPP Server can be deployed alone or with Eyeball Networks SIP Server and AnyFirewall Server to provide infrastructure for consumer and enterprise voice, video conferencing, and unified communications services.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Eyeball XMPP Server Administrator Guide

  1. 1. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Eyeball XMPP Server v9.5 Administrator Guide
  2. 2. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  3. 3. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  4. 4. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  5. 5. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  6. 6. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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>
  7. 7. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  8. 8. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  9. 9. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  10. 10. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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>
  11. 11. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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...
  12. 12. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. $ ./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
  13. 13. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  14. 14. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. $ 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
  15. 15. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. $ /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.
  16. 16. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  17. 17. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  18. 18. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 (No need to be changed) 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.
  19. 19. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. log_file (No need to be changed) 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)
  20. 20. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  21. 21. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  22. 22. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved.  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
  23. 23. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Network Configuration Network Configuration Available parameters: Parameter Description 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 (No need to be changed) 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 (No need to be changed) 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.
  24. 24. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmpp_server_port (No need to be changed) 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 (No need to be changed) 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 (No need to be changed) 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 (No need to be changed) 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 (No need to be changed) Specify to change the TCP send buffer size. The default is 10,240 bytes (10 KB). recvbuffer_size (No need to be changed) Specify to change the TCP receive buffer size. The default is 133,072 bytes (128 KB). num_threads (No need to be changed) Specify the number of worker threads. The default is 16. message_queue_size (No need to be changed) 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
  25. 25. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  26. 26. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Server to Server Communication Server to Server Communication Available parameters: Parameter Description 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.
  27. 27. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Administration Administration Available parameters: Parameter Description 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.
  28. 28. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Password File Password File Available parameter: Parameter Description 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 ”.
  29. 29. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Log Files Available parameters: Parameter Description log_enable (y|Y, n|N) Enable or disable log. By default logging is enabled. log_file (No need to be changed) 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 (No need to be changed) 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 (No need to be changed) 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 (No need to be changed) 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.
  30. 30. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Database Connection Database Connection Available parameters: Parameter Description 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 (No need to be changed) 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.
  31. 31. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Licensing Licensing Parameter Description license_name (No need to be changed) Name of your license that is provided by Eyeball Networks Inc. Your organization must have a valid production license in order to run Eyeball Server components. The license name is delivered through the Eyeball Software download page. license_cert_file (No need to be changed) Name of the file containing your certificate and the private key of your organization. This file is provided by Eyeball Networks Inc. through the Eyeball Software download page. This file must be kept secret. eyeball_cert_file (No need to be changed) 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.
  32. 32. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Authentication Module Authentication Module Available parameters: Parameter Description 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.
  33. 33. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. In-band Registration In-band Registration Available parameters: Parameter Description 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.
  34. 34. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Multicast Multicast Available parameter: Parameter Description server_multicast_limit Maximum limit for multicasting message and presence.
  35. 35. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Force Plaintext Authentication Force Plaintext Authentication Available parameter: Parameter Description disable_md5_auth (y|Y,n|N) Force plain text authentication or enable md5 authentication
  36. 36. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. BOSH BOSH Available parameters: Parameter Description 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'.
  37. 37. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. PubSub Available parameters: Parameter Description 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.
  38. 38. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  39. 39. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. CPU Usage Settings CPU Usage Settings Available parameters: Parameter Description tolerable_cpu_usage (No need to be changed) If the CPU usage is more than x% then server will not receive any new connection. Default 90%. cpu_usage_check_timeout (No need to be changed) Server calculates CPU usage after every x seconds. Default is set to 300 second. It cannot be less than 15 second.
  40. 40. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. TLS Configuration TLS Configuration Available parameters: Parameter Description 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.
  41. 41. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Message settings Message settings Available parameters: Parameter Description 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.
  42. 42. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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)
  43. 43. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Custom Namespace Custom Namespace Available parameters: Parameter Description 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.
  44. 44. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Client TLS Configuration Client TLS Configuration Available parameters: Parameter Description 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.
  45. 45. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Chat Room settings Chat Room settings Available parameters: Parameter Description 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.
  46. 46. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  47. 47. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  48. 48. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  49. 49. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  50. 50. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  51. 51. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Adding an XMPP Edge Server Adding an XMPP Edge Server 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:
  52. 52. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. SRV _xmpp-client._tcp.mydomain.com _xmpp-client._tcp.mydomain.com has SRV record 0 100 5222 xmpp1.mydomain.com. _xmpp-client._tcp.mydomain.com has SRV record 1 100 5222 xmpp2.mydomain.com. _xmpp-client._tcp.mydomain.com has SRV record 2 100 5222 xmpp3.mydomain.com. In addition, entries in the firewall may be required to allow incoming TCP packets to reach the new XMPP Edge Server.
  53. 53. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Removing an XMPP Edge Server Removing an 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.
  54. 54. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Adding an XMPP State Server Adding an XMPP State Server 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.
  55. 55. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. Removing an XMPP State Server Removing an XMPP State Server 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.
  56. 56. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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)
  57. 57. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  58. 58. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  59. 59. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. User Accounts: pass3des User Accounts: pass3des 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.
  60. 60. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  61. 61. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  62. 62. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  63. 63. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  64. 64. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved.  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.
  65. 65. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  66. 66. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 xmppd.conf configuration file. 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 xmppd.conf configuration file. 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.
  67. 67. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  68. 68. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  69. 69. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  70. 70. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  71. 71. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  72. 72. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  73. 73. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  74. 74. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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
  75. 75. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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).
  76. 76. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  77. 77. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  78. 78. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 ' ', `incomingpassword` varchar(32) NOT NULL default ' ', `outgoingpassword` varchar(32) NOT NULL default ' ', `outgoingauthmethod` varchar(12) NOT NULL default 'auto', `active` varchar(1) NOT NULL default 'Y', `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', PRIMARY KEY (`domain`) )
  79. 79. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.
  80. 80. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 `account` ( `account_id` int(10) unsigned NOT NULL AUTO_INCREMENT, `user_id` varchar(128) NOT NULL DEFAULT ' ', `password` varchar(32) NOT NULL DEFAULT ' ', `active` varchar(1) NOT NULL DEFAULT 'Y', `im_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 (`account_id`), UNIQUE KEY `account_user_index_idx` (`user_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)
  81. 81. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. pubsub_affiliation pubsub_affiliation CREATE TABLE IF NOT EXISTS `pubsub_affiliation` ( `id` int(10) NOT NULL AUTO_INCREMENT, `node_id` varchar(50) NOT NULL, `jid` varchar(256) NOT NULL, `affiliation` varchar(500) NOT NULL, `is_admin_changed` int(1) NOT NULL DEFAULT '0', PRIMARY KEY (`id`) ) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=10 ;
  82. 82. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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;
  83. 83. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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;
  84. 84. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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, `option_include_body` int(1) NOT NULL DEFAULT '1', `options_deliver` int(1) NOT NULL DEFAULT '1', `expire_for_presence` varchar(50) NOT NULL, `expire_datetime` datetime NOT NULL DEFAULT '2213-07-06 16:17:53' ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
  85. 85. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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`) )
  86. 86. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. stateserverregistry stateserverregistry State Servers register here periodically to indicate that they are active (UPDATE, SELECT) CREATE TABLE `stateserverregistry` ( `address` varchar(32) NOT NULL default ' ', `status` varchar(21) NOT NULL default ' ', `recordtime` int(11) default NULL, `usercount` 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 (`address`) )
  87. 87. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. vcard vcard This table stores the vcard information of the user. CREATE TABLE IF NOT EXISTS `vcard` (
 `account_id` int(10) unsigned NOT NULL DEFAULT '0',
 `email` 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',
 `url` varchar(100) DEFAULT ' ',
 `street_address` varchar(100) DEFAULT ' ',
 `extended_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 ' ',
 `org_name` varchar(100) DEFAULT ' ',
 `org_unit` varchar(100) DEFAULT ' ',
 `job_title` varchar(100) DEFAULT ' ',
 `role` varchar(100) DEFAULT ' ',
 `description` text NOT NULL,
 `image_type` varchar(50) DEFAULT ' ',
 `image` text NOT NULL,
 `subscriptiontype` int(10) unsigned NOT NULL DEFAULT '55288', `recordtime` datetime DEFAULT '1970-01-01 00:00:00',
 PRIMARY KEY (`account_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  88. 88. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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` ( `account_id` int(10) unsigned NOT NULL default '0', `listname` varchar(32) NOT NULL default ' ', `type` int(10) unsigned NOT NULL default '0', `allow` 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', `iq` int(10) unsigned NOT NULL default '0', `value` varchar(32) NOT NULL default ' ', KEY `xmppblocklist_user_index_idx` (`account_id`,`listname`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  89. 89. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppblocklistname xmppblocklistname Names of block lists associated with each user are stored in this table (INSERT, UPDATE, SELECT, DELETE) CREATE TABLE `xmppblocklistname` ( `account_id` int(10) unsigned NOT NULL default '0', `listname` varchar(32) NOT NULL default ' ', PRIMARY KEY (`account_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  90. 90. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppblocklistusage xmppblocklistusage Names of block lists associated with each resource are stored in this table. (INSERT, UPDATE, SELECT, DELETE) CREATE TABLE `xmppblocklistusage` ( `account_id` int(10) unsigned NOT NULL default '0', `listname` varchar(32) default NULL, `resourcename` varchar(32) NOT NULL default ' ', KEY `xmppblocklistusage_2_index_idx` (`account_id`,`listname`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  91. 91. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 ;
  92. 92. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppchatroomaffiliation xmppchatroomaffiliation CREATE TABLE IF NOT EXISTS `xmppchatroomaffiliation` ( `room_id` int(10) unsigned NOT NULL, `user_id` varchar(96) NOT NULL, `affiliation` enum('admin','owner','member','outcast') NOT NULL, `date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`room_id`,`user_id`(70)) ) ENGINE=MyISAM DEFAULT CHARSET=latin1;
  93. 93. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppchatroomaffiliationhistory xmppchatroomaffiliationhistory CREATE TABLE IF NOT EXISTS `xmppchatroomaffiliationhistory` ( `room_id` int(10) unsigned NOT NULL, `user_id` varchar(96) NOT NULL, `affiliation` enum('admin','owner','member','outcast') NOT NULL, `date` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP) ENGINE=MyISAM DEFAULT CHARSET=latin1;
  94. 94. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppchatroomhistory xmppchatroomhistory CREATE TABLE IF NOT EXISTS `xmppchatroomhistory` ( `room_id` int(10) unsigned NOT NULL, `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 ) ENGINE=InnoDB DEFAULT CHARSET=latin1;
  95. 95. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppchatroomlog xmppchatroomlog CREATE TABLE IF NOT EXISTS `xmppchatroomlog` ( `id` int(10) unsigned NOT NULL AUTO_INCREMENT, `room_id` int(10) unsigned NOT NULL, `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 ;
  96. 96. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppchatroommembers xmppchatroommembers CREATE TABLE IF NOT EXISTS `xmppchatroommembers` ( `room_id` int(10) unsigned NOT NULL, `user_id` varchar(96) NOT NULL, `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)) ) ENGINE=MyISAM DEFAULT CHARSET=latin1;
  97. 97. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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, `account_id` int(10) unsigned NOT NULL default '0', `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`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  98. 98. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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 ' ', `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', PRIMARY KEY (`xmppofflinemessage_id`), KEY `xmppofflinemessage_2_index_idx` (`touserid`,`messageid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  99. 99. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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` ( `domain` varchar(32) NOT NULL default ' ', `incomingpassword` varchar(32) NOT NULL default ' ', `outgoingpassword` varchar(32) NOT NULL default ' ', `outgoingauthmethod` varchar(12) NOT NULL default 'auto', `active` varchar(1) NOT NULL default 'Y', `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', PRIMARY KEY (`domain`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  100. 100. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmpppeerdomainconnection xmpppeerdomainconnection This table stores the current active server-to-server connections. CREATE TABLE `xmpppeerdomainconnection` ( `domain` varchar(32) NOT NULL default ' ', `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', PRIMARY KEY (`domain`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  101. 101. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppprivatestorage xmppprivatestorage Stores private user data. (INSERT, UPDATE, SELECT, DELETE) CREATE TABLE `xmppprivatestorage` ( `xmppprivatestorage_id` int(10) unsigned NOT NULL auto_increment, `account_id` int(10) unsigned NOT NULL default '0', `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`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  102. 102. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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, `account_id` int(10) unsigned NOT NULL default '0', `resourcename` varchar(32) NOT NULL default ' ', `state` varchar(12) NOT NULL default ' ', `address` varchar(23) 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`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  103. 103. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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', `address` varchar(32) NOT NULL default ' ', `action` varchar(16) NOT NULL default ' ', `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', PRIMARY KEY (`xmppserverhistory_id`), KEY `xmppserverhistory_2_index_idx` (`xmppserver_id`,`recordtime`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  104. 104. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. xmppserverregistry xmppserverregistry This table stores instance information. CREATE TABLE `xmppserverregistry` ( `address` varchar(32) NOT NULL default ' ', `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', `processid` int(10) unsigned NOT NULL default '0', PRIMARY KEY (`address`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  105. 105. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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, `recordtime` datetime NOT NULL default '1970-01-01 00:00:00', `serveraddress` varchar(21) NOT NULL default ' ', `connections` int(10) unsigned NOT NULL default '0', `activeusers` int(10) unsigned NOT NULL default '0', `login` int(10) unsigned NOT NULL default '0', `logout` int(10) unsigned NOT NULL default '0', `instantmessages` int(10) unsigned NOT NULL default '0', `filetransfers` int(10) unsigned NOT NULL default '0', `presencestanzas` int(10) unsigned NOT NULL default '0', `iqstanzas` 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`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  106. 106. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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, `account_id` int(10) unsigned NOT NULL default '0', `contact` varchar(48) NOT NULL default ' ', PRIMARY KEY (`xmppsubscription_id`), KEY `xmppsubscription_index2_idx` (`account_id`,`contact`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  107. 107. Copyright © 2002-2014 Eyeball Networks Inc. Patented and patents pending. All rights reserved. 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.*

×