JBoss Enterprise Application Platform 6

Administration and Configuration Guide

For Use with JBoss Enterprise Application Platform 6

Edition 3

Nidhi Chaudhary

Russell Dickenson

Sande Gilda

Vikram Goyal

Eamon Logue

Darrin Mison

Scott Mumford

David Ryan

Misty Stanley-Jones

Keerat Verma

Tom Wells

Legal Notice

Copyright © 2013 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, MetaMatrix, 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.

Abstract

This book is a guide to the administration and configuration of JBoss Enterprise Application Platform 6 and its patch releases.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
1. Introduction to Administering the JBoss Enterprise Application Platform
1.1. Introducing JBoss Enterprise Application Platform 6
1.2. New and Changed Features in JBoss Enterprise Application Platform 6
2. Application Server Management
2.1. Manage the Application Server
2.2. Installation Structure and Details
2.3. JBoss Enterprise Application Platform 6 Profiles
2.4. About JBoss Enterprise Application Platform 6 Configuration Files
2.5. Management APIs
2.5.1. Management Application Programming Interfaces (APIs)
2.6. Start JBoss Enterprise Application Platform 6
2.6.1. Start JBoss Enterprise Application Platform 6
2.6.2. Start JBoss Enterprise Application Platform 6 as a Standalone Server
2.6.3. Start JBoss Enterprise Application Platform 6 as a Managed Domain
2.6.4. Start JBoss Enterprise Application Platform 6 with an Alternative Configuration
2.6.5. Stop JBoss Enterprise Application Platform 6
2.6.6. Reference of Switches and Arguments to pass at Server Runtime
2.7. Run JBoss Enterprise Application Platform 6 as a Service
2.7.1. Run JBoss Enterprise Application Platform 6 as an Operating System Service
2.7.2. Install JBoss Enterprise Application Platform as a Service in Red Hat Enterprise Linux
2.7.3. Install JBoss Enterprise Application Platform 6 as a Service in Microsoft Windows
2.8. Start and Stop Servers
2.8.1. Start and Stop Servers
2.8.2. Start a Server Using the Management Console
2.8.3. Stop a Server Using the Management Console
2.9. Filesystem Paths
2.9.1. Filesystem Paths
2.10. Configuration File History
2.10.1. Configuration File History
2.10.2. Start the Server with a Previous Configuration
2.10.3. Save a Configuration Snapshot Using the Management CLI
2.10.4. Load a Configuration Snapshot
2.10.5. Delete a Configuration Snapshot Using Management CLI
2.10.6. List All Configuration Snapshots Using Management CLI
3. Management Interfaces
3.1. About the Management Console and Management CLI
3.2. The Management Console
3.2.1. Management Console
3.2.2. Log in to the Management Console
3.2.3. Change the Language of the Management Console
3.2.4. Configure a Server Using the Management Console
3.2.5. Add a Deployment in the Management Console
3.2.6. Create a New Server in the Management Console
3.2.7. Change the Default Log Levels Using the Management Console
3.2.8. Create a New Server Group in the Management Console
3.3. The Management CLI
3.3.1. About the Management Command Line Interface (CLI)
3.3.2. Launch the Management CLI
3.3.3. Quit the Management CLI
3.3.4. Connect to a Managed Server Instance Using the Management CLI
3.3.5. Get Help with the Management CLI
3.3.6. Use the Management CLI in Batch Mode
3.3.7. Use Operations and Commands in the Management CLI
3.3.8. Reference of Management CLI Commands
3.3.9. Reference of Management CLI Operations
3.4. Management CLI Operations
3.4.1. Display the Attributes of a Resource with the Management CLI
3.4.2. Display the Active User in the Management CLI
3.4.3. Display System and Server Information in the Management CLI
3.4.4. Display an Operation Description using the Management CLI
3.4.5. Display the Operation Names using the Management CLI
3.4.6. Display Available Resources using the Management CLI
3.4.7. Display Available Resource Descriptions using the Management CLI
3.4.8. Reload the Application Server using the Management CLI
3.4.9. Shut the Application Server down using the Management CLI
3.4.10. Configure an Attribute with the Management CLI
3.5. The Management CLI Command History
3.5.1. Use the Management CLI Command History
3.5.2. Show the Management CLI Command history
3.5.3. Clear the Management CLI Command history
3.5.4. Disable the Management CLI Command history
3.5.5. Enable the Management CLI Command history
4. User Management
4.1. User Creation
4.1.1. Add the Initial User for the Management Interfaces
4.1.2. Add a User to the Management Interface
5. Network and Port Configuration
5.1. Interfaces
5.1.1. About Interfaces
5.1.2. Configure Interfaces
5.2. Socket Binding Groups
5.2.1. About Socket Binding Groups
5.2.2. Configure Socket Bindings
5.2.3. Network Ports Used By JBoss Enterprise Application Platform 6
5.2.4. About Port Offsets for Socket Binding Groups
5.2.5. Configure Port Offsets
5.3. IPv6
5.3.1. Configure JVM Stack Preferences for IPv6 Networking
5.3.2. Configure the Interface Declarations for IPv6 Networking
5.3.3. Configure JVM Stack Preferences for IPv6 Addresses
6. Datasource Management
6.1. Introduction
6.1.1. About JDBC
6.1.2. JBoss Enterprise Application Platform 6 Supported Databases
6.1.3. Types of Datasources
6.1.4. The Example Datasource
6.1.5. Deployment of -ds.xml files
6.2. JDBC Drivers
6.2.1. Install a JDBC Driver with the Management Console
6.2.2. Install a JDBC Driver as a Core Module
6.2.3. JDBC Driver Download Locations
6.2.4. Access Vendor Specific Classes
6.3. Non-XA Datasources
6.3.1. Create a Non-XA Datasource with the Management Interfaces
6.3.2. Modify a Non-XA Datasource with the Management Interfaces
6.3.3. Remove a Non-XA Datasource with the Management Interfaces
6.4. XA Datasources
6.4.1. Create an XA Datasource with the Management Interfaces
6.4.2. Modify an XA Datasource with the Management Interfaces
6.4.3. Remove an XA Datasource with the Management Interfaces
6.4.4. XA Recovery
6.5. Datasource Security
6.5.1. About Datasource Security
6.6. Datasource Configuration
6.6.1. Datasource Parameters
6.6.2. Datasource Connection URLs
6.6.3. Datasource Extensions
6.7. Example Datasources
6.7.1. Example PostgreSQL Datasource
6.7.2. Example PostgreSQL XA Datasource
6.7.3. Example MySQL Datasource
6.7.4. Example MySQL XA Datasource
6.7.5. Example Oracle Datasource
6.7.6. Example Oracle XA Datsource
6.7.7. Example Microsoft SQLServer Datasource
6.7.8. Example Microsoft SQLServer XA Datasource
6.7.9. Example IBM DB2 Datasource
6.7.10. Example IBM DB2 XA Datasource
6.7.11. Example Sybase Datasource
6.7.12. Example Sybase XA Datasource
7. Configuring Modules
7.1. Introduction
7.1.1. Modules
7.1.2. Global Modules
7.1.3. Module Dependencies
7.1.4. Subdeployment Class Loader Isolation
7.2. Disable Sub-Deployment Module Isolation for All Deployments
7.3. Add a module to all deployments
7.4. Reference
7.4.1. Included Modules
7.4.2. Dynamic Module Naming
8. Application Deployment
8.1. About Application Deployment
8.2. Deploy with the Management Console
8.2.1. Manage Application Deployment in the Management Console
8.2.2. Deploy an Application Using the Management Console
8.2.3. Undeploy an Application Using the Management Console
8.3. Deploy with the Management CLI
8.3.1. Manage Application Deployment in the Management CLI
8.3.2. Deploy an Application in a Managed Domain Using the Management CLI
8.3.3. Undeploy an Application in a Managed Domain Using the Management CLI
8.3.4. Deploy an Application in a Standalone Server Using the Management CLI
8.3.5. Undeploy an Application in a Standalone Server Using the Management CLI
8.4. Deploy with the Deployment Scanner
8.4.1. Manage Application Deployment in the Deployment Scanner
8.4.2. Deploy an Application to a Standalone Server Instance with the Deployment Scanner
8.4.3. Undeploy an Application to a Standalone Server Instance with the Deployment Scanner
8.4.4. Redeploy an Application to a Standalone Server Instance with the Deployment Scanner
8.4.5. Reference for Deployment Scanner Marker Files
8.4.6. Reference for Deployment Scanner Attributes
8.4.7. Configure the Deployment Scanner
8.4.8. Configure the Deployment Scanner with the Management CLI
8.5. Deploy with Maven
8.5.1. Manage Application Deployment with Maven
8.5.2. Deploy an Application with Maven
8.5.3. Undeploy an Application with Maven
9. Securing JBoss Enterprise Application Platform
9.1. About the Security Subsystem
9.2. About the Structure of the Security Subsystem
9.3. Configure the Security Subsystem
9.4. About Deep Copy Subject Mode
9.5. Enable Deep Copy Subject Mode
9.6. Security Domains
9.6.1. About Security Domains
9.6.2. About Picketbox
9.6.3. About Authentication
9.6.4. Configure Authentication in a Security Domain
9.6.5. About Authorization
9.6.6. Configure Authorization in a Security Domain
9.6.7. About Security Auditing
9.6.8. Configure Security Auditing
9.6.9. About Security Mapping
9.6.10. Configure Security Mapping in a Security Domain
9.6.11. Use a Security Domain in Your Application
9.6.12. Java Authorization Contract for Containers (JACC)
9.6.13. Java Authentication SPI for Containers (JASPI)
9.7. Management Interface Security
9.7.1. Default User Security Configuration
9.7.2. Overview of Advanced Management Interface Configuration
9.7.3. About LDAP
9.7.4. Use LDAP to Authenticate to the Management Interfaces
9.7.5. Disable the HTTP Management Interface
9.7.6. Remove Silent Authentication from the Default Security Realm
9.7.7. Disable Remote Access to the JMX Subsystem
9.7.8. Configure Security Realms for the Management Interfaces
9.8. Network Security
9.8.1. Secure the Management Interfaces
9.8.2. Specify Which Network Interface the JBoss Enterprise Application Platform Uses
9.8.3. Configure Network Firewalls to Work with JBoss Enterprise Application Platform 6
9.8.4. Network Ports Used By JBoss Enterprise Application Platform 6
9.9. Java Security Manager
9.9.1. About the Java Security Manager
9.9.2. Run JBoss Enterprise Application Platform Within the Java Security Manager
9.9.3. About Java Security Manager Policies
9.9.4. Write a Java Security Manager Policy
9.9.5. Debug Security Manager Policies
9.10. Application Security
9.10.1. Enabling/Disabling Descriptor Based Property Replacement
9.11. Password Vaults for Sensitive Strings
9.11.1. About Securing Sensitive Strings in Clear-Text Files
9.11.2. Create a Java Keystore to Store Sensitive Strings
9.11.3. Mask the Keystore Password and Initialize the Password Vault
9.11.4. Configure the JBoss Enterprise Application Platform to Use the Password Vault
9.11.5. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore
9.11.6. Store and Resolve Sensitive Strings In Your Applications
10. Security Administration Reference
10.1. Included Authentication Modules
10.2. Included Authorization Modules
10.3. Included Security Mapping Modules
10.4. Included Security Auditing Provider Modules
11. The Logging Subsystem
11.1. Introduction
11.1.1. Overview of Logging
11.1.2. Application Logging Frameworks Supported By JBoss LogManager
11.1.3. Configure Boot Logging
11.1.4. Default Log File Locations
11.1.5. About Log Levels
11.1.6. Supported Log Levels
11.1.7. About Log Categories
11.1.8. About the Root Logger
11.1.9. About Log Handlers
11.1.10. Types of Log Handlers
11.1.11. About Log Formatters
11.1.12. Log Formatter Syntax
11.2. Configure Logging in the Management Console
11.3. Logging Configuration in the CLI
11.3.1. Configure the Root Logger with the CLI
11.3.2. Configure a Log Category in the CLI
11.3.3. Configure a Console Log Handler in the CLI
11.3.4. Configure a File Log Handler in the CLI
11.3.5. Configure a Periodic Log Handler in the CLI
11.3.6. Configure a Size Log Handler in the CLI
11.3.7. Configure a Async Log Handler in the CLI
11.4. Logging Configuration Properties
11.4.1. Root Logger Properties
11.4.2. Log Category Properties
11.4.3. Console Log Handler Properties
11.4.4. File Log Handler Properties
11.4.5. Periodic Log Handler Properties
11.4.6. Size Log Handler Properties
11.4.7. Async Log Handler Properties
11.5. Sample XML Configuration for Logging
11.5.1. Sample XML Configuration for the Root Logger
11.5.2. Sample XML Configuration for a Log Category
11.5.3. Sample XML Configuration for a Console Log Handler
11.5.4. Sample XML Configuration for a File Log Handler
11.5.5. Sample XML Configuration for a Periodic Log Handler
11.5.6. Sample XML Configuration for a Size Log Handler
11.5.7. Sample XML Configuration for a Async Log Handler
12. JVM
12.1. About JVM
12.1.1. About JVM Settings
12.1.2. Display the JVM Status in the Management Console
13. HTTP Clustering and Load Balancing
13.1. Introduction
13.1.1. About High-Availability and Load Balancing Clusters
13.1.2. Components Which Can Benefit from High Availability
13.1.3. Overview of HTTP Connectors
13.1.4. Worker Node
13.2. General Configuration
13.2.1. Subsystem Configuration Overview
13.2.2. Configure the Web Subsystem
13.2.3. Implement SSL Encryption for the JBoss Enterprise Application Platform Web Server
13.2.4. Generate a SSL Encryption Key and Certificate
13.2.5. SSL Connector Reference
13.2.6. About Web Service Endpoints
13.2.7. Replace the Default Welcome Web Application
13.2.8. About the Stand-Alone HTTPD
13.2.9. Install the Apache HTTPD included with JBoss Enterprise Application Platform 6
13.2.10. Use an External HTTPD as the Web Front-end for JBoss Enterprise Application Platform Applications
13.2.11. Configure the JBoss Enterprise Application Platform to Accept Requests From an External HTTPD
13.2.12. Use TCP Communication for the Clustering Subsystem
13.2.13. Configure the JGroups Subsystem to Use TCP
13.2.14. Configure the mod_cluster Subsystem to Use TCP
13.3. Web, HTTP Connectors, and HTTP Clustering
13.3.1. About the mod_cluster HTTP Connector
13.3.2. Configure the mod_cluster Subsystem
13.3.3. Install the mod_cluster Module Into Apache HTTPD or Enterprise Web Server HTTPD
13.3.4. Configure Server Advertisement Properties for Your mod_cluster-enabled HTTPD
13.3.5. Configure a mod_cluster Worker Node
13.4. Apache mod_jk
13.4.1. About the Apache mod_jk HTTP Connector
13.4.2. Configure the JBoss Enterprise Application Platform to Communicate with Apache Mod_jk
13.4.3. Install the Mod_jk Module Into Apache HTTPD or Enterprise Web Server HTTPD
13.4.4. Configuration Reference for Apache Mod_jk Workers
13.5. Apache mod_proxy
13.5.1. About the Apache mod_proxy HTTP Connector
13.5.2. Install the Mod_proxy HTTP Connector Into Apache HTTPD
13.6. Microsoft ISAPI
13.6.1. About the Internet Server API (ISAPI) HTTP Connector
13.6.2. Configure Microsoft IIS to Use the ISAPI Redirector
13.6.3. Configure the ISAPI Redirector to Send Client Requests to the JBoss Enterprise Application Platform
13.6.4. Configure ISAPI to Balance Client Requests Across Multiple JBoss Enterprise Application Platform Servers
13.7. Oracle NSAPI
13.7.1. About the Netscape Server API (NSAPI) HTTP Connector
13.7.2. Configure the NSAPI Connector on Oracle Solaris
13.7.3. Configure NSAPI as a Basic HTTP Connector
13.7.4. Configure NSAPI as a Load-balancing Cluster
14. Messaging
14.1. HornetQ
14.1.1. HornetQ
14.1.2. About Java Messaging Service (JMS)
14.1.3. Supported Messaging Styles
14.1.4. About Acceptors and Connectors
14.1.5. About Bridges
14.1.6. Work with Large Messages
14.1.7. Configure High-availability (HA) Failover
14.1.8. Embed HornetQ in Applications
14.1.9. Configure the JMS Server
14.1.10. About Java Naming and Directory Interface (JNDI)
14.1.11. Configure JNDI for HornetQ
14.1.12. Configure JMS Address Settings
14.1.13. Reference for HornetQ Configuration Attributes
14.1.14. Configure Messaging with HornetQ
14.1.15. Configure Delayed Redelivery
14.1.16. Configure Dead Letter Addresses
14.1.17. Configure Message Expiry Addresses
14.1.18. Set Message Expiry
15. Transaction Subsystem
15.1. Transaction Subsystem Configuration
15.1.1. Transactions Configuration Overview
15.1.2. Configure the Transaction Manager
15.1.3. Configure Your Datasource to Use JTA Transactions
15.1.4. Configure an XA Datasource
15.1.5. About Transaction Log Messages
15.1.6. Configure Logging for the Transaction Subsystem
15.2. Transaction Administration
15.2.1. Browse and Manage Transactions
15.3. Transaction References
15.3.1. JBoss Transactions Errors and Exceptions
15.3.2. JTA Clustering Limitations
15.4. ORB Configuration
15.4.1. About Common Object Request Broker Architecture (CORBA)
15.4.2. Configure the ORB for JTS Transactions
16. Enterprise JavaBeans
16.1. Introduction
16.1.1. Overview of Enterprise JavaBeans
16.1.2. Overview of Enterprise JavaBeans for Administrators
16.1.3. Enterprise Beans
16.1.4. Session Beans
16.1.5. Message-Driven Beans
16.2. Configuring Bean Pools
16.2.1. Bean Pools
16.2.2. Create a Bean Pool
16.2.3. Remove a Bean Pool
16.2.4. Edit a Bean Pool
16.2.5. Assign Bean Pools for Session and Message-Driven Beans
16.3. Configuring EJB Thread Pools
16.3.1. Enterprise Bean Thread Pools
16.3.2. Create a Thread Pool
16.3.3. Remove a Thread Pool
16.3.4. Edit a Thread Pool
16.4. Configuring Session Beans
16.4.1. Session Bean Access Timeout
16.4.2. Set Default Session Bean Access Timeout Values
16.5. Configuring Message-Driven Beans
16.5.1. Set Default Resource Adapter for Message-Driven Beans
16.6. Configuring the EJB3 Timer Service
16.6.1. EJB3 Timer Service
16.6.2. Configure the EJB3 timer Service
16.7. Configuring the EJB Asynchronous Invocation Service
16.7.1. EJB3 Asynchronous Invocation Service
16.7.2. Configure the EJB3 Asynchronous Invocation Service Thread Pool
16.8. Configuring the EJB3 Remote Invocation Service
16.8.1. EJB3 Remote Service
16.8.2. Configure the EJB3 Remote Service
16.9. Configuring EJB 2.x Entity Beans
16.9.1. EJB Entity Beans
16.9.2. Container-Managed Persistence
16.9.3. Enable EJB 2.x Container-Managed Persistence
16.9.4. Configure EJB 2.x Container-Managed Persistence
16.9.5. CMP Subsystem Properties for HiLo Key Generators
17. Java Connector Architecture (JCA)
17.1. Introduction
17.1.1. About the Java EE Connector API (JCA)
17.1.2. Java Connector Architecture (JCA)
17.1.3. Resource Adapters
17.2. Configure the Java Connector Architecture (JCA) Subsystem
17.3. Deploy a Resource Adapter
17.4. Configure a Deployed Resource Adapter
17.5. Resource Adapter Descriptor Reference
17.6. Deploy the WebSphere MQ Resource Adapter
18. Deploy JBoss Enterprise Application Platform 6 on Amazon EC2
18.1. Introduction
18.1.1. About Amazon EC2
18.1.2. About Amazon Machine Instances (AMIs)
18.1.3. About JBoss Cloud Access
18.1.4. JBoss Cloud Access Features
18.1.5. Supported Amazon EC2 Instance Types
18.1.6. Supported Red Hat AMIs
18.2. Deploying JBoss Enterprise Application Platform 6 on Amazon EC2
18.2.1. Overview of Deploying JBoss Enterprise Application Platform 6 on Amazon EC2
18.2.2. Non-clustered JBoss Enterprise Application Platform 6
18.2.3. Clustered JBoss Enterprise Application Platform 6
18.3. Establishing Monitoring with JBoss Operations Network (JON)
18.3.1. About AMI Monitoring
18.3.2. About Connectivity Requirements
18.3.3. About Network Address Translation (NAT)
18.3.4. About Amazon EC2 and DNS
18.3.5. About Routing in EC2
18.3.6. About Terminating and Restarting with JON
18.3.7. Configure an Instance to Register with JBoss Operations Network
18.4. User Script Configuration
18.4.1. Permanent Configuration Parameters
18.4.2. Custom Script Parameters
18.5. Troubleshooting
18.5.1. About Troubleshooting Amazon EC2
18.5.2. Diagnostic Information
19. Supplemental References
19.1. Download Files From the Red Hat Customer Portal
19.2. Configure the Default JDK on Red Hat Enterprise Linux
A. Revision History

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Getting Help and Giving Feedback

2.1. Do You Need Help?

If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can:
  • search or browse through a knowledgebase of technical support articles about Red Hat products.
  • submit a support case to Red Hat Global Support Services (GSS).
  • access other product documentation.
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

2.2. Give us Feedback

If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product JBoss Enterprise Application Platform 6 and the component doc-Administration_and_Configuration_Guide. The following link will take you to a pre-filled bug report for this product: https://bugzilla.redhat.com/.
Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly.
Document URL:


Section Number and Name:


Describe the issue:


Suggestions for improvement:


Additional information:


Be sure to give us your name so that you can receive full credit for reporting the issue.

Chapter 1. Introduction to Administering the JBoss Enterprise Application Platform

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

  • JBoss Enterprise Application Platform 6 is a certified implementation of the Java Enterprise Edition 6 Full Profile and Web Profile specifications.
  • A Managed Domain provides 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 can all be managed per server group.
  • The Management Console and Management CLI are brand new interfaces for managing your domain or standalone JBoss Enterprise Application Platform 6 instance. There is no longer any need to edit XML configuration files by hand. The Management CLI even offers batch mode, so that you can script and automate management tasks.
  • Application security, including security domains, are managed centrally for simplified configuration.
  • The directory layout of JBoss Enterprise Application Platform 6 has been simplified. 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.
  • The classloading mechanism has been made completely modular, so that modules are loaded and unloaded on demand. This provides performance and security benefits, as well as very fast start-up and restart times.
  • Datasource management is streamlined. Database drivers can be deployed just like other services. In addition, datasources are created and managed directly in the Management Console or Management CLI.
  • JBoss Enterprise Application Platform 6 starts and stops very quickly, which is especially beneficial to developers. It uses fewer resources and is extremely efficient in its use of system resources.

Chapter 2. Application Server Management

2.1. Manage the Application Server
2.2. Installation Structure and Details
2.3. JBoss Enterprise Application Platform 6 Profiles
2.4. About JBoss Enterprise Application Platform 6 Configuration Files
2.5. Management APIs
2.5.1. Management Application Programming Interfaces (APIs)
2.6. Start JBoss Enterprise Application Platform 6
2.6.1. Start JBoss Enterprise Application Platform 6
2.6.2. Start JBoss Enterprise Application Platform 6 as a Standalone Server
2.6.3. Start JBoss Enterprise Application Platform 6 as a Managed Domain
2.6.4. Start JBoss Enterprise Application Platform 6 with an Alternative Configuration
2.6.5. Stop JBoss Enterprise Application Platform 6
2.6.6. Reference of Switches and Arguments to pass at Server Runtime
2.7. Run JBoss Enterprise Application Platform 6 as a Service
2.7.1. Run JBoss Enterprise Application Platform 6 as an Operating System Service
2.7.2. Install JBoss Enterprise Application Platform as a Service in Red Hat Enterprise Linux
2.7.3. Install JBoss Enterprise Application Platform 6 as a Service in Microsoft Windows
2.8. Start and Stop Servers
2.8.1. Start and Stop Servers
2.8.2. Start a Server Using the Management Console
2.8.3. Stop a Server Using the Management Console
2.9. Filesystem Paths
2.9.1. Filesystem Paths
2.10. Configuration File History
2.10.1. Configuration File History
2.10.2. Start the Server with a Previous Configuration
2.10.3. Save a Configuration Snapshot Using the Management CLI
2.10.4. Load a Configuration Snapshot
2.10.5. Delete a Configuration Snapshot Using Management CLI
2.10.6. List All Configuration Snapshots Using Management CLI

2.1. Manage the Application Server

JBoss Enterprise Application Platform 6 offers you multiple management tools to configure and administer your implementation as you require. These include the new Management Console or the Management Command Line Interface (CLI), as examples of the underlying Management API that enables expert users to develop their own tools if they desire.

2.2. 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 2.1. 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 2.2. 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 2.3. 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.

2.3. JBoss Enterprise Application Platform 6 Profiles

The concept of profiles that was used in previous versions of JBoss Enterprise Application Platform is no longer used. JBoss Enterprise Application Platform 6 now uses a small number of configuration files to hold all information about its configuration.
Modules and drivers are loaded on an as-needed basis, so the concept of a default profile which was used in previous versions of JBoss Enterprise Application Platform 6, where profiles were used to make the server start more efficiently, does not apply. At deployment time, module dependencies are determined, ordered, and resolved by the server or domain controller, and loaded in the correct order. During undeployment, modules are unloaded when no deployment needs them any longer.
It is possible to disable modules or undeploy drivers or other services manually by removing the subsystems from the configuration. However, for most cases this is unnecessary. If none of your applications use a module, it will not be loaded.

2.4. About JBoss Enterprise Application Platform 6 Configuration Files

The configuration for JBoss Enterprise Application Platform 6 has changed considerably from previous versions. One of the most obvious differences is the use of a simplified configuration file structure, which includes one or more of the files listed below.

Table 2.4. Configuration File Locations

Server mode Location Purpose
domain.xml EAP_HOME/domain/configuration/domain.xml This is the main configuration file for a managed domain. Only the domain master reads this file. On other domain members, it can be removed.
host.xml EAP_HOME/domain/configuration/host.xml This file includes configuration details specific to a physical host in a managed domain, such as network interfaces, socket bindings, the name of the host, and other host-specific details. The host.xml file includes all of the features of both host-master.xml and host-slave.xml, which are described below. This file is not present for standalone servers.
host-master.xml EAP_HOME/domain/configuration/host-master.xml This file includes only the configuration details necessary to run a server as a managed domain master server. This file is not present for standalone servers.
host-slave.xml EAP_HOME/domain/configuration/host-slave.xml This file includes only the configuration details necessary to run a server as a managed domain slave server. This file is not present for standalone servers.
standalone.xml EAP_HOME/standalone/configuration/standalone.xml This is the default configuration file for a standalone server. It contains all information about the standalone server, including subsystems, networking, deployments, socket bindings, and other configurable details.
standalone-ha.xml EAP_HOME/standalone/configuration/standalone-ha.xml This configuration file enables the mod_cluster and JGroups subsystems for a standalone server, so that it can participate in a high-availability or load-balancing cluster. This file is not necessary for a managed domain.

These are only the default locations. You can specify a different configuration file at run-time.

2.5. Management APIs

2.5.1. Management Application Programming Interfaces (APIs)

Management clients
JBoss Enterprise Application Platform 6 offers three different approaches to configure and manage servers, being a web interface, a command line client and a set of XML configuration files. While the recommended methods for editing the configuration file include the Management Console and Management CLI, edits made to the configuration by all three are always synchronized across the different views and finally persisted to the XML files. Note that edits made to the XML configuration files while a server instance is running will be overwritten by the server model.
HTTP API
The Management Console is an example of a web interface built with the Google Web Toolkit (GWT). The Management Console communicates with the server using the HTTP management interface. The HTTP API endpoint is the entry point for management clients that rely on the HTTP protocol to integrate with the management layer. It uses a JSON encoded protocol and a de-typed, RPC-style API to describe and execute management operations against a Managed Domain or Standalone Server. The HTTP API is used by the web console, but offers integration capabilities for a wide range of other clients too.
The HTTP API endpoint is co-located with either the domain controller or a Standalone Server instance. The HTTP API Endpoint serves two different contexts; one for executing management operations and the other to access the web interface. By default, it runs on port 9990.

Example 2.1. HTTP API Configuration File Example

<management-interfaces>
    [...]
    <http-interface interface="management" port="9990"/>
<management-interfaces>

The web console is served through the same port as the HTTP management API. It is important to distinguish between the Management Console accessed as on a default localhost, the Management Console as accessed remotely by a specific host and port combination, and the exposed domain API.

Table 2.5. TableTitle

URL Description
http://localhost:9990/console The Management Console accessed on the local host, controlling the Managed Domain configuration.
http://hostname:9990/console The Management Console accessed remotely, naming the host and controlling the Managed Domain configuration.
http://hostname:9990/management The HTTP Management API runs on the same port as the Management Console, displaying the raw attributes and values exposed to the API.

Native API
An example of a Native API tool is the Management CLI. This management tool is available for a Managed Domain or Standalone Server instance, allowing the a user to connect to the domain controller or a Standalone Server instance and execute management operations available through the de-typed management model.
The Native API endpoint is the entry point for management clients that rely on the native protocol to integrate with the management layer. It uses an open binary protocol and an RPC-style API based on a very small number of Java types to describe and execute management operations. It's used by the Management CLI management tool, but offers integration capabilities for a wide range of other clients too.
The Native API endpoint is co-located with either a host controller or a Standalone Server. It must be enabled to use the Management CLI. By default, it runs on port 9999.

Example 2.2. Native API Configuration File Example

<management-interfaces>
    <native-interface interface="management" port="9999"/>
    [...]
<management-interfaces>

2.6. Start JBoss Enterprise Application Platform 6

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

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

2.6.4. Start JBoss Enterprise Application Platform 6 with an Alternative Configuration

Task Summary
If you do not specify a configuration file, the server starts with the default file. However, when you start the server, you can specify a configuration manually. The process varies slightly, depending on whether you are using a Managed Domain or Standalone Server, and depending on which operating system you are using.
Task Prerequisites
Before using an alternate configuration file, prepare it using the default configuration as a template. For a Managed Domain, the configuration file needs to be placed in EAP_HOME/domain/configuration/. For a Standalone Server, the configuration file should be placed in EAP_HOME/standalone/configuration/.

Example configurations

Several example configurations are included in the configuration directories. Use these examples to enable extra features such as clustering or the Transactions XTS API.
  1. Managed Domain

    For a Managed Domain, provide the file name of the configuration file as an option to the --domain-config parameter. You do not need to give the full path, if the configuration file resides in the EAP_HOME/domain/configuration/ directory.

    Example 2.3. Using an alternate configuration file for a Managed Domain in Red Hat Enterprise Linux

    [user@host bin]$ ./domain.sh --domain-config=domain-alternate.xml

    Example 2.4. Using an alternate configuration file for a Managed Domain in Microsoft Windows Server

    C:\EAP_HOME\bin> domain.bat --domain-config=domain-alternate.xml

  2. Standalone server

    For a Standalone Server, provide the filename of the configuration file as an option to the --server-config parameter. You do not need to give the full path to the configuration file if it is in the EAP_HOME/standalone/configuration/ directory.

    Example 2.5. Using an alternate configuration file for a Standalone Server in Red Hat Enterprise Linux

    [user@host bin]$ ./standalone.sh --server-config=standalone-alternate.xml

    Example 2.6. Using an alternate configuration file for a Standalone Server in Microsoft Windows Server

    C:\EAP_HOME\bin> standalone.bat --server-config=standalone-alternate.xml

