Getting Started

Installing JBoss Enterprise Application Platform creates a top level directory, which will be named jboss-eap-<version> if you used the zip installation method, and will be named according to your specification if you used the GUI installer. Throughout this guide we refer to this top-level directory as the JBOSS_DIST directory. There are four sub-directories immediately below this:

Below is the layout of the installation directory of JBoss Enterprise Application Platform. In the figure, the default server configuration file set is shown expanded. In a clean installation, within the server/default directory only the conf, deploy, and lib directories exist. The data, log, tmp and work sub-directories are created by JBoss and won’t exist until you’ve run the server at least once. Section 2.3, “Starting and Stopping the Server” will teach you to run the server.

jboss-eap-<version>                  // jboss.home_url
	|+ doc
	|+ jboss-as
		|+ bin
		|+ client
		|+ docs
		|+ icons
		|+ lib                         // jboss.lib.url
		|+ scripts
		|+ server
			|+ all                // jboss.server.name
			|+ default            // jboss.server.home.url
				|+ conf       // jboss.server.config.url
				|+ deploy
				|+ lib        // jboss.server.lib.url
				|+ data
				|+ log
				|+ tmp
				|+ work
			|+ minimal
			|+ production
	|+ seam
	|+ Uninstaller                      // jboss.uninstaller.url

Several of the locations may be overridden. For these locations, the org.jboss.system.server.ServerConfig interface constant and its corresponding system property string are shown in the figure. The names ending in URL correspond to locations that can be specified using a URL to access remote locations, for example, HTTP URLs against a web server.

The table below illustrates the contents of the jboss-as directory.

[vsr]$ls server/default/conf 
jbossjta-properties.xml  jndi.properties   standardjbosscmp-jdbc.xml
jboss-log4j.xml          login-config.xml  standardjboss.xml
jboss-minimal.xml        props             xmdesc
jboss-service.xml        standardjaws.xml

The directory server configuration you’re using, is effectively the server root while JBoss is running. It contains all the code and configuration information for the services provided by the particular server configuration. It’s where the log output goes, and it’s where you deploy your applications. Table 2.2, “Server Configuration Directory Structure” shows the directories inside the server configuration directory (JBOSS_DIST/jboss-as/server/<instance-name>) and their functions.

The "default" server configuration file set is located in the JBOSS_DIST/jboss-as/server/default directory. Let's take a look at the contents of the default server configuration file set:

jboss-eap-<version>                // jboss.home_url
	|+ doc
	|+ jboss-as
		|+ bin
		|+ client
		|+ docs
		|+ icons
		|+ lib                        // jboss.lib.url
		|+ scripts
		|+ server
			|+ all               // jboss.server.name
			|+ default           // jboss.server.home.url
				|+ conf      // jboss.server.config.url
					|+ props
					|+ xmdesc
					-  jbossjta-properties.xml  
					-  jboss-minimal.xml  
					-  jndi.properties                   
					-  standardjboss.xml
					-  jboss-log4j.xml
					-  jboss-service.xml
					-  login-config.xml
					-  standardjbosscmp-jdbc.xml
				|+ deploy
					|+ ejb3.deployer
					|+ http-invoker.sar
					|+ jboss-aop-jdk50.deployer
					|+ jboss-bean.deployer
					|+ jboss-web.deployer
					|+ jbossws.sar
					|+ jms
					|+ jmx-console.war
					|+ management
					|+ uuid-key-generator.sar
					-  bsh-deployer.xml
					-  cache-invalidation-service.xml
					-  client-deployer-service.xml
					-  ear-deployer.xml
					-  ejb3-interceptors-aop.xml
					-  ejb-deployer.xml
					-  hsqldb-ds.xml
					-  jboss-ha-local-jdbc.rar
					-  jboss-ha-xa-jdbc.rar
					-  jbossjca-service.xml
					-  jboss-local-jdbc.rar
					-  jboss-xa-jdbc.rar
					-  jmx-invoker-service.xml
					-  jsr88-service.xml
					-  mail-service.xml
					-  monitoring-service.xml
					-  properties-service.xml
					-  quartz-ra.rar
					-  schedule-manager-service.xml
					-  scheduler-service.xml
					-  sqlexception-service.xml
				|+ lib            // jboss.server.lib.url
			|+ minimal
			|+ production
	|+ seam
	|+ Uninstaller                          // jboss.uninstaller.url

