Look what Java and SIP can do
 (SIP)Java =
Home     News     Projects     Downloads     Support     Contact
SipExchange Home

SipExchange Overview

Terminologies

SipExchange Administration

SIP Phone Interoperability

Installation

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): The software has been tested with J2SDK version 1.6.0. The software will not work with Java 1.4. You can download this software from Sun's java site - http://www.java.com.
  2. JBOSS Application Server: Download and install JBOSS 4.0.5. You can download the software from http://www.jboss.org. If you try it using a later version of JBOSS like 4.2.x, you will run into some incompatibilities - see this page for more details. In a near future release, SipExchange will have support for the later JBOSS version.
  3. MYSQL server: SipExchange uses MySQL as a persistence layer for most application data. Therefore, you also need MYSQL server to be installed on the server. Download and install MYSQL 5.0 or above.  Download the software from the MySQL web site.

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.

Important Notes:

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 a previous version of SipExchange installed on your system, you must remove it first. The SipExchange software is currently in its early stages of development and we currently do not support upgrades from a previous version. 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> 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 the base software

Before you can install SipExchange, you must install the pre-requisite software discussed above.
  1. The J2SDK software comes with its own installers. Install the software as per the instruction on the Sun's web site.  We recommend that you install the software directly under the C:\ drive on Windows or /usr/java directory under Linux (Linux installers using RPM may not get a choice). Basically, the path where Java is installed must not have any blank spaces like "C:\Program Files\java". We will refer to this directory as $JAVA_HOME.
  2. Installing JBOSS server typically involves unpacking the JBOSS distribution into a directory. Please read the instructions outlined in the JBOSS web site for more details. We recommend that you install it under the C:\ on Windows and /usr/java directory under Linux. We will refer to this directory as $JBOSS_HOME. Follow the steps outlined in the JBOSS documentation that describe how to install JBOSS as a Linux or Windows service so that it gets started up when the system starts up. While running JBOSS, make sure that the JBOSS server uses the Java you just installed.
  3. The MySQL server already comes with an installer. Run the installer as per the instructions provided by the MySQL web site. Install MYSQL as a Windows or Linux service so that it gets started up when the system starts up. 

Installing SipExchange