Result:
JBoss Enterprise Application Platform 6 is now running, using your alternate configuration.

2.6.5. Stop JBoss Enterprise Application Platform 6

Task Summary:
The way that you stop JBoss Enterprise Application Platform 6 depends on how it was started. This task covers stopping an instance that was started interactively, stopping an instance that was started by a service, and stopping an instance that was forked into the background by a script.

Note

This task does not address stopping a server or server group in a Managed Domain. For those scenarios, see Section 2.8.3, “Stop a Server Using the Management Console”.

Procedure 2.1. Task:

  1. Stop an instance which was started interactively from a command prompt.

    Press Ctrl-C in the terminal where JBoss Enterprise Application Platform 6 is running.
  2. Stop an instance which was started as an operating system service.

    Depending on your operating system, use one of the following procedures.
    • Red Hat Enterprise Linux

      For Red Hat Enterprise Linux, if you have written a service script, use its stop facility. This needs to be written into the script. Then you can use service scriptname stop, where scriptname is the name of your script.
    • Microsoft Windows Server

      In Microsoft Windows, use the net service command, or stop the service from the Services applet in the Control Panel.
  3. Stop an instance which is running in the background (Red Hat Enterprise Linux)

    1. Locate the instance from the process list. One option is to run the command ps aux |grep "[j]ava -server". This returns one result for each JBoss Enterprise Application Platform 6 instance that is running on the local machine.
    2. Send the process the TERM signal, by running kill process_ID, where process_ID is the number in the second field of the ps aux command above.
Result:
Each of these alternatives shuts JBoss Enterprise Application Platform 6 down cleanly so that data is not lost.

2.6.6. Reference of Switches and Arguments to pass at Server Runtime

The application server startup script accepts the addition of arguments and switches at runtime. The use of these parameters allows for the server to be started under alternative configurations to those defined in the standalone.xml, domain.xml and host.xml configuration files. This might include starting the server with an alternative set of socket bindings or a secondary configuration. A list of these available parameters can be accessed by passing the help switch at startup.

Example 2.7. 

The following example is similar to the server startup explained in Section 2.6.2, “Start JBoss Enterprise Application Platform 6 as a Standalone Server”, with the addition of the -h or --help switches. The results of the help switch are explained in the table below.
[localhost bin]$ standalone.sh -h

Table 2.6. Table of runtime switches and arguments

Argument or Switch Description
--admin-only Set the server's running type to ADMIN_ONLY. This will cause it to open administrative interfaces and accept management requests, but not start other runtime services or accept end user requests.
-b=<value> Set system property jboss.bind.address to the given value.
-b <value> Set system property jboss.bind.address to the given value.
-b<interface>=<value> Set system property jboss.bind.address.<interface> to the given value.
-c=<config> Name of the server configuration file to use. The default is standalone.xml.
-c <config> Name of the server configuration file to use. The default is standalone.xml.
-D<name>[=<value>] Set a system property.
-h Display the help message and exit.
--help Display the help message and exit.
-P=<url> Load system properties from the given URL.
-P <url> Load system properties from the given URL.
--properties=<url> Load system properties from the given URL.
-S<name>[=<value>] Set a security property.
--server-config=<config> Name of the server configuration file to use. The default is standalone.xml.
-u=<value> Set system property jboss.default.multicast.address to the given value.
-u <value> Set system property jboss.default.multicast.address to the given value.
-V Display the application server version and exit.
-v Display the application server version and exit.
--version Display the application server version and exit.

2.7. Run JBoss Enterprise Application Platform 6 as a Service

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

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

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

2.8. Start and Stop Servers

2.8.1. Start and Stop Servers

You can start and stop servers with the Management CLI or the Management Console.
If you are running a Standalone Server instance, you can shut the server down with the shutdown operation in the Management CLI. There is no specific equivalent in the Management Console, as you are free to use your filesystem to shut down the running instance.
If you are running a Managed Domain, the Management Console allows you to selectively start or stop specific servers in the domain. The Management CLI allows you to start all inactive servers, and stop any servers currently running. Like with the Standalone Server instance, the shutdown operation will shut down the server, in this case specifically the domain controller, all host controllers and their server instances.

2.8.2. Start a Server Using the Management Console

Procedure 2.4. Task

  1. Navigate to Server Instances in the Management Console

    1. Select the Runtime tab from the top-right of the console.
    2. Select Domain StatusServer Instances from the menu on the left of the console.
    Server Instances

    Figure 2.1. Server Instances


  2. Select a server

    From the list of Server Instances, select the server you want to start. Servers that are running are indicated by a check mark.
  3. Click the Start button

    Click on the Start button above the server list to open the confirmation dialogue box. Click the Confirm button to start the server.
    Confirm server modification

    Figure 2.2. Confirm server modification


Result
The selected server is started and running.
Started server

Figure 2.3. Started server


2.8.3. Stop a Server Using the Management Console

Procedure 2.5. Task

  1. Navigate to Server Instances in the Management Console

    1. Select the Runtime tab from the top-right of the console.
    2. Select Domain StatusServer Instances from the menu on the left of the console.
    Server Instances

    Figure 2.4. Server Instances


  2. Select a server

    From the list of Server Instances, select the server you want to stop. Servers that are running are indicated by a check mark.
  3. Click the Stop button

    Click on the Stop button above the server list to open the confirmation dialogue box. Click the Confirm button to start the server.
    Confirm server modification

    Figure 2.5. Confirm server modification


Result
The selected server is stopped.
Stopped server

Figure 2.6. Stopped server


2.9. Filesystem Paths

2.9.1. Filesystem Paths

JBoss Enterprise Application Platform 6 uses logical names for a filesystem paths. The domain.xml, host.xml and standalone.xml configurations all include a section where paths can be declared. Other sections of the configuration can then reference those paths by their logical name, avoiding the declaration of the absolute path for each instance. This benefits configuration and administration efforts as it allows specific host configurations to resolve to universal logical names.
For example, the logging subsystem configuration includes a reference to the jboss.server.log.dir path that points to the server's log directory.

Example 2.8. Relative path example for the logging directory

<file relative-to="jboss.server.log.dir" path="server.log"/>

JBoss Enterprise Application Platform 6 automatically provides a number of standard paths without any need for the user to configure them in a configuration file.

Table 2.7. Standard Paths

Value Description
jboss.home The root directory of the JBoss EAP 6 distribution.
user.home The user home directory.
user.dir The user's current working directory.
java.home The Java installation directory
jboss.server.base.dir The root directory for an individual server instance.
jboss.server.data.dir The directory the server will use for persistent data file storage.
jboss.server.log.dir The directory the server will use for log file storage.
jboss.server.tmp.dir The directory the server will use for temporary file storage.
jboss.domain.servers.dir The directory under which a host controller will create the working area for individual server instances in a managed domain.

Users can add their own paths or override all except the first five of the above by adding a path element to their configuration file. The following example shows a new relative path declaration relative to the root directory for the individual server instance.

Example 2.9. Format of a relative path

<path name="examplename" path="example/path" relative-to="jboss.server.data.dir"/>

The structure of a path declaration uses the following attributes.

Table 2.8. Path Attributes

Attribute Description
name The name of the path.
path The actual filesystem path. Treated as an absolute path, unless the relative-to attribute is specified, in which case the value is treated as relative to that path.
relative-to An optional attribute indicating the name of another previously named path, or of one of the standard paths provided by the system.

A path element in a domain.xml configuration file only requires the name attribute. It does not need to include any information indicating what the actual filesystem path is, as shown in the following example.

Example 2.10. Domain path example

<path name="example"/>

This configuration simply declares that there is a path named example that the other parts of the domain.xml configuration can reference. The actual filesystem location declared by example is specific to the respective host.xml configuration files of the host instances joining the domain groups. If this approach is used, there must be a path element in each machine's host.xml that specifies what the actual filesystem path is.

Example 2.11. Host path example

<path name="example" path="path/to/example" />

A path element in a standalone.xml must include the specification of the actual filesystem path.

2.10. Configuration File History

2.10.1. Configuration File History

The application server configuration files include the standalone.xml instance, as well as the domain.xml and host.xml files. While these files may be modified by direct editing, the recommended method is to configure the application server model with the available management operations, including the Management CLI and the Management Console.
To assist in the maintenance and management of the server instance, the application server creates a timestamped version of the original configuration file at the time of startup. Any additional configuration changes made by management operations result in the original file being automatically backed up, and a working copy of the instance being preserved for reference and rollback. This archival functionality extends to saving, loading and deleting snapshots of the server configuration to allow for recall and rollback scenarios.

2.10.2. Start the Server with a Previous Configuration

The following example shows how to start the application server with a previous configuration in a standalone server with standalone.xml. The same concept applies to a managed domain with domain.xml and host.xml respectively.
This example recalls a previous configuration saved automatically by the application server as management operations modify the server model.
  1. Identify the backed up version that you want to start. This example will recall the instance of the server model prior to the first modification after successfully booting up.
    EAP_HOME/configuration/standalone_xml_history/current/standalone.v1.xml 
  2. Start the server with this instance of the backed up model by passing in the relative filename under jboss.server.config.dir.
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/current/standalone.v1.xml 
Result
The application server starts with the selected configuration.

2.10.3. Save a Configuration Snapshot Using the Management CLI

Snapshots are a point-in-time copy of the current server instance. These copies can be saved and loaded by the administrator.
The following example uses the standalone.xml instance, but the same process applies to the domain.xml and host.xml models.
Task
  • Save a snapshot

    Run the take-snapshot operation to capture a copy of the current server instance.
    [standalone@localhost:9999 /] :take-snapshot
    {
        "outcome" => "success",
        "result" => "/home/User/EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-172258657standalone.xml"
    }
    
Result
A snapshot of the current server instance has been saved.

2.10.4. Load a Configuration Snapshot

Snapshots are a point-in-time copy of the current server instance. These copies can be saved and loaded by the administrator. The process of loading snapshots is similar to the method used to Section 2.10.2, “Start the Server with a Previous Configuration”, running from the command line rather than the Management CLI interface used to create, list and delete snapshots.
The following example uses the standalone.xml instance, but the same process applies to the domain.xml and host.xml models.

Procedure 2.6. Task

  1. Identify the snapshot to be loaded. This example will recall the following file from the snapshot directory. The default path for the snapshot files is as follows.
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110812-191301472standalone.xml
    The snapshots are expressed by their relative paths, by which the above example can be written as follows.
    jboss.server.config.dir/standalone_xml_history/snapshot/20110812-191301472standalone.xml
  2. Start the server with the selected snapshot instance by passing in the filename.
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20110913-164449522standalone.xml
Result
The server restarts with the selected snapshot profile.

2.10.5. Delete a Configuration Snapshot Using Management CLI

Snapshots are a point-in-time copy of the current server instance. These copies can be saved and loaded by the administrator.
The following examples use the standalone.xml instance, but the same process applies to the domain.xml and host.xml models.

Procedure 2.7. Delete a Specific Snapshot

  1. Identify the snapshot to be deleted. This example will delete the following file from the snapshot directory.
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-165714239standalone.xml
  2. Run the :delete-snapshot command to delete a specific snapshot, specifying the name of the snapshot as in the example below.
    [standalone@localhost:9999 /] :delete-snapshot(name="20110630-165714239standalone.xml")
    {"outcome" => "success"}
    
Result
The snapshot has been deleted.

Procedure 2.8. Delete All Snapshots

  • Run the :delete-snapshot(name="all") command to delete all snapshots as in the example below.
    [standalone@localhost:9999 /] :delete-snapshot(name="all")
    {"outcome" => "success"}
    
Result
All snapshots have been deleted.

2.10.6. List All Configuration Snapshots Using Management CLI

Snapshots are a point-in-time copy of the current server instance. These copies can be saved and loaded by the administrator.
The following example uses the standalone.xml instance, but the same process applies to the domain.xml and host.xml models.

Procedure 2.9. Task

  • List all snapshots

    List all of the saved snapshots by running the :list-snapshots command.
    [standalone@localhost:9999 /] :list-snapshots
    {
        "outcome" => "success",
        "result" => {
            "directory" => "/home/hostname/EAP_Home/standalone/configuration/standalone_xml_history/snapshot",
            "names" => [
                "20110818-133719699standalone.xml",
                "20110809-141225039standalone.xml",
                "20110802-152010683standalone.xml",
                "20110808-161118457standalone.xml",
                "20110912-151949212standalone.xml",
                "20110804-162951670standalone.xml"
            ]
        }
    }
    
Result
The snapshots are listed.

Chapter 3. Management Interfaces

3.1. About the Management Console and Management CLI
3.2. The Management Console
3.2.1. Management Console
3.2.2. Log in to the Management Console
3.2.3. Change the Language of the Management Console
3.2.4. Configure a Server Using the Management Console
3.2.5. Add a Deployment in the Management Console
3.2.6. Create a New Server in the Management Console
3.2.7. Change the Default Log Levels Using the Management Console
3.2.8. Create a New Server Group in the Management Console
3.3. The Management CLI
3.3.1. About the Management Command Line Interface (CLI)
3.3.2. Launch the Management CLI
3.3.3. Quit the Management CLI
3.3.4. Connect to a Managed Server Instance Using the Management CLI
3.3.5. Get Help with the Management CLI
3.3.6. Use the Management CLI in Batch Mode
3.3.7. Use Operations and Commands in the Management CLI
3.3.8. Reference of Management CLI Commands
3.3.9. Reference of Management CLI Operations
3.4. Management CLI Operations
3.4.1. Display the Attributes of a Resource with the Management CLI
3.4.2. Display the Active User in the Management CLI
3.4.3. Display System and Server Information in the Management CLI
3.4.4. Display an Operation Description using the Management CLI
3.4.5. Display the Operation Names using the Management CLI
3.4.6. Display Available Resources using the Management CLI
3.4.7. Display Available Resource Descriptions using the Management CLI
3.4.8. Reload the Application Server using the Management CLI
3.4.9. Shut the Application Server down using the Management CLI
3.4.10. Configure an Attribute with the Management CLI
3.5. The Management CLI Command History
3.5.1. Use the Management CLI Command History
3.5.2. Show the Management CLI Command history
3.5.3. Clear the Management CLI Command history
3.5.4. Disable the Management CLI Command history
3.5.5. Enable the Management CLI Command history

3.1. About the Management Console and Management CLI

In JBoss Enterprise Application Platform 6, all server instances and configurations are managed through management interfaces rather than by editing XML files. While the configuration XML files are still available for editing, administration through the management interfaces provides extra validation and advanced features for the persistent management of server instances. Changes made to the XML configuration files while the server instance is running will be overwritten by the server model, and any XML comments added will be removed as well. Only the management interfaces should be used for modifying the configuration files while a server instance is running.
To manage servers through a graphical user-interface in a web browser, use the Management Console.
To manage servers through a command line interface, use the Management CLI.

3.2. The Management Console

3.2.1. Management Console

The Management Console is a web-based administration tool for JBoss Enterprise Application Platform 6.
Use the Management Console to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The Management Console also has the ability to perform administrative tasks, with live notifications when any changes require the server instance to be restarted or reloaded.
In a Managed Domain, server instances and server groups in the same domain can be centrally managed from the Management Console of the domain controller.

3.2.2. Log in to the Management Console

Prerequisites

  • JBoss Enterprise Application Platform 6 must be running.

Procedure 3.1. Task

  1. Navigate to the Management Console start page

    Navigate to the Management Console in your web browser. The default location is http://localhost:9990/console/, where port 9990 is predefined as the Management Console socket binding.
  2. Log in to the Management Console

    Enter the username and password of the account that you created previously to log into the Management Console login screen.
    The login screen for the Management console.

    Figure 3.1. Log in screen for the Management Console


Result

Once logged in, one of the Management Console landing pages appears:
Managed domain
Standalone server

3.2.3. Change the Language of the Management Console

The language settings of web-based Management Console use English by default. You can choose to use one of the following languages instead.

Supported Languages

  • German (de)
  • Simplified Chinese (zh-Hans)
  • Brazilian Portuguese (pt-BR)
  • French (fr)
  • Spanish (es)
  • Japanese (ja)

Procedure 3.2. Task

  1. Log into the Management Console.

    Log into the web-based Management Console.
  2. Open the Settings dialog.

    Near the bottom right of the screen is a Settings label. Click it to open the settings for the Management Console.
  3. Select the desired language.

    Select the desired language from the Locale selection box. Select Save. A confirmation box informs you that you need to reload the application. Click Confirm. Refresh your web browser to use the new locale.

3.2.4. Configure a Server Using the Management Console

Procedure 3.3. Task

  1. Navigate to the server's Server Configuration panel in the Management Console

    1. Select the Server tab from the top-right of the console.
    2. Expand the Server Configurations menu item on the left of the console and select the relevant server from the list.
    Server configuration

    Figure 3.2. Server configuration


  2. Edit the server configuration

    1. Select the Edit button beneath the server list.
    2. Make changes to the configuration attributes.
    3. Select the Save button beneath the server list.
Result
The server configuration is changed, and will take effect next time the server restarts.

3.2.5. Add a Deployment in the Management Console

Procedure 3.4. Task

  1. Navigate to the Manage Deployments panel in the Management Console

    1. Select the Runtime tab from the top right of the console.
    2. For either a managed domain or a standalone server, select the DeploymentsManage Deployments option from the menu on the left of the console.
    The Manage Deployments panel appears.
    Manage domain deployments

    Figure 3.3. Manage domain deployments


  2. Add deployment content

    Select the Add Content button in the top right of the Deployments panel. An Upload dialog box appears.
  3. Choose a file to deploy

    In the dialog box, select the Choose File button. Browse to the file you want to deploy and select it for upload. Select the Next button to proceed once a file has been selected.
    Deployment selection

    Figure 3.4. Deployment selection


  4. Verify deployment names

    Verify the deployment name and runtime name that appear in the Upload dialog box. Select the Save button to upload the file once the names are verified.
    Verify deployment names

    Figure 3.5. Verify deployment names


Result
The selected content is uploaded to the server and is now ready for deployment.
Uploaded deployment in a managed domain

Figure 3.6. Uploaded deployment in a managed domain


Uploaded deployment on a standalone server instance

Figure 3.7. Uploaded deployment on a standalone server instance


3.2.6. Create a New Server in the Management Console

Procedure 3.5. Task

  1. Navigate to the Server Configurations page in the Management Console

    Select the Server tab from the top-right of the console.
  2. Create a new configuration

    1. Select the Add button at the top of the Server Configuration panel.
    2. Edit the basic server settings in the Create Server Configuration dialog.
    3. Select the Save button to save the new server configuration.
Result
The new server is created and listed in the Server Configurations list.

3.2.7. Change the Default Log Levels Using the Management Console

Procedure 3.6. Task

  1. Navigate to the Logging panel in the Management Console

    1. If you are working with a managed domain, select the Profiles tab from the top-right of the console, then select the relevant profile from the drop-down list on the left of the console.
    2. For either a managed domain or a standalone server, select the CoreLogging option from the menu on the left of the console.
    3. Click on the Log Categories tab in the top of the console.
    Logging panel

    Figure 3.8. Logging panel


  2. Edit logger details

    Edit the details for any of the entries in the Log Categories table.
    1. Select an entry in the Log Categories table, then select the Edit button in the Details section below.
    2. Set the log level for the category with the Log Level drop-down box. Select the Save button when done.
Result
The log levels for the relevant categories are now updated.

3.2.8. Create a New Server Group in the Management Console

Procedure 3.7. Task

  1. Navigate to the Server Groups view

    Select the Profiles tab in the top-right corner.
  2. Select the Group Configurations tab under the Server Groups menu in the left hand column.
    The Server Groups view

    Figure 3.9. The Server Groups view


  3. Add a server group

    Click the Add button to add a new server group.
  4. Configure the server group

    1. Enter a name for the server group.
    2. Select the profile you want to add the server group to.
    3. Select the socket binding you want to add the server group to.
    4. Select the Save button to save your new group.
    The Create Server Group dialog

    Figure 3.10. The Create Server Group dialog


Result
The new server group is visible in the Management Console.

3.3. The Management CLI

3.3.1. About the Management Command Line Interface (CLI)

The Management Command Line Interface (CLI) is a command line administration tool for JBoss Enterprise Application Platform 6.
Use the Management CLI to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch modes, allowing multiple tasks to be run as a group.

3.3.2. Launch the Management CLI

Procedure 3.8. Task

    • Launch the CLI in Linux

      Run the EAP_HOME/bin/jboss-cli.sh file by entering the following at a command line:
      $ EAP_HOME/bin/jboss-cli.sh
    • Launch the CLI in Windows

      Run the EAP_HOME\bin\jboss-cli.bat file by double-clicking it, or by entering the following at a command line:
      C:\>EAP_HOME\bin\jboss-cli.bat

3.3.3. Quit the Management CLI

Procedure 3.9. Task

  • Run the quit command

    From the Management CLI, enter the quit command:
    [domain@localhost:9999 /] quit
    Closed connection to localhost:9999

3.3.4. Connect to a Managed Server Instance Using the Management CLI

Procedure 3.10. Task

  • Run the connect command

    From the Management CLI, enter the connect command:
    [disconnected /] connect
    Connected to domain controller at localhost:9999
    • Alternatively, to connect to a managed server when starting the Management CLI on a Linux system, use the --connect parameter:
      $ EAP_HOME/bin/jboss-cli.sh --connect
    • The --connect parameter can be used to specify the host and port of the server. To connect to the address 192.168.0.1 with the port value 9999 the following would apply:
      $ EAP_HOME/bin/jboss-cli.sh --connect --controller=192.168.0.1:9999

3.3.5. Get Help with the Management CLI

Summary
The Management CLI features a help dialog with general and context sensitive options. The help commands dependent on the operation context require an established connection to either a standalone or domain controller. These commands will not appear in the listing unless the connection has been established.

Procedure 3.11. Task

  1. Run the help command

    From the Management CLI, enter the help command:
    [standalone@localhost:9999 /] help
  2. Get context sensitive help

    From the Management CLI, enter the help -commands extended command:
    [standalone@localhost:9999 /] help --commands
  3. For a more detailed description of a specific command, execute the help command with '--help' as the argument.
    [standalone@localhost:9999 /]  deploy --help
Result
The CLI help information is displayed.

3.3.6. Use the Management CLI in Batch Mode

Procedure 3.12. Task