The "all" server configuration file set is located in the JBOSS_DIST/jboss-as/server/all directory. In addition to the services in the "default" set, the all configuration contains several other services in the conf/ directory as shown below.

The following table explains the files providing ejb3 services.

Finally, in the EJB3 "all" configuration there are two additional services.

You can add your own configurations too. The best way to do this is to copy an existing one that is closest to your needs and modify the contents. For example, if you weren’t interested in using messaging, you could copy the production directory, renaming it as myconfig, remove the jms subdirectory and then start JBoss with the new configuration.

run -c myconfig

Move to JBOSS_DIST/jboss-as/bin directory and execute the run.bat (for Windows) or run.sh (for Linux) script, as appropriate for your operating system. Your output should look like the following (accounting for installation directory differences) and contain no error or exception messages:

[jwulf@thinkpad bin]$ ./run.sh 
=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: /home/jwulf/jboss-eap-4.2/jboss-as

  JAVA: java

  JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client.
gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true

  CLASSPATH: /home/jwulf/jboss-eap-4.2/jboss-as/bin/run.jar

=========================================================================

13:11:46,215 INFO  [Server] Starting JBoss (MX MicroKernel)...
.
.
.
.
13:11:47,071 INFO  [ServerInfo] Java version: 1.5.0_11,Sun Microsystems Inc.
13:11:47,071 INFO  [ServerInfo] Java VM: 
Java HotSpot(TM) Server VM 1.5.0_11-b03,Sun Microsystems Inc.
13:11:47,072 INFO  [ServerInfo] OS-System: Linux 2.6.21-1.3228.rhel5,i386
13:11:48,558 INFO  [Server] Core system initialized
13:11:56,934 INFO  [WebService] Using RMI server codebase: http://127.0.0.1:8083/
13:11:56,940 INFO  [Log4jService$URLWatchTimerTask] 
Configuring from URL: resource:jboss-log4j.xml

Using run.sh without any arguments starts the server using the production server configuration file set. To start with an alternate configuration file set, pass the name of the server configuration file set [same as the name of the server configuration directory under JBOSS_DIST/jboss-as/server] that you want to use, as the value to the -c command line option. For example, to start with the minimal configuration file set you should specify:

[bin]$ ./run.sh -c minimal
...
...
...
15:05:40,301 INFO  [Server] JBoss (MX MicroKernel) [4.2.0.GA (build: SVNTag=JBoss_4_2_0_GA date=200706111042)] Started in 5s:75ms

The run script supports the following options:

usage: run.sh [options]
-h, --help                          Show help message
-V, --version                       Show version information
--                                  Stop processing options
-D<name>[=<value>]      Set a system property
-d, --bootdir=<dir>           Set the boot patch directory; Must be absolute or url
-p, --patchdir=<dir>          Set the patch directory; Must be absolute or url
-n, --netboot=<url>           Boot from net with the given url as base
-c, --configuration=<name>    Set the server configuration name
-B, --bootlib=<filename>      Add an extra library to the front bootclasspath
-L, --library=<filename>      Add an extra library to the loaders classpath
-C, --classpath=<url>         Add an extra url to the loaders classpath
-P, --properties=<url>        Load system properties from the given url
-b, --host=<host or ip>       Bind address for all JBoss services
-g, --partition=<name>        HA Partition name (default=DefaultDomain)
-u, --udp=<ip>                UDP multicast address
-l, --log=<log4j|jdk>         Specify the logger plugin type

To shutdown the server, you simply issue a Ctrl-C sequence in the console in which JBoss was started. Alternatively, you can use the shutdown.sh command.

[bin]$ ./shutdown.sh -S

The shutdown script supports the following options:

A JMX client to shutdown (exit or halt) a remote JBoss server.

usage: shutdown [options] <operation>

