SipExchange Installation HowTo

In order to understand how to install SipExchange, you must read the entire howto sequentially, not just the topics you need to know more about. This is because a topic may refer to a previous topic.

Table of Contents

Conventions followed in this document

  1. We have used the term “directory” to specify a file location. This is a common Unix convention. In the Windows environment, the term “folder” is used to mean the same thing.
  2. We have used the Unix directory naming convention in this document. In the Unix environment, a directory hierarchy is specified by the “/” separator. In the Windows environment, the “\” separator is used. In addition, Unix systems do not use drive letters as in Windows. If you are using Windows, you will need to modify the commands accordingly. For example, if we stated $JIPLET_HOME/bin and you are using Windows, it may translate to C:\jiplet-standalone\bin.
  3. We have used $SIPEXCHANGE_HOME or similar names to specify variables. While installing/configuring, you will need to replace these variables with the actual value. For example, in this document, the variable $SIPEXCHANGE_HOME has been used to specify the directory where the SipExchange code binary is unpackaged. We have commonly used the following variables:
    1. $JAVA_HOME – directory where the Java Runtime Environment (JRE) is installed.
    2. $SIPEXCHANGE_HOME – directory where the SipExchange software is unpacked.
    3. $JBOSS_HOME – directory where JBOSS is installed.
    4. $HOST – host name/IP address of the system where the jiplet container is installed.
    5. $RUN – the JBOSS run mode (default, minimal, all, etc.)
  4. Commands are specified using bold. You need to enter the command by typing/pasting the command and pressing the Enter/Return key. Although in the Unix world this may seem natural, in the Windows environment, lots of users are lost when it comes to entering a command. Also, the prompts “#” or “C:\>” are shown, do not enter them.

Hardware requirements

SipExchange runs as an enterprise application inside the JBOSS server and bundles the jiplet container software with it. The hardware requirements for running SipExchange are the same as that of the jiplet container. Please read the jiplet container installation howto for details. If you have a large SipExchange installation with many subscribers, you may need additional hard disk space and RAM.

It may be possible to install SipExchange on operating systems like MacOS but we have never tested with operating systems other than Microsoft Windows and Linux.

Pre-requisite software

The following pre-requisite software must be downloaded prior to installing SipExchange.

  1. Java software development kit (J2SDK): Download JDK 1.5 from the Sun web site – and install as per the instructions provided in the site. The software has been tested with J2SDK version 1.5. The software will not work with Java 1.4 and we have had some difficulty running the Jboss server with JDK 1.6.
  2. Apache Ant 1.7: Download Apache Ant 1.7 binary distribution from the Apache web site – and install as per the instructions provided in the site. The installation of the SipExchange application uses Ant for creating database tables and for deploying the software on the Jboss server.
  3. Jboss Application Server: Download and install Jboss 4.2.1GA binary distribution from and install as per the instruction provided by this site. If you try to install SipExchange on a later version of Jboss like 5.x, you may run into some incompatibilities. In a near future release, SipExchange will add support for the later Jboss versions.
  4. Jboss Portal: Download Jboss Portal 2.7.1 binary distribution from Do not install the software as instructed in the Jboss documentation. The installation procedure is outlined below.  If you try to install SipExchange on a later version of Jboss Portal, you may run into some incompatibilities.
  5. Instead of downloading Jboss Application Server 4.2.1 and Jboss Portal 2.7.1 separately, Jboss provides a bundled binary download containing both these components. You can download the bundled distribution. This reduces the number of installation steps slightly. Please see the steps described in the section – Installing Jboss Portal.
  6. MySQL server: SipExchange uses MySQL as a persistence layer for most application data. Download and install MYSQL 5.0 or above from the MySQL web site and install as per the instructions provided by the site. You can install the MySQL server on a separate server for relieving the load on the server running the Jboss Application Server (SipExchange). Please see the discussion below.

SipExchange installation

The SipExchange application uses the jiplet container for handling SIP messages. The jiplet container is bundled with SipExchange and you do not have to install it separately. Make sure that  the server where you want to install SipExchange meets the hardware requirements, the operating system is properly installed and networking is configured as described in the jiplet container installation howto.

Removing previous installations:

If you have previously installed the jiplet container as a Jboss service and/or deployed the jiplet container reference application, please uninstall them as it may adversely interact with SipExchange. To remove the Jiplet Container, do the following:

  1. Remove all jiplet-related sar and war files from $JBOSS_HOME/server/$RUN/deploy directory.
  2. Remove the directory $JBOSS_HOME/server/$RUN/conf/jiplet.

