Installation Guide

JBoss Enterprise Application Platform 6

For Use with JBoss Enterprise Application Platform 6

Edition 2

Sande Gilda

Eamon Logue

Darrin Mison

David Ryan

Misty Stanley-Jones

Keerat Verma

Tom Wells

Abstract

This book is a guide to the installation of JBoss Enterprise Application Platform 6 and its patch releases.

Preface

Chapter 1. Introducing JBoss Enterprise Application Platform 6

1.1. Introducing JBoss Enterprise Application Platform 6

JBoss Enterprise Application Platform 6 is a middleware platform built on open standards, and compliant with Java EE. It integrates JBoss Application Server 7 with high-availability clustering, powerful messaging, distributed caching, and other technologies to create a stable, scalable, and fast platform. In addition, it also includes APIs and development frameworks you can use to develop secure, powerful, and scalable Java EE applications quickly.

1.2. New and Changed Features in JBoss Enterprise Application Platform 6

Table 1.1. 6.0.1 Features

Feature Description
Java Certification Certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications.
Managed Domain
  • Centralized management of multiple server instances and physical hosts, while a Standalone Server allows for a single server instance.
  • Configurations, deployments, socket bindings, modules, extensions, and system properties are managed per server group.
  • Application security, including security domains, are managed centrally for simplified configuration.
Management Console and Management CLI New interfaces are provided to manage the domain or standalone server. Manual editing of XML configuration files is no longer required. The Management CLI also offers batch mode that can script and automate management tasks.
Simplified directory layout The modules/ directory now contains the application server modules, instead of using common and server-specific lib/directories. The domain/ and standalone/ directories contain the artifacts and configuration files for domain and standalone deployments.
Modular classloading mechanism Modules are loaded and unloaded on demand to provide performance and security benefits and a faster start-up and restart time.
Streamlined Data source management Database drivers are deployed just like other services. In addition, datasources are created and managed directly in the Management Console or Management CLI.
Faster start and stop time JBoss Enterprise Application Platform 6 uses fewer resources and is extremely efficient in its use of system resources. This is especially beneficial for developers.

Chapter 2. Downloading JBoss Enterprise Application Platform 6

2.1. About the Red Hat Customer Portal

The Red Hat Customer Portal is a website where Red Hat customers download officially-supported software, manage entitlements and support contracts, contact Global Support Services, and file bugs against Red Hat products. The web address to access the Customer Portal is https://access.redhat.com.

2.2. Available Downloads for JBoss Enterprise Application Platform 6

JBoss Enterprise Application Platform 6 includes a number of different installation types and optional components, which are available for download on the Red Hat Customer Portal at https://access.redhat.com/. The following table explains the different options. Some components are only appropriate for certain operating systems or architectures, and thus are only available for those specific variations.

Table 2.1. Available Downloads for JBoss Enterprise Application Platform 6

Name Description Operating Systems
Apache HTTP Server
A stand-alone Apache HTTP server instance for each supported operating system and architecture. This HTTP server has been tested and verified to work with JBoss Enterprise Application Platform 6.
Red Hat Enterprise Linux 5, Red Hat Enterprise Linux 6, Microsoft Windows Server 2008, Solaris 10 and 11
Native Components
Components which have been compiled to be optimized for a specific platform. For instance, DLLs are provided for Microsoft Windows Server environments. In some cases, the native components may provide performance improvements.
Red Hat Enterprise Linux 5, Red Hat Enterprise Linux 6, Microsoft Windows Server 2008, Solaris 10 and 11
Native Utilities
Utilities specific to each supported operating system and architecture, such as scripts and utilities for installing JBoss Enterprise Application Platform as a service in your operating system and generating SSL encryption keys and certificates.
Red Hat Enterprise Linux 5, Red Hat Enterprise Linux 6, Microsoft Windows Server 2008, Solaris 10 and 11
Webserver Connector Natives
Pre-compiled modules for Apache, Microsoft, and Oracle iPlanet web servers, for HTTP load balancing and high-availability capabilities. These binaries are extensively tested and known to work well with JBoss Enterprise Application Platform 6.
Red Hat Enterprise Linux 5, Red Hat Enterprise Linux 6, Microsoft Windows Server 2008, Solaris 10 and 11
Javadocs
Documentation for all public APIs exposed by JBoss Enterprise Application Platform 6. You can install these into your local HTTP server or IDE, or can view them on your local machine.
Platform-independent
Installer
Java graphical installer for JBoss Enterprise Application Platform 6
Platform-independent
Maven Repository
A Maven repository which you can download and make available in your local development environment, and which contains artifacts common to applications built upon JBoss Enterprise Application Platform 6.
Platform-independent
Quickstarts
Example applications to help you get started developing Java EE 6 applications with APIs supplied with JBoss Enterprise Application Platform 6.
Platform-independent
Source Code
The Java source code for JBoss Enterprise Application Platform 6, provided so that you can recompile it in your own environment or audit it yourself.
Platform-independent
Application Platform
The ZIP installation package which can be installed and run on every supported platform. This is the most common way to install JBoss Enterprise Application Platform 6.
Platform-independent

Important

The RPM installation method's downloads are not available on the Customer Portal, but via the Red Hat Network (RHN). To install JBoss Enterprise Application Platform 6 via RPM, refer to the following topic: Section 4.4, “Install JBoss Enterprise Application Platform 6 using the Red Hat Network (RPM installation)”

2.3. Download JBoss Enterprise Application Platform 6

  1. Log into the Customer Service Portal at https://access.redhat.com.
  2. From the menu, select DownloadsJBoss Enterprise MiddlewareDownloads.
  3. Select Application Platform from the Product drop-down box.
  4. Locate the appropriate Application Platform version and click the Download link.
  5. Download any other available packages you need, such as the Quickstarts, Maven Repository, HTTP Connectors, or Native binaries.
Result

JBoss Enterprise Application Platform 6 and any supplemental files that you selected are downloaded to your computer.

