Understanding WSO2 Tungsten Configuration Files

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Afkham Azeez
  • 11 Jul, 2006

Introduction

WSO2 Tungsten (henceforth known as Tungsten) contains a number of configuration files. It is important to understand the purposes and usages of these files in order to effectively use Tungsten as well as change the default configurations to suit specific user needs. Also, some of the configuration files should be modified only by advanced users who have an in-depth knowledge of how Tungsten works, while some other config files can be easily modified by any user. This article will take a detailed look at all of these aspects.

Abbreviations

    AAR - Axis2 ARchive HTML - HyperText Markup Language JAR - Java ARchive JSP - JavaServer Pages JNDI - Java Naming & Directory Interface MAR - Module ARchive MIME - Multipurpose Internet Mail Extensions POJO - Plain Old Java Object RDBMS - Relational DataBase Management System SOAP - Simple Object Access Protocol SQL - Structured Query Language SSL - Secure Socket Layer UI - User Interface XML - eXtensible Markup Language

Location of the Configuration Files

Standalone Distribution

In this distribution, the configuration files are located in the TUNGSTEN_HOME/conf directory. TUNGSTEN_HOME will be the directory to which the tungsten archive was extracted. In this distribution, the TUNGSTEN_HOME/conf directory is added to the Tungsten classpath, so that some of the files can be picked up from the classpath, as well as it can be edited by the user easily since they are not contained within an archive.

Embeddable Distribution

In this distribution, the configuration files are located in the TUNGSTEN_HOME/conf directory. TUNGSTEN_HOME will be the directory you specified during the installation of Tungsten Embeddable distribution. The TUNGSTEN_HOME can be changed by editing the "tungsten.home" property found in the tungsten.war/WEB-INF/classes/tungsten.properties file. In addition to the configuration files located in TUNGSTEN_HOME/conf, some configuration files are also located in tungsten.war/WEB-INF/classes. These files are:

  • hibernate.cfg.xml
  • tungsten.hbm.xml
  • log4j.properties
  • ui-extensions-config.xml

What are these files used for?

In this section, we will look at what each of the files found in the TUNGSTEN_HOME/conf directory are used for and how the default settings in each of the files can be changed.

tungsten.xml

This is the main configuration file of Tungsten. In this section, we will take a detailed look at the elements of more importance in this file. This file can also be specified using the tungsten.xml System property.

Axis2 Configurations

This section defines the Apache Axis2 modules and services repository, as well as the modules that should be globally engaged. When Tungsten is started up for the first time, the names of the globally engaged modules are persisted in the database, and thereafter, for any existing module, global engagement will be driven by the configuration in the database. However, if you add a new module by directly copying it to the Axis2 modules repository, you could add a global engagement entry to this file. The relevant XML segment is shown below.

  
<!--
Axis2 related configurations
-->
<Axis2Config>
<!--
Location of the Axis2 Services & Modules repository
-->
<RepositoryLocation>repository</RepositoryLocation>

<!--
Modules which should be globally engaged
-->
<GloballyEngage>
<Module>addressing</Module>
<Module>StatisticsAggregator</Module>
<Module>MessageMonitor</Module>
</GloballyEngage>
</Axis2Config>

Tungsten Management Console Web Application

In the case of the standalone distribution, this section is is used for configuring the Tungsten Management Console Web Application context path mapping to the resource base. These values are required for configuring the embedded Jetty servlet container. In the case of the embeddable distribution, only the "ContextPath" element is available. If the user changes the "ContextPath" in the case of the embeddable distribution, he should also make the necessary changes in the Application server to reflect this change, and vice versa. The relevant XML segment is shown below.

    
<!-- ************************************************* -->
<!--Configuration directly related to Tungsten Web App -->
<!-- ************************************************* -->
<AdminWeb>
<!--Tungsten admin will be accessed via the context path given
below -->
<ContextPath>/</ContextPath>

<!--This is where the admin web pages are maintained-->
<ResourceBase>lib/www</ResourceBase>
</AdminWeb>

Web Client for Services

Apache Axis2 supports the concept of a self contained AAR. This means, an AAR can contain Web clients written using JSP, HTML and JavaScripts. The Web contents within an AAR are copied to the ResourceBase location defined in this section, and will be accessible relative to the ContextPath defined here. The Chad sample that ships with Tungsten demonstrates how this works. E.g.: The Chad Web UI is accessed via the URL http://localhost:9762/wservices/Chad. The relevant XML segment is shown below.

   
<!-- ************************************************* -->
<!-- web content in an AAR will be copied to this location-->
<!-- ************************************************* -->
<ServiceWeb>
<!--This is where the AAR web pages are maintained-->
<ContextPath>/wservices</ContextPath>
<ResourceBase>lib/extras/wservices</ResourceBase>
</ServiceWeb>

HTTP Settings

The HTTP port can be changed in the standalone distribution using the setting shown below. In the case of the embeddable distribution, the port has to be changed in the Application server.

    
<!--
HTTP settings.
-->
<HTTP>
<Port>9762</Port>
</HTTP>

HTTPS Settings