If you have SipExchange 0.0.4a installed on your system, please remove the older version of the software from your system. Starting from  version 1.0.0b, you will be able to upgrade to a newer version without losing any data. To remove the previous installation:

  1. Shutdown Jboss.
  2. Remove the directory $JBOSS_HOME/server/$RUN/conf/jiplet.
  3. Remove the sipex database by entering the following command:

    $ mysql -u root -p
    Enter password: mysql-root-password
    mysql> drop database sipex;
    mysql> exitTo run the “mysql” command, make sure that the $MYSQL_HOME/bin is included in the PATH environment variable on your system.  Replace the phrase “mysql-root-password” with the root password. If you do not have a root password set, don’t use the “-p” option in the mysql command.

Installing SipExchange on two servers

You can split the SipExchange processing load into two servers. In one of the servers, you can run the  MySQL database and in another server, you can run the Jboss application server. If you go with this approach, just make sure of the following:

  1. Install MySQL server in one of the servers.
  2. Install the rest of the software described above on the other server.
  3. Temporarily enable the MySQL “root” user to have access from the server running Jboss. This is needed during the installation time because the installation script needs to create databases and only the root user can do it by default. By default, MySQL restricts access to root account from localhost only for security reasons. Please remember to revert the access once the SipExchange installation is completed. To turn on root access from the other server, you need to enter the following command from a command prompt/terminal.

    $ mysql -u root -p
    Enter password: mysql-root-password
    mysql>flush privileges;
    mysql> exit

    Replace SIPEX_SERVER in the commands above with the IP address/host name of the server where the Jboss application server is installed. Replace ROOT_PASSWORD by a cryptic password that you want for the MySQL root user.

  4. Run the installation steps described below from the server running the Jboss application server.

Installing Jboss Portal

As mentioned earlier, you must not install the Jboss Portal as per the instructions provided in the Jboss Portal installation documentation. Instead, you must use the procedure outlines below.

If you downloaded the Jboss AS + Jboss Portal bundle, follow the steps outlined below:

  1. Unpack the binary distribution under an appropriate directory. This directory will be referred to as $JBOSS_HOME from now on.
  2. Delete the file $JBOSS_HOME/server/$RUN/deploy/portal-hsqldb-ds.xml. You can also move the file to another location and save the file.
  3. There is a bug in MySQL 5.0 server that prevents the Jboss Portal from running properly. Please see step 5, below for instructions on how to remedy the situation.

If you downloaded and installed Jboss AS and want to add the Jboss Portal software, at the top of it, follow the steps below:

  1. Unpack the Jboss Portal distribution that you downloaded into a temporary area in your filesystem. The distribution is extracted into the directory – jboss-portal-x.y.z where x.y.z is the version number.
  2. Shutdown the Jboss server if it is running.
  3. Under this directory, you will file a sub-directory called – jboss-portal.sar.
  4. Copy this directory under the directory – $JBOSS_HOME/server/$RUN/deploy.
  5. There is a bug in the MySQL 5.0 server that prevents the Jboss Portal from running properly. Here is the instruction from the Jboss Portal wiki. Please execute step 1 below and ignore the step 2.

Your trail:
MySQL 5 can run in strict mode, which causes errors to be thrown instead of warnings when data truncation occurs (see mysql bug 14048).

Errors may look similar to this:

11:16:36,520 ERROR JDBCExceptionReporter? Data truncation: Data too long for column ‘jbp_viewrealemail’ at row 1

While MySQL 5 is not yet supported, there is a way to prevent the error from being thrown during the installation of the portal:

   1. If you have MySQL 5 installed already and running in strict mode, edit the my.ini (or my.cfg) file of MySQL and remove the “STRICT_TRANS_TABLES” part from the line: sql-mode=STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
   2. Add “jdbcCompliantTruncation=false” in your datasource descriptor file (*-ds.xml) under the deploy directory. Your connection URL should look like: <connection-url>jdbc:mysql://your-host-name:3306/jbossportal?useServerPrepStmts=false&amp;jdbcCompliantTruncation=false</connection-url>

This should prevent any further data truncation related errors during the portal installation.

The SipExchange installation process will do the rest of the portal installation for you.

Installing SipExchange

Download and unpack SipExchange