Chapter 3. Preparing to Install JBoss Enterprise Application Platform 6

3.1. Installation Prerequisites for JBoss Enterprise Application Platform 6

Before you can install JBoss Enterprise Application Platform 6, you need to meet the following requirements:

3.2. Java Environments Supported By JBoss Enterprise Application Platform 6

JBoss Enterprise Application Platform 6 requires Java 6 or Java 7. The list of supported Java environments can be found at http://www.jboss.com/products/platforms/application/supportedconfigurations/. A Java Development Kit (JDK) is required for development, and a Java Runtime Environment (JRE) is required to run JBoss Enterprise Application Platform.

Note

If you are using a RPM installation, you need a Java 6 JDK installed even if you use the Java 7 JDK for development.

3.3. Install OpenJDK on Red Hat Enterprise Linux

Introduction

OpenJDK is one of many Java Development Kits (JDKs) supported in Red Hat Enterprise Linux for use with JBoss enterprise products. This task shows you how to install OpenJDK in Red Hat Enterprise Linux, and how to configure your system to use it as the default JDK.

Note

It is possible to install multiple JDKs on a single system.
Task Prerequisites

You must meet the following conditions before continuing with this task:

  • You must be running Red Hat Enterprise Linux 6. OpenJDK is not available or supported for Red Hat Enterprise Linux 5 at this time.
  • The server running Red Hat Enterprise Linux 6 must be registered with RHN and subscribed to the base channel. Refer to the Package Management section of the Red Hat Enterprise Linux 6 Deployment Guide on https://access.redhat.com/knowledge/docs/ for more information about managing subscriptions and entitlements on Red Hat Enterprise Linux systems.
  1. Install the OpenJDK RPM.

    There are two different ways to install an RPM, depending on whether you have used a command-line interface (CLI) or a Graphical User Interface (GUI).
    • From the CLI

      After logging in with administrator access, run one of the following two commands:
      OpenJDK 6
      yum install java-1.6.0-openjdk-devel
      OpenJDK 7
      yum install java-1.7.0-openjdk-devel
    • From a GUI

      1. In Gnome, select Administration from the System menu, and click Add / Remove Software.
      2. Search for openjdk and choose the java-1.6.0-openjdk-devel option for OpenJDK 6 or the java-1.7.0-openjdk-devel option for OpenJDK 7.
      3. Click Apply to install the selected packages and dependencies.
      4. When prompted, enter the administrator password to install the packages.
  2. Optional: Set the JAVA_HOME environment variable.

    Some applications such as Apache Maven and Apache Ant require you to set the JAVA_HOME environment variable. If you need to do this, follow these steps.
    1. Determine the correct value for JAVA_HOME. Red Hat Enterprise Linux installs OpenJDK 1.6 into either /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0/ or /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64/, depending on whether your system is a 32-bit or 64-bit architecture. The JAVA_HOME should point to the directory containing a bin/java executable.
    2. As the user who will use OpenJDK, open the shell configuration file. For the Bash shell, this file is /home/username/.bashrc.
    3. At the bottom of the file, type the following line, replacing the hypothetical path with the actual path to use on your own system: export JAVA_HOME="/path/to/java/home"
    4. Save the file, and log out of and back into your session.
  3. Switch between different OpenJDK versions using the alternatives utility.

    Red Hat Enterprise Linux includes a utility called alternatives, which lets you change the default version for applications which allow multiple versions to be installed. OpenJDK is one such application.
    To use the alternatives utility, perform the following steps. Note that setting the environment variables overrides the behavior of the alternatives command. For instance, if you use a script which manually sets $JAVA_HOME and $JAVA variables to a different JDK from the one specified by the alternatives command, the environment variables will override the command.
    • Log in as the root user, or prefix the commands below with the sudo command.
    • The alternatives command is not installed by default, but may already be installed on your system. If not, install the alternatives package by running the following command:
      yum install alternatives
    • Issue the following command:
      /usr/sbin/alternatives --config java
    • Follow the prompts that follow to set the default version of OpenJDK.
Result:

OpenJDK is installed on your server and available for your use. If necessarily, the JAVA_HOME environment variable has been specified as well. If necessary, the default OpenJDK for your system has been set using the alternatives utility.

Chapter 4. Installing JBoss Enterprise Application Platform 6

4.1. Installation Methods for JBoss Enterprise Application Platform 6

The installation choices for JBoss Enterprise Application Platform 6 include an RPM repository, a JAR installer or the extraction of a ZIP archive.
You can use the RPM installer if you have a compatible operating system, or the Zip file if you would like to extract the server manually. The installer file is available to assist new users in the configuration and startup process, which also creates an XML installation script to automate the installation process for other or future installations.

4.2. Install JBoss Enterprise Application Platform 6 Using the Installer Method

Summary

The JBoss Enterprise Application Platform 6 installer offers multiple methods for installation. Choose from either the standard Graphical User Interface (GUI) installation, or a Command Line Interface (CLI) mode with the console parameter. An Automatic Installation mode enables you to generate an XML file of your selected installation settings to assist in future installations.

Procedure 4.1. Task

  • Install JBoss Enterprise Application Platform 6

    Choose your installation preference.
    • GUI Installation

      1. Launch the GUI installer with the following Java command.
        java -jar jboss-eap-6.0.0-installer.jar
      2. Follow the installation prompts. At the end of installation, an XML file of the installation can be generated, for future use with the Automatic Installation feature.
    • Console Installation

      1. Launch the console installer with the following Java command.
        java -jar jboss-eap-6.0.0-installer.jar -console
      2. Follow the installation text prompts. At the end of the installation, an XML file of the installation can be generated, for use with the automatic installation feature.
    • Automatic Installation

      1. If you have created a previous installation instance, you will have generated an automatic installation XML script. You can use this file to run the automatic installation option.
      2. Launch the automatic installer with the following Java command.
        java -jar jboss-eap-6.0.0-installer.jar NameOfXML.xml
      3. Installation will complete according to the values in the XML file.