Batch processing allows a number of operation requests to be grouped in a sequence and executed together as a unit. If any of the operation requests in the sequence fail, the entire group of operations is rolled back.
  1. Enter batch mode

    Enter batch mode with the batch command.
    [standalone@localhost:9999 /] batch
    [standalone@localhost:9999 / #]
    Batch mode is indicated by the hash symbol (#) in the prompt.
  2. Add operation requests to the batch

    Once in batch mode, enter operation requests as normal. The operation requests are added to the batch in the order they are entered.
    Refer to Section 3.3.7, “Use Operations and Commands in the Management CLI” for details on formatting operation requests.
  3. Run the batch

    Once the entire sequence of operation requests is entered, run the batch with the run-batch command.
    [standalone@localhost:9999 / #] run-batch
    The batch executed successfully.
Result
The entered sequence of operation requests is completed as a batch.

3.3.7. Use Operations and Commands in the Management CLI

Procedure 3.13. Task

  1. Construct the operation request

    Operation requests allow for low-level interaction with the management model. They provide a controlled way to edit server configurations. An operation request consists of three parts:
    • an address, prefixed with a slash (/).
    • an operation name, prefixed with a colon (:).
    • an optional set of parameters, contained within parentheses (()).
    1. Determine the address

      The configuration is presented as a hierarchical tree of addressable resources. Each resource node offers a different set of operations. The address specifies which resource node to perform the operation on. An address uses the following syntax:
      /node-type=node-name
      • node-type is the resource node type. This maps to an element name in the configuration XML.
      • node-name is the resource node name. This maps to the name attribute of the element in the configuration XML.
      • Separate each level of the resource tree with a slash (/).
      Refer to the configuration XML files to determine the required address. The EAP_HOME/standalone/configuration/standalone.xml file holds the configuration for a standalone server and the EAP_HOME/domain/configuration/domain.xml and EAP_HOME/domain/configuration/host.xml files hold the configuration for a managed domain.

      Example 3.1. Example operation addresses

      To perform an operation on the logging subsystem, use the following address in an operation request:
      /subsystem=logging
      To perform an operation on the Java datasource, use the following address in an operation request:
      /subsystem=datasources/data-source=java

    2. Determine the operation

      Operations differ for each different type of resource node. An operation uses the following syntax:
      :operation-name
      • operation-name is the name of the operation to request.
      Use the read-operation-names operation on any resource address in a standalone server to list the available operations.

      Example 3.2. Available operations

      To list all available operations for the logging subsystem, enter the following request for a standalone server:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-names
      {
          "outcome" => "success",
          "result" => [
              "add",
              "read-attribute",
              "read-children-names",
              "read-children-resources",
              "read-children-types",
              "read-operation-description",
              "read-operation-names",
              "read-resource",
              "read-resource-description",
              "remove",
              "undefine-attribute",
              "whoami",
              "write-attribute"
          ]
      }

    3. Determine any parameters

      Each operation may require different parameters.
      Parameters use the following syntax:
      (parameter-name=parameter-value)
      • parameter-name is the name of the parameter.
      • parameter-value is the value of the parameter.
      • Multiple parameters are separated by commas (,).
      To determine any required parameters, perform the read-children-types command on a resource node, passing the operation name as a parameter. Refer to Example 3.3, “Determine operation parameters” for details.

      Example 3.3. Determine operation parameters

      To determine any required parameters for the read-children-types operation on the logging subsystem, enter the read-operation-description command as follows:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-description(name=read-children-types)
      {
          "outcome" => "success",
          "result" => {
              "operation-name" => "read-children-types",
              "description" => "Gets the type names of all the children under the selected resource",
              "reply-properties" => {
                  "type" => LIST,
                  "description" => "The children types",
                  "value-type" => STRING
              },
              "read-only" => false
          }
      }

  2. Enter the full operation request

    Once the address, operation, and any parameters have been determined, enter the full operation request.

    Example 3.4. Example operation request

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(recursive=true)

Result
The management interface performs the operation request on the server configuration.

3.3.8. Reference of Management CLI Commands

Summary
The topic Section 3.3.5, “Get Help with the Management CLI” describes how to access the Management CLI help features, including a help dialogue with general and context sensitive options. The help commands are dependent on the operation context and require an established connection to either a standalone or domain controller. These commands will not appear in the listing unless the connection has been established.

Table 3.1. 

Command Description
batch Starts the batch mode by creating a new batch or, depending on the existing held back batches, re-activates one. If there are no held back batches this command invoked w/o arguments will start a new batch. If there is an unnamed held back batch, this command will re-activate it. If there are named held back batches, they can be activated by executing this command with the name of the held back batch as the argument.
cd Changes the current node path to the argument. The current node path is used as the address for operation requests that do not contain the address part. If an operation request does include the address, the included address is considered relative to the current node path. The current node path may end on a node-type. In that case, to execute an operation specifying a node-name would be sufficient, such as logging:read-resource.
clear Clears the screen.
command Allows you to add new, remove and list existing generic type commands. A generic type command is a command that is assigned to a specific node type and which allows you to perform any operation available for an instance of that type. It can also modify any of the properties exposed by the type on any existing instance.
connect Connects to the controller on the specified host and port.
connection-factory Defines a connection factory.
data-source Manages JDBC datasource configurations in the datasource subsystem.
deploy Deploys the application designated by the file path or enables an application that is pre-existing but disabled in the repository. If executed without arguments, this command will list all the existing deployments.
help Displays the help message. Can be used with the --commands argument to provide context sensitive results for the given commands.
history Displays the CLI command history in memory and displays a status of whether the history expansion is enabled or disabled. Can be used with arguments to clear, disable and enable the history expansion as required.
jms-queue Defines a JMS queue in the messaging subsystem.
jms-topic Defines a JMS topic in the messaging subsystem.
ls List the contents of the node path. By default the result is printed in columns using the whole width of the terminal. Using the -l switch will print results on one name per line.
pwd Prints the full node path of the current working node.
quit Terminates the command line interface.
read-attribute Prints the value and, depending on the arguments, the description of the attribute of a managed resource.
read-operation Displays the description of a specified operation, or lists all available operations if none is specified.
undeploy Undeploys an application when run with the name of the intended application. Can be run with arguments to remove the application from the repository also. Prints the list of all existing deployments when executed without an application specified.
version Prints the application server version and environment information.
xa-data-source Manages JDBC XA datasource configuration in the datasource subsystem.

3.3.9. Reference of Management CLI Operations

Exposing operations in the Management CLI
Operations in the Management CLI can be exposed by using the read-operation-names operation described in the topic Section 3.4.5, “Display the Operation Names using the Management CLI”. The operation descriptions can be exposed by using the read-operation-descriptions operation described in the topic Section 3.4.4, “Display an Operation Description using the Management CLI”.

Table 3.2. Management CLI operations

Operation Name Description
add-namespace Adds a namespace prefix mapping to the namespaces attribute's map.
add-schema-location Adds a schema location mapping to the schema-locations attribute's map.
delete-snapshot Deletes a snapshot of the server configuration from the snapshots directory.
full-replace-deployment Add previously uploaded deployment content to the list of content available for use, replace existing content of the same name in the runtime, and remove the replaced content from the list of content available for use. Refer to link for further information.
list-snapshots Lists the snapshots of the server configuration saved in the snapshots directory.
read-attribute Displays the value of an attribute for the selected resource.
read-children-names Displays the names of all children under the selected resource with the given type.
read-children-resources Displays information about all of a resource's children that are of a given type.
read-children-types Displays the type names of all the children under the selected resource.
read-config-as-xml Reads the current configuration and displays it in XML format.
read-operation-description Displays the details of an operation on the given resource.
read-operation-names Displays the names of all the operations for the given resource.
read-resource Displays a model resource's attribute values along with either basic or complete information about any child resources.
read-resource-description Displays the description of a resource's attributes, types of children and operations.
reload Reloads the server by shutting all services down and restarting.
remove-namespace Removes a namespace prefix mapping from the namespaces attribute map.
remove-schema-location Removes a schema location mapping from the schema-locations attribute map.
replace-deployment Replace existing content in the runtime with new content. The new content must have been previously uploaded to the deployment content repository.
resolve-expression Operation that accepts an expression as input or a string that can be parsed into an expression, and resolves it against the local system properties and environment variables.
resolve-internet-address Takes a set of interface resolution criteria and finds an IP address on the local machine that matches the criteria, or fails if no matching IP address can be found.
server-set-restart-required Puts the server into a restart-required mode
shutdown Shuts down the server via a call to System.exit(0).
start-servers Starts all configured servers in a Managed Domain that are not currently running.
stop-servers Stops all servers currently running in a Managed Domain.
take-snapshot Takes a snapshot of the server configuration and saves it to the snapshots directory.
upload-deployment-bytes Indicates that the deployment content in the included byte array should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
upload-deployment-stream Indicates that the deployment content available at the included input stream index should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
upload-deployment-url Indicates that the deployment content available at the included URL should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
validate-address Validates the operation's address.
write-attribute Sets the value of an attribute for the selected resource.

3.4. Management CLI Operations

3.4.1. Display the Attributes of a Resource with the Management CLI

Summary
The read-attribute operation is a global operation used to read the current runtime value of a selected attribute. It can be used to expose only the values that have been set by the user, ignoring any default or undefined values. The request properties include the following parameters.

Request Properties

name
The name of the attribute to get the value for under the selected resource.
include-defaults
A Boolean parameter that can be set to false to restrict the operation results to only show attributes set by the user and ignore default values.

Procedure 3.14. Task

An advantage of the read-attribute operation is the ability to expose the current runtime value of a specific attribute. Similar results can be achieved with the read-resource operation, but only with the addition of the include-runtime request property, and only as part of a list of all available resources for that node. The read-attribute operation is intended for fine-grained attribute queries, as the following example shows.

Example 3.5. Run the read-attribute operation to expose the public interface IP

If you know the name of the attribute that you would like to expose, you can use the read-attribute to return the exact value in the current runtime.
[standalone@localhost:9999 /] /interface=public:read-attribute(name=resolved-address)
{
    "outcome" => "success",
    "result" => "127.0.0.1"
}
The resolved-address attribute is a runtime value, so it is not displayed in the results of the standard read-resource operation.
[standalone@localhost:9999 /] /interface=public:read-resource                        
{
    "outcome" => "success",
    "result" => {
        "any" => undefined,
        "any-address" => undefined,
        "any-ipv4-address" => undefined,
        "any-ipv6-address" => undefined,
        "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
        "link-local-address" => undefined,
        "loopback" => undefined,
        "loopback-address" => undefined,
        "multicast" => undefined,
        "name" => "public",
        "nic" => undefined,
        "nic-match" => undefined,
        "not" => undefined,
        "point-to-point" => undefined,
        "public-address" => undefined,
        "site-local-address" => undefined,
        "subnet-match" => undefined,
        "up" => undefined,
        "virtual" => undefined
    }
}
To display resolved-address and other runtime values, you must use the include-runtime request property.
[standalone@localhost:9999 /] /interface=public:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "any" => undefined,
        "any-address" => undefined,
        "any-ipv4-address" => undefined,
        "any-ipv6-address" => undefined,
        "inet-address" => expression "${jboss.bind.address:127.0.0.1}",
        "link-local-address" => undefined,
        "loopback" => undefined,
        "loopback-address" => undefined,
        "multicast" => undefined,
        "name" => "public",
        "nic" => undefined,
        "nic-match" => undefined,
        "not" => undefined,
        "point-to-point" => undefined,
        "public-address" => undefined,
        "resolved-address" => "127.0.0.1",
        "site-local-address" => undefined,
        "subnet-match" => undefined,
        "up" => undefined,
        "virtual" => undefined
    }
}

Result
The current runtime attribute value is displayed.

3.4.2. Display the Active User in the Management CLI

Summary
The whoami operation is a global operation used to identify the attributes of the current active user. The operation exposes the identity of the username and the realm that they are assigned to. The whoami operation is useful for administrators managing multiple users accounts across multiple realms, or to assist in keeping track of active users across domain instances with multiple terminal session and users accounts.

Procedure 3.15. Task

  • Run the whoami operation

    From the Management CLI, use the whoami operation to display the active user account.
    [standalone@localhost:9999 /] :whoami
    The following example uses the whoami operation in a standalone server instance to show that the active user is username, and that the user is assigned to the ManagementRealm realm.

    Example 3.6. Use the whoami in a standalone instance

    [standalone@localhost:9999 /]:whoami
    {
        "outcome" => "success",
        "result" => {"identity" => {
            "username" => "username",
            "realm" => "ManagementRealm"
        }}
    }
    

Result
Your current active user account is displayed.

3.4.3. Display System and Server Information in the Management CLI

Procedure 3.16. Task

  • Run the version command

    From the Management CLI, enter the version command:
    [domain@localhost:9999 /] version
Result
Your application server version and environment information is displayed.

3.4.4. Display an Operation Description using the Management CLI

Procedure 3.17. Task

  • Run the read-operation-description operation

    From the Management CLI, use read-operation-description to display information about the operation. The operation requires additional parameters in the format of a key-value pair to indicate which operation to display. For more details on operation requests, refer to the topic Section 3.3.7, “Use Operations and Commands in the Management CLI”.
    [standalone@localhost:9999 /]:read-operation-description(name=name-of-operation)

Example 3.7. Display the list-snapshots operation description

The following example shows the method for describing the list-snapshots operation.
[standalone@localhost:9999 /] :read-operation-description(name=list-snapshots)
{
    "outcome" => "success",
    "result" => {
        "operation-name" => "list-snapshots",
        "description" => "Lists the snapshots",
        "reply-properties" => {
            "type" => OBJECT,
            "value-type" => {
                "directory" => {
                    "type" => STRING,
                    "description" => "The directory where the snapshots are stored"
                },
                "names" => {
                    "type" => LIST,
                    "value-type" => STRING,
                    "description" => "The names of the snapshots within the snapshots directory"
                }
            }
        },
        "read-only" => false
    }
}

Result
The description is displayed for the chosen operation.

3.4.5. Display the Operation Names using the Management CLI

Procedure 3.18. Task

Example 3.8. Display the operation names using the Management CLI

The following example shows the method for describing the read-operation-names operation.
[standalone@localhost:9999 /]:read-operation-names
{
    "outcome" => "success",
    "result" => [
        "add-namespace",
        "add-schema-location",
        "delete-snapshot",
        "full-replace-deployment",
        "list-snapshots",
        "read-attribute",
        "read-children-names",
        "read-children-resources",
        "read-children-types",
        "read-config-as-xml",
        "read-operation-description",
        "read-operation-names",
        "read-resource",
        "read-resource-description",
        "reload",
        "remove-namespace",
        "remove-schema-location",
        "replace-deployment",
        "shutdown",
        "take-snapshot",
        "upload-deployment-bytes",
        "upload-deployment-stream",
        "upload-deployment-url",
        "validate-address",
        "write-attribute"
    ]
}

Result
The available operation names are displayed.

3.4.6. Display Available Resources using the Management CLI

Summary
The read-resource operation is a global operation used to read resource values. It can be used to expose either basic or complete information about the resources of the current or child nodes, along with a range of request properties to expand or limit the scope of the operation results. The request properties include the following parameters.

Request Properties

recursive
Whether to recursively include complete information about child resources.
recursive-depth
The depth to which information about child resources should be included.
proxies
Whether to include remote resources in a recursive query. For example including the host level resources from slave Host Controllers in a query of the Domain Controller.
include-runtime
Whether to include runtime attributes in the response, such as attribute values that do not come from the persistent configuration. This request property is set to false by default.
include-defaults
A boolean request property that serves to enable or disable the reading of default attributes. When set to false only the attributes set by the user are returned, ignoring any that remain undefined.

Procedure 3.19. Task

  1. Run the read-resource operation

    From the Management CLI, use the read-resource operation to display the available resources.
    [standalone@localhost:9999 /]:read-resource
    The following example shows how you might use the read-resource operation on a standalone server instance to expose general resource information. The results resemble the standalone.xml configuration file, displaying the system resources, extensions, interfaces and subsystems installed or configured for the server instance. These can be further queried directly.

    Example 3.9. Using the read-resource operation at the root level

    [standalone@localhost:9999 /]:read-resource
    {
        "outcome" => "success",
        "result" => {
            "deployment" => undefined,
            "management-major-version" => 1,
            "management-minor-version" => 2,
            "name" => "hostname",
            "namespaces" => [],
            "product-name" => "EAP",
            "product-version" => "6.0.0.GA",
            "profile-name" => undefined,
            "release-codename" => "Steropes",
            "release-version" => "7.1.2.Final-redhat-1",
            "schema-locations" => [],
            "system-property" => undefined,
            "core-service" => {
                "management" => undefined,
                "service-container" => undefined,
                "server-environment" => undefined,
                "platform-mbean" => undefined
            },
            "extension" => {
                "org.jboss.as.clustering.infinispan" => undefined,
                "org.jboss.as.configadmin" => undefined,
                "org.jboss.as.connector" => undefined,
                "org.jboss.as.deployment-scanner" => undefined,
                "org.jboss.as.ee" => undefined,
                "org.jboss.as.ejb3" => undefined,
                "org.jboss.as.jaxrs" => undefined,
                "org.jboss.as.jdr" => undefined,
                "org.jboss.as.jmx" => undefined,
                "org.jboss.as.jpa" => undefined,
                "org.jboss.as.logging" => undefined,
                "org.jboss.as.mail" => undefined,
                "org.jboss.as.naming" => undefined,
                "org.jboss.as.osgi" => undefined,
                "org.jboss.as.pojo" => undefined,
                "org.jboss.as.remoting" => undefined,
                "org.jboss.as.sar" => undefined,
                "org.jboss.as.security" => undefined,
                "org.jboss.as.threads" => undefined,
                "org.jboss.as.transactions" => undefined,
                "org.jboss.as.web" => undefined,
                "org.jboss.as.webservices" => undefined,
                "org.jboss.as.weld" => undefined
            },
            "interface" => {
                "management" => undefined,
                "public" => undefined,
                "unsecure" => undefined
            },
            "path" => {
                "jboss.server.temp.dir" => undefined,
                "user.home" => undefined,
                "jboss.server.base.dir" => undefined,
                "java.home" => undefined,
                "user.dir" => undefined,
                "jboss.server.data.dir" => undefined,
                "jboss.home.dir" => undefined,
                "jboss.server.log.dir" => undefined,
                "jboss.server.config.dir" => undefined,
                "jboss.controller.temp.dir" => undefined
            },
            "socket-binding-group" => {"standard-sockets" => undefined},
            "subsystem" => {
                "logging" => undefined,
                "configadmin" => undefined,
                "datasources" => undefined,
                "deployment-scanner" => undefined,
                "ee" => undefined,
                "ejb3" => undefined,
                "infinispan" => undefined,
                "jaxrs" => undefined,
                "jca" => undefined,
                "jdr" => undefined,
                "jmx" => undefined,
                "jpa" => undefined,
                "mail" => undefined,
                "naming" => undefined,
                "osgi" => undefined,
                "pojo" => undefined,
                "remoting" => undefined,
                "resource-adapters" => undefined,
                "sar" => undefined,
                "security" => undefined,
                "threads" => undefined,
                "transactions" => undefined,
                "web" => undefined,
                "webservices" => undefined,
                "weld" => undefined
            }
        }
    }
    

  2. Run the read-resource operation against a child node

    The read-resource operation can be run to query child nodes from the root. The structure of the operation first defines the node to expose, and then appends the operation to run against it.
    [standalone@localhost:9999 /]/subsystem=web/connector=http:read-resource
    In the following example, specific resource information about a web subsystem component can be exposed by directing the read-resource operation towards the specific web subsystem node.

    Example 3.10. Expose child node resources from the root node

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource                      
    {
        "outcome" => "success",
        "result" => {
            "enable-lookups" => false,
            "enabled" => true,
            "executor" => undefined,
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "name" => "http",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 8433,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    

    The same results are possible by using the cd command to navigate into the child nodes and run the read-resource operation directly.

    Example 3.11. Expose child node resources by changing directories

    [standalone@localhost:9999 /] cd subsystem=web
    [standalone@localhost:9999 subsystem=web] cd connector=http
    [standalone@localhost:9999 connector=http] :read-resource
    {
        "outcome" => "success",
        "result" => {
            "enable-lookups" => false,
            "enabled" => true,
            "executor" => undefined,
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "name" => "http",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 8433,
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    

  3. Use the recursive parameter to include active values in results

    The recursive parameter can be used to expose the values of all attributes, including non-persistent values, those passed at startup, or other attributes otherwise active in the runtime model.
    [standalone@localhost:9999 /]/interface=public:read-resource(include-runtime=true)
    Compared to the previous example, the inclusion of the include-runtime request property exposes additional active attributes, such as the bytes sent and byes received by the http connector.

    Example 3.12. Expose additional and active values with the include-runtime parameter

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(include-runtime=true)
    {
        "outcome" => "success",
        "result" => {
            "bytesReceived" => "0",
            "bytesSent" => "0",
            "enable-lookups" => false,
            "enabled" => true,
            "errorCount" => "0",
            "executor" => undefined,
            "max-connections" => undefined,
            "max-post-size" => 2097152,
            "max-save-post-size" => 4096,
            "maxTime" => "0",
            "name" => "http",
            "processingTime" => "0",
            "protocol" => "HTTP/1.1",
            "proxy-name" => undefined,
            "proxy-port" => undefined,
            "redirect-port" => 8433,
            "requestCount" => "0",
            "scheme" => "http",
            "secure" => false,
            "socket-binding" => "http",
            "ssl" => undefined,
            "virtual-server" => undefined
        }
    }
    

3.4.7. Display Available Resource Descriptions using the Management CLI

Procedure 3.20. Task

  1. Run the read-resource-description operation

    From the Management CLI, use the read-resource-description operation to read and display the available resources. For more details on operation requests, refer to the topic Section 3.3.7, “Use Operations and Commands in the Management CLI”.
    [standalone@localhost:9999 /]:read-resource-description
  2. Use optional parameters

    The read-resource-description operation allows the use of the additional parameters.
    1. Use the operations parameter to include descriptions of the resource's operations.
      [standalone@localhost:9999 /]:read-resource-description(operations=true)
    2. Use the inherited parameter to include or exclude descriptions of the resource's inherited operations. The default state is true.
      [standalone@localhost:9999 /]:read-resource-description(inherited=false)
    3. Use the recursive parameter to include recursive descriptions of the child resources.
      [standalone@localhost:9999 /]:read-resource-description(recursive=true)
    4. Use the locale parameter to get the resource description in. If null, the default locale will be used.
      [standalone@localhost:9999 /]:read-resource-description(locale=true)
Result
Descriptions of the available resources are displayed.

3.4.8. Reload the Application Server using the Management CLI

Procedure 3.21. Task

Result
The application server reloads by shutting down all services and starting the runtime again. The Management CLI automatically reconnects.

3.4.9. Shut the Application Server down using the Management CLI

Procedure 3.22. Task

Result
The application server is shut down. The Management CLI will be disconnected as the runtime is unavailable.

3.4.10. Configure an Attribute with the Management CLI

Summary
The write-attribute operation is a global operation used to write or modify a selected resource attribute. You can use the operation to make persistent changes and to modify the configuration settings of your managed server instances. The request properties include the following parameters.

Request Properties

name
The name of the attribute to set the value for under the selected resource.
value
The desired value of the attribute under the selected resource. May be null if the underlying model supports null values.

Procedure 3.23. Task

  • Run the write-attribute operation

    From the Management CLI, use the write-attribute operation to modify the value of a resource attribute. The operation can be run at the child node of the resource or at the root node of the Management CLI where the full resource path is specified.

Example 3.13. Disable the deployment scanner with the write-attribute operation

The following example uses the write-attribute operation to disable the deployment scanner. The operation is run from the root node, using tab completion to aid in populating the correct resource path.
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)
{"outcome" => "success"}
The results of the operation can be confirmed directly with the read-attribute operation.
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:read-attribute(name=scan-enabled)
{
    "outcome" => "success",
    "result" => false
}
The results can also be confirmed by listing all of the node's available resource attributes with the read-resource operation. In the following example, this particular configuration shows the scan-enabled attribute is now set to false.
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:read-resource                                 
{
    "outcome" => "success",
    "result" => {
        "auto-deploy-exploded" => false,
        "auto-deploy-xml" => true,
        "auto-deploy-zipped" => true,
        "deployment-timeout" => 600,
        "path" => "deployments",
        "relative-to" => "jboss.server.base.dir",
        "scan-enabled" => false,
        "scan-interval" => 5000
    }
}

Result
The resource attribute is updated.

3.5. The Management CLI Command History

3.5.1. Use the Management CLI Command History

The Management CLI features a command history functionality that is enabled by default in the application server installation. The history is kept both as a record in the volatile memory of the active CLI session, and appended to a log file that saves automatically in the user's home directory as .jboss-cli-history. This history file is configured by default to record up to a maximum of 500 CLI commands.
The history command by itself will return the history of the current session, or with additional arguments will disable, enable or clear the history from the session memory. The Management CLI also features the ability to use your keyboard's arrow keys to go back and forth in the history of commands and operations.

3.5.2. Show the Management CLI Command history

Procedure 3.24. Task

  • Run the history command

    From the Management CLI, enter the history command:
    [standalone@localhost:9999 /] history
Result
The CLI command history stored in memory since the CLI startup or the history clear command is displayed.

3.5.3. Clear the Management CLI Command history

Procedure 3.25. Task

  • Run the history --clear command

    From the Management CLI, enter the history --clear command:
    [standalone@localhost:9999 /] history --clear
Result
The history of commands recorded since the CLI startup is cleared from the session memory. The command history is still present in the .jboss-cli-history file saved to the user's home directory.

3.5.4. Disable the Management CLI Command history

Procedure 3.26. Task

  • Run the history --disable command

    From the Management CLI, enter the history --disable command:
    [standalone@localhost:9999 /] history --disable
Result
Commands made in the CLI will not be recorded either in memory or in the .jboss-cli-history file saved to the user's home directory.

3.5.5. Enable the Management CLI Command history

Procedure 3.27. Task

  • Run the history --enable command

    From the Management CLI, enter the history --enable command:
    [standalone@localhost:9999 /] history --enable
Result
Commands made in the CLI are recorded in memory and in the .jboss-cli-history file saved to the user's home directory.

Chapter 4. User Management

4.1. User Creation

4.1.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 9.7.1, “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 4.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.

4.1.2. Add a User to the Management Interface

Chapter 5. Network and Port Configuration

5.1. Interfaces

5.1.1. About Interfaces

The application server uses named interface references throughout the configuration. This gives the configuration the ability to reference the individual interface declarations with logical names, rather than the full details of the interface at each use. The use of logical names also allows for consistency in group references to named interfaces, where server instances on a managed domain may contain varying interface details across multiple machines. With this methodology, each server instance may correspond to a logical name group that allows for easier administration of the interface group as a whole.
A network interface is declared by specifying a logical name and a selection criteria for the physical interface. The application server ships with a default configuration for a management and a public interface name. In this configuration, the public interface group is intended for use by any application-related network communication such as Web or Messaging. The management interface group is intended for use for all components and services that are required by the management layer, including the HTTP Management Endpoint. The interface names themselves are provided as a suggestion only, where any name for any group can be substituted or created as required.
The domain.xml, host.xml and standalone.xml configuration files all include interface declarations. The declaration criteria can reference a wildcard address or specify a set of one of more characteristics that an interface or address must have in order to be a valid match. The following examples show multiple possible configurations of interface declarations, typically defined in either the standalone.xml or host.xml configuration files. This allows any remote host groups to maintain their own specific interface attributes, while still allowing reference to the any interface groups in the domain.xml configuration file of the domain controller.
The first example shows a specific inet-address value specified for both the management and public relative name groups.

Example 5.1. An interface group created with an inet-address value

<interfaces>
  <interface name="management">
   <inet-address value="127.0.0.1"/>
  </interface>
  <interface name="public">
   <inet-address value="127.0.0.1"/>
  </interface>
</interfaces>


In the following example a global interface group uses the any-address element to declare a wildcard address.

Example 5.2. A global group created with a wildcard declaration

<interface name="global">
   <!-- Use the wild-card address -->
   <any-address/>
</interface>


The following example declares a network interface card under a relative group with the name external.

Example 5.3. An external group created with an NIC value

        
<interface name="external">
   <nic name="eth0"/>
</interface>


In the following example a declaration is created as the default group for a specific requirement. In this instance, the characteristics of the additional elements set the condition for the interface to be a valid match. This allows for the creation of very specific interface declaration groups, with the ability to reference them in a preset manner, reducing the configuration and administration time across multiple server instances.

Example 5.4. A default group created with specific conditional values

<interface name="default">
   <!-- Match any interface/address on the right subnet if it's
        up, supports multicast, and isn't point-to-point -->
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>


While the interface declarations can be made and edited in the source configuration files, the Management CLI and Management Console provide a safe, controlled and persistent environment for configuration changes.

5.1.2. Configure Interfaces

The default interface configurations in the standalone.xml and host.xml configuration files offer three named interfaces with relative interface tokens for each. You can use the Management Console or Management CLI to configure additional attributes and values, as listed in the table below. You can also replace the relative interface bindings with specific values as required. Note that if you do so, you will be unable to pass an interface value at server runtime, as the -b switch can only override a relative value.

Example 5.5. Default Interface Configurations

        <interfaces>
            <interface name="management">
                <inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
            </interface>
            <interface name="public">
                <inet-address value="${jboss.bind.address:127.0.0.1}"/>
            </interface>
            <interface name="unsecure">
                <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
            </interface>
        </interfaces>

Table 5.1. Interface Attributes and Values

Interface Element Description
any Empty element of the address exclusion type, used to constrain the selection criteria.
any-address Empty element indicating that sockets using this interface should be bound to a wildcard address. The IPv6 wildcard address (::) will be used unless the java.net.preferIpV4Stack system property is set to true, in which case the IPv4 wildcard address (0.0.0.0) will be used. If a socket is bound to an IPv6 anylocal address on a dual-stack machine, it can accept both IPv6 and IPv4 traffic; if it is bound to an IPv4 (IPv4-mapped) anylocal address, it can only accept IPv4 traffic.
any-ipv4-address Empty element indicating that sockets using this interface should be bound to the IPv4 wildcard address (0.0.0.0).
any-ipv6-address Empty element indicating that sockets using this interface should be bound to the IPv6 wildcard address (::).
inet-address Either a IP address in IPv6 or IPv4 dotted decimal notation, or a hostname that can be resolved to an IP address.
link-local-address Empty element indicating that part of the selection criteria for an interface should be whether or not an address associated with it is link-local.
loopback Empty element indicating that part of the selection criteria for an interface should be whether or not it is a loopback interface.
loopback-address A loopback address that may not actually be configured on the machine's loopback interface. Differs from inet-addressType in that the given value will be used even if no NIC can be found that has the IP address associated with it.
multicast Empty element indicating that part of the selection criteria for an interface should be whether or not it supports multicast.
nic The name of a network interface (e.g. eth0, eth1, lo).
nic-match A regular expression against which the names of the network interfaces available on the machine can be matched to find an acceptable interface.
not Empty element of the address exclusion type, used to constrain the selection criteria.
point-to-point Empty element indicating that part of the selection criteria for an interface should be whether or not it is a point-to-point interface.
public-address Empty element indicating that part of the selection criteria for an interface should be whether or not it has a publicly routable address.
site-local-address Empty element indicating that part of the selection criteria for an interface should be whether or not an address associated with it is site-local.
subnet-match A network IP address and the number of bits in the address' network prefix, written in "slash notation"; e.g. "192.168.0.0/16".
up Empty element indicating that part of the selection criteria for an interface should be whether or not it is currently up.
virtual Empty element indicating that part of the selection criteria for an interface should be whether or not it is a virtual interface.

  • Configure Interface Attributes

    Choose either the Management CLI or the Management Console to configure your interface attributes as required.
    • Configure Interface Attributes with the Management CLI

      Use the Management CLI to add new interfaces and write new values to the interface attributes.
      1. Add a New Interface

        Use the add operation to create a new interface if required. You can run this command from the root of the Management CLI session, which in the following example creates a new interface name title interfacename, with an inet-address declared as 12.0.0.2.
        /interface=interfacename/:add(inet-address=12.0.0.2)
      2. Edit Interface Attributes

        Use the write operation to write a new value to an attribute. you can use tab completion to help complete the command string as you type, as well as to expose the available attributes. The following example updates the inet-address value to 12.0.0.8
        /interface=interfacename/:write(inet-address=12.0.0.8)
      3. Edit Interface Attributes

        Confirm the values are changed by running the read-resource operation with the include-runtime=true parameter to expose all current values active in the server model.
        [standalone@localhost:9999 interface=public] :read-resource(include-runtime=true)
    • Configure Interface Attributes with the Management Console

      Use the Management Console to add new interfaces and write new values to the interface attributes.
      1. Log into the Management Console.

        Log into the Management Console of your Managed Domain or Standalone Server instance.
      2. If you use a Managed Domain, choose the correct profile.

        Select the Profiles tab at the top right, and then select the correct profile from the Profile menu at the top left of the next screen.
      3. Select the Interfaces item from the navigation menu.

        Select the Interfaces menu item from the navigation menu.
      4. Add a New Interface

        1. Click the Add button.
        2. Enter any required values for Name, Inet Address and Address Wildcard.
        3. Click the Save to finish.
      5. Edit Interface Attributes

        1. Select the Interface to edit and click the Edit button.
        2. Enter any required values for Name, Inet Address and Address Wildcard.
        3. Click the Save to finish.

5.2. Socket Binding Groups

5.2.1. About Socket Binding Groups

Socket bindings and socket binding groups allow you to define network ports and their relationship to the networking interfaces required for your JBoss Enterprise Application Platform 6 configuration.
A socket binding is a named configuration for a socket. The declarations for these named configurations can be found in both the domain.xml and standalone.xml configuration files. Other sections of the configuration can then reference those sockets by their logical name, rather than having to include the full details of the socket configuration. This allows you to reference relative socket configurations which may otherwise vary on different machines.
Socket bindings are collected under a socket binding group. A socket binding group is a collection of socket binding declarations that are grouped under a logical name. The named group can then be referenced throughout the configuration. A standalone server contains only one such group, while a managed domain instance can contain multiple groups. You can create a socket binding group for each server group in the managed domain, or share a socket binding group between multiple server groups.
The naming groups allow for simplified references to be used for particular groups of socket bindings when configuring server groups in the case of a managed domain. Another common use is for the configuration and management of multiple instances of the standalone server on the one system. The following examples show the default socket binding groups in the configuration files for the standalone and domain instances.

Example 5.6. Default socket bindings for the standalone configuration

The default socket binding groups in the standalone.xml configuration file are grouped under standard-sockets. This group is also referenced to the public interface, using the same logical referencing methodology.
   
<socket-binding-group name="standard-sockets" default-interface="public">
    <socket-binding name="http" port="8080"/>
    <socket-binding name="https" port="8443"/>
    <socket-binding name="jacorb" port="3528"/>
    <socket-binding name="jacorb-ssl" port="3529"/>
    <socket-binding name="jmx-connector-registry" port="1090" interface="management"/>
    <socket-binding name="jmx-connector-server" port="1091" interface="management"/>
    <socket-binding name="jndi" port="1099"/>
    <socket-binding name="messaging" port="5445"/>
    <socket-binding name="messaging-throughput" port="5455"/>
    <socket-binding name="osgi-http" port="8090" interface="management"/>
    <socket-binding name="remoting" port="4447"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
</socket-binding-group>

Example 5.7. Default socket bindings for the domain configuration

The default socket binding groups in the domain.xml configuration file contain four groups: the standard-sockets, ha-sockets, full-sockets and the full-ha-sockets groups. These groups are also referenced to an interface called public.
<socket-binding-groups>
    <socket-binding-group name="standard-sockets" default-interface="public">
        <!-- Needed for server groups using the 'default' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'ha' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jgroups-mping" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" port="57600"/>
        <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" port="54200"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="full-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jacorb" interface="unsecure" port="3528"/>
        <socket-binding name="jacorb-ssl" interface="unsecure" port="3529"/>
        <socket-binding name="messaging" port="5445"/>
        <socket-binding name="messaging-group" port="0" multicast-address="${jboss.messaging.group.address:231.7.7.7}" multicast-port="${jboss.messaging.group.port:9876}"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
    <socket-binding-group name="full-ha-sockets" default-interface="public">
        <!-- Needed for server groups using the 'full-ha' profile  -->
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <socket-binding name="jacorb" interface="unsecure" port="3528"/>
        <socket-binding name="jacorb-ssl" interface="unsecure" port="3529"/>
        <socket-binding name="jgroups-mping" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
        <socket-binding name="jgroups-tcp" port="7600"/>
        <socket-binding name="jgroups-tcp-fd" port="57600"/>
        <socket-binding name="jgroups-udp" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
        <socket-binding name="jgroups-udp-fd" port="54200"/>
        <socket-binding name="messaging" port="5445"/>
        <socket-binding name="messaging-group" port="0" multicast-address="${jboss.messaging.group.address:231.7.7.7}" multicast-port="${jboss.messaging.group.port:9876}"/>
        <socket-binding name="messaging-throughput" port="5455"/>
        <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
        <socket-binding name="osgi-http" interface="management" port="8090"/>
        <socket-binding name="remoting" port="4447"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">
            <remote-destination host="localhost" port="25"/>
        </outbound-socket-binding>
    </socket-binding-group>
</socket-binding-groups>

The socket binding instances can be created and edited in the standalone.xml and domain.xml source files in the application server directory. The recommended method of managing bindings is to use either the Management Console or the Management CLI. The advantages of using the Management Console include a graphical user interface with a dedicated Socket Binding Group screen under the General Configuration section. The Management CLI offers an API and workflow based around a command line approach that allows for batch processing and the use of scripts across the higher and lower levels of the application server configuration. Both interfaces allow for changes to be persisted or otherwise saved to the server configuration.

5.2.2. Configure Socket Bindings

Socket bindings can be defined in unique socket binding groups. The Standalone Server contains one such group, the standard-sockets group, and is unable to create any further groups. Instead you can create alternate Standalone Server configuration files. For the Managed Domain however, you can create multiple socket binding groups and configure the socket bindings that they contain as you require. The following table shows the available attributes for each socket binding.

Table 5.2. Socket Binding Attributes

Component Description Role
Name Logical name of the socket configuration that should be used elsewhere in the configuration. Required
Port Base port to which a socket based on this configuration should be bound. Note that servers can be configured to override this base value by applying an increment or decrement to all port values. Required
Interface Logical name of the interface to which a socket based on this configuration should be bound. If not defined, the value of the "default-interface" attribute from the enclosing socket binding group will be used. Optional
Multicast Address If the socket will be used for multicast, the multicast address to use. Optional
Multicast Port Bound to the lifecycle of the conversation. The conversation scope is between the lengths of the request and the session, and is controlled by the application. Optional
Fixed Port If the above contexts do not meet your needs, you can define custom scopes. Optional

  • Configure Socket Bindings in Socket Binding Groups

    Choose either the Management CLI or the Management Console to configure your socket bindings as required.
    • Configure Socket Bindings Using the Management CLI

      Use the Management CLI to configure socket bindings.
      1. Add a New Socket Binding

        Use the add operation to create a new address setting if required. You can run this command from the root of the Management CLI session, which in the following examples creates a new socket binding titled newsocket, with a port attribute declared as 1234. The examples apply for both Standalone Server and a Managed Domain editing on the standard-sockets socket binding group as shown.
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:add(port=1234)
      2. Edit Pattern Attributes

        Use the write operation to write a new value to an attribute. You can use tab completion to help complete the command string as you type, as well as to expose the available attributes. The following example updates the port value to 2020
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:write-attribute(name=port,value=2020)
      3. Confirm Pattern Attributes

        Confirm the values are changed by running the read-resource operation with the include-runtime=true parameter to expose all current values active in the server model.
        [domain@localhost:9999 /] /socket-binding-group=standard-sockets/socket-binding=newsocket/:read-resource
    • Configure Socket Bindings Using the Management Console

      Use the Management Console to configure socket bindings.
      1. Log into the Management Console.

        Log into the Management Console of your Managed Domain or Standalone Server.
      2. Select the Profile tab

        Select the Profiles tab at the top right.
      3. Select the Socket Binding item from the navigation menu.

        Select the Socket Binding menu item from the navigation menu. If you are using a Managed Domain, select the desired group in the Socket Binding Groups menu.
      4. Add a New Socket Binding

        1. Click the Add button.
        2. Enter any required values for Name, Port and Binding Group.
        3. Click the Save to finish.
      5. Edit Interface Attributes

        1. Select the Socket Binding to edit and click the Edit button.
        2. Enter any required values such as Name, Interface or Port.
        3. Click the Save to finish.

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

Numerical port offsets

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

5.2.4. About Port Offsets for Socket Binding Groups

Port offsets are a numeric offset added to the port values given by the socket binding group for that server. This allows a single server to inherit the socket bindings of the server group that is belongs, with an offset to ensure that it does not clash with the other servers in the 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.

5.2.5. Configure Port Offsets

  • Configure Port Offsets

    Choose either the Management CLI or the Management Console to configure your port offsets.
    • Configure Port Offsets Using the Management CLI

      Use the Management CLI to configure port offsets.
      1. Edit Port Offsets

        Use the write operation to write a new value to the port offset atttribute. The following example updates the socket-binding-port-offset value of server-two to 250. This server is a member of the default local host group.
        [domain@localhost:9999 /] /host=master/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)
      2. Confirm Port Offset Attributes

        Confirm the values are changed by running the read-resource operation with the include-runtime=true parameter to expose all current values active in the server model.
        [domain@localhost:9999 /] /host=master/server-config=server-two/:read-resource(include-runtime=true)
    • Configure Port Offsets Using the Management Console

      Use the Management Console to configure port offsets.
      1. Log into the Management Console.

        Log into the Management Console of your Managed Domain.
      2. Select the Server tab

        Select the Server tab at the top right.
      3. Edit Port Offset Attributes

        1. Select the server under the Configuration Name section and click the Edit button.
        2. Enter any desired values in the Port Offset field.
        3. Click the Save button to finish.

5.3. IPv6

5.3.1. Configure JVM Stack Preferences for IPv6 Networking

Task Summary
This topic covers enabling IPv6 networking for the JBoss Enterprise Application Platform 6 installation.

Procedure 5.1. Task

  1. Open the relevant file for the installation:
    • For a Standalone Server:

      Open EAP_HOME/bin/standalone.conf.
    • For a Managed Domain:

      Open EAP_HOME/bin/domain.conf.
  2. Change the IPv4 Stack Java property to false:
    -Djava.net.preferIPv4Stack=false
    For example:
    # Specify options to pass to the Java VM.
    #
    if [ "x$JAVA_OPTS" = "x" ]; then
       JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=false 
       -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 
       -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv6Addresses=true"
    fi
    

5.3.2. Configure the Interface Declarations for IPv6 Networking

Task Summary
Follow these steps to configure the interface inet address to the IPv6 default:

Procedure 5.2. Task

  1. Select the Profile tab, in the top right corner of the console.
  2. Select the Interfaces option under General Configuration.
  3. Select the named network interface to configure.
  4. Click the Edit button.
  5. Set the inet address to:
    ${jboss.bind.address.management:[ADDRESS]}
  6. Click the Save button to save the changes.
  7. Restart the server to implement the changes.

5.3.3. Configure JVM Stack Preferences for IPv6 Addresses

Task Summary
This topic covers configuring the JBoss Enterprise Application Platform 6 installation to prefer IPv6 addresses through the configuration files.

Procedure 5.3. Task

  1. Open the relevant file for the installation:
    • For a Standalone Server:

      Open EAP_HOME/bin/standalone.conf.
    • For a Managed Domain:

      Open EAP_HOME/bin/domain.conf.
  2. Append the following Java property to the Java VM options:
    -Djava.net.preferIPv6Addresses=true
    For example:
    # Specify options to pass to the Java VM.
    #
    if [ "x$JAVA_OPTS" = "x" ]; then
       JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=false 
       -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 
       -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv6Addresses=true"
    fi
    

Chapter 6. Datasource Management

6.1. Introduction

6.1.1. About JDBC

The JDBC API is the standard that defines how databases are accessed by Java applications. An application configures a datasource that references a JDBC driver. Application code can then be written against the driver, rather than the database. The driver converts the code to the database language. This means that if the correct driver is installed, an application can be used with any supported database.
The JDBC 4.0 specification is defined here: http://jcp.org/en/jsr/detail?id=221.
To get started with JDBC and datasources, refer to the JDBC Driver section of the Administration and Configuration Guide for JBoss Enterprise Application Platform 6.

6.1.2. JBoss Enterprise Application Platform 6 Supported Databases

The list of JDBC compliant databases supported by JBoss Enterprise Application Platform 6 is available here: http://www.redhat.com/resourcelibrary/articles/jboss-enterprise-application-platform-supported-configurations.

6.1.3. Types of Datasources

The two general types of resources are referred to as datasources and XA datasources.
Non-XA datasources are used for applications which do not use transactions, or applications which use transactions with a single database.
XA datasources are used by applications whose transactions are distributed across multiple databases. XA datasources introduce additional overhead.
You specify the type of your datasource when you create it in the Management Console or Management CLI.

6.1.4. The Example Datasource

JBoss Enterprise Application Platform 6 includes a H2 database. It is a lightweight, relational database management system that provides developers with the ability to quickly build applications, and is the example datasource for the platform.

Warning

However, it should not be used in a production environment. It is a very small, self-contained datasource that supports all of the standards needed for testing and building applications, but is not robust or scalable enough for production use.
For a list of supported and certified datasources, refer here: Section 6.1.2, “JBoss Enterprise Application Platform 6 Supported Databases”.

6.1.5. Deployment of -ds.xml files

In JBoss Enterprise Application Platform 6, datasources are defined as a resource of the server subsystem. In previous versions, a *-ds.xml datasource configuration file was required in the deployment directory of the server configuration. *-ds.xml files can still be deployed in JBoss Enterprise Application Platform 6, following the schema available here: http://docs.jboss.org/ironjacamar/schema/datasources_1_1.xsd.

Warning

This feature should only be used for development. It is not recommended for production environments, because it is not supported by the JBoss administrative and management tools.

Important

It is mandatory to use a reference to an already deployed / defined <driver> entry when deploying *-ds.xml files.

6.2. JDBC Drivers

6.2.1. Install a JDBC Driver with the Management Console

Summary
Before your application can connect to a JDBC datasource, your datasource vendor's JDBC drivers need to be installed in a location where the JBoss Enterprise Application Platform can use them. JBoss Enterprise Application Server allows you to deploy these drivers just like any other deployment. This means that you can deploy them across multiple servers in a server group, if you use a managed domain.

Note

The preferred installation method for JDBC drivers is to install them as a core module. To install the JDBC driver as a core module, refer here: Section 6.2.2, “Install a JDBC Driver as a Core Module”.
Prerequisites
Before performing this task, you need to meet the following prerequisites:
  • Download the JDBC driver from your database vendor.

Procedure 6.1. Task

  1. Access the Management Console.

  2. Deploy the JAR file to your server or server group.

    If you use a managed domain, deploy the JAR file to a server group. Otherwise, deploy it to your server. See Section 8.2.2, “Deploy an Application Using the Management Console”.
Result:
The JDBC driver is deployed, and is available for your applications to use.

6.2.2. Install a JDBC Driver as a Core Module

Prerequisites
Before performing this task, you need to meet the following prerequisites:

Procedure 6.2. Task

  1. Create a file path structure under the EAP_HOME/modules/ directory. For example, for a MySQL JDBC driver, create a directory structure as follows: EAP_HOME/modules/com/mysql/main/.
  2. Copy the JDBC driver JAR into the main/ subdirectory.
  3. In the main/ subdirectory, create a module.xml file similar to the example below:

    Example 6.1. Example module.xml file

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
      <resources>
        <resource-root path="mysql-connector-java-5.1.15.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
      </dependencies>
    </module>
    
    The module name, com.mysql, should match the directory structure for the module.

  4. Start the Server.
  5. Start the Management CLI.
  6. Run the following CLI command to add the JDBC driver module as a driver:
    /subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME)

    Example 6.2. Example CLI Command

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)

Result
The JDBC driver is now installed and set up as a core module, and is available to be referenced by application datasources.

6.2.3. JDBC Driver Download Locations

The following table gives the standard download locations for JDBC drivers of common databases used with the JBoss Enterprise Application Platform. These links point to third-party websites which are not controlled or actively monitored by Red Hat. For the most up-to-date drivers for your database, check your database vendor's documentation and website.

6.2.4. Access Vendor Specific Classes

Summary
This topic covers the steps required to use the JDBC specific classes. This is necessary when an application needs to use vendor specific functionality that is not part of the JDBC API.

Warning

This is advanced usage. Only applications that need functionality not found in the JDBC API should implement this procedure.

Important

This process is required when using the reauthentication mechanism, and accessing vendor specific classes.

Important

Follow the vendor specific API guidelines closely, as the connection is being controlled by the IronJacamar container.

Procedure 6.3. Add a Dependency to the Application

    • Configure the MANIFEST.MF file

      1. Open the application's META-INF/MANIFEST.MF file in a text editor.
      2. Add a dependency for the JDBC module and save the file.
        Dependencies: MODULE_NAME

        Example 6.3. Example Dependency

        Dependencies: com.mysql

      1. Create a jboss-deployment-structure.xml file

        Create a file called jboss-deployment-structure.xml in the META-INF/ or WEB-INF folder of the application.

        Example 6.4. Example jboss-deployment-structure.xml file

        <jboss-deployment-structure>
          <deployment>
            <dependencies>
              <module name="com.mysql" />
            </dependencies>
          </deployment>
        </jboss-deployment-structure>
        

Example 6.5. Access the Vendor Specific API

The example below accesses the MySQL API.
import java.sql.Connection;
import org.jboss.jca.adapters.jdbc.WrappedConnection;

  Connection c = ds.getConnection();
  WrappedConnection wc = (WrappedConnection)c;
  com.mysql.jdbc.Connection mc = wc.getUnderlyingConnection();

6.3. Non-XA Datasources

6.3.1. Create a Non-XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to create a non-XA datasource, using either the Management Console or the Management CLI.

Prerequisites

  • The JBoss Enterprise Application Platform 6 server must be running.

Oracle Datasources

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Procedure 6.4. Task

    • Management CLI

      1. Launch the CLI tool and connect to your server.
      2. Run the following command to create a non-XA datasource, configuring the variables as appropriate:
        data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME  --connection-url=CONNECTION_URL
      3. Enable the datasource:
        data-source enable --name=DATASOURCE_NAME
    • Management Console

      1. Login to the Management Console.
      2. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.1. Datasources panel


      3. Create a new datasource

        1. Select the Add button at the top of the Datasources panel.
        2. Enter the new datasource attributes in the Create Datasource wizard and proceed with the Next button.
        3. Enter the JDBC driver details in the Create Datasource wizard and proceed with the Next button.
        4. Enter the connection settings in the Create Datasource wizard and select the Done button.
Result
The non-XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

6.3.2. Modify a Non-XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to modify a non-XA datasource, using either the Management Console or the Management CLI.

JTA Integration

Non-XA datasources can be integrated with JTA transactions. To integrate the datasource with JTA, ensure that the jta parameter is set to true.

Procedure 6.5. Task

    • Management CLI

      1. Use the write-attribute command to configure a datasource attribute:
        /subsystem=datasources/data-source=DATASOURCE_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
      2. Reload the server to confirm the changes:
        :reload
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.2. Datasources panel


      2. Edit the datasource

        1. Select the relevant datasource from the Available Datasources list. The datasource attributes are displayed in the Attributes panel below it.
        2. Select the Edit button to edit the datasource attributes.
        3. Edit the datasource attributes and select the Save button when done.
Result
The non-XA datasource has been configured. The changes are now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

6.3.3. Remove a Non-XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to remove a non-XA datasource from JBoss Enterprise Application Platform 6, using either the Management Console or the Management CLI.

Procedure 6.6. Task

    • Management CLI

      1. Run the following command to remove a non-XA datasource:
        data-source remove --name=DATASOURCE_NAME
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.3. Datasources panel


      2. Select the registered datasource to be deleted, and click the Remove button in the top right corner of the console.
Result
The non-XA datasource has been removed from the server.

6.4. XA Datasources

6.4.1. Create an XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to create an XA datasource, using either the Management Console or the Management CLI.

Oracle Datasources

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Procedure 6.7. Task

    • Management CLI

      1. Run the following command to create an XA datasource, configuring the variables as appropriate:
        xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS
      2. Configure the XA datasource properties

        1. Set the server name

          Run the following command to configure the server name for the host:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOSTNAME)
        2. Set the database name

          Run the following command to configure the database name:
          /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
      3. Enable the datasource:
        xa-data-source enable --name=XA_DATASOURCE_NAME
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.4. Datasources panel


      2. Select the XA Datasource panel.
      3. Create a new XA datasource

        1. Select the Add button at the top of the XA Datasources panel.
        2. Enter the new XA datasource attributes in the Create XA Datasource wizard and proceed with the Next button.
        3. Enter the JDBC driver details in the Create XA Datasource wizard and proceed with the Next button.
        4. Edit the XA properties and proceed with the Next button.
        5. Enter the connection settings in the Create XA Datasource wizard and select the Done button.
