Jboss Admin Tutorial: JBoss Directory Structure

4. JBoss Directory Structure

4.1. JBoss AS Directory Structure

JBossORG-EULA.txt       copyright.txt           lib/
bin/                    docs/                   readme.html
client/                 jar-versions.xml        server/
common/                 lgpl.html
  • Root dir known as jboss.home.dir or $JBOSS_HOME
  • Understanding the layout is important:

    • Locating libraries
    • Updating configuration
    • Deploying apps and services

When JBoss AS is installed (uncompressed), the following directories are created:

  • ${jboss.home.dir}/bin
  • ${jboss.home.dir}/client
  • ${jboss.home.dir}/common
  • ${jboss.home.dir}/docs
  • ${jboss.home.dir}/lib
  • ${jboss.home.dir}/server

4.2. The bin Directory

README-service.txt      run.conf                twiddle.sh
classpath.sh            run.conf.bat            wsconsume.bat
jboss_init_hpux.sh      run.jar                 wsconsume.sh
jboss_init_redhat.sh    run.sh                  wsprovide.bat
jboss_init_suse.sh      service.bat             wsprovide.sh
jbosssvc.exe            shutdown.bat            wsrunclient.bat
password_tool.sh        shutdown.jar            wsrunclient.sh
probe.bat               shutdown.sh             wstools.bat
probe.sh                twiddle.bat             wstools.sh
run.bat                 twiddle.jar

JBoss AS ${jboss.home.dir}/bin directory contains startup/shutdown scripts, bootstrap libraries, Web Services and server management utilities:

  • classpath.sh: A tool to determine JBoss classpaths (both client and server)
  • jboss_init_redhat.sh and jboss_init_suse.sh: JBoss system control scripts for RedHat and SuSE systems
  • probe.sh and probe.bat: used for discovering JBoss AS clusters.
  • run.sh and run.bat: Scripts for starting JBoss AS
  • run.jar: Bootstrap code for starting JBoss AS
  • service.bat: Script to manage JBoss as a Windows service.
  • shutdown.sh and shutdown.bat: Scripts for shutting down JBoss AS (including remote instances)
  • shutdown.jar: Bootstrap code for shutting down JBoss AS
  • twiddle.sh and twiddle.bat: Scripts for running JBoss AS command-line management client (based on JMX)
  • twiddle.jar: Bootstrap code for the JMX management (instrumentation) client
  • wsconsume, wsprovide, wsrunclient and wstools are utilities for Web Services. We will see that later on Web Services chapter.

4.3. The client Directory

  • Contains the Java libraries (JARs) required for clients that run outside the JBoss AS containers, such as:

    • WebService clients
    • EJB clients
    • JMX clients
  • Used by external applications that need to access JNDI resources
  • On Unix, to get the client CLASSPATH, run: ${jboss.home.dir}/bin/classpath.sh -c
  • As of JBoss 5, the file client/jbossall-client.jar contains references to other JARs via Class-Path setting in its META-INF/MANIFEST.MF file. This makes it possible for external JBoss clients to just reference this one JAR file as opposed to many of them.

We will use the client/ directory later with some clients (like JMS) that will run outside the JBoss AS.

4.4. The common directory

  • Contains the lib directory (also known as jboss.common.lib.url).

    • lib folder contains the common libraries shared by all server configurations (more on this later)
    • This directory is new to JBoss 5. In earlier versions of JBoss a number of common libraries were simply duplicated for each configuration set.

4.5. The docs Directory

dtd/            examples/       licenses/       schema/         tests/
  • Examples: sample configuration: JMX, JCA, JMS, NetBoot, etc.

    • Contains excellent examples for many different configurations. For example, the file docs/examples/jca/mysql-ds.xml can serve as a starting point in defining a MySQL-based DataSource (shared database connection-pool) in JBoss AS.
  • DTDs and Schemas for J2EE and JBoss XML files

    • Contain all J2EE-referenced XML DTD and XSD files, making it simple to validate XML files and lookup the relevant "grammar" when making configuration changes. DTDs were employed by J2EE 1.3 and JBoss 4 whereas Schemas are used since J2EE 1.4 and JBoss 5.
  • Licenses for all JBoss components
  • Unit test results