After you have installed all the base software including the Jboss Portal, the next step is to install the SipExchange software itself. Download the binary version of the software from the SipExchange download page. The software is packaged into a ZIP file. Unpack the distribution into a temporary area using a zip utility. On Linux, you can use the “unzip” utility or the “jar” utility included with the J2SDK package. On Windows, you can use  the unzip utility included with some versions of Windows or you can use an utility like WINZIP.  When you unpack, it will create a directory called “sipexchange” under the temporary area where you unpacked the distribution. We will refer to this directory as $SIPEXCHANGE_HOME from now on.

Prepare the Jboss server

Follow the steps outlined below:

  1. Shutdown the Jboss server if you are running it.
  2. Adjust the Java memory parameters in order to ensure that Jboss does not run out of memory when running SipExchange. You may have to adjust these values further depending on the number of users but the following JVM parameters are a good start: -Xms128m -Xmx512m -XX:MaxPermSize=256mYou can set these values by adding to the environment variable – JAVA_OPTS specified in the file $JBOSS_HOME/bin/run.bat (or if using Linux). Read the Jboss documentation for more details.
  3. By default, the Jboss web server only listens to connections from localhost. You have to tell the Jboss application server to listen to connections from external interfaces. For more details, read the Jboss documentation on this topic.
  4. SipExchange will install the SipExchange enterprise application under the “default” server. Jboss comes with various server configurations like “default”, “all”, “minimal”, etc. You can find out what server configurations are included by looking at the directory $JBOSS_HOME/server. All the subdirectories under this directory are the server configurations that are available by default. We will call the server configuration as $RUN from now on.
  5. SipExchange is setup to serve all the web pages using SSL so that the information remains secure. Modify Jboss servlet container configuration to setup SSL, follow the steps below:
    1. Open the file $JBOSS_HOME/server/$RUN/deploy/jboss-web.deployer/server.xml using a text editor of your choice.  Search for a XML code segment which looks like the following:

      <Connector port=”8443″ protocol=”HTTP/1.1″ SSLEnabled=”true”
      maxThreads=”150″ scheme=”https” secure=”true”
      clientAuth=”false” sslProtocol=”TLS” />

    2. Make sure that the code segment is commented out as shown above. The start of the comment and the end of the comment are shown in bold characters above. If the segment is not commented out, comment out the segment by placing the start and end of the comments as shown above.
    3. Just above the code segment, add the following code segment:

      <!– SSL/TLS Connector configuration using the cafesip keystore –>
            <Connector port=”8443″ protocol=”HTTP/1.1″ SSLEnabled=”true”
      maxThreads=”150″ scheme=”https” secure=”true”
      clientAuth=”false” sslProtocol=”TLS”
      keystorePass=”a1b2c3d4″ />

    4. Copy the file $SIPEXCHANGE_HOME/conf/runtime/cafesip.keystore to $JBOSS_HOME/server/$RUN/conf directory. This is the last step for setting up SSL. We recommend that you use your own SSL certificate instead of the cafesip.keystore file supplied with SipExchange. To use your own certificates, you can replace this file with your own SSL keystore and make sure that you have changed the parameters in server.xml (see previous step) accordingly.
  6. The final step is to setup the Jboss servlet container to use single sign-on. To enable sigle sign-on, edit the file – $JBOSS_HOME/server/$RUN/deploy/jboss-web.deployer/server.xml  (same as the one that you use above for setting up SSL). Search for the phrase – SingleSignOn. You will find a commented out block like the one shown below. Just uncomment it and save the file.

    <Valve className=”org.apache.catalina.authenticator.SingleSignOn” />

Run the SipExchange installer

Please execute the steps below:

  1. Shutdown Jboss, if it is running.
  2. Make sure that the MySQL server is running.
  3. If you are running Linux, create an user and group called “jboss” and “jboss” respectively who will own the Jboss process. From a terminal enter the following command:> chown -R jboss.jboss $JBOSS_HOME # replace $JBOSS_HOME with the location where Jboss is installed
  4. Open a command-line terminal (Windows command prompt or a Linux terminal).
  5. On Windows, execute the following commands:> CD $SIPEXCHANGE_HOME    #  replace $SIPEXCHANGE _HOME with the full path name where you extracted sipexchange.
    > SET JAVA_HOME=$JAVA_HOME # replace $JAVA_HOME with the location where JAVA is installed
    > SET JBOSS_HOME=$JBOSS_HOME  # replace $JBOSS_HOME with the full path name where Jboss is installed
    > SET ANT_OPTS=-Xmx512M
    > $ANT_HOME\bin\ant -f install.ant install  # release $ANT_HOME with the full path name where ant is installed
  6. On Linux, login as the root userexecute the following commands:> CD $SIPEXCHANGE_HOME    #  replace $SIPEXCHANGE _HOME with the full path name where you extracted sipexchange.
    > export JAVA_HOME=$JAVA_HOME # replace $JAVA_HOME with the location where JAVA is installed
    > export JBOSS_HOME=$JBOSS_HOME # replace $JBOSS_HOME with the full path name where Jboss is installed
    > export ANT_OPTS=-Xmx512M
    > $ANT_HOME/bin/ant -f install.ant install  # release $ANT_HOME with the full path name where ant is installed
  7. The system will prompt you to enter a series of information. Note that in many cases, the default value is is place within square brackets. For example:   MySQL host [localhost]If you want to accept the default value, please hit return. Enter the correct values. If you made a mistake, abort the installation by entering CTRL-C and re-running the Ant command again. During this prompting sequence, you may see an SQL exception when we are trying to check if a database exists – that is harmless and you can ignore it.
  8. After you have entered all the information the installer needs, it will setup SipExchange. If there are errors, it will be indicated in the installer output that you will see on the screen.
  9. Start the Jboss server. At this point, the SipExchange application must up and running. You can see the log messages generated by Jboss to see if the server encountered any problems while starting up.