Result
The XA datasource has been added to the server. It is now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

6.4.2. Modify an XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to modify an XA datasource, using either the Management Console or the Management CLI.

Procedure 6.8. Task

    • Management CLI

      1. Configure XA datasource attributes

        Use the write-attribute command to configure a datasource attribute:
        /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
      2. Configure XA datasource properties

        Run the following command to configure an XA datasource subresource:
        /subsystem=datasources/xa-data-source=DATASOURCE_NAME/xa-datasource-properties=PROPERTY_NAME:add(value=PROPERTY_VALUE)
      3. Reload the server to confirm the changes:
        :reload
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.5. Datasources panel


      2. Select the XA Datasource panel.
      3. Edit the datasource

        1. Select the relevant XA datasource from the Available XA Datasources list. The XA datasource attributes are displayed in the Attributes panel below it.
        2. Select the Edit button to edit the datasource attributes.
        3. Edit the XA datasource attributes and select the Save button when done.
Result
The XA datasource has been configured. The changes are now visible in either the standalone.xml or domain.xml file, as well as the management interfaces.

6.4.3. Remove an XA Datasource with the Management Interfaces

Task Summary
This topic covers the steps required to remove an XA datasource from JBoss Enterprise Application Platform 6, using either the Management Console or the Management CLI.

Procedure 6.9. Task

    • Management CLI

      1. Run the following command to remove an XA datasource:
        xa-data-source remove --name=XA_DATASOURCE_NAME
    • Management Console

      1. Navigate to the Datasources panel in the Management Console

          • Standalone Mode

            Select the Profile tab from the top-right of the console.
          • Domain Mode

            1. Select the Profiles tab from the top-right of the console.
            2. Select the appropriate profile from the drop-down box in the top left.
            3. Expand the Subsystems menu on the left of the console.
        1. Select ConnectorDatasources from the menu on the left of the console.
        Datasources panel

        Figure 6.6. Datasources panel


      2. Select the XA Datasource panel.
      3. Select the registered XA datasource to be deleted, and click the Remove button in the top right corner of the console.
Result
The XA datasource has been removed from the server.

6.4.4. XA Recovery

6.4.4.1. About XA Recovery Modules

Each XA resource needs a recovery module associated with its configuration. The recovery module must extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.
JBoss Enterprise Application Platform provides recovery modules for JDBC and JMS XA resources. For these types of resources, recovery modules are automatically registered. If you need to use a custom module, you can register it in your datasource.

6.4.4.2. Configure XA Recovery Modules

For most JDBC and JMS resources, the recovery module is automatically associated with the resource. In these cases, you only need to configure the options that allow the recovery module to connect to your resource to perform recovery.
For custom resources which are not JDBC or JMS, contact Red Hat Global Support Services for information on supported configurations.
Each of these configuration attributes can be set either during datasource creation, or afterward. You can set them using either the web-based Management Console or the command-line Management CLI. Refer to Section 6.4.1, “Create an XA Datasource with the Management Interfaces” and Section 6.4.2, “Modify an XA Datasource with the Management Interfaces” for general information on configuring XA datasources.
Refer to the following tables for general datasource configuration attributes, and for information about configuration details relating to specific database vendors.

Table 6.2. General Configuration Attributes

Attribute Description  
recovery-username
The username the recovery module should use to connect to the resource for recovery.
 
recovery-password
The password the recovery module should use to connect to the resource for recovery.
 
recovery-security-domain
The security domain the recovery module should use to connect to the resource for recovery.
 
recovery-plugin-class-name
If you need to use a custom recovery module, set this attribute to the fully-qualified class name of the module. The module should extend class com.arjuna.ats.jta.recovery.XAResourceRecovery.
 
recovery-plugin-properties
If you use a custom recovery module which requires properties to be set, set this attribute to the list of comma-separated key=value pairs for the properties.
 

Vendor-Specific Configuration Information

