The largest Interview Solution Library on the web

« Previous | 1 | 2 | 3 | Next »

JBoss - The JBoss Server - A Quick Tour

9.1. Server Structure

Now that you’ve downloaded JBoss and have run the server for the first time, the next thing you will want to know is how the installation is laid out and what goes where. At first glance there seems to be a lot of stuff in there, and it’s not obvious what you need to look at and what you can safely ignore for the time being. To remedy that, we’ll explore the server directory structure, locations of the key configuration files, log files, deployment and so on. It’s worth familiarizing yourself with the layout at this stage as it will help you understand the JBoss service architecture so that you’ll be able to find your way around when it comes to deploying your own applications.

9.2. Server Configurations

Fundamentally, the JBoss architecture consists of the microcontainer, bootstrap beans loaded into the micrcontainer, a collection of deployers for loading various deployment types, and various mcbean(-jboss-beans.xml) and legacy mbean(jboss-service.xml) deployments. This makes it easy to assemble different configurations and gives you the flexibility to tailor them to meet your requirements.

You don’t have to run a large, monolithic server all the time; you can remove the components you don’t need (which can also reduce the server startup time considerably) and you can also integrate additional services into JBoss by writing your own MBeans. You certainly do not need to do this to be able to run standard Java EE 5 applications though.

You don’t need a detailed understanding of the microcontainer to use JBoss, but it’s worth keeping a picture of this basic architecture in mind as it is central to the way JBoss works.

The JBoss Application Server ships with three different server configurations. Within the <JBoss_Home>/server directory, you will find five subdirectories: minimal, default, standard, all and web - one for each server configuration. Each of these configurations provide a different set of services. The default configuration is the one used if you don’t specify another one when starting up the server.


has a minimal configuration—the bare minimum services required to start JBoss. It starts the logging service, a JNDI server and a URL deployment scanner to find new deployments. This is what you would use if you want to use JMX/JBoss to start your own services without any other Java EE 5 technologies. This is just the bare server. There is no web container, no EJB or JMS support.


is a base Java EE 5 server profile containing a default set of services. It has the most frequently used services required to deploy a Java EE application. It does not include the JAXR service, the IIOP service, or any of the clustering services.


The all configuration starts all the available services. This includes the RMI/IIOP and clustering services, which are not loaded in the default configuration.


is the JavaEE 5 certified configuration of services.


is a lightweight web container oriented profile that previews the JavaEE 6 web profile.

If you want to know which services are configured in each of these instances, the primary differences will be in the <JBoss_Home>/server//deployers/ directory and also the services deployments in the /server//deploy directory. For example, the default profile deployers and deploy directory contents are:

[usr@localhost <JBoss_Home>]$ls server/default/deployers
alias-deployers-jboss-beans.xml jboss-aop-jboss5.deployer
bsh.deployer jboss-jca.deployer
clustering-deployer-jboss-beans.xml jbossweb.deployer
dependency-deployers-jboss-beans.xml jbossws.deployer
directory-deployer-jboss-beans.xml j sr77-deployers-jboss-beans.xml
ear-deployer-jboss-beans.xml metadata-deployer-jboss-beans.xml
ejb-deployer-jboss-beans.xml seam.deployer
ejb3.deployer security-deployer-jboss-beans.xml
[usr@localhost <JBoss_Home>]$ls server/default/deploy
ROOT.war jsr88-service.xml
cache-invalidation-service.xml legacy-invokers-service.xml
ejb2-container-jboss-beans.xml mail-ra.rar
ejb2-timer-service.xml mail-service.xml
ejb3-connectors-jboss-beans.xml management
ejb3-container-jboss-beans.xml messaging
ejb3-interceptors-aop.xml monitoring-service.xml
ejb3-timer-service.xml profileservice-jboss-beans.xml
hdscanner-jboss-beans.xml properties-service.xml
hsqldb-ds.xml quartz-ra.rar
http-invoker.sar remoting-jboss-beans.xml
jboss-local-jdbc.rar schedule-manager-service.xml
jboss-xa-jdbc.rar scheduler-service.xml
jbossweb.sar security
jbossws.sar sqlexception-service.xml
jca-jboss-beans.xml transaction-jboss-beans.xml
jms-ra.rar transaction-service.xml
jmx-console.war uuid-key-generator.sar
jmx-invoker-service.xml vfs-jboss-beans.xml