Result

The installation is complete.

4.3. Install JBoss Enterprise Application Platform 6 Using the ZIP Download

Summary

The Zip file installation method is appropriate for all support operating systems.

Prerequisites

Before you can install JBoss Enterprise Application Platform 6, you need to download the Zip archive from the Red Hat Customer Service Portal.

Procedure 4.2. Task

  1. Move the Zip archive to the desired location.

    Move the Zip file to the server and directory where you want to install JBoss Enterprise Application Platform 6. The directory should be accessible by the user who will start and stop the server.
  2. Use an appropriate application to extract the Zip archive.

    In Linux, the command to extract a Zip archive is typically called unzip. In a Microsoft Windows environment, right-click the file and select Extract All.
Result

The directory created by extracting the Zip archive is the top-level directory for JBoss Enterprise Application Platform 6. This is typically referred to as EAP_HOME. If you ever decide to move your installation, you can move this directory to another directory or another server.

4.4. Install JBoss Enterprise Application Platform 6 using the Red Hat Network (RPM installation)

Summary

The RPM package method of installing JBoss Enterprise Application Platform 6 is appropriate for Red Hat Enterprise Linux 6. The recommended installation method is to use the Red Hat Network (RHN) to manage your server subscriptions and channels.

Important

The jbossas-hornetq-native package is included for high availability in JBoss Enterprise Application Platform 6 but it is not activated by default.
Prerequisites

To install JBoss Enterprise Application Platform 6 using the Red Hat Network, the host server must meet the following requirements:

  • The server must be registered on the Red Hat Network.
  • The server must be subscribed to the Red Hat Enterprise Linux Server (v.6) base software channel.
  • The server must be subscribed to the JBoss Application Platform (v 6) for 6Server x86_64 sub-channel. The sub-channel is in the Additional Services Channels for Red Hat Enterprise Linux 6 for x86_64 group.
  • A Java 6 JDK must be installed. If you wish to use a Java 7 JDK, you need to install both versions. To configure which JDK your system uses as the default, run the following command, with superuser privileges:
    [root@host /root]# alternatives --config java
    A plus sign (+) is displayed beside the current default. Follow the on-screen instructions to make any changes, or press the Enter key to keep the current selection.
A system configured for RHN installation of JBoss Enterprise Application Platform 6

Figure 4.1. A system configured for RHN installation of JBoss Enterprise Application Platform 6

Procedure 4.3. Task

Access and install the RPM package by using the YUM install via the Red Hat Network.
  1. Install the RPM package by using YUM and the Red Hat Network

    Use YUM to install the default JBoss Enterprise Application Platform 6 group package by using the groupinstall command.
    [user@host ~]$ yum groupinstall jboss-eap6
  2. Configure init options.

    The RPM install contains init scripts for launching the server. The configuration for the init scripts are contained in serveral additional files. Refer to Section 4.5, “RPM Installation Configuration Files” for details about these files and the options contained within.
Result

The installation is complete. Refer to Section A.1, “RPM Package List and Dependencies” for a complete list of all the packages installed.

4.5. RPM Installation Configuration Files

The RPM installation of JBoss Enterprise Application Platform 6 includes three additional configuration files that are used by the service init script to specify the application server's launch environment. One of these files applies to all JBoss Enterprise Application Platform 6 instances, the other two provide overrides for standalone and domain mode servers.

Table 4.1. RPM Installation Configuration Files

File Description
/etc/jbossas/jbossas.conf This file is read first and applies to all JBoss Enterprise Application Platform 6 instances.
/etc/sysconfig/jbossas Settings specific to standalone servers. Values specified here will override those in jbossas.conf when running as a standalone server.
/etc/sysconfig/jbossas-domain Settings specific to domain-mode servers. Values specified here wille overrides those in jbossas.conf when running as a domain-mode server.

Table 4.2. RPM Installation Configuration Properties

Property Description
JBOSS_USER
The system user account that the JBoss Enterprise Application Platform 6 runs as. This user also has ownership of the files.
Default value: jboss.
JBOSS_GROUP
The system user group that the JBoss Enterprise Application Platform 6 files belong to.
Default value: jboss
JBOSS_START_WAIT
The number of seconds that the init script will wait until confirming that the server has launched successfully after receiving a start or restart command.
Default value: 60
JBOSS_SHUTDOWN_WAIT
The number of seconds that the init script will wait for the server to shutdown before continuing when it receives a stop or restart command.
Default value: 20
JBOSS_CONSOLE_LOG
The file that the CONSOLE log handler will be redirected to.
Default value: /var/log/jbossas/$JBOSSCONF/console.log
JAVA_HOME
The directory where your Java Runtime Environment is installed.
Default value: /usr/lib/jvm/jre
JBOSS_HOME
The directory where the application server files are installed.
Default value: /usr/share/jbossas
JAVAPTH
The path where the Java executable files are installed.
Default value: $JAVA_HOME/bin
JBOSSCONF
The server mode to launch this server in, standalone or domain.
Default value: standalone or domain depending on server mode.
JBOSSSH
The script which is used to launch to server.
Default value: $JBOSS_HOME/bin/$JBOSSCONF.sh
JBOSS_SERVER_CONFIG
The server configuration file to use.
Default value: standalone.xml or domain.xml or standalone or domain servers respectively.

4.6. Installation Structure and Details

JBoss Enterprise Application Platform 6 includes a simplified directory structure, compared to previous versions. Following is a listing of the directory structure, and a description of what the directory contains.

Table 4.3. Top-level directories and files