Oracle
If the Oracle datasource is configured incorrectly, you may see errors like the following in your log output:
WARN  [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery  got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
To resolve this error, ensure that the Oracle user configured in recovery-username has access to the tables needed for recovery. The following SQL statement shows the correct grants for Oracle 11g or Oracle 10g R2 instances patched for Oracle bug 5945463.
GRANT SELECT ON sys.dba_pending_transactions TO recovery-username;
GRANT SELECT ON sys.pending_trans$ TO recovery-username;
GRANT SELECT ON sys.dba_2pc_pending TO recovery-username;
GRANT EXECUTE ON sys.dbms_xa TO recovery-username;
If you use an Oracle 11 version prior to 11g, change the final EXECUTE statement to the following:
	GRANT EXECUTE ON sys.dbms_system TO recovery-username;
PostgreSQL
See the PostgreSQL documentation for instructions on enabling prepared (i.e. XA) transactions. Version 8.4-701 of PostgreSQL's JDBC driver has a bug in org.postgresql.xa.PGXAConnection which breaks recovery in certain situations. This is fixed in newer versions.
MySQL
Based on http://bugs.mysql.com/bug.php?id=12161, XA transaction recovery did not work in some versions of MySQL 5. This is addressed in MySQL 6.1. Refer to the bug URL or to the MySQL documentation for more information.
IBM DB2
IBM DB2 expects method XAResource.recover to be called only during the designated resynchronization stage which occurs when the application server is restarted after a crash or failure. This is a design decision in the DB2 implementation, and out of the scope of this documentation.

6.5. Datasource Security

6.5.1. About Datasource Security

The preferred solution for datasource security is the use of either security domains or password vaults. Examples of each are included below. For more information, refer to:

Example 6.6. Security Domain Example

<security>
   <security-domain>mySecurityDomain</security-domain>
</security>

Example 6.7. Password Vault Example

<security>
  <user-name>admin</user-name>
  <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>

6.6. Datasource Configuration

6.6.1. Datasource Parameters

Table 6.3. Datasource parameters common to non-XA and XA datasources

Parameter Description
jndi-name The unique JNDI name for the datasource.
pool-name The name of the management pool for the datasource.
enabled Whether or not the datasource is enabled.
use-java-context
Whether to bind the datasource to global JNDI.
spy
Enable spy functionality on the JDBC layer. This logs all JDBC traffic to the datasource. The logging-category parameter must also be set to org.jboss.jdbc.
use-ccm Enable the cached connection manager.
new-connection-sql A SQL statement which executes when the connection is added to the connection pool.
transaction-isolation
One of the following:
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
url-delimiter The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.
url-selector-strategy-class-name A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy.
security
Contains child elements which are security settings. Refer to Table 6.8, “Security parameters”.
validation
Contains child elements which are validation settings. Refer to Table 6.9, “Validation parameters”.
timeout
Contains child elements which are timeout settings. Refer to Table 6.10, “Timeout parameters”.
statement
Contains child elements which are statement settings. Refer to Table 6.11, “Statement parameters”.

Table 6.4. Non-XA datasource parameters

Parameter Description
jta Enable JTA integration for non-XA datasources. Does not apply to XA datasources.
connection-url The JDBC driver connection URL.
driver-class The fully-qualified name of the JDBC driver class.
connection-property
Arbitrary connection properties passed to the method Driver.connect(url,props). Each connection-property specifies a string name/value pair. The property name comes from the name, and the value comes from the element content.
pool
Contains child elements which are pooling settings. Refer to Table 6.6, “Pool parameters common to non-XA and XA datasources”.

Table 6.5. XA datasource parameters

Parameter Description
xa-datasource-property
A property to assign to implementation class XADataSource. Specified by name=value. If a setter method exists, in the format setName, the property is set by calling a setter method in the format of setName(value).
xa-datasource-class
The fully-qualified name of the implementation class javax.sql.XADataSource.
driver
A unique reference to the classloader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
xa-pool
recovery
Contains child elements which are recovery settings. Refer to Table 6.12, “Recovery parameters”.

Table 6.6. Pool parameters common to non-XA and XA datasources

Parameter Description
min-pool-size The minimum number of connections a pool holds.
max-pool-size The maximum number of connections a pool can hold.
prefill Whether to try to prefill the connection pool. An empty element denotes a true value. The default is false.
use-strict-min Whether the pool-size is strict. Defaults to false.
flush-strategy
Whether the pool should be flushed in the case of an error. Valid values are:
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
The default is FailingConnectionOnly.
allow-multiple-users Specifies if multiple users will access the datasource through the getConnection(user, password) method, and whether the internal pool type should account for this behavior.

Table 6.7. XA pool parameters

Parameter Description
is-same-rm-override Whether the javax.transaction.xa.XAResource.isSameRM(XAResource) class returns true or false.
interleaving Whether to enable interleaving for XA connection factories.
no-tx-separate-pools Whether to create separate sub-pools for each context. This is required for Oracle datasources, which do not allow XA connections to be used both inside and outside of a JTA transaction.
pad-xid Whether to pad the Xid.
wrap-xa-resource
Whether to wrap the XAResource in an org.jboss.tm.XAResourceWrapper instance.

Table 6.8. Security parameters

Parameter Description
user-name The username to use to create a new connection.
password The password to use to create a new connection.
security-domain Contains the name of a JAAS security-manager which handles authentication. This name correlates to the application-policy/name attribute of the JAAS login configuration.
reauth-plugin Defines a reauthentication plugin to use to reauthenticate physical connections.

Table 6.9. Validation parameters

Parameter Description
valid-connection-checker
An implementation of interface org.jboss.jca.adaptors.jdbc.ValidConnectionChecker which provides a SQLException.isValidConnection(Connection e) method to validate a connection. An exception means the connection is destroyed. This overrides the parameter check-valid-connection-sql if it is present.
check-valid-connection-sql An SQL statement to check validity of a pool connection. This may be called when a managed connection is taken from a pool for use.
validate-on-match
Indicates whether connection level validation is performed when a connection factory attempts to match a managed connection for a given set. Mutually exclusive to background validation.
background-validation
Specifies that connections are validated on a background thread, rather than being validated prior to use. Mutually exclusive to validate-on-match.
background-validation-millis The amount of time, in milliseconds, that background validation runs.
use-fast-fail
If true, fail a connection allocation on the first attempt, if the connection is invalid. Defaults to false.
stale-connection-checker
An instance of org.jboss.jca.adapters.jdbc.StaleConnectionChecker which provides a Boolean isStaleConnection(SQLException e) method. If this method returns true, the exception is wrapped in an org.jboss.jca.adapters.jdbc.StaleConnectionException, which is a subclass of SQLException.
exception-sorter
An instance of org.jboss.jca.adapters.jdbc.ExceptionSorter which provides a Boolean isExceptionFatal(SQLException e) method. This method validates whether an exception should be broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.

Table 6.10. Timeout parameters

Parameter Description
blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, and exception is thrown. This blocks only while waiting for a permit for a connection, and does not throw an exception if creating a new connection takes a long time. Defaults to 30000, which is 30 seconds.
idle-timeout-minutes
The maximum time, in minutes, before an idle connection is closed. The actual maximum time depends upon the idleRemover scan time, which is half of the smallest idle-timeout-minutes of any pool.
set-tx-query-timeout
Whether to set the query timeout based on the time remaining until transaction timeout. Any configured query timeout is used if no transaction exists. Defaults to false.
query-timeout Timeout for queries, in seconds. The default is no timeout.
allocation-retry The number of times to retry allocating a connection before throwing an exception. The default is 0, so an exception is thrown upon the first failure.
allocation-retry-wait-millis
How long, in milliseconds, to wait before retrying to allocate a connection. The default is 5000, which is 5 seconds.
xa-resource-timeout
If non-zero, this value is passed to method XAResource.setTransactionTimeout.

Table 6.11. Statement parameters

Parameter Description
track-statements
Whether to check for unclosed statements when a connection is returned to a pool and a statement is returned to the prepared statement cache. If false, statements are not tracked.

Valid values

  • true: statements and result sets are tracked, and a warning is issued if they are not closed.
  • false: neither statements or result sets are tracked.
  • nowarn: statements are tracked but no warning is issued. This is the default.
prepared-statement-cache-size The number of prepared statements per connection, in a Least Recently Used (LRU) cache.
share-prepared-statements
Whether asking for the same statement twice without closing it uses the same underlying prepared statement. The default is false.

Table 6.12. Recovery parameters

Parameter Description
recover-credential A username/password pair or security domain to use for recovery.
recover-plugin
An implementation of class org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.

6.6.2. Datasource Connection URLs

Table 6.13. 

Datasource Connection URL
PostgreSQL jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME
MySQL jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME
Oracle jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACLE_SID
IBM DB2 jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME
Microsoft SQLServer jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME

6.6.3. Datasource Extensions

Datasource deployments can use several extensions in the JDBC resource adapter to improve the connection validation, and check whether an exception should reestablish the connection. Those extensions are:

Table 6.14. Datasource Extensions

Datasource Extension Configuration Parameter Description
org.jboss.jca.adapters.jdbc.spi.ExceptionSorter <exception-sorter> Checks whether an SQLException is fatal for the connection on which it was thrown
org.jboss.jca.adapters.jdbc.spi.StaleConnection <stale-connection-checker> Wraps stale SQLExceptions in a org.jboss.jca.adapters.jdbc.StaleConnectionException
org.jboss.jca.adapters.jdbc.spi.ValidConnection <valid-connection-checker> Checks whether a connection is valid for use by the application

JBoss Enterprise Application Platform 6 also features implementations of these extensions for several supported databases.

Extension Implementations

Generic
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
PostgreSQL
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
MySQL
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
IBM DB2
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
Sybase
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
Microsoft SQLServer
  • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
Oracle
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker

6.7. Example Datasources

6.7.1. Example PostgreSQL Datasource

Example 6.8. 

The example below is a PostgreSQL datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
    <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
    <driver>postgresql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="postgresql" module="org.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the PostgreSQL datasource above.
<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-902.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.2. Example PostgreSQL XA Datasource

Example 6.9. 

The example below is a PostgreSQL XA datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS">
    <driver>postgresql</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="PortNumber">5432</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">postgresdb</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker">
      </valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter">
      </exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="postgresql" module="org.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the PostgreSQL XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-902.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.3. Example MySQL Datasource

Example 6.10. 

The example below is a MySQL datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
    <connection-url>jdbc:mysql://mysql-localhost:3306/jbossdb</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the MySQL datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.4. Example MySQL XA Datasource

Example 6.11. 

The example below is a MySQL XA datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:jboss/MysqlXADS" pool-name="MysqlXADS">
  <driver>mysql</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mysqldb</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the MySQL XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.5. Example Oracle Datasource

Oracle Datasources

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Example 6.12. 

The example below is an Oracle datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url>
    <driver>oracle</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Oracle datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
  <resources>
    <resource-root path="ojdbc6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.6. Example Oracle XA Datsource

Oracle Datasources

Prior to version 10.2 of the Oracle datasource, the <no-tx-separate-pools/> parameter was required, as mixing non-transactional and transactional connections would result in an error. This parameter may no longer be required for certain applications.

Important

The following settings must be applied for the user accessing an Oracle XA datasource in order for XA recovery to operate correctly:
  • GRANT SELECT ON sys.dba_pending_transactions TO user;
  • GRANT SELECT ON sys.pending_trans$ TO user;
  • GRANT SELECT ON sys.dba_2pc_pending TO user;
  • GRANT EXECUTE ON sys.dbms_xa TO user;

Example 6.13. 

The example below is an Oracle XA datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:/XAOracleDS" pool-name="XAOracleDS">
    <driver>oracle</driver>
    <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
      <no-tx-separate-pools />
    </xa-pool>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Oracle XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
  <resources>
    <resource-root path="ojdbc6.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.7. Example Microsoft SQLServer Datasource

Example 6.14. 

The example below is a Microsoft SQLServer datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:/MSSQLDS" pool-name="MSSQLDS">
    <connection-url>jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url>
    <driver>sqlserver</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
    </validation>
  </datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
</datasources>
The example below is a module.xml file for the Microsoft SQLServer datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.8. Example Microsoft SQLServer XA Datasource

Example 6.15. 

The example below is a Microsoft SQLServer XA datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:/MSSQLXADS" pool-name="MSSQLXADS">
    <driver>sqlserver</driver>
    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mssqldb</xa-datasource-property>
    <xa-datasource-property name="SelectMethod">cursor</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Microsoft SQLServer XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.9. Example IBM DB2 Datasource

Example 6.16. 

The example below is an IBM DB2 datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:/DB2DS" pool-name="DB2DS">
    <connection-url>jdbc:db2:ibmdb2db</connection-url>
    <driver>ibmdb2</driver>
    <pool>
      <min-pool-size>0</min-pool-size>
      <max-pool-size>50</max-pool-size>
    </pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security> 
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
      <xa-datasource-class>com.ibm.db2.jdbc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the IBM DB2 datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.10. Example IBM DB2 XA Datasource

Example 6.17. 

The example below is an IBM DB2 XA datasource configuration. The datasource has been enabled, a user has been added and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:/DB2XADS" pool-name="DB2XADS">
    <driver>ibmdb2</driver>
    <xa-datasource-property name="DatabaseName">ibmdb2db</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"></valid-connection-checker>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker"></stale-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"></exception-sorter>
    </validation>
    <recovery>
      <recovery-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin">
        <config-property name="EnableIsValid">false</config-property>
        <config-property name="IsValidOverride">false</config-property>
        <config-property name="EnableClose">false</config-property>
      </recovery-plugin>
    </recovery>
  </xa-datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
      <xa-datasource-class>com.ibm.db2.jdbc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the IBM DB2 XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.11. Example Sybase Datasource

Example 6.18. 

The example below is a Sybase datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB" enabled="true">
    <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Sybase datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
  <resources>
    <resource-root path="jconn2.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.7.12. Example Sybase XA Datasource

Example 6.19. 

The example below is a Sybase XA datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.
<datasources>
  <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS" enabled="true">
    <xa-datasource-property name="NetworkProtocol">Tds</xa-datasource-property>
    <xa-datasource-property name="ServerName">myserver</xa-datasource-property>
    <xa-datasource-property name="PortNumber">4100</xa-datasource-property>
    <xa-datasource-property name="DatabaseName">mydatabase</xa-datasource-property>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"></exception-sorter>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <datasource-class>com.sybase.jdbc2.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc3.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Sybase XA datasource above.
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
  <resources>
    <resource-root path="jconn2.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

Chapter 7. Configuring Modules

7.1. Introduction

7.1.1. Modules

A Module is a logical grouping of classes used for class loading and dependency management. JBoss Enterprise Application Platform 6 identifies two different types of modules, sometimes called static and dynamic modules. However the only difference between the two is how they are packaged. All modules provide the same features.
Static Modules
Static Modules are predefined in the EAP_HOME/modules/ directory of the application server. Each sub-directory represents one module and contains one or more JAR files and a configuration file (module.xml). The name of the module is defined in the module.xml file. All the application server provided APIs are provided as static modules, including the Java EE APIs as well as other APIs such as JBoss Logging.
Creating custom static modules can be useful if many applications are deployed on the same server that use the same third party libraries. Instead of bundling those libraries with each application, a module containing these libraries can be created and installed by the JBoss administrator. The applications can then declare an explicit dependency on the custom static modules.
Dynamic Modules
Dynamic Modules are created and loaded by the application server for each JAR or WAR deployment (or subdeployment in an EAR). The name of a dynamic module is derived from the name of the deployed archive. Because deployments are loaded as modules, they can configure dependencies and be used as dependencies by other deployments.
Modules are only loaded when required. This usually only occurs when an application is deployed that has explicit or implicit dependencies.

7.1.2. Global Modules

A global module is a module that JBoss Enterprise Application Platform 6 provides as a dependency to every application. Any module can be made global by adding it to the application server's list of global modules. It does not require changes to the module.

7.1.3. Module Dependencies

A module dependency is a declaration that one module requires the classes of another module in order to function. Modules can declare dependencies on any number of other modules. When the application server loads a module, the modular class loader parses the dependencies of that module and adds the classes from each dependency to its class path. If a specified dependency cannot be found, the module will fail to load.
Deployed applications (JAR and WAR) are loaded as dynamic modules and make use of dependencies to access the APIs provided by JBoss Enterprise Application Platform 6.
There are two types of dependencies: explicit and implicit.
Explicit dependencies are declared in configuration by the developer. Static modules can declare dependencies in the modules.xml file. Dynamic modules can have dependencies declared in the MANIFEST.MF or jboss-deployment-structure.xml deployment descriptors of the deployment.
Explicit dependencies can be specified as optional. Failure to load an optional dependency will not cause a module to fail to load. However if the dependency becomes available later it will NOT be added to the module's class path. Dependencies must be available when the module is loaded.
Implicit dependencies are added automatically by the application server when certain conditions or meta-data are found in a deployment. The Java EE 6 APIs supplied with JBoss Enterprise Application Platform are examples of modules that are added by detection of implicit dependencies in deployments.
Deployments can also be configured to exclude specific implicit dependencies. This is done with the jboss-deployment-structure.xml deployment descriptor file. This is commonly done when an application bundles a specific version of a library that the application server will attempt to add as an implicit dependency.
A module's class path contains only its own classes and that of it's immediate dependencies. A module is not able to access the classes of the dependencies of one of its dependencies. However a module can specify that an explicit dependency is exported. An exported dependency is provided to any module that depends on the module that exports it.

Example 7.1. Module dependencies

Module A depends on Module B and Module B depends on Module C. Module A can access the classes of Module B, and Module B can access the classes of Module C. Module A cannot access the classes of Module C unless:
  • Module A declares an explicit dependency on Module C, or
  • Module B exports its dependency on Module C.

7.1.4. Subdeployment Class Loader Isolation

Each subdeployment in an Enterprise Archive (EAR) is an dynamic module with its own class loader and cannot access the resources of other subdeployments. This is called subdeployment class loader isolation.
JBoss Enterprise Application Platform 6 has strict subdeployment class loader isolation disabled by default. It can be enabled if required.

7.2. Disable Sub-Deployment Module Isolation for All Deployments

This task shows server administrators how to disable Subdeployment Module Isolation on the application server. This affects all deployments.

Warning

This task requires you to edit the XML configuration files of the server. The server must be halted before doing this. This is temporary as the final release administration tools will support this type of configuration.
  1. Stop the server

    Halt the JBoss Enterprise Application Platform server.
  2. Open the server configuration file

    Open the server configuration file in a text editor.
    This file will be different for a managed domain or standalone server. In addition, non-default locations and file names may be used. The default configuration files are domain/configuration/domain.xml and standalone/configuration/standalone.xml for managed domains and standalone servers respectively.
  3. Locate the EE Subsystem Configuration

    Locate the EE Subsystem configuration element in the configuration file. The <profile> element of the configuration file contains several subsystem elements. The EE Subsystem element has the namespace of urn:jboss:domain:ee:1.0.
    <profile>
    
       ...
    
       <subsystem xmlns="urn:jboss:domain:ee:1.0" />
    
       ...
    The default configuration has a single self-closing tag but a custom configuration may have separate open and closing tags (possibly with other elements within) like this:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ></subsystem>
  4. Replace self-closing tags if necessary

    If the EE Subsystem element is a single self-closing tag then replace with with appropriate opening and closing tags like this:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ></subsystem>
  5. Add ear-subdeployments-isolated element

    Add the ear-subdeployments-isolated element as a child of the EE Subsystem element and add the content of false like this:
    <subsystem xmlns="urn:jboss:domain:ee:1.0" ><ear-subdeployments-isolated>false</ear-subdeployments-isolated></subsystem>
  6. Start the server

    Relaunch the JBoss Enterprise Application Platform server to start it running with the new configuration.
Result:
The server will now be running with Subdeployment Module Isolation disabled for all deployments.

7.3. Add a module to all deployments

This task shows how JBoss administrators can define a list of global modules.

Prerequisites

  1. You must know the name of the modules that are to be configured as global modules. Refer to Section 7.4.1, “Included Modules” for the list of static modules included with JBoss Enterprise Application Platform 6. If the module is in another deployment, refer to Section 7.4.2, “Dynamic Module Naming” to determine the module name.

Procedure 7.1. Add a module to the list of global modules

  1. Navigate to the EE Subsystem panel.
    EE Subsystem Panel

    Figure 7.1. EE Subsystem Panel


  2. Click the Add button in the Global Modules section. The Create Module dialog appears.
  3. Type in the name of the module and optionally the module slot.
  4. Click the Save button to add the new global module, or click the Cancel link to abort.
    • If you click the Save button, the dialog will close and the specified module will be added to the list of global modules.
    • If you click Cancel, the dialog will close and no changes will be made.
Result
The modules added to the list of global modules will be added as dependencies to every deployment.

7.4. Reference

7.4.1. Included Modules

  • asm.asm
  • ch.qos.cal10n
  • com.google.guava
  • com.h2database.h2
  • com.sun.jsf-impl
  • com.sun.jsf-impl
  • com.sun.xml.bind
  • com.sun.xml.messaging.saaj
  • gnu.getopt
  • javaee.api
  • javax.activation.api
  • javax.annotation.api
  • javax.api
  • javax.ejb.api
  • javax.el.api
  • javax.enterprise.api
  • javax.enterprise.deploy.api
  • javax.faces.api
  • javax.faces.api
  • javax.inject.api
  • javax.interceptor.api
  • javax.jms.api
  • javax.jws.api
  • javax.mail.api
  • javax.management.j2ee.api
  • javax.persistence.api
  • javax.resource.api
  • javax.rmi.api
  • javax.security.auth.message.api
  • javax.security.jacc.api
  • javax.servlet.api
  • javax.servlet.jsp.api
  • javax.servlet.jstl.api
  • javax.transaction.api
  • javax.validation.api
  • javax.ws.rs.api
  • javax.wsdl4j.api
  • javax.xml.bind.api
  • javax.xml.jaxp-provider
  • javax.xml.registry.api
  • javax.xml.rpc.api
  • javax.xml.soap.api
  • javax.xml.stream.api
  • javax.xml.ws.api
  • jline
  • net.sourceforge.cssparser
  • net.sourceforge.htmlunit
  • net.sourceforge.nekohtml
  • nu.xom
  • org.antlr
  • org.apache.ant
  • org.apache.commons.beanutils
  • org.apache.commons.cli
  • org.apache.commons.codec
  • org.apache.commons.collections
  • org.apache.commons.io
  • org.apache.commons.lang
  • org.apache.commons.logging
  • org.apache.commons.pool
  • org.apache.cxf
  • org.apache.httpcomponents
  • org.apache.james.mime4j
  • org.apache.log4j
  • org.apache.neethi
  • org.apache.santuario.xmlsec
  • org.apache.velocity
  • org.apache.ws.scout
  • org.apache.ws.security
  • org.apache.ws.xmlschema
  • org.apache.xalan
  • org.apache.xerces
  • org.apache.xml-resolver
  • org.codehaus.jackson.jackson-core-asl
  • org.codehaus.jackson.jackson-jaxrs
  • org.codehaus.jackson.jackson-mapper-asl
  • org.codehaus.jackson.jackson-xc
  • org.codehaus.woodstox
  • org.dom4j
  • org.hibernate
  • org.hibernate.envers
  • org.hibernate.infinispan
  • org.hibernate.validator
  • org.hornetq
  • org.hornetq.ra
  • org.infinispan
  • org.infinispan.cachestore.jdbc
  • org.infinispan.cachestore.remote
  • org.infinispan.client.hotrod
  • org.jacorb
  • org.javassist
  • org.jaxen
  • org.jboss.as.aggregate
  • org.jboss.as.appclient
  • org.jboss.as.cli
  • org.jboss.as.clustering.api
  • org.jboss.as.clustering.common
  • org.jboss.as.clustering.ejb3.infinispan
  • org.jboss.as.clustering.impl
  • org.jboss.as.clustering.infinispan
  • org.jboss.as.clustering.jgroups
  • org.jboss.as.clustering.service
  • org.jboss.as.clustering.singleton
  • org.jboss.as.clustering.web.infinispan
  • org.jboss.as.clustering.web.spi
  • org.jboss.as.cmp
  • org.jboss.as.connector
  • org.jboss.as.console
  • org.jboss.as.controller
  • org.jboss.as.controller-client
  • org.jboss.as.deployment-repository
  • org.jboss.as.deployment-scanner
  • org.jboss.as.domain-add-user
  • org.jboss.as.domain-http-error-context
  • org.jboss.as.domain-http-interface
  • org.jboss.as.domain-management
  • org.jboss.as.ee
  • org.jboss.as.ee.deployment
  • org.jboss.as.ejb3
  • org.jboss.as.embedded
  • org.jboss.as.host-controller
  • org.jboss.as.jacorb
  • org.jboss.as.jaxr
  • org.jboss.as.jaxrs
  • org.jboss.as.jdr
  • org.jboss.as.jmx
  • org.jboss.as.jpa
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate
  • org.jboss.as.jpa.hibernate.infinispan
  • org.jboss.as.jpa.openjpa
  • org.jboss.as.jpa.spi
  • org.jboss.as.jpa.util
  • org.jboss.as.jsr77
  • org.jboss.as.logging
  • org.jboss.as.mail
  • org.jboss.as.management-client-content
  • org.jboss.as.messaging
  • org.jboss.as.modcluster
  • org.jboss.as.naming
  • org.jboss.as.network
  • org.jboss.as.osgi
  • org.jboss.as.platform-mbean
  • org.jboss.as.pojo
  • org.jboss.as.process-controller
  • org.jboss.as.protocol
  • org.jboss.as.remoting
  • org.jboss.as.sar
  • org.jboss.as.security
  • org.jboss.as.server
  • org.jboss.as.standalone
  • org.jboss.as.threads
  • org.jboss.as.transactions
  • org.jboss.as.web
  • org.jboss.as.webservices
  • org.jboss.as.webservices.server.integration
  • org.jboss.as.webservices.server.jaxrpc-integration
  • org.jboss.as.weld
  • org.jboss.as.xts
  • org.jboss.classfilewriter
  • org.jboss.com.sun.httpserver
  • org.jboss.common-core
  • org.jboss.dmr
  • org.jboss.ejb-client
  • org.jboss.ejb3
  • org.jboss.iiop-client
  • org.jboss.integration.ext-content
  • org.jboss.interceptor
  • org.jboss.interceptor.spi
  • org.jboss.invocation
  • org.jboss.ironjacamar.api
  • org.jboss.ironjacamar.impl
  • org.jboss.ironjacamar.jdbcadapters
  • org.jboss.jandex
  • org.jboss.jaxbintros
  • org.jboss.jboss-transaction-spi
  • org.jboss.jsfunit.core
  • org.jboss.jts
  • org.jboss.jts.integration
  • org.jboss.logging
  • org.jboss.logmanager
  • org.jboss.logmanager.log4j
  • org.jboss.marshalling
  • org.jboss.marshalling.river
  • org.jboss.metadata
  • org.jboss.modules
  • org.jboss.msc
  • org.jboss.netty
  • org.jboss.osgi.deployment
  • org.jboss.osgi.framework
  • org.jboss.osgi.resolver
  • org.jboss.osgi.spi
  • org.jboss.osgi.vfs
  • org.jboss.remoting3
  • org.jboss.resteasy.resteasy-atom-provider
  • org.jboss.resteasy.resteasy-cdi
  • org.jboss.resteasy.resteasy-jackson-provider
  • org.jboss.resteasy.resteasy-jaxb-provider
  • org.jboss.resteasy.resteasy-jaxrs
  • org.jboss.resteasy.resteasy-jsapi
  • org.jboss.resteasy.resteasy-multipart-provider
  • org.jboss.sasl
  • org.jboss.security.negotiation
  • org.jboss.security.xacml
  • org.jboss.shrinkwrap.core
  • org.jboss.staxmapper
  • org.jboss.stdio
  • org.jboss.threads
  • org.jboss.vfs
  • org.jboss.weld.api
  • org.jboss.weld.core
  • org.jboss.weld.spi
  • org.jboss.ws.api
  • org.jboss.ws.common
  • org.jboss.ws.cxf.jbossws-cxf-client
  • org.jboss.ws.cxf.jbossws-cxf-factories
  • org.jboss.ws.cxf.jbossws-cxf-server
  • org.jboss.ws.cxf.jbossws-cxf-transports-httpserver
  • org.jboss.ws.jaxws-client
  • org.jboss.ws.jaxws-jboss-httpserver-httpspi
  • org.jboss.ws.native.jbossws-native-core
  • org.jboss.ws.native.jbossws-native-factories
  • org.jboss.ws.native.jbossws-native-services
  • org.jboss.ws.saaj-impl
  • org.jboss.ws.spi
  • org.jboss.ws.tools.common
  • org.jboss.ws.tools.wsconsume
  • org.jboss.ws.tools.wsprovide
  • org.jboss.xb
  • org.jboss.xnio
  • org.jboss.xnio.nio
  • org.jboss.xts
  • org.jdom
  • org.jgroups
  • org.joda.time
  • org.junit
  • org.omg.api
  • org.osgi.core
  • org.picketbox
  • org.picketlink
  • org.python.jython.standalone
  • org.scannotation.scannotation
  • org.slf4j
  • org.slf4j.ext
  • org.slf4j.impl
  • org.slf4j.jcl-over-slf4j
  • org.w3c.css.sac
  • sun.jdk

7.4.2. Dynamic Module Naming

All deployments are loaded as modules by JBoss Enterprise Application Platform 6 and named according to the following conventions.
  1. Deployments of WAR and JAR files are named with the following format:
     deployment.DEPLOYMENT_NAME 
    For example, inventory.war and store.jar will have the module names of deployment.inventory.war and deployment.store.jar respectively.
  2. Subdeployments within an Enterprise Archive are named with the following format:
     deployment.EAR_NAME.SUBDEPLOYMENT_NAME 
    For example, the subdeployment of reports.war within the enterprise archive accounts.ear will have the module name of deployment.accounting.ear.reports.war.

Chapter 8. Application Deployment

8.1. About Application Deployment

JBoss Enterprise Application Platform 6 features a range of application deployment and configuration options to cater to both administrative and development environments. For administrators, the Management Console and the Management CLI offer the ideal graphical and command line interfaces to manage application deployments in a production environment. For developers, the range of application deployment testing options include a highly configurable filesystem deployment scanner, the use of an IDE such as JBoss Developer Studio, or deployment and undeployment via Maven.

8.2. Deploy with the Management Console

8.2.1. Manage Application Deployment in the Management Console

Deploying applications via the Management Console gives you the benefit of a graphical interface that is easy to use. You can see at a glance what applications are deployed to your server or server groups, and you can disable or delete applications from the content repository as required.

8.2.2. Deploy an Application Using the Management Console

Procedure 8.1. Task

  1. Navigate to the Manage Deployments panel in the Management Console

    1. Select the Runtime tab from the top right of the console.
    2. Select the DeploymentsManage Deployments option from the menu on the left of the console.
  2. Deploy an application

    The deployment method will differ depending on whether you are deploying to a standalone server instance or a managed domain.
    • Deploy to a standalone server instance

      The Deployments table shows all available application deployments and their status.
      Available deployments

      Figure 8.1. Available deployments


      1. Enable the application in a standalone server instance

        Click on the Enable button in the Deployments table to enable the application deployment.
      2. Confirm

        Click on the confirm button to confirm that the application will be enabled on the server instance.
        Available deployments in a standalone server

        Figure 8.2. Available deployments in a standalone server


    • Deploy to a managed domain

      The Deployment Content section contains a Content Repository table showing all available application deployments and their status.
      Available deployments in a managed domain

      Figure 8.3. Available deployments in a managed domain


      1. Enable the application in a Managed Domain

        Click on the Add to Groups button in the Content Repository table.
      2. Select server groups

        Check the boxes for each of the server groups that you want the application to be added to and click on the Save button to continue.
        Select server groups for application deployment

        Figure 8.4. Select server groups for application deployment


      3. Confirm

        Click on the Server Group Deployments tab to view the Server Groups table. Your application is now deployed to the server groups that you have selected.
        Confirmation of application deployment to server groups

        Figure 8.5. Confirmation of application deployment to server groups


Result
The application is deployed on the relevant server or server group.

8.2.3. Undeploy an Application Using the Management Console

Procedure 8.2. Task

  1. Navigate to the Manage Deployments panel in the Management Console

    1. Select the Runtime tab from the top right of the console.
    2. Select the DeploymentsManage Deployments option from the menu on the left of the console.
  2. Undeploy an application

    The undeployment method will differ depending on whether you are deploying to a standalone server instance or a managed domain.
    • Undeploy from a standalone server instance

      The Deployments table shows all available application deployments and their status.
      Available deployments

      Figure 8.6. Available deployments


      1. Disable the application in a standalone server instance

        Click on the Disable button in the Deployments table to disable the application.
      2. Confirm that you wish to disable the application

        Click on the confirm button to confirm that the application will be disabled on the server instance.
        Confirm the application to disable

        Figure 8.7. Confirm the application to disable


    • Undeploy from a managed domain

      The Deployment Content section contains a Content Repository table showing all available application deployments and their status.
      Available deployments in a managed domain

      Figure 8.8. Available deployments in a managed domain


      1. Disable the application in a Managed Domain

        Click on the Server Group Deployments tab to view the server groups and the status of their deployed applications.
        Server group deployments

        Figure 8.9. Server group deployments


      2. Select server group

        Click on the name of the server in the Server Group table to undeploy an application from.
      3. Disable the application from the selected server

        Click on the disable button to disable the application for the selected server.
      4. Confirm that you wish to disable the application

        Click on the confirm button to confirm that the application will be disabled on the server instance.
        Confirm the application to disable

        Figure 8.10. Confirm the application to disable


      5. Repeat undeployment for remaining server groups

        Repeat as required for other server groups. The application status is confirmed for each server group in the Deployments table.
        Confirmation of application undeployment from a server group

        Figure 8.11. Confirmation of application undeployment from a server group


Result
The application is undeployed from the relevant server or server group.

8.3. Deploy with the Management CLI

8.3.1. Manage Application Deployment in the Management CLI

Deploying applications via the Management CLI gives you the benefit of single command line interface with the ability to create and run deployment scripts. You can use this scripting ability to configure specific application deployment and management scenarios. You can manage the deployment status of a single server in the case of a standalone instance, or an entire network of servers in the case of a managed domain.

8.3.2. Deploy an Application in a Managed Domain Using the Management CLI

Procedure 8.3. Task

  • Run the deploy command

    From the Management CLI, enter the deploy command with the path to the application deployment. Include the --all-server-groups parameter to deploy to all server groups.
    [domain@localhost:9999 /] deploy /path/to/test-application.war --all-server-groups
    'test-application.war' deployed successfully.
    • Alternatively, define specific server groups for the deployment with the --server-groups parameter.
      [domain@localhost:9999 /] deploy /path/to/test-application.war --server-groups server_group_1, server_group_2 
      'test-application.war' deployed successfully.
Result
The specified application is now deployed to a server group in your managed domain.

8.3.3. Undeploy an Application in a Managed Domain Using the Management CLI

Procedure 8.4. Task

  • Run the undeploy command

    From the Management CLI, enter the undeploy command with the filename of the application deployment. The application can be undeployed from any server group that it was originally deployed to with the addition of the --all-relevant-server-groups parameter.
    [domain@localhost:9999 /] undeploy test-application.war --all-relevant-server-groups
    Successfully undeployed test-application.war.
Result
The specified application is now undeployed.

8.3.4. Deploy an Application in a Standalone Server Using the Management CLI

Procedure 8.5. Task

  • Run the deploy command

    From the Management CLI, enter the deploy command with the path to the application deployment.
    [standalone@localhost:9999 /] deploy ~/path/to/test-application.war 
    'test-application.war' deployed successfully.
Result
The specified application is now deployed in the standalone server.

8.3.5. Undeploy an Application in a Standalone Server Using the Management CLI

Procedure 8.6. Task

  • Run the undeploy command

    From the Management CLI, enter the undeploy command with the filename of the application deployment.
    [standalone@localhost:9999 /] undeploy test-application.war 
    Successfully undeployed test-application.war.
Result
The specified application is now undeployed.

8.4. Deploy with the Deployment Scanner

8.4.1. Manage Application Deployment in the Deployment Scanner

Deploying applications to a standalone server instance via the deployment scanner allows you to build and test applications in a manner suited for rapid development cycles. You can configure the deployment scanner to suit your needs for deployment frequency and behaviour for a variety of application types.

8.4.2. Deploy an Application to a Standalone Server Instance with the Deployment Scanner

Summary
This task shows a method for deploying applications to a standalone server instance with the deployment scanner. As indicated in the Section 8.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Procedure 8.7. Task

  1. Copy content to the deployment folder

    Copy the application file to the deployment folder found at EAP_HOME/standalone/deployments/.
  2. Deployment scanning modes

    The application deployment varies between automatic and manual deployment scanner modes.
    • Automatic deployment

      The deployment scanner picks up a change to the state of the folder and creates a marker file as defined in the Section 8.4.5, “Reference for Deployment Scanner Marker Files” topic.
    • Manual deployment

      The deployment scanner requires a marker file to trigger the deployment process. The following example uses the Unix touch command to create a new .dodeploy file.

      Example 8.1. Deploy with the touch command

      [user@host bin]$ touch $EAP_HOME/standalone/deployments/example.war.dodeploy

Result
The application file is deployed to the application server. A marker file is created in the deployment folder to indicate the successful deployment, and the application is flagged as Enabled in the Management Console.

Example 8.2. Deployment folder contents after deployment

example.war
example.war.deployed

8.4.3. Undeploy an Application to a Standalone Server Instance with the Deployment Scanner

Summary
This task shows a method for undeploying applications from a standalone server instance that have been deployed with the deployment scanner. As indicated in the Section 8.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Note

The deployment scanner should not be used in conjunction with other deployment methods for application management. Applications removed from the application server by the management console will be removed from the runtime without affecting the marker files or application contained in the deployment directory. To minimize the risk of accidental redployment or other errors, use the Management CLI and Management Console for administration in production environments.

Procedure 8.8. Task

  • Undeploy the application

    There are two methods to undeploy the application depending on whether you want to delete the application from the deployment folder or only alter its deployment status.
    • Undeploy by deleting the marker file

      Delete the deployed application's example.war.deployed marker file to trigger the deployment scanner to begin undeploying the application from the runtime.
      Result
      The deployment scanner undeploys the application and creates a example.war.undeployed marker file. The application remains in the deployment folder.
    • Undeploy by removing the application

      Remove the application from the deployment directory to trigger the deployment scanner to begin undeploying the application from the runtime.
      Result
      The deployment scanner undeploys the application and creates a filename.filetype.undeployed marker file. The application is not present in the deployment folder.
Result
The application file is undeployed from the application server and is not visible in the Deployments screen of the Management Console.

8.4.4. Redeploy an Application to a Standalone Server Instance with the Deployment Scanner

Summary
This task shows a method for redeploying applications to a standalone server instance that have been deployed with the deployment scanner. As indicated in the Section 8.1, “About Application Deployment” topic, this method is retained for the convenience of developers, where the Management Console and Management CLI methods are recommended for application management under production environments.

Procedure 8.9. Task

  • Redeploy the application

    There are three possible methods to redeploy an application deployed with the deployment scanner. These methods trigger the deployment scanner to initiate a deployment cycle, and can be chosen to suit personal preference.
Result
The application file is redeployed.

8.4.5. Reference for Deployment Scanner Marker Files

Marker files
Marker files are a part of the deployment scanner subsystem. These files mark the status of an application within the deployment directory of the standalone server instance. A marker file has the same name as the application, with the file suffix indicating the state of the application's deployment. The following table defines the types and responses for each marker file.

Example 8.4. Marker file example

The following example shows the marker file for a successfully deployed instance of an application called testapplication.war.
testapplication.war.deployed

Table 8.1. Marker filetype definitions

Filename Suffix Origin Description
.dodeploy User generated Indicates that the content should be deployed or redeployed into the runtime.
.skipdeploy User generated Disables auto-deploy of an application while present. Useful as a method of temporarily blocking the auto-deployment of exploded content, preventing the risk of incomplete content edits pushing live. Can be used with zipped content, although the scanner detects in-progress changes to zipped content and waits until completion.
.isdeploying System generated Indicates the initiation of deployment. The marker file will be deleted when the deployment process completes.
.deployed System generated Indicates that the content has been deployed. The content will be undeployed if this file is deleted.
.failed System generated Indicates deployment failure. The marker file contains information about the cause of failure. If the marker file is deleted, the content will be visible to the auto-deployment again.
.isundeploying System generated Indicates a response to a .deployed file deletion. The content will be undeployed and the marker will be automatically deleted upon completion.
.undeployed System generated Indicates that the content has been undeployed. Deletion of the marker file has no impact to content redeployment.
.pending System generated Indicates that deployment instructions will be sent to the server pending resolution of a detected issue. This marker serves as a global deployment road-block. The scanner will not instruct the server to deploy or undeploy any other content while this condition exists.

8.4.6. Reference for Deployment Scanner Attributes

The deployment scanner contains the following attributes that are exposed to the Management CLI and able to be configured using the write-attribute operation. For more information on configuration options, refer to the topic Section 8.4.8, “Configure the Deployment Scanner with the Management CLI”.

Table 8.2. Deployment Scanner Attributes

Name Description Type default Value
auto-deploy-exploded Allows the automatic deployment of exploded content without requiring a .dodeploy marker file. Recommended for only basic development scenarios to prevent exploded application deployment from occurring during changes by the developer or operating system. Boolean False
auto-deploy-xml Allows the automatic deployment of XML content without requiring a .dodeploy marker file. Boolean True
auto-deploy-zipped Allows the automatic deployment of zipped content without requiring a .dodeploy marker file. Boolean True
deployment-timeout The time value in seconds for the deployment scanner to allow a deployment attempt before being cancelled. Long 60
path Defines the actual filesystem path to be scanned. If the relative-to attribute is specified, the path value acts as a relative addition to that directory or path. String Deployments
relative-to Reference to a filesystem path defined in the paths section of the server configuration XML file. String jboss.server.base.dir
scan-enabled Allows the automatic scanning for applications by scan-interval and at startup. Boolean True
scan-interval The time interval in milliseconds between scans of the repository. A value of less than 1 restricts the scanner to operate only at startup. Int 5000

8.4.7. Configure the Deployment Scanner

The deployment scanner can be configured using the Management Console or the Management CLI. You can create a new deployment scanner or manage the existing scanner attributes. These include the scanning interval, the location of the deployment folder, and the application file types that will trigger a deployment.

8.4.8. Configure the Deployment Scanner with the Management CLI

Summary
While there are multiple methods of configuring the deployment scanner, the Management CLI can be used to expose and modify the attributes by use of batch scripts or in real time. You can modify the behaviour of the deployment scanner by use of the read-attribute and write-attribute global command line operations. Further information about the deployment scanner attributes are defined in the topic Section 8.4.6, “Reference for Deployment Scanner Attributes”.
The deployment scanner is a subsystem of JBoss Enterprise Application Platform 6, and can be viewed in the standalone.xml.
<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
</subsystem>

Procedure 8.10. Task

  1. Determine the deployment scanner attributes to configure

    Configuring the deployment scanner via the Management CLI requires that you first expose the correct attribute names. You can do this with the read-resources operation at either the root node, or by using the cd command to change into the subsystem child node. You can also display the attributes with the ls command at this level.
    • Expose the deployment scanner attributes with the read-resource operation

      Use the read-resource operation to expose the attributes defined by the default deployment scanner resource.
      [standalone@localhost:9999 /]/subsystem=deployment-scanner/scanner=default:read-resource
      {
          "outcome" => "success",
          "result" => {
              "auto-deploy-exploded" => false,
              "auto-deploy-xml" => true,
              "auto-deploy-zipped" => true,
              "deployment-timeout" => 60,
              "path" => "deployments",
              "relative-to" => "jboss.server.base.dir",
              "scan-enabled" => true,
              "scan-interval" => 5000
          }
      }
    • Expose the deployment scanner attributes with the ls command

      Use the ls command with the -l optional argument to display a table of results that include the subsystem node attributes, values, and type. You can learn more about the ls command and its arguments by exposing the CLI help entry by typing ls --help. For more information about the help menu in the Management CLI, refer to the topic Section 3.3.5, “Get Help with the Management CLI”.
      [standalone@localhost:9999 /] ls -l /subsystem=deployment-scanner/scanner=default
      ATTRIBUTE            VALUE                 TYPE    
      auto-deploy-exploded false                 BOOLEAN 
      auto-deploy-xml      true                  BOOLEAN 
      auto-deploy-zipped   true                  BOOLEAN 
      deployment-timeout   60                    LONG    
      path                 deployments           STRING  
      relative-to          jboss.server.base.dir STRING  
      scan-enabled         true                  BOOLEAN 
      scan-interval        5000                  INT
  2. Configure the deployment scanner with the write-attribute operation

    Once you have determined the name of the attribute to modify, use the write-attribute to specify the attribute name and the new value to write to it. The following examples are all run at the child node level, which can be accessed by using the cd command and tab completion to expose and change into the default scanner node.
    [standalone@localhost:9999 /] cd subsystem=deployment-scanner/scanner=default
    1. Enable automatic deployment of exploded content

      Use the write-attribute operation to enable the automatic deployment of exploded application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-exploded,value=true)
      {"outcome" => "success"}
    2. Disable the automatic deployment of XML content

      Use the write-attribute operation to disable the automatic deployment of XML application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-xml,value=false)     
      {"outcome" => "success"}
    3. Disable the automatic deployment of zipped content

      Use the write-attribute command to disable the automatic deployment of zipped application content.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=auto-deploy-zipped,value=false)
      {"outcome" => "success"}
    4. Configure the path attribute

      Use the write-attribute operation to modify the path attribute, substituting the example newpathname value for the new path name for the deployment scanner to monitor. Note that the server will require a reload to take effect.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=path,value=newpathname)            
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
    5. Configure the relative path attribute

      Use the write-attribute operation to modify the relative reference to the filesystem path defined in the paths section of the configuration XML file. Note that the server will require a reload to take effect.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=relative-to,value=new.relative.dir)
      {
          "outcome" => "success",
          "response-headers" => {
              "operation-requires-reload" => true,
              "process-state" => "reload-required"
          }
      }
    6. Disable the deployment scanner

      Use the write-attribute operation to disable the deployment scanner by setting the scan-enabled value to false.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-enabled,value=false)        
      {"outcome" => "success"}
    7. Change the scan interval

      Use the write-attribute operation to modify the scan interval time from 5000 milliseconds to 10000 milliseconds.
      [standalone@localhost:9999 scanner=default] :write-attribute(name=scan-interval,value=10000)
      {"outcome" => "success"}