while the web profile deployers and deploy directory contents are:

[usr@localhost <JBoss_Home>]$ls server/web/deployers
alias-deployers-jboss-beans.xml jbossweb.deployer
ejb3.deployer metadata-deployer-jboss-beans.xml
jboss-aop-jboss5.deployer security-deployer-jboss-beans.xml
[usr@localhost <JBoss_Home>]$ls server/web/deployers
ROOT.war jbossweb.sar
ejb3-container-jboss-beans.xml jca-jboss-beans.xml
hdscanner-jboss-beans.xml jmx-console.war
hsqldb-ds.xml jmx-invoker-service.xml
http-invoker.sar security
jboss-local-jdbc.rar transaction-jboss-beans.xml

The default configuration is the one used if you don’t specify another one when starting up the server.
To start the server using an alternate configuration refer to Section 9.3.2, “Start the Server With Alternate Configuration”.

9.2.1. Server Configuration Directory Structure

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 9.1, “Server Configuration Directory Structure” shows the directories inside the server configuration directory (<JBoss_Home>/server/<instance-name>) and their functions.

Table 9.1. Server Configuration Directory Structure
confThe conf directory contains the bootstrap.xml bootstrap descriptor file for a given server configuration. This defines the core microcontainer beans that are fixed for the lifetime of the server.
dataThe data directory is available for use by services that want to store content in the file system. It holds persistent data for services intended to survive a server restart. Serveral JBoss services, such as the embedded Hypersonic database instance, store data here.
deployThe deploy directory contains the hot-deployable services (those which can be added to or removed from the running server). It also contains applications for the current server configuration. You deploy your application code by placing application packages (JAR, WAR and EAR files) in the deploy directory. The directory is constantly scanned for updates, and any modified components will be re-deployed automatically.
libThis directory contains JAR files (Java libraries that should not be hot deployed) needed by this server configuration. You can add required library files here for JDBC drivers etc. All JARs in this directory are loaded into the shared classpath at startup. Note that this directory only contains those jars unique to the server configuration. Jars common across the server configurations are now located in <JBoss_Home>/common/lib.
logThis is where the log files are written. JBoss uses the Jakarta log4j package for logging and you can also use it directly in your own applications from within the server. This may be overridden through the conf/jbosslog4j. xml configuration file.
tmpThe tmp directory is used for temporary storage by JBoss services. The deployer, for example, expands application archives in this directory.
workThis directory is used by Tomcat for compilation of JSPs.
9.2.2. The "default" Server Configuration File Set

The "default" server configuration file set is located in the <JBoss_Home>/server/default directory. The following example illustrates a truncated directory structure of the jboss-as- <release> server configuration files:

