The conf directory, JBoss v5.x

Configure what you need

So you’re ready to configure some JBoss files? Great, lets have a look at the conf directory. The jboss/server/<configured instance>/conf directory is where you’ll find the majority of the configuration files for your jboss instance. For most deployments, the majority of these folders and files will remain untouched as they default to usable configurations. In this article we’ll go over the more practical configurable files, while leaving the really low level configurations alone.

`-- conf
    |-- bootstrap/
    |--|-- bindingservice.bean
    |   `-- META-INF
    |   |    `-- bindings-jboss-beans.xml *
    |   |-- aop.xml
    |   |-- classloader.xml
    |   |-- deployers.xml
    |   |-- jmx.xml
    |   |-- logging.xml
    |   |-- profile.xml *
    |   `-- vfs.xml
    |-- props
    |   |-- jbossws-roles.properties
    |   |-- jbossws-users.properties
    |   |-- jmx-console-roles.properties
    |   `-- jmx-console-users.properties
    |-- xmdesc
    |   |-- AttributePersistenceService-xmbean.xml
    |   |-- ClientUserTransaction-xmbean.xml
    |   |-- JNDIView-xmbean.xml
    |   |-- Log4jService-xmbean.xml
    |   |-- NamingBean-xmbean.xml
    |   |-- NamingProviderURLWriter-xmbean.xml
    |   `-- NamingService-xmbean.xml
    |-- bootstrap.xml
    |-- jacorb.properties
    |-- java.policy
    |-- jax-ws-catalog.xml
    |-- jboss-log4j.xml
    |-- jboss-service.xml
    |-- jbossjta-properties.xml
    |-- jndi.properties
    |-- login-config.xml
    |-- standardjboss.xml
    `-- standardjbosscmp-jdbc.xml

For starters, the bootstrap.xml file lets you configure which microcontainer deployments are loaded on boot. The ones we want to pay special attention to are profile.xml and conf/bindingservice.beans’s bindings-jboss-beans.xml (marked with an asterisk in the layout diagram) The other files are geared for low level configurations. For example – aop.xml configured how aop is implemented in jboss, deployers.xml configures jboss’ classloaders, and vfs.xml tells jboss what lib folders to load jars from.

External deployments

If you open up profile.xml, you’ll see a set of configurations that describe what kind of deployers are used for the profile object management service. Most of the contents deal with Jboss’ innards, but worthy of reviewing is the “applicationURIs” property. It’s actually a list of java.net.URI urls, and you can add elements to this list in order to configure Jboss so that it looks in to external deployment directories in addition to the defauls deploy directory. More detail is described in the related article “External deploy directories in JBoss 5.1”.

Port Bindings

Before Jboss 5, you would have to manually go in and change each port into its own numberspace. There were a bunch of places where these ports would need to be updated (for things like the naming and rmi services) across a slew of files scattered all over the place. In Jboss 5, if you open up bindings-jboss-beans.xml, you’ll find a means of binding multiple jboss instances across different ports in a single centralized location. Out of the box, Jboss ships with 4 sets of port configurations. Each configuration set reserves a set of ports for JBoss’ use. If you trail through each of these port configurations, you’ll notice the sets are offset by increments of 100. So for example the first configuration reserves 1099 for the NamingServer, while the second set reserves 1199, and the third set uses 1299 and so on. This functionality is particularly useful when you want Jboss to run on a single IP address. Given a choice though, I would opt for using a single IP per Jboss instance. It’s nice to have this option though, in case multiple IPs is not an option.

We can get an idea of how JBoss configures these binding sets from the snippets below – both are straight out of the bindings-jboss-beans.xml file:

<!-- Provides management tools -->
<bean name="ServiceBindingManagementObject" 
  class="org.jboss.services.binding.managed.ServiceBindingManagementObject">

  <constructor>
     <!-- The name of the set of bindings to use for this server -->
     <parameter>${jboss.service.binding.set:ports-default}</parameter>

     <!--  The binding sets -->
     <parameter>
	 <set>
	    <inject bean="PortsDefaultBindings"/>
	    <inject bean="Ports01Bindings"/>
	    <inject bean="Ports02Bindings"/>
	    <inject bean="Ports03Bindings"/>
	 </set>
     </parameter>

     <!-- Base binding metadata used to create bindings for each set -->
     <parameter><inject bean="StandardBindings"/></parameter>

  </constructor>
</bean>

...

<!-- bindings are obtained by taking the base bindings and adding offsets  -->
<bean name="Ports01Bindings"  
	class="org.jboss.services.binding.impl.ServiceBindingSet">
	<constructor>
	<!--  The name of the set -->
		<parameter>ports-01</parameter>
	<!-- Default host name -->
		<parameter>${jboss.bind.address}</parameter>
	<!-- The port offset -->
		<parameter>100</parameter>
	<!-- Bindings to which the "offset by X" approach can't be applied -->
		<parameter><null/></parameter>
	</constructor>
</bean>

If you run Jboss without a ports configuration, it will use the default port settings. If you want to use a specific port configuration, all you need to do is add the startup param to the run.sh script used to invoke jboss: “-Djboss.service.binding.set=ports-01”. This param selects which port config to use, and likewise can be used to use any of the available port bindings found in bindings-jboss-beans.xml.

The props folder – default UsersRolesLoginModule properties for jmx-console security

If you make use of jmx-console’s default UsersRolesLoginModule JAAS security domain configuration, you’ll find that the user and role properties are stored in this “props” folder. More on securing the jmx console can be found here. You can also opt to use a different security module, by defining a different login module in login-config.xml. More on this in a few paragraphs.

The xmdesc folder – mbean descriptors

This folder contains all the descriptors used for the major mbeans described in the jboss-service.xml. Not all the possible mbeans have been converted over to the new bootstrapping style format, so these legacy descriptors close the gap to allow existing mbean services to continue to work.

Logging with jboss-log4j.xml

This piece allows you to configure the logging for the entire instance. If you’re familiar with log4j, you’ll know right off the bat how to configure the logging. Out of the box Jboss ships with console output enabled. For production level environments though, we’ll want that disabled as console logging always takes up unnecessary system resources. You are able to control smtp, console, file, jms, and file based logging with levels (DEBUG, INFO, WARN, ERROR, FATAL etc) and by category (com.yourpackage.class or com.yourpackage). Asynchronous appenders allow you to configure logging that gets piped to more than one target. Learn mroe about how to configure this from Apache’s Log4J’s project website. A basic log4j configuration can be found in the example below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" 
      debug="false">
   <!-- A time/date based rolling appender -->
      <appender class="org.jboss.logging.appender.DailyRollingFileAppender"
        name="FILE">
      <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
      <param name="File" value="${jboss.server.log.dir}/server.log"/>
      <param name="Append" value="true"/>
       
      <!-- Rollover at midnight each day -->
      <param name="DatePattern" value="'.'yyyy-MM-dd"/>

      <layout class="org.apache.log4j.PatternLayout">
         <!-- Default pattern: Date Priority [Category] (Thread) Messagen -->
         <param name="ConversionPattern" value="%d %-5p [%c] (%t) %m%n"/>
      </layout>
   </appender>

   <root>
	<priority value="${jboss.server.log.threshold}"/>
	<appender-ref ref="FILE"/>
   </root>
</log>

JAAS/Security Domains with login-config.xml

This file allows you to configure security domain with JAAS for your applications. You have a number of login modules to choose from, notably the DatabaseServerLoginModule. This module allows you to hook in a set of users and roles query into a datasource to validate authentication credentials and allow access to your application. In a default install, Jboss will have example configurations where users and roles are also stored in the props directory and accessed via the UsersRolesLoginModule.

An example JAAS database login module configuration in login-config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<deployment xmlns="urn:jboss:bean-deployer:2.0">
  <application-policy xmlns="urn:jboss:security-beans:1.0" name="loginForm">
    <authentication>
      <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
        flag="required">
        <!--  BASE64 also possible -->
        <module-option name="hashAlgorithm">MD5</module-option> 
        <module-option name="unauthenticatedIdentity">guest</module-option>
        <module-option name="dsJndiName">java:/DefaultDS</module-option>
        <module-option name="principalsQuery">
        	SELECT password FROM User WHERE username=?
        </module-option>
        <module-option name="rolesQuery">
        	SELECT role, 'Roles' 
        	FROM UserRoles, User 
        	WHERE User.username=? 
        		AND User.id = UserRoles.user_id
        </module-option>
      </login-module>
    </authentication>
  </application-policy>
</deployment>

In order for this configuration to work we’ll need to also add security domains to our web application’s web.xml as well as a the Jboss only jboss-web.xml deployment descriptor. More on how to configure this can be fond in Jboss’ server manual, section 9.6.4.

The remaining files

The last remaining files cover various integration configurations, and delve into Jboss’ low level implementation. One example is the java.policy file which configures your instance’s security policy on the jvm level. You may constrain permissions to allow strictly reading across the board or some custom mix of read and write, and by class. More information can be found on Jboss Web’s security manager page. For the uninitiated, Jboss Web is the integrated version of Tomcat 6 that deploys with JBoss as a deployable service.

The jbossjta-properties.xml file configures the Jboss transaction server’s default behavior. The jax-ws-catalog.xml maps xml metadata for use with jax-ws webservices, as specified by the Oasis XML Catalog spec. The jndi.properties file maps classes used by Jboss’ naming server. The jacorb.properties file configures JacORB (Java implementation of OMG’s Corba standard) for use with Jboss.

Finally, the standardjbosscmp.xml config defines how various types of enterprise java beans are configured during regular use, while standardjbosscmp-jdbc.xml configures specific persistence dialects relating to type mappings so that datasource files can communicate correctly with different database vendors. In your datasource file you can add a type element to specify which of these defined types jboss should use:

<?xml version="1.0" encoding="UTF-8"?>  
<datasources>   
     <local-tx-datasource> 
        <jndi-name>DefaultDS</jndi-name> 
        <connection-url>jdbc:postgresql://localhost:5432/db</connection-url> 
        <driver-class>org.postgresql.Driver</driver-class> 
         <user-name>user</user-name>   
         <password>password</password> 
          <metadata> 
               <type-mapping>PostgreSQL</type-mapping> 
          </metadata>          
     </local-tx-datasource> 
</datasources>

The recap

Once you’ve gone over these configuration files, you’ll have seen with some depth part of what Jboss is capable of. As mentioned earlier, you wont want to muck around with most of these configurations unless you’re working on Jboss server code itself or unless you want to tweak the server’s behavior. The most commonly edited files end up being bindings-jboss-beans.xml (multiple port bindings), profile.xml (external deploy directories), jboss-log4j.xml (logging), login-config.xml (security domains) and java.policy (jvm level security permissions). With these basics you can be well off into configuring Jboss for whatever needs you need to fill.

Resources:
Securing the JMX Console
JBoss App server Quick Tour
JBoss Web manual
Oasis XML Catalog project

Comments (2)

  1. 6:39 PM, November 2, 2010Francesco Marchioni  / Reply

    Hi Antonio,
    interesting blog. Would you like to exchange link/feed with mine which is about jBoss too ? (Added in the Website section)
    Regards
    Francesco

    • 9:20 PM, November 2, 2010Ant  / Reply

      Sure – your site looks pretty good I’ll blogroll it. Nice tips.

Leave a Reply

Allowed Tags - You may use these HTML tags and attributes in your comment.

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Pingbacks (0)

› No pingbacks yet.