Configuration files

The default JBoss configuration set is located in the conf/default directory.

JBoss allows the administrator to maintain more than one configuration set. All one has to do is to copy all the files from the default configuration into a new subdirectory of conf.

For example, you can create a new configuration "myjboss" by creating under the conf directory a subdirectory called myjboss and copying all the files from subdirectory conf/default into conf/myjboss. After possibly altering certain settings in the newly created files, you can run JBoss with the new configuration by invoking the platform-dependent scripts and just passing the configuration name as a parameter, like this:

run.bat myjboss

There are several configuration files for JBoss. A description of each is given below:

jboss.properties
This is a file in the standard Java Properties format that is loaded into the System properties on startup of the JBoss server. System properties that are not required to be available prior to the invocation of the JBoss server main method can be specified here.
jboss.conf
The configuration file jboss.conf contains typically only those core service MBeans that are necessary to achieve the initial bootstrap of JBoss, like the class path extension inclusion mechanism shown in Figure 2.2, logging, configuration service, service control, etc.
Figure 2.2. Excerpt from jboss.conf
```
			
<MLET CODE="org.jboss.util.ClassPathExtension" ARCHIVE="jboss.jar" CODEBASE="../../lib/ext/">
 <ARG TYPE="java.lang.String" VALUE="../../log/">
</MLET>
			
		    
```
This file is loaded by an instance of the javax.management.loading.MLet class and it is written following the standard MLet syntax for JMX MBeans (refer to the JMX specification for more details). Any standard JMX MBean can be placed in the jboss.conf file as long as it does not depend on JBoss service MBeans like naming. MBeans that depend on JBoss service MBeans need to be configured in the jboss.jcml file so that startup dependencies can be managed.
Usually, you would never have to change this file.
jboss.jcml
This file lists all the JMX service MBeans that need to be included in the running instance of JBoss. Notice that, contrary to the MLet syntax, this file contains well-formed XML.
The need for deviation from MLet syntax is justified by the fact that MLet doesn't allow named parameters, only TYPE-VALUE pairs. Having only TYPE-VALUE pairs easily leads to problems due to MBean parameter mismatches.
The syntax of jboss.jcml allows the use of named parameters in MBean instantiation directives and it is a lot easier to use. For example, Figure 2.3 shows an MBean element used to create and include MailService in JBoss.
Figure 2.3. Excerpt from jboss.jcml
```
			    
<mbean code="org.jboss.mail.MailService" name="DefaultDomain:service=Mail">
<attribute name="JNDIName">Mail</attribute>
<attribute name="ConfigurationFile">mail.properties</attribute>
<attribute name="User">user_id</attribute>
<attribute name="Password">password</attribute>
</mbean>
			    
			
```
In a nutshell:
- The code attribute of the MBean element specifies which class to load and instantiate.
- The name attribute of the MBean element specifies the unique name of the MBean under the specified JMX domain.
- The attribute child elements of the MBean element specify the corresponding attributes of the instantiated MBean. The values of the attributes can be any Java primitives or String objects.
The jboss.jcml file is loaded by the org.jboss.configuration.ConfigurationService MBean. This service acts much like the standard JMX MLet class in that it loads and configures MBeans. The dependencies among MBeans are managed by the org.jboss.util.ServiceControl MBean. The ServiceControl MBean listens for REGISTRATION_NOTIFICATION and UNREGISTRATION_NOTIFICATION JMX events to determine which MBeans are available. The order of registration determines the order of initialization and startup. The ServiceControl expects MBeans requiring dependency management to conform to the org.jboss.util.Service interface. This interface allows for the orderly initialization, startup, stop and destroying of MBeans. The sequence is based on the order in which MBeans are specified in the jboss.jcml file. See the section called “How to Integrate Custom Services via MBeans” for the details on how to create an MBean that has dependencies on other MBeans.
jboss.dependencies
For reasons of simplicity and ease of configuration, the DependencyManager of JBoss was deprecated in the 2.1 release, so this file is no longer used.
Now all the MBeans listed in jboss.jcml have vertical dependency on each other. For example, a JNDI provider is required for DataSource wrappers because a DataSource wrapper needs to store a reference to itself in JNDI; therefore, a JNDI provider MBean has to be listed before the DataSource wrapper. See the section called “How to Integrate Custom Services via MBeans” for the details of the dependency mechanism.
jboss-auto.jcml
JBoss has the very powerful feature of being able to record a runtime snapshot of all of its running MBeans, including their attributes, and later reproduce that snapshot in another JBoss instance.
When such a snapshot is taken, it is recorded in XML format in the jboss-auto.jcml file.
Consider the following scenario:
The administrator takes a running JBoss instance, adds a few MBeans, modifies attributes of other MBeans, saves the configuration and finally gracefully shuts down JBoss.
The next time that JBoss is started, all the dynamically added Mbeans from the previous run are recreated and their attributes set. JBoss also resets any other modified attributes, regardless whether an MBean was added dynamically (at runtime) or statically (through jboss.jcml).
You also have the option not taking runtime snapshots; to do so, simply delete the jboss-auto.jcml file before starting JBoss, in which case JBoss will not record any of the MBeans changes at runtime.
Dependency between jboss.jcml and jboss-auto.jcml
If while using the runtime snapshot feature there is a need to remove an MBean listed in jboss.jcml, you also have to remove it from jboss-auto.jcml, if it appears there, to achieve the desired effect. Do not remove the entire jboss-auto.jcml file unless you want to stop taking runtime snapshots; to remove all the MBeans, create a functionally empty jboss-auto.jcml file, like this:
```
			
<?xml version="1.0" encoding="UTF-8"?>

<server>
</server>
			
		    
```
mail.properties
Following the EJB specification, JBoss provides access to a mail resource through the standard JavaMail APIs. This file specifies properties of the mail provider, such as where to find the SMTP and POP servers, as well as other mail-related configuration settings.
Note that you are allowed to specify multiple sets of configurations by creating multiple mail.properties files. All you have to do is to specify additional MailService MBeans with different ConfigurationFile attributes in the jboss.jcml file. See the section called “Using JavaMail in JBoss” for additional details.
jnp.properties and jndi.properties
These two files are JNDI related. The first one contains properties of JNP, the JNDI provider implementation in JBoss, while the second specifies properties for JNDI clients.
JNDI clients can read properties listed in a jndi.properties file as long as it appears somewhere in their class path. This improves the portability of the client program because it is not written to operate in a particular configuration. Note that you have to change the java.naming.provider.url=localhost property-value pair if you are using clients that reside on a machine other than the JBoss server host itself.
standardjaws.xml
Represents a default configuration file for the JBoss CMP engine. It contains the JNDI name of a default DataSource, per database JDBC Object-SQL mappings, default CMP entity beans settings, etc. See Chapter 4 for additional details.
auth.conf
This file is a JAAS login module configuration file, supported by the default javax.security.auth.login.Configuration implementation. It contains sample server side authentication configurations that are applicable when using JAAS based security. See Chapter 7 for additional details on the JBoss security framework.
server.policy
The default Java2 security policy for the JBoss server. Currently, this is set to an all-open configuration, but it is unused because the JBoss server does not run with a security manager by default. See Chapter 7 for a description of the JBoss security framework.
standardjboss.xml
This file provides the default container configuration. The use of this file is an advanced topic covered by Chapter 5.