Do I need the Jiplet Console application?
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:

1. The ability to view the properties of the connectors, realms and jiplet contexts.
2. The ability to upload and deploy jiplet contexts and realms remotely.
3. For the standalone environment, the ability to deploy and undeploy jiplet contexts and realms without re-starting the jiplet container.
4. 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.


How do I setup the system administrator accounts for 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:

1. $JBOSS_HOME/server/$RUN/conf/roles.properties: Add a line that looks like:
   
   adminuser=admin
   
   This creates a user called "adminuser" with sysadmin privilege.
   
2. $JBOSS_HOME/server/$RUN/conf/users.properties: Add a line that looks like:
   
   adminuser=changeme
   
   This creates the adminuser with password "changeme".

You will have to re-start JBOSS (??).

Now you are ready to login to the jiplet console.


How do I use more advanced authentication mechanisms like LDAP, etc. for the jiplet console?

How do I access the jiplet console?
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.


How do I add a new context using the jiplet console?
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:

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



How do I install a new context WITHOUT using the jiplet console?
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.


How do I install a new context in the JBOSS environment?
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.

If you have a new context in exploded form, you may want to use one of the two methods described above (1, 2).

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.


How do I manage connectors?
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:

1. TCP port 5060
   
2. 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.

How do I add users and roles into a realm?
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.


How do I tune my log messages coming out of the jiplet container?
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.