Name Purpose
appclient/ Contains configuration details for the application client container.
bin/ Contains start-up scripts for JBoss Enterprise Application Platform 6 on Red Hat Enterprise Linux and Microsoft Windows.
bundles/ Contains OSGi bundles which pertain to JBoss Enterprise Application Platform 6 internal functionality.
docs/ License files, schemas, and examples.
domain/ Configuration files, deployment content, and writable areas used when JBoss Enterprise Application Platform 6 runs as a managed domain.
modules/ Modules which are dynamically loaded by JBoss Enterprise Application Platform 6 when services request them.
standalone/ Configuration files, deployment content, and writable areas used when JBoss Enterprise Application Platform 6 runs as a standalone server.
welcome-content/ Contains content used by the Welcome web application which is available on port 8080 of a default installation.
jboss-modules.jar
The bootstrapping mechanism which loads modules.

Table 4.4. Directories within the domain/ directory

Name Purpose
configuration/ Configuration files for the managed domain. These files are modified by the Management Console and Management CLI, and are not meant to be edited directly.
data/ Information about deployed services. Services are deployed using the Management Console and Management CLI, rather than by a deployment scanner. Therefore, do not place files in this directory manually.
log/ Contains the run-time log files for the host and process controllers which run on the local instance.
servers/ Contains the equivalent data/, log/, and tmp/ directories for each server instance in a domain, which contain similar data to the same directories within the top-level domain/ directory.
tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the managed domain.

Table 4.5. Directories within the standalone/ directory

Name Purpose
configuration/ Configuration files for the standalone server. These files are modified by the Management Console and Management CLI, and are not meant to be edited directly.
deployments/ Information about deployed services. The standalone server does include a deployment scanner, so you can place archives in this directory to be deployed. However, the recommended approach is to manage deployments using the Management Console or Management CLI.
lib/ External libraries which pertain to a standalone server mode. Empty by default.
tmp/ Contains temporary data such as files pertaining to the shared-key mechanism used by the Management CLI to authenticate local users to the server.

Chapter 5. Upgrading JBoss Enterprise Application Platform 6

5.1. Upgrade the JBoss Enterprise Application Platform 6 ZIP Installation

Summary

Upgrading to JBoss Enterprise Application Platform 6.0.1 requires some initial work to back up the existing 6.0.0 installation. This topic covers upgrading the ZIP installation.

Prerequisites

Warning

For managed domains, the master Host Controller (or Domain Controller) instance should be upgraded first, before each Host Controller is upgraded.

Procedure 5.1. Upgrade to JBoss Enterprise Application Platform 6.0.1

  1. Move the 6.0.1 ZIP archive to the desired location. It is recommended that this is a different location to the JBoss Enterprise Application Platform 6.0.0 installation.

    Important

    If you wish to install JBoss Enterprise Application Platform 6.0.1 to the same directory location as 6.0.0, you will need to move the existing installation to a different location before proceeding. This is to prevent modified configuration files, deployments, and upgrades from 6.0.0 to 6.0.1 from being lost.
  2. Unzip the archive. This step installs a clean instance of JBoss Enterprise Application Platform 6.0.1.
  3. Copy the EAP_HOME/domain/ and EAP_HOME/standalone/ directories from the 6.0.0 installation over the 6.0.1 directories.
  4. Review the changes made to the bin directory of the 6.0.0 installation, and make the equivalent modifications to the 6.0.1 directory.

    Warning

    Files in the 6.0.1 bin directory should not be overwritten by the 6.0.0 files. Changes should be made manually.
  5. Review the remaining modified files from the 6.0.0 installation, and move these changes into the 6.0.1 installation. These files may include:
    • The welcome-content directory.
    • Custom modules in the modules directory.
    • Custom bundles in the bundles directory.
Result

The JBoss Enterprise Application Platform 6 ZIP installation has been successfully upgraded to the 6.0.1 release.

5.2. Upgrade the JBoss Enterprise Application Platform 6 RPM Installation

Summary

Upgrading to JBoss Enterprise Application Platform 6.0.1 requires some initial work to back up the existing 6.0.0 installation. This topic covers upgrading the RPM installation via the Red Hat Network (RHN).

Prerequisites

  • Ensure that the base operating system is up to date.
  • Ensure that the the jboss-eap6 RHN channel is enabled.
  • Back up any modified configuration files, deployments, and all user data.

Warning

For managed domains, the master Host Controller (or Domain Controller) instance should be upgraded first, before each Host Controller is upgraded.

Procedure 5.2. Upgrade to JBoss Enterprise Application Platform 6.0.1

  1. Run the following command in a terminal to upgrade the installation:
    [user@host] yum update
  2. Manually merge each created *.rpmnew file that contains changes into the production configuration files.
Result

JBoss Enterprise Application Platform 6 has been successfully upgraded to the 6.0.1 release.

Chapter 6. Running JBoss Enterprise Application Platform 6 as a Service

6.1. Run JBoss Enterprise Application Platform 6 as an Operating System Service

JBoss Enterprise Application Platform 6 can be configured to run as a service, allowing you to start a Managed Domain or Standalone Server configuration at system runtime, and allowing the server instance to continue to run when you log out of your local system.

6.2. Install JBoss Enterprise Application Platform as a Service in Red Hat Enterprise Linux

Summary

Use the following procedure to install JBoss Enterprise Application Platform 6 as a service on Red Hat Enterprise Linux.

Prerequisites

You need administrator access to complete this task.