The actual JBoss AS documentation can be downloaded from http://www.jboss.org/jbossas/docs/5-x.html

4.6. The lib Directory

  • Contains JBoss bootstrap libraries (core libraries)
  • Do not place your own files here or remove any of the existing files
  • As an example, you’ll find here the JBoss Microcontainer and the old JMX kernel.

4.7. The server Directory

all/            minimal/        node2/          web/
default/        node1/          standard/
  • Known in JBoss AS as jboss.server.base.dir
  • Root of server configuration sets
  • JBoss comes with minimal, default and all
  • Version 5.x comes with 2 new configurations: standard and web
  • Defaults to configuration set in server/default
  • Configuration sets contain the actual JBoss services

To change the configuration set that JBoss AS runs with, execute: bin/run.sh -c <configuration-set>

For example:

bin/run.sh -c minimal
bin/run.sh -c all

Configuration sets:


  • Includes support for JNDI and logging. It does not contain any other J2EE services like Servlet/JSP container, EJB container, or JMS.
  • Can serve as a starting point when creating your own configuration sets


  • As the name implies, this is the default Java EE 5 configuration. Contains the most used services except JAXR, IIOP and clustering services.


  • This configuration extends the default configuration set and also include JAXR, IIOP and clustering services


  • Certified Java EE 5 configuration compliant.

The major differences with the existing configurations is that call-by-value and deployment isolation are enabled by default, along with support for rmiiiop and juddi (taken from the all config).


  • Lightweight web container profile (Java EE 6 web profile). It provides support for JTA/JCA and JPA except for the servlet/JSP container.

4.8. The server Configuration Sets

all/            minimal/        node2/          web/
default/        node1/          standard/
  • The currently running server/<server> dir is known in JBoss AS as jboss.server.home.url
  • The name of the server (e.g. "default") is known as jboss.server.name
  • Configuration sets are independent of each other

Each configuration set has to have at least the following four directories: conf/, deploy/, deployers/, and lib/. Other (referenced) directories such as data/, log/, tmp/, and work/ are automatically created on JBoss AS startup if they do not exist.

4.9. The default/conf Directory

bindingservice.beans/           jbossts-properties.xml
bootstrap/                      jndi.properties
bootstrap.xml                   login-config.xml
java.policy                     props/
jax-ws-catalog.xml              standardjboss.xml
jboss-log4j.xml                 standardjbosscmp-jdbc.xml
jboss-service.xml               xmdesc/
  • Known in JBoss as jboss.server.config.url
  • Contains a bootstrap descriptor (jboss-service.xml) that defines which services are loaded for the lifetime of the instance