options:
-h, --help                Show this help message (default)
-D<name>[=<value>]        Set a system property
--                        Stop processing options
-s, --server=<url>        Specify the JNDI URL of the remote server
-n, --serverName=<url>    Specify the JMX name of the ServerImpl
-a, --adapter=<name>      Specify JNDI name of the MBeanServerConnection to use
-u, --user=<name>         Specify the username for authentication
-p, --password=<name>     Specify the password for authentication

operations:
-S, --shutdown            Shutdown the server
-e, --exit=<code>         Force the VM to exit with a status code
-H, --halt=<code>         Force the VM to halt with a status code

Using the shutdown command requires a server configuration that contains the jmx-invoker-service.xml service. Hence you cannot use the shutdown command with the minimal configuration.

You can configure the server to run as a service under Microsoft Windows, and configure it to start automatically if desired.

Download the JavaService package from http://forge.objectweb.org/projects/javaservice/.

Unzip the package and use the JBossInstall.bat file to install the JBoss service. You must set the JAVA_HOME and JBOSS_HOME environment variables to point to the jdk and jboss-as directories before running JBossInstall.bat. Run JBossInstall.bat with the following syntax:

JBossInstall.bat <depends> [-auto | -manual]

Where <depends> is the name of any service that the JBoss AS server depends on, such as the mysql database service.

Once the service is installed the server can be started by using the command net start JBoss, and stopped with the command net stop JBoss.

Please refer to the documentation included in the JavaService package for further information.

The core services specified in the conf/jboss-service.xml file are started first when the server starts up. If you have a look at this file in an editor you will see MBeans for various services including logging, security, JNDI, JNDIView etc. Try commenting out the entry for the JNDIView service.

Note that because the mbeans definition had nested comments, we had to comment out the mbean in two sections, leaving the original comment as it was.

<!-- Section 1 commented out
<mbean code="org.jboss.naming.JNDIView"
    name="jboss:service=JNDIView"
    xmbean-dd="resource:xmdesc/JNDIView-xmbean.xml">
-->
    <!-- The HANamingService service name -->
<!-- Section two commented out
    <attribute name="HANamingService">jboss:service=HAJNDI</attribute></mbean>
-->

If you then restart JBoss, you will see that the JNDIView service no longer appears in the JMX Management Console (JMX Console) listing. In practice, you should rarely, if ever, need to modify this file, though there is nothing to stop you adding extra MBean entries in here if you want to. The alternative is to use a separate file in the deploy directory, which allows your service to be hot deployable.