[user@localhost <JBoss_Home>]$ tree
|-- bin
|-- client
|-- common
| |-- lib
| | |-- antlr.jar
| | |-- ... many more jars
|-- docs
| |-- dtd
| |-- examples
| | |-- binding-manager
| | | `-- sample-bindings.xml
| | |-- jca
| | |-- jms
| | |-- jmx
| | |-- netboot
| | | `-- netboot.war
| | `-- varia
| | |-- deployment-service
| | |-- derby-plugin.jar
| | |-- entity-resolver-manager
| | | `-- xmlresolver-service.xml
| | `-- jboss-bindings.xml
| `-- schema
|-- lib
| |-- commons-codec.jar
| |-- commons-httpclient.jar
| |-- commons-logging.jar
| |-- concurrent.jar
| |-- endorsed
| | |-- serializer.jar
| | |-- xalan.jar
| | `-- xercesImpl.jar
| |-- getopt.jar
| |-- jboss-common.jar
| |-- jboss-jmx.jar
| |-- jboss-system.jar
| |-- jboss-xml-binding.jar
| `-- log4j-boot.jar
`-- server
|-- all
| |-- conf
| | |-- bootstrap/
| | | |-- aop.xml
| | | |-- bindings.xml
| | | |-- aop.xml
| | | |-- classloader.xml
| | | |-- deployers.xml
| | | |-- jmx.xml
| | | |-- profile-repository.xml
| | | |-- profile.xml
| | | |-- vfs.xml
| | |-- bootstrap.xml
| | |-- bootstrap-norepo.xml
| | |--
| | |-- java.policy
| | |-- jax-ws-catalog.xml
| | |-- jboss-log4j.xml
| | |-- jboss-service.xml
| | |-- jbossjta-properties.xml
| | |--
| | |-- login-config.xml
| | |-- props
| | | |--
| | | |--
| | | |--
| | | `--
| | |-- standardjboss.xml
| | |-- standardjbosscmp-jdbc.xml
| | `-- xmdesc
| |-- deploy
| |-- deploy-hasingleton
| | `-- jms
| |-- deployers
| `-- lib
|-- default
| |-- conf
| | |-- bootstrap/
| | | |-- aop.xml
| | | |-- bindings.xml
| | | |-- aop.xml
| | | |-- classloader.xml
| | | |-- deployers.xml
| | | |-- jmx.xml
| | | |-- profile-repository.xml
| | | |-- profile.xml
| | | |-- vfs.xml
| | |-- bootstrap.xml
| | |-- bootstrap-norepo.xml
| | |--
| | |-- java.policy
| | |-- jax-ws-catalog.xml
| | |-- jboss-log4j.xml
| | |-- jboss-service.xml
| | |-- jbossjta-properties.xml
| | |--
| | |-- login-config.xml
| | |-- props
| | | |--
| | | |--
| | | |--
| | | `--
| | |-- standardjboss.xml
| | |-- standardjbosscmp-jdbc.xml
| | `-- xmdesc
| | |-- AttributePersistenceService-xmbean.xml
| | |-- ClientUserTransaction-xmbean.xml
| | |-- JNDIView-xmbean.xml
| | |-- Log4jService-xmbean.xml
| | |-- NamingBean-xmbean.xml
| | |-- NamingService-xmbean.xml
| | |-- TransactionManagerService-xmbean.xml
| | |-- org.jboss.deployment.JARDeployer-xmbean.xml
| | |-- org.jboss.deployment.MainDeployer-xmbean.xml
| | `-- org.jboss.deployment.SARDeployer-xmbean.xml
| |-- data
| | |-- hypersonic
| | |-- jboss.identity
| | |-- tx-object-store
| | `-- xmbean-attrs
| |-- deploy
| |-- lib
| |-- log
| | |-- boot.log
| | |-- server.log
| | `-- server.log.2008-08-09
| |-- tmp
| `-- work
| `-- jboss.web
| `-- localhost
`-- minimal
|-- conf
| |-- bootstrap/
| |-- bootstrap/aop.xml
| |-- bootstrap/classloader.xml
| |-- bootstrap/deployers.xml
| |-- bootstrap/jmx.xml
| |-- bootstrap/profile.xml
| |-- bootstrap.xml
| |-- jboss-log4j.xml
| |-- jboss-service.xml
| |--
| `-- xmdesc
| |-- NamingBean-xmbean.xml
| `-- NamingService-xmbean.xml
|-- deploy/
|-- deploy/hdscanner-jboss-beans.xml
|-- deployers/
`-- lib
|-- jboss-minimal.jar
|-- jnpserver.jar
`-- log4j.jar Contents of "conf" directory

The files in the conf directory are explained in the following table.