Result
Your configuration changes are saved to the deployment scanner.

8.5. Deploy with Maven

8.5.1. Manage Application Deployment with Maven

Deploying applications via Maven allows you to incorporate a deployment cycle as part of your existing development workflow.

8.5.2. Deploy an Application with Maven

Summary
This task shows a method for deploying applications with Maven. The example provided uses the jboss-as-helloworld.war application found in the JBoss Enterprise Application Platform 6 Quick Starts collection. The helloworld project contains a POM file which initializes the jboss-as-maven-plugin. This plugin provides simple operations to deploy and undeploy applications to and from the application server.

Procedure 8.11. Deploy an application with Maven

  1. Run the Maven deploy command in a terminal session

    Open a terminal session and navigate to the directory containing the quickstart examples.
  2. Run the Maven deploy command to deploy the application. If the application is already running, it will be redeployed.
    [localhost]$ mvn package jboss-as:deploy
  3. Confirm the application deployment

    • View result in terminal window

      The deployment can be confirmed by viewing the operation logs in the terminal window.

      Example 8.5. Maven confirmation for helloworld application

                              
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESSFUL
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 3 seconds
      [INFO] Finished at: Mon Oct 10 17:22:05 EST 2011
      [INFO] Final Memory: 21M/343M
      [INFO] ------------------------------------------------------------------------
      

    • View results in server terminal window

      The deployment can also be confirmed in the status stream of the active application server instance.

      Example 8.6. Application server confirmation for helloworld application

           
      17:22:04,922 INFO  [org.jboss.as.server.deployment] (pool-1-thread-3) Content added at location /home/username/EAP_Home/standalone/data/content/2c/39607b0c8dbc6a36585f72866c1bcfc951f3ff/content
      17:22:04,924 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-1) Starting deployment of "jboss-as-helloworld.war"
      17:22:04,954 INFO  [org.jboss.weld] (MSC service thread 1-3) Processing CDI deployment: jboss-as-helloworld.war
      17:22:04,973 INFO  [org.jboss.weld] (MSC service thread 1-2) Starting Services for CDI deployment: jboss-as-helloworld.war
      17:22:04,979 INFO  [org.jboss.weld] (MSC service thread 1-4) Starting weld service
      17:22:05,051 INFO  [org.jboss.web] (MSC service thread 1-2) registering web context: /jboss-as-helloworld
      17:22:05,064 INFO  [org.jboss.as.server.controller] (pool-1-thread-3) Deployed "jboss-as-helloworld.war"
      

Result
The application is deployed to the application server.

8.5.3. Undeploy an Application with Maven

Summary
This task shows a method for undeploying applications with Maven. The example provided uses the jboss-as-helloworld.war application found in the Enterprise Application Server Quick Starts collection. The helloworld project contains a POM file which initializes the jboss-as-maven-plugin. This plug-in provides simple operations to deploy and undeploy applications to and from the application server.

Procedure 8.12. Undeploy an application with Maven

  1. Run the Maven deploy command in a terminal session

    Open a terminal session and navigate to the directory containing the quickstart examples.

    Example 8.7. Change into the helloworld application directory

    [localhost]$ cd ~/EAP_Quickstarts/helloworld
    

  2. Run the Maven undeploy command to undeploy the application.
    [localhost]$ mvn jboss-as:undeploy
  3. Confirm the application undeployment

    • View result in terminal window

      The undeployment can be confirmed by viewing the operation logs in the terminal window.

      Example 8.8. Maven confirmation for helloworld application

                              
      [INFO] ------------------------------------------------------------------------
      [INFO] Building JBoss AS Quickstarts: Helloworld
      [INFO]    task-segment: [jboss-as:undeploy]
      [INFO] ------------------------------------------------------------------------
      [INFO] [jboss-as:undeploy {execution: default-cli}]
      [INFO] Executing goal undeploy for /home/username/EAP_Quickstarts/helloworld/target/jboss-as-helloworld.war on server localhost (127.0.0.1) port 9999.
      Oct 10, 2011 5:33:02 PM org.jboss.remoting3.EndpointImpl <clinit>
      INFO: JBoss Remoting version 3.2.0.Beta2
      Oct 10, 2011 5:33:02 PM org.xnio.Xnio <clinit>
      INFO: XNIO Version 3.0.0.Beta2
      Oct 10, 2011 5:33:02 PM org.xnio.nio.NioXnio <clinit>
      INFO: XNIO NIO Implementation Version 3.0.0.Beta2
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESSFUL
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 1 second
      [INFO] Finished at: Mon Oct 10 17:33:02 EST 2011
      [INFO] Final Memory: 11M/212M
      [INFO] ------------------------------------------------------------------------
      

    • View results in server terminal window

      The undeployment can also be confirmed in the status stream of the active application server instance.

      Example 8.9. Application server confirmation for helloworld application

           
      17:33:02,334 INFO  [org.jboss.weld] (MSC service thread 1-3) Stopping weld service
      17:33:02,342 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-3) Stopped deployment jboss-as-helloworld.war in 15ms
      17:33:02,352 INFO  [org.jboss.as.server.controller] (pool-1-thread-5) Undeployed "jboss-as-helloworld.war"
      

Result
The application is undeployed from the application server.

Chapter 9. Securing JBoss Enterprise Application Platform

9.1. About the Security Subsystem
9.2. About the Structure of the Security Subsystem
9.3. Configure the Security Subsystem
9.4. About Deep Copy Subject Mode
9.5. Enable Deep Copy Subject Mode
9.6. Security Domains
9.6.1. About Security Domains
9.6.2. About Picketbox
9.6.3. About Authentication
9.6.4. Configure Authentication in a Security Domain
9.6.5. About Authorization
9.6.6. Configure Authorization in a Security Domain
9.6.7. About Security Auditing
9.6.8. Configure Security Auditing
9.6.9. About Security Mapping
9.6.10. Configure Security Mapping in a Security Domain
9.6.11. Use a Security Domain in Your Application
9.6.12. Java Authorization Contract for Containers (JACC)
9.6.13. Java Authentication SPI for Containers (JASPI)
9.7. Management Interface Security
9.7.1. Default User Security Configuration
9.7.2. Overview of Advanced Management Interface Configuration
9.7.3. About LDAP
9.7.4. Use LDAP to Authenticate to the Management Interfaces
9.7.5. Disable the HTTP Management Interface
9.7.6. Remove Silent Authentication from the Default Security Realm
9.7.7. Disable Remote Access to the JMX Subsystem
9.7.8. Configure Security Realms for the Management Interfaces
9.8. Network Security
9.8.1. Secure the Management Interfaces
9.8.2. Specify Which Network Interface the JBoss Enterprise Application Platform Uses
9.8.3. Configure Network Firewalls to Work with JBoss Enterprise Application Platform 6
9.8.4. Network Ports Used By JBoss Enterprise Application Platform 6
9.9. Java Security Manager
9.9.1. About the Java Security Manager
9.9.2. Run JBoss Enterprise Application Platform Within the Java Security Manager
9.9.3. About Java Security Manager Policies
9.9.4. Write a Java Security Manager Policy
9.9.5. Debug Security Manager Policies
9.10. Application Security
9.10.1. Enabling/Disabling Descriptor Based Property Replacement
9.11. Password Vaults for Sensitive Strings
9.11.1. About Securing Sensitive Strings in Clear-Text Files
9.11.2. Create a Java Keystore to Store Sensitive Strings
9.11.3. Mask the Keystore Password and Initialize the Password Vault
9.11.4. Configure the JBoss Enterprise Application Platform to Use the Password Vault
9.11.5. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore
9.11.6. Store and Resolve Sensitive Strings In Your Applications

9.1. About the Security Subsystem

The security subsystem provides the infrastructure for all security functionality in the JBoss Enterprise Application Platform. Most configuration elements rarely need to be changed. The only configuration element which may need to be changed is whether to use deep-copy-subject-mode. In addition, you can configure system-wide security properties. Most of the configuration relates to security domains.
Deep Copy Mode
If deep copy subject mode is disabled (the default), copying a security data structure makes a reference to the original, rather than copying the entire data structure. This behavior is more efficient, but is prone to data corruption if multiple threads with the same identity clear the subject by means of a flush or logout operation.
Deep copy subject mode causes a complete copy of the data structure and all its associated data to be made, as long as they are marked cloneable. This is more thread-safe, but less efficient.
System-Wide Security Properties
You can set system-wide security properties, which are applied to java.security.Security class.
A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative security configurations which one or more applications use to control authentication, authorization, auditing, and mapping. Three security domains are included by default: jboss-ejb-policy, jboss-web-policy, and other. The Management API, Management Console, and Management CLI use the other security domain. You can create as many security domains as you need to accomodate the needs of your applications.

9.2. About the Structure of the Security Subsystem

The security subsystem is configured in the managed domain or standalone configuration file. Most of the configuration elements can be configured using the web-based management console or the console-based management CLI. The following is the XML representing an example security subsystem.

Example 9.1. Example Security Subsystsem Configuration

<subsystem xmlns="urn:jboss:domain:security:1.1">
	<security-management>
		...
	</security-management>
	<subject-factory>
		...
	</subject-factory>
    <security-domains>
        <security-domain name="other" cache-type="default">
            <authentication>
                <login-module code="Remoting" flag="optional">
                    <module-option name="password-stacking" value="useFirstPass"/>
                </login-module>
                <login-module code="RealmUsersRoles" flag="required">
                    <module-option name="usersProperties" value="${jboss.domain.config.dir}/application-users.properties"/>
                    <module-option name="rolesProperties" value="${jboss.domain.config.dir}/application-roles.properties"/>
                    <module-option name="realm" value="ApplicationRealm"/>
                    <module-option name="password-stacking" value="useFirstPass"/>
                </login-module>
            </authentication>
        </security-domain>
        <security-domain name="jboss-web-policy" cache-type="default">
            <authorization>
                <policy-module code="Delegating" flag="required"/>
            </authorization>
        </security-domain>
        <security-domain name="jboss-ejb-policy" cache-type="default">
            <authorization>
                <policy-module code="Delegating" flag="required"/>
            </authorization>
        </security-domain>
    </security-domains>
	<security-properties>
		...
	</security-properties>
</subsystem>		

The <security-management>, <subject-factory>, and <security-properties> elements are empty in the default configuration.

Each top-level element within the security subsystem contains information about a different aspect of the security configuration.
<security-management>
This section overrides high-level behaviors of the security subsystem. Each setting is optional. It is unusual to change any of these settings except for deep copy subject mode.
Option Description
deep-copy-subject-mode
Specifies whether to copy or link to security tokens, for additional thread safety.
authentication-manager-class-name
Specifies an alternate AuthenticationManager implementation class name to use.
default-callback-handler-class-name
Specifies a global class name for the CallbackHandler implementation to be used with login modules.
authorization-manager-class-name
Specifies an alternate AuthorizationManager implementation class name to use.
audit-manager-class-name
Specifies an alternate AuditManager implementation class name to use.
identity-trust-manager-class-name
Specifies an alternate IdentityTrustManager implementation class name to use.
mapping-manager-class-name
Specifies the MappingManager implementation class name to use.
<subject-factory>
The subject factory controls creation of subject instances. It may use the authentication manager to verify the caller. The main use of the subject factory is for JCA components to establish a subject.It is unusual to need to modify the subject factory.
<security-domains>
A container element which holds multiple security domains. A security domain may contain information about authentication, authorization, mapping, and auditing modules, as well as JASPI authentication and JSSE configuration. Your application would specify a security domain to manage its security information.
<security-properties>
Contains names and values of properties which are set on the java.security.Security class.

9.3. Configure the Security Subsystem

The top-level configuration of the security subsystem includes one attribute, deep-copy-subject-mode which includes child elements security-domains and security-properties. You can configure the security subsystem using the Management CLI or web-based Management Console.
Deep Copy Mode
If deep copy subject mode is disabled (the default), copying a security data structure makes a reference to the original, rather than copying the entire data structure. This behavior is more efficient, but is prone to data corruption if multiple threads with the same identity clear the subject by means of a flush or logout operation.
Deep copy subject mode causes a complete copy of the data structure and all its associated data to be made, as long as they are marked cloneable. This is more thread-safe, but less efficient.
System-Wide Security Properties
You can set system-wide security properties, which are applied to class java.security.Security class.
Security Domains
A security domain is a set of Java Authentication and Authorization Service (JAAS) declarative security configurations which one or more applications use to control authentication, authorization, security auditing, and security mapping. Three security domains are included by default: jboss-ejb-policy, jboss-web-policy, and other. The Management API, Management Console, and Management CLI use the other security domain. You can create as many security domains as you need to accomodate the needs of your applications.

9.4. About Deep Copy Subject Mode

If deep copy subject mode is disabled (the default), copying a security data structure makes a reference to the original, rather than copying the entire data structure. This behavior is more efficient, but is prone to data corruption if multiple threads with the same identity clear the subject by means of a flush or logout operation.
Deep copy subject mode causes a complete copy of the data structure and all its associated data to be made, as long as they are marked cloneable. This is more thread-safe, but less efficient.
Deep copy subject mode is configured as part of the security subsystem.

9.5. Enable Deep Copy Subject Mode

You can enable deep copy security mode from the web-based management console or the management CLI.

Procedure 9.1. Enable Deep Copy Security Mode from the Management Console

  1. Log into the Managment Console.

    The management console is usually available at a URL such as http://127.0.0.1:9990/. Adjust this value to suit your needs.
  2. Managed Domain: Select the appropriate profile.

    In a managed domain, the security subsystem is configured per profile, and you can enable or disable the deep copy security mode in each, independently.
    To select a profile, click the Profiles label at the top right of the console display, and then select the profile you wish to change from the Profile selection box at the top left.
  3. Open the Security Subsystem configuration menu.

    Expand the Security menu item at the right of the management console, then click the Security Subsystem link.
  4. Modify the deep-copy-subject-mode value.

    Click the Edit button. Check the box beside Deep Copy Subjects: to enable deep copy subject mode.
Enable Deep Copy Subject Mode Using the Management CLI
If you prefer to use the management CLI to enable this option, use one of the following commands.

Example 9.2. Managed Domain

/profile=full/subsystem=security:write-attribute(name=deep-copy-subject-mode,value=TRUE)

Example 9.3. Standalone Server

/subsystem=security:write-attribute(name=deep-copy-subject-mode,value=TRUE)

9.6. Security Domains

9.6.1. About Security Domains

Security domains are part of the JBoss Enterprise Application Platform security subsystem. All security configuration is now managed centrally, by the domain controller of a managed domain, or by the standalone server.
A security domain consists of configurations for authentication, authorization, security mapping, and auditing. It implements Java Authentication and Authorization Service (JAAS) declarative security.
Authentication refers to verifying the identity of a user. In security terminology, this user is referred to as a principal. Although authentication and authorization are different, many of the included authentication modules also handle authorization.
An authorization is a security policy, which contains information about actions which are allowed or prohibited. In security terminology, this is often referred to as a role.
Security mapping refers to the ability to add, modify, or delete information from a principal, role, or attribute before passing the information to your application.
The auditing manager allows you to configure provider modules to control the way that security events are reported.
If you use security domains, you can remove all specific security configuration from your application itself. This allows you to change security parameters centrally. One common scenario that benefits from this type of configuration structure is the process of moving applications between testing and production environments.

9.6.2. About Picketbox

Picketbox is the foundational security framework that provides the authentication, authorization, audit and mapping capabilities to Java applications running in the JBoss Enterprise Application Platform. It provides the following capabilities, in a single framework with a single configuration:
The Picketbox configuration uses a mark-up language called eXtensible Access Control Markup Language (XACML).

9.6.3. About Authentication

Authentication refers to identifying a subject and verifying the authenticity of the identification. The most common authentication mechanism is a username and password combination. Other common authentication mechanisms use shared keys, smart cards, or fingerprints. The outcome of a successful authentication is referred to as a principal, in terms of Java Enterprise Edition declarative security.
The JBoss Enterprise Application Platform uses a pluggable system of authentication modules to provide flexibility and integration with the authentication systems you already use in your organization. Each security domain contains one or more configured authentication modules. Each module includes additional configuration parameters to customize its behavior. The easiest way to configure the authentication subsystem is within the web-based management console.
Authentication is not the same as authorization, although they are often linked. Many of the included authentication modules can also handle authorization.

9.6.4. Configure Authentication in a Security Domain

To configure authentication settings for a security domain, log into the management console and follow this procedure.

Procedure 9.2. Task

  1. Open the security domain's detailed view.

    Click the Profiles label at the top right of the management console. In a managed domain, select the profile to modify from the Profile selection box at the top left of the Profile view. Click the Security menu item at the left, and click Security Domains from the expanded menu. Click the View link for the security domain you want to edit.
  2. Navigate to the Authentication subsystem configuration.

    Click the Authentication label at the top of the view if it is not already selected.
    The configuration area is divided into two areas: Login Modules and Details. The login module is the basic unit of configuration. A security domain can include several login modules, each of which can include several attributes and options.
  3. Add an authentication module.

    Click the Add button to add a JAAS authentication module. Fill in the details for your module. The Code is the class name of the module. The Flags controls how the module relates to other authentication modules within the same security domain.
    Explanation of the Flags
    The Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.
    Flag Details
    Required
    The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
    Requisite
    LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).
    Sufficient
    The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.
    Optional
    The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
    After you have added your module, you can modify its Code or Flags by clicking the Edit button in the Details section of the screen. Be sure the Attributes tab is selected.
  4. Optional: Add, edit, or remove module options.

    If you need to add options to your module, click its entry in the Login Modules list, and select the Module Options tab in the Details section of the page. Click the Add button, and provide the key and value for the option. To edit an option that already exists, click the key or to change it. Use the Remove button to remove an option.
Result
Your authentication module is added to the security domain, and is immediately available to applications which use the security domain.
The jboss.security.security_domain Module Option
By default, each login module defined in a security domain has the jboss.security.security_domain module option added to it automatically. This option causes problems with login modules which check to make sure that only known options are defined. The IBM Kerberos login module, com.ibm.security.auth.module.Krb5LoginModule is one of these.
You can disable the behavior of adding this module option by setting the system property to true when starting JBoss Enterprise Application Platform. Add the following to your start-up parameters.
-Djboss.security.disable.secdomain.option=true
You can also set this property using the web-based Management Console. In a standalone server, you can set system properties in the Profile section of the configuration. In a managed domain, you can set system properties for each server group.

9.6.5. About Authorization

Authorization is a mechanism for granting or denying access to a resource based on identity. It is implemented as a set of declarative security roles which can be granted to principals.
The JBoss Enterprise Application Platform uses a modular system to configure authorization. Each security domain can contain one or more authorization policies. Each policy has a basic module which defines its behavior. It is configured through specific flags and attributes. The easiest way to configure the authorization subsystem is by using the web-based management console.
Authorization is different from authentication, and usually happens after authentication. Many of the authentication modules also handle authorization.

9.6.6. Configure Authorization in a Security Domain

To configure authorization settings for a security domain, log into the management console and follow this procedure.

Procedure 9.3. Task

  1. Open the security domain's detailed view.

    Click the Profiles label at the top right of the management console. In a managed domain, select the profile to modify from the Profile selection box at the top left of the Profile view. Click the Security menu item at the left, and click Security Domains from the expanded menu. Click the View link for the security domain you want to edit.
  2. Navigate to the Authorization subsystem configuration.

    Click the Authorization label at the top of the view if it is not already selected.
    The configuration area is divided into two areas: Policies and Details. The login module is the basic unit of configuration. A security domain can include several authorization policies, each of which can include several attributes and options.
  3. Add a policy.

    Click the Add button to add a JAAS authorization policy module. Fill in the details for your module. The Code is the class name of the module. The Flags controls how the module relates to other authorization policy modules within the same security domain.
    Explanation of the Flags
    The Java Enterprise Edition 6 specification provides the following explanation of the flags for security modules. The following list is taken from http://docs.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html#AppendixA. Refer to that document for more detailed information.
    Flag Details
    Required
    The LoginModule is required to succeed. If it succeeds or fails, authorization still continues to proceed down the LoginModule list.
    Requisite
    LoginModule is required to succeed. If it succeeds, authorization continues down the LoginModule list. If it fails, control immediately returns to the application (authorization does not proceed down the LoginModule list).
    Sufficient
    The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authorization does not proceed down the LoginModule list). If it fails, authorization continues down the LoginModule list.
    Optional
    The LoginModule is not required to succeed. If it succeeds or fails, authorization still continues to proceed down the LoginModule list.
    After you have added your module, you can modify its Code or Flags by clicking the Edit button in the Details section of the screen. Be sure the Attributes tab is selected.
  4. Optional: Add, edit, or remove module options.

    If you need to add options to your module, click its entry in the Login Modules list, and select the Module Options tab in the Details section of the page. Click the Add button, and provide the key and value for the option. To edit an option that already exists, click the key or to change it. Use the Remove button to remove an option.
Result
Your authorization policy module is added to the security domain, and is immediately available to applications which use the security domain.

9.6.7. About Security Auditing

Security auditing refers to triggering events, such as writing to a log, in response to an event that happens within the security subsystem. Auditing mechanisms are configured as part of a security domain, along with authentication, authorization, and security mapping details.
Auditing uses provider modules. You can use one of the included ones, or implement your own.

9.6.8. Configure Security Auditing

To configure security auditing settings for a security domain, log into the management console and follow this procedure.

Procedure 9.4. Task

  1. Open the security domain's detailed view.

    Click the Profiles label at the top right of the management console. In a standalone server, the tab is labeled Profile. In a managed domain, select the profile to modify from the Profile selection box at the top left of the Profile view. Click the Security menu item at the left, and click Security Domains from the expanded menu. Click the View link for the security domain you want to edit.
  2. Navigate to the Auditing subsystem configuration.

    Click the Audit label at the top of the view if it is not already selected.
    The configuration area is divided into two areas: Provider Modules and Details. The provider module is the basic unit of configuration. A security domain can include several provider modules each of which can include attributes and options.
  3. Add a provider module.

    Click the Add button to add a provider module. Fill in the Code section with the classname of the provider module.
    After you have added your module, you can modify its Code by clicking the Edit button in the Details section of the screen. Be sure the Attributes tab is selected.
  4. Optional: Add, edit, or remove module options.

    If you need to add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click the Add button, and provide the key and value for the option. To edit an option that already exists, remove it by clicking the Remove label, and add it again with the correct options by clicking the Add button.
Result
Your security auditing module is added to the security domain, and is immediately available to applications which use the security domain.

9.6.9. About Security Mapping

Security mapping allows you to combine authentication and authorization information after the authentication or authorization happens, but before the information is passed to your application. One example of this is using an X509 certificate for authentication, and then converting the principal from the certificate to a logical name which your application can display.
You can map principals (authentication), roles (authorization), or credentials (attributes which are not principals or roles).
Role Mapping is used to add, replace, or remove roles to the subject after authentication.
Principal mapping is used to modify a principal after authentication.
Attribute mapping is used to convert attributes from an external system to be used by your application, and vice versa.

9.6.10. Configure Security Mapping in a Security Domain

To configure security mapping settings for a security domain, log into the management console and follow this procedure.

Procedure 9.5. Task

  1. Open the security domain's detailed view.

    Click the Profiles label at the top right of the management console. This tab is labeled Profile in a standalone server. In a managed domain, select the profile to modify from the Profile selection box at the top left of the Profile view. Click the Security menu item at the left, and click Security Domains from the expanded menu. Click the View link for the security domain you want to edit.
  2. Navigate to the Mapping subsystem configuration.

    Click the Mapping label at the top of the view if it is not already selected.
    The configuration area is divided into two areas: Modules and Details. The mapping module is the basic unit of configuration. A security domain can include several mapping modules, each of which can include several attributes and options.
  3. Add a module.

    Click the Add button to add a security mapping module. Fill in the details for your module. The Code is the class name of the module. The Type field refers to the type of mapping this module performs. Allowed values are principal, role, attribute or credential.
    After you have added your module, you can modify its Code or Type by clicking the Edit button in the Details section of the screen. Be sure the Attributes tab is selected.
  4. Optional: Add, edit, or remove module options.

    If you need to add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click the Add button, and provide the key and value for the option. To edit an option that already exists, click the Remove label key to remove it, and add it again with the new value. Use the Remove button to remove an option.
Result
Your security mapping module is added to the security domain, and is immediately available to applications which use the security domain.

9.6.11. Use a Security Domain in Your Application

Overview
To use a security domain in your application, first you must configure the domain in either the server's configuration file or the application's descriptor file. Then you must add the required annotations to the EJB that uses it. This topic covers the steps required to use a security domain in your application.

Procedure 9.6. Configure Your Application to Use a Security Domain

  1. Define the Security Domain

    You can define the security domain either in the server's configuration file or the application's descriptor file.
    • Configure the security domain in the server's configuration file

      The security domain is configured in the security subsystem of the server's configuration file. If the JBoss Enterprise Application Platform instance is running in a managed domain, this is the domain/configuration/domain.xml file. If the JBoss Enterprise Application Platform instance is running as a standalone server, this is the standalone/configuration/standalone.xml file.
      The other, jboss-web-policy, and jboss-ejb-policy security domains are provided by default in JBoss Enterprise Application Platform 6. The following XML example was copied from the security subsystem in the server's configuration file.
      <subsystem xmlns="urn:jboss:domain:security:1.2">
          <security-domains>
              <security-domain name="other" cache-type="default">
                  <authentication>
                      <login-module code="Remoting" flag="optional">
                          <module-option name="password-stacking" value="useFirstPass"/>
                      </login-module>
                      <login-module code="RealmDirect" flag="required">
                          <module-option name="password-stacking" value="useFirstPass"/>
                      </login-module>
                  </authentication>
              </security-domain>
              <security-domain name="jboss-web-policy" cache-type="default">
                  <authorization>
                      <policy-module code="Delegating" flag="required"/>
                  </authorization>
              </security-domain>
              <security-domain name="jboss-ejb-policy" cache-type="default">
                  <authorization>
                      <policy-module code="Delegating" flag="required"/>
                  </authorization>
              </security-domain>
          </security-domains>
      </subsystem>
      
      You can configure additional security domains as needed using the Management Console or CLI.
    • Configure the security domain in the application's descriptor file

      The security domain is specified in the <security-domain> child element of the <jboss-web> element in the application's WEB-INF/jboss-web.xml file. The following example configures a security domain named my-domain.
      <jboss-web>
          <security-domain>my-domain</security-domain>
      </jboss-web>        
      
      
      This is only one of many settings which you can specify in the WEB-INF/jboss-web.xml descriptor.
  2. Add the Required Annotation to the EJB

    You configure security in the EJB using the @SecurityDomain and @RolesAllowed annotations. The following EJB code example limits access to the other security domain by users in the guest role.
    package example.ejb3;
    
    import java.security.Principal;
    
    import javax.annotation.Resource;
    import javax.annotation.security.RolesAllowed;
    import javax.ejb.SessionContext;
    import javax.ejb.Stateless;
    
    import org.jboss.ejb3.annotation.SecurityDomain;
    
    /**
     * Simple secured EJB using EJB security annotations
     * Allow access to "other" security domain by users in a "guest" role.
     */
    @Stateless
    @RolesAllowed({ "guest" })
    @SecurityDomain("other")
    public class SecuredEJB {
    
       // Inject the Session Context
       @Resource
       private SessionContext ctx;
    
       /**
        * Secured EJB method using security annotations
        */
       public String getSecurityInfo() {
          // Session context injected using the resource annotation
          Principal principal = ctx.getCallerPrincipal();
          return principal.toString();
       }
    }
    
    For more code examples, see the ejb-security quickstart in the JBoss Enterprise Application Platform 6 Quickstarts bundle, which is available from the Red Hat Customer Portal.

9.6.12. Java Authorization Contract for Containers (JACC)

9.6.12.1. About Java Authorization Contract for Containers (JACC)

Java Authorization Contract for Containers (JACC) is a standard which defines a contract between containers and authorization service providers, which results in the implementation of providers for use by containers. It was defined in JSR-115, which can be found on the Java Community Process website at http://jcp.org/en/jsr/detail?id=115. It has been part of the core Java Enterprise Edition (Java EE) specification since Java EE version 1.3.
JBoss Enterprise Application Platform implements support for JACC within the security functionality of the security subsystem.

9.6.12.2. Configure Java Authorization Contract for Containers (JACC) Security

To configure Java Authorization Contract for Containers (JACC), you need to configure your security domain with the correct module, and then modify your jboss-web.xml to include the correct parameters.
Add JACC Support to the Security Domain
To add JACC support to the security domain, add the JACC authorization policy to the authorization stack of the security domain, with the required flag set. The following is an example of a security domain with JACC support. However, the security domain is configured in the Management Console or Management CLI, rather than directly in the XML.
<security-domain name="jacc" cache-type="default">
    <authentication>
        <login-module code="UsersRoles" flag="required">
        </login-module>
    </authentication>
    <authorization>
        <policy-module code="JACC" flag="required"/>
    </authorization>
</security-domain>

Configure a Web Application to use JACC
The jboss-web.xml is located in the META-INF/ or WEB-INF/ directory of your deployment, and contains overrides and additional JBoss-specific configuration for the web container. To use your JACC-enabled security domain, you need to include the <security-domain> element, and also set the <use-jboss-authorization> element to true. The following application is properly configured to use the JACC security domain above.
<jboss-web>
    <security-domain>jacc</security-domain>
    <use-jboss-authorization>true</use-jboss-authorization>
</jboss-web>

Configure an EJB Application to Use JACC
Configuring EJBs to use a security domain and to use JACC differs from Web Applications. For an EJB, you can declare method permissions on a method or group of methods, in the ejb-jar.xml descriptor. Within the <ejb-jar> element, any child <method-permission> elements contain information about JACC roles. Refer to the example configuration for more details. The EJBMethodPermission class is part of the Java Enterprise Edition 6 API, and is documented at http://docs.oracle.com/javaee/6/api/javax/security/jacc/EJBMethodPermission.html.

Example 9.4. Example JACC Method Permissions in an EJB

<ejb-jar>
  <method-permission>
    <description>The employee and temp-employee roles may access any method of the EmployeeService bean </description>
    <role-name>employee</role-name>
    <role-name>temp-employee</role-name>
    <method>
      <ejb-name>EmployeeService</ejb-name>
      <method-name>*</method-name>
    </method>
  </method-permission>
</ejb-jar>


You can also constrain the authentication and authorization mechanisms for an EJB by using a security domain, just as you can do for a web application. Security domains are declared in the jboss-ejb3.xml descriptor, in the <security> child element. In addition to the security domain, you can also specify the run-as principal, which changes the principal the EJB runs as.

Example 9.5. Example Security Domain Declaration in an EJB


<security>
  <ejb-name>*</ejb-name>
  <security-domain>myDomain</s:security-domain>
  <run-as-principal>myPrincipal</s:run-as-principal>
</s:security>


9.6.13. Java Authentication SPI for Containers (JASPI)