The HTTPS settings in the standalone distribution should be changed using the configuration in this section. In the case of the embeddable distribution, these changes have to be carried out in the configuration file relevant to the respective Application server.

 

    <!--
HTTPS settings.
-->
<HTTPS>
<Port>9443</Port>
<PoolName>P1</PoolName>
<MaxIdleTimeMs>30000</MaxIdleTimeMs>
<LowResources>30</LowResources>
<LowResourcePersistTimeMs>2000</LowResourcePersistTimeMs>
<Keystore>
<!-- Key store file location-->
<Location>conf/tungsten.jks</Location>
<!-- Key store password-->
<Password>tungsten</Password>
<!-- Private Key alias-->
<KeyAlias>tungsten</KeyAlias>
<!-- Private Key password-->
<KeyPassword>tungsten</KeyPassword>
<!-- Key store type (JKS/PKCS12 etc.)-->
<KeystoreType>JKS</KeystoreType>
</Keystore>
</HTTPS>

Default Admin Account

The default administrative account is created using the following section. It is highly recommended that the user change this password after successfully installing Tungsten. For further information on password management in Tungsten, see the Password Management article

   
<!--
The default admin account which will be created when Tungsten
is started up for the first time.
-->
<DefaultAdmin>
<Username>admin</Username>
<Password>admin</Password>
<Description>Default Administrator</Description>
</DefaultAdmin>

Default User Roles

This section is used for defining the default roles that should be added to the database.

   <!--
The default user roles which will be created when Tungsten
is started up for the first time.
-->
<ServiceUserRoles>
<Role>
<Name>admin</Name>
<Description>Default Administrator Role</Description>
</Role>
<Role>
<Name>user</Name>
<Description>Default User Role</Description>
</Role>
</ServiceUserRoles>

Default Key Store

The default security configurations are defined here. All passwords stored in the database are encrypted, and the following settings are needed for this purpose.

    
<!--
Security configurations
-->
<Security>
<!--
KeyStore which will be used for encrypting/decrypting passwords
and other sensitive information.
-->
<Keystore>
<!-- Key store file location-->
<Location>conf/tungsten.jks</Location>
<!-- Key store password-->
<Password>tungsten</Password>
<!-- Private Key password-->
<KeyPassword>tungsten</KeyPassword>
<!-- Key store type (JKS/PKCS12 etc.)-->
<KeystoreType>JKS</KeystoreType>
</Keystore>

<!--
The directory under which all other KeyStore files will be stored
-->
<KeystoresDir>conf/keystores</KeystoresDir>
</Security>

There are several other configuration elements which were not looked at in this section, but all of those elements are self explanatory, and the user need not modify those sections in most cases. Some of the elements found in the standalone Tungsten distribution's tungsten.xml will be missing in that of the embeddable Tungsten distribution. These have been omitted since they have to be changed in the relevant configuration file of the Application server.

axis2.xml

Axis2 is the SOAP processing framework used by Tungsten. The axis2.xml file is used for configuring the Axis2 framework. This file can also be specified using the axis2.xml System property. For further information regarding configuring Axis2, see the Axis2 Configuration Guide

admin-client-axis2.xml

This is the client side axis2.xml file used by the Tungsten command line Admin client.

mime-mappings.xml

This file maps file extensions to MIME types. If the user intends to upload or download files with MIME types or file extensions not defined in this file, he should add corresponding entries to this file. Modifying this file will not be necessary for most users since it defines mappings for all known MIME types and standard file extensions. The location of this file is defined in the tungsten.xml. The relevant segment in the tungsten.xml file is shown below:

 

    <!--
Pointer to the file which maintains a mapping between file extensions
and MIME Types. You can add new MIME type to file extension mappings
to this file
-->
<MimeMappingsFileLocation>conf/mime-mappings.xml</
MimeMappingsFileLocation>

log4j.properties

Tungsten uses Log4J for the purpose of logging. This log4j.properties file is the standard properties file used for configuring Log4J for Tungsten, and is placed in the Tungsten classpath. This file defines the Log4J Appenders, the logging levels of the Log4J loggers etc. The Log4J appenders used by Tungsten, by default, are:

  • TUNGSTEN_CONSOLE - Appends logging output to the console
  • TUNGSTEN_LOGFILE - Appends logging output to a file
  • TUNGSTEN_MEMORY - Appends logging output to a buffer maintained in main memory

When Tungsten is started up for the first time, the logging configuration read from this file will be used for initializing the relevant database tables. Subsequent changes to this file will not affect the system logging configuration since it will be driven by the settings in the database. Whenever the user wishes to change the logging configuration, it should be carried out using the Tungsten Management Console. The reader should also note that there are several other log4j.properties files in the Tungsten distributions. These files are used by the samples that ship with Tungsten. The main log4j.properties file located in TUNGSTEN_HOME/conf, is used by the Tungsten server, in the case of the standalone distribution, as well as the command line Admin client. In the case of the embeddable distribution, the log4j.properties file used by tungsten.war is located in tungsten.war/WEB-INF/classes. For further information on Log4J configuration see here.

derby.properties

