JBoss Installation

Before we start I would like to make one note and that is when you install software try and rename the installation directory (not to use any spaces) because in some environments (Windows) it likes to place JBoss in a pathname that has spaces (c:\program files\...), when you develop applications later, spaces in pathnames will cause you major headaches.

The first task we need to do is to obtain the JDK from Sun (http://java.sun.com), I used version 1.6.0 and JBoss runs perfectly but you might want to try with the latest version, download the JDK and install into your environment following Sun's instructions. Once installed don't forgot to set a JAVA_HOME environment variable that points to your JDK.

JAVA_HOME set JAVA_HOME=c:/jdk1.6.0_12

Installing JBoss is simple and there are a number of ways that you can install it

The fastest way to install JBoss is to download the binary version from http://www.jboss.org, unzip it and copy it to directory and that's it, it is ready to go, no installation. If you are going to install it straight into Production, then you need to make some changes to the default configuration to secure it, I have a topic on Production configurations. JBoss will work straight out of the box and is ideal for a development environment, the other route is to use JEMS installer which is a GUI based installer that allows you to configure the services that JBoss will use, you need to download the jems-installer file (http://labs.jboss.com/jeminstaller) which is an executable JAR file (90MB), looking at the web site the JEMS installer does not appear to supported very well as the link did not work but you can obtain the file from SourceForge.

It appears that the binary installation is the preferred way to go, one note is that there is no installation and everything that you need is contained in one directory (no registry settings or package stuff), this means you just copy the directory and put onto any server (Windows or Unix) and it should start up, the only difference is the way you start JBoss

There is a file called "service" in the bin directory which can create a windows JBoss service for you, I had problems when using this, it gave a file error message, this was because of the "jbosssvc" wrapper file was either corrupt or the wrong type, search for a newer version on the web and replace the one in the original install (I have a link below to the one I used)

create a windows JBoss service

c:\jboss6\bin\service install

Note: downloaded jbosssvc file

Directory Structure

When you have finished installing JBoss you should have a top level directory structure like below (Yes. I know its JBoss 4 but its the same layout)


This directory contains all the scripts (both Unix and Windows) that you will need to start and stop JBoss. There are a number of others files here

  • twiddle - we discussed this earlier
  • probe - used to discover JBoss AS clusters
  • wsconsume - Used for web services
  • wsprovide - Used for web services
  • wsrunclient - Used for web services
  • wstools - Used for web services
  • run.sh and run.bat - used to start JBoss
client This directory contains many Java libraries that are used to communicate with JBoss server from a client application. These client applications are called standalone client or remote clients and could be Swing applications, remote Web services, JMS clients. If for what ever reason you need to use these libraries use the jbossall-client.jar file, this jar file contains a META-INF/Manifest.mf file that contains a class path reference to all the jar files in this directory.
common This directory I believe is from the version 4 JBoss implemention, where all common Java libraries were placed so that all web application could use them, I now believe that all common libraries should be placed in the <server config>/lib directory (see below).

There are no user manuals in this directory, but it contains the following

  • Document type definition (DTD) files and XML schemas for the configuration files that JBoss AS uses
  • Configuration examples for various J2EE and JBoss AS
  • Licenses for various libraries included in JBoss AS
  • Unit test results from the tests run against the server for the particular release
lib This directory contains all the libraries that need to start the core JBoss server. Do not put any libraries that you want to use across all web applications, these need to go in <server config>/lib (see below)

This directory only has the server configurations in it, each directory represents a different server configuration that JBoss can be started in (see above).

Normally you copy a particular directory that suits you and rename to what ever you want and then configure this directory for your environment, then use the -c option to start your server configuration

c:\jboss5\bin\run.bat -c myServerConfig

The server directory holds the server configuration, see above for the layout of this directory


Each server configuration has a conf directory that holds files used for servlet-wide configuration. This directory is only scanned once during the boot sequence so any changes that yo make are not picked up until you restart the server. The import files in this directory are

  • bootstrap.xml - defines core microcontainer services
  • jboss-service.xml - defines core JMX services
  • jboss-log4j.xml - configures logging
  • login-config.xml - configures authentication and authorization modules for security
  • standardjboss.xml - used to configure the various EJB containers
  • jacorb.properties - Used to configure the Java Object Request Broker (JacORB) service, used in clustering
  • jax-ws-catalog.xml - Used to map XML metadata names to local metadata descriptor files
  • jbossjta-properties.xml - Used to configure the Java Transaction API (JTA) service
  • jboss-service.xml - a variation of the jboss-service.xml file configured for a minimal app server configuration
  • jndi.properties - Used by the JNDI service to define default properties
  • standardjbosscmp-jdbc.xml - Used by the EJB service to define type mappings for various databases for data persistence
deploy this is where applications and services are deployed. You can deploy any application packages here for example JAR, WAR or EAR that you create. By copying them into this directory JBoss will automatically deploy them to the application server.
deployers contains all the JBoss AS services that are used to recognize and deploy different applications and archive types, for example the ejb3.deployer directory contains libraries and configuration files necessary for starting the service that deploys EJB3 applications that you deploy into the deploy directory.
lib this directory holds all the Java libraries that can be accessed by all web applications.
Generated Directories

JBoss creates additional directories when first started

  • data - used to write to the filesystem for storing temporary data
  • log - holds three log files: boot.log, server.log, audit.log
  • tmp - stores temporary data by various services
  • work - used by the web server to store compiled JSP files and other temporary data

Server Configurations

JBoss is designed to be modular, this means that you add or remove services very easily, by removing unwanted services you can decrease the memory allocation and increase performance, it also reduces security risks. The picture below shows how the microcontainer runs on top of the JVM and how various application-server services plug into the microcontainer. When you start JBoss you are always starting a server configuration which is a directory structure under the server's server directory, it contains code, libraries and configuration files for a set of services and applications that run when the server starts.

Typically you copy one of the already supplied configurations and adapt it to your environment, then start this configuration using the -c option with run.bat or run.sh, or you can just use one of the supplied configurations.

start a different configuration run.bat -c minimal

run.bat -c <your configuration>
all Includes everything - clustering, RMI/IIOP support
default this is the default configuration if you do not specify anything, it does not include a web container, no ejb or JMS support
minimal Includes only JNDI, logging services an a URL deployment scanner to find new deployments
web Used to contain services which will allow simple web applications (servlet, jsp) to be deployed.

JBoss Boot Sequence

I have read a number of JBoss books and none of them detailed the JBoss boot sequence, searching the web and using the JBoss log file, I will put a quick summary of the boot sequence below, it may not be to accurate but there is no document that explains this well, I will update this as and when I get more information.

bootstrap.xml Defines the core microcontainer services that start when the server first starts.
bootstrap.xml file
vfs.xml This configures the Virtual filesystem, which is a simple read-only framework abstracting the way we look at the the filesystem. It uses virtual files which can be accessed by a URI/URL (uses a URI/URL:MBean link pairing)
classloader.xml This configures the core classloading system and classpath
aop.xml Aspect-oriented programming is a programming paradigm that increases modularity by allowing the separation of cross-cutting concerns. (its a post OOP programming paradigm)
jmx.xml This configures the JMX Kernel Mbeans
deployers.xml This configures the MainDeployer, Structure Deployers, the bootstrap MC and the JMX deployer
binding.xml This configures the ServiceBindingManager bean and configuration
profile-repository.xml This configures the ProfileService beans which includes management and deployment support.

Starting and Stopping JBoss

To start JBoss using the default configuration, you open a console window and go to the bin directory, then run "run.sh" or "run.bat", you can also use the -c option to change the default server configuration, I have already discussed this above. To stop JBoss use the "shutdown" command

Starting JBoss # cd <JBoss dir>/bin

# run.sh
c:\> run.bat

# run.sh -c all
Stopping JBoss # shutdown.sh
c:\> shutdown.bat

When JBoss has started you should see the below line in the log file, you can also check that JBoss has started by using the following URL http://localhost:8080

JBoss has started 2009-04-03 12:05:12,125 INFO [org.jboss.bootstrap.microcontainer.ServerImpl] (main) JBoss (Microcontainer) [5.0.1.GA (build: SVNTag=JBoss_5_0_1_GA date=200902231221)] Started in 1m:907ms


JBoss uses log4j an open source logging framework, the configuration file is located at server/xxx/conf/jboss-log4j.xml. I have already discussed log4j in my Tomcat tutorial, so have a look there first then continue back here. JBoss be default has two appenders configured, one for the console and for the server/xxx/log/server.log file. Most configuration setups use a rolling log file, it is created each time JBoss is stopped and restarted and at midnight it is rolled over, you can also specify a size for it to rollover.

Rolling logfile <log4j: ...>
  <appender name="FILE" class="org.jboss.logging.appender.RollingFileAppender">
    <errorHandler ../>
    <param name="File" value="${jboss.server.log.dir}/server.log"/>
    <param name="Append" value="true"/>
    <param name="MaxFileSize" value="10MB"/>
    <param name="MaxBackupIndex" value="20"/>
    <layout ../>
Limiting logging <log4j:...>
  <category name="org.jboss.jms">
    <priority value="WARN"/>

System Properties

There are a number of system properties that define default directory locations

jboss.home.dir c:\jboss-5.0.0.GA
jboss.home.url file:/c:\jboss-5.0.0.GA
jboss.lib.url <jboss.home.url>lib/
jboss.patch.url -none-
jboss.server.base.dir <jboss.home.dir>/server
jboss.server.base.url <jboss.home.url>server/
jboss.server.home.dir <jboss.server.base.dir>/default
jboss.server.home.url <jboss.server.base.url>default/
jboss.server.config.url <jboss.server.home.url>conf/
jboss.server.data.dir <jboss.server.home.dir>/data
jboss.server.lib.url <jboss.server.home.url>lib/
jboss.server.log.dir <jboss.server.home.dir>/log
jboss.server.temp.dir <jboss.server.home.dir>/tmp

You can also provide system properties on the commandline by using the "-D" option

supplying commandline properties c:\> run.bat -Djboss.server.log.dir=d:/log

There are two more systems properties which are of interest

jboss.server.name default

System properties are used in a number of configuration XML files and as stated above you can add your own properties using the "-D" option

Using your own system properties

c:\> run.bat -Dtrading.database.login=trader1 -Dtrading.database.password=traderpw

// In your oracle-ds.xml file