9.6.13.1. About Java Authentication SPI for Containers (JASPI) Security

Java Application SPI for Containers (JASPI or JASPIC) is a pluggable interface for Java applications. It is defined in JSR-196 of the Java Community Process. Refer to http://www.jcp.org/en/jsr/detail?id=196 for details about the specification.

9.6.13.2. Configure Java Authentication SPI for Containers (JASPI) Security

To authenticate against a JASPI provider, add a <authentication-jaspi> element to your security domain. The configuration is similar to a standard authentication module, but login module elements are enclosed in a <login-module-stack> element. The structure of the configuration is:

Example 9.6. Structure of the authentication-jaspi element

<authentication-jaspi>
	<login-module-stack name="...">
	  <login-module code="..." flag="...">
	    <module-option name="..." value="..."/>
	  </login-module>
	</login-module-stack>
	<auth-module code="..." login-module-stack-ref="...">
	  <module-option name="..." value="..."/>
	</auth-module>
</authentication-jaspi>


The login module itself is configured in exactly the same way as a standard authentication module.
Because the web-based management console does not expose the configuration of JASPI authentication modules, you need to stop the JBoss Enterprise Application Platform completely before adding the configuration directly to the EAP_HOME/domain/configuration/domain.xml or EAP_HOME/standalone/configuration/standalone.xml.

9.7. Management Interface Security

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

9.7.2. Overview of Advanced Management Interface Configuration

The Management interface configuration in the EAP_HOME/domain/configuration/host.xml or EAP_HOME/standalone/configuration/standalone.xml controls which network interfaces the host controller process binds to, which types of management interfaces are available at all, and which type of authentication system is used to authenticate users on each interface. This topic discusses how to configure the Management Interfaces to suit your environment.
The Management subsystem consists of a <management> element that includes several configurable attributes, and the following three configurable child elements. The security realms and outbound connections are each first defined, and then applied to the management interfaces as attributes.
  • <security-realms>
  • <outbound-connections>
  • <management-interfaces>
Security Realms
The security realm is responsible for the authentication and authorization of users allowed to administer the JBoss Enterprise Application Platform via the Management API, Management CLI, or web-based Management Console.
Two different file-based security realms are included in a default installation: ManagementRealm and ApplicationRealm. Each of these security realms uses a -users.properties file to store users and hashed passwords, and a -roles.properties to store mappings between users and roles. Support is also included for an LDAP-enabled security realm.

Note

Security realms can also be used for your own applications. The security realms discussed here are specific to the management interfaces.
Outbound Connections
Some security realms connect to external interfaces, such as an LDAP server. An outbound connection defines how to make this connection. A pre-defined connection type, ldap-connection, sets all of the required and optional attributes to connect to the LDAP server and verify the credential.
Management Interfaces
A management interface includes properties about how connect to and configure JBoss Enterprise Application Platform. Such information includes the named network interface, port, security realm, and other configurable information about the interface. Two interfaces are included in a default installation:
  • http-interface is the configuration for the web-based Management Console.
  • native-interface is the configuration for the command-line Management CLI and the REST-like Management API.
Each of the three main configurable elements of the host management subsystem are interrelated. A security realm refers to an outbound connection, and a management interface refers to a security realm.

9.7.3. About LDAP

Lightweight Directory Access Protocol (LDAP) is a protocol for storing and distributing directory information across a network. This directory information includes information about users, hardware devices, access roles and restrictions, and other information.
Some common implementations of LDAP include OpenLDAP, Microsoft Active Directory, IBM Tivoli Directory Server, Oracle Internet Directory, and others.
JBoss Enterprise Application Platform includes several authentication and authorization modules which allow you to use a LDAP server as the authentication and authorization authority for your Web and EJB applications.

9.7.4. Use LDAP to Authenticate to the Management Interfaces

To use an LDAP directory server as the authentication source for the Management Console, Management CLI, or Management API, you need to perform the following procedures:
  1. Create an outbound connection to the LDAP server.
  2. Create an LDAP-enabled security realm.
  3. Reference the new security domain in the Management Interface.
Create an Outbound Connection to an LDAP Server
The LDAP outbound connection allows the following attributes:

Table 9.1. Attributes of an LDAP Outbound Connection

Attribute Required Description
name yes
The name to identify this connection. This name is used in the security realm definition.
url yes
The URL address of the directory server.
search-dn yes
The fully distinguished name (DN) of the user authorized to perform searches.
search-credentials yes
The password of the user authorized to perform searches.
initial-context-factory no
The initial context factory to use when establishing the connection. Defaults to com.sun.jndi.ldap.LdapCtxFactory.

Example 9.7. Add an LDAP Outbound Connection

This example adds an outbound connection with the following properties set:
  • Search DN: cn=search,dc=acme,dc=com
  • Search Credential: myPass
  • URL: http://127.0.0.1
/host=master/core-service=management/ldap-connection=ldap_connection/:add(search-credential=myPass,url=http://127.0.0.1,search-dn=cn=search,dc=acme,dc=com)

Example 9.8. XML Representing an LDAP Outbound Connection

<outbound-connections>
   <ldap name="ldap_connection" url="ldap://127.0.0.1" search-dn="cn=search,dc=acme,dc=com" search-credential="myPass" />
</outboundconnections>	


Create an LDAP-Enabled Security Realm
The Management Interfaces can authenticate against LDAP server instead of the property-file based security realms configured by default. The LDAP authenticator operates by first establishing a connection to the remote directory server. It then performs a search using the username which the user passed to the authentication system, to find the fully-qualified distinguished name (DN) of the LDAP record. A new connection is established, using the DN of the user as the credential, and password supplied by the user. If this authentication to the LDAP server is successful, the DN is verified to be valid.
The LDAP security realm needs the following configuration attributes and elements in order to perform its functions.
connection
The name of the connection defined in <outbound-connections> to use to connect to the LDAP directory.
base-dn
The distinguished name of the context to begin searching for the user.
recursive
Whether the search should be recursive throughout the LDAP directory tree, or only search the specified context. Defaults to false.
user-dn
The attribute of the user that holds the distinguished name. This is subsequently used to test authentication as the user can complete. Defaults to dn.
One of username-filter or advanced-filter, as a child element
The username-filter takes a single attribute called attribute, whose value is the name of the LDAP attribute which holds the username, such as userName or sambaAccountName.
The advanced-filter takes a single attribute called filter. This attribute contains a filter query in standard LDAP syntax. Be cautious to escape any & characters by changing them to &amp;. An example of a filter is:
(&(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))
After escaping the ampersand character, the filter appears as:
(&amp;(sAMAccountName={0})(memberOf=cn=admin,cn=users,dc=acme,dc=com))

Example 9.9. XML Representing an LDAP-enabled Security Realm

This example uses the following parameters:
  • connection - ldap_connection
  • base-dn - cn=users,dc=acme,dc=com.
  • username-filter - attribute="sambaAccountName"
<security-realm name="TestRealm">
   <authentication>
      <ldap connection="ldap_connection" base-dn="cn=users,dc=acme,dc=com">
         <username-filter attribute="sambaAccountName" />
      </ldap>
  </authentication>
</security-realm>	


Example 9.10. Add an LDAP Security Realm

The command below adds a security realm and sets its attributes.
/host=master/core-service=management/security-realm=ldap_security_realm/authentication=ldap:add(base-dn="DC=mycompany,DC=org", recursive=true, username-attribute="MyAccountName", connection="ldap_connection")

Apply the New Security Realm to the Management Interface
After you create a security realm, you need to reference it in the configuration of your management interface. The management interface will use the security realm for HTTP digest authentication.

Example 9.11. Apply the Security Realm to the HTTP Interface

After this configuration is in place, the web-based Management Console will use LDAP to authenticate its users.
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=TestRealm)

Restart JBoss Enterprise Application Platform and your HTTP interface uses your LDAP server for authentication.

9.7.5. Disable the HTTP Management Interface

In a managed domain, you only need access to the HTTP interface on the domain controller, rather than on domain member servers. In addition, on a production server, you may decide to disable the web-based Management Console altogether.

Note

Other clients, such as JBoss Operations Network, also operate using the HTTP interface. If you want to use these services, and simply disable the Management Console itself, you can set the console-enabled-attribute of the HTTP interface to false, instead of disabling the interface completely.
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=false)
To disable access to the HTTP interface, which also disables access to the web-based Management Console, you can delete the HTTP interface altogether.
The following JBoss CLI command allows you to read the current contents of your HTTP interface, in case you decide to add it again.

Example 9.12. Read the Configuration of the HTTP Interface

/host=master/core-service=management/management-interface=http-interface/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
    "outcome" => "success",
    "result" => {
        "console-enabled" => true,
        "interface" => "management",
        "port" => expression "${jboss.management.http.port:9990}",
        "secure-port" => undefined,
        "security-realm" => "ManagementRealm"
    }
}

To remove the HTTP interface, issue the following command:

Example 9.13. Remove the HTTP Interface

/host=master/core-service=management/management-interface=http-interface/:remove

To re-enable access, issue the following commands to re-create the HTTP Interface with the default values.

Example 9.14. Re-Create the HTTP Interface

/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=console-enabled,value=true)
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=interface,value=management)
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=port,value=${jboss.management.http.port:9990})
/host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=ManagementRealm)

9.7.6. Remove Silent Authentication from the Default Security Realm

Summary
The default installation of JBoss Enterprise Application Platform 6 contains a method of silent authentication for a local Management CLI user. This allows the local user the ability to access the Management CLI without username or password authentication. This functionality is enabled as a convenience, and to assist local users running Management CLI scripts without requiring authentication. It is considered a useful feature given that access to the local configuration typically also gives the user the ability to add their own user details or otherwise disable security checks.
The convenience of silent authentication for local users can be disabled where greater security control is required. This can be achieved by removing the local element within the security-realm section of the configuration file. This applies to both the standalone.xml for a Standalone Server instance, or host.xml for a Managed Domain. You should only consider the removal of the local element if you understand the impact that it might have on your particular server configuration.
The preferred method of removing silent authentication is by use of the Management CLI, which directly removes the local element visible in the following example.

Example 9.15. Example of the local element in the security-realm

<security-realms>
    <security-realm name="ManagementRealm">
        <authentication>
            <local default-user="$local"/>
            <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
        </authentication>
    </security-realm>
    <security-realm name="ApplicationRealm">
        <authentication>
            <local default-user="$local" allowed-users="*"/>
            <properties path="application-users.properties" relative-to="jboss.server.config.dir"/>
        </authentication>
        <authorization>
            <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
        </authorization>
    </security-realm>
</security-realms>

Procedure 9.7. Task

  • Remove silent authentication with the Management CLI

    Remove the local element from the Management Realm and Application Realm as required.
    1. Remove the local element from the Management Realm.
      /core-service=management/security-realm=ManagementRealm/authentication=local:remove
    2. Remove the local element from the Application Realm.
      /core-service=management/security-realm=ApplicationRealm/authentication=local:remove
Result
The silent authentication mode is removed from the ManagementRealm and the ApplicationRealm.

9.7.7. Disable Remote Access to the JMX Subsystem

Remote JMX connectivity allows you to trigger JDK and application management operations. In order to secure an installation, disable this function. You can do this either by removing the remote connection configuration, or removing the JMX subsystem entirely. The JBoss CLI commands reference the default profile in a managed domain configuration. To modify a different profile, modify the /profile=default part of the command. For a standalone server, remove that portion of the command completely.

Note

The remoting connector is removed from the JMX subsystem by default. This command is provided for your information, in case you add it during development.

Example 9.16. Remove the Remote Connector from the JMX Subsystem

/profile=default/subsystem=jmx/remoting-connector=jmx/:remove

Example 9.17. Remove the JMX Subsystem

Run this command for each profile you use, if you use a managed domain.
/profile=default/subsystem=jmx/:remove

9.7.8. Configure Security Realms for the Management Interfaces

The Management Interfaces use security realms to control authentication and access to the configuration mechanisms of JBoss Enterprise Application Platform. This topic shows you how to read and configure security realms. These commands use the Management CLI.
Read a Security Realm's Configuration
This example shows the default configuration for the ManagementRealm security realm. It uses a file called mgmt-users.properties to store its configuration information.

Example 9.18. Default ManagementRealm

	/host=master/core-service=management/security-realm=ManagementRealm/:read-resource(recursive=true,proxies=false,include-runtime=false,include-defaults=true)
{
    "outcome" => "success",
    "result" => {
        "authorization" => undefined,
        "server-identity" => undefined,
        "authentication" => {"properties" => {
            "path" => "mgmt-users.properties",
            "plain-text" => false,
            "relative-to" => "jboss.domain.config.dir"
        }}
    }
}

Write a Security Realm
The following commands create a new security realm called TestRealm and set the name and directory for the relevant properties file.

Example 9.19. Writing a Security Realm

/host=master/core-service=management/security-realm=TestRealm/:add
/host=master/core-service=management/security-realm=TestRealm/authentication=properties/:write-attribute(name=path,value=TestUsers.properties)
/host=master/core-service=management/security-realm=TestRealm/authentication=properties/:write-attribute(name=relative-to,value=jboss.domain.config.dir)

Apply a Security Realm to the Management Interface
After adding a security realm, supply its name as a reference to the Management Interface.

Example 9.20. Add a Security Realm to a Management Interface

host=master/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=TestRealm)

Changes to management interfaces take effect after JBoss Enterprise Application Platform is restarted.

9.8. Network Security

9.8.1. Secure the Management Interfaces

Summary
In a test environment, it is typical to run JBoss Enterprise Application Platform 6 with no security layer on the management interfaces, comprised of the Management Console, Management CLI, and any other API implementation. This allows for rapid development and configuration changes.
In addition, the a silent authentication mode is present by default, allowing a local client on the host machine to connect to the Management CLI without requiring a username or password. This behaviour is a convenience for local users and Management CLI scripts, but it can be disabled if required. The procedure is described in the topic Section 9.7.6, “Remove Silent Authentication from the Default Security Realm”.
When you begin testing and preparing your environment to move to production, it is vitally important to secure the management interfaces by at least the following methods:

9.8.2. Specify Which Network Interface the JBoss Enterprise Application Platform Uses

Overview
Isolating services so that they are accessible only to the clients who need them increases the security of your network. The JBoss Enterprise Application Platform includes two interfaces in its default configuration, both of which bind to the IP address 127.0.0.1, or localhost, by default. One of the interfaces is called management, and is used by the Management Console, CLI, and API. The other is called public, and is used to deploy applications. These interfaces are not special or significant, but are provided as a starting point.
The management interface uses ports 9990 and 9999 by default, and the public interface uses port 8080, or port 8443 if you use HTTPS.
You can change the IP address of the management interface, public interface, or both.

Be cautious when exposing the management interfaces.

If you expose the management interfaces to other network interfaces which are accessible from remote hosts, be aware of the security implications. Most of the time, it is not advisable to provide remote access to the management interfaces.
  1. Stop the JBoss Enterprise Application Platform.

    Stop the JBoss Enterprise Application Platform by sending an interrupt in the appropriate way for your operating system. If you are running the JBoss Enterprise Application Platform as a foreground application, the typical way to do this is to press Ctrl+C.
  2. Restart the JBoss Enterprise Application Platform, specifying the bind address.

    Use the -b command-line switch to start the JBoss Enterprise Application Platform on a specific interface.

    Example 9.21. Specify the public interface.

    EAP_HOME/bin/domain.sh -b 10.1.1.1

    Example 9.22. Specify the management interface.

    EAP_HOME/bin/domain.sh -bmanagement=10.1.1.1

    Example 9.23. Specify different addresses for each interface.

    EAP_HOME/bin/domain.sh -bmanagement=127.0.0.1 -b 10.1.1.1

    Example 9.24. Bind the public interface to all network interfaces.

    EAP_HOME/bin/domain.sh -b 0.0.0.0

It is possible to edit your XML configuration file directly, to change the default bind addresses. However, if you do this, you will no longer be able to use the -bcommand-line switch to specify an IP address at run-time, so this is not recommended. If you do decide to do this, be sure to stop the JBoss Enterprise Application Platform completely before editing the XML file.

9.8.3. 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 9.8.4, “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 9.8. 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 9.8.4, “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 9.8.4, “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.

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

Numerical port offsets

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

9.9. Java Security Manager

9.9.1. About the Java Security Manager

Java Security Manager
The Java Security Manager is a class that manages the external boundary of the Java Virtual Machine (JVM) sandbox, controlling how code executing within the JVM can interact with resources outside the JVM. When the Java Security Manager is activated, the Java API checks with the security manager for approval before executing a wide range of potentially unsafe operations.
The Security Manager uses a security policy to determine whether a given action will be permitted or denied.
Security Policy
A set of defined permissions for different classes of code. The Java Security Manager compares actions requested by applications against the security policy. If an action is allowed by the policy, the Security Manager will permit that action to take place. If the action is not allowed by the policy, the Security Manager will deny that action. The security policy can define permissions based on the location of code or on the code's signature.
The Security Manager and the security policy used are configured using the Java Virtual Machine options java.security.manager and java.security.policy.

9.9.2. Run JBoss Enterprise Application Platform Within the Java Security Manager

To specify a Java Security Manager policy, you need to edit the Java options passed to the domain or server instance during the bootstrap process. For this reason, you cannot pass the parameters as options to the domain.sh or standalone.sh scripts. The following procedure guides you through the steps of configuring your instance to run within a Java Security Manager policy.

Prerequisites

  • Before you following this procedure, you need to write a security policy, using the policytool command which is included with your Java Development Kit (JDK). This procedure assumes that your policy is located at EAP_HOME/bin/server.policy.
  • The domain or standalone server must be completely stopped before you edit any configuration files.
Perform the following procedure for each physical host or instance in your domain, if you have domain members spread across multiple systems.

Procedure 9.9. Task

  1. Edit the configuration file.

    Open the configuration file for editing. This file is located in one of two places, depending on whether you use a managed domain or standalone server. This is not the executable file used to start the server or domain.
    • Managed Domain

      EAP_HOME/bin/domain.conf
    • Standalone Server

      EAP_HOME/bin/standalone.conf
  2. Add the Java options at the end of the file.

    Add the following line to a new line at the very end of the file. You can modify the -Djava.security.policy value to specify the exact location of your security policy. It should go onto one line only, with no line break. You can modify the -Djava.security.debug to log more or less information, by specifying the debug level. The most verbose is failure,access,policy.
    JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djboss.home.dir=$PWD/.. -Djava.security.policy==$PWD/server.policy -Djava.security.debug=failure"
    
    
  3. Start the domain or server.

    Start the domain or server as normal.

9.9.3. About Java Security Manager Policies

The Java Security Manager uses a security policy to determine whether a given action will be permitted or denied.
The security policy is a set of defined permissions for different classes of code. The Java Security Manager compares actions requested by applications against the security policy. If an action is allowed by the policy, the Java Security Manager will permit that action to take place. If the action is not allowed by the policy, the Java Security Manager will deny that action. The security policy can define permissions based on the location of code or on the code's signature.
The Java Security Manager and the security policy used are configured using the Java Virtual Machine options java.security.manager and java.security.policy.

9.9.4. Write a Java Security Manager Policy

Introduction
An application called policytool is included with most JDK and JRE distributions, for the purpose of creating and editing Java Security Manager security policies. Detailed information about policytool is linked from http://docs.oracle.com/javase/6/docs/technotes/tools/.
Basic Information
A security policy consists of the following configuration elements:
CodeBase
The URL location (excluding the host and domain information) where the code originates from. This parameter is optional.
SignedBy
The alias used in the keystore to reference the signer whose private key was used to sign the code. This can be a single value or a comma-separated list of values. This parameter is optional. If omitted, presence or lack of a signature has no impact on the Java Security Manager.
Principals
A list of principal_type/principal_name pairs, which must be present within the executing thread's principal set. The Principals entry is optional. If it is omitted, it signifies "any principals".
Permissions
A permission is the access which is granted to the code. Many permissions are provided as part of the Java Enterprise Edition 6 (Java EE 6) specification. This document only covers additional permissions which are provided by JBoss Enterprise Application Platform.

Procedure 9.10. Task

  1. Start policytool.

    Start the policytool tool in one of the following ways.
    • Red Hat Enterprise Linux

      From your GUI or a command prompt, run /usr/bin/policytool.
    • Microsoft Windows Server

      Run policytool.exe from your Start menu or from the bin\ of your Java installation. The location can vary.
  2. Create a new policy.

    To create a new policy, select Add Policy Entry. Add the parameters you need, then click Done.
  3. Edit an existing policy

    Select the policy from the list of existing policies, and select the Edit Policy Entry button. Edit the parameters as needed.
  4. Delete an existing policy.

    Select the policy from the list of existing policies, and select the Delete Policy Entry button.

Permission Specific to JBoss Enterprise Application Platform

org.jboss.security.SecurityAssociation.getPrincipalInfo
Provides access to the org.jboss.security.SecurityAssociationgetPrincipal() and getCredential() methods. The risk involved with using this runtime permission is the ability to see the current thread caller and credentials.
org.jboss.security.SecurityAssociation.getSubject
Provides access to the org.jboss.security.SecurityAssociationgetSubject() method.
org.jboss.security.SecurityAssociation.setPrincipalInfo
Provides access to the org.jboss.security.SecurityAssociationsetPrincipal(), setCredential(), setSubject(), pushSubjectContext(), and popSubjectContext() methods. The risk involved with using this runtime permission is the ability to set the current thread caller and credentials.
org.jboss.security.SecurityAssociation.setServer
Provides access to the org.jboss.security.SecurityAssociationsetServer method. The risk involved with using this runtime permission is the ability to enable or disable multi-thread storage of the caller principal and credential.
org.jboss.security.SecurityAssociation.setRunAsRole
Provides access to the org.jboss.security.SecurityAssociationpushRunAsRole, popRunAsRole, pushRunAsIdentity, and popRunAsIdentity methods. The risk involved with using this runtime permission is the ability to change the current caller run-as role principal.
org.jboss.security.SecurityAssociation.accessContextInfo
Provides access to the org.jboss.security.SecurityAssociationaccessContextInfo, and accessContextInfo getter and setter methods. This allows you to both set and get the current security context info.
org.jboss.naming.JndiPermission
Provides special permissions to files and directories in a specified JNDI tree path, or recursively to all files and subdirectories. A JndiPermission consists of a pathname and a set of valid permissions related to the file or directory.
The available permissions include:
  • bind
  • rebind
  • unbind
  • lookup
  • list
  • listBindings
  • createSubcontext
  • all