In JBoss log4j is used for logging. If you are not familiar with the log4j package and would like to use it in your applications, you can read more about it at the Jakarta web site (http://jakarta.apache.org/log4j/).

Logging is controlled from a central conf/log4j.xml file. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, JBoss produces output to both the console and a log file (server.log in the log directory).

There are 5 basic log levels used: DEBUG, INFO, WARN, ERROR and FATAL. The logging threshold on the console is INFO, which means that you will see informational messages, warning messages and error messages on the console but not general debug messages. In contrast, there is no threshold set for the server.log file, so all generated logging messages will be logged there.

If things are going wrong and there doesn’t seem to be any useful information in the console, always check the server.log file to see if there are any debug messages which might help you to track down the problem. However, be aware that just because the logging threshold allows debug messages to be displayed, that doesn't mean that all of JBoss will produce detailed debug information for the log file. You will also have to boost the logging limits set for individual categories. Take the following category for example.

<!-- Limit JBoss categories to INFO --> 
<category name="org.jboss"> 
    <priority value="INFO"/> 
</category>

This limits the level of logging to INFO for all JBoss classes, apart from those which have more specific overrides provided. If you were to change this to DEBUG, it would produce much more detailed logging output.

As another example, let’s say you wanted to set the output from the container-managed persistence engine to DEBUG level and to redirect it to a separate file, cmp.log, in order to analyze the generated SQL commands. You would add the following code to the log4j.xml file:

<appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender"> 
    <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> 
    <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/> 
    <param name="Append" value="false"/> 
    <param name="MaxFileSize" value="500KB"/> 
    <param name="MaxBackupIndex" value="1"/> 
 
    <layout class="org.apache.log4j.PatternLayout"> 
        <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> 
    </layout> 
</appender> 
 
<category name="org.jboss.ejb.plugins.cmp"> 
    <priority value="DEBUG" /> 
    <appender-ref ref="CMP"/> 
</category>

This creates a new file appender and specifies that it should be used by the logger (or category) for the package org.jboss.ejb.plugins.cmp.

The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is cmp.log. Older files have the date they were written added to the name. You will notice that the log directory also contains HTTP request logs which are produced by the web container.

The security domain information is stored in the file login-config.xml as a list of named security domains, each of which specifies a number of JAAS ^[1] login modules which are used for authentication purposes in that domain. When you want to use security in an application, you specify the name of the domain you want to use in the application’s JBoss-specific deployment descriptors, jboss.xml and/or jboss-web.xml. We will quickly look at how to do this to secure the JMX Console application.

Almost every aspect of the JBoss server can be controlled through the JMX Console, so it is important to make sure that, at the very least, the application is password protected. Otherwise, any remote user could completely control your server. To protect it, we will add a security domain to cover the application. ^[2] This can be done in the jboss-web.xml file for the JMX Console, which can be found in deploy/jmx-console.war/WEB-INF/ directory. Uncomment the security-domain in that file, as shown below.

<jboss-web>
    <security-domain>java:/jaas/jmx-console</security-domain>
</jboss-web>

This links the security domain to the web application, but it doesn't tell the web application what security policy to enforce, what URLs are we trying to protect, and who is allowed to access them. To configure this, go to the web.xml file in the same directory and uncomment the security-constraint that is already there. This security constraint will require a valid user name and password for a user in the JBossAdmin group.

<!-- 
   A security constraint that restricts access to the HTML JMX console
   to users with the role JBossAdmin. Edit the roles to what you want and
   uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
   secured access to the HTML JMX console.
-->
<security-constraint>
    <web-resource-collection>
        <web-resource-name>HtmlAdaptor</web-resource-name>
        <description>
            An example security config that only allows users with the
            role JBossAdmin to access the HTML JMX console web application
        </description>
        <url-pattern>/*</url-pattern>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
        <role-name>JBossAdmin</role-name>
    </auth-constraint>
</security-constraint>

That's great, but where do the user names and passwords come from? They come from the jmx-console security domain we linked the application to. We have provided the configuration for this in the conf/login-config.xml.

<application-policy name="jmx-console">
    <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
                     flag="required">
            <module-option name="usersProperties">
                props/jmx-console-users.properties
            </module-option>
            <module-option name="rolesProperties">
                props/jmx-console-roles.properties
            </module-option>
        </login-module>
    </authentication> 
</application-policy>

This configuration uses a simple file based security policy. The configuration files are found in the conf/props directory of your server configuration. The usernames and passwords are stored in the conf/props/jmx-console-users.properties file and take the form "username=password". To assign a user to the JBossAdmin group add "username=JBossAdmin" to the jmx-console-roles.properties file. The existing file creates an admin user with the password admin. For security, please either remove the user or change the password to a stronger one.

JBoss will re-deploy the JMX Console whenever you update its web.xml. You can check the server console to verify that JBoss has seen your changes. If you have configured everything correctly and re-deployed the application, the next time you try to access the JMX Console, it will ask you for a name and password. ^[3]

The JMX Console isn't the only web based management interface to JBoss. There is also the Web Console. Although it's a Java applet, the corresponding web application can be secured in the same way as the JMX Console. The Web Console is in the file deploy/management/web-console.war. The only difference is that the Web Console is provided as a simple WAR file instead of using the exploded directory structure that the JMX Console did. The only real difference between the two is that editing the files inside the WAR file is a bit more cumbersome.

The non-core, hot-deployable services are added to the deploy directory. They can be either XML descriptor files, *-service.xml, or JBoss Service Archive (SAR) files. SARs contain both the XML descriptor and additional resources the service requires (e.g. classes, library JAR files or other archives), all packaged up into a single archive.

Detailed information on all these services can be found in the JBoss Enterprise Application Platform: Server Configuration Guide, which also provides comprehensive information on server internals and the implementation of services such as JTA and the J2EE Connector Architecture (JCA).