JBoss Application Server is the open source implementation of the Java EE suite of services. It comprises a set of offerings for enterprise customers who are looking for preconfigured profiles of JBoss Enterprise Middleware components that have been tested and certified together to provide an integrated experience. It's easy-to-use server architecture and high flexibility makes JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform.

Because it is Java-based, JBoss Application Server is cross-platform, easy to install and use on any operating system that supports Java. The readily available source code is a powerful learning tool to debug the server and understand it. It also gives you the flexibility to create customized versions for your personal or business use.

Installing JBoss Application Server is simple and easy. You can have it installed and running in no time. This guide will teach you to install and get started with the JBoss Application Server.

1. Software Versions

Software	Description
JBoss Application Server	5.0.0

Table 1. Software Versions

2. Help Contribute

If you find a typographical error in the Installation Guide and Getting Started Guide, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: http://jira.jboss.com against the project JBoss Application Server and component Docs/Installation and Getting Started Guide.

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Note

Be sure to give us your name so you can receive full credit.

Note

This content is taken from svn.jboss.org/repos/jbossas/projects/docs/community/5 and has yet to be branched.

To access the content directly and make changes yourself:

		svn co https://svn.jboss.org/repos/jbossas/projects/docs/community/5 --username yourusername

Chapter 1. Getting Started

1.1. Pre-Requisites

1.1.1. Hardware and Operating System Requirements
1.1.2. Configuring Your Java Environment

1.1. Pre-Requisites

You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.

1.1.1. Hardware and Operating System Requirements

For the latest information on supported Operating System / JVM combinations and supported Database platforms, please refer to http://www.jboss.com.

1.1.2. Configuring Your Java Environment

You must have a working installation of JDK 1.5 or JDK 1.6 before you install JBoss Application Server. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM.

Benefits of 64-bit JVM on 64-bit OS and Hardware:

Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications.
64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
Applications that run with more than 1.5GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Linux

Download the Sun JDK 5.0 or JDK 6 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp for JDK 5.0 or http://java.sun.com/javase/downloads/ for JDK 6.0. Select the JDK Update <x>" (where x is the latest update number) for download and then select "RPM in self-extracting" file for Linux^[1]. Read the instructions on Sun's website for installing the JDK.
If you do not want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.
Download and install the appropriate -compat RPM from JPackage here. Please ensure you choose a matching version of the -compat package to the JDK you installed.
Create an environment variable that points to the JDK installation directory and call it JAVA_HOME. Add $JAVA_HOME/bin to the system path to be able to run java from the command line. You can do this by adding the following lines to the .bashrc file in your home directory.
```
#In this example /usr/java/jdk1.6.0_07 is the JDK installation directory.
export JAVA_HOME=/usr/java/jdk1.6.0_07
export PATH=$PATH:$JAVA_HOME/bin
```
Set this variable for the user account doing the installation and also for the user account that will run the server.

If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.5 or JDK1.6 installation as the default source for the java and javac executables. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.

Select alternatives for java, javac and java_sdk_1.<x>

As root, type the following command at the shell prompt and you should see something like this:

[root@vsr ~]$ /usr/sbin/alternatives --config java
There are 2 programs which provide 'java'.
Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.4.2-gcj/bin/java
*+ 2           /usr/lib/jvm/jre-1.5.0-sun/bin/java
Enter to keep the current selection[+], or type selection number:

