Installation

• Conventions followed in this document
• Hardware requirements
• Pre-requisite software
• SipExchange installation
• Installing SipExchange on two servers
  
• Installing Jboss Portal
  
• Installing SipExchange
• Common problems
  
• Post-installation configuration and SIP phone setup

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

Pre-requisite software

1. Java software development kit (J2SDK): Download JDK 1.5 from the Sun web site - http://www.java.com 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 - http://ant.apache.org/bindownload.cgi 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 http://www.jboss.org 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 http://www.jboss.org. 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

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.

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> exit
   
   To run the "mysql" command, make sure that the $MYSQL_HOME/bin is included in the the PATH environment variable as explained below.  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

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> GRANT ALL PRIVILEGES ON *.* TO root@SIPEX_SERVER IDENTIFIED BY 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

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.
   

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.

AvoidMySQL5DataTruncationErrors
   
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.

Installing SipExchange

Download and unpack SipExchange

Prepare the Jboss server

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=256m
   
   You can set these values by adding to the environment variable - JAVA_OPTS specified in the file $JBOSS_HOME/bin/run.bat (or run.sh 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"
                  keystoreFile="${jboss.server.home.dir}/conf/cafesip.keystore"
                  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

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

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.
   

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.

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

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.
   

Search this website 

Send questions or comments about this web site to webmaster@cafesip.org.
Copyright © 2005, CafeSip.org.
Licensed under the CafeSip License.
The CafeSip.org projects, web site and web facilities have been sponsored by QUIK Computing