Procedure 6.1. Task

  1. Copy the start-up script to the /etc/init.d/ directory

    The start-up script and an associated configuration file are located in the EAP_HOME/bin/init.d/ directory. Copy each of these files to the /etc/init.d/ directory.
    [user@host init.d]$ sudo cp jboss-as-standalone.sh jboss-as.conf /etc/init.d
  2. Add the start-up script as a service.

    Add the new jboss-as-standalone.sh service to list of automatically started services, using the chkconfig service management command.
    [user@host init.d]$ sudo chkconfig --add jboss-as-standalone.sh
  3. Edit the script options.

    If desired, edit the jboss-as.conf file to customize start-up options for JBoss Enterprise Application Platform and the JVM. Use the comments in the file as guidance. It is recommended to set the JBOSS_HOME variable in this file, to point to the directory where you extracted JBoss Enterprise Application Platform 6. Do not add a trailing slash (/) at the end of the directory name.
  4. Edit the script itself.

    You may need to edit the start-up script itself. It makes certain assumptions about the name of your start-up file and the location of your JBoss Enterprise Application Platform instance. Customize the script, paying special attention to the following variables, which you will need to customize to start JBoss Enterprise Application Platform 6 as a managed domain.
    • JBOSS_HOME - the location where JBoss Enterprise Application Platform 6 is extracted
    • JBOSS_USER - the user with the ability to run JBoss Enterprise Application Platform. This should be a non-privileged user, as no superuser privileges as required.
    • JBOSS_CONFIG - the name of the configuration file used to start JBoss Enterprise Application Platform 6, such as domain.xml or standalone.xml
    • JBOSS_SCRIPT - the script used to start JBoss Enterprise Application Platform 6, such as domain.sh or standalone.sh
  5. Start the service.

    If desired, start the new service using the standard syntax for starting Red Hat Enterprise Linux services.
    [user@host bin]$ sudo service jboss-as-standalone.sh start
Result

JBoss Enterprise Application Platform 6 starts automatically when the Red Hat Enterprise Linux reaches its default run-level, and stops automatically when the operating system goes through its shutdown routine.

6.3. Install JBoss Enterprise Application Platform 6 as a Service in Microsoft Windows

Summary

This task installs JBoss Enterprise Application Platform 6 as a service on Microsoft Windows.

Prerequisites

You need administrator access to complete this task.

Procedure 6.2. Task

  1. Download the Native Utilities package for your architecture.

    32-bit, 64-bit, and Itanium 64-bit packages are available from the Red Hat Customer Portal at https://access.redhat.com. For more information on downloading software from the Red Hat Customer Portal, refer to the JBoss Enterprise Application Platform 6 Installation Guide, available here: https://access.redhat.com/knowledge/docs/JBoss_Enterprise_Application_Platform/.
  2. Unzip the downloaded archive.

    Unzip the archive into a new folder.
    Result: The modules\native\bin\ folder is created.

    The modules\native\bin\ folder contains the files you need to install JBoss Enterprise Application Platform 6 as a service. These services are part of Procrun, which is a series of wrapper scripts provided by Apache Commons. To learn more about Procrun and its syntax, refer to the following link: http://commons.apache.org/daemon/procrun.html.

  3. Run the modules\sbin\prunsrv.exe executable.

    prunsrv.exe install path_to_startup_script
    Result

    The service is installed. JBoss Enterprise Application Platform 6 is listed in the Services applet services.msc.

  4. Manage your service.

    Use the modules\bin\prunmgr.exe executable to manage, edit, add, or delete services. The following command-line options are supported:
    • run
    • service
    • start
    • stop
    • update
    • install
    • delete
    • pause [seconds]
    • version
    • help
    The general syntax is:
    prunmgr.exe command service_name
Result

You can use the net service command at the command line, or the services.msc applet, to start, stop, and manage automatic start-up of JBoss Enterprise Application Platform 6 in Microsoft Windows Server.

Chapter 7. Getting Started with JBoss Enterprise Application Platform 6

7.1. Add the Initial User for the Management Interfaces

Overview

The management interfaces in JBoss Enterprise Application Platform 6 are secured by default, and there is no default user. This is a security precaution, to prevent security breaches from remote systems due to simple configuration errors. Local non-HTTP access is protected by a SASL mechanism, with a negotiation happening between the client and server each time the client connects for the first time from the localhost.

This task describes how to create the initial administrative user, which can use the web-based Management Console and remote instances of the Management CLI to configure and administer JBoss Enterprise Application Platform 6 from remote systems. For more information about the default security configuration, refer to Section 7.8, “Default User Security Configuration”.

Note

HTTP communication with JBoss Enterprise Application Platform 6 is considered to be remote access, even if the traffic originates on the localhost. Therefore, you must create at least one user in order to be able to use the management console. If you attempt to access the management console before adding a user, you will receive an error because it does not even deploy until the user is added.

Procedure 7.1. Task

  1. Invoke the add-user.sh or add-user.bat script.

    Change to the EAP_HOME/bin/ directory. Invoke the appropriate script for your operating system.
    Red Hat Enterprise Linux
    [user@host bin]$ ./add-user.sh
    Microsoft Windows Server
    C:\bin>  add-user.bat
  2. Choose to add a Management user.

    Select option a to add a Management user. This user is added to the ManagementRealm and is authorized to perform management operations using the web-based Management Console or command-line based Management CLI. The other choice, b, adds a user to the ApplicationRealm, and provides no particular permissions. That realm is provided for use with applications.
  3. Choose the realm for the user.

    The next prompt refers to the realm where the user will be added. For a user with permissions to manage JBoss Enterprise Application Platform 6, choose the default, which is ManagementRealm.
  4. Enter the desired username and password.

    When prompted, enter the security realm, username and password. Pressing ENTER selects the default realm of ManagementRealm, which allows the user to administer JBoss Enterprise Application Platform 6 using the management interfaces. You must add at least one user to this realm. You are prompted to confirm the information. If you are satisfied, type yes .
  5. Choose whether the user represents a remote JBoss Enterprise Application Platform 6 server instance.

    Besides administrators, the other type of user which occasionally needs to be added to JBoss Enterprise Application Platform 6 in the ManagementRealm is a user representing another instance of JBoss Enterprise Application Platform 6, which needs to be able to authenticate to join a cluster as a member. The next prompt allows you to designate your added user for this purpose. If you select yes, you will be given a hashed secret value, representing the user's password, which would need to be added to a different configuration file. For the purposes of this task, answer no to this question.
  6. Enter additional users.

    You can enter additional users if desired, by repeating the procedure. You can also add them at any time on a running system. Instead of choosing the default security realm, you can add users to other realms to fine-tune their authorizations.
  7. Create users non-interactively.

    You can create users non-interactively, by passing in each parameter at the command line. This approach is not recommended on shared systems, because the passwords will be visible in log and history files. The syntax for the command, using the management realm, is:
    [user@host bin]$ ./add-user.sh username password
    To use the application realm, use the -a parameter.
    [user@host bin]$ ./add-user.sh -a username password
