In order to understand how to configure the Jiplet Container, you must read the entire howto sequentially, not just the topics you need to know more about. This is because one topic may refer to a previous topic.
- What kind of conventions are followed by this howto documentation?
- What are the parameters I can configure on the Jiplet Container?
- Do I need the Jiplet Console application?
- How do I use more advanced authentication mechanisms like LDAP, etc. for the jiplet console?
- How do I access the jiplet console?
- How do I setup the system administrator accounts for the jiplet console?
- How do I add a new context using the jiplet console?
- How do I install a new context WITHOUT using the jiplet console?
- How do I install a new context in the JBOSS environment?
- How do I manage connectors?
- How do I configure relams?
- How do I configure the JDBC realm?
- How do I switch to a different database for the JDBC realm?
- How do I tune my log messages coming out of the jiplet container?
- How do I use the Jiplet Container JMX interface?
- What about more advanced configurations not listed in this howto?
- We have used the term “directory” for specify a file location. This is a common Unix convention. In the Windows environment, the term “folder” is used to mean the same thing.
- 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.
- We have used $JIPLET_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 $JIPLET_HOME has been used to specify the directory where the jiplet container code binary is installed. We have commonly used the following variables:
- $JAVA_HOME – directory where the Java Runtime Environment (JRE) is installed.
- $JIPLET_HOME – directory where the Jiplet Container software is installed.
- $JBOSS_HOME – directory where JBOSS is installed.
- $TOMCAT_HOME – directory where Tomcat is installed.
- $HOST – host name/IP address of the system where the jiplet container is installed.
- $RUN – the JBOSS run mode (default, minimal, all, etc.)
- 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:\>” is shown, do not enter them.
The jiplet container provides complete flexibility in how you can configure the system. In order to modify the system configuration, you may have to adopt multiple means. There are multiple ways you can change the configuration of the system. Which method you choose will depend on what you want to do. The following are some of the ways you can change the system configuration:
- By using the Jiplet Console web-based user interface: You can deploy and undeploy jiplet contexts, view the properties of the connectors, contexts, realms and the jiplets as well as manage realms from a web-based user interface. Other capabilities may be added in future releases.
- By modifying the jiplet configuration files: The jiplet container configuration files are located in $JIPLET_HOME/conf directory. You can configure connectors and log properties by modifying these files.
- By using the JBOSS management user interface and JMX console: If you are running the jiplet container as a JBOSS service, you can start and stop the jiplet container service and the Jiplet console web application without re-starting the jiplet container.
- There are a number of JBOSS configuration files that you can modify to tune various aspects of the JBOSS configuration including logging and tracing. This is only applicable if you are running the jiplet container as a JBOSS service.
We recommend it but it is not necessary. If you do not install the Jiplet Console, you lose some of the features offered by the jiplet container. Namely:
- The ability to view the properties of the connectors, realms and jiplet contexts.
- The ability to upload and deploy jiplet contexts and realms remotely.
- For the standalone environment, the ability to deploy and undeploy jiplet contexts and realms without re-starting the jiplet container.
- The ability to administer user accounts for the realms (that support user account management).
If you think that you won’t need the above capabilties, you may not want to install the jiplet console.
The jiplet console allows only authorized users to access the system.
If you are running the standalone jiplet container and have installed the jiplet console as a Tomcat webapp, modify the file $TOMCAT_HOME/conf/tomcat-users.xml where $TOMCAT_HOME is the directory where Tomcat is installed. Add a role called “admin” if it does not exist already and add one or more users.
To add the role, add a new XML element as shown below:
Below that, add a user by adding an XML element like the one shown below:
You have created a system administrator account with user name “adminuser” and password “changeme”. You can enter multiple users this way. After entering, you will have to re-start Tomcat.
If you are not using Tomcat, you will have to do something similar.
If you are running the jiplet container as a JBOSS service, you will have to modify/create two files:
- $JBOSS_HOME/server/$RUN/conf/roles.properties: Add a line that looks like:adminuser=adminThis creates a user called “adminuser” with sysadmin privilege.
- $JBOSS_HOME/server/$RUN/conf/users.properties: Add a line that looks like:adminuser=changemeThis creates the adminuser with password “changeme”.
You will have to re-start JBOSS.
Now you are ready to login to the jiplet console.
It is possible to configure more advanced authetication including LDAP, JAAS, etc. You will have to read the JBOSS/Tomcat documentation for details.
You can access the jiplet console using any modern web browser from the following URL:
where $HOST is the host name/IP address of the system where you have installed the jiplet console application. When prompted for the user name and password, enter the user name and password you configured as described in the step above.
The rest of the web-based user interface is pretty intutive. Use the navigation bar to the left of the screen to get help on topics and, in particular, use the “Context” menu to view the list of contexts, add new contexts, remove contexts and view context and jiplet properties.
The “Logout” hyperlink does not work as desired (not really our fault?). Close the browser instead.
After you log into the jiplet console, use the “Contexts” menu to view the list of contexts. Click the “+” hyperlink to get to the “Add context” screen. You need to have the jiplet application binaries with you. A jiplet binary may come in two forms:
- As a SPR file: This is a single file with a “.spr” extension. It is a ZIP file that contains all the classes and the jiplet descriptor.
- As an “exploded” directory: a directory containing all the class files and the jiplet descriptor.
If you have the exploded directory, copy the directory into the server in a temporary directory. From the jiplet console, enter the directory location on the server. You can optionally provide a name. If you do not specify a name, the directory name is used instead.
If you have a SPR file, you can copy the file into a server temporary directory and install the jiplet using the same procedure as the exploded directory. Alternatively, you can upload the file to the server from the local machine where you are running the browser.
In addition to deployment of the context from the jiplet console, you can also override the context mapping while installing the jiplet context. As explained in the Jiplet Developer Guide, each jiplet contains a deployment descriptor where, among other things, you can specify the mapping that the jiplet container uses to route SIP request messages to the context. That is, when a SIP request message is received, the jiplet container looks up the context mapping to determine which context gets to handle the message. Sometimes it is required to override the context mapping at install time and the jiplet console allows you to do that. This feature also allows a service provider hosting jiplet applications from multiple vendors to set the mapping for each vendor. For example, the service provider can specify that vendor x.org can only receive SIP request messages for x.org.
To verify that the jiplet context is installed successfully, view the contexts list and you should see the new jiplet context in the list. You will also be able to access the properties of the context as well as the jiplets in the context.
To remove the jiplet context, use the jiplet console to remove the context.
If you have not installed the jiplet console and would like to install a new context, you can do it by installing the SPR file or the exploded directory (see above) into the “deploy” directory of the jiplet container and re-starting the jiplet container. The deploy directory is located under the $JIPLET_HOME directory.
To remove the jiplet context, delete the SPR file and the exploded directory. If you installed a SPR, the jiplet container will explode the spr file under the deploy directory. You will need to remove both the SPR file and the exploded directory. Restart the jiplet container for the change to take effect.
Note: If you are running the jiplet container as a JBOSS service, and have a SPR file, we do not recommend using this method (although it may still work). You may want to deploy the SPR file using the JBOSS deployment mechanism as described here.
JBOSS supports deployment of JBOSS componets by copying zipped application files into the JBOSS deployment directory. The jiplet container comes with a custom deployer that can install jiplet contexts with the “.spr” extenstion. To install a jiplet context, simply copy the context SPR file into $JBOSS_HOME/server/$RUN/deploy directory. To undeploy, delete the SPR file from the same directory.
Note that you can use the jiplet console to deploy the SPR file instead of using this method. The jiplet console will copy the SPR file into JBOSS’s deployment directory as explained above.
SIP connectors define addresses and ports, or listening points, that the jiplet container uses to receive and send SIP messages. When you install the jiplet container, it comes with a single connector having two listening points:
- TCP port 5060
- UDP port 5060
These listening points use the host address of the machine running the jiplet container. If you need to configure additional ports, IP addresses, or multiple connectors, you will need to modify the file server.xml. For the standalone jiplet container, this file is located in the directory $JIPLET_HOME/conf. When running as a JBOSS service, the file is located in the $JBOSS_HOME/server/$RUN/conf/jiplet directory. Modify the file and re-start the container. The file contains detailed information in the form of XML comments that explain the parameters. Please read it carefully and make appropriate changes. Here is a sample server.xml file. You can view the properties of the connectors from the jiplet console.
Realms allow you to define authentication and authrozation databases for using with your system. The default factory setting enables the memory realm (see the installaton howto for more details). But you can also enable multiple instances of the memory realms as well as add new types of realms – namely, the JDBC realm. In addition, you can define your custom authentication mechanism but that requires some amount of software development on your part. Please refer to the jiplet advanced developer guide if you need to create your custom realm. The realms are configured in the server.xml file. Please read the comments in this file and make appropriate changes as necessary.
By default, the JDBC realm is not enabled. To use the default setting, you will have to download the MySQL database from thier MySQL web site. You will also have to uncomment the section in the server.xml file to enable it. Before you do that, make sure that all the parameters are configured correctly. The factory default setting uses the “test” database (see the jdbc-url parameter). The test database is a scratch database area where users can create tables, read, write, etc. Many MySQL installations do not setup the test database for security reasons. So, you may have to choose a different database. For MySQL, to create user accounts and database, you can login to a mysql client using the root account and run the following commands:
use mysql; GRANT ALL PRIVILEGES ON newdb.* TO user@localhost IDENTIFIED BY 'a1b2c3d4'; GRANT ALL PRIVILEGES ON newdb.* TO firstname.lastname@example.org IDENTIFIED BY 'a1b2c3d4'; GRANT ALL PRIVILEGES ON newdb.* TO user@'%' IDENTIFIED BY 'a1b2c3d4'; create database newdb;
where newdb is the name of the database, user is the user name and a1b2c3d4 is the password for the user. Make sure that you have entered these values in the server.xml file.
The JDBC realm stores the authentication and authorization information into a SQL database. The default factory configuration assumes that you are using a MySQL database. It is possible to switch to a different database.
Java programs access a SQL database using a JDBC connection. For most popular database, there are JDBC drivers available that you can use to connect to the database server. The JDBC driver for MySQL is included with the jiplet container. For other databases, you will have to download it from the database vendor’s web site. The driver will be typically packaged in a “jar” file (a file with a .jar extension). Once you have this file, perform the following steps:
- Copy the JDBC driver jar file into the $JIPLET_HOME/common/lib directory if you are running the standalone jiplet container.
- Copy the JDBC driver file to the $JIPLET_HOME directory if you are running the jiplet container as a JBOSS service.
- Modify the server.xml file. Modify the jdbc-driver parameter and specify a new class name. This name will be provided to you by your database vendor. You need to have this name entered correctly for it to work.
- Modify the jdbc-url parameter to use the appropriate schema (jdbc:mysql for MySQL). This information will be provided by your database vendor. You will also need to modify the database name (test by default).
- Modify the jdbc-user and jdbc-password parameters to specify the database user name and password. Make sure that the user has the proper privileges to add tables, insert, select, delete and update. Contact your database administrator for details.
- Re-start the jiplet container for the changes to take effect.
- If you get database access-related errors, please contact your database administrator.
That will depend on the type of realm you are using.
The JDBC realm supports the provisioning of the realm from external management systems. The external management can use the exposed JMX methods to add, modify and remove users. The jiplet console uses this interface to provide screens that allow you to list the realms, and add, modify and remove user accounts. To use the jiplet console, select a realm from the navigation tree on the left hand side of the screen and select the option to administer user accounts. If you want to use your own program to directly manipulate the underlying SQL tables, here is the table schema. Note: the table is created by the jiplet container, first time it starts up.
create table users ( user_name varchar(15) not null primary key, user_pass varchar(15) not null ); create table user_roles ( user_name varchar(15) not null, role_name varchar(15) not null, primary key (user_name, role_name) );
For the memory realm, you will need to modify the file where the account information is stored in the file jiplet-users.xml. For the standalone jiplet container, you will find this file in the directory $JIPLET_HOME/conf directory. When running as a JBOSS service, you will find this file in the directory $JBOSS_HOME/server/$RUN/conf/jiplet directory. Please read the comments on this file to understand how to add roles and user information.
The standalone jiplet container uses LOG4J for printing log messages. LOG4J is a very popular open-source mechanism for printing and controlling log messages. The log configuration file is located in the $JIPLET_HOME/conf directory and is called log4j.xml. Edit the file to make necessary changes. For more details on the structure of the configuration file, please refer to the LOG4J web site. By default, the logs are stored in the $JIPLET_HOME/logs directory – one log file for every day. You can do more fancy things like sending an email on error messages, etc. by adding your own appenders and invoking other appenders included with LOG4J. Note: The jiplet container does not delete old logs automatically. Please delete them periodically manually or by using a scheduled job.
If you are using the JBOSS service, the logging is controlled by the JBOSS log service. JBOSS also uses LOG4J for managing logs. To customize logs, modify the file $JBOSS_HOME/server/$RUN/conf/log4j.xml file.
The jiplet container provides a JMX interface using which management applications can manage the jiplet container. The jiplet console uses this interface to communicate with the jiplet container process. You can use the same interface to manage the jiplet. However, there is really no reason to use the JMX interface as far as end-users are concerned. Instead you can use the more user-friendly jiplet console web-based management interface. The only reason that we see why you want to use the JMX interface is to trouble-shoot problems related to the jiplet console. The JMX interface operates on the following communication adaptors:
- JMX/RMI interface on TCP/IP port 9999: When running as the standalone jiplet container, the container uses the MX4J JMX implementation. You can use the MX4J JMX client classes to communicate through this interface. You can also use the JMX management client provided by MX4J to view the MBEANs and invoke operations. If you do not want to use this interface and would like the standalone jiplet container to not start them, you can modify the startup scripts $JIPLET_HOME/bin/jiplet (Linux) or $JIPLET_HOME/bin/jiplet.bat (Windows) . Search for “-Djiplet.jmx.enabled=true” and change it to “-Djiplet.jmx.enabled=false“. Restart the container.
- JMX/RMI interface for JBOSS: When running as a JBOSS service, the jiplet container uses the JBOSS JMX implementation. You can use JBOSS JMX client libraries to communicate through this interface. You can also use the JBOSS JMX console to view the MBEANS and invoke operations.
Here are some of the things you can do that are not described in the howto:
- Create your own the custom startup scripts.
- Use a different JAIN-SIP stack.
- Use a custom LOG4J appender.
- Use a different JMX implementation.
- Use servlet containers other than Tomcat to host the jiplet-console.
- Using Java security to fine-tune access to system resources.
Since the jiplet container is open-source, you will be able to read the code to figure out how to do it. If you need help, visit the Jiplet support page to get additional help.