Table 9.2. Contents of "conf" directory
bootstrap.xmlThis is the bootstrap.xml file that defines which additional microcontainer deployments will be loaded as part of the bootstrap phase.
bootstrap/*This directory contains the microcontainer bootstrap descriptors that are referenced from the bootstrap.xml file.
jboss-service.xmljboss-service.xml legacy core mbeans that have yet to be ported to either bootstrap deployments, or deploy services. This file will go away in the near future.
jbossjta-properties.xmljbossjta-properties.xml specifies the JBossTS transaction manager default properties.
jndi.propertiesThe file specifies the JNDI InitialContext properties that are used within the JBoss server when an InitialContext is created using the no-arg constructor.
java.policyA placeholder java security policy file that simply grants all permissions.
jboss-log4j.xmlThis file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.
login-config.xmlThis file contains sample server side authentication configurations that are applicable when using JAAS based security.
props/*The props directory contains the users and roles property files for the jmx-console.
standardjboss.xmlThis file provides the default container configurations.
standardjbosscmp-jdbc.xmlThis file provides a default configuration file for the JBoss CMP engine.
xmdesc/*-mbean.xmlThe xmdesc directory contains XMBean descriptors for several services configured in the jboss-service.xml file. Contents of "deployers" directory

The files in the deployers directory are explained in the following table.

Table 9.3. Contents of "deployers" directory
alias-deployers-jboss-beans.xmlDeployers that know how to handle The know how to handle in as true controller context. Meaning they will only get active/installed when their original is installed.
bsh.deployerThis file configures the bean shell deployer, which deploys bean shell scripts as JBoss mbean services.
clustering-deployer-jboss-beans.xmlClustering-related deployers which add dependencies on needed clustering services to clustered EJB3, EJB2 beans and to distributable web applications.
dependency-deployers-jboss-beans.xmlDeployers for aliases.txt, jbossdependency. xml jboss-depedency.xml adds generic dependency on whatever. aliases.txt adds human-readable name for deployments, e.g. vfszip://home/blah/.../jboss-5.0.0.GA/ server/default/deploy/some-long-name.ear aliased to ales-app.ear.
directory-deployer-jboss-beans.xmlAdds legacy behavior for directories, handling its children as possible deployments. e.g. .sar's lib directory to treat its .jar files as deployments
ear-deployer-jboss-beans.xmlJavaEE 5 enterprise application related deployers
ejb-deployer-jboss-beans.xmlLegacy JavaEE 1.4 ejb jar related deployers
ejb3.deployerThis is a deployer that supports JavaEE 5 ejb3, JPA, and application client deployments, .
hibernate-deployer-jboss-beans.xmlDeployers for Hibernate -hibernate.xml descriptors, which are similar to Hibernate's .cfg.xml files.
jboss-aop-jboss5.deployerJBossAspectLibrary and base aspects. Why is this in deployers, dependencies?
jboss-jca.deployerjboss-jca.deployer description
jbossweb.deployerThe JavaEE 5 servlet, JSF, JSP deployers.
jbossws.deployerThe JavaEE 5 webservices endpoint deployers.
jsr77-deployers-jboss-beans.xmlDeployers for creating the JSR77 MBeans from the JavaEE components.
metadata-deployer-jboss-beans.xmlDeployers for processing the JavaEE metadata from xml, annotations.
seam.deployerDeployer providing integration support for JBoss Seam applications.
security-deployer-jboss-beans.xmlDeployers for configuration the security layers of the JavaEE components. Contents of "deploy" directory

The files in the deploy directory are explained in the following table.

Table 9.4. Contents of "deploy" directory
ROOT.warROOT.war establishes the '/' root web application.
cache-invalidation-service.xmlThis is a service that allows for custom invalidation of the EJB caches via JMS notifications. It is disabled by default.
ejb2-container-jboss-beans.xmlejb2-container-jboss-beans.xml UserTransaction integration bean for the EJB2 containers.
ejb2-timer-service.xmlejb2-timer-service.xml contains the ejb timer service beans.
ejb3-connectors-jboss-beans.xmlejb3-connectors-jboss-beans.xml EJB3 remoting transport beans.
ejb3-container-jboss-beans.xmlejb3-container-jboss-beans.xml UserTransaction integration bean for the EJB3 containers.
ejb3-interceptors-aop.xmejb3-interceptors-aop.xml defines the EJB3 container aspects.
ejb3-timer-service.xmlejb3-timer-service.xml an alternate quartz based timer service
hdscanner-jboss-beans.xmlhdscanner-jboss-beans.xml the deploy directory hot deployment scanning bean
hsqldb-ds.xmlconfigures the Hypersonic embedded database service configuration file. It sets up the embedded database and related connection factories.
http-invoker.sarcontains the detached invoker that supports RMI over HTTP. It also contains the proxy bindings for accessing JNDI over HTTP.
jboss-local-jdbc.raris a JCA resource adaptor that implements the JCA ManagedConnectionFactory interface for JDBC drivers that support the DataSource interface but not JCA.
jboss-xa-jdbc.rarJCA resource adaptors for XA DataSources
jbossweb.saran mbean service supporting TomcatDeployer with web application deployment service management.
jbossws.sarprovides JEE web services support.
jca-jboss-beans.xmljca-jboss-beans.xml is the application server implementation of the JCA specification. It provides the connection management facilities for integrating resource adaptors into the JBoss server.
jms-ra.rarjms-ra.rar JBoss JMS Resource Adapter
messaging/connection-factoriesservice. xmlconfigures the DLQ, ExpiryQueue JMS connection factory
messaging/destinations-service.xmlThe message persistence store service
messaging/destinations-service.xmlconfigures the DLQ, ExpiryQueue JMS destinations.
messaging/jms-ds.xmljms-ds.xml configures the JMSProviderLoader and JmsXA inflow resource adaptor connection factory binding.
messaging/legacy-service.xmllegacy-service.xml configures the JMSProviderLoader and JmsXA inflow resource adaptor connection factory binding.
messaging/messaging-jboss-beans.xmlThe messaging-jboss-beans.xml file configures JMS security and management beans.
messaging/messaging-service.xmlThe messaging-service.xml file configures the core JBoss Messaging service.
messaging/remoting-bisocketservice. xmlThe remoting-bisocket-service.xml configures the JMS remoting service layer.
jmx-console.warThe jmx-console.war directory provides the JMX Console. The JMX Console provides asimple web interface for managing the MBean server.
jmx-invoker-service.xmljmx-invoker-service.xml is an MBean service archive that exposes a subset of the JMX MBeanServer interface methods as an RMI interface to enable remote access to the JMX core functionality.
jmx-remoting.sarjmx-remoting.sar is a implementation providing access to the JMX server.
legacy-invokers-service.xmllegacy-invokers-service.xml the legacy detached jmx invoker remoting services.
jsr-88-service.xmljsr-88-service.xml provides the JSR 88 remote deployment service.
mail-ra.rarmail-ra.rar is a resource adaptor that provides a JavaMail connector.
mail-service.xmThe mail-service.xml file is an MBean service descriptor that provides JavaMail sessions for use inside the JBoss server.
monitoring-service.xmlThe monitoring-service.xml file configures alert monitors like the console listener and email listener used by JMX notifications.
profileservice-jboss-beans.xmlprofileservice-jboss-beans.xml description
properties-service.xmlThe properties-service.xml file is an MBean service descriptor that allows for customization of the JavaBeans PropertyEditors as well as the definition of system properties.
quartz-ra.rarquartz-ra.rar is a resource adaptor for inflow of Quartz events
remoting-jboss-beans.xmlremoting-jboss-beans.xml contains the unified invokers based on JBoss Remoting.
scheduler-service.xmlThe scheduler-service.xml and schedulemanager- service.xml files are MBean service descriptors that provide a scheduling type of service.
security/security-jboss-beans.xmlsecurity-jboss-beans.xml security domain related beans.
security/security-policies-jbossbeans. xmlsecurity-policies-jboss-beans.xml security authorization related beans for ejb and web authorization.
sqlexception-service.xmlThe sqlexception-service.xml file is an MBean service descriptor for the handling of vendor specific SQLExceptions.
transaction-jboss-beans.xmltransaction-jboss-beans.xml JTA transaction manager related beans.
transaction-service.xmltransaction-service.xml ClientUserTransaction proxy service configuration.
uuid-key-generator.sarThe uuid-key-generator.sar service provides a UUID-based key generation facility.
9.2.3. The "all" Server Configuration File Set

The "all" server configuration file set is located in the /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.

Table 9.5. Additional Services in "conf" directory for "all" configuration
cluster-service.xmlThis service configures clustering communication for most clustered services in JBoss.
deploy-hasingleton-service.xmlThis provides the HA singleton service, allowing JBoss to manage services that must be active on only one node of a cluster.
httpha-invoker.sarThis service provides HTTP tunneling support for clustered environments.
iiop-service.xmlThis provides IIOP invocation support.
juddi-service.sarThis service provides UDDI lookup services.
snmp-adaptor.sarThis is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.
9.2.4. EJB3 Services

The following table explains the files providing ejb3 services.

Table 9.6. EJB3 Services
ejb3-interceptors-aop.xmlThis service provides the AOP interceptor stack configurations for EJB3 bean types.
ejb3.deployerThis service deploys EJB3 applications into JBoss.
jboss-aop-jdk50.deployerThis is a Java 5 version of the AOP deployer. The AOP deployer configures the AspectManagerService and deploys JBoss AOP applications.
jbossws.sarThis provides Java EE 5 web services support.
Finally, in the EJB3 "all" configuration there are two additional services.

Table 9.7. Additional Services in EJB3 "all" Configuration
ejb3-clustered-sfsbcache-service.xmlThis provides replication and failover for EJB3 stateful session beans.
ejb3-entity-cache-service.xmlThis provides a clustered cache for EJB3 entity beans.

9.3. Starting and Stopping the Server

9.3.1. Start the Server

Move to JBOSS_DIST/jboss-as/bin directory and execute the run.bat (for Windows) or (for Linux) script, as appropriate for your operating system.

Remote connection to the JBoss AS server
JBoss AS now binds its services to localhost ( by default, instead of binding to all available interfaces ( This was primarily done for security reasons because of concerns of users going to production without having secured their servers properly. To enable remote access by binding JBoss services to a particular interface, simply run jboss with the -b option. To bind to all available interfaces and re-enable the legacy behaviour use -b In any case, be aware you still need to secure your server properly.

For more information including setting up multiple JBoss server instances on one machine and hosting multiple domains with JBoss, please refer to the Administration and Configuration Guide . Some examples on binding are shipped in <JBOSS_HOME>/docs/examples/binding-manager/sample-bindings.xml.

On starting your server, your screen output should look like the following (accounting for installation directory differences) and contain no error or exception messages:

[user@mypc bin]$ ./
JBoss Bootstrap Environment
JBOSS_HOME: /home/user/jboss-as-version/jboss-as
JAVA: java
JAVA_OPTS: -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client.
gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
CLASSPATH: /home/user/jboss-as-version/jboss-as/bin/run.jar

More options for the JBoss AS run script are discussed in Section 9.3.2, “Start the Server With Alternate Configuration” below.

Note that there is no "Server Started" message shown at the console when the server is started using the production profile, which is the default profile used when no other is specified. This message may be observed in the server.log file located in the server/production/log subdirectory.

9.3.2. Start the Server With Alternate Configuration

Using without any arguments starts the server using the default 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]$ ./ -c minimal
15:05:40,301 INFO [Server] JBoss (MX MicroKernel) [5.0.0 (build: SVNTag=JBoss_5_0_0
date=200801092200)] Started in 5s:75ms

9.3.3. Using

The run script supports the following options:

usage: [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

9.3.4. Stopping the Server

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

[bin]$ ./ -S

The shutdown script supports the following options:

A JMX client to shutdown (exit or halt) a remote JBoss server.
usage: shutdown [options] <operation>
-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
-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-invokerservice. xml service. Hence you cannot use the shutdown command with the minimal configuration.

9.3.5. Running as a Service under Microsoft Windows

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

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.

9.4. The JMX Console

When the JBoss Server is running, you can get a live view of the server by going to the JMX console application at http://localhost:8080/jmx-console. You should see something similar to Figure 9.1, “View of the JMX Management Console Web Application”.

The JMX Console is the JBoss Management Console which provides a raw view of the JMX MBeans which make up the server. They can provide a lot of information about the running server and allow you to modify its configuration, start and stop components and so on.

For example, find the service=JNDIView link and click on it. This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. Now find the operation called list near the bottom of the MBean view page and click the invoke button. The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.

Figure 9.1. View of the JMX Management Console Web Application

Look at some of the other MBeans and their listed operations; try changing some of the configuration attributes and see what happens. With a very few exceptions, none of the changes made through the console are persistent. The original configuration will be reloaded when you restart JBoss, so you can experiment freely without doing any permanent damage.

If you installed JBoss using the graphical installer, the JMX Console will prompt you for a username and password before you can access it. If you installed using other modes, you can still configure JMX Security manually. We will show you how to secure your console in Section 9.6.4, “Security Service”.

9.5. Hot-deployment of services in JBoss

Hot-deployable services are those which can be added to or removed from the running server. These are placed in the JBOSS_DIST/jboss-as/server//deploy directory. Let’s have a look at a practical example of hot-deployment of services in JBoss before we go on to look at server configuration issues in more detail.

Start JBoss if it isn’t already running and take a look at the server/production/deploy directory. Remove the mail-service.xml file and watch the output from the server:

13:10:05,235 INFO [MailService] Mail service 'java:/Mail' removed from JNDI

Then replace the file and watch JBoss re-install the service:

13:58:54,331 INFO [MailService] Mail Service bound to java:/Mail

This is hot-deployment in action.

9.6. Basic Configuration Issues

Now that we have examined the JBoss server, we will take a look at some of the main configuration files and what they are used for. All paths are relative to the server configuration directory (server/ default, for example).

9.6.1. Bootstrap Configuration

The microcontainer bootstrap configuration is described by the conf/bootstrap.xml and the conf/bootstrap/*.xml it references. Its expected that the number of bootstrap beans will be reduced in the future. Its not expected that you would need to edit the bootstrap configuration files for a typical installation.

9.6.2. Legacy Core Services

The legacy core services specified in the conf/jboss-service.xml file are started just after server starts up the microcontainer. 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.


Eventually this file will be dropped as the services are converted to microcontainer beans or mbeans that are deployed as deploy directory services.

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"
<!-- 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.

9.6.3. Logging Service

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://

Logging is controlled from a central conf/jboss-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 (log/server.log).

There are 6 basic log levels used: TRACE, 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"/>

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 conf/jboss-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"/>
<category name="org.jboss.ejb.plugins.cmp">
<priority value="DEBUG" />
<appender-ref ref="CMP"/>

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 their filenames. Please note that the log directory also contains HTTP request logs which are produced by the web container.

9.6.4. Security Service

The security domain information is stored in the file conf/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 (used in defining jboss specific configurations for an application) and/or jboss-web.xml (used in defining jboss for a Web application. We'll quickly look at how to do this to secure the JMX Console application which ships with JBoss.

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. 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.

1 The Java Authentication and Authorization Service. JBoss uses JAAS to provide pluggable authentication modules. You can use the ones that are provided or write your own if you have more specific requirements.

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 securityconstraint
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.
An example security config that only allows users with the
role JBossAdmin to access the HTML JMX console web application

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">
<login-module code=""
<module-option name="usersProperties">
<module-option name="rolesProperties">

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/ file and take the form "username=password". To assign a user to the JBossAdmin group add "username=JBossAdmin" to the jmx-consoleroles. properties file (additional roles on that username can be added comma separated). 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. 2

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/consolemgr. sar/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.

9.6.5. Additional Services

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

Detailed information on all these services can be found in the JBoss Application 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). 2 Since the username and password are session variables in the web browser you may need to restart your browser to use the login dialog window.
« Previous | 1 | 2 | 3 | Next »

copyright © 2014 - all rights riserved by