Tungsten ships with an Apache Derby database. An Apache Derby database can be configured using a derby.properties file, which should reside in the directory pointed to by the "derby.system.home" System property. The default derby.properties file that ships with Tungsten contains the following solitary entry:

derby.stream.error.file=../logs/tungsten-derby.log

This Derby property sets the log file to which the output from the Derby RDBMS is written. For further information see here.

 

hibernate.cfg.xml

This is the main configuration file used by the Hibernate framework, and should be placed in the Tungsten classpath. This file defines the database connection settings, database connection pooling configurations, the hibernate mapping files etc. This file could be used for switching RDBMSs without the need for changing any code. For further information on switching to a different RDBMS, see the Changing the Tungsten RDBMS article. For further information about Hibernate, see here.

 

hibernate.cfg.xml for standalone distribution

<hibernate-configuration>
<session-factory>

<!-- Database connection settings -->
<property name="connection.driver_class">org.apache.derby.jdbc.EmbeddedDriver</property>
<property name="connection.url">jdbc:derby:../database/TUNGSTEN_DB;create=true</property>
<property name="connection.username">tungsten</property>
<property name="connection.password">tungsten</property>

<!-- JDBC connection pool (use the built-in) -->
<property name="connection.pool_size">1</property>

<!-- SQL dialect -->
<property name="dialect">org.hibernate.dialect.DerbyDialect</property>

<!-- Echo all executed SQL to stdout -->
<property name="show_sql">false</property>

<mapping resource="tungsten.hbm.xml"/>
</session-factory>
</hibernate-configuration>

hibernate.cfg.xml for embeddable distribution

<hibernate-configuration>
<session-factory>
<!--
Settings to connect to the database via a JNDI datasource
-->
<property name="connection.datasource">java:comp/env/jdbc/tungsten_db</property>
<property name="connection.pool_size">1</property>
<property name="dialect">org.hibernate.dialect.DerbyDialect</property>
<property name="show_sql">false</property>
<mapping resource="tungsten.hbm.xml"/>
</session-factory>
</hibernate-configuration>

When comparing the hibernate.cfg.xml files for the two Tungsten distributions, it is easily noticeable that in the case of the embeddable distribution, the connection to the database is obtained through a JNDI datasource name, which has to be registered in the application server hosting the Tungsten embeddable distribution, whereas in the case of the standalone distribution, all of the database connection parameters are set in the hibernate.cfg.xml file itself. The "dialect" property is used to define the RDBMS (e.g. MySQL, PostgreSQL etc.) of the Tungsten database. The "show_sql" property can be turned on for debugging purposes. When "show_sql" is set to "true", all SQLs will be printed out. This file should be modified if the user wishes to switch to a different database, different RDBMS or change connection pooling settings.

tungsten.hbm.xml

In summary, this file defines the mappings between the POJOs representing data, and the corresponding database tables. It also defines the constraints on and relationships between these POJOs. Modifying this file is not necessary in most of the cases, and should be carried out only by advanced users who have an in-depth understanding of the Tungsten data organization model and a very good understanding of the Hibernate framework. See here for information related to Hibernate mappings.

ui-extensions-config.xml

The Tungsten Management Console uses the WSO2 Management UI Framework, which allow the UI of the Management Console to be easily extended. This framework allows the welcome file of the Management Console to be modified at runtime. The framework will search the welcome file for the tokens defined in this configuration file, and will replace each of the occurrences of a token with the contents of the file to which this token is mapped to. This file will not require modifications in most cases. Only advanced users who wish to customize the Tungsten Management Console User Interface will need to modify this file.

tungsten.jks

This is the default key store file which ships with Tungsten. This file is used for two purposes. viz.:

  1. Encryption and Decryption of passwords stored in the Tungsten database-

    In the tungsten.xml file, the "Security configurations" section defines the key store location, which defaults to this tungsten.jks file. The relevant XML segment in the tungsten.xml is shown below:

         
    <!--
    Security configurations
    -->
    <Security>
    <!--
    KeyStore which will be used for encrypting/decrypting passwords
    and other sensitive information.
    -->
    <Keystore>
    <Location>conf/tungsten.jks</Location>
    ...
    </Keystore>
    ...
    </Security>
  2. HTTPS configuration-

    In the tungsten.xml file, the "HTTPS settings" section defines the key store location, which defaults to this tungsten.jks file. The relevant XML segment in the tungsten.xml file is;

        <!--
    HTTPS settings.
    -->
    <HTTPS>
    ...
    <Keystore>
    <Location>conf/tungsten.jks</Location>
    ...
    </Keystore>
    </HTTPS>

ssl-client-truststore.jks

The Tungsten command line Admin client communicates with the WSO2 Tungsten server via HTTPS. This key store file is used by this command line Admin client as its SSL trust store, by default.

Summary

This article explained the purposes of each of the Tungsten configuration files as well as the configuration changes that can be carried out by an end user of Tungsten.

Author

Afkham Azeez, Product Manager of WSO2 Tungsten & Senior Software Engineer, WSO2 Inc. azeez AT wso2 DOT com

About Author

  • Afkham Azeez
  • VP, Platform Architecture
  • WSO2