Result

Any users you add are activated within the security realms you have specified. Users active within the ManagementRealm realm are able to manage JBoss Enterprise Application Platform 6 from remote systems.

7.3. Start JBoss Enterprise Application Platform 6 as a Managed Domain

Red Hat Enterprise Linux.
Run the command: EAP_HOME/bin/domain.sh
Microsoft Windows Server.
Run the command: EAP_HOME\bin\domain.bat
Optional: Pass additional parameters to the start-up script
For a list of parameters you can pass to the start-up script, use the -h parameter.
Result

The JBoss Enterprise Application Platform 6 Managed Domain instance starts.

7.4. Start JBoss Enterprise Application Platform 6 as a Standalone Server

Red Hat Enterprise Linux.
Run the command: EAP_HOME/bin/standalone.sh
Microsoft Windows Server.
Run the command: EAP_HOME\bin\standalone.bat
Optional: Specify additional parameters.
To print a list of additional parameters to pass to the start-up scripts, use the -h parameter.
Result

The JBoss Enterprise Application Platform 6 Standalone Server instance starts.

7.5. Test the Installation

  1. Look for error messages in the log files.

    After you start the server, view the log files in EAP_HOME/domain/log/ or EAP_HOME/standalone/log/.
    Result:

    If the server started properly, there will be no errors, and you will see output similar to the following:

    Example 7.1. Example of a successful start-up

    10:20:37,007 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss EAP 6.0.0.GA (AS 7.1.2.Final-redhat-1) started in 17942ms - Started 134 of 214 services (79 services are passive or on-demand)
    
    In a managed domain, you see a similar message for each locally-run server.
  2. Browse to the Management Console.

    If the installation worked properly and your server is running, you should be able to access the Management Console by pointing your web browser at an address similar to http://YOUR_SERVER:9990/, replacing YOUR_SERVER with a valid value.
    Result:

    The front page of the Management Console appears.

Result:

The Management Console is a deployable service. If you are able to reach it after starting the server, your installation is working properly and is able to deploy services.

7.6. Network Ports Used By JBoss Enterprise Application Platform 6

The ports used by the JBoss Enterprise Application Platform 6 default configuration depend on several factors:
  • Whether you use a managed domain or standalone server configuration.
  • Whether your server groups use one of the default socket binding groups, or a custom group.
  • The requirements of your individual deployments.

Note

A numerical port offset can be configured, to alleviate port conflicts when you run multiple servers on the same physical server. If your server uses a numerical port offset, add the offset to the default port number for its server group's socket binding group. For instance, if the HTTP port of the socket binding group is 8080, and your server uses a port offset of 100, its HTTP port is 8180.
Unless otherwise stated, the ports use the TCP protocol.

The default socket binding groups

  • full-ha-sockets
  • full-sockets
  • ha-sockets
  • standard-sockets

Table 7.1. Reference of the default socket bindings

Name Port Mulicast Port Description full-ha-sockets full-sockets ha-socket standard-socket
ajp 8009 Apache JServ Protocol. Used for HTTP clustering and load balancing. Yes Yes Yes Yes
http 8080 The default port for deployed web applications. Yes Yes Yes Yes
https 8443 SSL-encrypted connection between deployed web applications and clients. Yes Yes Yes Yes
jacorb 3528 CORBA services for JTS transactions and other ORB-dependent services. Yes Yes No No
jacorb-ssl 3529 SSL-encrypted CORBA services. Yes Yes No No
jgroups-diagnostics 7500 Multicast. Used for peer discovery in HA clusters. Yes No Yes No
jgroups-mping 45700 Multicast. Used to discover initial membership in a HA cluster. Yes No Yes No
jgroups-tcp 7600 Unicast peer discovery in HA clusters using TCP. Yes No Yes No
jgroups-tcp-fd 57600 Used for HA failure detection over TCP. Yes No Yes No
jgroups-udp 55200 45688 Unicast peer discovery in HA clusters using UDP. Yes No Yes No
jgroups-udp-fd 54200 Used for HA failure detection over UDP. Yes No Yes No
messaging 5445 JMS service. Yes Yes No No
messaging-group Referenced by HornetQ JMS broadcast and discovery groups. Yes Yes No No
messaging-throughput 5455 Used by JMS Remoting. Yes Yes No No
mod_cluster 23364 Multicast port for communication between the JBoss Enterprise Application Platform and the HTTP load balancer. Yes No Yes No
osgi-http 8090 Used by internal components which use the OSGi subsystem. Yes Yes Yes Yes
remoting 4447 Used for remote EJB invocation. Yes Yes Yes Yes
txn-recovery-environment 4712 The JTA transaction recovery manager. Yes Yes Yes Yes
txn-status-manager 4713 The JTA / JTS transation manager. Yes Yes Yes Yes
Management Ports

In addition to the socket binding groups, each host controller opens two more ports for management purposes:

  • 9990 - The Web Management Console port
  • 9999 - The port used by the Management Console and Management API

7.7. Configure Network Firewalls to Work with JBoss Enterprise Application Platform 6

Overview

Most production environments use firewalls as part of an overall network security strategy. If you need multiple server instances to communicate with each other or with external services such as web servers or databases, your firewall needs to take this into account. A well-managed firewall only opens the ports which are necessary to operation, and limits access to the ports to specific IP addresses, subnets, and network protocols.

A full discussion of firewalls is out of the scope of this documentation.

Prerequisites

  • Determine the ports you need to open. Refer to Section 7.6, “Network Ports Used By JBoss Enterprise Application Platform 6” to determine the list of ports for your situation.
  • An understanding of your firewall software is required. This procedure uses the system-config-firewall command in Red Hat Enterprise Linux 6. Microsoft Windows Server includes a built-in firewall, and several third-party firewall solutions are available for each platform.