Pathnames ending in /* indicate that the specified permissions apply to all files and directories of the pathname. Pathnames ending in /- indicate recursive permissions to all files and subdirectories of the pathname. Pathnames consisting of the special token <<ALL BINDINGS>> matches any file in any directory.
org.jboss.security.srp.SRPPermission
A custom permission class for protecting access to sensitive SRP information like the private session key and private key. This permission does not have any actions defined. The getSessionKey target provides access to the private session key which results from the SRP negotiation. Access to this key allows you to encrypt and decrypt messages that have been encrypted with the session key.
org.hibernate.secure.HibernatePermission
This permission class provides basic permissions to secure Hibernate sessions. The target for this property is the entity name. The available actions include:
  • insert
  • delete
  • update
  • read
  • * (all)
org.jboss.metadata.spi.stack.MetaDataStackPermission
Provides a custom permission class for controlling how callers interact with the metadata stack. The available permissions are:
  • modify
  • push (onto the stack)
  • pop (off the stack)
  • peek (onto the stack)
  • * (all)
org.jboss.config.spi.ConfigurationPermission
Secures setting of configuration properties. Defines only permission target names, and no actions. The targets for this property include:
  • <property name> (the property this code has permission to set)
  • * (all properties)
org.jboss.kernel.KernelPermission
Secures access to the kernel configuration. Defines only permission target names and no actions. The targets for this property include:
  • access (to the kernel configuration)
  • configure (implies access)
  • * (all)
org.jboss.kernel.plugins.util.KernelLocatorPermission
Secures access to the kernel. Defines only permission target names and no actions. The targets for this property include:
  • kernel
  • * (all)

9.9.5. Debug Security Manager Policies

You can enable debugging information to help you troubleshoot security policy-related issues. The java.security.debug option configures the level of security-related information reported. The command java -Djava.security.debug=help will produce help output with the full range of debugging options. Setting the debug level to all is useful when troubleshooting a security-related failure whose cause is completely unknown, but for general use it will produce too much information. A sensible general default is access:failure.

Procedure 9.11. Enable general debugging

  • This procedure will enable a sensible general level of security-related debug information.

    Add the following line to the server configuration file.
    • If the JBoss Enterprise Application Platform instance is running in a managed domain, the line is added to the bin/domain.conf file for Linux or the bin/domain.conf.bat file for Windows.
    • If the JBoss Enterprise Application Platform instance is running as a standalone server, the line is added to the bin/standalone.conf file for Linux, or the bin\standalone.conf.bat file for Windows.
Linux
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Windows
JAVA_OPTS="%JAVA_OPTS% -Djava.security.debug=access:failure"
Result
A general level of security-related debug information has been enabled.

9.10. Application Security

9.10.1. Enabling/Disabling Descriptor Based Property Replacement

Summary
Finite control over descriptor property replacement was introduced in jboss-as-ee_1_1.xsd. This task covers the steps required to configure descriptor based property replacement.
Descriptor based property replacement flags have boolean values:
  • When set to true, property replacements are enabled.
  • When set to false, property replacements are disabled.

Procedure 9.12. jboss-descriptor-property-replacement

jboss-descriptor-property-replacement is used to enable or disable property replacement in the following descriptors:
  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml
The default value for jboss-descriptor-property-replacement is true.
  1. In the Management CLI, run the following command to determine the value of jboss-descriptor-property-replacement:
    /subsystem=ee:read-attribute(name="jboss-descriptor-property-replacement")
  2. Run the following command to configure the behavior:
    /subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Procedure 9.13. spec-descriptor-property-replacement

spec-descriptor-property-replacement is used to enable or disable property replacement in the following descriptors:
  • ejb-jar.xml
  • persistence.xml
The default value for spec-descriptor-property-replacement is false.
  1. In the Management CLI, run the following command to confirm the value of spec-descriptor-property-replacement:
    /subsystem=ee:read-attribute(name="spec-descriptor-property-replacement")
  2. Run the following command to configure the behavior:
    /subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)
Result
The descriptor based property replacement tags have been successfully configured.

9.11. Password Vaults for Sensitive Strings

9.11.1. About Securing Sensitive Strings in Clear-Text Files

Web applications and other deployments often include clear-text files, such as XML deployment descriptors, which include sensitive information such as passwords and other sensitive strings. JBoss Enterprise Application Platform includes a password vault mechanism which enables you to encrypt sensitive strings and store them in an encrypted keystore. The vault mechanism manages decrypting the strings for use with security domains, security realms, or other verification systems. This provides an extra layer of security. The mechanism relies upon tools that are included in all supported Java Development Kit (JDK) implementations.

9.11.2. Create a Java Keystore to Store Sensitive Strings

Prerequisites

  • The keytool command must be available to use. It is provided by the Java Runtime Environment (JRE). Locate the path for the file. In Red Hat Enterprise Linux, it is installed to /usr/bin/keytool.

Procedure 9.14. Task

  1. Create a directory to store your keystore and other encrypted information.

    Create a directory to hold your keystore and other important information. The rest of this procedure assumes that the directory is /home/USER/vault/.
  2. Determine the parameters to use with keytool.

    Determine the following parameters:
    alias
    The alias is a unique identifier for the vault or other data stored in the keystore. The alias in the example command at the end of this procedure is vault. Aliases are case-insensitive.
    keyalg
    The algorithm to use for encryption. The default is DSA. The example in this procedure uses RSA. Check the documentation for your JRE and operating system to see which other choices may be available to you.
    keysize
    The size of an encryption key impacts how difficult it is to decrypt through brute force. The default size of keys is 1024. It must be between 512 and 1024, and a multiple of 64. The example in this procedure uses 1024.
    keystore
    The keystore a database which holds encrypted information and the information about how to decrypt it. If you do not specify a keystore, the default keystore to use is a file called .keystore in your home directory. The first time you add data to a keystore, it is created. The example in this procedure uses the vault.keystore keystore.
    The keystore command has many other options. Refer to the documentation for your JRE or your operating system for more details.
  3. Determine the answers to questions the keystore command will ask.

    The keystore needs the following information in order to populate the keystore entry:
    Keystore password
    When you create a keystore, you must set a password. In order to work with the keystore in the future, you need to provide the password. Create a strong password that you will remember. The keystore is only as secure as its password and the security of the file system and operating system where it resides.
    Key password (optional)
    In addition to the keystore password, you can specify a password for each key it holds. In order to use such a key, the password needs to be given each time it is used. Usually, this facility is not used.
    First name (given name) and last name (surname)
    This, and the rest of the information in the list, helps to uniquely identify the key and place it into a hierarchy of other keys. It does not necessarily need to be a name at all, but it should be two words, and must be unique to the key. The example in this procedure uses Accounting Administrator. In directory terms, this becomes the common name of the certificate.
    Organizational unit
    This is a single word that identifies who uses the certificate. It may be the application or the business unit. The example in this procedure uses AccountingServices. Typically, all keystores used by a group or application use the same organizational unit.
    Organization
    This is usually a single-word representation of your organization's name. This typically remains the same across all certificates used by an organization. This example uses MyOrganization.
    City or municipality
    Your city.
    State or province
    Your state or province, or the equivalent for your locality.
    Country
    The two-letter code for your country.
    All of this information together will create a hierarchy for your keystores and certificates, ensuring that they use a consistent naming structure but are unique.
  4. Run the keytool command, supplying the information that you gathered.

    Example 9.25. Example input and output of keystore command

    $ keytool -genkey -alias vault -keyalg RSA -keysize 1024 -keystore /home/USER/vault/vault.keystore
    Enter keystore password: vault22 
    Re-enter new password:vault22 
    What is your first and last name?
      [Unknown]:  Accounting Administrator
    What is the name of your organizational unit?
      [Unknown]:  AccountingServices
    What is the name of your organization?
      [Unknown]:  MyOrganization
    What is the name of your City or Locality?
      [Unknown]:  Raleigh
    What is the name of your State or Province?
      [Unknown]:  NC
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is CN=Accounting Administrator, OU=AccountingServices, O=MyOrganization, L=Raleigh, ST=NC, C=US correct?
      [no]:  yes
    
    Enter key password for <vault>
            (RETURN if same as keystore password):
    

Result
A file named vault.keystore is created in the /home/USER/vault/ directory. It stores a single key, called vault, which will be used to store encrypted strings, such as passwords, for the JBoss Enterprise Application Platform.

9.11.3. Mask the Keystore Password and Initialize the Password Vault

Prerequisites

  1. Run the vault.sh command.

    Run EAP_HOME/bin/vault.sh. Start a new interactive session by typing 0.
  2. Enter the directory where encrypted files will be stored.

    This directory should be reasonably secure, but the JBoss Enterprise Application Platform needs to be able to access it. If you followed Section 9.11.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in a directory called vault/ in your home directory. This example uses the directory /home/USER/vault/.

    Include the trailing slash on the directory name.

    Do not forget to include the trailing slash on the directory name. Either use / or \, depending on your operating system.
  3. Enter the path to the keystore.

    Enter the full path to the keystore file. This example uses /home/USER/vault/vault.keystore.
  4. Encrypt the keystore password.

    The following steps encrypt the keystore password, so that you can use it in configuration files and applications securely.
    1. Enter the keystore password.

      When prompted, enter the keystore password.
    2. Enter a salt value.

      Enter an 8-character salt value. The salt value, together with the iteration count (below), are used to create the hash value.
    3. Enter the iteration count.

      Enter a number for the iteration count.
    4. Make a note of the masked password information.

      The masked password, the salt, and the iteration count are printed to standard output. Make a note of them in a secure location. An attacker could use them to decrypt the password.
    5. Enter the alias of the vault.

      When prompted, enter the alias of the vault. If you followed Section 9.11.2, “Create a Java Keystore to Store Sensitive Strings” to create your vault, the alias is vault.
  5. Exit the interactive console.

    Type exit to exit the interactive console.
Result
Your keystore password has been masked for use in configuration files and deployments. In addition, your vault is fully configured and ready to use.

9.11.4. Configure the JBoss Enterprise Application Platform to Use the Password Vault

Overview
Before you can mask passwords and other sensitive attributes in configuration files, you need to make the JBoss Enterprise Application Platform aware of the password vault which stores and decrypts them. Follow this procedure to enable this functionality.

Procedure 9.15. Task

  1. Determine the correct values for the command.

    Determine the values for the following parameters, which are determined by the commands used to create the keystore itself. For information on creating a keystore, refer to the following topics: Section 9.11.2, “Create a Java Keystore to Store Sensitive Strings” and Section 9.11.3, “Mask the Keystore Password and Initialize the Password Vault”.
    Parameter Description
    KEYSTORE_URL
    The file system path or URI of the keystore file, usually called something like vault.keystore
    KEYSTORE_PASSWORD
    The password used to access the keystore. This value should be masked.
    KEYSTORE_ALIAS
    The name of the keystore.
    SALT
    The salt used to encrypt and decrypt keystore values.
    ITERATION_COUNT
    The number of times the encryption algorithm is run.
    ENC_FILE_DIR
    The path to the directory from which the keystore commands are run. Typically the directory containing the password vault.
    host (managed domain only)
    The name of the host you are configuring
  2. Use the Management CLI to enable the password vault.

    Run one of the following commands, depending on whether you use a managed domain or standalone server configuraiton. Substitute the values in the command with the ones from the first step of this procedure.
    • Managed Domain

      /host=YOUR_HOST/core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
      
    • Standalone Server

      /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "PATH_TO_KEYSTORE"), ("KEYSTORE_PASSWORD" => "MASKED_PASSWORD"), ("KEYSTORE_ALIAS" => "ALIAS"), ("SALT" => "SALT"),("ITERATION_COUNT" => "ITERATION_COUNT"), ("ENC_FILE_DIR" => "ENC_FILE_DIR")])
      
    The following is an example of the command with hypothetical values:
    /core-service=vault:add(vault-options=[("KEYSTORE_URL" => "/home/user/vault/vault.keystore"), ("KEYSTORE_PASSWORD" => "MASK-3y28rCZlcKR"), ("KEYSTORE_ALIAS" => "vault"), ("SALT" => "12438567"),("ITERATION_COUNT" => "50"), ("ENC_FILE_DIR" => "/home/user/vault/")])
    
Result
The JBoss Enterprise Application Platform is configured to decrypt masked strings using the password vault. To add strings to the vault and use them in your configuration, refer to the following topic: Section 9.11.5, “Store and Retrieve Encrypted Sensitive Strings in the Java Keystore”.

9.11.5. Store and Retrieve Encrypted Sensitive Strings in the Java Keystore

Overview
Including passwords and other sensitive strings in plain-text configuration files is insecure. The JBoss Enterprise Application Platform includes the ability to store and mask these sensitive strings in an encrypted keystore, and use masked values in configuration files.

Procedure 9.16. Task

  1. Run the vault.sh command.

    Run EAP_HOME/bin/vault.sh. Start a new interactive session by typing 0.
  2. Enter the directory where encrypted files will be stored.

    If you followed Section 9.11.2, “Create a Java Keystore to Store Sensitive Strings”, your keystore is in a directory called vault/ in your home directory. In most cases, it makes sense to store all of your encrypted information in the same place as the key store. This example uses the directory /home/USER/vault/.

    Note

    Do not forget to include the trailing slash on the directory name. Either use / or \, depending on your operating system.
  3. Enter the path to the keystore.

    Enter the full path to the keystore file. This example uses /home/USER/vault/vault.keystore.
  4. Enter the keystore password, vault name, salt, and iteration count.

    When prompted, enter the keystore password, vault name, salt, and iteration count. A handshake is performed.
  5. Select the option to store a password.

    Select option 0 to store a password or other sensitive string.
  6. Enter the value.

    When prompted, enter the value twice. If the values do not match, you are prompted to try again.
  7. Enter the vault block.

    Enter the vault block, which is a container for attributes which pertain to the same resource. An example of an attribute name would be ds_ExampleDS. This will form part of the reference to the encrypted string, in your datasource or other service definition.
  8. Enter the attribute name.

    Enter the name of the attribute you are storing. An example attribute name would be password.
    Result
    A message such as the one below shows that the attribute has been saved.
    Attribute Value for (ds_ExampleDS, password) saved
  9. Make note of the information about the encrypted string.

    A message prints to standard output, showing the vault block, attribute name, shared key, and advice about using the string in your configuration. Make note of this information in a secure location. Example output is shown below.
    ********************************************
    Vault Block:ds_ExampleDS
    Attribute Name:password
    Shared Key:N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0
    Configuration should be done as follows:
    VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0
    ********************************************
    
  10. Use the encrypted string in your configuration.

    Use the string from the previous step in your configuration, in place of a plain-text string. A datasource using the encrypted password above is shown below.
    ...
      <subsystem xmlns="urn:jboss:domain:datasources:1.0">
        <datasources>
          <datasource jndi-name="java:jboss/datasources/ExampleDS" enabled="true" use-java-context="true" pool-name="H2DS">
            <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
            <driver>h2</driver>
            <pool></pool>
            <security>
              <user-name>sa</user-name>
              <password>VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0</password>
            </security>
          </datasource>
          <drivers>
             <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
             </driver>
          </drivers>
        </datasources>
      </subsystem>
    ...
    
    You can use an encrypted string anywhere in your domain or standalone configuration file. After you store your string in the keystore, use the following syntax to replace any clear-text string with an encrypted one.
    ${VAULT::<replaceable>VAULT_BLOCK</replaceable>::<replaceable>ATTRIBUTE_NAME</replaceable>::<replaceable>ENCRYPTED_VALUE</replaceable>
    Here is a sample real-world value, where the vault block is ds_ExampleDS and the attribute is password.
    <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>

9.11.6. Store and Resolve Sensitive Strings In Your Applications

Overview
Configuration elements of the JBoss Enterprise Application Platform support the ability to resolve encrypted strings against values stored in a Java Keystore, via the Security Vault mechanism. You can add support for this feature to your own applications.
First, add the password to the vault. Second, replace the clear-text password with the one stored in the vault. You can use this method to obscure any sensitive string in your application.
Prerequisites
Before performing this procecure, make sure that the directory for storing your vault files exists. It does not matter where you place them, as long as the user who executes JBoss Enterprise Application Platform has permission to read and write the files. This example places the vault/ directory into the /home/USER/vault/ directory. The vault itself is a file called vault.keystore inside the vault/ directory.

Example 9.26. Adding the Password String to the Vault

Add the string to the vault using the EAP_HOME/bin/vault.sh command. The full series of commands and responses is included in the following screen output. Values entered by the user are emphasized. Some output is removed for formatting. In Microsoft Windows, the name of the command is vault.bat. Note that in Microsoft Windows, file paths use the \ character as a directory separater, rather than the / character.
[user@host bin]$ ./vault.sh 
**********************************
****  JBoss Vault ********
**********************************
Please enter a Digit::   0: Start Interactive Session  1: Remove Interactive Session  2: Exit
0
Starting an interactive session
Enter directory to store encrypted files:/home/user/vault/
Enter Keystore URL:/home/user/vault/vault.keystore
Enter Keystore password: ...
Enter Keystore password again: ...
Values match
Enter 8 character salt:12345678
Enter iteration count as a number (Eg: 44):25

Enter Keystore Alias:vault
Vault is initialized and ready for use
Handshake with Vault complete
Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
0
Task:  Store a password
Please enter attribute value: sa
Please enter attribute value again: sa
Values match
Enter Vault Block:DS
Enter Attribute Name:thePass
Attribute Value for (DS, thePass) saved

Please make note of the following:
********************************************
Vault Block:DS
Attribute Name:thePass
Shared Key:OWY5M2I5NzctYzdkOS00MmZhLWExZGYtNjczM2U5ZGUyOWIxTElORV9CUkVBS3ZhdWx0
Configuration should be done as follows:
VAULT::DS::thePass::OWY5M2I5NzctYzdkOS00MmZhLWExZGYtNjczM2U5ZGUyOWIxTElORV9CUkVBS3ZhdWx0
********************************************

Please enter a Digit::   0: Store a password  1: Check whether password exists  2: Exit
2
The string that will be added to the Java code is the last value of the output, the line beginning with VAULT.

The following servlet uses the vaulted string instead of a clear-text password. The clear-text version is commented out so that you can see the difference.

Example 9.27. Servlet Using a Vaulted Password

package vaulterror.web;
 
import java.io.IOException;
import java.io.Writer;
 
import javax.annotation.Resource;
import javax.annotation.sql.DataSourceDefinition;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
 
 
/*@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "sa",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)*/
@DataSourceDefinition(
        name = "java:jboss/datasources/LoginDS",
        user = "sa",
        password = "VAULT::DS::thePass::OWY5M2I5NzctYzdkOS00MmZhLWExZGYtNjczM2U5ZGUyOWIxTElORV9CUkVBS3ZhdWx0",
        className = "org.h2.jdbcx.JdbcDataSource",
        url = "jdbc:h2:tcp://localhost/mem:test"
)
@WebServlet(name = "MyTestServlet", urlPatterns = { "/my/" }, loadOnStartup = 1)
public class MyTestServlet  extends HttpServlet {
 
    private static final long serialVersionUID = 1L;
 
 
    @Resource(lookup = "java:jboss/datasources/LoginDS")
    private DataSource ds;
 
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        Writer writer = resp.getWriter();
        writer.write((ds != null) + "");
    }
}

Your servlet is now able to resolve the vaulted string.

Chapter 10. Security Administration Reference

10.1. Included Authentication Modules

The following authentication modules are included in the JBoss Enterprise Application Platform. Some of these handle authorization as well as authentication. These usually include the word Role within the Code name.
When you configure these modules, use the Code value to refer to the module.

Table 10.1. Client

Code
Client
Class
org.jboss.security.ClientLoginModule
Description
This login module is designed to establish caller identity and credentials when the JBoss Enterprise Application Platform is acting as a client. It should never be used as part of a security domain used for actual server authentication.

Table 10.2. Client Module Options

Option Type Default Description
multi-threaded
true or false
false
Set to true if each thread has its own principal and credential storage. Set to false to indicate that all threads in the VM share the same identity and credential.
password-stacking
useFirstPass or false
false
Set to useFirstPass to indicate that this login module should look for information stored in the LoginContext to use as the identity. This option can be used when stacking other login modules with this one.
>restore-login-identity
true or false
false
Set to true if the identity and credential seen at the start of the login() method should be restored after the logout() method is invoked.

Table 10.3. Certificate

Code
Certificate
Class
org.jboss.security.auth.spi.BaseCertLoginModule
Description
This login module is designed to authenticate users based on X509 Certificates. A use case for this is CLIENT-CERT authentication of a web application.

Table 10.4. Certificate Module Options

Option Type Default Description
securityDomain
string
none
Name of the security domain that has the JSSE configuration for the truststore holding the trusted certificates.
verifier
Class
none
The class name of the org.jboss.security.auth.certs.X509CertificateVerifier to use for verification of the login certificate.

Table 10.5. CertificateUsers

Code
CertificateUsers
Class
org.jboss.security.auth.spi.UsersRolesLoginModule
Description
Uses a properties resources. The first maps usernames to passwords, and the second maps usernames to roles.

Table 10.6. CertificateUsers Module Options

Option Type Default Description
unauthenticatedIdentity
A string
none
Defines the principal name that should be assigned to requests which contain no authentication information. This can allow unprotected servlets to invoke methods on EJBs that do not require a specific role. Such a principal has no associated roles and can only access either unsecured EJBs or EJB methods that are associated with the unchecked permission constraint.
password-stacking
useFirstPass or false
false
Set to useFirstPass to indicate that this login module should look for information stored in the LoginContext to use as the identity. This option can be used when stacking other login modules with this one.
hashAlgorithm A string
none
The name of the java.security.MessageDigest algorithm to use to hash the password. There is no default so this option must be explicitly set to enable hashing. When hashAlgorithm is specified, the clear text password obtained from the CallbackHandler is hashed before it is passed to UsernamePasswordLoginModule.validatePassword as the inputPassword argument. The expectedPassword stored in the users.properties file must be comparably hashed. Refer to http://docs.oracle.com/javase/6/docs/api/java/security/MessageDigest.html for information on java.security.MessageDigest and the algorithms this class supports.
hashEncoding
base64 or hex
base64
The string format for the hashed password, if hashAlgorithm is also set.
hashCharSet
A string
The default encoding set in the container's environment.
The encoding used to convert the clear-text password to a byte array.
usersProperties
The fully-qualified file path and name of a properties file or resource
users.properties
The file containing the mappings between users and passwords. Each property in the file has the format username=password.
rolesProperties
The fully-qualified file path and name of a properties file or resource
roles.properties
The file containing the mappings between users and roles. Each property in the file has the format username=role1,role2,...,roleN.
ignorePasswordCase
true or false
false
Whether the password comparison should ignore case. This is useful for hashed password encoding where the case of the hashed password is not significant.
principalClass
A fully-qualified classname.
none
A Principal implementation class which contains a constructor that takes a String argument for the princpal name.
roleGroupSeparator
A single character
. (a single period)
The character used to seperate the username from the role group name in the rolesGroup file.
defaultUsersProperties
string
defaultUsers.properties
Name of the resource or file to fall back to if the usersProperties file can't be found.
defaultRolesProperties
string
defaultRoles.properties
Name of the resource or file to fall back to if the rolesProperties file cannot be found.
hashUserPassword
true or false
true
Whether to hash the password entered by the user, when hashAlgorithm is specified. Defaults to true.
hashStorePassword
true or false
true
Whether the store password returned from getUsersPassword() should be hashed, when hashAlgorithm is specified.
digestCallback
A fully-qualified classname.
none
The class name of the org.jboss.crypto.digest.DigestCallback implementation that includes pre or post digest content such as salt values. Only used if hashAlgorithm is specified.
storeDigestCallback
A fully-qualified classname.
none
The class name of the org.jboss.crypto.digest.DigestCallback implementation that includes pre/post digest content like salts for hashing the store password. Only used if hashStorePassword is true and hashAlgorithm is specified.
callback.option.STRING
Various none
All options prefixed with callback.option. are passed to the DigestCallback.init(Map) method. The input username is always passed in via the javax.security.auth.login.name option, and the input/store password is passed in via the javax.security.auth.login.password option to the digestCallback or storeDigestCallback.

Table 10.7. CertificateRoles

Code
CertificateRoles
Class
org.jboss.security.auth.spi.CertRolesLoginModule
Description
This login module extends the Certificate login module to add role mapping capabilities from a properties file. It takes all of the same options as the Certificate login module, and adds the following options.

Table 10.8. CertificateRoles Module Options

Option Type Default Description
rolesProperties
A string
roles.properties
The name of the resource or file containing the roles to assign to each user. The role properties file must be in the format username=role1,role2 where the username is the DN of the certificate, escaping any = (equals) and space characters. The following example is in the correct format:
CN\=unit-tests-client,\ OU\=Red\ Hat\ Inc.,\ O\=Red\ Hat\ Inc.,\ ST\=North\ Carolina,\ C\=US=JBossAdmin
defaultRolesProperties
A string
defaultRoles.properties
Name of the resource or file to fall back to if the rolesProperties file cannot be found.
roleGroupSeparator
A single character
. (a single period)
Which character to use as the role group separator in the roleProperties file.

Table 10.9. Database

Code Database
Class
org.jboss.security.auth.spi.DatabaseServerLoginModule
Description
A JDBC-based login module that supports authentication and role mapping. It is based on two logical tables, with the following definitions.
  • Principals: PrincipalID (text), Password (text)
  • Roles: PrincipalID (text), Role (text), RoleGroup (text)

Table 10.10. Database Module Options

Option Type Default Description
dsJndiName
A JNDI resource
none
The name of the JNDI resource storing the authentication information. This option is required.
principalsQuery
A prepared SQL statement
select Password from Principals where PrincipalID=?
The prepared SQL query to obtain the information about the principal.
rolesQuery
A prepared SQL statement
select Role, RoleGroup from Roles where PrincipalID=?
The prepared SQL query to obtain the information about the roles.

Table 10.11. DatabaseCertificate

Code
DatabaseCertificate
Class
org.jboss.security.auth.spi.DatabaseCertLoginModule
Description
This login module extends the Certificate login module to add role mapping capabilities from a database table. It has the same options plus these additional options:

Table 10.12. DatabaseCertificate Module Options

Option Type Default Description
dsJndiName
A JNDI resource
The name of the JNDI resource storing the authentication information. This option is required.
rolesQuery
A prepared SQL statement
select Role,RoleGroup from Roles where PrincipalID=?
SQL prepared statement to be executed in order to map roles. It should be an equivalent to select Role, RoleGroup from Roles where PrincipalID=?, where Role is the role name and the RoleGroup column value should always be Roles. with capital R.
suspendResume
true or false
true
Whether any existing JTA transaction should be suspended during database operations.

Table 10.13. Identity

Code
Identity
Class
org.jboss.security.auth.spi.IdentityLoginModule
Description
Associates the principal specified in the module options with any subject authenticated against the module. The type of Principal class used is org.jboss.security.SimplePrincipal.. If no principal option is specified a principal with the name of guest is used.

Table 10.14. Identity Module Options

Option Type Default Description
principal
A string
guest
The name to use for the principal.
roles
A comma-separated list of strings
none
A comma-delimited list of roles which will be assigned to the subject.

Table 10.15. Ldap

Code
Ldap
Class
org.jboss.security.auth.spi.LdapLoginModule
Description
Authenticates against an LDAP server, when the username and password are stored in an LDAP server that is accessible using a JNDI LDAP provider. Many of the options are not required, because they are determined by the LDAP provider or the environment.

Table 10.16. Ldap Module Options

Option Type Default Description
java.naming.factory.initial
class name
com.sun.jndi.ldap.LdapCtxFactory
InitialContextFactory implementation class name.
java.naming.provider.url
ldap:// URL
none
URL for the LDAP server.
java.naming.security.authentication
none, simple, or the name of a SASL mechanism
simple
The security level to use to bind to the LDAP server.
java.naming.security.protocol
A transport protocol
If unspecified, determined by the provider.
The transport protocol to use for secure access, such as SSL.
java.naming.security.principal
A string
none
The name of the principal for authenticating the caller to the service. This is built from other properties described below.
java.naming.security.credentials
A credential type
none
The type of credential used by the authentication scheme. Some examples include hashed password, clear-text password, key, or certificate,. If this property is unspecified, the behavior is determined by the service provider.
principalDNPrefix
A string
none
Prefix added to the username to form the user DN. You can prompt the user for a username and build the fully-qualified DN by using the principalDNPrefix and principalDNSuffix.
principalDNSuffix
string
Suffix added to the username to form the user DN. You can prompt the user for a username and build the fully-qualified DN by using the principalDNPrefix and principalDNSuffix.
useObjectCredential
true or false
false
Whether the credential should be obtained as an opaque Object using the org.jboss.security.auth.callback.ObjectCallback type of Callback rather than as a char[] password using a JAAS PasswordCallback. This allows for passing non-char[] credential information to the LDAP server.
rolesCtxDN
A fully-qualified DN
none
The fully-qualified DN for the context to search for user roles.
userRolesCtxDNAttributeName
An attribute
none
The attribute in the user object that contains the DN for the context to search for user roles. This differs from rolesCtxDN in that the context to search for a user's roles may be unique for each user.
rolesAttributeID
An attribute
roles
Name of the attribute containing the user roles.
rolesAttributeIsDN
true or false
false
Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.
rolesNameAttributeID
An attribute
group
Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute.
uidAttributeID
An attribute
uid
Name of the attribute in the UserRolesAttributeDN that corresponds to the user ID. This is used to locate the user roles.
matchOnUserDN
true or false
false
Whether or not the search for user roles should match on the user's fully distinguished DN or the username only. If true, the full user DN is used as the match value. If false, only the username is used as the match value against the uidAttributeName attribute.
allowEmptyPasswords
true or false
true
Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

Table 10.17. LdapExtended

Code
LdapExtended
Class
org.jboss.security.auth.spi.LdapExtLoginModule
Description
An alternate LDAP login module implementation that uses searches to locate the bind user and associated roles. The roles query recursively follows DNs to navigate a hierarchical role structure. It uses the same java.naming options as the Ldap module, and uses the following options instead of the other options of the Ldap module.
The authentication happens in 2 steps:
  1. An initial bind to the LDAP server is done using the bindDN and bindCredential options. The bindDN is a LDAP user with the ability to search both the baseCtxDN and rolesCtxDN trees for the user and roles. The user DN to authenticate against is queried using the filter specified by the baseFilter attribute.
  2. The resulting user DN is authenticated by binding to the LDAP server using the user DN as the InitialLdapContext environment Context.SECURITY_PRINCIPAL. The Context.SECURITY_CREDENTIALS property is set to the String password obtained by the callback handler.

Table 10.18. LdapExtended Module Options

Option Type Default Description
baseCtxDN
A fully-qualified DN
none
The fixed DN of the top-level context to begin the user search.
bindDN
A fully-qualified DN
none
The DN used to bind against the LDAP server for the user and roles queries. This DN needs read and search permissions on the baseCtxDN and rolesCtxDN values.
bindCredential
A string, optionally encrypted
none
The password for the bindDN. This can be encrypted if the jaasSecurityDomain is specified.
jaasSecurityDomain
A JMX ObjectName
none
The JMX ObjectName of the JaasSecurityDomain to use to decrypt the bindCredential. The encrypted form of the password is the format returned by the JaasSecurityDomain.encrypt64(byte[]) method.
baseFilter
LDAP filter string
none
A search filter used to locate the context of the user to authenticate. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. A common example for the search filter is (uid={0}).
rolesCtxDN
fully-qualified DN
none
The fixed DN of the context to search for user roles. This is not the DN where the actual roles are, but the DN where the objects containing the user roles are. For example, in a Microsoft Active Directory server, this is the DN where the user account is.
roleFilter
LDAP filter string
A search filter used to locate the roles associated with the authenticated user. The input username or userDN obtained from the login module callback is substituted into the filter anywhere a {0} expression is used. The authenticated userDN is substituted into the filter anywhere a {1} is used. An example search filter that matches on the input username is (member={0}). An alternative that matches on the authenticated userDN is (member={1}).
roleAttributeIsDN
true or false
false
Whether or not the roleAttributeID contains the fully-qualified DN of a role object. If false, the role name is taken from the value of the roleNameAttributeId attribute of the context name. Certain directory schemas, such as Microsoft Active Directory, require this attribute to be set to true.
defaultRole
Role name
none
A role included for all authenticated users
parseRoleNameFromDN
true or false
false
A flag indicating if the DN returned by a query contains the roleNameAttributeID. If set to true, the DN is checked for the roleNameATtributeID. If set to false, the DN is not checked for the roleNameAttributeID. This flag can improve the performance of LDAP queries.
parseUsername
true or false
false
A flag indicating if the DN is to be parsed for the username. If set to true, the DN is parsed for the username. If set to false the DN is not parsed for the username. This option is used together with usernameBeginString and usernameEndString.
usernameBeginString
a string
none
Defines the string which is to be removed from the start of the DN to reveal the username. This option is used together with usernameEndString.
usernameEndString
a string
none
Defines the string which is to be removed from the end of the DN to reveal the username. This option is used together with usernameBeginString.
roleNameAttributeID
An attribute
group
Name of the attribute within the roleCtxDN context which contains the role name. If the roleAttributeIsDN property is set to true, this property is used to find the role object's name attribute.
distinguishedNameAttribute
An attribute
distinguishedName
The name of the attribute in the user entry that contains the DN of the user. This may be necessary if the DN of the user itself contains special characters (backslash for example) that prevent correct user mapping. If the attribute does not exist, the entry's DN is used.
roleRecursion
An integer
0
The numbers of levels of recursion the role search will go below a matching context. Disable recursion by setting this to 0.
searchTimeLimit
An integer
10000 (10 seconds)
The timeout in milliseconds for user or role searches.
searchScope
One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE
SUBTREE_SCOPE
The search scope to use.
allowEmptyPasswords
true or false
true
Whether to allow empty passwords. Most LDAP servers treat empty passwords as anonymous login attempts. To reject empty passwords, set this to false.

Table 10.19. RoleMapping

Code
RoleMapping
Class
org.jboss.security.auth.spi.RoleMappingLoginModule
Description
Maps a role which is the end result of the authentication process to a declarative role. This module must be flagged as optional when you add it to the security domain.

Table 10.20. RoleMapping Module Options

Option Type Default Description
rolesProperties
The fully-qualified file path and name of a properties file or resource
roles.properties
The fully-qualified file path and name of a properties file or resource which maps roles to replacement roles. The format is original_role=role1,role2,role3
replaceRole
true or false
false
Whether to add to the current roles, or replace the current roles with the mapped ones. Replaces if set to true.

Table 10.21. RunAs

Code
RunAs
Class
Class: org.jboss.security.auth.spi.RunAsLoginModule
Description
A helper module that pushes a run as role onto the stack for the duration of the login phase of authentication, and pops the run as role off the stack in either the commit or abort phase. This login module provides a role for other login modules that must access secured resources in order to perform their authentication, such as a login module which accesses a secured EJB. RunAsLoginModule must be configured before the login modules that require a run as role to be established.

Table 10.22. RunAs Options

Option Type Default Description
roleName
A role name.
nobody
The name of the role to use as the run as role during the login phase.

Table 10.23. Simple

Code
Simple
Class
org.jboss.security.auth.spi.SimpleServerLoginModule
Description
A module for quick setup of security for testing purposes. It implements the following simple algorithm:
  • f the password is null, authenticate the user and assign an identity of guest and a role of guest.
  • Otherwise, if the password is equal to theuser, assign an identity equal to the username and both and and guest roles.
  • Otherwise, authentication fails.

Simple Module Options
The Simple module has no options.

Table 10.24. ConfiguredIdentity

Code
ConfiguredIdentity
Class
org.picketbox.datasource.security.ConfiguredIdentityLoginModule
Description
Associates the principal specified in the module options with any subject authenticated against the module. The type of Principal class used is org.jboss.security.SimplePrincipal.

Table 10.25. ConfiguredIdentity Module Options

Option Type Default Description
principal
Name of a principal.
guest
The principal which will be associated with any subject authenticated against the module.

Table 10.26. SecureIdentity

Code
SecureIdentity
Class
org.picketbox.datasource.security.SecureIdentityLoginModule
Description
This module is provided for legacy purposes. It allows you to encrypt a password and then use the encrypted password with a static principal. If your application uses SecureIdentity, consider using a password vault mechanism instead.

Table 10.27. SecureIdentity Module Options

Option Type Default Description
username
string none The username for authentication.
password
encrypted string none
The password to use for authentication. To encrypt the password, use the module directly at the command line.
java org.picketbox.datasource.security.SecureIdentityLoginModule password_to_encrypt
Paste the result of this command into the module option's value field.
managedConnectionFactoryName
A JCA resource none
The name of the JCA connection factory for your datasource.

Table 10.28. PropertiesUsers

Code
PropertiesUsers
Class
org.jboss.security.auth.spi.PropertiesUsersLoginModule
Description
Uses a properties file to store usernames and passwords for authentication. No authorization (role mapping) is provided. This module is only appropriate for testing.

Table 10.29. PropertiesUsers Module Options

Option Type Default Description
properties
The fully-qualified file path and name of a Java properties file or resource. none
The properties file containing the usernames and clear-text passwords to be used for authentication.

Table 10.30. SimpleUsers

Code
SimpleUsers
Class
org.jboss.security.auth.spi.SimpleUsersLoginModule
Description
This login module stores the username and clear-text password in a Java properties file. It is included for testing only, and is not appropriate for a production environment.

Table 10.31. SimpleUsers Module Options

Option Type Default Description
username
string none The username to use for authentication.
password
string none The clear-text password to use for authentication.

Table 10.32. LdapUsers

Code
LdapUsers
Class
org.jboss.security.auth.spi.LdapUsersLoginModule
Description
The LdapUsers module is superseded by the ExtendedLDAP and AdvancedLdap modules.

Table 10.33. Kerberos

Code
Kerberos
Class
com.sun.security.auth.module.Krb5LoginModule
Description
Performs Kerberos login authentication, using GSSAPI. This module is part of the security framework from the API provided by Sun Microsystems. Details can be found at http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html. This module needs to be paired with another module which handles the authentication and roles mapping.

Table 10.34. Kerberos Module Options

Option Type Default Description
storekey
true or false
false
Whether or not to add the KerberosKey to the subject's private credentials.
doNotPrompt
true or false
false
If set to true, the user is not prompted for the password.
useTicketCache
Boolean value of true or false
.
false
If true, the GTG is obtained from the ticket cache. If false, the ticket cache is not used.
ticketcache
A file or resource representing a Kerberos ticket cache.
The default depends on which operating system you use.
  • Red Hat Enterprise Linux / Solaris: /tmp/krb5cc_uid, using the numeric UID value of the operating system.
  • Microsoft Windows Server: uses the Local Security Authority (LSA) API to find the ticketcache.
The location of the ticket cache.
useKeyTab
true or false
false Whether to obtain the principal's key from a key table file.
keytab
A file or resource representing a Kerberos keytab.
the location in the operating system's Kerberos configuration file, or /home/user/krb5.keytab
The location of the key table file.
principal
A string none
The name of the principal. This can either be a simple user name or a service name such as host/testserver.acme.com. Use this instead of obtaining the principal from the key table, or when the key table contains more than one principal.
useFirstPass
true or false
false
Whether to retrieve the username and password from the module's shared state, using javax.security.auth.login.name and javax.security.auth.login.password as the keys. If authentication fails, no retry attempt is made.
tryFirstPass
true or false
false
Same as useFirstPass, but if authentication fails, the module uses the CallbackHandler to retrieve a new username and password. If the second authentication fails, the failure is reported to the calling application.
storePass
true or false
false
Whether to store the username and password in the module's shared state. This does not happen if the keys already exist in the shared state, or if authentication fails.
clearPass
true or false
false
Set this to true to clear a the username and password from the shared state after both phases of authentication complete.

Table 10.35. SPNEGOUsers

Code
SPNEGOUsers
Class
org.jboss.security.negotiation.spnego.SPNEGOLoginModule
Description
Allows SPNEGO authentication to a Microsoft Active Directory server or other environment which supports SPNEGO. SPNEGO can also carry Kerberos credentials. This module needs to be paired with another module which handles authentication and role mapping.

Table 10.36. SPNEGO Module Options

Option Type Default Description
storeKey
true or false
false
Whether or not to store the key.
useKeyTab
true or false
false
Whether to use a key table.
principal
String reperesenting a principal for Kerberos auhentication.
none
The name of the principal for authentication.
keyTab
A file or resource representing a keytab.
none
The location of a key table.
doNotPrompt
true or false
false
Whether to prompt for a password.