Download and unpack SipExchange
After you have installed the base software, the next step is to install the SipExchange software itself. Download the binary version of the software from the CafeSip.org download site. 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. Select the server that you want to run. By default, 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 typically use the "default" configuration which includes all the necessary configurations we need. but you can use a different one if you like. If you use a different server configuration, please make sure that  the server configuration includes a web container (tomcat), EJB container and a web services container.  You can start up a JBOSS server configuration by running the command  $JBOSS_HOME/bin/run -c server (this is for Linux, for Windows: replace the "/" with "\") where server is the name of the configuration. Read the JBOSS documentation in order to understand how to startup a particular server configuration. We will call the server configuration as $RUN from now on.
  3. Modify the order in which JBOSS deploys modules as per the instructions in the jiplet container documentation. Please follow all the steps except the last 2 steps.
  4. Create administrator accounts so that you can view and administer the Jiplet Container embedded in the SipExchange. Follow the same steps outlined in the jiplet container configuration howto for JBOSS as described here. If your system is administered by multiple users, please assign an user id for each one of them. The Jiplet Container logs the system administrator actions in the log file for you to audit their actions at a later time.
  5. Install the SipExchange authentication realm so that the web applications installed as a part of SipExchange can authenticate the subscribers and administrators. To  install the realm,  open the file $JBOSS_HOME/server/$RUN/conf/login-config.xml with a text editor. Add the following XML segment at the end of the file. Save the changes.

    <application-policy name = "sipex">
           <authentication>
              <login-module code = "org.cafesip.sipexchange.realms.web.SipexWebLoginModule"
                 flag = "required">
            <module-option name = "subscriber.jndi.location">ejb/SipExchange/SubscriberService</module-option>
                <module-option name = "admin.jndi.location">ejb/SipExchange/AdminService</module-option>
              </login-module>
           </authentication>
        </application-policy>


  6. Modify JBOSS configuration so that the SipExchange web applications can use SSL (HTTPS) for secure access. To setup SSL, follow the steps below:
    1. Open the file $JBOSS_HOME/server/$RUN/deploy/jbossweb-tomcat55.war/server.xml using a text editor of your choice.  Search for a XML code segment which looks like the following:

      <!-- SSL/TLS Connector configuration using the admin devl guide keystore
            <Connector port="8443" address="${jboss.bind.address}"
                 maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
                 emptySessionPath="true"
                 scheme="https" secure="true" clientAuth="false"
                 keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"
                 keystorePass="rmi+ssl" 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" address="${jboss.bind.address}"
                 maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
                 scheme="https" secure="true" clientAuth="false"
                 keystoreFile="${jboss.server.home.dir}/conf/cafesip.keystore"
                 keystorePass="a1b2c3d4" sslProtocol = "TLS" />

    4. Copy the file $SIPEXCHANGE_HOME/setup/cafesip.keystore to $JBOSS_HOME/server/$RUN/conf directory. This is the last step for setting up SSL. If you like to use your own SSL keystore instead of the cafesip.keystore file supplied with SipExchange, then 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.
  7. Finally, set up a mail service so that SipExchange application can send emails. You will need to know the SMTP server name to which the SipExchange relays all the emails to. If your SMTP server requires an user name and password, you need to obtain these. Please contact your system administrator for this information if you don't have it. Once you have obtained the information, follow the steps below:
    1. Open the file $SIPEXCHANGE_HOME/deployment/sipexchange-mail-service.xml using a text editor of your choice.
    2. Search for the code segment that looks like

                <property name="mail.smtp.host" value="SMTP.SERVER.ADDRESS"/>

      Replace the SMTP.SERVER>ADDRESS text with the real SMTP server address you are using.
    3. Search for the code segment that looks like

              <property name="mail.from" value="MYEMAIL@MYDOMAIN"/>

      Replace the MYEMAIL@MYDOMAIN text with a real email address of the system administrator (yours?).
    4. If your SMTP server requires authentication, search for the code segment that looks like

             <attribute name="User">nobody</attribute>
             <attribute name="Password">password</attribute>

      Replace the nobody with the user name and password with the real password.
Prepare the database
Follow the steps outlined below:
  1. The MYSQL server must be up and running before you can use SipExchange. Make sure that the MySQL server is started up and running.
  2. If you have not assigned a MySQL root password, assign one now. To assign the password, you will have to run the mysqladmin utility from a DOS prompt (Windows) or a shell (Linux). If the MySQL binaries are not in your PATH, you can set the PATH variable to include the path $MYSQL_HOME/bin where $MYSQL_HOME is the directory where MySQL is installed. Setting the PATH environment variable varies from system to system and, on Linux, also depends on the shell that you have installed. If you don't want to set the path variable, use the full path name for the command below:

               $ mysqladmin -u root password root_password

    where "root_password" is the password you want to set for the MySQL super-user.
  3. The next step is to install the Sipexchange database, users and schema.  Run the following script from the command line:

              $ mysql -u root -p < $SIPEXCHANGE_HOME\setup\init-db.sql
              Password:

    When the utility prompts you for the password, enter the root password. The command should complete without any error messages.
  4. Copy the file $SIPEXCHANGE_HOME/lib/mysql-connector-java-$VERSION.jar to $JBOSS_HOME/server/$RUN/lib directory. Replace the $VERSION with the version number that you have in the directory.
  5. Finally, if your server is directly connected to the Internet, please make sure that the MySQL server is not accessible from the outside world. Configure your router or firewall to block off access to port 3306 from the Internet.
If the database is running on a different host
If you have an existing MySQL database server that you would like to use and it is located in a different server, run steps 2 and 3 on the database server. Also, edit the file $SIPEXCHANGE_HOME/deployment/sipex-ds.xml and search for the code segment that looks like:

        <connection-url>jdbc:mysql://localhost/sipex</connection-url>

Replace the 'localhost' text with the server name where the database is running.
If you plan to use a different type of database server
If you plan to use some other database rather than MySQL, perform the following steps:
  1. Copy the JDBC driver provided by the database vendor to the same JOBSS lib directory specified in the database preparation section above. 
  2. Using the database access application (client) provided by the database vendor, create a database called sipex, an user called sipex with password a1b2c3d4 (you can change this if you like).
  3. Open the file $SIPEXCHANGE_HOME\setup\init-db.sql and examine the code that creates the database tables. Convert the DDL statements into DDL statements that are compatible with the database of your choice. Note that this requires a very good understanding of SQL/DDL languages.
  4. Edit the file $SIPEXCHANGE_HOME/deployment/sipex-ds.xml. Change the connection-url and other database parameters as needed.
Deploying SipExchange on JBOSS
Please execute the steps below:
  1. Copy the files sipex-auth.jar and sipex-subscriber-client.jar from the $SIPEXCHANGE_HOME/lib directory to the $JBOSS_HOME/server/$RUN/lib directory.
  2. Copy all the files in the directory $SIPEXCHANGE_HOME/deployment to the directory $JBOSS_HOME/server/$RUN/deploy
  3. Start JBOSS server using the instructions provided by the JBOSS documentation.
At this point, the SipExchange application is up and running. You can see the log messages generated by JBOSS to see if the server encountered any problems while starting up.

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


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