Make sure the Sun version [jre-1.5.0-sun in this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.

Repeat the same for javac and java_sdk_1.<x>

[root@vsr ~]$ /usr/sbin/alternatives --config javac
There are 1 programs which provide 'javac'.
	Selection   Command
-----------------------------------------------
*+ 1           /usr/lib/jvm/java-1.5.0-sun/bin/javac
Enter to keep the current selection[+], or type selection number:

[root@vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
There are 1 programs which provide 'java_sdk_1.5.0'.
	Selection   Command
-----------------------------------------------
*+ 1           /usr/lib/jvm/java-1.5.0-sun
Enter to keep the current selection[+], or type selection number:

You should verify that java, javac and java_sdk_1.<x> all point to the same manufacturer and version.

Note

You can always override this step by setting the JAVA_HOME environment variable as explained in the previous step.

Make sure that the java executable is in your path and that you are using an appropriate version. To verify your Java environment, type java -version at the shell prompt and you should see something like this:
```
[root@vsr ~]$ java -version
java version "1.5.0_14"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03)
Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)
```

Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Microsoft Windows

Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp for JDK 5.0 or http://java.sun.com/javase/downloads/ for JDK 6.0. Choose the JDK Update <x>" (where x is the latest update number) for download and then select your Windows Platform options to perform the installation.
Create an environment variable called JAVA_HOME that points to the JDK installation directory, for example: C:\Program Files\Java\jdk1.5.0_14\. In order to run java from the command line add the jre\bin directory to your path, for example: C:\Program Files\Java\jdk1.5.0_14\jre\bin. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.

^[1]Make sure you choose the appropriate file for your platform.

Chapter 2. Installation Alternatives

You can install the JBoss Application Server in one of these two modes:

Binary files download

In this form of installation, simply unzip the downloaded zip file to the directory of your choice. You can unzip the JBoss Application Server on any operating system that supports the zip format. The zip file is available on http://labs.jboss.com/jbossas/downloads/. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in Section 1.1, “Pre-Requisites”. Further details on installation using the Binary files are discussed in Chapter 3, Installation With Binary Download

JBossAS 5.0.0 can be compiled with both Java5 and Java6. The Java5 compiled binary is our primary/recommended binary distribution. It has undergone rigorous testing and can run under both a Java 5 and a Java 6 runtime. When running under Java 6 you need to manually copy the following libraries from the JBOSS_HOME/client directory to the JBOSS_HOME/lib/endorsed directory, so that the JAX-WS 2.0 apis supported by JBossWS are used:

* jbossws-native-saaj.jar * jbossws-native-jaxrpc.jar * jbossws-native-jaxws.jar * jbossws-native-jaxws-ext.jar

Another alternative is to download the jdk6 distribution (jboss-5.0.0.CR2-jdk6.zip) in which case no configuration changes are required. Please refer to the release notes for additional information about running with JDK 6.
Source Files download

In this form of installation, download the source files from the web and build the source files locally. On successfully building your source files you can manually copy the built file into a desired folder and start the server. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in Section 1.1, “Pre-Requisites”. For more instructions on building your source files, please refer to Chapter 4, Installation With Source Download .

Three types of server configurations will be included in your installation - minimal , default , and all .

Chapter 3. Installation With Binary Download

3.1. Download and Installation

3.1. Download and Installation

You can download the Binary zip files from http://labs.jboss.com/jbossas/downloads/.

There are two binary distributions available:

In this form of installation, simply unzip the downloaded zip file to the directory of your choice on any operating system that supports the zip format.

Unzip jboss-<release>.zip to extract the archive contents into the location of your choice. You can do this using the JDK jar tool (or any other ZIP extraction tool). In the example below we are assuming you downloaded the zip file to the /jboss directory.
```
[usr]$ cd /jboss
[usr]$ jar -xvf jboss-<release>.zip
                        
```
You should now have a directory called jboss-<release>. Next you need to set your JBOSS_HOME environment variables. This is discussed in Chapter 5, Setting the JBOSS_HOME variable .

Chapter 4. Installation With Source Download

4.1. Download and Installation
4.2. Installing and configuring ANT
4.3. Building with Apache ANT

4.1. Download and Installation

You can download the zip source file from http://labs.jboss.com/jbossas/downloads/.

Uncompress jboss-<release>-src.tar.gz to extract the archive contents into the location of your choice. You can do this using the tar archiving utility in Linux (or any other compatible extraction tool). In this example we are assuming your source files were copied in the /jboss folder.
```
[user@localhost]$ cd /jboss
[user@localhost]$ tar -xvf jboss-<release>-src.tar.gz
                        
```
You should now have a directory called jboss-<release>-src.tar.gz. The next step is to build your source files. In this example we are using Apache ANT. This is discussed in the following section.

4.2. Installing and configuring ANT

Apache Ant is a Java-based build tool. Instead of using an extended model using shell-based commands, Ant is extended using Java classes that use XML-based configuration files. The configuration files call out a target tree that executes various tasks. Each task is run by an object that implements a particular Task interface. This gives you the ability to perform cross platform builds. Please also note that if needed, Ant provides an <exec> task that allows commands to be executed based on the Operating System it is executing on. For more information on Apache ANT please click here.

You will need to build your JBoss Application Server source files before you can run the application server. Apache Ant is shipped with the JBoss Application Server source files and can be executed from the <source_directory>/tools/bin directory.

The source files can also be built using Apache Maven which is also shipped with the JBoss Application Server source files under <source_directory>/tools/maven directory. For more information about Apache Maven, please refer to http://maven.apache.org/.

Like Java, you also need to set the environment variables for Apache ANT and/or Apache Maven. The following example illustrates a desirable configuration for the .bashrc file. In the example the file is edited using the gnome text editor (gedit).

[user@localhost ~]$ gedit .bashrc

# Source global definitions
if [ -f /etc/bashrc ]; then
/etc/bashrc
fi
......
# User specific aliases and functions
# The following are the environment variables for Java , ANT and Maven
	
export JAVA_HOME=/usr/java/jdk1.6.0_07/
export PATH=$PATH:$JAVA_HOME/bin

export ANT_HOME=/home/downloads/jboss-<source_directory>/tools/
export PATH=$PATH:$ANT_HOME/bin

export MAVEN_HOME=/home/downloads/jboss-<source_directory>/tools/maven
export PATH=$PATH:$MAVEN_HOME/bin

To implement the changes you've made to the .bashrc file, type the following on a terminal.

[user@localhost ~]$ source .bashrc
[user@localhost ~]$

If any errors are displayed, please check your .bashrc file for errors and ensure that all directory paths are correct.

4.3. Building with Apache ANT

To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's downloads folder.

[user@localhost]$ cd /home/user/downloads/jboss-<release>-src/build
[user@localhost build]$ ls
aspects    component-matrix  docbook-support  iiop     jmx           mbeans          security    system-jmx  tools
bootstrap  connector         ejb3             j2se     jmx-remoting  messaging       server      testsuite   varia
build      console           embedded         jbossas  main          pom.xml         spring-int  thirdparty  webservices
cluster    deployment        hibernate-int    jbossmq  management    profileservice  system      tomcat

From the contents of the build directory above, you can see the build.xml file which is used by Apache ANT as a configuration file when building your source files. The next step is to perform the build using Apache ANT as illustrated below.

[user@localhost build]$ ant
	
compile-classes:
[mkdir] Created dir: /jboss/jboss-<release>-src/tomcat/output/classes
[javac] Compiling 89 source files to /jboss/jboss-<release>-src/tomcat/output/classes
....
....content truncated
.....
.....
_buildmagic:build-bypass-check:
jars:
most:
main:
BUILD SUCCESSFUL
Total time: 2 seconds

A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the build/output/jboss-<release> directory as indicated below.

Note

At this point the JBoss Application Server source files build is a hybrid one (builds in both Ant and Maven) because it declares all JBoss dependencies as maven2 artifacts, however after the dependencies are resolved/imported the legacy ant based build is used to compile and build the distribution. The JBoss Application Server source files will change to a full maven build soon.

[user@localhost build]$ ls
build.bat        build-old.xml      build-thirdparty-old.xml  eclipse.psf       output
build-distr.xml  build-release.xml  build.xml                 etc               pom.xml
build.log        build.sh           docs                      local.properties  VersionRelease.java

[user@localhost build]$ cd output/jboss-<release>
[user@localhost build]$ ls
bin  client  docs  lib  server

The jboss-<release> directory contains your successful JBoss Application Server files. You can copy this folder to a different location or run the server from this folder after setting the JBOSS_HOME environment variable in your .bashrc file. Next you need to set your JBOSS_HOME environment variables. This is discussed in Chapter 5, Setting the JBOSS_HOME variable .

Chapter 5. Setting the JBOSS_HOME variable

5.1. Setting the JBOSS_HOME variable in Linux.
5.2. Setting the JBOSS_HOME variable in Windows.

5.1. Setting the `JBOSS_HOME` variable in Linux.

Before you can run the JBoss Application Server, you need to ensure that you've configured the JBOSS_HOME environment variable in your .bashrc file as follows. In this example the Application Server folder has beeen copied to the /usr/jboss/jboss-<release> folder. The following is a .bashrc file used in this installation. Please ensure that your .bashrc file has a similar configuration.

[user@localhost ~]$ gedit .bashrc
	
# Source global definitions
if [ -f /etc/bashrc ]; then
/etc/bashrc
fi
......
# User specific aliases and functions
# The following are the environment variables for Java, ANT and JBoss

export JAVA_HOME=/usr/java/jdk1.6.0_07
export PATH=$PATH:$JAVA_HOME/bin
	
export ANT_HOME=/usr/ant/apache-ant-1.6.0
export PATH=$PATH:$ANT_HOME/bin

export JBOSS_HOME=/usr/jboss/jboss-<release>
export PATH=$PATH:$JBOSS_HOME/bin

To implement your .bashrc file changes run the following command.

[user@localhost ~]$ source .bashrc
[user@localhost ~]$

If no errors are displayed on your terminal, you are now ready to run your JBoss Application Server.

5.2. Setting the `JBOSS_HOME` variable in Windows.

Create an environment variable called JBOSS_HOME that points to the JBoss Application Server installation directory, for example: C:\Program Files\JBoss\jboss-<release>\.
In order to run JBoss Application Server from the command line, add the jboss-<release>\bin directory to your path, for example: C:\Program Files\JBoss\jboss-<release>\bin. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.

You are now ready to start the JBoss Application Server.

Chapter 6. Uninstall JBoss

The JBoss Application Server may be uninstalled by simply deleting the JBoss Application Server's installation directory. You will also need to remove the JBOSS_HOME environment variables discussed in Chapter 5, Setting the JBOSS_HOME variable for your Linux or Windows platform.

Chapter 7. Test your Installation

After you have installed the JBoss Application Server, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, open the JBOSS_DIST/jboss-<release>/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 similar to the following (accounting for installation directory differences) and contain no error or exception messages:

[samson@dhcp-1-150 bin]$ sh run.sh 
=========================================================================
   JBoss Bootstrap Environment
   
   JBOSS_HOME: /downloads/jboss-5.0.0.CR2
   
   JAVA: /usr/local/jdk1.6.0_07//bin/java
   JAVA_OPTS: -Dprogram.name=run.sh -server -Xms128m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true
					
   CLASSPATH: /downloads/jboss-5.0.0.CR2/bin/run.jar:/usr/local/jdk1.6.0_07//lib/tools.jar
=========================================================================
							
15:23:05,038 INFO  [ServerImpl] Starting JBoss (Microcontainer)...
15:23:05,042 INFO  [ServerImpl] Release ID: JBoss [Morpheus] 5.0.0.CR2 (build: SVNTag=JBoss_5_0_0_CR2 date=200809171139)	
.
.
...output truncated
.
.
15:25:18,401 INFO  [Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
15:25:18,556 INFO  [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
15:25:18,620 INFO  [ServerImpl] JBoss (Microcontainer) [5.0.0.CR2 (build: SVNTag=JBoss_5_0_0_CR2 date=200809171139)] Started in 2m:13s:511ms

Now open http://localhost:8080 in your web browser. (Make sure you dont have anything else already on your machine using that port).^[2] The contents of your page should look similar to the following: Figure 7.1, “Test your Installation”.

Figure 7.1. Test your Installation

You are now ready to use the JBoss Application Server.

^[2] Note that on some machines, the name localhost may not resolve properly and you may need to use the local loopback address 127.0.0.1 instead.

Chapter 8. The JBoss Server - A Quick Tour

8.1. Server Structure

8.1.1. Server Configurations
8.1.2. Starting and Stopping the Server

8.2. The JMX Console

8.3. Hot-deployment of services in JBoss

8.4. Basic Configuration Issues

8.4.1. Core Services
8.4.2. Logging Service
8.4.3. Security Service
8.4.4. Additional Services

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

8.1.1. Server Configurations

Fundamentally, the JBoss architecture consists of the JMX MBean server, the microkernel, and a set of pluggable component services - the MBeans. 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 JMX 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 four subdirectories: minimal, default and all - 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.

minimal: 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.
default: 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.
all: The all configuration starts all the available services. This includes the RMI/IIOP and clustering services, which are not loaded in the default configuration.

If you want to know which services are configured in each of these instances, look at the jboss-service.xml file in the <JBoss_Home>/server/<instance-name>/conf/ directory and also the configuration files in the <JBoss_Home>/server/<instance-name>/deploy directory.

[usr@localhost <JBoss_Home>]$ls server/default/conf 
bootstrap-beans.xml       jboss-log4j.xml    login-config.xml           xmdesc
bootstrap-repo-beans.xml  jboss-minimal.xml  props
jax-ws-catalog.xml        jboss-service.xml  standardjbosscmp-jdbc.xml
 jbossjta-properties.xml   jndi.properties    standardjboss.xml

Note

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 8.1.2.2, “Start the Server With Alternate Configuration”.

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

Directory	Description
`conf`	The `conf` directory contains the `jboss-service.xml` bootstrap descriptor file for a given server configuration. This defines the core services that are fixed for the lifetime of the server.
`data`	The `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.
`deploy`	The `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.
`lib`	This 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.
`log`	This 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/` `jboss-log4j.xml` configuration file.
`tmp`	The `tmp` directory is used for temporary storage by JBoss services. The deployer, for example, expands application archives in this directory.
`work`	This directory is used by Tomcat for compilation of JSPs.

Table 8.1. Server Configuration Directory Structure

8.1.1.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
|-- 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
|   |   |-- jacorb.properties
|   |   |-- jboss-log4j.xml
|   |   |-- jboss-minimal.xml
|   |   |-- jboss-service.xml
|   |   |-- jbossjta-properties.xml
|   |   |-- jndi.properties
|   |   |-- login-config.xml
|   |   |-- props
|   |   |   |-- jbossws-roles.properties
|   |   |   |-- jbossws-users.properties
|   |   |   |-- jmx-console-roles.properties
|   |   |   `-- jmx-console-users.properties
|   |   |-- standardjboss.xml
|   |   |-- standardjbosscmp-jdbc.xml
|   |   `-- xmdesc
|   |-- deploy
|   |-- deploy-hasingleton
|   |   `-- jms
|   |-- farm
|   |   `-- cluster-examples-service.xml
|   `-- lib
|-- default
|   |-- conf
|   |   |-- jboss-log4j.xml
|   |   |-- jboss-minimal.xml
|   |   |-- jboss-service.xml
|   |   |-- jbossjta-properties.xml
|   |   |-- jndi.properties
|   |   |-- login-config.xml
|   |   |-- props
|   |   |   |-- jbossws-roles.properties
|   |   |   |-- jbossws-users.properties
|   |   |   |-- jmx-console-roles.properties
|   |   |   `-- jmx-console-users.properties
|   |   |-- 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
|   |-- jboss-log4j.xml
|   |-- jboss-service.xml
|   |-- jndi.properties
|   `-- xmdesc
|       |-- NamingBean-xmbean.xml
|       `-- NamingService-xmbean.xml
|-- deploy
`-- lib
|-- jboss-management.jar
|-- jboss-minimal.jar
|-- jnpserver.jar
            `-- log4j.jar

8.1.1.2.1. Contents of "conf" directory

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

File	Description
`jboss-minimal.xml`	This is a minimalist example of the `jboss-service.xml` configuration file. (This is the `jboss-service.xml` file used in the `minimal` configuration file set)
`jboss-service.xml`	`jboss-service.xml` defines the core services and their configurations.
`jndi.properties`	The `jndi.properties` file specifies the JNDI `InitialContext` properties that are used within the JBoss server when an `InitialContext` is created using the no-arg constructor.
`jboss-log4j.xml`	This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.
`login-config.xml`	This 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`.
`standardjaws.xml`	This file provides the default configuration for the legacy EJB 1.1 CMP engine.
`standardjboss.xml`	This file provides the default container configurations.
`standardjbosscmp-jdbc.xml`	This file provides a default configuration file for the JBoss CMP engine.
`xmdesc/*-mbean.xml`	The `xmdesc` directory contains XMBean descriptors for several services configured in the `jboss-service.xml` file.

Table 8.2. Contents of "conf" directory

8.1.1.2.2. Contents of "deploy" directory

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

File	Description
`bsh-deployer.xml`	This file configures the bean shell deployer, which deploys bean shell scripts as JBoss services.
`cache-invalidation-service.xml`	This is a service that allows for custom invalidation of the EJB caches via JMS notifications. It is disabled by default.
`client-deployer-service.xml`	This is a service that provides support for Java EE application clients. It manages the `java:comp/env` enterprise naming context for client applications based on the `application-client.xml` descriptor.
`ear-deployer.xml`	The EAR deployer is the service responsible for deploying Java EE EAR files.
`ejb-deployer.xml`	The EJB deployer is the service responsible for deploying JEE EJB JAR files.
`hsqldb-ds.xml`	`hsqldb-ds.xml` configures the Hypersonic embedded database service configuration file. It sets up the embedded database and related connection factories.
`http-invoker.sar`	`http-invoker.sar` contains the detached invoker that supports RMI over HTTP. It also contains the proxy bindings for accessing JNDI over HTTP.
`jboss-aop-jdk50.deployer`	This service configures the `AspectManagerService` and deploys JBoss AOP applications.
`jboss-bean.deployer`	`jboss-bean.deployer` provides the JBoss microcontainer, which deploys POJO services wrapped in `.beans` files.
`jboss-ha-local-jdbc.rar`	`jboss-ha-local-jdbc.rar` is an experimental version of `jboss-local-jdbc.rar` that supports datasource failover.
`jboss-ha-xa-jdbc.rar`	`jboss-ha-xa-jdbc.rar` is an experimental version of `jboss-xa-jdbc.rar` that supports datasource failover.
`jboss-local-jdbc.rar`	`jboss-local-jdbc.rar` is a JCA resource adaptor that implements the JCA `ManagedConnectionFactory` interface for JDBC drivers that support the `DataSource` interface but not JCA.
`jboss-xa-jdbc.rar`	`jboss-xa-jdbc.rar` is a JCA resource adaptor that implements the JCA `ManagedConnectionFactory` interface for JDBC drivers that support the `XADataSource` interface.
`jbossjca-service.xml`	`jbossjca-service.xml` is the application server implementation of the JCA specification. It provides the connection management facilities for integrating resource adaptors into the JBoss server.
`jboss-web.deployer`	The `jboss-web.deployer` directory provides the Tomcat servlet engine.
`jbossws.sar`	`jbossws.sar` provides JEE web services support.
`messaging/destinations-service.xml`	`destinations-service.xml` configures a number of Messaging queues and topics used by the Messaging unit tests.
`messaging/messaging-service.xml`	The `messaging-service.xml` file configures the core JBoss Messaging service.
`jmx-console.war`	The `jmx-console.war` directory provides the JMX Console. The JMX Console provides a simple web interface for managing the MBean server.
`jmx-invoker-service.sar`	`jmx-invoker-service.sar` is an unpacked 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. This is similar to the legacy `jmx-rmi-adaptor.sar`, with the difference that the transport is handled by the detached invoker architecture.
`jsr-88-service.xml`	`jsr-88-service.xml` provides the JSR 88 remote deployment service.
`mail-ra.rar`	`mail-ra.rar` is a resource adaptor that provides a JavaMail connector.
`mail-service.xml`	The `mail-service.xml` file is an MBean service descriptor that provides JavaMail sessions for use inside the JBoss server.
`management/console-mgr.sar`	`console-mgr.sar` provides the Web Console. It is a web application/applet that provides a richer view of the JMX server management data than the JMX console. You may view the console using the URL `http://localhost:8080/web-console/`.
`monitoring-service.xml`	The `monitoring-service.xml` file configures alert monitors like the console listener and email listener used by JMX notifications.
`properties-service.xml`	The `properties-service.xml` file is an MBean service descriptor that allows for customization of the JavaBeans `PropertyEditor`s as well as the definition of system properties.
`scheduler-service.xml`	The `scheduler-service.xml` and `schedule-manager-service.xml` files are MBean service descriptors that provide a scheduling type of service.
`sqlexception-service.xml`	The `sqlexception-service.xml` file is an MBean service descriptor for the handling of vendor specific `SQLException`s.
`uuid-key-generator.sar`	The `uuid-key-generator.sar` service provides a UUID-based key generation facility.

Table 8.3. Contents of "deploy" directory

8.1.1.3. The "all" Server Configuration File Set

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

File	Description
`cluster-service.xml`	This service configures clustering communication for most clustered services in JBoss.
`deploy-hasingleton-service.xml`	This provides the HA singleton service, allowing JBoss to manage services that must be active on only one node of a cluster.
`httpha-invoker.sar`	This service provides HTTP tunneling support for clustered environments.
`iiop-service.xml`	This provides IIOP invocation support.
`juddi-service.sar`	This service provides UDDI lookup services.
`snmp-adaptor.sar`	This is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.

Table 8.4. Additional Services in "conf" directory for "all" configuration

8.1.1.4. EJB3 Services

The following table explains the files providing ejb3 services.

File	Description
`ejb3-interceptors-aop.xml`	This service provides the AOP interceptor stack configurations for EJB3 bean types.
`ejb3.deployer`	This service deploys EJB3 applications into JBoss.
`jboss-aop-jdk50.deployer`	This is a Java 5 version of the AOP deployer. The AOP deployer configures the `AspectManagerService` and deploys JBoss AOP applications.
`jbossws.sar`	This provides Java EE 5 web services support.

Table 8.5. EJB3 Services

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

File	Description
`ejb3-clustered-sfsbcache-service.xml`	This provides replication and failover for EJB3 stateful session beans.
`ejb3-entity-cache-service.xml`	This provides a clustered cache for EJB3 entity beans.

Table 8.6. Additional Services in EJB3 "all" Configuration

8.1.1.5. Adding Your Own Configuration

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.sh -c 
                           myconfig

8.1.2. Starting and Stopping the Server

8.1.2.1. Start the Server

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.

Remote connection to the JBoss AS server

JBoss AS now binds its services to localhost (127.0.0.1) by default, instead of binding to all available interfaces (0.0.0.0). 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 0.0.0.0. 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]$ ./run.sh 
=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: /home/user/jboss-as-version/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/user/jboss-as-version/jboss-as/bin/run.jar

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

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

Note

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.

8.1.2.2. Start the Server With Alternate Configuration

Using run.sh 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]$ ./run.sh -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

8.1.2.3. Using run.sh

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

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