Installation

• Conventions followed in this document
• Hardware requirements
• Pre-requisite software
• SipExchange installation
• Installing the base software
• Installing SipExchange
• 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): 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

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 the base software

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

Prepare the JBOSS server

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

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 plan to use a different type of database server

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

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.

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.

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