The files in directory ${jboss.server.config.url} :

  • bootstrap/*: Bootstrap descriptors for core microcontainer services defined in bootstrap.xml
  • bootstrap.xml: Defines the core microcontainer beans to load during bootstap
  • jboss-service.xml: Defines the core JMX services configurations
  • jndi.properties: Specifies a set of properties that are passed to JNDI when new InitialDirContext() is called within JBoss
  • jboss-log4j.xml: Configuration file for the logging service (Log4J) defining log filters, priorities, and destinations
  • login-config.xml: Defines security realms used for authentication and authorization (JAAS)
  • props/*.properties: Java property files (usually used for JAAS realms)
  • java.policy: Placeholder for security permissions (Java Security Manager). Grant-All by default
  • standardjboss.xml: Configuration file for the standard EJB container
  • standardjbosscmp-jdbc.xml: Configuration file for the standard JBossCMP engine
  • xmdesc/*-mbean.xml: XMBean descriptors for services configured in the jboss-service.xml file
  • props/*: property files defining users and roles for the jmx-console

Any changes to files in this directory require a full server restart in order to take effect.

4.10. The default/data Directory

hypersonic/             wsdl/
tx-object-store/        xmbean-attrs/
  • Known in JBoss as jboss.server.data.dir
  • Location where some services store private content on the file system

    • Hypersonic DB - built-in (by default use as the temporary message store by JMS)
    • XMBeans attribute persistence (not enabled by default)
    • Transaction objects (temporary storage of objects during the two-phase commit process)
  • This directory is not directory exposed to the end users (e.g. though the web interface)

Unless you use Hypersonic DB, the contents of this directory (including the directory itself) can be cleared (deleted) between JBoss restarts.

4.11. The default/deploy Directory

CurrencyConverterApp.ear                jsr88-service.xml
ROOT.war/                               legacy-invokers-service.xml
admin-console.war/                      mail-ra.rar
cache-invalidation-service.xml          mail-service.xml
ejb2-container-jboss-beans.xml          management/
ejb2-timer-service.xml                  messaging/
ejb3-connectors-jboss-beans.xml         monitoring-service.xml
ejb3-container-jboss-beans.xml          my-ws.war
ejb3-interceptors-aop.xml               printservice.sar/
ejb3-timerservice-jboss-beans.xml       profileservice-jboss-beans.xml
fortune.war/                            profileservice-secured.jar/
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
jmx-remoting.sar/                       xnio-provider.jar/
  • Dynamic deployment content directory
  • This is where applications and services are deployed
  • Default location used by hot deployment service
  • Contains code and configuration files for all services

Some files in the deploy directory include:

  • ROOT.war: is the / root web application
  • cache-invalidation-service.xml - Custom invalidation of EJB caches via JMS
  • ejb2-container-jboss-beans.xml - UserTransaction integration bean for EJB2 container
  • ejb2-timer-service.xml - EJB timer service bean
  • ejb3-connectors-jboss-beans.xml - EJB3 remoting transport bean
  • ejb3-container-jboss-beans.xml - UserTransaction integration bean for EJB3 container
  • ejb3-interceptors-aop.xml - AOP for EJB3
  • ejb3-timer-service.xml - alternate quartz based timer service
  • hdscanner-jboss-beans.xml - hot deployment scanner bean
  • hsqldb-ds.xml - Hypersonic embedded database and related connection factories
  • http-invoker.sar - Detached invoker that supports RMI/HTTP
  • jboss-local-jdbc.rar - JCA to DataSource adaptor for JDBC drivers
  • jboss-xa-jdbc.rar - JCA to XADataSource adaptor for JDBC drivers.
  • jbossweb.sar - Tomcat Servlet/JSP Engine
  • jbossws.sar - The JBoss service that supports web services
  • jca-jboss-beans.xml - Connection management facilities for integrating JCA adaptors into JBoss AS
  • jms-ra.rar - JMS resssource adapter
  • messaging/connection-factories-service.xml - DLQ, ExpiryQueue JMS connection factory
  • messaging/destinations-service.xml - Message persistence store service
  • messaging/jms-ds.xml
  • messaging/legacy-service.xml
  • messaging/messaging-jboss-beans.xml - JMS security and management beans
  • messaging/messaging-service.xml - Core messaging service
  • messaging/remoting-bisocket-service.xml - JMS remoting service layer
  • jmx-console.war - Web application that provides HTML interface to manage MBean server
  • jmx-invoker-service.xml - RMI to JMX adaptor into JBoss
  • jmx-remoting.sar -
  • legacy-invokers-service.xml -
  • jsr-88-service.xml -
  • mail-ra.rar - Resource adaptor that provides a JavaMail connector
  • mail-service.xml - JavaMail session service (SMTP)
  • monitoring-service.xml - Configuration for alert monitors such as email or console listeners
  • properties-service.xml - JavaBeans PropertyEditors and definition of system properties
  • admin-console.war - admin console for JBoss AS
  • scheduler-service.xml - JBoss scheduling service
  • sqlexception-service.xml - Vendor-specific SQL exception handler
  • security/security-jboss-beans.xml - Security domain related beans
  • security/security-policies-jboss-beans.xml - Security authorization for EJB and web authorization
  • transaction-jboss-beans.xml - JTA transaction manager related beans
  • uuid-key-generator.sar - UUID-based key generation facility

4.12. The default/deployers Directory

alias-deployers-jboss-beans.xml         jboss-threads.deployer/
bsh.deployer/                           jbossweb.deployer/
clustering-deployer-jboss-beans.xml     jbossws.deployer/
dependency-deployers-jboss-beans.xml    jsr77-deployers-jboss-beans.xml
directory-deployer-jboss-beans.xml      logbridge-jboss-beans.xml
ear-deployer-jboss-beans.xml            messaging-definitions-jboss-beans.xml
ejb-deployer-jboss-beans.xml            metadata-deployer-jboss-beans.xml
ejb3.deployer/                          seam.deployer/
hibernate-deployer-jboss-beans.xml      security-deployer-jboss-beans.xml
jboss-aop-jboss5.deployer/              webbeans.deployer/
jboss-ejb3-endpoint-deployer.jar        xnio.deployer/
  • Contains all the JBoss AS services that are used to recognize and deploy different application and archive types.

Some files in the deployers directory:

  • hibernate-deployer-jboss-beans.xml - Deployer for Hibernate archives (HAR)
  • ejb-deployer-jboss-beans.xml - Service responsible for deploying EJB JAR files
  • ear-deployer-jboss-beans.xml - Service responsible for deploying EAR files
  • jbossweb.deployer - Service responsible for deploying WAR files
  • jboss-aop-jboss5.deployer - Deployer that sets up Aspect Manager Service and deploys AOP applications
  • etc…

This directory is new as of JBoss AS 5

4.13. The default/lib Directory

  • Directory referred to by the bootstrap code when loading the configuration set
  • Known within JBoss as jboss.server.lib.url
  • This directory is for Java code (JARs) to be used both by the deployed applications and JBoss AS services
  • If you have Java libraries that you need to be made available to all your applications/services, these can be placed in the ${jboss.server.lib.url} directory.
  • Similarly, you would also use this directory for Java libraries that need to be used by both your applications/services, and JBoss AS services.

    • A typical example of this is a JDBC driver that is needed by JBoss AS to manage a pool of database connections, as well as your code, which implicitly uses it to interact with the database server.

As of JBoss 5, some JARs that used to reside in this directory have been moved to common/lib in order to share them with other configuration sets.

4.14. The default/log Directory

  • Known within JBoss as jboss.server.log.dir
  • Default destination directory for JBoss AS log files (3 log files)
  • boot.log - logs boot process until logging service starts
  • server.log - takes over once the logging service is initialized from ${jboss.server.config.url}/jboss-log4j.xml
  • audit.log - audit security
  • Default startup log priority: DEBUG
  • STDOUT and STDERR are logged to console

By default:

  • Log file server.log is rolled over daily (with the ".yyyy-MM-dd" extension)
  • Existing logs are overwritten on [re]start
  • Old log files are not automatically cleaned by the server during runtime

Since the logging system is managed by Log4J it can be easily configured to:

  • Roll over logs hourly
  • Roll over logs by size (e.g. 500KB)
  • Automatically remove old logs
  • Log to SMTP, SNMP, Syslog, JMS, etc.

This directory can be cleared (deleted) between JBoss restarts.

4.15. The default/tmp Directory

  • Known in JBoss as jboss.server.temp.dir
  • Used by JBoss AS to store temporary files such as unpacked service and application deployments
  • Deployments are automatically removed on server shutdown

This directory can be cleared (deleted) between JBoss restarts.


Unpacked deployments (e.g. expanded WAR files) are not copied over. Packed deployments (WAR, EAR, RAR) are uncompressed, whereas JARs and XML-described services are copied over.

4.16. The default/work Directory

  • Directory where compiled JSP .java and .class files reside
  • Also contains cached TLDs
  • Very useful for debugging problems in JSPs

Java ServerPages (.jsp files) are automatically compiled into Java Servlets (.java file) and then into Java byte-code (.class files) by Tomcat (the embedded servlet engine running within JBoss AS).

Many JSP errors are easier to fix when developers are able to look at the compiled .java files and match the line numbers to error/exception messages.

Unless you care to preserve compiled JSPs, this directory can be cleared (deleted) between JBoss restarts.

Table of Contents

1. Overview of Java Enterprise Edition
1.1. What is Java EE?
1.2. Open and Standard-based
1.3. Multi-tier
1.4. Web-Enabled
1.5. Server Centric
1.6. Component-Based Distributed Architecture
1.7. Enterprise Applications
1.8. Java EE Contents
1.9. Java EE Services
2. Overview of JBoss Application Server
2.1. JBoss Organization
2.2. JBoss AS Background
2.3. Highlights of JBoss AS
2.4. What is new in JBoss AS 5?
2.5. JBoss AS Architecture
2.6. JBoss Microcontainer Layer
2.7. Services Layer
2.8. Aspect Layer
2.9. Application Layer
2.10. JBoss AS Services
2.11. JBoss AS Requirements
3. Installing JBoss AS
3.1. Getting and Installing Java
3.2. Configuring Java
3.3. Getting JBoss AS
3.4. Installing JBoss AS 5
4. JBoss Directory Structure
4.1. JBoss AS Directory Structure
4.2. The bin Directory
4.3. The client Directory
4.4. The common directory
4.5. The docs Directory
4.6. The lib Directory
4.7. The server Directory
4.8. The server Configuration Sets
4.9. The default/conf Directory
4.10. The default/data Directory
4.11. The default/deploy Directory
4.12. The default/deployers Directory
4.13. The default/lib Directory
4.14. The default/log Directory
4.15. The default/tmp Directory
4.16. The default/work Directory
5. Controlling the Life-Cycle of JBoss AS
5.1. Starting JBoss AS
5.2. Verifying JBoss AS Startup
5.3. Stopping JBoss AS
5.4. Starting From a Remote Server
6. Deployments on JBoss
6.1. Java EE Deployment Lifecycle
6.2. Deployment Descriptors
6.3. Deployment on JBoss AS
6.4. Deployers on JBoss AS
6.5. Deployment Dependencies
6.6. Hot vs. Cold Deployment
6.7. Bootstrapping JBoss
6.8. Lab: Deployment
7. Web Application Administration
7.1. Web Technologies
7.2. CGI vs. Servlets/JSPs
7.3. Tomcat Web Container
7.4. Tomcat’s server.xml
7.5. Tomcat’s web.xml
7.6. Defining and Mapping Servlets
7.7. Defining and Mapping Filters
7.8. Session Configuration
7.9. Welcome File List
7.10. Error Documents
7.11. Serving Static Content
7.12. Virtual Hosting with Tomcat
7.13. Web Access Logging
7.14. Lab: Tomcat
8. JNDI Administration
8.1. Java Naming and Directory Interface
8.2. JNDI in Java EE
8.3. JNDI on JBoss
8.4. Lab: JNDI View
9. Javamail Administration
9.1. What is JavaMail?
9.2. Configuring JavaMail Service
9.3. Lab: Mail
10. JMS Administration
10.1. JMS Overview
10.2. JMS in Java EE
10.3. When is JMS Used
10.4. JMS Architecture
10.5. JMS Messaging Domains
10.6. JMS Message Consumption
10.7. JMS on JBoss Configuration
10.8. Configure JMS connection factories
10.9. Configure JMS destinations
10.10. Advanded JBoss Messaging
10.11. JBoss Messaging bridge
10.12. Persistence service configuration
10.13. Lab: JMS
11. Enterprise Java Beans Administration
11.1. Introduction to EJB 3.0
11.2. EJB 3.0 Components
11.3. EJB Container
11.4. Benefits of EJB Technology
11.5. Drawbacks of EJBs
11.6. Session Beans
11.7. Interceptors
11.8. Entity Beans
11.9. Message-Driven Bean
11.10. Session Beans Client Interfaces
11.11. Stateless Session Beans Life Cycle
11.12. Stateful Session Beans Life Cycle
11.13. Message-Driven Beans Life Cycle
11.14. Configuring the EJB container
11.15. Stateful Session Bean Configuration
11.16. Lab: Stateless Session Bean
12. Web Services and JBoss
12.1. Web Services Overview
12.2. Service Oriented Architecture
12.3. Web Services With JAX-WS
12.4. Web Services on JBoss
12.5. JBoss Web Services Tools
12.6. Lab: Web Services
13. JMX Administration
13.1. What is JMX?
13.2. Why JMX?
13.3. JMX Architecture
13.4. JMX on JBoss AS
13.5. JMX Console
13.6. Web Console
13.7. Twiddle Tool
13.8. JBoss AS Administration Console
13.9. Lab: JMX Print Service
13.10. JBoss Monitoring
13.11. Snapshot and Web Console
13.12. Monitoring with JConsole
13.13. Scheduling on JBoss
13.14. Lab: Monitoring
14. Class Loading on JBoss
14.1. Class Namespace Isolation
14.2. Java Class Runtime Identity
14.3. Class Loading in Java EE
14.4. Class Loading On JBoss
14.5. The Class Loader
14.6. Default Class Search Order
14.7. Scoping Classes
14.8. Scoped Class Search Order
14.9. App-specific Log4J Config
14.10. Problems With Class Loading
14.11. Lab: Class Loading
15. Database Integration on JBoss
15.1. Steps Involved
15.2. Resource Requirement
15.3. Install JDBC Drivers
15.4. Define a RDBMS DBCP Resource
15.5. Map our Resource
15.6. Using our DataSource (RDBMS DBCP)
15.7. Hypersonic Database
15.8. Detecting Connection Leaks
15.9. Lab: Database Connectivity
16. Security on JBoss
16.1. Securing Applications
16.2. Filtering Clients by Source
16.3. Authentication & Authorization
16.4. Requiring A&A
16.5. Plain-Text Login Module
16.6. Database Login Module
16.7. FORM-based Login
16.8. Configuring JBoss AS for SSL
16.9. Creating SSL Certificates
16.10. Configure SSL Connector
16.11. Testing SSL Configuration
16.12. Requiring SSL in Apps
16.13. Lab: Application Security
16.14. Securing JMS destinations
16.15. Securing JBoss AS
16.16. JBoss AS System User
16.17. File System Security
16.18. Securing JMX Invoker
16.19. Securing JBoss Applications
16.20. Securing Hypersonic DB
16.21. Java Security Manager
16.22. Running Behind a Firewall
16.23. Lab: JBoss Security
17. Tuning JBoss
17.1. JVM Tuning
17.2. Tomcat Tuning
17.3. RMI Tuning
17.4. Log4J Tuning
17.5. Tuning Other Services
17.6. JMS Tuning
17.7. Slimming JBoss
18. High Availability and Scalability on JBoss
18.1. Requirements
18.2. Clustering: General understanding
18.3. Clustering and JBoss
18.4. Simple Web Architecture
18.5. External Load Balancer Architecture
18.6. Smart Proxy Architecture
18.7. General configuration for the following examples
18.8. Fronting with a Web Server
18.9. Fronting with Apache HTTPD
18.10. Installing mod_jk
18.11. Configuring mod_jk
18.12. Simple Load Balancing
18.13. Enabling Sticky Sessions
18.14. Clustered Session Replication
18.15. Clustering Single Sign-On
18.16. Clustering with HA-JNDI
18.17. HA-JNDI Client Configuration
18.18. Clustering with HA-JMS
18.19. Clustering with Stateless Session Beans
18.20. Clustering with Stateful Session Beans
18.21. Lab: Clustering