Common problems

After the installation, SipExchange should be fully operational but here are some of the problems that have been reported by our testers and by users.

The SIP phones do not connect to the SipExchange server: This may be caused because of various reasons:

  1. You have not setup the domains and the users properly. Please see the post-installations steps below.
  2. The phones have not been configured properly. Make sure that the registration and proxy server IP address/host name is set to that of the SipExchange server.
  3. When SipExchange is installed on a system with multiple IP addresses, by default, SipExchange picks the first IP address of the system. The phone may not be communicating through the IP address SipExchange picks. To fix this, you need to shutdown Jboss, open the file $JBOSS_HOME/server/$RUN/conf/jiplet/server.xml and add additional IP addresses and ports that you want to open for communications. The document comments explains how to do this.

The email notifications are not working: This may be caused by various reasons:

  1. The email server information you provided during the installation may not be correct. Just run the installation again to fix this.
  2. The email server is rejecting the mails from SipExchange because of security and spam filters. Talk to your system administrator or email service provider to fix this issue.
  3. The SipExchange installer assumes that the email server (SMTP server), you are using uses secure connections. If that is not the case, you may have to manually edit the email properties. Open the file – $JBOSS_HOME/server/$RUN/deploy/sipexchange-mail-service.xml and edit the parameters appropriately. Restart Jboss. To verify that the mail service is working properly, create a subscriber account from SipExchange Console and verify that the subscriber receives an email.

Users cannot hear each other talk: This may be caused because of the following reasons:

  1. The SIP phones you are using are not compatible with SipExchange. We have tested with a limited sets of SIP phones and there are many others that we have not tested with or could not make them to work with SipExchange. We have found that a number of SIP phones do not follow SIP standards and some of them use extensions that SipExchange does not currently support. For a list of SIP phones that we tested with, click here.
  2. A network firewall may be blocking the ports used for the voice communication (payload). Please contact your system administrator to unblock ports used by SIP and the ports used by your SIP phone.  If you are trying to setup SipExchange to send and receive calls on the Internet, there needs to be substantial configuration including setting up of STUN servers. There is quite a bit of information on the web on this topic.

Post-installation configuration and SIP phone setup

The next step is to configure the SipExchange application. You will have to create a domain and subscribers for the domain to get started. Please read the administration howto for details.

The final step is to set up your SIP phones. For any SIP phone, setup the host name/IP address of the SipExchange server as the proxy name and the name of the registrar. Also setup the domain name, subscriber name and password (if required) following the procedures laid out by the SIP phone. Click here to read more about the SIP soft phones that have been tested with SipExchange and how to set them up.

As discussed earlier, the SipExchange application uses the Jiplet Container for SIP message handling. You may need to make some modifications to the settings for it to work for your environment. In particular,  check the following:

  1. Check/modify the default SIP connector settings used by the jiplet container as described here.
  2. Open up the ports used by the jiplet container and be sure to take proper security measures.
  3. If SipExchange is running on a server that is accessible from the Internet, please make sure that you have done the following:
    1. Using firewall settings, disable access to the JNDI port (1099) from the Internet.
    2. Using firewall settings, disable access to MySQL port (3306) from the Internet.
    3. Make sure that the web services provided by SipExchange is not available from the Internet (unless you want to).
    4. Change the default admin password.
VN:R_U [1.9.20_1166]
Rating: 0.0/10 (0 votes cast)

Leave a Reply