Assumptions

This procedure configures a firewall in an environment with the following assumptions:

  • The operating system is Red Hat Enterprise Linux 6.
  • JBoss Enterprise Application Platform 6 runs on host 10.1.1.2. Optionally, the server has its own firewall.
  • The network firewall server runs on host 10.1.1.1 on interface eth0, and has an external interface eth1.
  • You want traffic on port 5445 (a port used by JMS) forwarded to JBoss Enterprise Application Platform 6. No other traffic should be allowed through the network firewall.

Procedure 7.2. Task

  1. Log into the Management Console.

    Log into the Management Console. By default, it runs on http://localhost:9990/console/.
  2. Managed Domain: Determine the socket binding group your server group uses.

    Each server group uses a socket binding group, which is a collection of socket bindings. A socket binding is a name-value pair of port name and number.
    To determine which socket binding group your server groups, click the Server Groups label at the top right side of the screen. Then click the name of your server group in the Available server group configurations table. The Server attributes area at the bottom of the screen is populated with the profile and socket binding group used by the server group.
  3. Determine the socket bindings used by the socket binding group.

    Click the Profiles label at the top right of the Management Console. At the left-hand side of the screen, a series of menus is shown. The bottom menu heading is General Configuration. Click the Socket Binding Groups item below this heading. The Socket Binding Declarations screen appears. Initially, the standard-sockets group is shown. You can choose a different group by selecting it from the combo box on the right-hand side.

    Note

    If you use a standalone server, it has only one socket binding group.
    The list of socket names and ports is shown, six values per page. You can go through the pages by using the arrow navigation below the table.
  4. Determine the ports you need to open.

    Depending on the function of the particular port and the needs of your environment, some of the ports may need to be accessible across your firewall. If you are unsure of the purpose of a socket binding, refer to Section 7.6, “Network Ports Used By JBoss Enterprise Application Platform 6” for a list of the default socket bindings and their purposes.
  5. Configure your firewall to forward traffic to JBoss Enterprise Application Platform 6.

    Perform these steps to configure your network firewall to allow traffic on the desired port.
    1. Log into your firewall machine and access a command prompt, as the root user.
    2. Issue the command system-config-firewall to launch the firewall configuration utility. A GUI or command-line utility launches, depending on the way you are logged into the firewall system. This task makes the assumption that you are logged in via SSH and using the command-line interface.
    3. Use the TAB key on your keyboard to navigate to the Customize button, and press the ENTER key. The Trusted Services screen appears.
    4. Do not change any values, but use the TAB key to navigate to the Forward button, and press ENTER to advanced to the next screen. The Other Ports screen appears.
    5. Use the TAB key to navigate to the <Add> button, and press ENTER. The Port and Protocol screen appears.
    6. Enter 5445 in the Port / Port Range field, then use the TAB key to move to the Protocol field, and enter tcp. Use the TAB key to navigate to the OK button, and press ENTER.
    7. Use the TAB key to navigate to the Forward button until you reach the Port Forwarding screen.
    8. Use the TAB key to navigate to the <Add> button, and press the ENTER key.
    9. Fill in the following values to set up port forwarding for port 5445.
      • Source interface: eth1
      • Protocol: tcp
      • Port / Port Range: 5445
      • Destination IP address: 10.1.1.2
      • Port / Port Range: 5445
      Use the TAB key to navigate to the OK button, and press ENTER.
    10. Use the TAB key to navigate to the Close button, and press ENTER.
    11. Use the TAB key to navigate to the OK button, and press ENTER. To apply the changes, read the warning and click Yes.
  6. Configure a firewall on your JBoss Enterprise Application Platform 6 host.

    Some organizations choose to configure a firewall on the JBoss Enterprise Application Platform 6 server itself, and close all ports that are not necessary for its operation. Consult Section 7.6, “Network Ports Used By JBoss Enterprise Application Platform 6” and determine which ports to open, then close the rest. The default configuration of Red Hat Enterprise Linux 6 closes all ports except 22 (used for Secure Shell (SSH) and 5353 (used for multicast DNS). While you are configuring ports, make sure you have physical access to your server so that you do not inadvertently lock yourself out.
Result

Your firewall is configured to forward traffic to your internal JBoss Enterprise Application Platform 6 server in the way you specified in your firewall configuration. If you chose to enable a firewall on your server, all ports are closed except the ones needed to run your applications.

7.8. Default User Security Configuration

Introduction

All management interfaces in JBoss Enterprise Application Platform 6 are secured by default. This security takes two different forms:

  • Local interfaces are secured by a SASL contract between local clients and the server they connect to. This security mechanism is based on the client's ability to access the local filesystem. This is because access to the local filesystem would allow the client to add a user or otherwise change the configuration to thwart other security mechanisms. This adheres to the principle that if physical access to the filesystem is achieved, other security mechanisms are superfluous. The mechanism happens in four steps:

    Note

    HTTP access is considered to be remote, even if you connect to the localhost using HTTP.
    1. The client sends a message to the server which includes a request to authenticate with the local SASL mechanism.
    2. The server generates a one-time token, writes it to a unique file, and sends a message to the client with the full path of the file.
    3. The client reads the token from the file and sends it to the server, verifying that it has local access to the filesystem.
    4. The server verifies the token and then deletes the file.
  • Remote clients, including local HTTP clients, use realm-based security. The default realm with the permissions to configure the JBoss Enterprise Application Platform 6 remotely using the management interfaces is ManagementRealm. A script is provided which allows you to add users to this realm (or realms you create). For more information on adding users, refer to the Getting Started chapter of the Installation guide for JBoss Enterprise Application Platform 6. For each user, the username, a hashed password, and the realm are stored in a file. The file is in a different location if the JBoss Enterprise Application Platform 6 is configured as a managed domain or a standalone server.
    Managed domain
    EAP_HOME/domain/configuration/mgmt-users.properties
    Standalone server
    EAP_HOME/standalone/configuration/mgmt-users.properties
    Even though the contents of the mgmt-users.properties are masked, the file should still be treated as a sensitive file. It is recommended that it be set to the file mode of 600, which gives no access other than read and write access by the file owner.

Chapter 8. Uninstalling JBoss Enterprise Application Platform 6

8.2. Uninstall JBoss Enterprise Application Platform 6 From a Zip Installation

  1. Log into the server.

    Log into your server as a user who has write access to the JBoss Enterprise Application Platform 6 installation directory.
  2. Remove the installation directory.

    JBoss Enterprise Application Platform 6 installs in a single directory when you use the Zip installation method. Delete the installation directory to uninstall JBoss Enterprise Application Platform 6.
  3. Optional: Remove any initialization scripts you created.

    If you created initialization scripts or other scripts which depended upon JBoss Enterprise Application Platform 6 being installed on your computer, remove them.
  4. Optional: Microsoft Windows: Remove JBoss Enterprise Application Platform 6 from your Services.

    To remove the JBoss Enterprise Application Platform 6 service, run the following command at a command prompt, as an administrative user: sc delete "JBEAP6SVC".
Result:

JBoss Enterprise Application Platform 6 is uninstalled from your server.

8.3. Uninstall JBoss Enterprise Application Platform 6 From a Graphical Installation

  1. Navigate to the EAP_HOME/Uninstaller/ directory on the server.

    During the installation of JBoss Enterprise Application Platform 6, a directory called EAP_HOME/Uninstaller/ was created. This directory contains a file called uninstaller.jar.
  2. Run the java -jar uninstaller.jar command.

    This command uninstalls JBoss Enterprise Application Platform 6.
Result:

JBoss Enterprise Application Platform 6 is uninstalled from your server.

8.4. Uninstall JBoss Enterprise Application Platform 6 From an RPM Installation

  1. Log into the server.

    Log into the server where JBoss Enterprise Application Platform 6 is installed and gain root access.
  2. Optional: Create a list of files and directories created by the RPM installation.

    To create a list of files and directories created by the RPM installation, run the command rpm -ql jboss-eap6 > /tmp/jbeap6.txt. The reason to do this step is because removing the RPM may not remove all of these files and directories from your system. You may need to remove some of them by hand.
  3. Remove the package with the yum command.

    Use the YUM groupremove command to remove the jboss-eap6 group.
    yum groupremove jboss-eap6
  4. Optional: Check for and remove files or directories that were not removed by the yum groupremove command.

    Check the list of files and directories created by the rpm -ql command above. Remove any that were not removed automatically.
Result

JBoss Enterprise Application Platform 6 is uninstalled from your server.

Appendix A. JBoss Enterprise Application Platform 6 RPM Packages

A.1. RPM Package List and Dependencies

JBoss Enterprise Application Platform 6 is installed on Red Hat Enterprise Linux 6 using the YUM package group JBoss EAP 6. That group is made up of the following packages.
  • jbossas-appclient
  • jbossas-bundles
  • jbossas-core
  • jbossas-domain
  • jbossas-hornetq-native
  • jbossas-jbossweb-native
  • jbossas-modules-eap
  • jbossas-product-eap
  • jbossas-standalone
  • jbossas-welcome-content-eap

Appendix B. Revision History

Revision History
Revision 0.1-1.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 0.1-1 Tue Dec 18 2012 Tom Wells
JBoss Enterprise Application Platform 6.0.1 Installation Guide.
Revision 0.0-16 Fri Dec 14 2012 Tom Wells
Bugzilla fixes and updated topics for the JBoss Enterprise Application Platform 6.0.1 Installation Guide.
Revision 0.0-15 Tue Dec 11 2012 Tom Wells
Updated build of the JBoss Enterprise Application Platform 6.0.1 Installation Guide.
Revision 0.0-14 Mon Dec 03 2012 Tom Wells
Updated build of the JBoss Enterprise Application Platform 6.0.1 Installation Guide.
Revision 0.0-13 Fri Nov 30 2012 Tom Wells
Updated build of the JBoss Enterprise Application Platform 6.0.1 Installation Guide.
Revision 0.0-12 Tue Nov 27 2012 Tom Wells
Bugzilla fixes, new topics, and structural changes for the JBoss Enterprise Application Platform 6 Installation Guide.
Revision 0.0-11 Tue Nov 13 2012 Tom Wells
Bugzilla fixes, new topics, and structural changes for the JBoss Enterprise Application Platform 6 Installation Guide.
Revision 0.0-10 Tue Oct 09 2012 Tom Wells
Release update. Bugzilla fixes, new topics, and structural changes for the JBoss Enterprise Application Platform 6 Installation Guide.
Revision 0.0-9 Wed Oct 03 2012 Tom Wells
Updated documentation. Includes revised RPM installation instructions, bugzilla fixes, and updated topics.
Revision 0.0-8 Fri Sept 28 2012 Tom Wells
Updated structure and bugzilla fixes for the Installation Guide.
Revision 0.0-7 Fri Sept 21 2012 Tom Wells
Bugzilla fixes for the Installation Guide.
Revision 0.0-6 Wed Sept 12 2012 Tom Wells
Bugzilla fixes and updated documentation for the Installation Guide.
Revision 0.0-5 Mon Sept 3 2012 Tom Wells
Bug fixes for the August asynchronous update to the Installation guide.
Revision 0.0-4 Mon Sept 3 2012 Tom Wells
Bug fixes for the August asynchronous update to the Installation guide.
Revision 0.0-3 Fri Aug 31 2012 Tom Wells
August update of the Installation guide for JBoss Enterprise Application Platform 6.
Revision 0.0-2 Fri Aug 31 2012 Tom Wells
Updated edition of the Installation guide for JBoss Enterprise Application Platform 6.0.0.
Revision 0.0-1 Wed Jun 20 2012 Tom Wells
First edition of the JBoss Enterprise Application Platform 6 Installation Guide.

Legal Notice

Copyright © 2012 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.